1 vivid: Virtual Video Test Driver
2 ================================
4 This driver emulates video4linux hardware of various types: video capture, video
5 output, vbi capture and output, radio receivers and transmitters and a software
6 defined radio receiver. In addition a simple framebuffer device is available for
7 testing capture and output overlays.
9 Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs.
11 Each input can be a webcam, TV capture device, S-Video capture device or an HDMI
12 capture device. Each output can be an S-Video output device or an HDMI output
15 These inputs and outputs act exactly as a real hardware device would behave. This
16 allows you to use this driver as a test input for application development, since
17 you can test the various features without requiring special hardware.
19 This document describes the features implemented by this driver:
21 - Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O.
22 - A large list of test patterns and variations thereof
23 - Working brightness, contrast, saturation and hue controls
24 - Support for the alpha color component
25 - Full colorspace support, including limited/full RGB range
26 - All possible control types are present
27 - Support for various pixel aspect ratios and video aspect ratios
28 - Error injection to test what happens if errors occur
29 - Supports crop/compose/scale in any combination for both input and output
30 - Can emulate up to 4K resolutions
31 - All Field settings are supported for testing interlaced capturing
32 - Supports all standard YUV and RGB formats, including two multiplanar YUV formats
33 - Raw and Sliced VBI capture and output support
34 - Radio receiver and transmitter support, including RDS support
35 - Software defined radio (SDR) support
36 - Capture and output overlay support
38 These features will be described in more detail below.
44 Section 1: Configuring the driver
45 Section 2: Video Capture
46 Section 2.1: Webcam Input
47 Section 2.2: TV and S-Video Inputs
48 Section 2.3: HDMI Input
49 Section 3: Video Output
50 Section 3.1: S-Video Output
51 Section 3.2: HDMI Output
52 Section 4: VBI Capture
54 Section 6: Radio Receiver
55 Section 7: Radio Transmitter
56 Section 8: Software Defined Radio Receiver
58 Section 9.1: User Controls - Test Controls
59 Section 9.2: User Controls - Video Capture
60 Section 9.3: User Controls - Audio
61 Section 9.4: Vivid Controls
62 Section 9.4.1: Test Pattern Controls
63 Section 9.4.2: Capture Feature Selection Controls
64 Section 9.4.3: Output Feature Selection Controls
65 Section 9.4.4: Error Injection Controls
66 Section 9.4.5: VBI Raw Capture Controls
67 Section 9.5: Digital Video Controls
68 Section 9.6: FM Radio Receiver Controls
69 Section 9.7: FM Radio Modulator
70 Section 10: Video, VBI and RDS Looping
71 Section 10.1: Video and Sliced VBI looping
72 Section 10.2: Radio & RDS Looping
73 Section 11: Cropping, Composing, Scaling
75 Section 13: Capture Overlay
76 Section 14: Output Overlay
77 Section 15: CEC (Consumer Electronics Control)
78 Section 16: Some Future Improvements
81 Section 1: Configuring the driver
82 ---------------------------------
84 By default the driver will create a single instance that has a video capture
85 device with webcam, TV, S-Video and HDMI inputs, a video output device with
86 S-Video and HDMI outputs, one vbi capture device, one vbi output device, one
87 radio receiver device, one radio transmitter device and one SDR device.
89 The number of instances, devices, video inputs and outputs and their types are
90 all configurable using the following module options:
92 n_devs: number of driver instances to create. By default set to 1. Up to 64
93 instances can be created.
95 node_types: which devices should each driver instance create. An array of
96 hexadecimal values, one for each instance. The default is 0x1d3d.
97 Each value is a bitmask with the following meaning:
98 bit 0: Video Capture node
99 bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
100 bit 4: Radio Receiver node
101 bit 5: Software Defined Radio Receiver node
102 bit 8: Video Output node
103 bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
104 bit 12: Radio Transmitter node
105 bit 16: Framebuffer for testing overlays
107 So to create four instances, the first two with just one video capture
108 device, the second two with just one video output device you would pass
109 these module options to vivid:
111 n_devs=4 node_types=0x1,0x1,0x100,0x100
113 num_inputs: the number of inputs, one for each instance. By default 4 inputs
114 are created for each video capture device. At most 16 inputs can be created,
115 and there must be at least one.
117 input_types: the input types for each instance, the default is 0xe4. This defines
118 what the type of each input is when the inputs are created for each driver
119 instance. This is a hexadecimal value with up to 16 pairs of bits, each
120 pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1,
121 30-31 map to input 15. Each pair of bits has the following meaning:
123 00: this is a webcam input
124 01: this is a TV tuner input
125 10: this is an S-Video input
126 11: this is an HDMI input
128 So to create a video capture device with 8 inputs where input 0 is a TV
129 tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you
130 would use the following module options:
132 num_inputs=8 input_types=0xffa9
134 num_outputs: the number of outputs, one for each instance. By default 2 outputs
135 are created for each video output device. At most 16 outputs can be
136 created, and there must be at least one.
138 output_types: the output types for each instance, the default is 0x02. This defines
139 what the type of each output is when the outputs are created for each
140 driver instance. This is a hexadecimal value with up to 16 bits, each bit
141 gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit
142 15 maps to output 15. The meaning of each bit is as follows:
144 0: this is an S-Video output
145 1: this is an HDMI output
147 So to create a video output device with 8 outputs where outputs 0-3 are
148 S-Video outputs and outputs 4-7 are HDMI outputs you would use the
149 following module options:
151 num_outputs=8 output_types=0xf0
153 vid_cap_nr: give the desired videoX start number for each video capture device.
154 The default is -1 which will just take the first free number. This allows
155 you to map capture video nodes to specific videoX device nodes. Example:
157 n_devs=4 vid_cap_nr=2,4,6,8
159 This will attempt to assign /dev/video2 for the video capture device of
160 the first vivid instance, video4 for the next up to video8 for the last
161 instance. If it can't succeed, then it will just take the next free
164 vid_out_nr: give the desired videoX start number for each video output device.
165 The default is -1 which will just take the first free number.
167 vbi_cap_nr: give the desired vbiX start number for each vbi capture device.
168 The default is -1 which will just take the first free number.
170 vbi_out_nr: give the desired vbiX start number for each vbi output device.
171 The default is -1 which will just take the first free number.
173 radio_rx_nr: give the desired radioX start number for each radio receiver device.
174 The default is -1 which will just take the first free number.
176 radio_tx_nr: give the desired radioX start number for each radio transmitter
177 device. The default is -1 which will just take the first free number.
179 sdr_cap_nr: give the desired swradioX start number for each SDR capture device.
180 The default is -1 which will just take the first free number.
182 ccs_cap_mode: specify the allowed video capture crop/compose/scaling combination
183 for each driver instance. Video capture devices can have any combination
184 of cropping, composing and scaling capabilities and this will tell the
185 vivid driver which of those is should emulate. By default the user can
186 select this through controls.
188 The value is either -1 (controlled by the user) or a set of three bits,
189 each enabling (1) or disabling (0) one of the features:
191 bit 0: Enable crop support. Cropping will take only part of the
193 bit 1: Enable compose support. Composing will copy the incoming
194 picture into a larger buffer.
195 bit 2: Enable scaling support. Scaling can scale the incoming
196 picture. The scaler of the vivid driver can enlarge up
197 or down to four times the original size. The scaler is
198 very simple and low-quality. Simplicity and speed were
201 Note that this value is ignored by webcam inputs: those enumerate
202 discrete framesizes and that is incompatible with cropping, composing
205 ccs_out_mode: specify the allowed video output crop/compose/scaling combination
206 for each driver instance. Video output devices can have any combination
207 of cropping, composing and scaling capabilities and this will tell the
208 vivid driver which of those is should emulate. By default the user can
209 select this through controls.
211 The value is either -1 (controlled by the user) or a set of three bits,
212 each enabling (1) or disabling (0) one of the features:
214 bit 0: Enable crop support. Cropping will take only part of the
216 bit 1: Enable compose support. Composing will copy the incoming
217 buffer into a larger picture frame.
218 bit 2: Enable scaling support. Scaling can scale the incoming
219 buffer. The scaler of the vivid driver can enlarge up
220 or down to four times the original size. The scaler is
221 very simple and low-quality. Simplicity and speed were
224 multiplanar: select whether each device instance supports multi-planar formats,
225 and thus the V4L2 multi-planar API. By default device instances are
228 This module option can override that for each instance. Values are:
230 1: this is a single-planar instance.
231 2: this is a multi-planar instance.
233 vivid_debug: enable driver debugging info
235 no_error_inj: if set disable the error injecting controls. This option is
236 needed in order to run a tool like v4l2-compliance. Tools like that
237 exercise all controls including a control like 'Disconnect' which
238 emulates a USB disconnect, making the device inaccessible and so
239 all tests that v4l2-compliance is doing will fail afterwards.
241 There may be other situations as well where you want to disable the
242 error injection support of vivid. When this option is set, then the
243 controls that select crop, compose and scale behavior are also
244 removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the
245 will default to enabling crop, compose and scaling.
247 Taken together, all these module options allow you to precisely customize
248 the driver behavior and test your application with all sorts of permutations.
249 It is also very suitable to emulate hardware that is not yet available, e.g.
250 when developing software for a new upcoming device.
253 Section 2: Video Capture
254 ------------------------
256 This is probably the most frequently used feature. The video capture device
257 can be configured by using the module options num_inputs, input_types and
258 ccs_cap_mode (see section 1 for more detailed information), but by default
259 four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI
260 input, one input for each input type. Those are described in more detail
263 Special attention has been given to the rate at which new frames become
264 available. The jitter will be around 1 jiffie (that depends on the HZ
265 configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second),
266 but the long-term behavior is exactly following the framerate. So a
267 framerate of 59.94 Hz is really different from 60 Hz. If the framerate
268 exceeds your kernel's HZ value, then you will get dropped frames, but the
269 frame/field sequence counting will keep track of that so the sequence
270 count will skip whenever frames are dropped.
273 Section 2.1: Webcam Input
274 -------------------------
276 The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It
277 supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones
278 are available depends on the chosen framesize: the larger the framesize, the
279 lower the maximum frames per second.
281 The initially selected colorspace when you switch to the webcam input will be
285 Section 2.2: TV and S-Video Inputs
286 ----------------------------------
288 The only difference between the TV and S-Video input is that the TV has a
289 tuner. Otherwise they behave identically.
291 These inputs support audio inputs as well: one TV and one Line-In. They
292 both support all TV standards. If the standard is queried, then the Vivid
293 controls 'Standard Signal Mode' and 'Standard' determine what
296 These inputs support all combinations of the field setting. Special care has
297 been taken to faithfully reproduce how fields are handled for the different
298 TV standards. This is particularly noticeable when generating a horizontally
299 moving image so the temporal effect of using interlaced formats becomes clearly
300 visible. For 50 Hz standards the top field is the oldest and the bottom field
301 is the newest in time. For 60 Hz standards that is reversed: the bottom field
302 is the oldest and the top field is the newest in time.
304 When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
305 contain the top field for 50 Hz standards and the bottom field for 60 Hz
306 standards. This is what capture hardware does as well.
308 Finally, for PAL/SECAM standards the first half of the top line contains noise.
309 This simulates the Wide Screen Signal that is commonly placed there.
311 The initially selected colorspace when you switch to the TV or S-Video input
314 The pixel aspect ratio will depend on the TV standard. The video aspect ratio
315 can be selected through the 'Standard Aspect Ratio' Vivid control.
316 Choices are '4x3', '16x9' which will give letterboxed widescreen video and
317 '16x9 Anamorphic' which will give full screen squashed anamorphic widescreen
318 video that will need to be scaled accordingly.
320 The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available
321 every 6 MHz, starting from 49.25 MHz. For each channel the generated image
322 will be in color for the +/- 0.25 MHz around it, and in grayscale for
323 +/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER
324 ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz.
325 It will also return correct afc values to show whether the frequency is too
328 The audio subchannels that are returned are MONO for the +/- 1 MHz range around
329 a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
330 channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or
331 LANG1 | LANG2 (for others), or STEREO | SAP.
333 Which one is returned depends on the chosen channel, each next valid channel
334 will cycle through the possible audio subchannel combinations. This allows
335 you to test the various combinations by just switching channels..
337 Finally, for these inputs the v4l2_timecode struct is filled in in the
338 dequeued v4l2_buffer struct.
341 Section 2.3: HDMI Input
342 -----------------------
344 The HDMI inputs supports all CEA-861 and DMT timings, both progressive and
345 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
346 mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the
347 field order is always top field first, and when you start capturing an
348 interlaced format you will receive the top field first.
350 The initially selected colorspace when you switch to the HDMI input or
351 select an HDMI timing is based on the format resolution: for resolutions
352 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
353 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
355 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
356 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
357 standard, and for all others a 1:1 pixel aspect ratio is returned.
359 The video aspect ratio can be selected through the 'DV Timings Aspect Ratio'
360 Vivid control. Choices are 'Source Width x Height' (just use the
361 same ratio as the chosen format), '4x3' or '16x9', either of which can
362 result in pillarboxed or letterboxed video.
364 For HDMI inputs it is possible to set the EDID. By default a simple EDID
365 is provided. You can only set the EDID for HDMI inputs. Internally, however,
366 the EDID is shared between all HDMI inputs.
368 No interpretation is done of the EDID data with the exception of the
369 physical address. See the CEC section for more details.
371 There is a maximum of 15 HDMI inputs (if there are more, then they will be
372 reduced to 15) since that's the limitation of the EDID physical address.
375 Section 3: Video Output
376 -----------------------
378 The video output device can be configured by using the module options
379 num_outputs, output_types and ccs_out_mode (see section 1 for more detailed
380 information), but by default two outputs are configured: an S-Video and an
381 HDMI input, one output for each output type. Those are described in more detail
384 Like with video capture the framerate is also exact in the long term.
387 Section 3.1: S-Video Output
388 ---------------------------
390 This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2".
391 The S-Video output supports all TV standards.
393 This output supports all combinations of the field setting.
395 The initially selected colorspace when you switch to the TV or S-Video input
399 Section 3.2: HDMI Output
400 ------------------------
402 The HDMI output supports all CEA-861 and DMT timings, both progressive and
403 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
404 mode for interlaced formats is always V4L2_FIELD_ALTERNATE.
406 The initially selected colorspace when you switch to the HDMI output or
407 select an HDMI timing is based on the format resolution: for resolutions
408 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
409 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
411 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
412 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
413 standard, and for all others a 1:1 pixel aspect ratio is returned.
415 An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID.
417 There is a maximum of 15 HDMI outputs (if there are more, then they will be
418 reduced to 15) since that's the limitation of the EDID physical address. See
419 also the CEC section for more details.
421 Section 4: VBI Capture
422 ----------------------
424 There are three types of VBI capture devices: those that only support raw
425 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
426 support both. This is determined by the node_types module option. In all
427 cases the driver will generate valid VBI data: for 60 Hz standards it will
428 generate Closed Caption and XDS data. The closed caption stream will
429 alternate between "Hello world!" and "Closed captions test" every second.
430 The XDS stream will give the current time once a minute. For 50 Hz standards
431 it will generate the Wide Screen Signal which is based on the actual Video
432 Aspect Ratio control setting and teletext pages 100-159, one page per frame.
434 The VBI device will only work for the S-Video and TV inputs, it will give
435 back an error if the current input is a webcam or HDMI.
438 Section 5: VBI Output
439 ---------------------
441 There are three types of VBI output devices: those that only support raw
442 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
443 support both. This is determined by the node_types module option.
445 The sliced VBI output supports the Wide Screen Signal and the teletext signal
446 for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards.
448 The VBI device will only work for the S-Video output, it will give
449 back an error if the current output is HDMI.
452 Section 6: Radio Receiver
453 -------------------------
455 The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS.
456 The frequency ranges are:
459 AM: 520 kHz - 1710 kHz
460 SW: 2300 kHz - 26.1 MHz
462 Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW.
463 The signal strength decreases the further the frequency is from the valid
464 frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
465 ideal frequency. The initial frequency when the driver is loaded is set to
468 The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls'
469 modes. In the 'Controls' mode the RDS information is stored in read-only
470 controls. These controls are updated every time the frequency is changed,
471 or when the tuner status is requested. The Block I/O method uses the read()
472 interface to pass the RDS blocks on to the application for decoding.
474 The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
475 and the further the frequency is away from the valid frequency the more RDS
476 errors are randomly introduced into the block I/O stream, up to 50% of all
477 blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
478 can occur in equal proportions: blocks marked 'CORRECTED', blocks marked
479 'ERROR', blocks marked 'INVALID' and dropped blocks.
481 The generated RDS stream contains all the standard fields contained in a
482 0B group, and also radio text and the current time.
484 The receiver supports HW frequency seek, either in Bounded mode, Wrap Around
485 mode or both, which is configurable with the "Radio HW Seek Mode" control.
488 Section 7: Radio Transmitter
489 ----------------------------
491 The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS.
492 The frequency ranges are:
495 AM: 520 kHz - 1710 kHz
496 SW: 2300 kHz - 26.1 MHz
498 The initial frequency when the driver is loaded is 95.5 MHz.
500 The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls'
501 modes. In the 'Controls' mode the transmitted RDS information is configured
502 using controls, and in 'Block I/O' mode the blocks are passed to the driver
506 Section 8: Software Defined Radio Receiver
507 ------------------------------------------
509 The SDR receiver has three frequency bands for the ADC tuner:
515 The RF tuner supports 50 MHz - 2000 MHz.
517 The generated data contains the In-phase and Quadrature components of a
518 1 kHz tone that has an amplitude of sqrt(2).
524 Different devices support different controls. The sections below will describe
525 each control and which devices support them.
528 Section 9.1: User Controls - Test Controls
529 ------------------------------------------
531 The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and
532 Integer Menu are controls that represent all possible control types. The Menu
533 control and the Integer Menu control both have 'holes' in their menu list,
534 meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called.
535 Both menu controls also have a non-zero minimum control value. These features
536 allow you to check if your application can handle such things correctly.
537 These controls are supported for every device type.
540 Section 9.2: User Controls - Video Capture
541 ------------------------------------------
543 The following controls are specific to video capture.
545 The Brightness, Contrast, Saturation and Hue controls actually work and are
546 standard. There is one special feature with the Brightness control: each
547 video input has its own brightness value, so changing input will restore
548 the brightness for that input. In addition, each video input uses a different
549 brightness range (minimum and maximum control values). Switching inputs will
550 cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set.
551 This allows you to test controls that can change their range.
553 The 'Gain, Automatic' and Gain controls can be used to test volatile controls:
554 if 'Gain, Automatic' is set, then the Gain control is volatile and changes
555 constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal
558 The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
559 image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid
562 The 'Alpha Component' control can be used to set the alpha component for
563 formats containing an alpha channel.
566 Section 9.3: User Controls - Audio
567 ----------------------------------
569 The following controls are specific to video capture and output and radio
570 receivers and transmitters.
572 The 'Volume' and 'Mute' audio controls are typical for such devices to
573 control the volume and mute the audio. They don't actually do anything in
577 Section 9.4: Vivid Controls
578 ---------------------------
580 These vivid custom controls control the image generation, error injection, etc.
583 Section 9.4.1: Test Pattern Controls
584 ------------------------------------
586 The Test Pattern Controls are all specific to video capture.
588 Test Pattern: selects which test pattern to use. Use the CSC Colorbar for
589 testing colorspace conversions: the colors used in that test pattern
590 map to valid colors in all colorspaces. The colorspace conversion
591 is disabled for the other test patterns.
593 OSD Text Mode: selects whether the text superimposed on the
594 test pattern should be shown, and if so, whether only counters should
595 be displayed or the full text.
597 Horizontal Movement: selects whether the test pattern should
598 move to the left or right and at what speed.
600 Vertical Movement: does the same for the vertical direction.
602 Show Border: show a two-pixel wide border at the edge of the actual image,
603 excluding letter or pillarboxing.
605 Show Square: show a square in the middle of the image. If the image is
606 displayed with the correct pixel and image aspect ratio corrections,
607 then the width and height of the square on the monitor should be
610 Insert SAV Code in Image: adds a SAV (Start of Active Video) code to the image.
611 This can be used to check if such codes in the image are inadvertently
612 interpreted instead of being ignored.
614 Insert EAV Code in Image: does the same for the EAV (End of Active Video) code.
617 Section 9.4.2: Capture Feature Selection Controls
618 -------------------------------------------------
620 These controls are all specific to video capture.
622 Sensor Flipped Horizontally: the image is flipped horizontally and the
623 V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where
624 a sensor is for example mounted upside down.
626 Sensor Flipped Vertically: the image is flipped vertically and the
627 V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where
628 a sensor is for example mounted upside down.
630 Standard Aspect Ratio: selects if the image aspect ratio as used for the TV or
631 S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may
632 introduce letterboxing.
634 DV Timings Aspect Ratio: selects if the image aspect ratio as used for the HDMI
635 input should be the same as the source width and height ratio, or if
636 it should be 4x3 or 16x9. This may introduce letter or pillarboxing.
638 Timestamp Source: selects when the timestamp for each buffer is taken.
640 Colorspace: selects which colorspace should be used when generating the image.
641 This only applies if the CSC Colorbar test pattern is selected,
642 otherwise the test pattern will go through unconverted.
643 This behavior is also what you want, since a 75% Colorbar
644 should really have 75% signal intensity and should not be affected
645 by colorspace conversions.
647 Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE
648 to be sent since it emulates a detected colorspace change.
650 Transfer Function: selects which colorspace transfer function should be used when
651 generating an image. This only applies if the CSC Colorbar test pattern is
652 selected, otherwise the test pattern will go through unconverted.
653 This behavior is also what you want, since a 75% Colorbar
654 should really have 75% signal intensity and should not be affected
655 by colorspace conversions.
657 Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE
658 to be sent since it emulates a detected colorspace change.
660 Y'CbCr Encoding: selects which Y'CbCr encoding should be used when generating
661 a Y'CbCr image. This only applies if the format is set to a Y'CbCr format
662 as opposed to an RGB format.
664 Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE
665 to be sent since it emulates a detected colorspace change.
667 Quantization: selects which quantization should be used for the RGB or Y'CbCr
668 encoding when generating the test pattern.
670 Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
671 to be sent since it emulates a detected colorspace change.
673 Limited RGB Range (16-235): selects if the RGB range of the HDMI source should
674 be limited or full range. This combines with the Digital Video 'Rx RGB
675 Quantization Range' control and can be used to test what happens if
676 a source provides you with the wrong quantization range information.
677 See the description of that control for more details.
679 Apply Alpha To Red Only: apply the alpha channel as set by the 'Alpha Component'
680 user control to the red color of the test pattern only.
682 Enable Capture Cropping: enables crop support. This control is only present if
683 the ccs_cap_mode module option is set to the default value of -1 and if
684 the no_error_inj module option is set to 0 (the default).
686 Enable Capture Composing: enables composing support. This control is only
687 present if the ccs_cap_mode module option is set to the default value of
688 -1 and if the no_error_inj module option is set to 0 (the default).
690 Enable Capture Scaler: enables support for a scaler (maximum 4 times upscaling
691 and downscaling). This control is only present if the ccs_cap_mode
692 module option is set to the default value of -1 and if the no_error_inj
693 module option is set to 0 (the default).
695 Maximum EDID Blocks: determines how many EDID blocks the driver supports.
696 Note that the vivid driver does not actually interpret new EDID
697 data, it just stores it. It allows for up to 256 EDID blocks
698 which is the maximum supported by the standard.
700 Fill Percentage of Frame: can be used to draw only the top X percent
701 of the image. Since each frame has to be drawn by the driver, this
702 demands a lot of the CPU. For large resolutions this becomes
703 problematic. By drawing only part of the image this CPU load can
707 Section 9.4.3: Output Feature Selection Controls
708 ------------------------------------------------
710 These controls are all specific to video output.
712 Enable Output Cropping: enables crop support. This control is only present if
713 the ccs_out_mode module option is set to the default value of -1 and if
714 the no_error_inj module option is set to 0 (the default).
716 Enable Output Composing: enables composing support. This control is only
717 present if the ccs_out_mode module option is set to the default value of
718 -1 and if the no_error_inj module option is set to 0 (the default).
720 Enable Output Scaler: enables support for a scaler (maximum 4 times upscaling
721 and downscaling). This control is only present if the ccs_out_mode
722 module option is set to the default value of -1 and if the no_error_inj
723 module option is set to 0 (the default).
726 Section 9.4.4: Error Injection Controls
727 ---------------------------------------
729 The following two controls are only valid for video and vbi capture.
731 Standard Signal Mode: selects the behavior of VIDIOC_QUERYSTD: what should
734 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
735 to be sent since it emulates a changed input condition (e.g. a cable
736 was plugged in or out).
738 Standard: selects the standard that VIDIOC_QUERYSTD should return if the
739 previous control is set to "Selected Standard".
741 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
742 to be sent since it emulates a changed input standard.
745 The following two controls are only valid for video capture.
747 DV Timings Signal Mode: selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what
750 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
751 to be sent since it emulates a changed input condition (e.g. a cable
752 was plugged in or out).
754 DV Timings: selects the timings the VIDIOC_QUERY_DV_TIMINGS should return
755 if the previous control is set to "Selected DV Timings".
757 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
758 to be sent since it emulates changed input timings.
761 The following controls are only present if the no_error_inj module option
762 is set to 0 (the default). These controls are valid for video and vbi
763 capture and output streams and for the SDR capture device except for the
764 Disconnect control which is valid for all devices.
766 Wrap Sequence Number: test what happens when you wrap the sequence number in
767 struct v4l2_buffer around.
769 Wrap Timestamp: test what happens when you wrap the timestamp in struct
772 Percentage of Dropped Buffers: sets the percentage of buffers that
773 are never returned by the driver (i.e., they are dropped).
775 Disconnect: emulates a USB disconnect. The device will act as if it has
776 been disconnected. Only after all open filehandles to the device
777 node have been closed will the device become 'connected' again.
779 Inject V4L2_BUF_FLAG_ERROR: when pressed, the next frame returned by
780 the driver will have the error flag set (i.e. the frame is marked
783 Inject VIDIOC_REQBUFS Error: when pressed, the next REQBUFS or CREATE_BUFS
784 ioctl call will fail with an error. To be precise: the videobuf2
785 queue_setup() op will return -EINVAL.
787 Inject VIDIOC_QBUF Error: when pressed, the next VIDIOC_QBUF or
788 VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be
789 precise: the videobuf2 buf_prepare() op will return -EINVAL.
791 Inject VIDIOC_STREAMON Error: when pressed, the next VIDIOC_STREAMON ioctl
792 call will fail with an error. To be precise: the videobuf2
793 start_streaming() op will return -EINVAL.
795 Inject Fatal Streaming Error: when pressed, the streaming core will be
796 marked as having suffered a fatal error, the only way to recover
797 from that is to stop streaming. To be precise: the videobuf2
798 vb2_queue_error() function is called.
801 Section 9.4.5: VBI Raw Capture Controls
802 ---------------------------------------
804 Interlaced VBI Format: if set, then the raw VBI data will be interlaced instead
805 of providing it grouped by field.
808 Section 9.5: Digital Video Controls
809 -----------------------------------
811 Rx RGB Quantization Range: sets the RGB quantization detection of the HDMI
812 input. This combines with the Vivid 'Limited RGB Range (16-235)'
813 control and can be used to test what happens if a source provides
814 you with the wrong quantization range information. This can be tested
815 by selecting an HDMI input, setting this control to Full or Limited
816 range and selecting the opposite in the 'Limited RGB Range (16-235)'
817 control. The effect is easy to see if the 'Gray Ramp' test pattern
820 Tx RGB Quantization Range: sets the RGB quantization detection of the HDMI
821 output. It is currently not used for anything in vivid, but most HDMI
822 transmitters would typically have this control.
824 Transmit Mode: sets the transmit mode of the HDMI output to HDMI or DVI-D. This
825 affects the reported colorspace since DVI_D outputs will always use
829 Section 9.6: FM Radio Receiver Controls
830 ---------------------------------------
832 RDS Reception: set if the RDS receiver should be enabled.
837 RDS Traffic Announcement:
839 RDS Music: these are all read-only controls. If RDS Rx I/O Mode is set to
840 "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set
841 to "Controls", then these controls report the received RDS data. Note
842 that the vivid implementation of this is pretty basic: they are only
843 updated when you set a new frequency or when you get the tuner status
846 Radio HW Seek Mode: can be one of "Bounded", "Wrap Around" or "Both". This
847 determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency
848 range or wrap-around or if it is selectable by the user.
850 Radio Programmable HW Seek: if set, then the user can provide the lower and
851 upper bound of the HW Seek. Otherwise the frequency range boundaries
854 Generate RBDS Instead of RDS: if set, then generate RBDS (the US variant of
855 RDS) data instead of RDS (European-style RDS). This affects only the
856 PICODE and PTY codes.
858 RDS Rx I/O Mode: this can be "Block I/O" where the RDS blocks have to be read()
859 by the application, or "Controls" where the RDS data is provided by
860 the RDS controls mentioned above.
863 Section 9.7: FM Radio Modulator Controls
864 ----------------------------------------
874 RDS Traffic Announcement:
876 RDS Music: these are all controls that set the RDS data that is transmitted by
879 RDS Tx I/O Mode: this can be "Block I/O" where the application has to use write()
880 to pass the RDS blocks to the driver, or "Controls" where the RDS data is
881 provided by the RDS controls mentioned above.
884 Section 10: Video, VBI and RDS Looping
885 --------------------------------------
887 The vivid driver supports looping of video output to video input, VBI output
888 to VBI input and RDS output to RDS input. For video/VBI looping this emulates
889 as if a cable was hooked up between the output and input connector. So video
890 and VBI looping is only supported between S-Video and HDMI inputs and outputs.
891 VBI is only valid for S-Video as it makes no sense for HDMI.
893 Since radio is wireless this looping always happens if the radio receiver
894 frequency is close to the radio transmitter frequency. In that case the radio
895 transmitter will 'override' the emulated radio stations.
897 Looping is currently supported only between devices created by the same
898 vivid driver instance.
901 Section 10.1: Video and Sliced VBI looping
902 ------------------------------------------
904 The way to enable video/VBI looping is currently fairly crude. A 'Loop Video'
905 control is available in the "Vivid" control class of the video
906 capture and VBI capture devices. When checked the video looping will be enabled.
907 Once enabled any video S-Video or HDMI input will show a static test pattern
908 until the video output has started. At that time the video output will be
909 looped to the video input provided that:
911 - the input type matches the output type. So the HDMI input cannot receive
912 video from the S-Video output.
914 - the video resolution of the video input must match that of the video output.
915 So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz
916 (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input.
918 - the pixel formats must be identical on both sides. Otherwise the driver would
919 have to do pixel format conversion as well, and that's taking things too far.
921 - the field settings must be identical on both sides. Same reason as above:
922 requiring the driver to convert from one field format to another complicated
923 matters too much. This also prohibits capturing with 'Field Top' or 'Field
924 Bottom' when the output video is set to 'Field Alternate'. This combination,
925 while legal, became too complicated to support. Both sides have to be 'Field
926 Alternate' for this to work. Also note that for this specific case the
927 sequence and field counting in struct v4l2_buffer on the capture side may not
930 - field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to
931 implement this, it would mean a lot of work to get this right. Since these
932 field values are rarely used the decision was made not to implement this for
935 - on the input side the "Standard Signal Mode" for the S-Video input or the
936 "DV Timings Signal Mode" for the HDMI input should be configured so that a
937 valid signal is passed to the video input.
939 The framerates do not have to match, although this might change in the future.
941 By default you will see the OSD text superimposed on top of the looped video.
942 This can be turned off by changing the "OSD Text Mode" control of the video
945 For VBI looping to work all of the above must be valid and in addition the vbi
946 output must be configured for sliced VBI. The VBI capture side can be configured
947 for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats)
948 and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped.
951 Section 10.2: Radio & RDS Looping
952 ---------------------------------
954 As mentioned in section 6 the radio receiver emulates stations are regular
955 frequency intervals. Depending on the frequency of the radio receiver a
956 signal strength value is calculated (this is returned by VIDIOC_G_TUNER).
957 However, it will also look at the frequency set by the radio transmitter and
958 if that results in a higher signal strength than the settings of the radio
959 transmitter will be used as if it was a valid station. This also includes
960 the RDS data (if any) that the transmitter 'transmits'. This is received
961 faithfully on the receiver side. Note that when the driver is loaded the
962 frequencies of the radio receiver and transmitter are not identical, so
963 initially no looping takes place.
966 Section 11: Cropping, Composing, Scaling
967 ----------------------------------------
969 This driver supports cropping, composing and scaling in any combination. Normally
970 which features are supported can be selected through the Vivid controls,
971 but it is also possible to hardcode it when the module is loaded through the
972 ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of
973 these module options.
975 This allows you to test your application for all these variations.
977 Note that the webcam input never supports cropping, composing or scaling. That
978 only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
979 webcams, including this virtual implementation, normally use
980 VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports.
981 And that does not combine with cropping, composing or scaling. This is
982 primarily a limitation of the V4L2 API which is carefully reproduced here.
984 The minimum and maximum resolutions that the scaler can achieve are 16x16 and
985 (4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or
986 less. So for a source resolution of 1280x720 the minimum the scaler can do is
987 320x180 and the maximum is 5120x2880. You can play around with this using the
988 qv4l2 test tool and you will see these dependencies.
990 This driver also supports larger 'bytesperline' settings, something that
991 VIDIOC_S_FMT allows but that few drivers implement.
993 The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's
994 designed for speed and simplicity, not quality.
996 If the combination of crop, compose and scaling allows it, then it is possible
997 to change crop and compose rectangles on the fly.
1003 The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
1004 YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar
1007 The alpha component can be set through the 'Alpha Component' User control
1008 for those formats that support it. If the 'Apply Alpha To Red Only' control
1009 is set, then the alpha component is only used for the color red and set to
1012 The driver has to be configured to support the multiplanar formats. By default
1013 the driver instances are single-planar. This can be changed by setting the
1014 multiplanar module option, see section 1 for more details on that option.
1016 If the driver instance is using the multiplanar formats/API, then the first
1017 single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1018 will have a plane that has a non-zero data_offset of 128 bytes. It is rare for
1019 data_offset to be non-zero, so this is a useful feature for testing applications.
1021 Video output will also honor any data_offset that the application set.
1024 Section 13: Capture Overlay
1025 ---------------------------
1027 Note: capture overlay support is implemented primarily to test the existing
1028 V4L2 capture overlay API. In practice few if any GPUs support such overlays
1029 anymore, and neither are they generally needed anymore since modern hardware
1030 is so much more capable. By setting flag 0x10000 in the node_types module
1031 option the vivid driver will create a simple framebuffer device that can be
1032 used for testing this API. Whether this API should be used for new drivers is
1035 This driver has support for a destructive capture overlay with bitmap clipping
1036 and list clipping (up to 16 rectangles) capabilities. Overlays are not
1037 supported for multiplanar formats. It also honors the struct v4l2_window field
1038 setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is
1039 FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay.
1041 The overlay only works if you are also capturing at that same time. This is a
1042 vivid limitation since it copies from a buffer to the overlay instead of
1043 filling the overlay directly. And if you are not capturing, then no buffers
1044 are available to fill.
1046 In addition, the pixelformat of the capture format and that of the framebuffer
1047 must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return
1050 In order to really see what it going on you will need to create two vivid
1051 instances: the first with a framebuffer enabled. You configure the capture
1052 overlay of the second instance to use the framebuffer of the first, then
1053 you start capturing in the second instance. For the first instance you setup
1054 the output overlay for the video output, turn on video looping and capture
1055 to see the blended framebuffer overlay that's being written to by the second
1056 instance. This setup would require the following commands:
1058 $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1
1059 $ v4l2-ctl -d1 --find-fb
1060 /dev/fb1 is the framebuffer associated with base address 0x12800000
1061 $ sudo v4l2-ctl -d2 --set-fbuf fb=1
1062 $ v4l2-ctl -d1 --set-fbuf fb=1
1063 $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15'
1064 $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15'
1065 $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15'
1068 $ v4l2-ctl -d2 -c horizontal_movement=4
1069 $ v4l2-ctl -d1 --overlay=1
1070 $ v4l2-ctl -d1 -c loop_video=1
1071 $ v4l2-ctl -d2 --stream-mmap --overlay=1
1073 And from another console:
1075 $ v4l2-ctl -d1 --stream-out-mmap
1077 And yet another console:
1081 and start streaming.
1083 As you can see, this is not for the faint of heart...
1086 Section 14: Output Overlay
1087 --------------------------
1089 Note: output overlays are primarily implemented in order to test the existing
1090 V4L2 output overlay API. Whether this API should be used for new drivers is
1093 This driver has support for an output overlay and is capable of:
1096 - list clipping (up to 16 rectangles)
1101 - local inverse alpha
1103 Output overlays are not supported for multiplanar formats. In addition, the
1104 pixelformat of the capture format and that of the framebuffer must be the
1105 same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error.
1107 Output overlays only work if the driver has been configured to create a
1108 framebuffer by setting flag 0x10000 in the node_types module option. The
1109 created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and
1112 In order to see the effects of the various clipping, chromakeying or alpha
1113 processing capabilities you need to turn on video looping and see the results
1114 on the capture side. The use of the clipping, chromakeying or alpha processing
1115 capabilities will slow down the video loop considerably as a lot of checks have
1116 to be done per pixel.
1119 Section 15: CEC (Consumer Electronics Control)
1120 ----------------------------------------------
1122 If there are HDMI inputs then a CEC adapter will be created that has
1123 the same number of input ports. This is the equivalent of e.g. a TV that
1124 has that number of inputs. Each HDMI output will also create a
1125 CEC adapter that is hooked up to the corresponding input port, or (if there
1126 are more outputs than inputs) is not hooked up at all. In other words,
1127 this is the equivalent of hooking up each output device to an input port of
1128 the TV. Any remaining output devices remain unconnected.
1130 The EDID that each output reads reports a unique CEC physical address that is
1131 based on the physical address of the EDID of the input. So if the EDID of the
1132 receiver has physical address A.B.0.0, then each output will see an EDID
1133 containing physical address A.B.C.0 where C is 1 to the number of inputs. If
1134 there are more outputs than inputs then the remaining outputs have a CEC adapter
1135 that is disabled and reports an invalid physical address.
1138 Section 16: Some Future Improvements
1139 ------------------------------------
1141 Just as a reminder and in no particular order:
1143 - Add a virtual alsa driver to test audio
1144 - Add virtual sub-devices and media controller support
1145 - Some support for testing compressed video
1146 - Add support to loop raw VBI output to raw VBI input
1147 - Add support to loop teletext sliced VBI output to VBI input
1148 - Fix sequence/field numbering when looping of video with alternate fields
1149 - Add support for V4L2_CID_BG_COLOR for video outputs
1150 - Add ARGB888 overlay support: better testing of the alpha channel
1151 - Improve pixel aspect support in the tpg code by passing a real v4l2_fract
1152 - Use per-queue locks and/or per-device locks to improve throughput
1153 - Add support to loop from a specific output to a specific input across
1155 - The SDR radio should use the same 'frequencies' for stations as the normal
1156 radio receiver, and give back noise if the frequency doesn't match up with
1158 - Make a thread for the RDS generation, that would help in particular for the
1159 "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated
1161 - Changing the EDID should cause hotplug detect emulation to happen.
git.samba.org / sfrench / cifs-2.6.git / blob