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