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