1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2
3 .. _overlay:
4
5 ***********************
6 Video Overlay Interface
7 ***********************
8
9 **Also known as Framebuffer Overlay or Preview
10
11 Video overlay devices have the ability to genl
12 (VGA-)video signal of a graphics card, or to s
13 directly in video memory of a graphics card, t
14 This can be considerable more efficient than c
15 displaying them by other means. In the old day
16 plants needed cooling towers this used to be t
17 video into a window.
18
19 Video overlay devices are accessed through the
20 files as :ref:`video capture <capture>` device
21
22 .. note::
23
24 The default function of a ``/dev/video`` de
25 capturing. The overlay function is only ava
26 the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioct
27
28 The driver may support simultaneous overlay an
29 read/write and streaming I/O methods. If so, o
30 frame rate of the video standard is not guaran
31 directed away from overlay to capture, or one
32 overlay and the other for capture if the captu
33
34 Applications should use different file descrip
35 overlay. This must be supported by all drivers
36 capturing and overlay. Optionally these driver
37 capturing and overlay with a single file descr
38 with V4L and earlier versions of V4L2. [#f1]_
39
40 A common application of two file descriptors i
41 :ref:`Xv/V4L <xvideo>` interface driver and a
42 While the X server controls video overlay, the
43 advantage of memory mapping and DMA.
44
45 Querying Capabilities
46 =====================
47
48 Devices supporting the video overlay interface
49 ``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capab
50 :c:type:`v4l2_capability` returned by the
51 :ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
52 method specified below must be supported. Tune
53 optional.
54
55
56 Supplemental Functions
57 ======================
58
59 Video overlay devices shall support :ref:`audi
60 :ref:`tuner`, :ref:`controls <control>`,
61 :ref:`cropping and scaling <crop>` and
62 :ref:`streaming parameter <streaming-par>` ioc
63 :ref:`video input <video>` and :ref:`video sta
64 ioctls must be supported by all video overlay
65
66
67 Setup
68 =====
69
70 *Note: support for this has been removed.*
71 Before overlay can commence applications must
72 frame buffer parameters, namely the address an
73 and the image format, for example RGB 5:6:5. T
74 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
75 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls ar
76 set these parameters, respectively. The :ref:`
77 privileged because it allows to set up DMA int
78 bypassing the memory protection mechanisms of
79 superuser can change the frame buffer address
80 supposed to run TV applications as root or wit
81 helper application with suitable privileges sh
82 system and program the V4L2 driver at the appr
83
84 Some devices add the video overlay to the outp
85 card. In this case the frame buffer is not mod
86 and the frame buffer address and pixel format
87 driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF
88 can check for this type of device by calling t
89 ioctl.
90
91 A driver may support any (or none) of five cli
92
93 1. Chroma-keying displays the overlaid image o
94 primary graphics surface assume a certain c
95
96 2. *Note: support for this has been removed.*
97 A bitmap can be specified where each bit co
98 the overlaid image. When the bit is set, th
99 pixel is displayed, otherwise a pixel of th
100
101 3. *Note: support for this has been removed.*
102 A list of clipping rectangles can be specif
103 video is displayed, so the graphics surface
104
105 4. The framebuffer has an alpha channel that c
106 blend the framebuffer with the video.
107
108 5. A global alpha value can be specified to bl
109 contents with video images.
110
111 When simultaneous capturing and overlay is sup
112 prohibits different image and frame buffer for
113 first takes precedence. The attempt to capture
114 (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overla
115 (:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fai
116 code or return accordingly modified parameters
117
118
119 Overlay Window
120 ==============
121
122 The overlaid image is determined by cropping a
123 parameters. The former select an area of the v
124 the latter how images are overlaid and clipped
125 at minimum requires to reset the parameters to
126 given in :ref:`crop`.
127
128 The overlay window is described by a struct
129 :c:type:`v4l2_window`. It defines the size of
130 its position over the graphics surface and the
131 To get the current parameters applications set
132 struct :c:type:`v4l2_format` to
133 ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
134 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The
135 struct :c:type:`v4l2_window` substructure name
136 possible to retrieve a previously programmed c
137
138 To program the overlay window applications set
139 struct :c:type:`v4l2_format` to
140 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize th
141 call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` io
142 adjusts the parameters against hardware limits
143 parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT
144 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can
145 about driver capabilities without actually cha
146 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also w
147
148 The scaling factor of the overlaid image is im
149 height given in struct :c:type:`v4l2_window` a
150 of the cropping rectangle. For more informatio
151
152 When simultaneous capturing and overlay is sup
153 prohibits different image and window sizes, th
154 takes precedence. The attempt to capture or ov
155 (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail
156 code or return accordingly modified parameters
157
158
159 .. c:type:: v4l2_window
160
161 struct v4l2_window
162 ------------------
163
164 ``struct v4l2_rect w``
165 Size and position of the window relative t
166 the frame buffer defined with
167 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The
168 frame buffer width and height, the ``x`` a
169 be negative, and it can lie completely out
170 driver clips the window accordingly, or if
171 modifies its size and/or position.
172
173 ``enum v4l2_field field``
174 Applications set this field to determine w
175 overlaid, typically one of ``V4L2_FIELD_AN
176 ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``
177 ``V4L2_FIELD_INTERLACED``. Drivers may hav
178 field order and return the actual setting
179
180 ``__u32 chromakey``
181 When chroma-keying has been negotiated wit
182 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` appli
183 to the desired pixel value for the chroma
184 same as the pixel format of the framebuffe
185 :c:type:`v4l2_framebuffer` ``fmt.pixelform
186 field), with bytes in host order. E. g. fo
187 :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR
188 be 0xRRGGBB on a little endian, 0xBBGGRR o
189
190 ``struct v4l2_clip * clips``
191 *Note: support for this has been removed.*
192 When chroma-keying has *not* been negotiat
193 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indic
194 applications can set this field to point t
195 rectangles.
196
197 Like the window coordinates w, clipping re
198 relative to the top, left corner of the fr
199 clipping rectangles must not extend the fr
200 height, and they must not overlap. If poss
201 should merge adjacent rectangles. Whether
202 x-y or y-x bands, or the order of rectangl
203 clip lists are not supported the driver ig
204 contents after calling :ref:`VIDIOC_S_FMT
205 are undefined.
206
207 ``__u32 clipcount``
208 *Note: support for this has been removed.*
209 When the application set the ``clips`` fie
210 contain the number of clipping rectangles
211 lists are not supported the driver ignores
212 after calling :ref:`VIDIOC_S_FMT <VIDIOC_G
213 supported but no clipping is desired this
214
215 ``void * bitmap``
216 *Note: support for this has been removed.*
217 When chroma-keying has *not* been negotiat
218 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indic
219 applications can set this field to point t
220
221 It must be of the same size as the window, ``w
222 Each bit corresponds to a pixel in the overlai
223 displayed only when the bit is *set*. Pixel co
224 bits like:
225
226
227 .. code-block:: c
228
229 ((__u8 *) bitmap)[w.width * y + x / 8] & (
230
231 where ``0`` ≤ x < ``w.width`` and ``0`` ≤
232
233 When a clipping bit mask is not supported the
234 its contents after calling :ref:`VIDIOC_S_FMT
235 undefined. When a bit mask is supported but no
236 field must be set to ``NULL``.
237
238 Applications need not create a clip list or bi
239 both, or despite negotiating chroma-keying, th
240 Regardless of the chosen method, the clipping
241 may be limited in quantity or quality. The res
242 exceeded are undefined. [#f3]_
243
244 ``__u8 global_alpha``
245 The global alpha value used to blend the f
246 images, if global alpha blending has been
247 (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
248 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
249 :ref:`framebuffer-flags`).
250
251 .. note::
252
253 This field was added in Linux 2.6.23, exten
254 structure. However the :ref:`VIDIOC_[G|S|TR
255 ioctls, which take a pointer to a :c:type:`
256 parent structure with padding bytes at the
257
258
259 .. c:type:: v4l2_clip
260
261 struct v4l2_clip [#f4]_
262 -----------------------
263
264 ``struct v4l2_rect c``
265 Coordinates of the clipping rectangle, rel
266 corner of the frame buffer. Only window pi
267 clipping rectangles are displayed.
268
269 ``struct v4l2_clip * next``
270 Pointer to the next clipping rectangle, ``
271 rectangle. Drivers ignore this field, it c
272 linked list of clipping rectangles.
273
274
275 .. c:type:: v4l2_rect
276
277 struct v4l2_rect
278 ----------------
279
280 ``__s32 left``
281 Horizontal offset of the top, left corner
282 pixels.
283
284 ``__s32 top``
285 Vertical offset of the top, left corner of
286 Offsets increase to the right and down.
287
288 ``__u32 width``
289 Width of the rectangle, in pixels.
290
291 ``__u32 height``
292 Height of the rectangle, in pixels.
293
294
295 Enabling Overlay
296 ================
297
298 To start or stop the frame buffer overlay appl
299 :ref:`VIDIOC_OVERLAY` ioctl.
300
301 .. [#f1]
302 In the opinion of the designers of this API
303 the efforts to support simultaneous capturi
304 restrict this ability by requiring a single
305 V4L and earlier versions of V4L2. Making th
306 applications depending on two file descript
307 to be compatible with all drivers, which is
308 than using two fds in applications which do
309 the general concept of one file descriptor
310 Hence as a complexity trade-off drivers *mu
311 descriptors and *may* support single fd ope
312
313 .. [#f2]
314 Should we require ``w.width`` to be a multi
315
316 .. [#f3]
317 When the image is written into frame buffer
318 undesirable if the driver clips out less pi
319 because the application and graphics system
320 regions need to be refreshed. The driver sh
321 or not write the image at all.
322
323 .. [#f4]
324 The X Window system defines "regions" which
325 BoxRec { short x1, y1, x2, y2; }`` with ``w
326 ``height = y2 - y1``, so one cannot pass X1
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.