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