1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 The Virtual Video Test Driver (vivid) 3 The Virtual Video Test Driver (vivid)
4 ===================================== 4 =====================================
5 5
6 This driver emulates video4linux hardware of v 6 This driver emulates video4linux hardware of various types: video capture, video
7 output, vbi capture and output, metadata captu 7 output, vbi capture and output, metadata capture and output, radio receivers and
8 transmitters, touch capture and a software def 8 transmitters, touch capture and a software defined radio receiver. In addition a
9 simple framebuffer device is available for tes 9 simple framebuffer device is available for testing capture and output overlays.
10 10
11 Up to 64 vivid instances can be created, each 11 Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs.
12 12
13 Each input can be a webcam, TV capture device, 13 Each input can be a webcam, TV capture device, S-Video capture device or an HDMI
14 capture device. Each output can be an S-Video 14 capture device. Each output can be an S-Video output device or an HDMI output
15 device. 15 device.
16 16
17 These inputs and outputs act exactly as a real 17 These inputs and outputs act exactly as a real hardware device would behave. This
18 allows you to use this driver as a test input 18 allows you to use this driver as a test input for application development, since
19 you can test the various features without requ 19 you can test the various features without requiring special hardware.
20 20
21 This document describes the features implement 21 This document describes the features implemented by this driver:
22 22
23 - Support for read()/write(), MMAP, USERPTR an 23 - Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O.
24 - A large list of test patterns and variations 24 - A large list of test patterns and variations thereof
25 - Working brightness, contrast, saturation and 25 - Working brightness, contrast, saturation and hue controls
26 - Support for the alpha color component 26 - Support for the alpha color component
27 - Full colorspace support, including limited/f 27 - Full colorspace support, including limited/full RGB range
28 - All possible control types are present 28 - All possible control types are present
29 - Support for various pixel aspect ratios and 29 - Support for various pixel aspect ratios and video aspect ratios
30 - Error injection to test what happens if erro 30 - Error injection to test what happens if errors occur
31 - Supports crop/compose/scale in any combinati 31 - Supports crop/compose/scale in any combination for both input and output
32 - Can emulate up to 4K resolutions 32 - Can emulate up to 4K resolutions
33 - All Field settings are supported for testing 33 - All Field settings are supported for testing interlaced capturing
34 - Supports all standard YUV and RGB formats, i 34 - Supports all standard YUV and RGB formats, including two multiplanar YUV formats
35 - Raw and Sliced VBI capture and output suppor 35 - Raw and Sliced VBI capture and output support
36 - Radio receiver and transmitter support, incl 36 - Radio receiver and transmitter support, including RDS support
37 - Software defined radio (SDR) support 37 - Software defined radio (SDR) support
38 - Capture and output overlay support 38 - Capture and output overlay support
39 - Metadata capture and output support 39 - Metadata capture and output support
40 - Touch capture support 40 - Touch capture support
41 41
42 These features will be described in more detai 42 These features will be described in more detail below.
43 43
44 Configuring the driver 44 Configuring the driver
45 ---------------------- 45 ----------------------
46 46
47 By default the driver will create a single ins 47 By default the driver will create a single instance that has a video capture
48 device with webcam, TV, S-Video and HDMI input 48 device with webcam, TV, S-Video and HDMI inputs, a video output device with
49 S-Video and HDMI outputs, one vbi capture devi 49 S-Video and HDMI outputs, one vbi capture device, one vbi output device, one
50 radio receiver device, one radio transmitter d 50 radio receiver device, one radio transmitter device and one SDR device.
51 51
52 The number of instances, devices, video inputs 52 The number of instances, devices, video inputs and outputs and their types are
53 all configurable using the following module op 53 all configurable using the following module options:
54 54
55 - n_devs: 55 - n_devs:
56 56
57 number of driver instances to create. 57 number of driver instances to create. By default set to 1. Up to 64
58 instances can be created. 58 instances can be created.
59 59
60 - node_types: 60 - node_types:
61 61
62 which devices should each driver insta 62 which devices should each driver instance create. An array of
63 hexadecimal values, one for each insta !! 63 hexadecimal values, one for each instance. The default is 0x1d3d.
64 Each value is a bitmask with the follo 64 Each value is a bitmask with the following meaning:
65 65
66 - bit 0: Video Capture node 66 - bit 0: Video Capture node
67 - bit 2-3: VBI Capture node: 0 67 - bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
68 - bit 4: Radio Receiver node 68 - bit 4: Radio Receiver node
69 - bit 5: Software Defined Radi 69 - bit 5: Software Defined Radio Receiver node
70 - bit 8: Video Output node 70 - bit 8: Video Output node
71 - bit 10-11: VBI Output node: 71 - bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
72 - bit 12: Radio Transmitter no 72 - bit 12: Radio Transmitter node
73 - bit 16: Framebuffer for test 73 - bit 16: Framebuffer for testing overlays
74 - bit 17: Metadata Capture nod 74 - bit 17: Metadata Capture node
75 - bit 18: Metadata Output node 75 - bit 18: Metadata Output node
76 - bit 19: Touch Capture node 76 - bit 19: Touch Capture node
77 77
78 So to create four instances, the first 78 So to create four instances, the first two with just one video capture
79 device, the second two with just one v 79 device, the second two with just one video output device you would pass
80 these module options to vivid: 80 these module options to vivid:
81 81
82 .. code-block:: none 82 .. code-block:: none
83 83
84 n_devs=4 node_types=0x1,0x1,0x 84 n_devs=4 node_types=0x1,0x1,0x100,0x100
85 85
86 - num_inputs: 86 - num_inputs:
87 87
88 the number of inputs, one for each ins 88 the number of inputs, one for each instance. By default 4 inputs
89 are created for each video capture dev 89 are created for each video capture device. At most 16 inputs can be created,
90 and there must be at least one. 90 and there must be at least one.
91 91
92 - input_types: 92 - input_types:
93 93
94 the input types for each instance, the 94 the input types for each instance, the default is 0xe4. This defines
95 what the type of each input is when th 95 what the type of each input is when the inputs are created for each driver
96 instance. This is a hexadecimal value 96 instance. This is a hexadecimal value with up to 16 pairs of bits, each
97 pair gives the type and bits 0-1 map t 97 pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1,
98 30-31 map to input 15. Each pair of bi 98 30-31 map to input 15. Each pair of bits has the following meaning:
99 99
100 - 00: this is a webcam input 100 - 00: this is a webcam input
101 - 01: this is a TV tuner input 101 - 01: this is a TV tuner input
102 - 10: this is an S-Video input 102 - 10: this is an S-Video input
103 - 11: this is an HDMI input 103 - 11: this is an HDMI input
104 104
105 So to create a video capture device wi 105 So to create a video capture device with 8 inputs where input 0 is a TV
106 tuner, inputs 1-3 are S-Video inputs a 106 tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you
107 would use the following module options 107 would use the following module options:
108 108
109 .. code-block:: none 109 .. code-block:: none
110 110
111 num_inputs=8 input_types=0xffa 111 num_inputs=8 input_types=0xffa9
112 112
113 - num_outputs: 113 - num_outputs:
114 114
115 the number of outputs, one for each in 115 the number of outputs, one for each instance. By default 2 outputs
116 are created for each video output devi 116 are created for each video output device. At most 16 outputs can be
117 created, and there must be at least on 117 created, and there must be at least one.
118 118
119 - output_types: 119 - output_types:
120 120
121 the output types for each instance, th 121 the output types for each instance, the default is 0x02. This defines
122 what the type of each output is when t 122 what the type of each output is when the outputs are created for each
123 driver instance. This is a hexadecimal 123 driver instance. This is a hexadecimal value with up to 16 bits, each bit
124 gives the type and bit 0 maps to outpu 124 gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit
125 15 maps to output 15. The meaning of e 125 15 maps to output 15. The meaning of each bit is as follows:
126 126
127 - 0: this is an S-Video output 127 - 0: this is an S-Video output
128 - 1: this is an HDMI output 128 - 1: this is an HDMI output
129 129
130 So to create a video output device wit 130 So to create a video output device with 8 outputs where outputs 0-3 are
131 S-Video outputs and outputs 4-7 are HD 131 S-Video outputs and outputs 4-7 are HDMI outputs you would use the
132 following module options: 132 following module options:
133 133
134 .. code-block:: none 134 .. code-block:: none
135 135
136 num_outputs=8 output_types=0xf 136 num_outputs=8 output_types=0xf0
137 137
138 - vid_cap_nr: 138 - vid_cap_nr:
139 139
140 give the desired videoX start number f 140 give the desired videoX start number for each video capture device.
141 The default is -1 which will just take 141 The default is -1 which will just take the first free number. This allows
142 you to map capture video nodes to spec 142 you to map capture video nodes to specific videoX device nodes. Example:
143 143
144 .. code-block:: none 144 .. code-block:: none
145 145
146 n_devs=4 vid_cap_nr=2,4,6,8 146 n_devs=4 vid_cap_nr=2,4,6,8
147 147
148 This will attempt to assign /dev/video 148 This will attempt to assign /dev/video2 for the video capture device of
149 the first vivid instance, video4 for t 149 the first vivid instance, video4 for the next up to video8 for the last
150 instance. If it can't succeed, then it 150 instance. If it can't succeed, then it will just take the next free
151 number. 151 number.
152 152
153 - vid_out_nr: 153 - vid_out_nr:
154 154
155 give the desired videoX start number f 155 give the desired videoX start number for each video output device.
156 The default is -1 which will just take 156 The default is -1 which will just take the first free number.
157 157
158 - vbi_cap_nr: 158 - vbi_cap_nr:
159 159
160 give the desired vbiX start number for 160 give the desired vbiX start number for each vbi capture device.
161 The default is -1 which will just take 161 The default is -1 which will just take the first free number.
162 162
163 - vbi_out_nr: 163 - vbi_out_nr:
164 164
165 give the desired vbiX start number for 165 give the desired vbiX start number for each vbi output device.
166 The default is -1 which will just take 166 The default is -1 which will just take the first free number.
167 167
168 - radio_rx_nr: 168 - radio_rx_nr:
169 169
170 give the desired radioX start number f 170 give the desired radioX start number for each radio receiver device.
171 The default is -1 which will just take 171 The default is -1 which will just take the first free number.
172 172
173 - radio_tx_nr: 173 - radio_tx_nr:
174 174
175 give the desired radioX start number f 175 give the desired radioX start number for each radio transmitter
176 device. The default is -1 which will j 176 device. The default is -1 which will just take the first free number.
177 177
178 - sdr_cap_nr: 178 - sdr_cap_nr:
179 179
180 give the desired swradioX start number 180 give the desired swradioX start number for each SDR capture device.
181 The default is -1 which will just take 181 The default is -1 which will just take the first free number.
182 182
183 - meta_cap_nr: 183 - meta_cap_nr:
184 184
185 give the desired videoX start number f 185 give the desired videoX start number for each metadata capture device.
186 The default is -1 which will just take 186 The default is -1 which will just take the first free number.
187 187
188 - meta_out_nr: 188 - meta_out_nr:
189 189
190 give the desired videoX start number f 190 give the desired videoX start number for each metadata output device.
191 The default is -1 which will just take 191 The default is -1 which will just take the first free number.
192 192
193 - touch_cap_nr: 193 - touch_cap_nr:
194 194
195 give the desired v4l-touchX start numb 195 give the desired v4l-touchX start number for each touch capture device.
196 The default is -1 which will just take 196 The default is -1 which will just take the first free number.
197 197
198 - ccs_cap_mode: 198 - ccs_cap_mode:
199 199
200 specify the allowed video capture crop 200 specify the allowed video capture crop/compose/scaling combination
201 for each driver instance. Video captur 201 for each driver instance. Video capture devices can have any combination
202 of cropping, composing and scaling cap 202 of cropping, composing and scaling capabilities and this will tell the
203 vivid driver which of those is should 203 vivid driver which of those is should emulate. By default the user can
204 select this through controls. 204 select this through controls.
205 205
206 The value is either -1 (controlled by 206 The value is either -1 (controlled by the user) or a set of three bits,
207 each enabling (1) or disabling (0) one 207 each enabling (1) or disabling (0) one of the features:
208 208
209 - bit 0: 209 - bit 0:
210 210
211 Enable crop support. Cropping 211 Enable crop support. Cropping will take only part of the
212 incoming picture. 212 incoming picture.
213 - bit 1: 213 - bit 1:
214 214
215 Enable compose support. Compos 215 Enable compose support. Composing will copy the incoming
216 picture into a larger buffer. 216 picture into a larger buffer.
217 217
218 - bit 2: 218 - bit 2:
219 219
220 Enable scaling support. Scalin 220 Enable scaling support. Scaling can scale the incoming
221 picture. The scaler of the viv 221 picture. The scaler of the vivid driver can enlarge up
222 or down to four times the orig 222 or down to four times the original size. The scaler is
223 very simple and low-quality. S 223 very simple and low-quality. Simplicity and speed were
224 key, not quality. 224 key, not quality.
225 225
226 Note that this value is ignored by web 226 Note that this value is ignored by webcam inputs: those enumerate
227 discrete framesizes and that is incomp 227 discrete framesizes and that is incompatible with cropping, composing
228 or scaling. 228 or scaling.
229 229
230 - ccs_out_mode: 230 - ccs_out_mode:
231 231
232 specify the allowed video output crop/ 232 specify the allowed video output crop/compose/scaling combination
233 for each driver instance. Video output 233 for each driver instance. Video output devices can have any combination
234 of cropping, composing and scaling cap 234 of cropping, composing and scaling capabilities and this will tell the
235 vivid driver which of those is should 235 vivid driver which of those is should emulate. By default the user can
236 select this through controls. 236 select this through controls.
237 237
238 The value is either -1 (controlled by 238 The value is either -1 (controlled by the user) or a set of three bits,
239 each enabling (1) or disabling (0) one 239 each enabling (1) or disabling (0) one of the features:
240 240
241 - bit 0: 241 - bit 0:
242 242
243 Enable crop support. Cropping 243 Enable crop support. Cropping will take only part of the
244 outgoing buffer. 244 outgoing buffer.
245 245
246 - bit 1: 246 - bit 1:
247 247
248 Enable compose support. Compos 248 Enable compose support. Composing will copy the incoming
249 buffer into a larger picture f 249 buffer into a larger picture frame.
250 250
251 - bit 2: 251 - bit 2:
252 252
253 Enable scaling support. Scalin 253 Enable scaling support. Scaling can scale the incoming
254 buffer. The scaler of the vivi 254 buffer. The scaler of the vivid driver can enlarge up
255 or down to four times the orig 255 or down to four times the original size. The scaler is
256 very simple and low-quality. S 256 very simple and low-quality. Simplicity and speed were
257 key, not quality. 257 key, not quality.
258 258
259 - multiplanar: 259 - multiplanar:
260 260
261 select whether each device instance su 261 select whether each device instance supports multi-planar formats,
262 and thus the V4L2 multi-planar API. By 262 and thus the V4L2 multi-planar API. By default device instances are
263 single-planar. 263 single-planar.
264 264
265 This module option can override that f 265 This module option can override that for each instance. Values are:
266 266
267 - 1: this is a single-planar i 267 - 1: this is a single-planar instance.
268 - 2: this is a multi-planar in 268 - 2: this is a multi-planar instance.
269 269
270 - vivid_debug: 270 - vivid_debug:
271 271
272 enable driver debugging info 272 enable driver debugging info
273 273
274 - no_error_inj: 274 - no_error_inj:
275 275
276 if set disable the error injecting con 276 if set disable the error injecting controls. This option is
277 needed in order to run a tool like v4l 277 needed in order to run a tool like v4l2-compliance. Tools like that
278 exercise all controls including a cont 278 exercise all controls including a control like 'Disconnect' which
279 emulates a USB disconnect, making the 279 emulates a USB disconnect, making the device inaccessible and so
280 all tests that v4l2-compliance is doin 280 all tests that v4l2-compliance is doing will fail afterwards.
281 281
282 There may be other situations as well 282 There may be other situations as well where you want to disable the
283 error injection support of vivid. When 283 error injection support of vivid. When this option is set, then the
284 controls that select crop, compose and 284 controls that select crop, compose and scale behavior are also
285 removed. Unless overridden by ccs_cap_ 285 removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the
286 will default to enabling crop, compose 286 will default to enabling crop, compose and scaling.
287 287
288 - allocators: 288 - allocators:
289 289
290 memory allocator selection, default is 290 memory allocator selection, default is 0. It specifies the way buffers
291 will be allocated. 291 will be allocated.
292 292
293 - 0: vmalloc 293 - 0: vmalloc
294 - 1: dma-contig 294 - 1: dma-contig
295 295
296 - cache_hints: 296 - cache_hints:
297 297
298 specifies if the device should set que 298 specifies if the device should set queues' user-space cache and memory
299 consistency hint capability (V4L2_BUF_ 299 consistency hint capability (V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS).
300 The hints are valid only when using MM 300 The hints are valid only when using MMAP streaming I/O. Default is 0.
301 301
302 - 0: forbid hints 302 - 0: forbid hints
303 - 1: allow hints 303 - 1: allow hints
304 304
305 - supports_requests: <<
306 <<
307 specifies if the device should support <<
308 three possible values, default is 1: <<
309 <<
310 - 0: no request <<
311 - 1: supports requests <<
312 - 2: requires requests <<
313 <<
314 Taken together, all these module options allow 305 Taken together, all these module options allow you to precisely customize
315 the driver behavior and test your application 306 the driver behavior and test your application with all sorts of permutations.
316 It is also very suitable to emulate hardware t 307 It is also very suitable to emulate hardware that is not yet available, e.g.
317 when developing software for a new upcoming de 308 when developing software for a new upcoming device.
318 309
319 310
320 Video Capture 311 Video Capture
321 ------------- 312 -------------
322 313
323 This is probably the most frequently used feat 314 This is probably the most frequently used feature. The video capture device
324 can be configured by using the module options 315 can be configured by using the module options num_inputs, input_types and
325 ccs_cap_mode (see "Configuring the driver" for !! 316 ccs_cap_mode (see section 1 for more detailed information), but by default
326 but by default four inputs are configured: a w !! 317 four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI
327 and an HDMI input, one input for each input ty !! 318 input, one input for each input type. Those are described in more detail
328 detail below. !! 319 below.
329 320
330 Special attention has been given to the rate a 321 Special attention has been given to the rate at which new frames become
331 available. The jitter will be around 1 jiffy ( !! 322 available. The jitter will be around 1 jiffie (that depends on the HZ
332 configuration of your kernel, so usually 1/100 323 configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second),
333 but the long-term behavior is exactly followin 324 but the long-term behavior is exactly following the framerate. So a
334 framerate of 59.94 Hz is really different from 325 framerate of 59.94 Hz is really different from 60 Hz. If the framerate
335 exceeds your kernel's HZ value, then you will 326 exceeds your kernel's HZ value, then you will get dropped frames, but the
336 frame/field sequence counting will keep track 327 frame/field sequence counting will keep track of that so the sequence
337 count will skip whenever frames are dropped. 328 count will skip whenever frames are dropped.
338 329
339 330
340 Webcam Input 331 Webcam Input
341 ~~~~~~~~~~~~ 332 ~~~~~~~~~~~~
342 333
343 The webcam input supports three framesizes: 32 334 The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It
344 supports frames per second settings of 10, 15, 335 supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones
345 are available depends on the chosen framesize: 336 are available depends on the chosen framesize: the larger the framesize, the
346 lower the maximum frames per second. 337 lower the maximum frames per second.
347 338
348 The initially selected colorspace when you swi 339 The initially selected colorspace when you switch to the webcam input will be
349 sRGB. 340 sRGB.
350 341
351 342
352 TV and S-Video Inputs 343 TV and S-Video Inputs
353 ~~~~~~~~~~~~~~~~~~~~~ 344 ~~~~~~~~~~~~~~~~~~~~~
354 345
355 The only difference between the TV and S-Video 346 The only difference between the TV and S-Video input is that the TV has a
356 tuner. Otherwise they behave identically. 347 tuner. Otherwise they behave identically.
357 348
358 These inputs support audio inputs as well: one 349 These inputs support audio inputs as well: one TV and one Line-In. They
359 both support all TV standards. If the standard 350 both support all TV standards. If the standard is queried, then the Vivid
360 controls 'Standard Signal Mode' and 'Standard' 351 controls 'Standard Signal Mode' and 'Standard' determine what
361 the result will be. 352 the result will be.
362 353
363 These inputs support all combinations of the f 354 These inputs support all combinations of the field setting. Special care has
364 been taken to faithfully reproduce how fields 355 been taken to faithfully reproduce how fields are handled for the different
365 TV standards. This is particularly noticeable 356 TV standards. This is particularly noticeable when generating a horizontally
366 moving image so the temporal effect of using i 357 moving image so the temporal effect of using interlaced formats becomes clearly
367 visible. For 50 Hz standards the top field is 358 visible. For 50 Hz standards the top field is the oldest and the bottom field
368 is the newest in time. For 60 Hz standards tha 359 is the newest in time. For 60 Hz standards that is reversed: the bottom field
369 is the oldest and the top field is the newest 360 is the oldest and the top field is the newest in time.
370 361
371 When you start capturing in V4L2_FIELD_ALTERNA 362 When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
372 contain the top field for 50 Hz standards and 363 contain the top field for 50 Hz standards and the bottom field for 60 Hz
373 standards. This is what capture hardware does 364 standards. This is what capture hardware does as well.
374 365
375 Finally, for PAL/SECAM standards the first hal 366 Finally, for PAL/SECAM standards the first half of the top line contains noise.
376 This simulates the Wide Screen Signal that is 367 This simulates the Wide Screen Signal that is commonly placed there.
377 368
378 The initially selected colorspace when you swi 369 The initially selected colorspace when you switch to the TV or S-Video input
379 will be SMPTE-170M. 370 will be SMPTE-170M.
380 371
381 The pixel aspect ratio will depend on the TV s 372 The pixel aspect ratio will depend on the TV standard. The video aspect ratio
382 can be selected through the 'Standard Aspect R 373 can be selected through the 'Standard Aspect Ratio' Vivid control.
383 Choices are '4x3', '16x9' which will give lett 374 Choices are '4x3', '16x9' which will give letterboxed widescreen video and
384 '16x9 Anamorphic' which will give full screen 375 '16x9 Anamorphic' which will give full screen squashed anamorphic widescreen
385 video that will need to be scaled accordingly. 376 video that will need to be scaled accordingly.
386 377
387 The TV 'tuner' supports a frequency range of 4 378 The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available
388 every 6 MHz, starting from 49.25 MHz. For each 379 every 6 MHz, starting from 49.25 MHz. For each channel the generated image
389 will be in color for the +/- 0.25 MHz around i 380 will be in color for the +/- 0.25 MHz around it, and in grayscale for
390 +/- 1 MHz around the channel. Beyond that it i 381 +/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER
391 ioctl will return 100% signal strength for +/- 382 ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz.
392 It will also return correct afc values to show 383 It will also return correct afc values to show whether the frequency is too
393 low or too high. 384 low or too high.
394 385
395 The audio subchannels that are returned are MO 386 The audio subchannels that are returned are MONO for the +/- 1 MHz range around
396 a valid channel frequency. When the frequency 387 a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
397 channel it will return either MONO, STEREO, ei 388 channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or
398 LANG1 | LANG2 (for others), or STEREO | SAP. 389 LANG1 | LANG2 (for others), or STEREO | SAP.
399 390
400 Which one is returned depends on the chosen ch 391 Which one is returned depends on the chosen channel, each next valid channel
401 will cycle through the possible audio subchann 392 will cycle through the possible audio subchannel combinations. This allows
402 you to test the various combinations by just s 393 you to test the various combinations by just switching channels..
403 394
404 Finally, for these inputs the v4l2_timecode st 395 Finally, for these inputs the v4l2_timecode struct is filled in the
405 dequeued v4l2_buffer struct. 396 dequeued v4l2_buffer struct.
406 397
407 398
408 HDMI Input 399 HDMI Input
409 ~~~~~~~~~~ 400 ~~~~~~~~~~
410 401
411 The HDMI inputs supports all CEA-861 and DMT t 402 The HDMI inputs supports all CEA-861 and DMT timings, both progressive and
412 interlaced, for pixelclock frequencies between 403 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
413 mode for interlaced formats is always V4L2_FIE 404 mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the
414 field order is always top field first, and whe 405 field order is always top field first, and when you start capturing an
415 interlaced format you will receive the top fie 406 interlaced format you will receive the top field first.
416 407
417 The initially selected colorspace when you swi 408 The initially selected colorspace when you switch to the HDMI input or
418 select an HDMI timing is based on the format r 409 select an HDMI timing is based on the format resolution: for resolutions
419 less than or equal to 720x576 the colorspace i 410 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
420 others it is set to REC-709 (CEA-861 timings) 411 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
421 412
422 The pixel aspect ratio will depend on the HDMI 413 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
423 set as for the NTSC TV standard, for 720x576 i 414 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
424 standard, and for all others a 1:1 pixel aspec 415 standard, and for all others a 1:1 pixel aspect ratio is returned.
425 416
426 The video aspect ratio can be selected through 417 The video aspect ratio can be selected through the 'DV Timings Aspect Ratio'
427 Vivid control. Choices are 'Source Width x Hei 418 Vivid control. Choices are 'Source Width x Height' (just use the
428 same ratio as the chosen format), '4x3' or '16 419 same ratio as the chosen format), '4x3' or '16x9', either of which can
429 result in pillarboxed or letterboxed video. 420 result in pillarboxed or letterboxed video.
430 421
431 For HDMI inputs it is possible to set the EDID 422 For HDMI inputs it is possible to set the EDID. By default a simple EDID
432 is provided. You can only set the EDID for HDM 423 is provided. You can only set the EDID for HDMI inputs. Internally, however,
433 the EDID is shared between all HDMI inputs. 424 the EDID is shared between all HDMI inputs.
434 425
435 No interpretation is done of the EDID data wit 426 No interpretation is done of the EDID data with the exception of the
436 physical address. See the CEC section for more 427 physical address. See the CEC section for more details.
437 428
438 There is a maximum of 15 HDMI inputs (if there 429 There is a maximum of 15 HDMI inputs (if there are more, then they will be
439 reduced to 15) since that's the limitation of 430 reduced to 15) since that's the limitation of the EDID physical address.
440 431
441 432
442 Video Output 433 Video Output
443 ------------ 434 ------------
444 435
445 The video output device can be configured by u 436 The video output device can be configured by using the module options
446 num_outputs, output_types and ccs_out_mode (se !! 437 num_outputs, output_types and ccs_out_mode (see section 1 for more detailed
447 for more detailed information), but by default !! 438 information), but by default two outputs are configured: an S-Video and an
448 an S-Video and an HDMI input, one output for e !! 439 HDMI input, one output for each output type. Those are described in more detail
449 described in more detail below. !! 440 below.
450 441
451 Like with video capture the framerate is also 442 Like with video capture the framerate is also exact in the long term.
452 443
453 444
454 S-Video Output 445 S-Video Output
455 ~~~~~~~~~~~~~~ 446 ~~~~~~~~~~~~~~
456 447
457 This output supports audio outputs as well: "L 448 This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2".
458 The S-Video output supports all TV standards. 449 The S-Video output supports all TV standards.
459 450
460 This output supports all combinations of the f 451 This output supports all combinations of the field setting.
461 452
462 The initially selected colorspace when you swi 453 The initially selected colorspace when you switch to the TV or S-Video input
463 will be SMPTE-170M. 454 will be SMPTE-170M.
464 455
465 456
466 HDMI Output 457 HDMI Output
467 ~~~~~~~~~~~ 458 ~~~~~~~~~~~
468 459
469 The HDMI output supports all CEA-861 and DMT t 460 The HDMI output supports all CEA-861 and DMT timings, both progressive and
470 interlaced, for pixelclock frequencies between 461 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
471 mode for interlaced formats is always V4L2_FIE 462 mode for interlaced formats is always V4L2_FIELD_ALTERNATE.
472 463
473 The initially selected colorspace when you swi 464 The initially selected colorspace when you switch to the HDMI output or
474 select an HDMI timing is based on the format r 465 select an HDMI timing is based on the format resolution: for resolutions
475 less than or equal to 720x576 the colorspace i 466 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
476 others it is set to REC-709 (CEA-861 timings) 467 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
477 468
478 The pixel aspect ratio will depend on the HDMI 469 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
479 set as for the NTSC TV standard, for 720x576 i 470 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
480 standard, and for all others a 1:1 pixel aspec 471 standard, and for all others a 1:1 pixel aspect ratio is returned.
481 472
482 An HDMI output has a valid EDID which can be o 473 An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID.
483 474
484 There is a maximum of 15 HDMI outputs (if ther 475 There is a maximum of 15 HDMI outputs (if there are more, then they will be
485 reduced to 15) since that's the limitation of 476 reduced to 15) since that's the limitation of the EDID physical address. See
486 also the CEC section for more details. 477 also the CEC section for more details.
487 478
488 VBI Capture 479 VBI Capture
489 ----------- 480 -----------
490 481
491 There are three types of VBI capture devices: 482 There are three types of VBI capture devices: those that only support raw
492 (undecoded) VBI, those that only support slice 483 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
493 support both. This is determined by the node_t 484 support both. This is determined by the node_types module option. In all
494 cases the driver will generate valid VBI data: 485 cases the driver will generate valid VBI data: for 60 Hz standards it will
495 generate Closed Caption and XDS data. The clos 486 generate Closed Caption and XDS data. The closed caption stream will
496 alternate between "Hello world!" and "Closed c 487 alternate between "Hello world!" and "Closed captions test" every second.
497 The XDS stream will give the current time once 488 The XDS stream will give the current time once a minute. For 50 Hz standards
498 it will generate the Wide Screen Signal which 489 it will generate the Wide Screen Signal which is based on the actual Video
499 Aspect Ratio control setting and teletext page 490 Aspect Ratio control setting and teletext pages 100-159, one page per frame.
500 491
501 The VBI device will only work for the S-Video 492 The VBI device will only work for the S-Video and TV inputs, it will give
502 back an error if the current input is a webcam 493 back an error if the current input is a webcam or HDMI.
503 494
504 495
505 VBI Output 496 VBI Output
506 ---------- 497 ----------
507 498
508 There are three types of VBI output devices: t 499 There are three types of VBI output devices: those that only support raw
509 (undecoded) VBI, those that only support slice 500 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
510 support both. This is determined by the node_t 501 support both. This is determined by the node_types module option.
511 502
512 The sliced VBI output supports the Wide Screen 503 The sliced VBI output supports the Wide Screen Signal and the teletext signal
513 for 50 Hz standards and Closed Captioning + XD 504 for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards.
514 505
515 The VBI device will only work for the S-Video 506 The VBI device will only work for the S-Video output, it will give
516 back an error if the current output is HDMI. 507 back an error if the current output is HDMI.
517 508
518 509
519 Radio Receiver 510 Radio Receiver
520 -------------- 511 --------------
521 512
522 The radio receiver emulates an FM/AM/SW receiv 513 The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS.
523 The frequency ranges are: 514 The frequency ranges are:
524 515
525 - FM: 64 MHz - 108 MHz 516 - FM: 64 MHz - 108 MHz
526 - AM: 520 kHz - 1710 kHz 517 - AM: 520 kHz - 1710 kHz
527 - SW: 2300 kHz - 26.1 MHz 518 - SW: 2300 kHz - 26.1 MHz
528 519
529 Valid channels are emulated every 1 MHz for FM 520 Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW.
530 The signal strength decreases the further the 521 The signal strength decreases the further the frequency is from the valid
531 frequency until it becomes 0% at +/- 50 kHz (F 522 frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
532 ideal frequency. The initial frequency when th 523 ideal frequency. The initial frequency when the driver is loaded is set to
533 95 MHz. 524 95 MHz.
534 525
535 The FM receiver supports RDS as well, both usi 526 The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls'
536 modes. In the 'Controls' mode the RDS informat 527 modes. In the 'Controls' mode the RDS information is stored in read-only
537 controls. These controls are updated every tim 528 controls. These controls are updated every time the frequency is changed,
538 or when the tuner status is requested. The Blo 529 or when the tuner status is requested. The Block I/O method uses the read()
539 interface to pass the RDS blocks on to the app 530 interface to pass the RDS blocks on to the application for decoding.
540 531
541 The RDS signal is 'detected' for +/- 12.5 kHz 532 The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
542 and the further the frequency is away from the 533 and the further the frequency is away from the valid frequency the more RDS
543 errors are randomly introduced into the block 534 errors are randomly introduced into the block I/O stream, up to 50% of all
544 blocks if you are +/- 12.5 kHz from the channe 535 blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
545 can occur in equal proportions: blocks marked 536 can occur in equal proportions: blocks marked 'CORRECTED', blocks marked
546 'ERROR', blocks marked 'INVALID' and dropped b 537 'ERROR', blocks marked 'INVALID' and dropped blocks.
547 538
548 The generated RDS stream contains all the stan 539 The generated RDS stream contains all the standard fields contained in a
549 0B group, and also radio text and the current 540 0B group, and also radio text and the current time.
550 541
551 The receiver supports HW frequency seek, eithe 542 The receiver supports HW frequency seek, either in Bounded mode, Wrap Around
552 mode or both, which is configurable with the " 543 mode or both, which is configurable with the "Radio HW Seek Mode" control.
553 544
554 545
555 Radio Transmitter 546 Radio Transmitter
556 ----------------- 547 -----------------
557 548
558 The radio transmitter emulates an FM/AM/SW tra 549 The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS.
559 The frequency ranges are: 550 The frequency ranges are:
560 551
561 - FM: 64 MHz - 108 MHz 552 - FM: 64 MHz - 108 MHz
562 - AM: 520 kHz - 1710 kHz 553 - AM: 520 kHz - 1710 kHz
563 - SW: 2300 kHz - 26.1 MHz 554 - SW: 2300 kHz - 26.1 MHz
564 555
565 The initial frequency when the driver is loade 556 The initial frequency when the driver is loaded is 95.5 MHz.
566 557
567 The FM transmitter supports RDS as well, both 558 The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls'
568 modes. In the 'Controls' mode the transmitted 559 modes. In the 'Controls' mode the transmitted RDS information is configured
569 using controls, and in 'Block I/O' mode the bl 560 using controls, and in 'Block I/O' mode the blocks are passed to the driver
570 using write(). 561 using write().
571 562
572 563
573 Software Defined Radio Receiver 564 Software Defined Radio Receiver
574 ------------------------------- 565 -------------------------------
575 566
576 The SDR receiver has three frequency bands for 567 The SDR receiver has three frequency bands for the ADC tuner:
577 568
578 - 300 kHz 569 - 300 kHz
579 - 900 kHz - 2800 kHz 570 - 900 kHz - 2800 kHz
580 - 3200 kHz 571 - 3200 kHz
581 572
582 The RF tuner supports 50 MHz - 2000 MHz. 573 The RF tuner supports 50 MHz - 2000 MHz.
583 574
584 The generated data contains the In-phase and Q 575 The generated data contains the In-phase and Quadrature components of a
585 1 kHz tone that has an amplitude of sqrt(2). 576 1 kHz tone that has an amplitude of sqrt(2).
586 577
587 578
588 Metadata Capture 579 Metadata Capture
589 ---------------- 580 ----------------
590 581
591 The Metadata capture generates UVC format meta 582 The Metadata capture generates UVC format metadata. The PTS and SCR are
592 transmitted based on the values set in vivid c 583 transmitted based on the values set in vivid controls.
593 584
594 The Metadata device will only work for the Web 585 The Metadata device will only work for the Webcam input, it will give
595 back an error for all other inputs. 586 back an error for all other inputs.
596 587
597 588
598 Metadata Output 589 Metadata Output
599 --------------- 590 ---------------
600 591
601 The Metadata output can be used to set brightn 592 The Metadata output can be used to set brightness, contrast, saturation and hue.
602 593
603 The Metadata device will only work for the Web 594 The Metadata device will only work for the Webcam output, it will give
604 back an error for all other outputs. 595 back an error for all other outputs.
605 596
606 597
607 Touch Capture 598 Touch Capture
608 ------------- 599 -------------
609 600
610 The Touch capture generates touch patterns sim 601 The Touch capture generates touch patterns simulating single tap, double tap,
611 triple tap, move from left to right, zoom in, 602 triple tap, move from left to right, zoom in, zoom out, palm press (simulating
612 a large area being pressed on a touchpad), and 603 a large area being pressed on a touchpad), and simulating 16 simultaneous
613 touch points. 604 touch points.
614 605
615 Controls 606 Controls
616 -------- 607 --------
617 608
618 Different devices support different controls. 609 Different devices support different controls. The sections below will describe
619 each control and which devices support them. 610 each control and which devices support them.
620 611
621 612
622 User Controls - Test Controls 613 User Controls - Test Controls
623 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
624 615
625 The Button, Boolean, Integer 32 Bits, Integer 616 The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and
626 Integer Menu are controls that represent all p 617 Integer Menu are controls that represent all possible control types. The Menu
627 control and the Integer Menu control both have 618 control and the Integer Menu control both have 'holes' in their menu list,
628 meaning that one or more menu items return EIN 619 meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called.
629 Both menu controls also have a non-zero minimu 620 Both menu controls also have a non-zero minimum control value. These features
630 allow you to check if your application can han 621 allow you to check if your application can handle such things correctly.
631 These controls are supported for every device 622 These controls are supported for every device type.
632 623
633 624
634 User Controls - Video Capture 625 User Controls - Video Capture
635 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 626 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
636 627
637 The following controls are specific to video c 628 The following controls are specific to video capture.
638 629
639 The Brightness, Contrast, Saturation and Hue c 630 The Brightness, Contrast, Saturation and Hue controls actually work and are
640 standard. There is one special feature with th 631 standard. There is one special feature with the Brightness control: each
641 video input has its own brightness value, so c 632 video input has its own brightness value, so changing input will restore
642 the brightness for that input. In addition, ea 633 the brightness for that input. In addition, each video input uses a different
643 brightness range (minimum and maximum control 634 brightness range (minimum and maximum control values). Switching inputs will
644 cause a control event to be sent with the V4L2 635 cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set.
645 This allows you to test controls that can chan 636 This allows you to test controls that can change their range.
646 637
647 The 'Gain, Automatic' and Gain controls can be 638 The 'Gain, Automatic' and Gain controls can be used to test volatile controls:
648 if 'Gain, Automatic' is set, then the Gain con 639 if 'Gain, Automatic' is set, then the Gain control is volatile and changes
649 constantly. If 'Gain, Automatic' is cleared, t 640 constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal
650 control. 641 control.
651 642
652 The 'Horizontal Flip' and 'Vertical Flip' cont 643 The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
653 image. These combine with the 'Sensor Flipped 644 image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid
654 controls. 645 controls.
655 646
656 The 'Alpha Component' control can be used to s 647 The 'Alpha Component' control can be used to set the alpha component for
657 formats containing an alpha channel. 648 formats containing an alpha channel.
658 649
659 650
660 User Controls - Audio 651 User Controls - Audio
661 ~~~~~~~~~~~~~~~~~~~~~ 652 ~~~~~~~~~~~~~~~~~~~~~
662 653
663 The following controls are specific to video c 654 The following controls are specific to video capture and output and radio
664 receivers and transmitters. 655 receivers and transmitters.
665 656
666 The 'Volume' and 'Mute' audio controls are typ 657 The 'Volume' and 'Mute' audio controls are typical for such devices to
667 control the volume and mute the audio. They do 658 control the volume and mute the audio. They don't actually do anything in
668 the vivid driver. 659 the vivid driver.
669 660
670 661
671 Vivid Controls 662 Vivid Controls
672 ~~~~~~~~~~~~~~ 663 ~~~~~~~~~~~~~~
673 664
674 These vivid custom controls control the image 665 These vivid custom controls control the image generation, error injection, etc.
675 666
676 667
677 Test Pattern Controls 668 Test Pattern Controls
678 ^^^^^^^^^^^^^^^^^^^^^ 669 ^^^^^^^^^^^^^^^^^^^^^
679 670
680 The Test Pattern Controls are all specific to 671 The Test Pattern Controls are all specific to video capture.
681 672
682 - Test Pattern: 673 - Test Pattern:
683 674
684 selects which test pattern to use. Use 675 selects which test pattern to use. Use the CSC Colorbar for
685 testing colorspace conversions: the co 676 testing colorspace conversions: the colors used in that test pattern
686 map to valid colors in all colorspaces 677 map to valid colors in all colorspaces. The colorspace conversion
687 is disabled for the other test pattern 678 is disabled for the other test patterns.
688 679
689 - OSD Text Mode: 680 - OSD Text Mode:
690 681
691 selects whether the text superimposed 682 selects whether the text superimposed on the
692 test pattern should be shown, and if s 683 test pattern should be shown, and if so, whether only counters should
693 be displayed or the full text. 684 be displayed or the full text.
694 685
695 - Horizontal Movement: 686 - Horizontal Movement:
696 687
697 selects whether the test pattern shoul 688 selects whether the test pattern should
698 move to the left or right and at what 689 move to the left or right and at what speed.
699 690
700 - Vertical Movement: 691 - Vertical Movement:
701 692
702 does the same for the vertical directi 693 does the same for the vertical direction.
703 694
704 - Show Border: 695 - Show Border:
705 696
706 show a two-pixel wide border at the ed 697 show a two-pixel wide border at the edge of the actual image,
707 excluding letter or pillarboxing. 698 excluding letter or pillarboxing.
708 699
709 - Show Square: 700 - Show Square:
710 701
711 show a square in the middle of the ima 702 show a square in the middle of the image. If the image is
712 displayed with the correct pixel and i 703 displayed with the correct pixel and image aspect ratio corrections,
713 then the width and height of the squar 704 then the width and height of the square on the monitor should be
714 the same. 705 the same.
715 706
716 - Insert SAV Code in Image: 707 - Insert SAV Code in Image:
717 708
718 adds a SAV (Start of Active Video) cod 709 adds a SAV (Start of Active Video) code to the image.
719 This can be used to check if such code 710 This can be used to check if such codes in the image are inadvertently
720 interpreted instead of being ignored. 711 interpreted instead of being ignored.
721 712
722 - Insert EAV Code in Image: 713 - Insert EAV Code in Image:
723 714
724 does the same for the EAV (End of Acti 715 does the same for the EAV (End of Active Video) code.
725 716
726 - Insert Video Guard Band 717 - Insert Video Guard Band
727 718
728 adds 4 columns of pixels with the HDMI 719 adds 4 columns of pixels with the HDMI Video Guard Band code at the
729 left hand side of the image. This only 720 left hand side of the image. This only works with 3 or 4 byte RGB pixel
730 formats. The RGB pixel value 0xab/0x55 721 formats. The RGB pixel value 0xab/0x55/0xab turns out to be equivalent
731 to the HDMI Video Guard Band code that 722 to the HDMI Video Guard Band code that precedes each active video line
732 (see section 5.2.2.1 in the HDMI 1.3 S 723 (see section 5.2.2.1 in the HDMI 1.3 Specification). To test if a video
733 receiver has correct HDMI Video Guard 724 receiver has correct HDMI Video Guard Band processing, enable this
734 control and then move the image to the 725 control and then move the image to the left hand side of the screen.
735 That will result in video lines that s 726 That will result in video lines that start with multiple pixels that
736 have the same value as the Video Guard 727 have the same value as the Video Guard Band that precedes them.
737 Receivers that will just keep skipping 728 Receivers that will just keep skipping Video Guard Band values will
738 now fail and either loose sync or thes 729 now fail and either loose sync or these video lines will shift.
739 730
740 731
741 Capture Feature Selection Controls 732 Capture Feature Selection Controls
742 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 733 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
743 734
744 These controls are all specific to video captu 735 These controls are all specific to video capture.
745 736
746 - Sensor Flipped Horizontally: 737 - Sensor Flipped Horizontally:
747 738
748 the image is flipped horizontally and 739 the image is flipped horizontally and the
749 V4L2_IN_ST_HFLIP input status flag is 740 V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where
750 a sensor is for example mounted upside 741 a sensor is for example mounted upside down.
751 742
752 - Sensor Flipped Vertically: 743 - Sensor Flipped Vertically:
753 744
754 the image is flipped vertically and th 745 the image is flipped vertically and the
755 V4L2_IN_ST_VFLIP input status flag is 746 V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where
756 a sensor is for example mounted upside 747 a sensor is for example mounted upside down.
757 748
758 - Standard Aspect Ratio: 749 - Standard Aspect Ratio:
759 750
760 selects if the image aspect ratio as u 751 selects if the image aspect ratio as used for the TV or
761 S-Video input should be 4x3, 16x9 or a 752 S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may
762 introduce letterboxing. 753 introduce letterboxing.
763 754
764 - DV Timings Aspect Ratio: 755 - DV Timings Aspect Ratio:
765 756
766 selects if the image aspect ratio as u 757 selects if the image aspect ratio as used for the HDMI
767 input should be the same as the source 758 input should be the same as the source width and height ratio, or if
768 it should be 4x3 or 16x9. This may int 759 it should be 4x3 or 16x9. This may introduce letter or pillarboxing.
769 760
770 - Timestamp Source: 761 - Timestamp Source:
771 762
772 selects when the timestamp for each bu 763 selects when the timestamp for each buffer is taken.
773 764
774 - Colorspace: 765 - Colorspace:
775 766
776 selects which colorspace should be use 767 selects which colorspace should be used when generating the image.
777 This only applies if the CSC Colorbar 768 This only applies if the CSC Colorbar test pattern is selected,
778 otherwise the test pattern will go thr 769 otherwise the test pattern will go through unconverted.
779 This behavior is also what you want, s 770 This behavior is also what you want, since a 75% Colorbar
780 should really have 75% signal intensit 771 should really have 75% signal intensity and should not be affected
781 by colorspace conversions. 772 by colorspace conversions.
782 773
783 Changing the colorspace will result in 774 Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE
784 to be sent since it emulates a detecte 775 to be sent since it emulates a detected colorspace change.
785 776
786 - Transfer Function: 777 - Transfer Function:
787 778
788 selects which colorspace transfer func 779 selects which colorspace transfer function should be used when
789 generating an image. This only applies 780 generating an image. This only applies if the CSC Colorbar test pattern is
790 selected, otherwise the test pattern w 781 selected, otherwise the test pattern will go through unconverted.
791 This behavior is also what you want, s 782 This behavior is also what you want, since a 75% Colorbar
792 should really have 75% signal intensit 783 should really have 75% signal intensity and should not be affected
793 by colorspace conversions. 784 by colorspace conversions.
794 785
795 Changing the transfer function will re 786 Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE
796 to be sent since it emulates a detecte 787 to be sent since it emulates a detected colorspace change.
797 788
798 - Y'CbCr Encoding: 789 - Y'CbCr Encoding:
799 790
800 selects which Y'CbCr encoding should b 791 selects which Y'CbCr encoding should be used when generating
801 a Y'CbCr image. This only applies if t 792 a Y'CbCr image. This only applies if the format is set to a Y'CbCr format
802 as opposed to an RGB format. 793 as opposed to an RGB format.
803 794
804 Changing the Y'CbCr encoding will resu 795 Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE
805 to be sent since it emulates a detecte 796 to be sent since it emulates a detected colorspace change.
806 797
807 - Quantization: 798 - Quantization:
808 799
809 selects which quantization should be u 800 selects which quantization should be used for the RGB or Y'CbCr
810 encoding when generating the test patt 801 encoding when generating the test pattern.
811 802
812 Changing the quantization will result 803 Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
813 to be sent since it emulates a detecte 804 to be sent since it emulates a detected colorspace change.
814 805
815 - Limited RGB Range (16-235): 806 - Limited RGB Range (16-235):
816 807
817 selects if the RGB range of the HDMI s 808 selects if the RGB range of the HDMI source should
818 be limited or full range. This combine 809 be limited or full range. This combines with the Digital Video 'Rx RGB
819 Quantization Range' control and can be 810 Quantization Range' control and can be used to test what happens if
820 a source provides you with the wrong q 811 a source provides you with the wrong quantization range information.
821 See the description of that control fo 812 See the description of that control for more details.
822 813
823 - Apply Alpha To Red Only: 814 - Apply Alpha To Red Only:
824 815
825 apply the alpha channel as set by the 816 apply the alpha channel as set by the 'Alpha Component'
826 user control to the red color of the t 817 user control to the red color of the test pattern only.
827 818
828 - Enable Capture Cropping: 819 - Enable Capture Cropping:
829 820
830 enables crop support. This control is 821 enables crop support. This control is only present if
831 the ccs_cap_mode module option is set 822 the ccs_cap_mode module option is set to the default value of -1 and if
832 the no_error_inj module option is set 823 the no_error_inj module option is set to 0 (the default).
833 824
834 - Enable Capture Composing: 825 - Enable Capture Composing:
835 826
836 enables composing support. This contro 827 enables composing support. This control is only
837 present if the ccs_cap_mode module opt 828 present if the ccs_cap_mode module option is set to the default value of
838 -1 and if the no_error_inj module opti 829 -1 and if the no_error_inj module option is set to 0 (the default).
839 830
840 - Enable Capture Scaler: 831 - Enable Capture Scaler:
841 832
842 enables support for a scaler (maximum 833 enables support for a scaler (maximum 4 times upscaling
843 and downscaling). This control is only 834 and downscaling). This control is only present if the ccs_cap_mode
844 module option is set to the default va 835 module option is set to the default value of -1 and if the no_error_inj
845 module option is set to 0 (the default 836 module option is set to 0 (the default).
846 837
847 - Maximum EDID Blocks: 838 - Maximum EDID Blocks:
848 839
849 determines how many EDID blocks the dr 840 determines how many EDID blocks the driver supports.
850 Note that the vivid driver does not ac 841 Note that the vivid driver does not actually interpret new EDID
851 data, it just stores it. It allows for 842 data, it just stores it. It allows for up to 256 EDID blocks
852 which is the maximum supported by the 843 which is the maximum supported by the standard.
853 844
854 - Fill Percentage of Frame: 845 - Fill Percentage of Frame:
855 846
856 can be used to draw only the top X per 847 can be used to draw only the top X percent
857 of the image. Since each frame has to 848 of the image. Since each frame has to be drawn by the driver, this
858 demands a lot of the CPU. For large re 849 demands a lot of the CPU. For large resolutions this becomes
859 problematic. By drawing only part of t 850 problematic. By drawing only part of the image this CPU load can
860 be reduced. 851 be reduced.
861 852
862 853
863 Output Feature Selection Controls 854 Output Feature Selection Controls
864 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 855 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
865 856
866 These controls are all specific to video outpu 857 These controls are all specific to video output.
867 858
868 - Enable Output Cropping: 859 - Enable Output Cropping:
869 860
870 enables crop support. This control is 861 enables crop support. This control is only present if
871 the ccs_out_mode module option is set 862 the ccs_out_mode module option is set to the default value of -1 and if
872 the no_error_inj module option is set 863 the no_error_inj module option is set to 0 (the default).
873 864
874 - Enable Output Composing: 865 - Enable Output Composing:
875 866
876 enables composing support. This contro 867 enables composing support. This control is only
877 present if the ccs_out_mode module opt 868 present if the ccs_out_mode module option is set to the default value of
878 -1 and if the no_error_inj module opti 869 -1 and if the no_error_inj module option is set to 0 (the default).
879 870
880 - Enable Output Scaler: 871 - Enable Output Scaler:
881 872
882 enables support for a scaler (maximum 873 enables support for a scaler (maximum 4 times upscaling
883 and downscaling). This control is only 874 and downscaling). This control is only present if the ccs_out_mode
884 module option is set to the default va 875 module option is set to the default value of -1 and if the no_error_inj
885 module option is set to 0 (the default 876 module option is set to 0 (the default).
886 877
887 878
888 Error Injection Controls 879 Error Injection Controls
889 ^^^^^^^^^^^^^^^^^^^^^^^^ 880 ^^^^^^^^^^^^^^^^^^^^^^^^
890 881
891 The following two controls are only valid for 882 The following two controls are only valid for video and vbi capture.
892 883
893 - Standard Signal Mode: 884 - Standard Signal Mode:
894 885
895 selects the behavior of VIDIOC_QUERYST 886 selects the behavior of VIDIOC_QUERYSTD: what should it return?
896 887
897 Changing this control will result in t 888 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
898 to be sent since it emulates a changed 889 to be sent since it emulates a changed input condition (e.g. a cable
899 was plugged in or out). 890 was plugged in or out).
900 891
901 - Standard: 892 - Standard:
902 893
903 selects the standard that VIDIOC_QUERY 894 selects the standard that VIDIOC_QUERYSTD should return if the
904 previous control is set to "Selected S 895 previous control is set to "Selected Standard".
905 896
906 Changing this control will result in t 897 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
907 to be sent since it emulates a changed 898 to be sent since it emulates a changed input standard.
908 899
909 900
910 The following two controls are only valid for 901 The following two controls are only valid for video capture.
911 902
912 - DV Timings Signal Mode: 903 - DV Timings Signal Mode:
913 904
914 selects the behavior of VIDIOC_QUERY_D 905 selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what
915 should it return? 906 should it return?
916 907
917 Changing this control will result in t 908 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
918 to be sent since it emulates a changed 909 to be sent since it emulates a changed input condition (e.g. a cable
919 was plugged in or out). 910 was plugged in or out).
920 911
921 - DV Timings: 912 - DV Timings:
922 913
923 selects the timings the VIDIOC_QUERY_D 914 selects the timings the VIDIOC_QUERY_DV_TIMINGS should return
924 if the previous control is set to "Sel 915 if the previous control is set to "Selected DV Timings".
925 916
926 Changing this control will result in t 917 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
927 to be sent since it emulates changed i 918 to be sent since it emulates changed input timings.
928 919
929 920
930 The following controls are only present if the 921 The following controls are only present if the no_error_inj module option
931 is set to 0 (the default). These controls are 922 is set to 0 (the default). These controls are valid for video and vbi
932 capture and output streams and for the SDR cap 923 capture and output streams and for the SDR capture device except for the
933 Disconnect control which is valid for all devi 924 Disconnect control which is valid for all devices.
934 925
935 - Wrap Sequence Number: 926 - Wrap Sequence Number:
936 927
937 test what happens when you wrap the se 928 test what happens when you wrap the sequence number in
938 struct v4l2_buffer around. 929 struct v4l2_buffer around.
939 930
940 - Wrap Timestamp: 931 - Wrap Timestamp:
941 932
942 test what happens when you wrap the ti 933 test what happens when you wrap the timestamp in struct
943 v4l2_buffer around. 934 v4l2_buffer around.
944 935
945 - Percentage of Dropped Buffers: 936 - Percentage of Dropped Buffers:
946 937
947 sets the percentage of buffers that 938 sets the percentage of buffers that
948 are never returned by the driver (i.e. 939 are never returned by the driver (i.e., they are dropped).
949 940
950 - Disconnect: 941 - Disconnect:
951 942
952 emulates a USB disconnect. The device 943 emulates a USB disconnect. The device will act as if it has
953 been disconnected. Only after all open 944 been disconnected. Only after all open filehandles to the device
954 node have been closed will the device 945 node have been closed will the device become 'connected' again.
955 946
956 - Inject V4L2_BUF_FLAG_ERROR: 947 - Inject V4L2_BUF_FLAG_ERROR:
957 948
958 when pressed, the next frame returned 949 when pressed, the next frame returned by
959 the driver will have the error flag se 950 the driver will have the error flag set (i.e. the frame is marked
960 corrupt). 951 corrupt).
961 952
962 - Inject VIDIOC_REQBUFS Error: 953 - Inject VIDIOC_REQBUFS Error:
963 954
964 when pressed, the next REQBUFS or CREA 955 when pressed, the next REQBUFS or CREATE_BUFS
965 ioctl call will fail with an error. To 956 ioctl call will fail with an error. To be precise: the videobuf2
966 queue_setup() op will return -EINVAL. 957 queue_setup() op will return -EINVAL.
967 958
968 - Inject VIDIOC_QBUF Error: 959 - Inject VIDIOC_QBUF Error:
969 960
970 when pressed, the next VIDIOC_QBUF or 961 when pressed, the next VIDIOC_QBUF or
971 VIDIOC_PREPARE_BUFFER ioctl call will 962 VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be
972 precise: the videobuf2 buf_prepare() o 963 precise: the videobuf2 buf_prepare() op will return -EINVAL.
973 964
974 - Inject VIDIOC_STREAMON Error: 965 - Inject VIDIOC_STREAMON Error:
975 966
976 when pressed, the next VIDIOC_STREAMON 967 when pressed, the next VIDIOC_STREAMON ioctl
977 call will fail with an error. To be pr 968 call will fail with an error. To be precise: the videobuf2
978 start_streaming() op will return -EINV 969 start_streaming() op will return -EINVAL.
979 970
980 - Inject Fatal Streaming Error: 971 - Inject Fatal Streaming Error:
981 972
982 when pressed, the streaming core will 973 when pressed, the streaming core will be
983 marked as having suffered a fatal erro 974 marked as having suffered a fatal error, the only way to recover
984 from that is to stop streaming. To be 975 from that is to stop streaming. To be precise: the videobuf2
985 vb2_queue_error() function is called. 976 vb2_queue_error() function is called.
986 977
987 978
988 VBI Raw Capture Controls 979 VBI Raw Capture Controls
989 ^^^^^^^^^^^^^^^^^^^^^^^^ 980 ^^^^^^^^^^^^^^^^^^^^^^^^
990 981
991 - Interlaced VBI Format: 982 - Interlaced VBI Format:
992 983
993 if set, then the raw VBI data will be 984 if set, then the raw VBI data will be interlaced instead
994 of providing it grouped by field. 985 of providing it grouped by field.
995 986
996 987
997 Digital Video Controls 988 Digital Video Controls
998 ~~~~~~~~~~~~~~~~~~~~~~ 989 ~~~~~~~~~~~~~~~~~~~~~~
999 990
1000 - Rx RGB Quantization Range: 991 - Rx RGB Quantization Range:
1001 992
1002 sets the RGB quantization detection o 993 sets the RGB quantization detection of the HDMI
1003 input. This combines with the Vivid ' 994 input. This combines with the Vivid 'Limited RGB Range (16-235)'
1004 control and can be used to test what 995 control and can be used to test what happens if a source provides
1005 you with the wrong quantization range 996 you with the wrong quantization range information. This can be tested
1006 by selecting an HDMI input, setting t 997 by selecting an HDMI input, setting this control to Full or Limited
1007 range and selecting the opposite in t 998 range and selecting the opposite in the 'Limited RGB Range (16-235)'
1008 control. The effect is easy to see if 999 control. The effect is easy to see if the 'Gray Ramp' test pattern
1009 is selected. 1000 is selected.
1010 1001
1011 - Tx RGB Quantization Range: 1002 - Tx RGB Quantization Range:
1012 1003
1013 sets the RGB quantization detection o 1004 sets the RGB quantization detection of the HDMI
1014 output. It is currently not used for 1005 output. It is currently not used for anything in vivid, but most HDMI
1015 transmitters would typically have thi 1006 transmitters would typically have this control.
1016 1007
1017 - Transmit Mode: 1008 - Transmit Mode:
1018 1009
1019 sets the transmit mode of the HDMI ou 1010 sets the transmit mode of the HDMI output to HDMI or DVI-D. This
1020 affects the reported colorspace since 1011 affects the reported colorspace since DVI_D outputs will always use
1021 sRGB. 1012 sRGB.
1022 1013
>> 1014 - Display Present:
>> 1015
>> 1016 sets the presence of a "display" on the HDMI output. This affects
>> 1017 the tx_edid_present, tx_hotplug and tx_rxsense controls.
>> 1018
1023 1019
1024 FM Radio Receiver Controls 1020 FM Radio Receiver Controls
1025 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 1021 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1026 1022
1027 - RDS Reception: 1023 - RDS Reception:
1028 1024
1029 set if the RDS receiver should be ena 1025 set if the RDS receiver should be enabled.
1030 1026
1031 - RDS Program Type: 1027 - RDS Program Type:
1032 1028
1033 1029
1034 - RDS PS Name: 1030 - RDS PS Name:
1035 1031
1036 1032
1037 - RDS Radio Text: 1033 - RDS Radio Text:
1038 1034
1039 1035
1040 - RDS Traffic Announcement: 1036 - RDS Traffic Announcement:
1041 1037
1042 1038
1043 - RDS Traffic Program: 1039 - RDS Traffic Program:
1044 1040
1045 1041
1046 - RDS Music: 1042 - RDS Music:
1047 1043
1048 these are all read-only controls. If 1044 these are all read-only controls. If RDS Rx I/O Mode is set to
1049 "Block I/O", then they are inactive a 1045 "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set
1050 to "Controls", then these controls re 1046 to "Controls", then these controls report the received RDS data.
1051 1047
1052 .. note:: 1048 .. note::
1053 The vivid implementation of this is p 1049 The vivid implementation of this is pretty basic: they are only
1054 updated when you set a new frequency 1050 updated when you set a new frequency or when you get the tuner status
1055 (VIDIOC_G_TUNER). 1051 (VIDIOC_G_TUNER).
1056 1052
1057 - Radio HW Seek Mode: 1053 - Radio HW Seek Mode:
1058 1054
1059 can be one of "Bounded", "Wrap Around 1055 can be one of "Bounded", "Wrap Around" or "Both". This
1060 determines if VIDIOC_S_HW_FREQ_SEEK w 1056 determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency
1061 range or wrap-around or if it is sele 1057 range or wrap-around or if it is selectable by the user.
1062 1058
1063 - Radio Programmable HW Seek: 1059 - Radio Programmable HW Seek:
1064 1060
1065 if set, then the user can provide the 1061 if set, then the user can provide the lower and
1066 upper bound of the HW Seek. Otherwise 1062 upper bound of the HW Seek. Otherwise the frequency range boundaries
1067 will be used. 1063 will be used.
1068 1064
1069 - Generate RBDS Instead of RDS: 1065 - Generate RBDS Instead of RDS:
1070 1066
1071 if set, then generate RBDS (the US va 1067 if set, then generate RBDS (the US variant of
1072 RDS) data instead of RDS (European-st 1068 RDS) data instead of RDS (European-style RDS). This affects only the
1073 PICODE and PTY codes. 1069 PICODE and PTY codes.
1074 1070
1075 - RDS Rx I/O Mode: 1071 - RDS Rx I/O Mode:
1076 1072
1077 this can be "Block I/O" where the RDS 1073 this can be "Block I/O" where the RDS blocks have to be read()
1078 by the application, or "Controls" whe 1074 by the application, or "Controls" where the RDS data is provided by
1079 the RDS controls mentioned above. 1075 the RDS controls mentioned above.
1080 1076
1081 1077
1082 FM Radio Modulator Controls 1078 FM Radio Modulator Controls
1083 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1084 1080
1085 - RDS Program ID: 1081 - RDS Program ID:
1086 1082
1087 1083
1088 - RDS Program Type: 1084 - RDS Program Type:
1089 1085
1090 1086
1091 - RDS PS Name: 1087 - RDS PS Name:
1092 1088
1093 1089
1094 - RDS Radio Text: 1090 - RDS Radio Text:
1095 1091
1096 1092
1097 - RDS Stereo: 1093 - RDS Stereo:
1098 1094
1099 1095
1100 - RDS Artificial Head: 1096 - RDS Artificial Head:
1101 1097
1102 1098
1103 - RDS Compressed: 1099 - RDS Compressed:
1104 1100
1105 1101
1106 - RDS Dynamic PTY: 1102 - RDS Dynamic PTY:
1107 1103
1108 1104
1109 - RDS Traffic Announcement: 1105 - RDS Traffic Announcement:
1110 1106
1111 1107
1112 - RDS Traffic Program: 1108 - RDS Traffic Program:
1113 1109
1114 1110
1115 - RDS Music: 1111 - RDS Music:
1116 1112
1117 these are all controls that set the R 1113 these are all controls that set the RDS data that is transmitted by
1118 the FM modulator. 1114 the FM modulator.
1119 1115
1120 - RDS Tx I/O Mode: 1116 - RDS Tx I/O Mode:
1121 1117
1122 this can be "Block I/O" where the app 1118 this can be "Block I/O" where the application has to use write()
1123 to pass the RDS blocks to the driver, 1119 to pass the RDS blocks to the driver, or "Controls" where the RDS data
1124 is Provided by the RDS controls menti 1120 is Provided by the RDS controls mentioned above.
1125 1121
1126 Metadata Capture Controls 1122 Metadata Capture Controls
1127 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 1123 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1128 1124
1129 - Generate PTS 1125 - Generate PTS
1130 1126
1131 if set, then the generated metadata s 1127 if set, then the generated metadata stream contains Presentation timestamp.
1132 1128
1133 - Generate SCR 1129 - Generate SCR
1134 1130
1135 if set, then the generated metadata s 1131 if set, then the generated metadata stream contains Source Clock information.
1136 1132
>> 1133 Video, VBI and RDS Looping
>> 1134 --------------------------
1137 1135
1138 Video, Sliced VBI and HDMI CEC Looping !! 1136 The vivid driver supports looping of video output to video input, VBI output
1139 -------------------------------------- !! 1137 to VBI input and RDS output to RDS input. For video/VBI looping this emulates
>> 1138 as if a cable was hooked up between the output and input connector. So video
>> 1139 and VBI looping is only supported between S-Video and HDMI inputs and outputs.
>> 1140 VBI is only valid for S-Video as it makes no sense for HDMI.
1140 1141
1141 Video Looping functionality is supported for !! 1142 Since radio is wireless this looping always happens if the radio receiver
1142 vivid driver instance, as well as across mult !! 1143 frequency is close to the radio transmitter frequency. In that case the radio
1143 The vivid driver supports looping of video an !! 1144 transmitter will 'override' the emulated radio stations.
1144 and an S-Video input. It also supports loopin !! 1145
1145 HDMI output and an HDMI input. !! 1146 Looping is currently supported only between devices created by the same
1146 !! 1147 vivid driver instance.
1147 To enable looping, set the 'HDMI/S-Video XXX- <<
1148 whether an input uses the Test Pattern Genera <<
1149 to an output. An input can be connected to an <<
1150 The inputs and outputs are numbered XXX-N whe <<
1151 (see module option n_devs). If there is only <<
1152 XXX will be 000. And N is the Nth S-Video/HDM <<
1153 If vivid is loaded without module options, th <<
1154 to the S-Video 000-0 output, or the HDMI 000- <<
1155 This is the equivalent of connecting or disco <<
1156 output in a physical device. <<
1157 1148
1158 If an 'HDMI/S-Video XXX-N Is Connected To' co <<
1159 output will be looped to the video input prov <<
1160 1149
1161 - the currently selected input matches the in !! 1150 Video and Sliced VBI looping
>> 1151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1162 1152
1163 - in the vivid instance of the output connect !! 1153 The way to enable video/VBI looping is currently fairly crude. A 'Loop Video'
1164 the output indicated by the control's value !! 1154 control is available in the "Vivid" control class of the video
>> 1155 capture and VBI capture devices. When checked the video looping will be enabled.
>> 1156 Once enabled any video S-Video or HDMI input will show a static test pattern
>> 1157 until the video output has started. At that time the video output will be
>> 1158 looped to the video input provided that:
>> 1159
>> 1160 - the input type matches the output type. So the HDMI input cannot receive
>> 1161 video from the S-Video output.
1165 1162
1166 - the video resolution of the video input mus 1163 - the video resolution of the video input must match that of the video output.
1167 So it is not possible to loop a 50 Hz (720x 1164 So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz
1168 (720x480) S-Video input, or a 720p60 HDMI o 1165 (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input.
1169 1166
1170 - the pixel formats must be identical on both 1167 - the pixel formats must be identical on both sides. Otherwise the driver would
1171 have to do pixel format conversion as well, 1168 have to do pixel format conversion as well, and that's taking things too far.
1172 1169
1173 - the field settings must be identical on bot 1170 - the field settings must be identical on both sides. Same reason as above:
1174 requiring the driver to convert from one fi 1171 requiring the driver to convert from one field format to another complicated
1175 matters too much. This also prohibits captu 1172 matters too much. This also prohibits capturing with 'Field Top' or 'Field
1176 Bottom' when the output video is set to 'Fi 1173 Bottom' when the output video is set to 'Field Alternate'. This combination,
1177 while legal, became too complicated to supp 1174 while legal, became too complicated to support. Both sides have to be 'Field
1178 Alternate' for this to work. Also note that 1175 Alternate' for this to work. Also note that for this specific case the
1179 sequence and field counting in struct v4l2_ 1176 sequence and field counting in struct v4l2_buffer on the capture side may not
1180 be 100% accurate. 1177 be 100% accurate.
1181 1178
1182 - field settings V4L2_FIELD_SEQ_TB/BT are not 1179 - field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to
1183 implement this, it would mean a lot of work 1180 implement this, it would mean a lot of work to get this right. Since these
1184 field values are rarely used the decision w 1181 field values are rarely used the decision was made not to implement this for
1185 now. 1182 now.
1186 1183
1187 - on the input side the "Standard Signal Mode 1184 - on the input side the "Standard Signal Mode" for the S-Video input or the
1188 "DV Timings Signal Mode" for the HDMI input 1185 "DV Timings Signal Mode" for the HDMI input should be configured so that a
1189 valid signal is passed to the video input. 1186 valid signal is passed to the video input.
1190 1187
1191 If any condition is not valid, then the 'Nois <<
1192 <<
1193 The framerates do not have to match, although 1188 The framerates do not have to match, although this might change in the future.
1194 1189
1195 By default you will see the OSD text superimp 1190 By default you will see the OSD text superimposed on top of the looped video.
1196 This can be turned off by changing the "OSD T 1191 This can be turned off by changing the "OSD Text Mode" control of the video
1197 capture device. 1192 capture device.
1198 1193
1199 For VBI looping to work all of the above must 1194 For VBI looping to work all of the above must be valid and in addition the vbi
1200 output must be configured for sliced VBI. The 1195 output must be configured for sliced VBI. The VBI capture side can be configured
1201 for either raw or sliced VBI. Note that at th 1196 for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats)
1202 and WSS (50 Hz formats) VBI data is looped. T 1197 and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped.
1203 1198
1204 1199
1205 Radio & RDS Looping 1200 Radio & RDS Looping
1206 ------------------- !! 1201 ~~~~~~~~~~~~~~~~~~~
1207 1202
1208 The vivid driver supports looping of RDS outp !! 1203 As mentioned in section 6 the radio receiver emulates stations are regular
1209 !! 1204 frequency intervals. Depending on the frequency of the radio receiver a
1210 Since radio is wireless this looping always h !! 1205 signal strength value is calculated (this is returned by VIDIOC_G_TUNER).
1211 frequency is close to the radio transmitter f !! 1206 However, it will also look at the frequency set by the radio transmitter and
1212 transmitter will 'override' the emulated radi !! 1207 if that results in a higher signal strength than the settings of the radio
1213 !! 1208 transmitter will be used as if it was a valid station. This also includes
1214 RDS looping is currently supported only betwe !! 1209 the RDS data (if any) that the transmitter 'transmits'. This is received
1215 vivid driver instance. !! 1210 faithfully on the receiver side. Note that when the driver is loaded the
1216 !! 1211 frequencies of the radio receiver and transmitter are not identical, so
1217 As mentioned in the "Radio Receiver" section, <<
1218 stations at regular frequency intervals. Depe <<
1219 radio receiver a signal strength value is cal <<
1220 VIDIOC_G_TUNER). However, it will also look a <<
1221 transmitter and if that results in a higher s <<
1222 of the radio transmitter will be used as if i <<
1223 includes the RDS data (if any) that the trans <<
1224 received faithfully on the receiver side. Not <<
1225 the frequencies of the radio receiver and tra <<
1226 initially no looping takes place. 1212 initially no looping takes place.
1227 1213
1228 1214
1229 Cropping, Composing, Scaling 1215 Cropping, Composing, Scaling
1230 ---------------------------- 1216 ----------------------------
1231 1217
1232 This driver supports cropping, composing and 1218 This driver supports cropping, composing and scaling in any combination. Normally
1233 which features are supported can be selected 1219 which features are supported can be selected through the Vivid controls,
1234 but it is also possible to hardcode it when t 1220 but it is also possible to hardcode it when the module is loaded through the
1235 ccs_cap_mode and ccs_out_mode module options. !! 1221 ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of
1236 the details of these module options. !! 1222 these module options.
1237 1223
1238 This allows you to test your application for 1224 This allows you to test your application for all these variations.
1239 1225
1240 Note that the webcam input never supports cro 1226 Note that the webcam input never supports cropping, composing or scaling. That
1241 only applies to the TV/S-Video/HDMI inputs an 1227 only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
1242 webcams, including this virtual implementatio 1228 webcams, including this virtual implementation, normally use
1243 VIDIOC_ENUM_FRAMESIZES to list a set of discr 1229 VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports.
1244 And that does not combine with cropping, comp 1230 And that does not combine with cropping, composing or scaling. This is
1245 primarily a limitation of the V4L2 API which 1231 primarily a limitation of the V4L2 API which is carefully reproduced here.
1246 1232
1247 The minimum and maximum resolutions that the 1233 The minimum and maximum resolutions that the scaler can achieve are 16x16 and
1248 (4096 * 4) x (2160 x 4), but it can only scal 1234 (4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or
1249 less. So for a source resolution of 1280x720 1235 less. So for a source resolution of 1280x720 the minimum the scaler can do is
1250 320x180 and the maximum is 5120x2880. You can 1236 320x180 and the maximum is 5120x2880. You can play around with this using the
1251 qv4l2 test tool and you will see these depend 1237 qv4l2 test tool and you will see these dependencies.
1252 1238
1253 This driver also supports larger 'bytesperlin 1239 This driver also supports larger 'bytesperline' settings, something that
1254 VIDIOC_S_FMT allows but that few drivers impl 1240 VIDIOC_S_FMT allows but that few drivers implement.
1255 1241
1256 The scaler is a simple scaler that uses the C 1242 The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's
1257 designed for speed and simplicity, not qualit 1243 designed for speed and simplicity, not quality.
1258 1244
1259 If the combination of crop, compose and scali 1245 If the combination of crop, compose and scaling allows it, then it is possible
1260 to change crop and compose rectangles on the 1246 to change crop and compose rectangles on the fly.
1261 1247
1262 1248
1263 Formats 1249 Formats
1264 ------- 1250 -------
1265 1251
1266 The driver supports all the regular packed an 1252 The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
1267 YUYV formats, 8, 16, 24 and 32 RGB packed for 1253 YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar
1268 formats. 1254 formats.
1269 1255
1270 The alpha component can be set through the 'A 1256 The alpha component can be set through the 'Alpha Component' User control
1271 for those formats that support it. If the 'Ap 1257 for those formats that support it. If the 'Apply Alpha To Red Only' control
1272 is set, then the alpha component is only used 1258 is set, then the alpha component is only used for the color red and set to
1273 0 otherwise. 1259 0 otherwise.
1274 1260
1275 The driver has to be configured to support th 1261 The driver has to be configured to support the multiplanar formats. By default
1276 the driver instances are single-planar. This 1262 the driver instances are single-planar. This can be changed by setting the
1277 multiplanar module option, see "Configuring t !! 1263 multiplanar module option, see section 1 for more details on that option.
1278 option. <<
1279 1264
1280 If the driver instance is using the multiplan 1265 If the driver instance is using the multiplanar formats/API, then the first
1281 single planar format (YUYV) and the multiplan 1266 single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1282 will have a plane that has a non-zero data_of 1267 will have a plane that has a non-zero data_offset of 128 bytes. It is rare for
1283 data_offset to be non-zero, so this is a usef 1268 data_offset to be non-zero, so this is a useful feature for testing applications.
1284 1269
1285 Video output will also honor any data_offset 1270 Video output will also honor any data_offset that the application set.
1286 1271
1287 1272
>> 1273 Capture Overlay
>> 1274 ---------------
>> 1275
>> 1276 Note: capture overlay support is implemented primarily to test the existing
>> 1277 V4L2 capture overlay API. In practice few if any GPUs support such overlays
>> 1278 anymore, and neither are they generally needed anymore since modern hardware
>> 1279 is so much more capable. By setting flag 0x10000 in the node_types module
>> 1280 option the vivid driver will create a simple framebuffer device that can be
>> 1281 used for testing this API. Whether this API should be used for new drivers is
>> 1282 questionable.
>> 1283
>> 1284 This driver has support for a destructive capture overlay with bitmap clipping
>> 1285 and list clipping (up to 16 rectangles) capabilities. Overlays are not
>> 1286 supported for multiplanar formats. It also honors the struct v4l2_window field
>> 1287 setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is
>> 1288 FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay.
>> 1289
>> 1290 The overlay only works if you are also capturing at that same time. This is a
>> 1291 vivid limitation since it copies from a buffer to the overlay instead of
>> 1292 filling the overlay directly. And if you are not capturing, then no buffers
>> 1293 are available to fill.
>> 1294
>> 1295 In addition, the pixelformat of the capture format and that of the framebuffer
>> 1296 must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return
>> 1297 an error.
>> 1298
>> 1299 In order to really see what it going on you will need to create two vivid
>> 1300 instances: the first with a framebuffer enabled. You configure the capture
>> 1301 overlay of the second instance to use the framebuffer of the first, then
>> 1302 you start capturing in the second instance. For the first instance you setup
>> 1303 the output overlay for the video output, turn on video looping and capture
>> 1304 to see the blended framebuffer overlay that's being written to by the second
>> 1305 instance. This setup would require the following commands:
>> 1306
>> 1307 .. code-block:: none
>> 1308
>> 1309 $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1
>> 1310 $ v4l2-ctl -d1 --find-fb
>> 1311 /dev/fb1 is the framebuffer associated with base address 0x12800000
>> 1312 $ sudo v4l2-ctl -d2 --set-fbuf fb=1
>> 1313 $ v4l2-ctl -d1 --set-fbuf fb=1
>> 1314 $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15'
>> 1315 $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15'
>> 1316 $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15'
>> 1317 $ v4l2-ctl -d0 -i2
>> 1318 $ v4l2-ctl -d2 -i2
>> 1319 $ v4l2-ctl -d2 -c horizontal_movement=4
>> 1320 $ v4l2-ctl -d1 --overlay=1
>> 1321 $ v4l2-ctl -d0 -c loop_video=1
>> 1322 $ v4l2-ctl -d2 --stream-mmap --overlay=1
>> 1323
>> 1324 And from another console:
>> 1325
>> 1326 .. code-block:: none
>> 1327
>> 1328 $ v4l2-ctl -d1 --stream-out-mmap
>> 1329
>> 1330 And yet another console:
>> 1331
>> 1332 .. code-block:: none
>> 1333
>> 1334 $ qv4l2
>> 1335
>> 1336 and start streaming.
>> 1337
>> 1338 As you can see, this is not for the faint of heart...
>> 1339
>> 1340
1288 Output Overlay 1341 Output Overlay
1289 -------------- 1342 --------------
1290 1343
1291 Note: output overlays are primarily implement 1344 Note: output overlays are primarily implemented in order to test the existing
1292 V4L2 output overlay API. Whether this API sho 1345 V4L2 output overlay API. Whether this API should be used for new drivers is
1293 questionable. 1346 questionable.
1294 1347
1295 This driver has support for an output overlay 1348 This driver has support for an output overlay and is capable of:
1296 1349
1297 - bitmap clipping, 1350 - bitmap clipping,
1298 - list clipping (up to 16 rectangles) 1351 - list clipping (up to 16 rectangles)
1299 - chromakey 1352 - chromakey
1300 - source chromakey 1353 - source chromakey
1301 - global alpha 1354 - global alpha
1302 - local alpha 1355 - local alpha
1303 - local inverse alpha 1356 - local inverse alpha
1304 1357
1305 Output overlays are not supported for multipl 1358 Output overlays are not supported for multiplanar formats. In addition, the
1306 pixelformat of the capture format and that of 1359 pixelformat of the capture format and that of the framebuffer must be the
1307 same for the overlay to work. Otherwise VIDIO 1360 same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error.
1308 1361
1309 Output overlays only work if the driver has b 1362 Output overlays only work if the driver has been configured to create a
1310 framebuffer by setting flag 0x10000 in the no 1363 framebuffer by setting flag 0x10000 in the node_types module option. The
1311 created framebuffer has a size of 720x576 and 1364 created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and
1312 RGB 5:6:5. 1365 RGB 5:6:5.
1313 1366
1314 In order to see the effects of the various cl 1367 In order to see the effects of the various clipping, chromakeying or alpha
1315 processing capabilities you need to turn on v 1368 processing capabilities you need to turn on video looping and see the results
1316 on the capture side. The use of the clipping, 1369 on the capture side. The use of the clipping, chromakeying or alpha processing
1317 capabilities will slow down the video loop co 1370 capabilities will slow down the video loop considerably as a lot of checks have
1318 to be done per pixel. 1371 to be done per pixel.
1319 1372
1320 1373
1321 CEC (Consumer Electronics Control) 1374 CEC (Consumer Electronics Control)
1322 ---------------------------------- 1375 ----------------------------------
1323 1376
1324 If there are HDMI inputs then a CEC adapter w 1377 If there are HDMI inputs then a CEC adapter will be created that has
1325 the same number of input ports. This is the e 1378 the same number of input ports. This is the equivalent of e.g. a TV that
1326 has that number of inputs. Each HDMI output w 1379 has that number of inputs. Each HDMI output will also create a
1327 CEC adapter that is hooked up to the correspo 1380 CEC adapter that is hooked up to the corresponding input port, or (if there
1328 are more outputs than inputs) is not hooked u 1381 are more outputs than inputs) is not hooked up at all. In other words,
1329 this is the equivalent of hooking up each out 1382 this is the equivalent of hooking up each output device to an input port of
1330 the TV. Any remaining output devices remain u 1383 the TV. Any remaining output devices remain unconnected.
1331 1384
1332 The EDID that each output reads reports a uni 1385 The EDID that each output reads reports a unique CEC physical address that is
1333 based on the physical address of the EDID of 1386 based on the physical address of the EDID of the input. So if the EDID of the
1334 receiver has physical address A.B.0.0, then e 1387 receiver has physical address A.B.0.0, then each output will see an EDID
1335 containing physical address A.B.C.0 where C i 1388 containing physical address A.B.C.0 where C is 1 to the number of inputs. If
1336 there are more outputs than inputs then the r 1389 there are more outputs than inputs then the remaining outputs have a CEC adapter
1337 that is disabled and reports an invalid physi 1390 that is disabled and reports an invalid physical address.
1338 1391
1339 1392
1340 Some Future Improvements 1393 Some Future Improvements
1341 ------------------------ 1394 ------------------------
1342 1395
1343 Just as a reminder and in no particular order 1396 Just as a reminder and in no particular order:
1344 1397
1345 - Add a virtual alsa driver to test audio 1398 - Add a virtual alsa driver to test audio
1346 - Add virtual sub-devices !! 1399 - Add virtual sub-devices and media controller support
1347 - Some support for testing compressed video 1400 - Some support for testing compressed video
1348 - Add support to loop raw VBI output to raw V 1401 - Add support to loop raw VBI output to raw VBI input
1349 - Add support to loop teletext sliced VBI out 1402 - Add support to loop teletext sliced VBI output to VBI input
1350 - Fix sequence/field numbering when looping o 1403 - Fix sequence/field numbering when looping of video with alternate fields
1351 - Add support for V4L2_CID_BG_COLOR for video 1404 - Add support for V4L2_CID_BG_COLOR for video outputs
1352 - Add ARGB888 overlay support: better testing 1405 - Add ARGB888 overlay support: better testing of the alpha channel
1353 - Improve pixel aspect support in the tpg cod 1406 - Improve pixel aspect support in the tpg code by passing a real v4l2_fract
1354 - Use per-queue locks and/or per-device locks 1407 - Use per-queue locks and/or per-device locks to improve throughput
>> 1408 - Add support to loop from a specific output to a specific input across
>> 1409 vivid instances
1355 - The SDR radio should use the same 'frequenc 1410 - The SDR radio should use the same 'frequencies' for stations as the normal
1356 radio receiver, and give back noise if the 1411 radio receiver, and give back noise if the frequency doesn't match up with
1357 a station frequency 1412 a station frequency
1358 - Make a thread for the RDS generation, that 1413 - Make a thread for the RDS generation, that would help in particular for the
1359 "Controls" RDS Rx I/O Mode as the read-only 1414 "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated
1360 in real-time. 1415 in real-time.
1361 - Changing the EDID doesn't wait 100 ms befor !! 1416 - Changing the EDID should cause hotplug detect emulation to happen.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.