Lines Matching refs:the
17 you can test the various features without requiring special hardware.
19 This document describes the features implemented by this driver:
24 - Support for the alpha color component
44 Section 1: Configuring the driver
80 Section 1: Configuring the driver
83 By default the driver will create a single instance that has a video capture
89 all configurable using the following module options:
96 Each value is a bitmask with the following meaning:
106 So to create four instances, the first two with just one video capture
107 device, the second two with just one video output device you would pass
112 num_inputs: the number of inputs, one for each instance. By default 4 inputs
116 input_types: the input types for each instance, the default is 0xe4. This defines
117 what the type of each input is when the inputs are created for each driver
119 pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1,
120 30-31 map to input 15. Each pair of bits has the following meaning:
129 would use the following module options:
133 num_outputs: the number of outputs, one for each instance. By default 2 outputs
137 output_types: the output types for each instance, the default is 0x02. This defines
138 what the type of each output is when the outputs are created for each
140 gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit
147 S-Video outputs and outputs 4-7 are HDMI outputs you would use the
152 vid_cap_nr: give the desired videoX start number for each video capture device.
153 The default is -1 which will just take the first free number. This allows
158 This will attempt to assign /dev/video2 for the video capture device of
159 the first vivid instance, video4 for the next up to video8 for the last
160 instance. If it can't succeed, then it will just take the next free
163 vid_out_nr: give the desired videoX start number for each video output device.
164 The default is -1 which will just take the first free number.
166 vbi_cap_nr: give the desired vbiX start number for each vbi capture device.
167 The default is -1 which will just take the first free number.
169 vbi_out_nr: give the desired vbiX start number for each vbi output device.
170 The default is -1 which will just take the first free number.
172 radio_rx_nr: give the desired radioX start number for each radio receiver device.
173 The default is -1 which will just take the first free number.
175 radio_tx_nr: give the desired radioX start number for each radio transmitter
176 device. The default is -1 which will just take the first free number.
178 sdr_cap_nr: give the desired swradioX start number for each SDR capture device.
179 The default is -1 which will just take the first free number.
181 ccs_cap_mode: specify the allowed video capture crop/compose/scaling combination
183 of cropping, composing and scaling capabilities and this will tell the
184 vivid driver which of those is should emulate. By default the user can
187 The value is either -1 (controlled by the user) or a set of three bits,
188 each enabling (1) or disabling (0) one of the features:
190 bit 0: Enable crop support. Cropping will take only part of the
192 bit 1: Enable compose support. Composing will copy the incoming
194 bit 2: Enable scaling support. Scaling can scale the incoming
195 picture. The scaler of the vivid driver can enlarge up
196 or down to four times the original size. The scaler is
204 ccs_out_mode: specify the allowed video output crop/compose/scaling combination
206 of cropping, composing and scaling capabilities and this will tell the
207 vivid driver which of those is should emulate. By default the user can
210 The value is either -1 (controlled by the user) or a set of three bits,
211 each enabling (1) or disabling (0) one of the features:
213 bit 0: Enable crop support. Cropping will take only part of the
215 bit 1: Enable compose support. Composing will copy the incoming
217 bit 2: Enable scaling support. Scaling can scale the incoming
218 buffer. The scaler of the vivid driver can enlarge up
219 or down to four times the original size. The scaler is
224 and thus the V4L2 multi-planar API. By default device instances are
234 no_error_inj: if set disable the error injecting controls. This option is
237 emulates a USB disconnect, making the device inaccessible and so
240 There may be other situations as well where you want to disable the
241 error injection support of vivid. When this option is set, then the
243 removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the
247 the driver behavior and test your application with all sorts of permutations.
255 This is probably the most frequently used feature. The video capture device
256 can be configured by using the module options num_inputs, input_types and
262 Special attention has been given to the rate at which new frames become
263 available. The jitter will be around 1 jiffie (that depends on the HZ
265 but the long-term behavior is exactly following the framerate. So a
266 framerate of 59.94 Hz is really different from 60 Hz. If the framerate
267 exceeds your kernel's HZ value, then you will get dropped frames, but the
268 frame/field sequence counting will keep track of that so the sequence
277 are available depends on the chosen framesize: the larger the framesize, the
278 lower the maximum frames per second.
280 The initially selected colorspace when you switch to the webcam input will be
287 The only difference between the TV and S-Video input is that the TV has a
291 both support all TV standards. If the standard is queried, then the Vivid
293 the result will be.
295 These inputs support all combinations of the field setting. Special care has
296 been taken to faithfully reproduce how fields are handled for the different
298 moving image so the temporal effect of using interlaced formats becomes clearly
299 visible. For 50 Hz standards the top field is the oldest and the bottom field
300 is the newest in time. For 60 Hz standards that is reversed: the bottom field
301 is the oldest and the top field is the newest in time.
303 When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
304 contain the top field for 50 Hz standards and the bottom field for 60 Hz
307 Finally, for PAL/SECAM standards the first half of the top line contains noise.
308 This simulates the Wide Screen Signal that is commonly placed there.
310 The initially selected colorspace when you switch to the TV or S-Video input
313 The pixel aspect ratio will depend on the TV standard. The video aspect ratio
314 can be selected through the 'Standard Aspect Ratio' Vivid control.
320 every 6 MHz, starting from 49.25 MHz. For each channel the generated image
321 will be in color for the +/- 0.25 MHz around it, and in grayscale for
322 +/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER
324 It will also return correct afc values to show whether the frequency is too
327 The audio subchannels that are returned are MONO for the +/- 1 MHz range around
328 a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
332 Which one is returned depends on the chosen channel, each next valid channel
333 will cycle through the possible audio subchannel combinations. This allows
334 you to test the various combinations by just switching channels..
336 Finally, for these inputs the v4l2_timecode struct is filled in in the
345 mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the
347 interlaced format you will receive the top field first.
349 The initially selected colorspace when you switch to the HDMI input or
350 select an HDMI timing is based on the format resolution: for resolutions
351 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
354 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
355 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
358 The video aspect ratio can be selected through the 'DV Timings Aspect Ratio'
359 Vivid control. Choices are 'Source Width x Height' (just use the
360 same ratio as the chosen format), '4x3' or '16x9', either of which can
363 For HDMI inputs it is possible to set the EDID. By default a simple EDID
364 is provided. You can only set the EDID for HDMI inputs. Internally, however,
365 the EDID is shared between all HDMI inputs.
367 No interpretation is done of the EDID data.
373 The video output device can be configured by using the module options
379 Like with video capture the framerate is also exact in the long term.
388 This output supports all combinations of the field setting.
390 The initially selected colorspace when you switch to the TV or S-Video input
401 The initially selected colorspace when you switch to the HDMI output or
402 select an HDMI timing is based on the format resolution: for resolutions
403 less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
406 The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
407 set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
418 support both. This is determined by the node_types module option. In all
419 cases the driver will generate valid VBI data: for 60 Hz standards it will
422 The XDS stream will give the current time once a minute. For 50 Hz standards
423 it will generate the Wide Screen Signal which is based on the actual Video
426 The VBI device will only work for the S-Video and TV inputs, it will give
427 back an error if the current input is a webcam or HDMI.
435 support both. This is determined by the node_types module option.
437 The sliced VBI output supports the Wide Screen Signal and the teletext signal
440 The VBI device will only work for the S-Video output, it will give
441 back an error if the current output is HDMI.
455 The signal strength decreases the further the frequency is from the valid
456 frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
457 ideal frequency. The initial frequency when the driver is loaded is set to
461 modes. In the 'Controls' mode the RDS information is stored in read-only
462 controls. These controls are updated every time the frequency is changed,
463 or when the tuner status is requested. The Block I/O method uses the read()
464 interface to pass the RDS blocks on to the application for decoding.
466 The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
467 and the further the frequency is away from the valid frequency the more RDS
468 errors are randomly introduced into the block I/O stream, up to 50% of all
469 blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
473 The generated RDS stream contains all the standard fields contained in a
474 0B group, and also radio text and the current time.
477 mode or both, which is configurable with the "Radio HW Seek Mode" control.
490 The initial frequency when the driver is loaded is 95.5 MHz.
493 modes. In the 'Controls' mode the transmitted RDS information is configured
494 using controls, and in 'Block I/O' mode the blocks are passed to the driver
501 The SDR receiver has three frequency bands for the ADC tuner:
509 The generated data contains the In-phase and Quadrature components of a
525 control and the Integer Menu control both have 'holes' in their menu list,
538 standard. There is one special feature with the Brightness control: each
540 the brightness for that input. In addition, each video input uses a different
542 cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set.
546 if 'Gain, Automatic' is set, then the Gain control is volatile and changes
547 constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal
550 The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
551 image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid
554 The 'Alpha Component' control can be used to set the alpha component for
565 control the volume and mute the audio. They don't actually do anything in
566 the vivid driver.
572 These vivid custom controls control the image generation, error injection, etc.
580 Test Pattern: selects which test pattern to use. Use the CSC Colorbar for
581 testing colorspace conversions: the colors used in that test pattern
583 is disabled for the other test patterns.
585 OSD Text Mode: selects whether the text superimposed on the
587 be displayed or the full text.
589 Horizontal Movement: selects whether the test pattern should
590 move to the left or right and at what speed.
592 Vertical Movement: does the same for the vertical direction.
594 Show Border: show a two-pixel wide border at the edge of the actual image,
597 Show Square: show a square in the middle of the image. If the image is
598 displayed with the correct pixel and image aspect ratio corrections,
599 then the width and height of the square on the monitor should be
600 the same.
602 Insert SAV Code in Image: adds a SAV (Start of Active Video) code to the image.
603 This can be used to check if such codes in the image are inadvertently
606 Insert EAV Code in Image: does the same for the EAV (End of Active Video) code.
614 Sensor Flipped Horizontally: the image is flipped horizontally and the
615 V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where
618 Sensor Flipped Vertically: the image is flipped vertically and the
619 V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where
622 Standard Aspect Ratio: selects if the image aspect ratio as used for the TV or
626 DV Timings Aspect Ratio: selects if the image aspect ratio as used for the HDMI
627 input should be the same as the source width and height ratio, or if
630 Timestamp Source: selects when the timestamp for each buffer is taken.
632 Colorspace: selects which colorspace should be used when generating the image.
633 This only applies if the CSC Colorbar test pattern is selected,
634 otherwise the test pattern will go through unconverted.
639 Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE
643 generating an image. This only applies if the CSC Colorbar test pattern is
644 selected, otherwise the test pattern will go through unconverted.
649 Changing the transfer function will result in the V4L2_EVENT_SOURCE_CHANGE
653 a Y'CbCr image. This only applies if the format is set to a Y'CbCr format
656 Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE
659 Quantization: selects which quantization should be used for the RGB or Y'CbCr
660 encoding when generating the test pattern.
662 Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
665 Limited RGB Range (16-235): selects if the RGB range of the HDMI source should
666 be limited or full range. This combines with the Digital Video 'Rx RGB
668 a source provides you with the wrong quantization range information.
669 See the description of that control for more details.
671 Apply Alpha To Red Only: apply the alpha channel as set by the 'Alpha Component'
672 user control to the red color of the test pattern only.
675 the ccs_cap_mode module option is set to the default value of -1 and if
676 the no_error_inj module option is set to 0 (the default).
679 present if the ccs_cap_mode module option is set to the default value of
680 -1 and if the no_error_inj module option is set to 0 (the default).
683 and downscaling). This control is only present if the ccs_cap_mode
684 module option is set to the default value of -1 and if the no_error_inj
685 module option is set to 0 (the default).
687 Maximum EDID Blocks: determines how many EDID blocks the driver supports.
688 Note that the vivid driver does not actually interpret new EDID
690 which is the maximum supported by the standard.
692 Fill Percentage of Frame: can be used to draw only the top X percent
693 of the image. Since each frame has to be drawn by the driver, this
694 demands a lot of the CPU. For large resolutions this becomes
695 problematic. By drawing only part of the image this CPU load can
705 the ccs_out_mode module option is set to the default value of -1 and if
706 the no_error_inj module option is set to 0 (the default).
709 present if the ccs_out_mode module option is set to the default value of
710 -1 and if the no_error_inj module option is set to 0 (the default).
713 and downscaling). This control is only present if the ccs_out_mode
714 module option is set to the default value of -1 and if the no_error_inj
715 module option is set to 0 (the default).
723 Standard Signal Mode: selects the behavior of VIDIOC_QUERYSTD: what should
726 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
730 Standard: selects the standard that VIDIOC_QUERYSTD should return if the
733 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
739 DV Timings Signal Mode: selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what
742 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
746 DV Timings: selects the timings the VIDIOC_QUERY_DV_TIMINGS should return
747 if the previous control is set to "Selected DV Timings".
749 Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE
753 The following controls are only present if the no_error_inj module option
754 is set to 0 (the default). These controls are valid for video and vbi
755 capture and output streams and for the SDR capture device except for the
758 Wrap Sequence Number: test what happens when you wrap the sequence number in
761 Wrap Timestamp: test what happens when you wrap the timestamp in struct
764 Percentage of Dropped Buffers: sets the percentage of buffers that
765 are never returned by the driver (i.e., they are dropped).
768 been disconnected. Only after all open filehandles to the device
769 node have been closed will the device become 'connected' again.
771 Inject V4L2_BUF_FLAG_ERROR: when pressed, the next frame returned by
772 the driver will have the error flag set (i.e. the frame is marked
775 Inject VIDIOC_REQBUFS Error: when pressed, the next REQBUFS or CREATE_BUFS
776 ioctl call will fail with an error. To be precise: the videobuf2
779 Inject VIDIOC_QBUF Error: when pressed, the next VIDIOC_QBUF or
781 precise: the videobuf2 buf_prepare() op will return -EINVAL.
783 Inject VIDIOC_STREAMON Error: when pressed, the next VIDIOC_STREAMON ioctl
784 call will fail with an error. To be precise: the videobuf2
787 Inject Fatal Streaming Error: when pressed, the streaming core will be
788 marked as having suffered a fatal error, the only way to recover
789 from that is to stop streaming. To be precise: the videobuf2
796 Interlaced VBI Format: if set, then the raw VBI data will be interlaced instead
803 Rx RGB Quantization Range: sets the RGB quantization detection of the HDMI
804 input. This combines with the Vivid 'Limited RGB Range (16-235)'
806 you with the wrong quantization range information. This can be tested
808 range and selecting the opposite in the 'Limited RGB Range (16-235)'
809 control. The effect is easy to see if the 'Gray Ramp' test pattern
812 Tx RGB Quantization Range: sets the RGB quantization detection of the HDMI
816 Transmit Mode: sets the transmit mode of the HDMI output to HDMI or DVI-D. This
817 affects the reported colorspace since DVI_D outputs will always use
824 RDS Reception: set if the RDS receiver should be enabled.
833 to "Controls", then these controls report the received RDS data. Note
834 that the vivid implementation of this is pretty basic: they are only
835 updated when you set a new frequency or when you get the tuner status
839 determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency
840 range or wrap-around or if it is selectable by the user.
842 Radio Programmable HW Seek: if set, then the user can provide the lower and
843 upper bound of the HW Seek. Otherwise the frequency range boundaries
846 Generate RBDS Instead of RDS: if set, then generate RBDS (the US variant of
847 RDS) data instead of RDS (European-style RDS). This affects only the
850 RDS Rx I/O Mode: this can be "Block I/O" where the RDS blocks have to be read()
851 by the application, or "Controls" where the RDS data is provided by
852 the RDS controls mentioned above.
868 RDS Music: these are all controls that set the RDS data that is transmitted by
869 the FM modulator.
871 RDS Tx I/O Mode: this can be "Block I/O" where the application has to use write()
872 to pass the RDS blocks to the driver, or "Controls" where the RDS data is
873 provided by the RDS controls mentioned above.
881 as if a cable was hooked up between the output and input connector. So video
885 Since radio is wireless this looping always happens if the radio receiver
886 frequency is close to the radio transmitter frequency. In that case the radio
887 transmitter will 'override' the emulated radio stations.
889 Looping is currently supported only between devices created by the same
897 control is available in the "Vivid" control class of the video
898 capture and VBI capture devices. When checked the video looping will be enabled.
900 until the video output has started. At that time the video output will be
901 looped to the video input provided that:
903 - the input type matches the output type. So the HDMI input cannot receive
904 video from the S-Video output.
906 - the video resolution of the video input must match that of the video output.
910 - the pixel formats must be identical on both sides. Otherwise the driver would
913 - the field settings must be identical on both sides. Same reason as above:
914 requiring the driver to convert from one field format to another complicated
916 Bottom' when the output video is set to 'Field Alternate'. This combination,
918 Alternate' for this to work. Also note that for this specific case the
919 sequence and field counting in struct v4l2_buffer on the capture side may not
924 field values are rarely used the decision was made not to implement this for
927 - on the input side the "Standard Signal Mode" for the S-Video input or the
928 "DV Timings Signal Mode" for the HDMI input should be configured so that a
929 valid signal is passed to the video input.
931 The framerates do not have to match, although this might change in the future.
933 By default you will see the OSD text superimposed on top of the looped video.
934 This can be turned off by changing the "OSD Text Mode" control of the video
937 For VBI looping to work all of the above must be valid and in addition the vbi
939 for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats)
946 As mentioned in section 6 the radio receiver emulates stations are regular
947 frequency intervals. Depending on the frequency of the radio receiver a
949 However, it will also look at the frequency set by the radio transmitter and
950 if that results in a higher signal strength than the settings of the radio
952 the RDS data (if any) that the transmitter 'transmits'. This is received
953 faithfully on the receiver side. Note that when the driver is loaded the
954 frequencies of the radio receiver and transmitter are not identical, so
962 which features are supported can be selected through the Vivid controls,
963 but it is also possible to hardcode it when the module is loaded through the
964 ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of
969 Note that the webcam input never supports cropping, composing or scaling. That
970 only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
974 primarily a limitation of the V4L2 API which is carefully reproduced here.
976 The minimum and maximum resolutions that the scaler can achieve are 16x16 and
978 less. So for a source resolution of 1280x720 the minimum the scaler can do is
979 320x180 and the maximum is 5120x2880. You can play around with this using the
985 The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's
988 If the combination of crop, compose and scaling allows it, then it is possible
989 to change crop and compose rectangles on the fly.
995 The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
999 The alpha component can be set through the 'Alpha Component' User control
1000 for those formats that support it. If the 'Apply Alpha To Red Only' control
1001 is set, then the alpha component is only used for the color red and set to
1004 The driver has to be configured to support the multiplanar formats. By default
1005 the driver instances are single-planar. This can be changed by setting the
1008 If the driver instance is using the multiplanar formats/API, then the first
1009 single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1013 Video output will also honor any data_offset that the application set.
1019 Note: capture overlay support is implemented primarily to test the existing
1022 is so much more capable. By setting flag 0x10000 in the node_types module
1023 option the vivid driver will create a simple framebuffer device that can be
1029 supported for multiplanar formats. It also honors the struct v4l2_window field
1030 setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is
1031 FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay.
1034 vivid limitation since it copies from a buffer to the overlay instead of
1035 filling the overlay directly. And if you are not capturing, then no buffers
1038 In addition, the pixelformat of the capture format and that of the framebuffer
1039 must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return
1043 instances: the first with a framebuffer enabled. You configure the capture
1044 overlay of the second instance to use the framebuffer of the first, then
1045 you start capturing in the second instance. For the first instance you setup
1046 the output overlay for the video output, turn on video looping and capture
1047 to see the blended framebuffer overlay that's being written to by the second
1048 instance. This setup would require the following commands:
1052 /dev/fb1 is the framebuffer associated with base address 0x12800000
1075 As you can see, this is not for the faint of heart...
1081 Note: output overlays are primarily implemented in order to test the existing
1095 Output overlays are not supported for multiplanar formats. In addition, the
1096 pixelformat of the capture format and that of the framebuffer must be the
1097 same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error.
1099 Output overlays only work if the driver has been configured to create a
1100 framebuffer by setting flag 0x10000 in the node_types module option. The
1104 In order to see the effects of the various clipping, chromakeying or alpha
1105 processing capabilities you need to turn on video looping and see the results
1106 on the capture side. The use of the clipping, chromakeying or alpha processing
1107 capabilities will slow down the video loop considerably as a lot of checks have
1123 - Add ARGB888 overlay support: better testing of the alpha channel
1126 - Improve pixel aspect support in the tpg code by passing a real v4l2_fract
1130 - The SDR radio should use the same 'frequencies' for stations as the normal
1131 radio receiver, and give back noise if the frequency doesn't match up with
1133 - Make a thread for the RDS generation, that would help in particular for the
1134 "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated