About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / vivid.txt


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.

1	vivid: Virtual Video Test Driver
2	================================
3	
4	This driver emulates video4linux hardware of various types: video capture, video
5	output, vbi capture and output, radio receivers and transmitters and a software
6	defined radio receiver. In addition a simple framebuffer device is available for
7	testing capture and output overlays.
8	
9	Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs.
10	
11	Each input can be a webcam, TV capture device, S-Video capture device or an HDMI
12	capture device. Each output can be an S-Video output device or an HDMI output
13	device.
14	
15	These inputs and outputs act exactly as a real hardware device would behave. This
16	allows you to use this driver as a test input for application development, since
17	you can test the various features without requiring special hardware.
18	
19	This 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	
38	These features will be described in more detail below.
39	
40	
41	Table of Contents
42	-----------------
43	
44	Section 1: Configuring the driver
45	Section 2: Video Capture
46	Section 2.1: Webcam Input
47	Section 2.2: TV and S-Video Inputs
48	Section 2.3: HDMI Input
49	Section 3: Video Output
50	Section 3.1: S-Video Output
51	Section 3.2: HDMI Output
52	Section 4: VBI Capture
53	Section 5: VBI Output
54	Section 6: Radio Receiver
55	Section 7: Radio Transmitter
56	Section 8: Software Defined Radio Receiver
57	Section 9: Controls
58	Section 9.1: User Controls - Test Controls
59	Section 9.2: User Controls - Video Capture
60	Section 9.3: User Controls - Audio
61	Section 9.4: Vivid Controls
62	Section 9.4.1: Test Pattern Controls
63	Section 9.4.2: Capture Feature Selection Controls
64	Section 9.4.3: Output Feature Selection Controls
65	Section 9.4.4: Error Injection Controls
66	Section 9.4.5: VBI Raw Capture Controls
67	Section 9.5: Digital Video Controls
68	Section 9.6: FM Radio Receiver Controls
69	Section 9.7: FM Radio Modulator
70	Section 10: Video, VBI and RDS Looping
71	Section 10.1: Video and Sliced VBI looping
72	Section 10.2: Radio & RDS Looping
73	Section 11: Cropping, Composing, Scaling
74	Section 12: Formats
75	Section 13: Capture Overlay
76	Section 14: Output Overlay
77	Section 15: Some Future Improvements
78	
79	
80	Section 1: Configuring the driver
81	---------------------------------
82	
83	By default the driver will create a single instance that has a video capture
84	device with webcam, TV, S-Video and HDMI inputs, a video output device with
85	S-Video and HDMI outputs, one vbi capture device, one vbi output device, one
86	radio receiver device, one radio transmitter device and one SDR device.
87	
88	The number of instances, devices, video inputs and outputs and their types are
89	all configurable using the following module options:
90	
91	n_devs: number of driver instances to create. By default set to 1. Up to 64
92		instances can be created.
93	
94	node_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	
112	num_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	
116	input_types: the input types for each instance, the default is 0xe4. This defines
117		what the type of each input is when the inputs are created for each driver
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	
133	num_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	
137	output_types: the output types for each instance, the default is 0x02. This defines
138		what the type of each output is when the outputs are created for each
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	
152	vid_cap_nr: give the desired videoX start number for each video capture device.
153		The default is -1 which will just take the first free number. This allows
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	
163	vid_out_nr: give the desired videoX start number for each video output device.
164	        The default is -1 which will just take the first free number.
165	
166	vbi_cap_nr: give the desired vbiX start number for each vbi capture device.
167	        The default is -1 which will just take the first free number.
168	
169	vbi_out_nr: give the desired vbiX start number for each vbi output device.
170	        The default is -1 which will just take the first free number.
171	
172	radio_rx_nr: give the desired radioX start number for each radio receiver device.
173	        The default is -1 which will just take the first free number.
174	
175	radio_tx_nr: give the desired radioX start number for each radio transmitter
176		device. The default is -1 which will just take the first free number.
177	
178	sdr_cap_nr: give the desired swradioX start number for each SDR capture device.
179	        The default is -1 which will just take the first free number.
180	
181	ccs_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	
204	ccs_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	
223	multiplanar: select whether each device instance supports multi-planar formats,
224		and thus the V4L2 multi-planar API. By default device instances are
225		single-planar.
226	
227		This module option can override that for each instance. Values are:
228	
229			1: this is a single-planar instance.
230			2: this is a multi-planar instance.
231	
232	vivid_debug: enable driver debugging info
233	
234	no_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	
246	Taken together, all these module options allow you to precisely customize
247	the driver behavior and test your application with all sorts of permutations.
248	It is also very suitable to emulate hardware that is not yet available, e.g.
249	when developing software for a new upcoming device.
250	
251	
252	Section 2: Video Capture
253	------------------------
254	
255	This is probably the most frequently used feature. The video capture device
256	can be configured by using the module options num_inputs, input_types and
257	ccs_cap_mode (see section 1 for more detailed information), but by default
258	four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI
259	input, one input for each input type. Those are described in more detail
260	below.
261	
262	Special attention has been given to the rate at which new frames become
263	available. The jitter will be around 1 jiffie (that depends on the HZ
264	configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second),
265	but the long-term behavior is exactly following the framerate. So a
266	framerate of 59.94 Hz is really different from 60 Hz. If the framerate
267	exceeds your kernel's HZ value, then you will get dropped frames, but the
268	frame/field sequence counting will keep track of that so the sequence
269	count will skip whenever frames are dropped.
270	
271	
272	Section 2.1: Webcam Input
273	-------------------------
274	
275	The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It
276	supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones
277	are available depends on the chosen framesize: the larger the framesize, the
278	lower the maximum frames per second.
279	
280	The initially selected colorspace when you switch to the webcam input will be
281	sRGB.
282	
283	
284	Section 2.2: TV and S-Video Inputs
285	----------------------------------
286	
287	The only difference between the TV and S-Video input is that the TV has a
288	tuner. Otherwise they behave identically.
289	
290	These inputs support audio inputs as well: one TV and one Line-In. They
291	both support all TV standards. If the standard is queried, then the Vivid
292	controls 'Standard Signal Mode' and 'Standard' determine what
293	the result will be.
294	
295	These inputs support all combinations of the field setting. Special care has
296	been taken to faithfully reproduce how fields are handled for the different
297	TV standards. This is particularly noticeable when generating a horizontally
298	moving image so the temporal effect of using interlaced formats becomes clearly
299	visible. For 50 Hz standards the top field is the oldest and the bottom field
300	is the newest in time. For 60 Hz standards that is reversed: the bottom field
301	is the oldest and the top field is the newest in time.
302	
303	When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will
304	contain the top field for 50 Hz standards and the bottom field for 60 Hz
305	standards. This is what capture hardware does as well.
306	
307	Finally, for PAL/SECAM standards the first half of the top line contains noise.
308	This simulates the Wide Screen Signal that is commonly placed there.
309	
310	The initially selected colorspace when you switch to the TV or S-Video input
311	will be SMPTE-170M.
312	
313	The pixel aspect ratio will depend on the TV standard. The video aspect ratio
314	can be selected through the 'Standard Aspect Ratio' Vivid control.
315	Choices are '4x3', '16x9' which will give letterboxed widescreen video and
316	'16x9 Anamorphic' which will give full screen squashed anamorphic widescreen
317	video that will need to be scaled accordingly.
318	
319	The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available
320	every 6 MHz, starting from 49.25 MHz. For each channel the generated image
321	will be in color for the +/- 0.25 MHz around it, and in grayscale for
322	+/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER
323	ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz.
324	It will also return correct afc values to show whether the frequency is too
325	low or too high.
326	
327	The audio subchannels that are returned are MONO for the +/- 1 MHz range around
328	a valid channel frequency. When the frequency is within +/- 0.25 MHz of the
329	channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or
330	LANG1 | LANG2 (for others), or STEREO | SAP.
331	
332	Which one is returned depends on the chosen channel, each next valid channel
333	will cycle through the possible audio subchannel combinations. This allows
334	you to test the various combinations by just switching channels..
335	
336	Finally, for these inputs the v4l2_timecode struct is filled in in the
337	dequeued v4l2_buffer struct.
338	
339	
340	Section 2.3: HDMI Input
341	-----------------------
342	
343	The HDMI inputs supports all CEA-861 and DMT timings, both progressive and
344	interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
345	mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the
346	field order is always top field first, and when you start capturing an
347	interlaced format you will receive the top field first.
348	
349	The initially selected colorspace when you switch to the HDMI input or
350	select an HDMI timing is based on the format resolution: for resolutions
351	less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
352	others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
353	
354	The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
355	set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
356	standard, and for all others a 1:1 pixel aspect ratio is returned.
357	
358	The video aspect ratio can be selected through the 'DV Timings Aspect Ratio'
359	Vivid control. Choices are 'Source Width x Height' (just use the
360	same ratio as the chosen format), '4x3' or '16x9', either of which can
361	result in pillarboxed or letterboxed video.
362	
363	For HDMI inputs it is possible to set the EDID. By default a simple EDID
364	is provided. You can only set the EDID for HDMI inputs. Internally, however,
365	the EDID is shared between all HDMI inputs.
366	
367	No interpretation is done of the EDID data.
368	
369	
370	Section 3: Video Output
371	-----------------------
372	
373	The video output device can be configured by using the module options
374	num_outputs, output_types and ccs_out_mode (see section 1 for more detailed
375	information), but by default two outputs are configured: an S-Video and an
376	HDMI input, one output for each output type. Those are described in more detail
377	below.
378	
379	Like with video capture the framerate is also exact in the long term.
380	
381	
382	Section 3.1: S-Video Output
383	---------------------------
384	
385	This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2".
386	The S-Video output supports all TV standards.
387	
388	This output supports all combinations of the field setting.
389	
390	The initially selected colorspace when you switch to the TV or S-Video input
391	will be SMPTE-170M.
392	
393	
394	Section 3.2: HDMI Output
395	------------------------
396	
397	The HDMI output supports all CEA-861 and DMT timings, both progressive and
398	interlaced, for pixelclock frequencies between 25 and 600 MHz. The field
399	mode for interlaced formats is always V4L2_FIELD_ALTERNATE.
400	
401	The initially selected colorspace when you switch to the HDMI output or
402	select an HDMI timing is based on the format resolution: for resolutions
403	less than or equal to 720x576 the colorspace is set to SMPTE-170M, for
404	others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings).
405	
406	The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it
407	set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV
408	standard, and for all others a 1:1 pixel aspect ratio is returned.
409	
410	An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID.
411	
412	
413	Section 4: VBI Capture
414	----------------------
415	
416	There 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
418	support both. This is determined by the node_types module option. In all
419	cases the driver will generate valid VBI data: for 60 Hz standards it will
420	generate Closed Caption and XDS data. The closed caption stream will
421	alternate between "Hello world!" and "Closed captions test" every second.
422	The XDS stream will give the current time once a minute. For 50 Hz standards
423	it will generate the Wide Screen Signal which is based on the actual Video
424	Aspect Ratio control setting and teletext pages 100-159, one page per frame.
425	
426	The VBI device will only work for the S-Video and TV inputs, it will give
427	back an error if the current input is a webcam or HDMI.
428	
429	
430	Section 5: VBI Output
431	---------------------
432	
433	There 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
435	support both. This is determined by the node_types module option.
436	
437	The sliced VBI output supports the Wide Screen Signal and the teletext signal
438	for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards.
439	
440	The VBI device will only work for the S-Video output, it will give
441	back an error if the current output is HDMI.
442	
443	
444	Section 6: Radio Receiver
445	-------------------------
446	
447	The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS.
448	The frequency ranges are:
449	
450		FM: 64 MHz - 108 MHz
451		AM: 520 kHz - 1710 kHz
452		SW: 2300 kHz - 26.1 MHz
453	
454	Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW.
455	The signal strength decreases the further the frequency is from the valid
456	frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the
457	ideal frequency. The initial frequency when the driver is loaded is set to
458	95 MHz.
459	
460	The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls'
461	modes. In the 'Controls' mode the RDS information is stored in read-only
462	controls. These controls are updated every time the frequency is changed,
463	or when the tuner status is requested. The Block I/O method uses the read()
464	interface to pass the RDS blocks on to the application for decoding.
465	
466	The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency,
467	and the further the frequency is away from the valid frequency the more RDS
468	errors are randomly introduced into the block I/O stream, up to 50% of all
469	blocks if you are +/- 12.5 kHz from the channel frequency. All four errors
470	can occur in equal proportions: blocks marked 'CORRECTED', blocks marked
471	'ERROR', blocks marked 'INVALID' and dropped blocks.
472	
473	The generated RDS stream contains all the standard fields contained in a
474	0B group, and also radio text and the current time.
475	
476	The receiver supports HW frequency seek, either in Bounded mode, Wrap Around
477	mode or both, which is configurable with the "Radio HW Seek Mode" control.
478	
479	
480	Section 7: Radio Transmitter
481	----------------------------
482	
483	The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS.
484	The frequency ranges are:
485	
486		FM: 64 MHz - 108 MHz
487		AM: 520 kHz - 1710 kHz
488		SW: 2300 kHz - 26.1 MHz
489	
490	The initial frequency when the driver is loaded is 95.5 MHz.
491	
492	The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls'
493	modes. In the 'Controls' mode the transmitted RDS information is configured
494	using controls, and in 'Block I/O' mode the blocks are passed to the driver
495	using write().
496	
497	
498	Section 8: Software Defined Radio Receiver
499	------------------------------------------
500	
501	The SDR receiver has three frequency bands for the ADC tuner:
502	
503		- 300 kHz
504		- 900 kHz - 2800 kHz
505		- 3200 kHz
506	
507	The RF tuner supports 50 MHz - 2000 MHz.
508	
509	The generated data contains the In-phase and Quadrature components of a
510	1 kHz tone that has an amplitude of sqrt(2).
511	
512	
513	Section 9: Controls
514	-------------------
515	
516	Different devices support different controls. The sections below will describe
517	each control and which devices support them.
518	
519	
520	Section 9.1: User Controls - Test Controls
521	------------------------------------------
522	
523	The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and
524	Integer Menu are controls that represent all possible control types. The Menu
525	control and the Integer Menu control both have 'holes' in their menu list,
526	meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called.
527	Both menu controls also have a non-zero minimum control value.  These features
528	allow you to check if your application can handle such things correctly.
529	These controls are supported for every device type.
530	
531	
532	Section 9.2: User Controls - Video Capture
533	------------------------------------------
534	
535	The following controls are specific to video capture.
536	
537	The Brightness, Contrast, Saturation and Hue controls actually work and are
538	standard. There is one special feature with the Brightness control: each
539	video input has its own brightness value, so changing input will restore
540	the brightness for that input. In addition, each video input uses a different
541	brightness range (minimum and maximum control values). Switching inputs will
542	cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set.
543	This allows you to test controls that can change their range.
544	
545	The 'Gain, Automatic' and Gain controls can be used to test volatile controls:
546	if 'Gain, Automatic' is set, then the Gain control is volatile and changes
547	constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal
548	control.
549	
550	The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the
551	image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid
552	controls.
553	
554	The 'Alpha Component' control can be used to set the alpha component for
555	formats containing an alpha channel.
556	
557	
558	Section 9.3: User Controls - Audio
559	----------------------------------
560	
561	The following controls are specific to video capture and output and radio
562	receivers and transmitters.
563	
564	The 'Volume' and 'Mute' audio controls are typical for such devices to
565	control the volume and mute the audio. They don't actually do anything in
566	the vivid driver.
567	
568	
569	Section 9.4: Vivid Controls
570	---------------------------
571	
572	These vivid custom controls control the image generation, error injection, etc.
573	
574	
575	Section 9.4.1: Test Pattern Controls
576	------------------------------------
577	
578	The Test Pattern Controls are all specific to video capture.
579	
580	Test Pattern: selects which test pattern to use. Use the CSC Colorbar for
581		testing colorspace conversions: the colors used in that test pattern
582		map to valid colors in all colorspaces. The colorspace conversion
583		is disabled for the other test patterns.
584	
585	OSD 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	
589	Horizontal Movement: selects whether the test pattern should
590		move to the left or right and at what speed.
591	
592	Vertical Movement: does the same for the vertical direction.
593	
594	Show Border: show a two-pixel wide border at the edge of the actual image,
595		excluding letter or pillarboxing.
596	
597	Show Square: show a square in the middle of the image. If the image is
598		displayed with the correct pixel and image aspect ratio corrections,
599		then the width and height of the square on the monitor should be
600		the same.
601	
602	Insert SAV Code in Image: adds a SAV (Start of Active Video) code to the image.
603		This can be used to check if such codes in the image are inadvertently
604		interpreted instead of being ignored.
605	
606	Insert EAV Code in Image: does the same for the EAV (End of Active Video) code.
607	
608	
609	Section 9.4.2: Capture Feature Selection Controls
610	-------------------------------------------------
611	
612	These controls are all specific to video capture.
613	
614	Sensor Flipped Horizontally: the image is flipped horizontally and the
615		V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where
616		a sensor is for example mounted upside down.
617	
618	Sensor Flipped Vertically: the image is flipped vertically and the
619		V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where
620	        a sensor is for example mounted upside down.
621	
622	Standard 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	
626	DV Timings Aspect Ratio: selects if the image aspect ratio as used for the HDMI
627		input should be the same as the source width and height ratio, or if
628		it should be 4x3 or 16x9. This may introduce letter or pillarboxing.
629	
630	Timestamp Source: selects when the timestamp for each buffer is taken.
631	
632	Colorspace: selects which colorspace should be used when generating the image.
633		This only applies if the CSC Colorbar test pattern is selected,
634		otherwise the test pattern will go through unconverted.
635		This behavior is also what you want, since a 75% Colorbar
636		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	
642	Transfer 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	
652	Y'CbCr Encoding: selects which Y'CbCr encoding should be used when generating
653		a Y'CbCr image.	This only applies if the format is set to a Y'CbCr format
654		as opposed to an RGB format.
655	
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	
659	Quantization: selects which quantization should be used for the RGB or Y'CbCr
660		encoding when generating the test pattern.
661	
662		Changing the quantization will result in the V4L2_EVENT_SOURCE_CHANGE
663		to be sent since it emulates a detected colorspace change.
664	
665	Limited RGB Range (16-235): selects if the RGB range of the HDMI source should
666		be limited or full range. This combines with the Digital Video 'Rx RGB
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	
671	Apply Alpha To Red Only: apply the alpha channel as set by the 'Alpha Component'
672		user control to the red color of the test pattern only.
673	
674	Enable 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	
678	Enable 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	
682	Enable 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	
687	Maximum 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	
692	Fill Percentage of Frame: can be used to draw only the top X percent
693		of the image. Since each frame has to be drawn by the driver, this
694		demands a lot of the CPU. For large resolutions this becomes
695		problematic. By drawing only part of the image this CPU load can
696		be reduced.
697	
698	
699	Section 9.4.3: Output Feature Selection Controls
700	------------------------------------------------
701	
702	These controls are all specific to video output.
703	
704	Enable 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	
708	Enable 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	
712	Enable 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	
718	Section 9.4.4: Error Injection Controls
719	---------------------------------------
720	
721	The following two controls are only valid for video and vbi capture.
722	
723	Standard 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	
730	Standard: 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	
737	The following two controls are only valid for video capture.
738	
739	DV 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	
746	DV 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	
753	The following controls are only present if the no_error_inj module option
754	is set to 0 (the default). These controls are valid for video and vbi
755	capture and output streams and for the SDR capture device except for the
756	Disconnect control which is valid for all devices.
757	
758	Wrap Sequence Number: test what happens when you wrap the sequence number in
759		struct v4l2_buffer around.
760	
761	Wrap Timestamp: test what happens when you wrap the timestamp in struct
762		v4l2_buffer around.
763	
764	Percentage of Dropped Buffers: sets the percentage of buffers that
765		are never returned by the driver (i.e., they are dropped).
766	
767	Disconnect: 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	
771	Inject V4L2_BUF_FLAG_ERROR: when pressed, the next frame returned by
772		the driver will have the error flag set (i.e. the frame is marked
773		corrupt).
774	
775	Inject VIDIOC_REQBUFS Error: when pressed, the next REQBUFS or CREATE_BUFS
776		ioctl call will fail with an error. To be precise: the videobuf2
777		queue_setup() op will return -EINVAL.
778	
779	Inject 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	
783	Inject 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	
787	Inject Fatal Streaming Error: when pressed, the streaming core will be
788		marked as having suffered a fatal error, the only way to recover
789		from that is to stop streaming. To be precise: the videobuf2
790		vb2_queue_error() function is called.
791	
792	
793	Section 9.4.5: VBI Raw Capture Controls
794	---------------------------------------
795	
796	Interlaced VBI Format: if set, then the raw VBI data will be interlaced instead
797		of providing it grouped by field.
798	
799	
800	Section 9.5: Digital Video Controls
801	-----------------------------------
802	
803	Rx RGB Quantization Range: sets the RGB quantization detection of the HDMI
804		input. This combines with the Vivid 'Limited RGB Range (16-235)'
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	
812	Tx 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	
816	Transmit Mode: sets the transmit mode of the HDMI output to HDMI or DVI-D. This
817		affects the reported colorspace since DVI_D outputs will always use
818		sRGB.
819	
820	
821	Section 9.6: FM Radio Receiver Controls
822	---------------------------------------
823	
824	RDS Reception: set if the RDS receiver should be enabled.
825	
826	RDS Program Type:
827	RDS PS Name:
828	RDS Radio Text:
829	RDS Traffic Announcement:
830	RDS Traffic Program:
831	RDS 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	
838	Radio 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	
842	Radio Programmable HW Seek: if set, then the user can provide the lower and
843		upper bound of the HW Seek. Otherwise the frequency range boundaries
844		will be used.
845	
846	Generate RBDS Instead of RDS: if set, then generate RBDS (the US variant of
847		RDS) data instead of RDS (European-style RDS). This affects only the
848		PICODE and PTY codes.
849	
850	RDS Rx I/O Mode: this can be "Block I/O" where the RDS blocks have to be read()
851		by the application, or "Controls" where the RDS data is provided by
852		the RDS controls mentioned above.
853	
854	
855	Section 9.7: FM Radio Modulator Controls
856	----------------------------------------
857	
858	RDS Program ID:
859	RDS Program Type:
860	RDS PS Name:
861	RDS Radio Text:
862	RDS Stereo:
863	RDS Artificial Head:
864	RDS Compressed:
865	RDS Dynamic PTY:
866	RDS Traffic Announcement:
867	RDS Traffic Program:
868	RDS Music: these are all controls that set the RDS data that is transmitted by
869		the FM modulator.
870	
871	RDS Tx I/O Mode: this can be "Block I/O" where the application has to use write()
872		to pass the RDS blocks to the driver, or "Controls" where the RDS data is
873		provided by the RDS controls mentioned above.
874	
875	
876	Section 10: Video, VBI and RDS Looping
877	--------------------------------------
878	
879	The vivid driver supports looping of video output to video input, VBI output
880	to VBI input and RDS output to RDS input. For video/VBI looping this emulates
881	as if a cable was hooked up between the output and input connector. So video
882	and VBI looping is only supported between S-Video and HDMI inputs and outputs.
883	VBI is only valid for S-Video as it makes no sense for HDMI.
884	
885	Since radio is wireless this looping always happens if the radio receiver
886	frequency is close to the radio transmitter frequency. In that case the radio
887	transmitter will 'override' the emulated radio stations.
888	
889	Looping is currently supported only between devices created by the same
890	vivid driver instance.
891	
892	
893	Section 10.1: Video and Sliced VBI looping
894	------------------------------------------
895	
896	The way to enable video/VBI looping is currently fairly crude. A 'Loop Video'
897	control is available in the "Vivid" control class of the video
898	capture and VBI capture devices. When checked the video looping will be enabled.
899	Once enabled any video S-Video or HDMI input will show a static test pattern
900	until the video output has started. At that time the video output will be
901	looped 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	
922	- 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	
927	- on the input side the "Standard Signal Mode" for the S-Video input or the
928	  "DV Timings Signal Mode" for the HDMI input should be configured so that a
929	  valid signal is passed to the video input.
930	
931	The framerates do not have to match, although this might change in the future.
932	
933	By default you will see the OSD text superimposed on top of the looped video.
934	This can be turned off by changing the "OSD Text Mode" control of the video
935	capture device.
936	
937	For VBI looping to work all of the above must be valid and in addition the vbi
938	output must be configured for sliced VBI. The VBI capture side can be configured
939	for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats)
940	and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped.
941	
942	
943	Section 10.2: Radio & RDS Looping
944	---------------------------------
945	
946	As mentioned in section 6 the radio receiver emulates stations are regular
947	frequency intervals. Depending on the frequency of the radio receiver a
948	signal strength value is calculated (this is returned by VIDIOC_G_TUNER).
949	However, it will also look at the frequency set by the radio transmitter and
950	if that results in a higher signal strength than the settings of the radio
951	transmitter will be used as if it was a valid station. This also includes
952	the RDS data (if any) that the transmitter 'transmits'. This is received
953	faithfully on the receiver side. Note that when the driver is loaded the
954	frequencies of the radio receiver and transmitter are not identical, so
955	initially no looping takes place.
956	
957	
958	Section 11: Cropping, Composing, Scaling
959	----------------------------------------
960	
961	This driver supports cropping, composing and scaling in any combination. Normally
962	which features are supported can be selected through the Vivid controls,
963	but it is also possible to hardcode it when the module is loaded through the
964	ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of
965	these module options.
966	
967	This allows you to test your application for all these variations.
968	
969	Note that the webcam input never supports cropping, composing or scaling. That
970	only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that
971	webcams, including this virtual implementation, normally use
972	VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports.
973	And that does not combine with cropping, composing or scaling. This is
974	primarily a limitation of the V4L2 API which is carefully reproduced here.
975	
976	The 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
978	less. So for a source resolution of 1280x720 the minimum the scaler can do is
979	320x180 and the maximum is 5120x2880. You can play around with this using the
980	qv4l2 test tool and you will see these dependencies.
981	
982	This driver also supports larger 'bytesperline' settings, something that
983	VIDIOC_S_FMT allows but that few drivers implement.
984	
985	The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's
986	designed for speed and simplicity, not quality.
987	
988	If the combination of crop, compose and scaling allows it, then it is possible
989	to change crop and compose rectangles on the fly.
990	
991	
992	Section 12: Formats
993	-------------------
994	
995	The driver supports all the regular packed and planar 4:4:4, 4:2:2 and 4:2:0
996	YUYV formats, 8, 16, 24 and 32 RGB packed formats and various multiplanar
997	formats.
998	
999	The alpha component can be set through the 'Alpha Component' User control
1000	for those formats that support it. If the 'Apply Alpha To Red Only' control
1001	is set, then the alpha component is only used for the color red and set to
1002	0 otherwise.
1003	
1004	The driver has to be configured to support the multiplanar formats. By default
1005	the driver instances are single-planar. This can be changed by setting the
1006	multiplanar module option, see section 1 for more details on that option.
1007	
1008	If the driver instance is using the multiplanar formats/API, then the first
1009	single planar format (YUYV) and the multiplanar NV16M and NV61M formats the
1010	will have a plane that has a non-zero data_offset of 128 bytes. It is rare for
1011	data_offset to be non-zero, so this is a useful feature for testing applications.
1012	
1013	Video output will also honor any data_offset that the application set.
1014	
1015	
1016	Section 13: Capture Overlay
1017	---------------------------
1018	
1019	Note: capture overlay support is implemented primarily to test the existing
1020	V4L2 capture overlay API. In practice few if any GPUs support such overlays
1021	anymore, and neither are they generally needed anymore since modern hardware
1022	is so much more capable. By setting flag 0x10000 in the node_types module
1023	option the vivid driver will create a simple framebuffer device that can be
1024	used for testing this API. Whether this API should be used for new drivers is
1025	questionable.
1026	
1027	This driver has support for a destructive capture overlay with bitmap clipping
1028	and list clipping (up to 16 rectangles) capabilities. Overlays are not
1029	supported for multiplanar formats. It also honors the struct v4l2_window field
1030	setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is
1031	FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay.
1032	
1033	The overlay only works if you are also capturing at that same time. This is a
1034	vivid limitation since it copies from a buffer to the overlay instead of
1035	filling the overlay directly. And if you are not capturing, then no buffers
1036	are available to fill.
1037	
1038	In addition, the pixelformat of the capture format and that of the framebuffer
1039	must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return
1040	an error.
1041	
1042	In order to really see what it going on you will need to create two vivid
1043	instances: the first with a framebuffer enabled. You configure the capture
1044	overlay of the second instance to use the framebuffer of the first, then
1045	you start capturing in the second instance. For the first instance you setup
1046	the output overlay for the video output, turn on video looping and capture
1047	to see the blended framebuffer overlay that's being written to by the second
1048	instance. This setup would require the following commands:
1049	
1050		$ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1
1051		$ 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	
1065	And from another console:
1066	
1067		$ v4l2-ctl -d1 --stream-out-mmap
1068	
1069	And yet another console:
1070	
1071		$ qv4l2
1072	
1073	and start streaming.
1074	
1075	As you can see, this is not for the faint of heart...
1076	
1077	
1078	Section 14: Output Overlay
1079	--------------------------
1080	
1081	Note: output overlays are primarily implemented in order to test the existing
1082	V4L2 output overlay API. Whether this API should be used for new drivers is
1083	questionable.
1084	
1085	This 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	
1095	Output overlays are not supported for multiplanar formats. In addition, the
1096	pixelformat of the capture format and that of the framebuffer must be the
1097	same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error.
1098	
1099	Output overlays only work if the driver has been configured to create a
1100	framebuffer by setting flag 0x10000 in the node_types module option. The
1101	created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and
1102	RGB 5:6:5.
1103	
1104	In order to see the effects of the various clipping, chromakeying or alpha
1105	processing capabilities you need to turn on video looping and see the results
1106	on the capture side. The use of the clipping, chromakeying or alpha processing
1107	capabilities will slow down the video loop considerably as a lot of checks have
1108	to be done per pixel.
1109	
1110	
1111	Section 15: Some Future Improvements
1112	------------------------------------
1113	
1114	Just 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
1120	- Add support to loop teletext sliced VBI output to VBI input
1121	- 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
1130	- The SDR radio should use the same 'frequencies' for stations as the normal
1131	  radio receiver, and give back noise if the frequency doesn't match up with
1132	  a station frequency
1133	- Make a thread for the RDS generation, that would help in particular for the
1134	  "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated
1135	  in real-time.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog