Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _overlay: | |
4 | ||
5 | *********************** | |
6 | Video Overlay Interface | |
7 | *********************** | |
8 | ||
471e5602 | 9 | **Also known as Framebuffer Overlay or Previewing.** |
5377d91f | 10 | |
5377d91f MH |
11 | Video overlay devices have the ability to genlock (TV-)video into the |
12 | (VGA-)video signal of a graphics card, or to store captured images | |
13 | directly in video memory of a graphics card, typically with clipping. | |
14 | This can be considerable more efficient than capturing images and | |
15 | displaying them by other means. In the old days when only nuclear power | |
16 | plants needed cooling towers this used to be the only way to put live | |
17 | video into a window. | |
18 | ||
19 | Video overlay devices are accessed through the same character special | |
706f8a99 MCC |
20 | files as :ref:`video capture <capture>` devices. |
21 | ||
22 | .. note:: The default function of a ``/dev/video`` device is video | |
23 | capturing. The overlay function is only available after calling | |
24 | the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. | |
5377d91f MH |
25 | |
26 | The driver may support simultaneous overlay and capturing using the | |
27 | read/write and streaming I/O methods. If so, operation at the nominal | |
28 | frame rate of the video standard is not guaranteed. Frames may be | |
29 | directed away from overlay to capture, or one field may be used for | |
30 | overlay and the other for capture if the capture parameters permit this. | |
31 | ||
32 | Applications should use different file descriptors for capturing and | |
33 | overlay. This must be supported by all drivers capable of simultaneous | |
34 | capturing and overlay. Optionally these drivers may also permit | |
35 | capturing and overlay with a single file descriptor for compatibility | |
4855307b | 36 | with V4L and earlier versions of V4L2. [#f1]_ |
5377d91f MH |
37 | |
38 | ||
39 | Querying Capabilities | |
40 | ===================== | |
41 | ||
42 | Devices supporting the video overlay interface set the | |
43 | ``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct | |
44 | :ref:`v4l2_capability <v4l2-capability>` returned by the | |
7347081e | 45 | :ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O |
5377d91f MH |
46 | method specified below must be supported. Tuners and audio inputs are |
47 | optional. | |
48 | ||
49 | ||
50 | Supplemental Functions | |
51 | ====================== | |
52 | ||
53 | Video overlay devices shall support :ref:`audio input <audio>`, | |
7347081e | 54 | :ref:`tuner`, :ref:`controls <control>`, |
5377d91f MH |
55 | :ref:`cropping and scaling <crop>` and |
56 | :ref:`streaming parameter <streaming-par>` ioctls as needed. The | |
57 | :ref:`video input <video>` and :ref:`video standard <standard>` | |
58 | ioctls must be supported by all video overlay devices. | |
59 | ||
60 | ||
61 | Setup | |
62 | ===== | |
63 | ||
64 | Before overlay can commence applications must program the driver with | |
65 | frame buffer parameters, namely the address and size of the frame buffer | |
66 | and the image format, for example RGB 5:6:5. The | |
4e03cb76 | 67 | :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and |
af4a4d0d | 68 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and |
2212ff25 | 69 | set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is |
5377d91f MH |
70 | privileged because it allows to set up DMA into physical memory, |
71 | bypassing the memory protection mechanisms of the kernel. Only the | |
72 | superuser can change the frame buffer address and size. Users are not | |
73 | supposed to run TV applications as root or with SUID bit set. A small | |
74 | helper application with suitable privileges should query the graphics | |
75 | system and program the V4L2 driver at the appropriate time. | |
76 | ||
77 | Some devices add the video overlay to the output signal of the graphics | |
78 | card. In this case the frame buffer is not modified by the video device, | |
79 | and the frame buffer address and pixel format are not needed by the | |
2212ff25 | 80 | driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application |
4e03cb76 | 81 | can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` |
5377d91f MH |
82 | ioctl. |
83 | ||
84 | A driver may support any (or none) of five clipping/blending methods: | |
85 | ||
86 | 1. Chroma-keying displays the overlaid image only where pixels in the | |
87 | primary graphics surface assume a certain color. | |
88 | ||
89 | 2. A bitmap can be specified where each bit corresponds to a pixel in | |
90 | the overlaid image. When the bit is set, the corresponding video | |
91 | pixel is displayed, otherwise a pixel of the graphics surface. | |
92 | ||
93 | 3. A list of clipping rectangles can be specified. In these regions *no* | |
94 | video is displayed, so the graphics surface can be seen here. | |
95 | ||
96 | 4. The framebuffer has an alpha channel that can be used to clip or | |
97 | blend the framebuffer with the video. | |
98 | ||
99 | 5. A global alpha value can be specified to blend the framebuffer | |
100 | contents with video images. | |
101 | ||
102 | When simultaneous capturing and overlay is supported and the hardware | |
103 | prohibits different image and frame buffer formats, the format requested | |
104 | first takes precedence. The attempt to capture | |
af4a4d0d | 105 | (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay |
cdb4af0f | 106 | (:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error |
5377d91f MH |
107 | code or return accordingly modified parameters.. |
108 | ||
109 | ||
110 | Overlay Window | |
111 | ============== | |
112 | ||
113 | The overlaid image is determined by cropping and overlay window | |
114 | parameters. The former select an area of the video picture to capture, | |
115 | the latter how images are overlaid and clipped. Cropping initialization | |
116 | at minimum requires to reset the parameters to defaults. An example is | |
117 | given in :ref:`crop`. | |
118 | ||
119 | The overlay window is described by a struct | |
120 | :ref:`v4l2_window <v4l2-window>`. It defines the size of the image, | |
121 | its position over the graphics surface and the clipping to be applied. | |
122 | To get the current parameters applications set the ``type`` field of a | |
123 | struct :ref:`v4l2_format <v4l2-format>` to | |
124 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the | |
4e03cb76 | 125 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the |
acf309a2 | 126 | :ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not |
5377d91f MH |
127 | possible to retrieve a previously programmed clipping list or bitmap. |
128 | ||
129 | To program the overlay window applications set the ``type`` field of a | |
130 | struct :ref:`v4l2_format <v4l2-format>` to | |
131 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and | |
af4a4d0d | 132 | call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver |
5377d91f | 133 | adjusts the parameters against hardware limits and returns the actual |
4e03cb76 | 134 | parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the |
af4a4d0d | 135 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn |
5377d91f | 136 | about driver capabilities without actually changing driver state. Unlike |
2212ff25 | 137 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled. |
5377d91f MH |
138 | |
139 | The scaling factor of the overlaid image is implied by the width and | |
140 | height given in struct :ref:`v4l2_window <v4l2-window>` and the size | |
141 | of the cropping rectangle. For more information see :ref:`crop`. | |
142 | ||
143 | When simultaneous capturing and overlay is supported and the hardware | |
144 | prohibits different image and window sizes, the size requested first | |
145 | takes precedence. The attempt to capture or overlay as well | |
cdb4af0f | 146 | (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error |
5377d91f MH |
147 | code or return accordingly modified parameters. |
148 | ||
149 | ||
150 | .. _v4l2-window: | |
151 | ||
152 | struct v4l2_window | |
153 | ------------------ | |
154 | ||
155 | ``struct v4l2_rect w`` | |
156 | Size and position of the window relative to the top, left corner of | |
157 | the frame buffer defined with | |
af4a4d0d | 158 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the |
5377d91f MH |
159 | frame buffer width and height, the ``x`` and ``y`` coordinates can |
160 | be negative, and it can lie completely outside the frame buffer. The | |
161 | driver clips the window accordingly, or if that is not possible, | |
162 | modifies its size and/or position. | |
163 | ||
164 | ``enum v4l2_field field`` | |
165 | Applications set this field to determine which video field shall be | |
166 | overlaid, typically one of ``V4L2_FIELD_ANY`` (0), | |
167 | ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or | |
168 | ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different | |
169 | field order and return the actual setting here. | |
170 | ||
171 | ``__u32 chromakey`` | |
172 | When chroma-keying has been negotiated with | |
af4a4d0d | 173 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field |
5377d91f MH |
174 | to the desired pixel value for the chroma key. The format is the |
175 | same as the pixel format of the framebuffer (struct | |
176 | :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat`` | |
177 | field), with bytes in host order. E. g. for | |
178 | :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should | |
179 | be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. | |
180 | ||
181 | ``struct v4l2_clip * clips`` | |
182 | When chroma-keying has *not* been negotiated and | |
4e03cb76 | 183 | :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, |
5377d91f MH |
184 | applications can set this field to point to an array of clipping |
185 | rectangles. | |
186 | ||
471e5602 MCC |
187 | Like the window coordinates w, clipping rectangles are defined |
188 | relative to the top, left corner of the frame buffer. However | |
189 | clipping rectangles must not extend the frame buffer width and | |
190 | height, and they must not overlap. If possible applications | |
191 | should merge adjacent rectangles. Whether this must create | |
192 | x-y or y-x bands, or the order of rectangles, is not defined. When | |
193 | clip lists are not supported the driver ignores this field. Its | |
194 | contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` | |
195 | are undefined. | |
5377d91f MH |
196 | |
197 | ``__u32 clipcount`` | |
198 | When the application set the ``clips`` field, this field must | |
199 | contain the number of clipping rectangles in the list. When clip | |
200 | lists are not supported the driver ignores this field, its contents | |
2212ff25 | 201 | after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are |
5377d91f MH |
202 | supported but no clipping is desired this field must be set to zero. |
203 | ||
204 | ``void * bitmap`` | |
205 | When chroma-keying has *not* been negotiated and | |
4e03cb76 | 206 | :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, |
5377d91f MH |
207 | applications can set this field to point to a clipping bit mask. |
208 | ||
209 | It must be of the same size as the window, ``w.width`` and ``w.height``. | |
210 | Each bit corresponds to a pixel in the overlaid image, which is | |
211 | displayed only when the bit is *set*. Pixel coordinates translate to | |
212 | bits like: | |
213 | ||
214 | ||
215 | .. code-block:: c | |
216 | ||
217 | ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7)) | |
218 | ||
4855307b | 219 | where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_ |
5377d91f MH |
220 | |
221 | When a clipping bit mask is not supported the driver ignores this field, | |
af4a4d0d | 222 | its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are |
5377d91f MH |
223 | undefined. When a bit mask is supported but no clipping is desired this |
224 | field must be set to ``NULL``. | |
225 | ||
226 | Applications need not create a clip list or bit mask. When they pass | |
227 | both, or despite negotiating chroma-keying, the results are undefined. | |
228 | Regardless of the chosen method, the clipping abilities of the hardware | |
229 | may be limited in quantity or quality. The results when these limits are | |
4855307b | 230 | exceeded are undefined. [#f3]_ |
5377d91f MH |
231 | |
232 | ``__u8 global_alpha`` | |
233 | The global alpha value used to blend the framebuffer with video | |
234 | images, if global alpha blending has been negotiated | |
235 | (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see | |
af4a4d0d | 236 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`, |
5377d91f MH |
237 | :ref:`framebuffer-flags`). |
238 | ||
706f8a99 MCC |
239 | .. note:: This field was added in Linux 2.6.23, extending the |
240 | structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>` | |
241 | ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>` | |
242 | parent structure with padding bytes at the end, are not affected. | |
5377d91f MH |
243 | |
244 | ||
245 | .. _v4l2-clip: | |
246 | ||
4855307b | 247 | struct v4l2_clip [#f4]_ |
6710ea47 | 248 | ----------------------- |
5377d91f | 249 | |
5377d91f MH |
250 | ``struct v4l2_rect c`` |
251 | Coordinates of the clipping rectangle, relative to the top, left | |
252 | corner of the frame buffer. Only window pixels *outside* all | |
253 | clipping rectangles are displayed. | |
254 | ||
255 | ``struct v4l2_clip * next`` | |
471e5602 | 256 | Pointer to the next clipping rectangle, ``NULL`` when this is the last |
5377d91f MH |
257 | rectangle. Drivers ignore this field, it cannot be used to pass a |
258 | linked list of clipping rectangles. | |
259 | ||
260 | ||
261 | .. _v4l2-rect: | |
262 | ||
263 | struct v4l2_rect | |
264 | ---------------- | |
265 | ||
266 | ``__s32 left`` | |
267 | Horizontal offset of the top, left corner of the rectangle, in | |
268 | pixels. | |
269 | ||
270 | ``__s32 top`` | |
271 | Vertical offset of the top, left corner of the rectangle, in pixels. | |
272 | Offsets increase to the right and down. | |
273 | ||
274 | ``__u32 width`` | |
275 | Width of the rectangle, in pixels. | |
276 | ||
277 | ``__u32 height`` | |
278 | Height of the rectangle, in pixels. | |
279 | ||
280 | ||
281 | Enabling Overlay | |
282 | ================ | |
283 | ||
284 | To start or stop the frame buffer overlay applications call the | |
7347081e | 285 | :ref:`VIDIOC_OVERLAY` ioctl. |
5377d91f | 286 | |
4855307b | 287 | .. [#f1] |
5377d91f MH |
288 | A common application of two file descriptors is the XFree86 |
289 | :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. | |
290 | While the X server controls video overlay, the application can take | |
291 | advantage of memory mapping and DMA. | |
292 | ||
293 | In the opinion of the designers of this API, no driver writer taking | |
294 | the efforts to support simultaneous capturing and overlay will | |
295 | restrict this ability by requiring a single file descriptor, as in | |
296 | V4L and earlier versions of V4L2. Making this optional means | |
297 | applications depending on two file descriptors need backup routines | |
298 | to be compatible with all drivers, which is considerable more work | |
299 | than using two fds in applications which do not. Also two fd's fit | |
300 | the general concept of one file descriptor for each logical stream. | |
301 | Hence as a complexity trade-off drivers *must* support two file | |
302 | descriptors and *may* support single fd operation. | |
303 | ||
4855307b | 304 | .. [#f2] |
5377d91f MH |
305 | Should we require ``w.width`` to be a multiple of eight? |
306 | ||
4855307b | 307 | .. [#f3] |
5377d91f MH |
308 | When the image is written into frame buffer memory it will be |
309 | undesirable if the driver clips out less pixels than expected, | |
310 | because the application and graphics system are not aware these | |
311 | regions need to be refreshed. The driver should clip out more pixels | |
312 | or not write the image at all. | |
471e5602 | 313 | |
4855307b | 314 | .. [#f4] |
471e5602 MCC |
315 | The X Window system defines "regions" which are vectors of ``struct |
316 | BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and | |
317 | ``height = y2 - y1``, so one cannot pass X11 clip lists directly. |