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