Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _osd: | |
4 | ||
5 | ****************************** | |
6 | Video Output Overlay Interface | |
7 | ****************************** | |
8 | ||
9 | ||
10 | **Also known as On-Screen Display (OSD)** | |
11 | Some video output devices can overlay a framebuffer image onto the | |
12 | outgoing video signal. Applications can set up such an overlay using | |
13 | this interface, which borrows structures and ioctls of the | |
14 | :ref:`Video Overlay <overlay>` interface. | |
15 | ||
16 | The OSD function is accessible through the same character special file | |
17 | as the :ref:`Video Output <capture>` function. Note the default | |
18 | function of such a ``/dev/video`` device is video capturing or output. | |
19 | The OSD function is only available after calling the | |
af4a4d0d | 20 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
5377d91f MH |
21 | |
22 | ||
23 | Querying Capabilities | |
24 | ===================== | |
25 | ||
26 | Devices supporting the *Video Output Overlay* interface set the | |
27 | ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of | |
28 | struct :ref:`v4l2_capability <v4l2-capability>` returned by the | |
7347081e | 29 | :ref:`VIDIOC_QUERYCAP` ioctl. |
5377d91f MH |
30 | |
31 | ||
32 | Framebuffer | |
33 | =========== | |
34 | ||
35 | Contrary to the *Video Overlay* interface the framebuffer is normally | |
36 | implemented on the TV card and not the graphics card. On Linux it is | |
37 | accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device, | |
38 | applications can find the corresponding framebuffer device by calling | |
4e03cb76 | 39 | the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst |
5377d91f MH |
40 | other information, the physical address of the framebuffer in the |
41 | ``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. | |
42 | The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same | |
43 | address in the ``smem_start`` field of struct | |
44 | :c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` | |
45 | ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in | |
46 | the ``linux/fb.h`` header file. | |
47 | ||
48 | The width and height of the framebuffer depends on the current video | |
49 | standard. A V4L2 driver may reject attempts to change the video standard | |
50 | (or any other ioctl which would imply a framebuffer size change) with an | |
51 | EBUSY error code until all applications closed the framebuffer device. | |
52 | ||
53 | ||
54 | .. code-block:: c | |
55 | ||
56 | #include <linux/fb.h> | |
57 | ||
58 | struct v4l2_framebuffer fbuf; | |
59 | unsigned int i; | |
60 | int fb_fd; | |
61 | ||
62 | if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) { | |
63 | perror("VIDIOC_G_FBUF"); | |
64 | exit(EXIT_FAILURE); | |
65 | } | |
66 | ||
67 | for (i = 0; i < 30; i++) { | |
68 | char dev_name[16]; | |
69 | struct fb_fix_screeninfo si; | |
70 | ||
71 | snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i); | |
72 | ||
73 | fb_fd = open(dev_name, O_RDWR); | |
74 | if (-1 == fb_fd) { | |
75 | switch (errno) { | |
76 | case ENOENT: /* no such file */ | |
77 | case ENXIO: /* no driver */ | |
78 | continue; | |
79 | ||
80 | default: | |
81 | perror("open"); | |
82 | exit(EXIT_FAILURE); | |
83 | } | |
84 | } | |
85 | ||
86 | if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) { | |
87 | if (si.smem_start == (unsigned long)fbuf.base) | |
88 | break; | |
89 | } else { | |
90 | /* Apparently not a framebuffer device. */ | |
91 | } | |
92 | ||
93 | close(fb_fd); | |
94 | fb_fd = -1; | |
95 | } | |
96 | ||
97 | /* fb_fd is the file descriptor of the framebuffer device | |
98 | for the video output overlay, or -1 if no device was found. */ | |
99 | ||
100 | ||
101 | Overlay Window and Scaling | |
102 | ========================== | |
103 | ||
104 | The overlay is controlled by source and target rectangles. The source | |
105 | rectangle selects a subsection of the framebuffer image to be overlaid, | |
106 | the target rectangle an area in the outgoing video signal where the | |
107 | image will appear. Drivers may or may not support scaling, and arbitrary | |
108 | sizes and positions of these rectangles. Further drivers may support any | |
109 | (or none) of the clipping/blending methods defined for the | |
110 | :ref:`Video Overlay <overlay>` interface. | |
111 | ||
112 | A struct :ref:`v4l2_window <v4l2-window>` defines the size of the | |
113 | source rectangle, its position in the framebuffer and the | |
114 | clipping/blending method to be used for the overlay. To get the current | |
115 | parameters applications set the ``type`` field of a struct | |
116 | :ref:`v4l2_format <v4l2-format>` to | |
117 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the | |
4e03cb76 | 118 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the |
5377d91f MH |
119 | :c:type:`struct v4l2_window` substructure named ``win``. It is not |
120 | possible to retrieve a previously programmed clipping list or bitmap. | |
121 | ||
122 | To program the source rectangle applications set the ``type`` field of a | |
123 | struct :ref:`v4l2_format <v4l2-format>` to | |
124 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win`` | |
af4a4d0d | 125 | substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
5377d91f | 126 | The driver adjusts the parameters against hardware limits and returns |
4e03cb76 | 127 | the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, |
af4a4d0d | 128 | the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn |
5377d91f | 129 | about driver capabilities without actually changing driver state. Unlike |
2212ff25 | 130 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled. |
5377d91f MH |
131 | |
132 | A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position | |
133 | of the target rectangle. The scaling factor of the overlay is implied by | |
134 | the width and height given in struct :ref:`v4l2_window <v4l2-window>` | |
135 | and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to | |
136 | *Video Output* and *Video Output Overlay* devices in the same way as to | |
137 | *Video Capture* and *Video Overlay* devices, merely reversing the | |
138 | direction of the data flow. For more information see :ref:`crop`. | |
139 | ||
140 | ||
141 | Enabling Overlay | |
142 | ================ | |
143 | ||
144 | There is no V4L2 ioctl to enable or disable the overlay, however the | |
145 | framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl. | |
146 | ||
147 | ||
148 | .. ------------------------------------------------------------------------------ | |
149 | .. This file was automatically converted from DocBook-XML with the dbxml | |
150 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
151 | .. from the linux kernel, refer to: | |
152 | .. | |
153 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
154 | .. ------------------------------------------------------------------------------ |