Back to home page

OSCL-LXR

 
 

    


0001 .. SPDX-License-Identifier: GPL-2.0
0002 
0003 The Virtual Video Test Driver (vivid)
0004 =====================================
0005 
0006 This driver emulates video4linux hardware of various types: video capture, video
0007 output, vbi capture and output, metadata capture and output, radio receivers and
0008 transmitters, touch capture and a software defined radio receiver. In addition a
0009 simple framebuffer device is available for testing capture and output overlays.
0010 
0011 Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs.
0012 
0013 Each input can be a webcam, TV capture device, S-Video capture device or an HDMI
0014 capture device. Each output can be an S-Video output device or an HDMI output
0015 device.
0016 
0017 These inputs and outputs act exactly as a real hardware device would behave. This
0018 allows you to use this driver as a test input for application development, since
0019 you can test the various features without requiring special hardware.
0020 
0021 This document describes the features implemented by this driver:
0022 
0023 - Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O.
0024 - A large list of test patterns and variations thereof
0025 - Working brightness, contrast, saturation and hue controls
0026 - Support for the alpha color component
0027 - Full colorspace support, including limited/full RGB range
0028 - All possible control types are present
0029 - Support for various pixel aspect ratios and video aspect ratios
0030 - Error injection to test what happens if errors occur
0031 - Supports crop/compose/scale in any combination for both input and output
0032 - Can emulate up to 4K resolutions
0033 - All Field settings are supported for testing interlaced capturing
0034 - Supports all standard YUV and RGB formats, including two multiplanar YUV formats
0035 - Raw and Sliced VBI capture and output support
0036 - Radio receiver and transmitter support, including RDS support
0037 - Software defined radio (SDR) support
0038 - Capture and output overlay support
0039 - Metadata capture and output support
0040 - Touch capture support
0041 
0042 These features will be described in more detail below.
0043 
0044 Configuring the driver
0045 ----------------------
0046 
0047 By default the driver will create a single instance that has a video capture
0048 device with webcam, TV, S-Video and HDMI inputs, a video output device with
0049 S-Video and HDMI outputs, one vbi capture device, one vbi output device, one
0050 radio receiver device, one radio transmitter device and one SDR device.
0051 
0052 The number of instances, devices, video inputs and outputs and their types are
0053 all configurable using the following module options:
0054 
0055 - n_devs:
0056 
0057         number of driver instances to create. By default set to 1. Up to 64
0058         instances can be created.
0059 
0060 - node_types:
0061 
0062         which devices should each driver instance create. An array of
0063         hexadecimal values, one for each instance. The default is 0x1d3d.
0064         Each value is a bitmask with the following meaning:
0065 
0066                 - bit 0: Video Capture node
0067                 - bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
0068                 - bit 4: Radio Receiver node
0069                 - bit 5: Software Defined Radio Receiver node
0070                 - bit 8: Video Output node
0071                 - bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both
0072                 - bit 12: Radio Transmitter node
0073                 - bit 16: Framebuffer for testing overlays
0074                 - bit 17: Metadata Capture node
0075                 - bit 18: Metadata Output node
0076                 - bit 19: Touch Capture node
0077 
0078         So to create four instances, the first two with just one video capture
0079         device, the second two with just one video output device you would pass
0080         these module options to vivid:
0081 
0082         .. code-block:: none
0083 
0084                 n_devs=4 node_types=0x1,0x1,0x100,0x100
0085 
0086 - num_inputs:
0087 
0088         the number of inputs, one for each instance. By default 4 inputs
0089         are created for each video capture device. At most 16 inputs can be created,
0090         and there must be at least one.
0091 
0092 - input_types:
0093 
0094         the input types for each instance, the default is 0xe4. This defines
0095         what the type of each input is when the inputs are created for each driver
0096         instance. This is a hexadecimal value with up to 16 pairs of bits, each
0097         pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1,
0098         30-31 map to input 15. Each pair of bits has the following meaning:
0099 
0100                 - 00: this is a webcam input
0101                 - 01: this is a TV tuner input
0102                 - 10: this is an S-Video input
0103                 - 11: this is an HDMI input
0104 
0105         So to create a video capture device with 8 inputs where input 0 is a TV
0106         tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you
0107         would use the following module options:
0108 
0109         .. code-block:: none
0110 
0111                 num_inputs=8 input_types=0xffa9
0112 
0113 - num_outputs:
0114 
0115         the number of outputs, one for each instance. By default 2 outputs
0116         are created for each video output device. At most 16 outputs can be
0117         created, and there must be at least one.
0118 
0119 - output_types:
0120 
0121         the output types for each instance, the default is 0x02. This defines
0122         what the type of each output is when the outputs are created for each
0123         driver instance. This is a hexadecimal value with up to 16 bits, each bit
0124         gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit
0125         15 maps to output 15. The meaning of each bit is as follows:
0126 
0127                 - 0: this is an S-Video output
0128                 - 1: this is an HDMI output
0129 
0130         So to create a video output device with 8 outputs where outputs 0-3 are
0131         S-Video outputs and outputs 4-7 are HDMI outputs you would use the
0132         following module options:
0133 
0134         .. code-block:: none
0135 
0136                 num_outputs=8 output_types=0xf0
0137 
0138 - vid_cap_nr:
0139 
0140         give the desired videoX start number for each video capture device.
0141         The default is -1 which will just take the first free number. This allows
0142         you to map capture video nodes to specific videoX device nodes. Example:
0143 
0144         .. code-block:: none
0145 
0146                 n_devs=4 vid_cap_nr=2,4,6,8
0147 
0148         This will attempt to assign /dev/video2 for the video capture device of
0149         the first vivid instance, video4 for the next up to video8 for the last
0150         instance. If it can't succeed, then it will just take the next free
0151         number.
0152 
0153 - vid_out_nr:
0154 
0155         give the desired videoX start number for each video output device.
0156         The default is -1 which will just take the first free number.
0157 
0158 - vbi_cap_nr:
0159 
0160         give the desired vbiX start number for each vbi capture device.
0161         The default is -1 which will just take the first free number.
0162 
0163 - vbi_out_nr:
0164 
0165         give the desired vbiX start number for each vbi output device.
0166         The default is -1 which will just take the first free number.
0167 
0168 - radio_rx_nr:
0169 
0170         give the desired radioX start number for each radio receiver device.
0171         The default is -1 which will just take the first free number.
0172 
0173 - radio_tx_nr:
0174 
0175         give the desired radioX start number for each radio transmitter
0176         device. The default is -1 which will just take the first free number.
0177 
0178 - sdr_cap_nr:
0179 
0180         give the desired swradioX start number for each SDR capture device.
0181         The default is -1 which will just take the first free number.
0182 
0183 - meta_cap_nr:
0184 
0185         give the desired videoX start number for each metadata capture device.
0186         The default is -1 which will just take the first free number.
0187 
0188 - meta_out_nr:
0189 
0190         give the desired videoX start number for each metadata output device.
0191         The default is -1 which will just take the first free number.
0192 
0193 - touch_cap_nr:
0194 
0195         give the desired v4l-touchX start number for each touch capture device.
0196         The default is -1 which will just take the first free number.
0197 
0198 - ccs_cap_mode:
0199 
0200         specify the allowed video capture crop/compose/scaling combination
0201         for each driver instance. Video capture devices can have any combination
0202         of cropping, composing and scaling capabilities and this will tell the
0203         vivid driver which of those is should emulate. By default the user can
0204         select this through controls.
0205 
0206         The value is either -1 (controlled by the user) or a set of three bits,
0207         each enabling (1) or disabling (0) one of the features:
0208 
0209         - bit 0:
0210 
0211                 Enable crop support. Cropping will take only part of the
0212                 incoming picture.
0213         - bit 1:
0214 
0215                 Enable compose support. Composing will copy the incoming
0216                 picture into a larger buffer.
0217 
0218         - bit 2:
0219 
0220                 Enable scaling support. Scaling can scale the incoming
0221                 picture. The scaler of the vivid driver can enlarge up
0222                 or down to four times the original size. The scaler is
0223                 very simple and low-quality. Simplicity and speed were
0224                 key, not quality.
0225 
0226         Note that this value is ignored by webcam inputs: those enumerate
0227         discrete framesizes and that is incompatible with cropping, composing
0228         or scaling.
0229 
0230 - ccs_out_mode:
0231 
0232         specify the allowed video output crop/compose/scaling combination
0233         for each driver instance. Video output devices can have any combination
0234         of cropping, composing and scaling capabilities and this will tell the
0235         vivid driver which of those is should emulate. By default the user can
0236         select this through controls.
0237 
0238         The value is either -1 (controlled by the user) or a set of three bits,
0239         each enabling (1) or disabling (0) one of the features:
0240 
0241         - bit 0:
0242 
0243                 Enable crop support. Cropping will take only part of the
0244                 outgoing buffer.
0245 
0246         - bit 1:
0247 
0248                 Enable compose support. Composing will copy the incoming
0249                 buffer into a larger picture frame.
0250 
0251         - bit 2:
0252 
0253                 Enable scaling support. Scaling can scale the incoming
0254                 buffer. The scaler of the vivid driver can enlarge up
0255                 or down to four times the original size. The scaler is
0256                 very simple and low-quality. Simplicity and speed were
0257                 key, not quality.
0258 
0259 - multiplanar:
0260 
0261         select whether each device instance supports multi-planar formats,
0262         and thus the V4L2 multi-planar API. By default device instances are
0263         single-planar.
0264 
0265         This module option can override that for each instance. Values are:
0266 
0267                 - 1: this is a single-planar instance.
0268                 - 2: this is a multi-planar instance.
0269 
0270 - vivid_debug:
0271 
0272         enable driver debugging info
0273 
0274 - no_error_inj:
0275 
0276         if set disable the error injecting controls. This option is
0277         needed in order to run a tool like v4l2-compliance. Tools like that
0278         exercise all controls including a control like 'Disconnect' which
0279         emulates a USB disconnect, making the device inaccessible and so
0280         all tests that v4l2-compliance is doing will fail afterwards.
0281 
0282         There may be other situations as well where you want to disable the
0283         error injection support of vivid. When this option is set, then the
0284         controls that select crop, compose and scale behavior are also
0285         removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the
0286         will default to enabling crop, compose and scaling.
0287 
0288 - allocators:
0289 
0290         memory allocator selection, default is 0. It specifies the way buffers
0291         will be allocated.
0292 
0293                 - 0: vmalloc
0294                 - 1: dma-contig
0295 
0296 - cache_hints:
0297 
0298         specifies if the device should set queues' user-space cache and memory
0299         consistency hint capability (V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS).
0300         The hints are valid only when using MMAP streaming I/O. Default is 0.
0301 
0302                 - 0: forbid hints
0303                 - 1: allow hints
0304 
0305 Taken together, all these module options allow you to precisely customize
0306 the driver behavior and test your application with all sorts of permutations.
0307 It is also very suitable to emulate hardware that is not yet available, e.g.
0308 when developing software for a new upcoming device.
0309 
0310 
0311 Video Capture
0312 -------------
0313 
0314 This is probably the most frequently used feature. The video capture device
0315 can be configured by using the module options num_inputs, input_types and
0316 ccs_cap_mode (see section 1 for more detailed information), but by default
0317 four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI
0318 input, one input for each input type. Those are described in more detail
0319 below.
0320 
0321 Special attention has been given to the rate at which new frames become
0322 available. The jitter will be around 1 jiffie (that depends on the HZ
0323 configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second),
0324 but the long-term behavior is exactly following the framerate. So a
0325 framerate of 59.94 Hz is really different from 60 Hz. If the framerate
0326 exceeds your kernel's HZ value, then you will get dropped frames, but the
0327 frame/field sequence counting will keep track of that so the sequence
0328 count will skip whenever frames are dropped.
0329 
0330 
0331 Webcam Input
0332 ~~~~~~~~~~~~
0333 
0334 The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It
0335 supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones
0336 are available depends on the chosen framesize: the larger the framesize, the
0337 lower the maximum frames per second.
0338 
0339 The initially selected colorspace when you switch to the webcam input will be
0340 sRGB.
0341 
0342 
0343 TV and S-Video Inputs
0344 ~~~~~~~~~~~~~~~~~~~~~
0345 
0346 The only difference between the TV and S-Video input is that the TV has a
0347 tuner. Otherwise they behave identically.
0348 
0349 These inputs support audio inputs as well: one TV and one Line-In. They
0350 both support all TV standards. If the standard is queried, then the Vivid
0351 controls 'Standard Signal Mode' and 'Standard' determine what
0352 the result will be.
0353 
0354 These inputs support all combinations of the field setting. Special care has
0355 been taken to faithfully reproduce how fields are handled for the different
0356 TV standards. This is particularly noticeable when generating a horizontally
0357 moving image so the temporal effect of using interlaced formats becomes clearly
0358 visible. For 50 Hz standards the top field is the oldest and the bottom field
0359 is the newest in time. For 60 Hz standards that is reversed: the bottom field
0360 is the oldest and the top field is the newest in time.
0361 
0362 When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
0363 contain the top field for 50 Hz standards and the bottom field for 60 Hz
0364 standards. This is what capture hardware does as well.
0365 
0366 Finally, for PAL/SECAM standards the first half of the top line contains noise.
0367 This simulates the Wide Screen Signal that is commonly placed there.
0368 
0369 The initially selected colorspace when you switch to the TV or S-Video input
0370 will be SMPTE-170M.
0371 
0372 The pixel aspect ratio will depend on the TV standard. The video aspect ratio
0373 can be selected through the 'Standard Aspect Ratio' Vivid control.
0374 Choices are '4x3', '16x9' which will give letterboxed widescreen video and
0375 '16x9 Anamorphic' which will give full screen squashed anamorphic widescreen
0376 video that will need to be scaled accordingly.
0377 
0378 The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available
0379 every 6 MHz, starting from 49.25 MHz. For each channel the generated image
0380 will be in color for the +/- 0.25 MHz around it, and in grayscale for
0381 +/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER
0382 ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz.
0383 It will also return correct afc values to show whether the frequency is too
0384 low or too high.
0385 
0386 The audio subchannels that are returned are MONO for the +/- 1 MHz range around
0387 a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
0388 channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or
0389 LANG1 | LANG2 (for others), or STEREO | SAP.
0390 
0391 Which one is returned depends on the chosen channel, each next valid channel
0392 will cycle through the possible audio subchannel combinations. This allows
0393 you to test the various combinations by just switching channels..
0394 
0395 Finally, for these inputs the v4l2_timecode struct is filled in in the
0396 dequeued v4l2_buffer struct.
0397 
0398 
0399 HDMI Input
0400 ~~~~~~~~~~
0401 
0402 The HDMI inputs supports all CEA-861 and DMT timings, both progressive and
0403 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
0404 mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the
0405 field order is always top field first, and when you start capturing an
0406 interlaced format you will receive the top field first.
0407 
0408 The initially selected colorspace when you switch to the HDMI input or
0409 select an HDMI timing is based on the format resolution: for resolutions
0410 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
0411 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
0412 
0413 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
0414 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
0415 standard, and for all others a 1:1 pixel aspect ratio is returned.
0416 
0417 The video aspect ratio can be selected through the 'DV Timings Aspect Ratio'
0418 Vivid control. Choices are 'Source Width x Height' (just use the
0419 same ratio as the chosen format), '4x3' or '16x9', either of which can
0420 result in pillarboxed or letterboxed video.
0421 
0422 For HDMI inputs it is possible to set the EDID. By default a simple EDID
0423 is provided. You can only set the EDID for HDMI inputs. Internally, however,
0424 the EDID is shared between all HDMI inputs.
0425 
0426 No interpretation is done of the EDID data with the exception of the
0427 physical address. See the CEC section for more details.
0428 
0429 There is a maximum of 15 HDMI inputs (if there are more, then they will be
0430 reduced to 15) since that's the limitation of the EDID physical address.
0431 
0432 
0433 Video Output
0434 ------------
0435 
0436 The video output device can be configured by using the module options
0437 num_outputs, output_types and ccs_out_mode (see section 1 for more detailed
0438 information), but by default two outputs are configured: an S-Video and an
0439 HDMI input, one output for each output type. Those are described in more detail
0440 below.
0441 
0442 Like with video capture the framerate is also exact in the long term.
0443 
0444 
0445 S-Video Output
0446 ~~~~~~~~~~~~~~
0447 
0448 This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2".
0449 The S-Video output supports all TV standards.
0450 
0451 This output supports all combinations of the field setting.
0452 
0453 The initially selected colorspace when you switch to the TV or S-Video input
0454 will be SMPTE-170M.
0455 
0456 
0457 HDMI Output
0458 ~~~~~~~~~~~
0459 
0460 The HDMI output supports all CEA-861 and DMT timings, both progressive and
0461 interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
0462 mode for interlaced formats is always V4L2_FIELD_ALTERNATE.
0463 
0464 The initially selected colorspace when you switch to the HDMI output or
0465 select an HDMI timing is based on the format resolution: for resolutions
0466 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
0467 others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
0468 
0469 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
0470 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
0471 standard, and for all others a 1:1 pixel aspect ratio is returned.
0472 
0473 An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID.
0474 
0475 There is a maximum of 15 HDMI outputs (if there are more, then they will be
0476 reduced to 15) since that's the limitation of the EDID physical address. See
0477 also the CEC section for more details.
0478 
0479 VBI Capture
0480 -----------
0481 
0482 There are three types of VBI capture devices: those that only support raw
0483 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
0484 support both. This is determined by the node_types module option. In all
0485 cases the driver will generate valid VBI data: for 60 Hz standards it will
0486 generate Closed Caption and XDS data. The closed caption stream will
0487 alternate between "Hello world!" and "Closed captions test" every second.
0488 The XDS stream will give the current time once a minute. For 50 Hz standards
0489 it will generate the Wide Screen Signal which is based on the actual Video
0490 Aspect Ratio control setting and teletext pages 100-159, one page per frame.
0491 
0492 The VBI device will only work for the S-Video and TV inputs, it will give
0493 back an error if the current input is a webcam or HDMI.
0494 
0495 
0496 VBI Output
0497 ----------
0498 
0499 There are three types of VBI output devices: those that only support raw
0500 (undecoded) VBI, those that only support sliced (decoded) VBI and those that
0501 support both. This is determined by the node_types module option.
0502 
0503 The sliced VBI output supports the Wide Screen Signal and the teletext signal
0504 for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards.
0505 
0506 The VBI device will only work for the S-Video output, it will give
0507 back an error if the current output is HDMI.
0508 
0509 
0510 Radio Receiver
0511 --------------
0512 
0513 The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS.
0514 The frequency ranges are:
0515 
0516         - FM: 64 MHz - 108 MHz
0517         - AM: 520 kHz - 1710 kHz
0518         - SW: 2300 kHz - 26.1 MHz
0519 
0520 Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW.
0521 The signal strength decreases the further the frequency is from the valid
0522 frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
0523 ideal frequency. The initial frequency when the driver is loaded is set to
0524 95 MHz.
0525 
0526 The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls'
0527 modes. In the 'Controls' mode the RDS information is stored in read-only
0528 controls. These controls are updated every time the frequency is changed,
0529 or when the tuner status is requested. The Block I/O method uses the read()
0530 interface to pass the RDS blocks on to the application for decoding.
0531 
0532 The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
0533 and the further the frequency is away from the valid frequency the more RDS
0534 errors are randomly introduced into the block I/O stream, up to 50% of all
0535 blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
0536 can occur in equal proportions: blocks marked 'CORRECTED', blocks marked
0537 'ERROR', blocks marked 'INVALID' and dropped blocks.
0538 
0539 The generated RDS stream contains all the standard fields contained in a
0540 0B group, and also radio text and the current time.
0541 
0542 The receiver supports HW frequency seek, either in Bounded mode, Wrap Around
0543 mode or both, which is configurable with the "Radio HW Seek Mode" control.
0544 
0545 
0546 Radio Transmitter
0547 -----------------
0548 
0549 The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS.
0550 The frequency ranges are:
0551 
0552         - FM: 64 MHz - 108 MHz
0553         - AM: 520 kHz - 1710 kHz
0554         - SW: 2300 kHz - 26.1 MHz
0555 
0556 The initial frequency when the driver is loaded is 95.5 MHz.
0557 
0558 The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls'
0559 modes. In the 'Controls' mode the transmitted RDS information is configured
0560 using controls, and in 'Block I/O' mode the blocks are passed to the driver
0561 using write().
0562 
0563 
0564 Software Defined Radio Receiver
0565 -------------------------------
0566 
0567 The SDR receiver has three frequency bands for the ADC tuner:
0568 
0569         - 300 kHz
0570         - 900 kHz - 2800 kHz
0571         - 3200 kHz
0572 
0573 The RF tuner supports 50 MHz - 2000 MHz.
0574 
0575 The generated data contains the In-phase and Quadrature components of a
0576 1 kHz tone that has an amplitude of sqrt(2).
0577 
0578 
0579 Metadata Capture
0580 ----------------
0581 
0582 The Metadata capture generates UVC format metadata. The PTS and SCR are
0583 transmitted based on the values set in vivid contols.
0584 
0585 The Metadata device will only work for the Webcam input, it will give
0586 back an error for all other inputs.
0587 
0588 
0589 Metadata Output
0590 ---------------
0591 
0592 The Metadata output can be used to set brightness, contrast, saturation and hue.
0593 
0594 The Metadata device will only work for the Webcam output, it will give
0595 back an error for all other outputs.
0596 
0597 
0598 Touch Capture
0599 -------------
0600 
0601 The Touch capture generates touch patterns simulating single tap, double tap,
0602 triple tap, move from left to right, zoom in, zoom out, palm press (simulating
0603 a large area being pressed on a touchpad), and simulating 16 simultaneous
0604 touch points.
0605 
0606 Controls
0607 --------
0608 
0609 Different devices support different controls. The sections below will describe
0610 each control and which devices support them.
0611 
0612 
0613 User Controls - Test Controls
0614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0615 
0616 The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and
0617 Integer Menu are controls that represent all possible control types. The Menu
0618 control and the Integer Menu control both have 'holes' in their menu list,
0619 meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called.
0620 Both menu controls also have a non-zero minimum control value.  These features
0621 allow you to check if your application can handle such things correctly.
0622 These controls are supported for every device type.
0623 
0624 
0625 User Controls - Video Capture
0626 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0627 
0628 The following controls are specific to video capture.
0629 
0630 The Brightness, Contrast, Saturation and Hue controls actually work and are
0631 standard. There is one special feature with the Brightness control: each
0632 video input has its own brightness value, so changing input will restore
0633 the brightness for that input. In addition, each video input uses a different
0634 brightness range (minimum and maximum control values). Switching inputs will
0635 cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set.
0636 This allows you to test controls that can change their range.
0637 
0638 The 'Gain, Automatic' and Gain controls can be used to test volatile controls:
0639 if 'Gain, Automatic' is set, then the Gain control is volatile and changes
0640 constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal
0641 control.
0642 
0643 The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
0644 image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid
0645 controls.
0646 
0647 The 'Alpha Component' control can be used to set the alpha component for
0648 formats containing an alpha channel.
0649 
0650 
0651 User Controls - Audio
0652 ~~~~~~~~~~~~~~~~~~~~~
0653 
0654 The following controls are specific to video capture and output and radio
0655 receivers and transmitters.
0656 
0657 The 'Volume' and 'Mute' audio controls are typical for such devices to
0658 control the volume and mute the audio. They don't actually do anything in
0659 the vivid driver.
0660 
0661 
0662 Vivid Controls
0663 ~~~~~~~~~~~~~~
0664 
0665 These vivid custom controls control the image generation, error injection, etc.
0666 
0667 
0668 Test Pattern Controls
0669 ^^^^^^^^^^^^^^^^^^^^^
0670 
0671 The Test Pattern Controls are all specific to video capture.
0672 
0673 - Test Pattern:
0674 
0675         selects which test pattern to use. Use the CSC Colorbar for
0676         testing colorspace conversions: the colors used in that test pattern
0677         map to valid colors in all colorspaces. The colorspace conversion
0678         is disabled for the other test patterns.
0679 
0680 - OSD Text Mode:
0681 
0682         selects whether the text superimposed on the
0683         test pattern should be shown, and if so, whether only counters should
0684         be displayed or the full text.
0685 
0686 - Horizontal Movement:
0687 
0688         selects whether the test pattern should
0689         move to the left or right and at what speed.
0690 
0691 - Vertical Movement:
0692 
0693         does the same for the vertical direction.
0694 
0695 - Show Border:
0696 
0697         show a two-pixel wide border at the edge of the actual image,
0698         excluding letter or pillarboxing.
0699 
0700 - Show Square:
0701 
0702         show a square in the middle of the image. If the image is
0703         displayed with the correct pixel and image aspect ratio corrections,
0704         then the width and height of the square on the monitor should be
0705         the same.
0706 
0707 - Insert SAV Code in Image:
0708 
0709         adds a SAV (Start of Active Video) code to the image.
0710         This can be used to check if such codes in the image are inadvertently
0711         interpreted instead of being ignored.
0712 
0713 - Insert EAV Code in Image:
0714 
0715         does the same for the EAV (End of Active Video) code.
0716 
0717 - Insert Video Guard Band
0718 
0719         adds 4 columns of pixels with the HDMI Video Guard Band code at the
0720         left hand side of the image. This only works with 3 or 4 byte RGB pixel
0721         formats. The RGB pixel value 0xab/0x55/0xab turns out to be equivalent
0722         to the HDMI Video Guard Band code that precedes each active video line
0723         (see section 5.2.2.1 in the HDMI 1.3 Specification). To test if a video
0724         receiver has correct HDMI Video Guard Band processing, enable this
0725         control and then move the image to the left hand side of the screen.
0726         That will result in video lines that start with multiple pixels that
0727         have the same value as the Video Guard Band that precedes them.
0728         Receivers that will just keep skipping Video Guard Band values will
0729         now fail and either loose sync or these video lines will shift.
0730 
0731 
0732 Capture Feature Selection Controls
0733 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0734 
0735 These controls are all specific to video capture.
0736 
0737 - Sensor Flipped Horizontally:
0738 
0739         the image is flipped horizontally and the
0740         V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where
0741         a sensor is for example mounted upside down.
0742 
0743 - Sensor Flipped Vertically:
0744 
0745         the image is flipped vertically and the
0746         V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where
0747         a sensor is for example mounted upside down.
0748 
0749 - Standard Aspect Ratio:
0750 
0751         selects if the image aspect ratio as used for the TV or
0752         S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may
0753         introduce letterboxing.
0754 
0755 - DV Timings Aspect Ratio:
0756 
0757         selects if the image aspect ratio as used for the HDMI
0758         input should be the same as the source width and height ratio, or if
0759         it should be 4x3 or 16x9. This may introduce letter or pillarboxing.
0760 
0761 - Timestamp Source:
0762 
0763         selects when the timestamp for each buffer is taken.
0764 
0765 - Colorspace:
0766 
0767         selects which colorspace should be used when generating the image.
0768         This only applies if the CSC Colorbar test pattern is selected,
0769         otherwise the test pattern will go through unconverted.
0770         This behavior is also what you want, since a 75% Colorbar
0771         should really have 75% signal intensity and should not be affected
0772         by colorspace conversions.
0773 
0774         Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE
0775         to be sent since it emulates a detected colorspace change.
0776 
0777 - Transfer Function:
0778 
0779         selects which colorspace transfer function should be used when
0780         generating an image. This only applies if the CSC Colorbar test pattern is
0781         selected, otherwise the test pattern will go through unconverted.
0782         This behavior is also what you want, since a 75% Colorbar
0783         should really have 75% signal intensity and should not be affected
0784         by colorspace conversions.
0785 
0786         Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE
0787         to be sent since it emulates a detected colorspace change.
0788 
0789 - Y'CbCr Encoding:
0790 
0791         selects which Y'CbCr encoding should be used when generating
0792         a Y'CbCr image. This only applies if the format is set to a Y'CbCr format
0793         as opposed to an RGB format.
0794 
0795         Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE
0796         to be sent since it emulates a detected colorspace change.
0797 
0798 - Quantization:
0799 
0800         selects which quantization should be used for the RGB or Y'CbCr
0801         encoding when generating the test pattern.
0802 
0803         Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
0804         to be sent since it emulates a detected colorspace change.
0805 
0806 - Limited RGB Range (16-235):
0807 
0808         selects if the RGB range of the HDMI source should
0809         be limited or full range. This combines with the Digital Video 'Rx RGB
0810         Quantization Range' control and can be used to test what happens if
0811         a source provides you with the wrong quantization range information.
0812         See the description of that control for more details.
0813 
0814 - Apply Alpha To Red Only:
0815 
0816         apply the alpha channel as set by the 'Alpha Component'
0817         user control to the red color of the test pattern only.
0818 
0819 - Enable Capture Cropping:
0820 
0821         enables crop support. This control is only present if
0822         the ccs_cap_mode module option is set to the default value of -1 and if
0823         the no_error_inj module option is set to 0 (the default).
0824 
0825 - Enable Capture Composing:
0826 
0827         enables composing support. This control is only
0828         present if the ccs_cap_mode module option is set to the default value of
0829         -1 and if the no_error_inj module option is set to 0 (the default).
0830 
0831 - Enable Capture Scaler:
0832 
0833         enables support for a scaler (maximum 4 times upscaling
0834         and downscaling). This control is only present if the ccs_cap_mode
0835         module option is set to the default value of -1 and if the no_error_inj
0836         module option is set to 0 (the default).
0837 
0838 - Maximum EDID Blocks:
0839 
0840         determines how many EDID blocks the driver supports.
0841         Note that the vivid driver does not actually interpret new EDID
0842         data, it just stores it. It allows for up to 256 EDID blocks
0843         which is the maximum supported by the standard.
0844 
0845 - Fill Percentage of Frame:
0846 
0847         can be used to draw only the top X percent
0848         of the image. Since each frame has to be drawn by the driver, this
0849         demands a lot of the CPU. For large resolutions this becomes
0850         problematic. By drawing only part of the image this CPU load can
0851         be reduced.
0852 
0853 
0854 Output Feature Selection Controls
0855 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0856 
0857 These controls are all specific to video output.
0858 
0859 - Enable Output Cropping:
0860 
0861         enables crop support. This control is only present if
0862         the ccs_out_mode module option is set to the default value of -1 and if
0863         the no_error_inj module option is set to 0 (the default).
0864 
0865 - Enable Output Composing:
0866 
0867         enables composing support. This control is only
0868         present if the ccs_out_mode module option is set to the default value of
0869         -1 and if the no_error_inj module option is set to 0 (the default).
0870 
0871 - Enable Output Scaler:
0872 
0873         enables support for a scaler (maximum 4 times upscaling
0874         and downscaling). This control is only present if the ccs_out_mode
0875         module option is set to the default value of -1 and if the no_error_inj
0876         module option is set to 0 (the default).
0877 
0878 
0879 Error Injection Controls
0880 ^^^^^^^^^^^^^^^^^^^^^^^^
0881 
0882 The following two controls are only valid for video and vbi capture.
0883 
0884 - Standard Signal Mode:
0885 
0886         selects the behavior of VIDIOC_QUERYSTD: what should it return?
0887 
0888         Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
0889         to be sent since it emulates a changed input condition (e.g. a cable
0890         was plugged in or out).
0891 
0892 - Standard:
0893 
0894         selects the standard that VIDIOC_QUERYSTD should return if the
0895         previous control is set to "Selected Standard".
0896 
0897         Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
0898         to be sent since it emulates a changed input standard.
0899 
0900 
0901 The following two controls are only valid for video capture.
0902 
0903 - DV Timings Signal Mode:
0904 
0905         selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what
0906         should it return?
0907 
0908         Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
0909         to be sent since it emulates a changed input condition (e.g. a cable
0910         was plugged in or out).
0911 
0912 - DV Timings:
0913 
0914         selects the timings the VIDIOC_QUERY_DV_TIMINGS should return
0915         if the previous control is set to "Selected DV Timings".
0916 
0917         Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
0918         to be sent since it emulates changed input timings.
0919 
0920 
0921 The following controls are only present if the no_error_inj module option
0922 is set to 0 (the default). These controls are valid for video and vbi
0923 capture and output streams and for the SDR capture device except for the
0924 Disconnect control which is valid for all devices.
0925 
0926 - Wrap Sequence Number:
0927 
0928         test what happens when you wrap the sequence number in
0929         struct v4l2_buffer around.
0930 
0931 - Wrap Timestamp:
0932 
0933         test what happens when you wrap the timestamp in struct
0934         v4l2_buffer around.
0935 
0936 - Percentage of Dropped Buffers:
0937 
0938         sets the percentage of buffers that
0939         are never returned by the driver (i.e., they are dropped).
0940 
0941 - Disconnect:
0942 
0943         emulates a USB disconnect. The device will act as if it has
0944         been disconnected. Only after all open filehandles to the device
0945         node have been closed will the device become 'connected' again.
0946 
0947 - Inject V4L2_BUF_FLAG_ERROR:
0948 
0949         when pressed, the next frame returned by
0950         the driver will have the error flag set (i.e. the frame is marked
0951         corrupt).
0952 
0953 - Inject VIDIOC_REQBUFS Error:
0954 
0955         when pressed, the next REQBUFS or CREATE_BUFS
0956         ioctl call will fail with an error. To be precise: the videobuf2
0957         queue_setup() op will return -EINVAL.
0958 
0959 - Inject VIDIOC_QBUF Error:
0960 
0961         when pressed, the next VIDIOC_QBUF or
0962         VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be
0963         precise: the videobuf2 buf_prepare() op will return -EINVAL.
0964 
0965 - Inject VIDIOC_STREAMON Error:
0966 
0967         when pressed, the next VIDIOC_STREAMON ioctl
0968         call will fail with an error. To be precise: the videobuf2
0969         start_streaming() op will return -EINVAL.
0970 
0971 - Inject Fatal Streaming Error:
0972 
0973         when pressed, the streaming core will be
0974         marked as having suffered a fatal error, the only way to recover
0975         from that is to stop streaming. To be precise: the videobuf2
0976         vb2_queue_error() function is called.
0977 
0978 
0979 VBI Raw Capture Controls
0980 ^^^^^^^^^^^^^^^^^^^^^^^^
0981 
0982 - Interlaced VBI Format:
0983 
0984         if set, then the raw VBI data will be interlaced instead
0985         of providing it grouped by field.
0986 
0987 
0988 Digital Video Controls
0989 ~~~~~~~~~~~~~~~~~~~~~~
0990 
0991 - Rx RGB Quantization Range:
0992 
0993         sets the RGB quantization detection of the HDMI
0994         input. This combines with the Vivid 'Limited RGB Range (16-235)'
0995         control and can be used to test what happens if a source provides
0996         you with the wrong quantization range information. This can be tested
0997         by selecting an HDMI input, setting this control to Full or Limited
0998         range and selecting the opposite in the 'Limited RGB Range (16-235)'
0999         control. The effect is easy to see if the 'Gray Ramp' test pattern
1000         is selected.
1001 
1002 - Tx RGB Quantization Range:
1003 
1004         sets the RGB quantization detection of the HDMI
1005         output. It is currently not used for anything in vivid, but most HDMI
1006         transmitters would typically have this control.
1007 
1008 - Transmit Mode:
1009 
1010         sets the transmit mode of the HDMI output to HDMI or DVI-D. This
1011         affects the reported colorspace since DVI_D outputs will always use
1012         sRGB.
1013 
1014 - Display Present:
1015 
1016         sets the presence of a "display" on the HDMI output. This affects
1017         the tx_edid_present, tx_hotplug and tx_rxsense controls.
1018 
1019 
1020 FM Radio Receiver Controls
1021 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1022 
1023 - RDS Reception:
1024 
1025         set if the RDS receiver should be enabled.
1026 
1027 - RDS Program Type:
1028 
1029 
1030 - RDS PS Name:
1031 
1032 
1033 - RDS Radio Text:
1034 
1035 
1036 - RDS Traffic Announcement:
1037 
1038 
1039 - RDS Traffic Program:
1040 
1041 
1042 - RDS Music:
1043 
1044         these are all read-only controls. If RDS Rx I/O Mode is set to
1045         "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set
1046         to "Controls", then these controls report the received RDS data.
1047 
1048 .. note::
1049         The vivid implementation of this is pretty basic: they are only
1050         updated when you set a new frequency or when you get the tuner status
1051         (VIDIOC_G_TUNER).
1052 
1053 - Radio HW Seek Mode:
1054 
1055         can be one of "Bounded", "Wrap Around" or "Both". This
1056         determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency
1057         range or wrap-around or if it is selectable by the user.
1058 
1059 - Radio Programmable HW Seek:
1060 
1061         if set, then the user can provide the lower and
1062         upper bound of the HW Seek. Otherwise the frequency range boundaries
1063         will be used.
1064 
1065 - Generate RBDS Instead of RDS:
1066 
1067         if set, then generate RBDS (the US variant of
1068         RDS) data instead of RDS (European-style RDS). This affects only the
1069         PICODE and PTY codes.
1070 
1071 - RDS Rx I/O Mode:
1072 
1073         this can be "Block I/O" where the RDS blocks have to be read()
1074         by the application, or "Controls" where the RDS data is provided by
1075         the RDS controls mentioned above.
1076 
1077 
1078 FM Radio Modulator Controls
1079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1080 
1081 - RDS Program ID:
1082 
1083 
1084 - RDS Program Type:
1085 
1086 
1087 - RDS PS Name:
1088 
1089 
1090 - RDS Radio Text:
1091 
1092 
1093 - RDS Stereo:
1094 
1095 
1096 - RDS Artificial Head:
1097 
1098 
1099 - RDS Compressed:
1100 
1101 
1102 - RDS Dynamic PTY:
1103 
1104 
1105 - RDS Traffic Announcement:
1106 
1107 
1108 - RDS Traffic Program:
1109 
1110 
1111 - RDS Music:
1112 
1113         these are all controls that set the RDS data that is transmitted by
1114         the FM modulator.
1115 
1116 - RDS Tx I/O Mode:
1117 
1118         this can be "Block I/O" where the application has to use write()
1119         to pass the RDS blocks to the driver, or "Controls" where the RDS data
1120         is Provided by the RDS controls mentioned above.
1121 
1122 Metadata Capture Controls
1123 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1124 
1125 - Generate PTS
1126 
1127         if set, then the generated metadata stream contains Presentation timestamp.
1128 
1129 - Generate SCR
1130 
1131         if set, then the generated metadata stream contains Source Clock information.
1132 
1133 Video, VBI and RDS Looping
1134 --------------------------
1135 
1136 The vivid driver supports looping of video output to video input, VBI output
1137 to VBI input and RDS output to RDS input. For video/VBI looping this emulates
1138 as if a cable was hooked up between the output and input connector. So video
1139 and VBI looping is only supported between S-Video and HDMI inputs and outputs.
1140 VBI is only valid for S-Video as it makes no sense for HDMI.
1141 
1142 Since radio is wireless this looping always happens if the radio receiver
1143 frequency is close to the radio transmitter frequency. In that case the radio
1144 transmitter will 'override' the emulated radio stations.
1145 
1146 Looping is currently supported only between devices created by the same
1147 vivid driver instance.
1148 
1149 
1150 Video and Sliced VBI looping
1151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1152 
1153 The way to enable video/VBI looping is currently fairly crude. A 'Loop Video'
1154 control is available in the "Vivid" control class of the video
1155 capture and VBI capture devices. When checked the video looping will be enabled.
1156 Once enabled any video S-Video or HDMI input will show a static test pattern
1157 until the video output has started. At that time the video output will be
1158 looped to the video input provided that:
1159 
1160 - the input type matches the output type. So the HDMI input cannot receive
1161   video from the S-Video output.
1162 
1163 - the video resolution of the video input must match that of the video output.
1164   So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz
1165   (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input.
1166 
1167 - the pixel formats must be identical on both sides. Otherwise the driver would
1168   have to do pixel format conversion as well, and that's taking things too far.
1169 
1170 - the field settings must be identical on both sides. Same reason as above:
1171   requiring the driver to convert from one field format to another complicated
1172   matters too much. This also prohibits capturing with 'Field Top' or 'Field
1173   Bottom' when the output video is set to 'Field Alternate'. This combination,
1174   while legal, became too complicated to support. Both sides have to be 'Field
1175   Alternate' for this to work. Also note that for this specific case the
1176   sequence and field counting in struct v4l2_buffer on the capture side may not
1177   be 100% accurate.
1178 
1179 - field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to
1180   implement this, it would mean a lot of work to get this right. Since these
1181   field values are rarely used the decision was made not to implement this for
1182   now.
1183 
1184 - on the input side the "Standard Signal Mode" for the S-Video input or the
1185   "DV Timings Signal Mode" for the HDMI input should be configured so that a
1186   valid signal is passed to the video input.
1187 
1188 The framerates do not have to match, although this might change in the future.
1189 
1190 By default you will see the OSD text superimposed on top of the looped video.
1191 This can be turned off by changing the "OSD Text Mode" control of the video
1192 capture device.
1193 
1194 For VBI looping to work all of the above must be valid and in addition the vbi
1195 output must be configured for sliced VBI. The VBI capture side can be configured
1196 for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats)
1197 and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped.
1198 
1199 
1200 Radio & RDS Looping
1201 ~~~~~~~~~~~~~~~~~~~
1202 
1203 As mentioned in section 6 the radio receiver emulates stations are regular
1204 frequency intervals. Depending on the frequency of the radio receiver a
1205 signal strength value is calculated (this is returned by VIDIOC_G_TUNER).
1206 However, it will also look at the frequency set by the radio transmitter and
1207 if that results in a higher signal strength than the settings of the radio
1208 transmitter will be used as if it was a valid station. This also includes
1209 the RDS data (if any) that the transmitter 'transmits'. This is received
1210 faithfully on the receiver side. Note that when the driver is loaded the
1211 frequencies of the radio receiver and transmitter are not identical, so
1212 initially no looping takes place.
1213 
1214 
1215 Cropping, Composing, Scaling
1216 ----------------------------
1217 
1218 This driver supports cropping, composing and scaling in any combination. Normally
1219 which features are supported can be selected through the Vivid controls,
1220 but it is also possible to hardcode it when the module is loaded through the
1221 ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of
1222 these module options.
1223 
1224 This allows you to test your application for all these variations.
1225 
1226 Note that the webcam input never supports cropping, composing or scaling. That
1227 only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
1228 webcams, including this virtual implementation, normally use
1229 VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports.
1230 And that does not combine with cropping, composing or scaling. This is
1231 primarily a limitation of the V4L2 API which is carefully reproduced here.
1232 
1233 The minimum and maximum resolutions that the scaler can achieve are 16x16 and
1234 (4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or
1235 less. So for a source resolution of 1280x720 the minimum the scaler can do is
1236 320x180 and the maximum is 5120x2880. You can play around with this using the
1237 qv4l2 test tool and you will see these dependencies.
1238 
1239 This driver also supports larger 'bytesperline' settings, something that
1240 VIDIOC_S_FMT allows but that few drivers implement.
1241 
1242 The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's
1243 designed for speed and simplicity, not quality.
1244 
1245 If the combination of crop, compose and scaling allows it, then it is possible
1246 to change crop and compose rectangles on the fly.
1247 
1248 
1249 Formats
1250 -------
1251 
1252 The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
1253 YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar
1254 formats.
1255 
1256 The alpha component can be set through the 'Alpha Component' User control
1257 for those formats that support it. If the 'Apply Alpha To Red Only' control
1258 is set, then the alpha component is only used for the color red and set to
1259 0 otherwise.
1260 
1261 The driver has to be configured to support the multiplanar formats. By default
1262 the driver instances are single-planar. This can be changed by setting the
1263 multiplanar module option, see section 1 for more details on that option.
1264 
1265 If the driver instance is using the multiplanar formats/API, then the first
1266 single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1267 will have a plane that has a non-zero data_offset of 128 bytes. It is rare for
1268 data_offset to be non-zero, so this is a useful feature for testing applications.
1269 
1270 Video output will also honor any data_offset that the application set.
1271 
1272 
1273 Capture Overlay
1274 ---------------
1275 
1276 Note: capture overlay support is implemented primarily to test the existing
1277 V4L2 capture overlay API. In practice few if any GPUs support such overlays
1278 anymore, and neither are they generally needed anymore since modern hardware
1279 is so much more capable. By setting flag 0x10000 in the node_types module
1280 option the vivid driver will create a simple framebuffer device that can be
1281 used for testing this API. Whether this API should be used for new drivers is
1282 questionable.
1283 
1284 This driver has support for a destructive capture overlay with bitmap clipping
1285 and list clipping (up to 16 rectangles) capabilities. Overlays are not
1286 supported for multiplanar formats. It also honors the struct v4l2_window field
1287 setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is
1288 FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay.
1289 
1290 The overlay only works if you are also capturing at that same time. This is a
1291 vivid limitation since it copies from a buffer to the overlay instead of
1292 filling the overlay directly. And if you are not capturing, then no buffers
1293 are available to fill.
1294 
1295 In addition, the pixelformat of the capture format and that of the framebuffer
1296 must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return
1297 an error.
1298 
1299 In order to really see what it going on you will need to create two vivid
1300 instances: the first with a framebuffer enabled. You configure the capture
1301 overlay of the second instance to use the framebuffer of the first, then
1302 you start capturing in the second instance. For the first instance you setup
1303 the output overlay for the video output, turn on video looping and capture
1304 to see the blended framebuffer overlay that's being written to by the second
1305 instance. This setup would require the following commands:
1306 
1307 .. code-block:: none
1308 
1309         $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1
1310         $ v4l2-ctl -d1 --find-fb
1311         /dev/fb1 is the framebuffer associated with base address 0x12800000
1312         $ sudo v4l2-ctl -d2 --set-fbuf fb=1
1313         $ v4l2-ctl -d1 --set-fbuf fb=1
1314         $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15'
1315         $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15'
1316         $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15'
1317         $ v4l2-ctl -d0 -i2
1318         $ v4l2-ctl -d2 -i2
1319         $ v4l2-ctl -d2 -c horizontal_movement=4
1320         $ v4l2-ctl -d1 --overlay=1
1321         $ v4l2-ctl -d1 -c loop_video=1
1322         $ v4l2-ctl -d2 --stream-mmap --overlay=1
1323 
1324 And from another console:
1325 
1326 .. code-block:: none
1327 
1328         $ v4l2-ctl -d1 --stream-out-mmap
1329 
1330 And yet another console:
1331 
1332 .. code-block:: none
1333 
1334         $ qv4l2
1335 
1336 and start streaming.
1337 
1338 As you can see, this is not for the faint of heart...
1339 
1340 
1341 Output Overlay
1342 --------------
1343 
1344 Note: output overlays are primarily implemented in order to test the existing
1345 V4L2 output overlay API. Whether this API should be used for new drivers is
1346 questionable.
1347 
1348 This driver has support for an output overlay and is capable of:
1349 
1350         - bitmap clipping,
1351         - list clipping (up to 16 rectangles)
1352         - chromakey
1353         - source chromakey
1354         - global alpha
1355         - local alpha
1356         - local inverse alpha
1357 
1358 Output overlays are not supported for multiplanar formats. In addition, the
1359 pixelformat of the capture format and that of the framebuffer must be the
1360 same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error.
1361 
1362 Output overlays only work if the driver has been configured to create a
1363 framebuffer by setting flag 0x10000 in the node_types module option. The
1364 created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and
1365 RGB 5:6:5.
1366 
1367 In order to see the effects of the various clipping, chromakeying or alpha
1368 processing capabilities you need to turn on video looping and see the results
1369 on the capture side. The use of the clipping, chromakeying or alpha processing
1370 capabilities will slow down the video loop considerably as a lot of checks have
1371 to be done per pixel.
1372 
1373 
1374 CEC (Consumer Electronics Control)
1375 ----------------------------------
1376 
1377 If there are HDMI inputs then a CEC adapter will be created that has
1378 the same number of input ports. This is the equivalent of e.g. a TV that
1379 has that number of inputs. Each HDMI output will also create a
1380 CEC adapter that is hooked up to the corresponding input port, or (if there
1381 are more outputs than inputs) is not hooked up at all. In other words,
1382 this is the equivalent of hooking up each output device to an input port of
1383 the TV. Any remaining output devices remain unconnected.
1384 
1385 The EDID that each output reads reports a unique CEC physical address that is
1386 based on the physical address of the EDID of the input. So if the EDID of the
1387 receiver has physical address A.B.0.0, then each output will see an EDID
1388 containing physical address A.B.C.0 where C is 1 to the number of inputs. If
1389 there are more outputs than inputs then the remaining outputs have a CEC adapter
1390 that is disabled and reports an invalid physical address.
1391 
1392 
1393 Some Future Improvements
1394 ------------------------
1395 
1396 Just as a reminder and in no particular order:
1397 
1398 - Add a virtual alsa driver to test audio
1399 - Add virtual sub-devices and media controller support
1400 - Some support for testing compressed video
1401 - Add support to loop raw VBI output to raw VBI input
1402 - Add support to loop teletext sliced VBI output to VBI input
1403 - Fix sequence/field numbering when looping of video with alternate fields
1404 - Add support for V4L2_CID_BG_COLOR for video outputs
1405 - Add ARGB888 overlay support: better testing of the alpha channel
1406 - Improve pixel aspect support in the tpg code by passing a real v4l2_fract
1407 - Use per-queue locks and/or per-device locks to improve throughput
1408 - Add support to loop from a specific output to a specific input across
1409   vivid instances
1410 - The SDR radio should use the same 'frequencies' for stations as the normal
1411   radio receiver, and give back noise if the frequency doesn't match up with
1412   a station frequency
1413 - Make a thread for the RDS generation, that would help in particular for the
1414   "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated
1415   in real-time.
1416 - Changing the EDID should cause hotplug detect emulation to happen.