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