diff options
Diffstat (limited to 'Documentation/video4linux/vivid.txt')
| -rw-r--r-- | Documentation/video4linux/vivid.txt | 1135 |
1 files changed, 0 insertions, 1135 deletions
diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt deleted file mode 100644 index 8da5d2a57..000000000 --- a/Documentation/video4linux/vivid.txt +++ /dev/null @@ -1,1135 +0,0 @@ -vivid: Virtual Video Test Driver -================================ - -This driver emulates video4linux hardware of various types: video capture, video -output, vbi capture and output, radio receivers and transmitters and a software -defined radio receiver. In addition a simple framebuffer device is available for -testing capture and output overlays. - -Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs. - -Each input can be a webcam, TV capture device, S-Video capture device or an HDMI -capture device. Each output can be an S-Video output device or an HDMI output -device. - -These inputs and outputs act exactly as a real hardware device would behave. This -allows you to use this driver as a test input for application development, since -you can test the various features without requiring special hardware. - -This document describes the features implemented by this driver: - -- Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O. -- A large list of test patterns and variations thereof -- Working brightness, contrast, saturation and hue controls -- Support for the alpha color component -- Full colorspace support, including limited/full RGB range -- All possible control types are present -- Support for various pixel aspect ratios and video aspect ratios -- Error injection to test what happens if errors occur -- Supports crop/compose/scale in any combination for both input and output -- Can emulate up to 4K resolutions -- All Field settings are supported for testing interlaced capturing -- Supports all standard YUV and RGB formats, including two multiplanar YUV formats -- Raw and Sliced VBI capture and output support -- Radio receiver and transmitter support, including RDS support -- Software defined radio (SDR) support -- Capture and output overlay support - -These features will be described in more detail below. - - -Table of Contents ------------------ - -Section 1: Configuring the driver -Section 2: Video Capture -Section 2.1: Webcam Input -Section 2.2: TV and S-Video Inputs -Section 2.3: HDMI Input -Section 3: Video Output -Section 3.1: S-Video Output -Section 3.2: HDMI Output -Section 4: VBI Capture -Section 5: VBI Output -Section 6: Radio Receiver -Section 7: Radio Transmitter -Section 8: Software Defined Radio Receiver -Section 9: Controls -Section 9.1: User Controls - Test Controls -Section 9.2: User Controls - Video Capture -Section 9.3: User Controls - Audio -Section 9.4: Vivid Controls -Section 9.4.1: Test Pattern Controls -Section 9.4.2: Capture Feature Selection Controls -Section 9.4.3: Output Feature Selection Controls -Section 9.4.4: Error Injection Controls -Section 9.4.5: VBI Raw Capture Controls -Section 9.5: Digital Video Controls -Section 9.6: FM Radio Receiver Controls -Section 9.7: FM Radio Modulator -Section 10: Video, VBI and RDS Looping -Section 10.1: Video and Sliced VBI looping -Section 10.2: Radio & RDS Looping -Section 11: Cropping, Composing, Scaling -Section 12: Formats -Section 13: Capture Overlay -Section 14: Output Overlay -Section 15: Some Future Improvements - - -Section 1: Configuring the driver ---------------------------------- - -By default the driver will create a single instance that has a video capture -device with webcam, TV, S-Video and HDMI inputs, a video output device with -S-Video and HDMI outputs, one vbi capture device, one vbi output device, one -radio receiver device, one radio transmitter device and one SDR device. - -The number of instances, devices, video inputs and outputs and their types are -all configurable using the following module options: - -n_devs: number of driver instances to create. By default set to 1. Up to 64 - instances can be created. - -node_types: which devices should each driver instance create. An array of - hexadecimal values, one for each instance. The default is 0x1d3d. - Each value is a bitmask with the following meaning: - bit 0: Video Capture node - bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both - bit 4: Radio Receiver node - bit 5: Software Defined Radio Receiver node - bit 8: Video Output node - bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both - bit 12: Radio Transmitter node - bit 16: Framebuffer for testing overlays - - So to create four instances, the first two with just one video capture - device, the second two with just one video output device you would pass - these module options to vivid: - - n_devs=4 node_types=0x1,0x1,0x100,0x100 - -num_inputs: the number of inputs, one for each instance. By default 4 inputs - are created for each video capture device. At most 16 inputs can be created, - and there must be at least one. - -input_types: the input types for each instance, the default is 0xe4. This defines - what the type of each input is when the inputs are created for each driver - instance. This is a hexadecimal value with up to 16 pairs of bits, each - pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1, - 30-31 map to input 15. Each pair of bits has the following meaning: - - 00: this is a webcam input - 01: this is a TV tuner input - 10: this is an S-Video input - 11: this is an HDMI input - - So to create a video capture device with 8 inputs where input 0 is a TV - tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you - would use the following module options: - - num_inputs=8 input_types=0xffa9 - -num_outputs: the number of outputs, one for each instance. By default 2 outputs - are created for each video output device. At most 16 outputs can be - created, and there must be at least one. - -output_types: the output types for each instance, the default is 0x02. This defines - what the type of each output is when the outputs are created for each - driver instance. This is a hexadecimal value with up to 16 bits, each bit - gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit - 15 maps to output 15. The meaning of each bit is as follows: - - 0: this is an S-Video output - 1: this is an HDMI output - - So to create a video output device with 8 outputs where outputs 0-3 are - S-Video outputs and outputs 4-7 are HDMI outputs you would use the - following module options: - - num_outputs=8 output_types=0xf0 - -vid_cap_nr: give the desired videoX start number for each video capture device. - The default is -1 which will just take the first free number. This allows - you to map capture video nodes to specific videoX device nodes. Example: - - n_devs=4 vid_cap_nr=2,4,6,8 - - This will attempt to assign /dev/video2 for the video capture device of - the first vivid instance, video4 for the next up to video8 for the last - instance. If it can't succeed, then it will just take the next free - number. - -vid_out_nr: give the desired videoX start number for each video output device. - The default is -1 which will just take the first free number. - -vbi_cap_nr: give the desired vbiX start number for each vbi capture device. - The default is -1 which will just take the first free number. - -vbi_out_nr: give the desired vbiX start number for each vbi output device. - The default is -1 which will just take the first free number. - -radio_rx_nr: give the desired radioX start number for each radio receiver device. - The default is -1 which will just take the first free number. - -radio_tx_nr: give the desired radioX start number for each radio transmitter - device. The default is -1 which will just take the first free number. - -sdr_cap_nr: give the desired swradioX start number for each SDR capture device. - The default is -1 which will just take the first free number. - -ccs_cap_mode: specify the allowed video capture crop/compose/scaling combination - for each driver instance. Video capture devices can have any combination - of cropping, composing and scaling capabilities and this will tell the - vivid driver which of those is should emulate. By default the user can - select this through controls. - - The value is either -1 (controlled by the user) or a set of three bits, - each enabling (1) or disabling (0) one of the features: - - bit 0: Enable crop support. Cropping will take only part of the - incoming picture. - bit 1: Enable compose support. Composing will copy the incoming - picture into a larger buffer. - bit 2: Enable scaling support. Scaling can scale the incoming - picture. The scaler of the vivid driver can enlarge up - or down to four times the original size. The scaler is - very simple and low-quality. Simplicity and speed were - key, not quality. - - Note that this value is ignored by webcam inputs: those enumerate - discrete framesizes and that is incompatible with cropping, composing - or scaling. - -ccs_out_mode: specify the allowed video output crop/compose/scaling combination - for each driver instance. Video output devices can have any combination - of cropping, composing and scaling capabilities and this will tell the - vivid driver which of those is should emulate. By default the user can - select this through controls. - - The value is either -1 (controlled by the user) or a set of three bits, - each enabling (1) or disabling (0) one of the features: - - bit 0: Enable crop support. Cropping will take only part of the - outgoing buffer. - bit 1: Enable compose support. Composing will copy the incoming - buffer into a larger picture frame. - bit 2: Enable scaling support. Scaling can scale the incoming - buffer. The scaler of the vivid driver can enlarge up - or down to four times the original size. The scaler is - very simple and low-quality. Simplicity and speed were - key, not quality. - -multiplanar: select whether each device instance supports multi-planar formats, - and thus the V4L2 multi-planar API. By default device instances are - single-planar. - - This module option can override that for each instance. Values are: - - 1: this is a single-planar instance. - 2: this is a multi-planar instance. - -vivid_debug: enable driver debugging info - -no_error_inj: if set disable the error injecting controls. This option is - needed in order to run a tool like v4l2-compliance. Tools like that - exercise all controls including a control like 'Disconnect' which - emulates a USB disconnect, making the device inaccessible and so - all tests that v4l2-compliance is doing will fail afterwards. - - There may be other situations as well where you want to disable the - error injection support of vivid. When this option is set, then the - controls that select crop, compose and scale behavior are also - removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the - will default to enabling crop, compose and scaling. - -Taken together, all these module options allow you to precisely customize -the driver behavior and test your application with all sorts of permutations. -It is also very suitable to emulate hardware that is not yet available, e.g. -when developing software for a new upcoming device. - - -Section 2: Video Capture ------------------------- - -This is probably the most frequently used feature. The video capture device -can be configured by using the module options num_inputs, input_types and -ccs_cap_mode (see section 1 for more detailed information), but by default -four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI -input, one input for each input type. Those are described in more detail -below. - -Special attention has been given to the rate at which new frames become -available. The jitter will be around 1 jiffie (that depends on the HZ -configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second), -but the long-term behavior is exactly following the framerate. So a -framerate of 59.94 Hz is really different from 60 Hz. If the framerate -exceeds your kernel's HZ value, then you will get dropped frames, but the -frame/field sequence counting will keep track of that so the sequence -count will skip whenever frames are dropped. - - -Section 2.1: Webcam Input -------------------------- - -The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It -supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones -are available depends on the chosen framesize: the larger the framesize, the -lower the maximum frames per second. - -The initially selected colorspace when you switch to the webcam input will be -sRGB. - - -Section 2.2: TV and S-Video Inputs ----------------------------------- - -The only difference between the TV and S-Video input is that the TV has a -tuner. Otherwise they behave identically. - -These inputs support audio inputs as well: one TV and one Line-In. They -both support all TV standards. If the standard is queried, then the Vivid -controls 'Standard Signal Mode' and 'Standard' determine what -the result will be. - -These inputs support all combinations of the field setting. Special care has -been taken to faithfully reproduce how fields are handled for the different -TV standards. This is particularly noticeable when generating a horizontally -moving image so the temporal effect of using interlaced formats becomes clearly -visible. For 50 Hz standards the top field is the oldest and the bottom field -is the newest in time. For 60 Hz standards that is reversed: the bottom field -is the oldest and the top field is the newest in time. - -When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will -contain the top field for 50 Hz standards and the bottom field for 60 Hz -standards. This is what capture hardware does as well. - -Finally, for PAL/SECAM standards the first half of the top line contains noise. -This simulates the Wide Screen Signal that is commonly placed there. - -The initially selected colorspace when you switch to the TV or S-Video input -will be SMPTE-170M. - -The pixel aspect ratio will depend on the TV standard. The video aspect ratio -can be selected through the 'Standard Aspect Ratio' Vivid control. -Choices are '4x3', '16x9' which will give letterboxed widescreen video and -'16x9 Anamorphic' which will give full screen squashed anamorphic widescreen -video that will need to be scaled accordingly. - -The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available -every 6 MHz, starting from 49.25 MHz. For each channel the generated image -will be in color for the +/- 0.25 MHz around it, and in grayscale for -+/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER -ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz. -It will also return correct afc values to show whether the frequency is too -low or too high. - -The audio subchannels that are returned are MONO for the +/- 1 MHz range around -a valid channel frequency. When the frequency is within +/- 0.25 MHz of the -channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or -LANG1 | LANG2 (for others), or STEREO | SAP. - -Which one is returned depends on the chosen channel, each next valid channel -will cycle through the possible audio subchannel combinations. This allows -you to test the various combinations by just switching channels.. - -Finally, for these inputs the v4l2_timecode struct is filled in in the -dequeued v4l2_buffer struct. - - -Section 2.3: HDMI Input ------------------------ - -The HDMI inputs supports all CEA-861 and DMT timings, both progressive and -interlaced, for pixelclock frequencies between 25 and 600 MHz. The field -mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the -field order is always top field first, and when you start capturing an -interlaced format you will receive the top field first. - -The initially selected colorspace when you switch to the HDMI input or -select an HDMI timing is based on the format resolution: for resolutions -less than or equal to 720x576 the colorspace is set to SMPTE-170M, for -others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). - -The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it -set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV -standard, and for all others a 1:1 pixel aspect ratio is returned. - -The video aspect ratio can be selected through the 'DV Timings Aspect Ratio' -Vivid control. Choices are 'Source Width x Height' (just use the -same ratio as the chosen format), '4x3' or '16x9', either of which can -result in pillarboxed or letterboxed video. - -For HDMI inputs it is possible to set the EDID. By default a simple EDID -is provided. You can only set the EDID for HDMI inputs. Internally, however, -the EDID is shared between all HDMI inputs. - -No interpretation is done of the EDID data. - - -Section 3: Video Output ------------------------ - -The video output device can be configured by using the module options -num_outputs, output_types and ccs_out_mode (see section 1 for more detailed -information), but by default two outputs are configured: an S-Video and an -HDMI input, one output for each output type. Those are described in more detail -below. - -Like with video capture the framerate is also exact in the long term. - - -Section 3.1: S-Video Output ---------------------------- - -This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2". -The S-Video output supports all TV standards. - -This output supports all combinations of the field setting. - -The initially selected colorspace when you switch to the TV or S-Video input -will be SMPTE-170M. - - -Section 3.2: HDMI Output ------------------------- - -The HDMI output supports all CEA-861 and DMT timings, both progressive and -interlaced, for pixelclock frequencies between 25 and 600 MHz. The field -mode for interlaced formats is always V4L2_FIELD_ALTERNATE. - -The initially selected colorspace when you switch to the HDMI output or -select an HDMI timing is based on the format resolution: for resolutions -less than or equal to 720x576 the colorspace is set to SMPTE-170M, for -others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). - -The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it -set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV -standard, and for all others a 1:1 pixel aspect ratio is returned. - -An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. - - -Section 4: VBI Capture ----------------------- - -There are three types of VBI capture devices: those that only support raw -(undecoded) VBI, those that only support sliced (decoded) VBI and those that -support both. This is determined by the node_types module option. In all -cases the driver will generate valid VBI data: for 60 Hz standards it will -generate Closed Caption and XDS data. The closed caption stream will -alternate between "Hello world!" and "Closed captions test" every second. -The XDS stream will give the current time once a minute. For 50 Hz standards -it will generate the Wide Screen Signal which is based on the actual Video -Aspect Ratio control setting and teletext pages 100-159, one page per frame. - -The VBI device will only work for the S-Video and TV inputs, it will give -back an error if the current input is a webcam or HDMI. - - -Section 5: VBI Output ---------------------- - -There are three types of VBI output devices: those that only support raw -(undecoded) VBI, those that only support sliced (decoded) VBI and those that -support both. This is determined by the node_types module option. - -The sliced VBI output supports the Wide Screen Signal and the teletext signal -for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards. - -The VBI device will only work for the S-Video output, it will give -back an error if the current output is HDMI. - - -Section 6: Radio Receiver -------------------------- - -The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS. -The frequency ranges are: - - FM: 64 MHz - 108 MHz - AM: 520 kHz - 1710 kHz - SW: 2300 kHz - 26.1 MHz - -Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW. -The signal strength decreases the further the frequency is from the valid -frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the -ideal frequency. The initial frequency when the driver is loaded is set to -95 MHz. - -The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls' -modes. In the 'Controls' mode the RDS information is stored in read-only -controls. These controls are updated every time the frequency is changed, -or when the tuner status is requested. The Block I/O method uses the read() -interface to pass the RDS blocks on to the application for decoding. - -The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency, -and the further the frequency is away from the valid frequency the more RDS -errors are randomly introduced into the block I/O stream, up to 50% of all -blocks if you are +/- 12.5 kHz from the channel frequency. All four errors -can occur in equal proportions: blocks marked 'CORRECTED', blocks marked -'ERROR', blocks marked 'INVALID' and dropped blocks. - -The generated RDS stream contains all the standard fields contained in a -0B group, and also radio text and the current time. - -The receiver supports HW frequency seek, either in Bounded mode, Wrap Around -mode or both, which is configurable with the "Radio HW Seek Mode" control. - - -Section 7: Radio Transmitter ----------------------------- - -The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS. -The frequency ranges are: - - FM: 64 MHz - 108 MHz - AM: 520 kHz - 1710 kHz - SW: 2300 kHz - 26.1 MHz - -The initial frequency when the driver is loaded is 95.5 MHz. - -The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls' -modes. In the 'Controls' mode the transmitted RDS information is configured -using controls, and in 'Block I/O' mode the blocks are passed to the driver -using write(). - - -Section 8: Software Defined Radio Receiver ------------------------------------------- - -The SDR receiver has three frequency bands for the ADC tuner: - - - 300 kHz - - 900 kHz - 2800 kHz - - 3200 kHz - -The RF tuner supports 50 MHz - 2000 MHz. - -The generated data contains the In-phase and Quadrature components of a -1 kHz tone that has an amplitude of sqrt(2). - - -Section 9: Controls -------------------- - -Different devices support different controls. The sections below will describe -each control and which devices support them. - - -Section 9.1: User Controls - Test Controls ------------------------------------------- - -The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and -Integer Menu are controls that represent all possible control types. The Menu -control and the Integer Menu control both have 'holes' in their menu list, -meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called. -Both menu controls also have a non-zero minimum control value. These features -allow you to check if your application can handle such things correctly. -These controls are supported for every device type. - - -Section 9.2: User Controls - Video Capture ------------------------------------------- - -The following controls are specific to video capture. - -The Brightness, Contrast, Saturation and Hue controls actually work and are -standard. There is one special feature with the Brightness control: each -video input has its own brightness value, so changing input will restore -the brightness for that input. In addition, each video input uses a different -brightness range (minimum and maximum control values). Switching inputs will -cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set. -This allows you to test controls that can change their range. - -The 'Gain, Automatic' and Gain controls can be used to test volatile controls: -if 'Gain, Automatic' is set, then the Gain control is volatile and changes -constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal -control. - -The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the -image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid -controls. - -The 'Alpha Component' control can be used to set the alpha component for -formats containing an alpha channel. - - -Section 9.3: User Controls - Audio ----------------------------------- - -The following controls are specific to video capture and output and radio -receivers and transmitters. - -The 'Volume' and 'Mute' audio controls are typical for such devices to -control the volume and mute the audio. They don't actually do anything in -the vivid driver. - - -Section 9.4: Vivid Controls ---------------------------- - -These vivid custom controls control the image generation, error injection, etc. - - -Section 9.4.1: Test Pattern Controls ------------------------------------- - -The Test Pattern Controls are all specific to video capture. - -Test Pattern: selects which test pattern to use. Use the CSC Colorbar for - testing colorspace conversions: the colors used in that test pattern - map to valid colors in all colorspaces. The colorspace conversion - is disabled for the other test patterns. - -OSD Text Mode: selects whether the text superimposed on the - test pattern should be shown, and if so, whether only counters should - be displayed or the full text. - -Horizontal Movement: selects whether the test pattern should - move to the left or right and at what speed. - -Vertical Movement: does the same for the vertical direction. - -Show Border: show a two-pixel wide border at the edge of the actual image, - excluding letter or pillarboxing. - -Show Square: show a square in the middle of the image. If the image is - displayed with the correct pixel and image aspect ratio corrections, - then the width and height of the square on the monitor should be - the same. - -Insert SAV Code in Image: adds a SAV (Start of Active Video) code to the image. - This can be used to check if such codes in the image are inadvertently - interpreted instead of being ignored. - -Insert EAV Code in Image: does the same for the EAV (End of Active Video) code. - - -Section 9.4.2: Capture Feature Selection Controls -------------------------------------------------- - -These controls are all specific to video capture. - -Sensor Flipped Horizontally: the image is flipped horizontally and the - V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where - a sensor is for example mounted upside down. - -Sensor Flipped Vertically: the image is flipped vertically and the - V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where - a sensor is for example mounted upside down. - -Standard Aspect Ratio: selects if the image aspect ratio as used for the TV or - S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may - introduce letterboxing. - -DV Timings Aspect Ratio: selects if the image aspect ratio as used for the HDMI - input should be the same as the source width and height ratio, or if - it should be 4x3 or 16x9. This may introduce letter or pillarboxing. - -Timestamp Source: selects when the timestamp for each buffer is taken. - -Colorspace: selects which colorspace should be used when generating the image. - This only applies if the CSC Colorbar test pattern is selected, - otherwise the test pattern will go through unconverted. - This behavior is also what you want, since a 75% Colorbar - should really have 75% signal intensity and should not be affected - by colorspace conversions. - - Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a detected colorspace change. - -Transfer Function: selects which colorspace transfer function should be used when - generating an image. This only applies if the CSC Colorbar test pattern is - selected, otherwise the test pattern will go through unconverted. - This behavior is also what you want, since a 75% Colorbar - should really have 75% signal intensity and should not be affected - by colorspace conversions. - - Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a detected colorspace change. - -Y'CbCr Encoding: selects which Y'CbCr encoding should be used when generating - a Y'CbCr image. This only applies if the format is set to a Y'CbCr format - as opposed to an RGB format. - - Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a detected colorspace change. - -Quantization: selects which quantization should be used for the RGB or Y'CbCr - encoding when generating the test pattern. - - Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a detected colorspace change. - -Limited RGB Range (16-235): selects if the RGB range of the HDMI source should - be limited or full range. This combines with the Digital Video 'Rx RGB - Quantization Range' control and can be used to test what happens if - a source provides you with the wrong quantization range information. - See the description of that control for more details. - -Apply Alpha To Red Only: apply the alpha channel as set by the 'Alpha Component' - user control to the red color of the test pattern only. - -Enable Capture Cropping: enables crop support. This control is only present if - the ccs_cap_mode module option is set to the default value of -1 and if - the no_error_inj module option is set to 0 (the default). - -Enable Capture Composing: enables composing support. This control is only - present if the ccs_cap_mode module option is set to the default value of - -1 and if the no_error_inj module option is set to 0 (the default). - -Enable Capture Scaler: enables support for a scaler (maximum 4 times upscaling - and downscaling). This control is only present if the ccs_cap_mode - module option is set to the default value of -1 and if the no_error_inj - module option is set to 0 (the default). - -Maximum EDID Blocks: determines how many EDID blocks the driver supports. - Note that the vivid driver does not actually interpret new EDID - data, it just stores it. It allows for up to 256 EDID blocks - which is the maximum supported by the standard. - -Fill Percentage of Frame: can be used to draw only the top X percent - of the image. Since each frame has to be drawn by the driver, this - demands a lot of the CPU. For large resolutions this becomes - problematic. By drawing only part of the image this CPU load can - be reduced. - - -Section 9.4.3: Output Feature Selection Controls ------------------------------------------------- - -These controls are all specific to video output. - -Enable Output Cropping: enables crop support. This control is only present if - the ccs_out_mode module option is set to the default value of -1 and if - the no_error_inj module option is set to 0 (the default). - -Enable Output Composing: enables composing support. This control is only - present if the ccs_out_mode module option is set to the default value of - -1 and if the no_error_inj module option is set to 0 (the default). - -Enable Output Scaler: enables support for a scaler (maximum 4 times upscaling - and downscaling). This control is only present if the ccs_out_mode - module option is set to the default value of -1 and if the no_error_inj - module option is set to 0 (the default). - - -Section 9.4.4: Error Injection Controls ---------------------------------------- - -The following two controls are only valid for video and vbi capture. - -Standard Signal Mode: selects the behavior of VIDIOC_QUERYSTD: what should - it return? - - Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a changed input condition (e.g. a cable - was plugged in or out). - -Standard: selects the standard that VIDIOC_QUERYSTD should return if the - previous control is set to "Selected Standard". - - Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a changed input standard. - - -The following two controls are only valid for video capture. - -DV Timings Signal Mode: selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what - should it return? - - Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates a changed input condition (e.g. a cable - was plugged in or out). - -DV Timings: selects the timings the VIDIOC_QUERY_DV_TIMINGS should return - if the previous control is set to "Selected DV Timings". - - Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE - to be sent since it emulates changed input timings. - - -The following controls are only present if the no_error_inj module option -is set to 0 (the default). These controls are valid for video and vbi -capture and output streams and for the SDR capture device except for the -Disconnect control which is valid for all devices. - -Wrap Sequence Number: test what happens when you wrap the sequence number in - struct v4l2_buffer around. - -Wrap Timestamp: test what happens when you wrap the timestamp in struct - v4l2_buffer around. - -Percentage of Dropped Buffers: sets the percentage of buffers that - are never returned by the driver (i.e., they are dropped). - -Disconnect: emulates a USB disconnect. The device will act as if it has - been disconnected. Only after all open filehandles to the device - node have been closed will the device become 'connected' again. - -Inject V4L2_BUF_FLAG_ERROR: when pressed, the next frame returned by - the driver will have the error flag set (i.e. the frame is marked - corrupt). - -Inject VIDIOC_REQBUFS Error: when pressed, the next REQBUFS or CREATE_BUFS - ioctl call will fail with an error. To be precise: the videobuf2 - queue_setup() op will return -EINVAL. - -Inject VIDIOC_QBUF Error: when pressed, the next VIDIOC_QBUF or - VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be - precise: the videobuf2 buf_prepare() op will return -EINVAL. - -Inject VIDIOC_STREAMON Error: when pressed, the next VIDIOC_STREAMON ioctl - call will fail with an error. To be precise: the videobuf2 - start_streaming() op will return -EINVAL. - -Inject Fatal Streaming Error: when pressed, the streaming core will be - marked as having suffered a fatal error, the only way to recover - from that is to stop streaming. To be precise: the videobuf2 - vb2_queue_error() function is called. - - -Section 9.4.5: VBI Raw Capture Controls ---------------------------------------- - -Interlaced VBI Format: if set, then the raw VBI data will be interlaced instead - of providing it grouped by field. - - -Section 9.5: Digital Video Controls ------------------------------------ - -Rx RGB Quantization Range: sets the RGB quantization detection of the HDMI - input. This combines with the Vivid 'Limited RGB Range (16-235)' - control and can be used to test what happens if a source provides - you with the wrong quantization range information. This can be tested - by selecting an HDMI input, setting this control to Full or Limited - range and selecting the opposite in the 'Limited RGB Range (16-235)' - control. The effect is easy to see if the 'Gray Ramp' test pattern - is selected. - -Tx RGB Quantization Range: sets the RGB quantization detection of the HDMI - output. It is currently not used for anything in vivid, but most HDMI - transmitters would typically have this control. - -Transmit Mode: sets the transmit mode of the HDMI output to HDMI or DVI-D. This - affects the reported colorspace since DVI_D outputs will always use - sRGB. - - -Section 9.6: FM Radio Receiver Controls ---------------------------------------- - -RDS Reception: set if the RDS receiver should be enabled. - -RDS Program Type: -RDS PS Name: -RDS Radio Text: -RDS Traffic Announcement: -RDS Traffic Program: -RDS Music: these are all read-only controls. If RDS Rx I/O Mode is set to - "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set - to "Controls", then these controls report the received RDS data. Note - that the vivid implementation of this is pretty basic: they are only - updated when you set a new frequency or when you get the tuner status - (VIDIOC_G_TUNER). - -Radio HW Seek Mode: can be one of "Bounded", "Wrap Around" or "Both". This - determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency - range or wrap-around or if it is selectable by the user. - -Radio Programmable HW Seek: if set, then the user can provide the lower and - upper bound of the HW Seek. Otherwise the frequency range boundaries - will be used. - -Generate RBDS Instead of RDS: if set, then generate RBDS (the US variant of - RDS) data instead of RDS (European-style RDS). This affects only the - PICODE and PTY codes. - -RDS Rx I/O Mode: this can be "Block I/O" where the RDS blocks have to be read() - by the application, or "Controls" where the RDS data is provided by - the RDS controls mentioned above. - - -Section 9.7: FM Radio Modulator Controls ----------------------------------------- - -RDS Program ID: -RDS Program Type: -RDS PS Name: -RDS Radio Text: -RDS Stereo: -RDS Artificial Head: -RDS Compressed: -RDS Dynamic PTY: -RDS Traffic Announcement: -RDS Traffic Program: -RDS Music: these are all controls that set the RDS data that is transmitted by - the FM modulator. - -RDS Tx I/O Mode: this can be "Block I/O" where the application has to use write() - to pass the RDS blocks to the driver, or "Controls" where the RDS data is - provided by the RDS controls mentioned above. - - -Section 10: Video, VBI and RDS Looping --------------------------------------- - -The vivid driver supports looping of video output to video input, VBI output -to VBI input and RDS output to RDS input. For video/VBI looping this emulates -as if a cable was hooked up between the output and input connector. So video -and VBI looping is only supported between S-Video and HDMI inputs and outputs. -VBI is only valid for S-Video as it makes no sense for HDMI. - -Since radio is wireless this looping always happens if the radio receiver -frequency is close to the radio transmitter frequency. In that case the radio -transmitter will 'override' the emulated radio stations. - -Looping is currently supported only between devices created by the same -vivid driver instance. - - -Section 10.1: Video and Sliced VBI looping ------------------------------------------- - -The way to enable video/VBI looping is currently fairly crude. A 'Loop Video' -control is available in the "Vivid" control class of the video -capture and VBI capture devices. When checked the video looping will be enabled. -Once enabled any video S-Video or HDMI input will show a static test pattern -until the video output has started. At that time the video output will be -looped to the video input provided that: - -- the input type matches the output type. So the HDMI input cannot receive - video from the S-Video output. - -- the video resolution of the video input must match that of the video output. - So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz - (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input. - -- the pixel formats must be identical on both sides. Otherwise the driver would - have to do pixel format conversion as well, and that's taking things too far. - -- the field settings must be identical on both sides. Same reason as above: - requiring the driver to convert from one field format to another complicated - matters too much. This also prohibits capturing with 'Field Top' or 'Field - Bottom' when the output video is set to 'Field Alternate'. This combination, - while legal, became too complicated to support. Both sides have to be 'Field - Alternate' for this to work. Also note that for this specific case the - sequence and field counting in struct v4l2_buffer on the capture side may not - be 100% accurate. - -- field settings V4L2_FIELD_SEQ_TB/BT are not supported. While it is possible to - implement this, it would mean a lot of work to get this right. Since these - field values are rarely used the decision was made not to implement this for - now. - -- on the input side the "Standard Signal Mode" for the S-Video input or the - "DV Timings Signal Mode" for the HDMI input should be configured so that a - valid signal is passed to the video input. - -The framerates do not have to match, although this might change in the future. - -By default you will see the OSD text superimposed on top of the looped video. -This can be turned off by changing the "OSD Text Mode" control of the video -capture device. - -For VBI looping to work all of the above must be valid and in addition the vbi -output must be configured for sliced VBI. The VBI capture side can be configured -for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats) -and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped. - - -Section 10.2: Radio & RDS Looping ---------------------------------- - -As mentioned in section 6 the radio receiver emulates stations are regular -frequency intervals. Depending on the frequency of the radio receiver a -signal strength value is calculated (this is returned by VIDIOC_G_TUNER). -However, it will also look at the frequency set by the radio transmitter and -if that results in a higher signal strength than the settings of the radio -transmitter will be used as if it was a valid station. This also includes -the RDS data (if any) that the transmitter 'transmits'. This is received -faithfully on the receiver side. Note that when the driver is loaded the -frequencies of the radio receiver and transmitter are not identical, so -initially no looping takes place. - - -Section 11: Cropping, Composing, Scaling ----------------------------------------- - -This driver supports cropping, composing and scaling in any combination. Normally -which features are supported can be selected through the Vivid controls, -but it is also possible to hardcode it when the module is loaded through the -ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of -these module options. - -This allows you to test your application for all these variations. - -Note that the webcam input never supports cropping, composing or scaling. That -only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that -webcams, including this virtual implementation, normally use -VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports. -And that does not combine with cropping, composing or scaling. This is -primarily a limitation of the V4L2 API which is carefully reproduced here. - -The minimum and maximum resolutions that the scaler can achieve are 16x16 and -(4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or -less. So for a source resolution of 1280x720 the minimum the scaler can do is -320x180 and the maximum is 5120x2880. You can play around with this using the -qv4l2 test tool and you will see these dependencies. - -This driver also supports larger 'bytesperline' settings, something that -VIDIOC_S_FMT allows but that few drivers implement. - -The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's -designed for speed and simplicity, not quality. - -If the combination of crop, compose and scaling allows it, then it is possible -to change crop and compose rectangles on the fly. - - -Section 12: Formats -------------------- - -The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0 -YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar -formats. - -The alpha component can be set through the 'Alpha Component' User control -for those formats that support it. If the 'Apply Alpha To Red Only' control -is set, then the alpha component is only used for the color red and set to -0 otherwise. - -The driver has to be configured to support the multiplanar formats. By default -the driver instances are single-planar. This can be changed by setting the -multiplanar module option, see section 1 for more details on that option. - -If the driver instance is using the multiplanar formats/API, then the first -single planar format (YUYV) and the multiplanar NV16M and NV61M formats the -will have a plane that has a non-zero data_offset of 128 bytes. It is rare for -data_offset to be non-zero, so this is a useful feature for testing applications. - -Video output will also honor any data_offset that the application set. - - -Section 13: Capture Overlay ---------------------------- - -Note: capture overlay support is implemented primarily to test the existing -V4L2 capture overlay API. In practice few if any GPUs support such overlays -anymore, and neither are they generally needed anymore since modern hardware -is so much more capable. By setting flag 0x10000 in the node_types module -option the vivid driver will create a simple framebuffer device that can be -used for testing this API. Whether this API should be used for new drivers is -questionable. - -This driver has support for a destructive capture overlay with bitmap clipping -and list clipping (up to 16 rectangles) capabilities. Overlays are not -supported for multiplanar formats. It also honors the struct v4l2_window field -setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is -FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay. - -The overlay only works if you are also capturing at that same time. This is a -vivid limitation since it copies from a buffer to the overlay instead of -filling the overlay directly. And if you are not capturing, then no buffers -are available to fill. - -In addition, the pixelformat of the capture format and that of the framebuffer -must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return -an error. - -In order to really see what it going on you will need to create two vivid -instances: the first with a framebuffer enabled. You configure the capture -overlay of the second instance to use the framebuffer of the first, then -you start capturing in the second instance. For the first instance you setup -the output overlay for the video output, turn on video looping and capture -to see the blended framebuffer overlay that's being written to by the second -instance. This setup would require the following commands: - - $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1 - $ v4l2-ctl -d1 --find-fb - /dev/fb1 is the framebuffer associated with base address 0x12800000 - $ sudo v4l2-ctl -d2 --set-fbuf fb=1 - $ v4l2-ctl -d1 --set-fbuf fb=1 - $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15' - $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15' - $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15' - $ v4l2-ctl -d0 -i2 - $ v4l2-ctl -d2 -i2 - $ v4l2-ctl -d2 -c horizontal_movement=4 - $ v4l2-ctl -d1 --overlay=1 - $ v4l2-ctl -d1 -c loop_video=1 - $ v4l2-ctl -d2 --stream-mmap --overlay=1 - -And from another console: - - $ v4l2-ctl -d1 --stream-out-mmap - -And yet another console: - - $ qv4l2 - -and start streaming. - -As you can see, this is not for the faint of heart... - - -Section 14: Output Overlay --------------------------- - -Note: output overlays are primarily implemented in order to test the existing -V4L2 output overlay API. Whether this API should be used for new drivers is -questionable. - -This driver has support for an output overlay and is capable of: - - - bitmap clipping, - - list clipping (up to 16 rectangles) - - chromakey - - source chromakey - - global alpha - - local alpha - - local inverse alpha - -Output overlays are not supported for multiplanar formats. In addition, the -pixelformat of the capture format and that of the framebuffer must be the -same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error. - -Output overlays only work if the driver has been configured to create a -framebuffer by setting flag 0x10000 in the node_types module option. The -created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and -RGB 5:6:5. - -In order to see the effects of the various clipping, chromakeying or alpha -processing capabilities you need to turn on video looping and see the results -on the capture side. The use of the clipping, chromakeying or alpha processing -capabilities will slow down the video loop considerably as a lot of checks have -to be done per pixel. - - -Section 15: Some Future Improvements ------------------------------------- - -Just as a reminder and in no particular order: - -- Add a virtual alsa driver to test audio -- Add virtual sub-devices and media controller support -- Some support for testing compressed video -- Add support to loop raw VBI output to raw VBI input -- Add support to loop teletext sliced VBI output to VBI input -- Fix sequence/field numbering when looping of video with alternate fields -- Add support for V4L2_CID_BG_COLOR for video outputs -- Add ARGB888 overlay support: better testing of the alpha channel -- Add custom DV timings support -- Add support for V4L2_DV_FL_REDUCED_FPS -- Improve pixel aspect support in the tpg code by passing a real v4l2_fract -- Use per-queue locks and/or per-device locks to improve throughput -- Add support to loop from a specific output to a specific input across - vivid instances -- The SDR radio should use the same 'frequencies' for stations as the normal - radio receiver, and give back noise if the frequency doesn't match up with - a station frequency -- Make a thread for the RDS generation, that would help in particular for the - "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated - in real-time. |