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