From 8e4bff4cab0ddac6060645b0715210484d02ff40 Mon Sep 17 00:00:00 2001 From: Yuval Adam <_@yuv.al> Date: Wed, 30 Aug 2017 08:25:59 +0000 Subject: Initial file dump from open source release --- Documentation/DocBook/media/v4l/common.xml | 1200 ++++++++++++++++++++++++++++ 1 file changed, 1200 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/common.xml (limited to 'Documentation/DocBook/media/v4l/common.xml') diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml new file mode 100644 index 00000000..1ddf354a --- /dev/null +++ b/Documentation/DocBook/media/v4l/common.xml @@ -0,0 +1,1200 @@ + Common API Elements + + Programming a V4L2 device consists of these +steps: + + + + Opening the device + + + Changing device properties, selecting a video and audio +input, video standard, picture brightness a. o. + + + Negotiating a data format + + + Negotiating an input/output method + + + The actual input/output loop + + + Closing the device + + + + In practice most steps are optional and can be executed out of +order. It depends on the V4L2 device type, you can read about the +details in . In this chapter we will discuss +the basic concepts applicable to all devices. + +
+ Opening and Closing Devices + +
+ Device Naming + + V4L2 drivers are implemented as kernel modules, loaded +manually by the system administrator or automatically when a device is +first opened. The driver modules plug into the "videodev" kernel +module. It provides helper functions and a common application +interface specified in this document. + + Each driver thus loaded registers one or more device nodes +with major number 81 and a minor number between 0 and 255. Assigning +minor numbers to V4L2 devices is entirely up to the system administrator, +this is primarily intended to solve conflicts between devices. + Access permissions are associated with character +device special files, hence we must ensure device numbers cannot +change with the module load order. To this end minor numbers are no +longer automatically assigned by the "videodev" module as in V4L but +requested by the driver. The defaults will suffice for most people +unless two drivers compete for the same minor numbers. + The module options to select minor numbers are named +after the device special file with a "_nr" suffix. For example "video_nr" +for /dev/video video capture devices. The number is +an offset to the base minor number associated with the device type. + + In earlier versions of the V4L2 API the module options +where named after the device special file with a "unit_" prefix, expressing +the minor number itself, not an offset. Rationale for this change is unknown. +Lastly the naming and semantics are just a convention among driver writers, +the point to note is that minor numbers are not supposed to be hardcoded +into drivers. + When the driver supports multiple devices of the same +type more than one minor number can be assigned, separated by commas: + + +> insmod mydriver.o video_nr=0,1 radio_nr=0,1 + + + In /etc/modules.conf this may be +written as: + +alias char-major-81-0 mydriver +alias char-major-81-1 mydriver +alias char-major-81-64 mydriver +options mydriver video_nr=0,1 radio_nr=0,1 + + + + When an application attempts to open a device +special file with major number 81 and minor number 0, 1, or 64, load +"mydriver" (and the "videodev" module it depends upon). + + + Register the first two video capture devices with +minor number 0 and 1 (base number is 0), the first two radio device +with minor number 64 and 65 (base 64). + + + When no minor number is given as module +option the driver supplies a default. +recommends the base minor numbers to be used for the various device +types. Obviously minor numbers must be unique. When the number is +already in use the offending device will not be +registered. + + By convention system administrators create various +character device special files with these major and minor numbers in +the /dev directory. The names recommended for the +different V4L2 device types are listed in . + + + The creation of character special files (with +mknod) is a privileged operation and +devices cannot be opened by major and minor number. That means +applications cannot reliable scan for loaded or +installed drivers. The user must enter a device name, or the +application can try the conventional device names. + + Under the device filesystem (devfs) the minor number +options are ignored. V4L2 drivers (or by proxy the "videodev" module) +automatically create the required device files in the +/dev/v4l directory using the conventional device +names above. +
+ + + +
+ Multiple Opens + + In general, V4L2 devices can be opened more than once. +When this is supported by the driver, users can for example start a +"panel" application to change controls like brightness or audio +volume, while another application captures video and audio. In other words, panel +applications are comparable to an OSS or ALSA audio mixer application. +When a device supports multiple functions like capturing and overlay +simultaneously, multiple opens allow concurrent +use of the device by forked processes or specialized applications. + + Multiple opens are optional, although drivers should +permit at least concurrent accesses without data exchange, &ie; panel +applications. This implies &func-open; can return an &EBUSY; when the +device is already in use, as well as &func-ioctl; functions initiating +data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read; +and &func-write; functions. + + Mere opening a V4L2 device does not grant exclusive +access. + Drivers could recognize the +O_EXCL open flag. Presently this is not required, +so applications cannot know if it really works. + Initiating data exchange however assigns the right +to read or write the requested type of data, and to change related +properties, to this file descriptor. Applications can request +additional access privileges using the priority mechanism described in +. +
+ +
+ Shared Data Streams + + V4L2 drivers should not support multiple applications +reading or writing the same data stream on a device by copying +buffers, time multiplexing or similar means. This is better handled by +a proxy application in user space. When the driver supports stream +sharing anyway it must be implemented transparently. The V4L2 API does +not specify how conflicts are solved. +
+ +
+ Functions + + To open and close V4L2 devices applications use the +&func-open; and &func-close; function, respectively. Devices are +programmed using the &func-ioctl; function as explained in the +following sections. +
+
+ +
+ Querying Capabilities + + Because V4L2 covers a wide variety of devices not all +aspects of the API are equally applicable to all types of devices. +Furthermore devices of the same type have different capabilities and +this specification permits the omission of a few complicated and less +important parts of the API. + + The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel +device is compatible with this specification, and to query the functions and I/O +methods supported by the device. + + Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the +V4L2 API version used by the driver, with generally matches the Kernel version. +There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is +supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide +support for an ioctl. + + Other features can be queried +by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; +to learn about the number, types and names of video connectors on the +device. Although abstraction is a major objective of this API, the +ioctl also allows driver specific applications to reliable identify +the driver. + + All V4L2 drivers must support +VIDIOC_QUERYCAP. Applications should always call +this ioctl after opening the device. +
+ +
+ Application Priority + + When multiple applications share a device it may be +desirable to assign them different priorities. Contrary to the +traditional "rm -rf /" school of thought a video recording application +could for example block other applications from changing video +controls or switching the current TV channel. Another objective is to +permit low priority applications working in background, which can be +preempted by user controlled applications and automatically regain +control of the device at a later time. + + Since these features cannot be implemented entirely in user +space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY; +ioctls to request and query the access priority associate with a file +descriptor. Opening a device assigns a medium priority, compatible +with earlier versions of V4L2 and drivers not supporting these ioctls. +Applications requiring a different priority will usually call +VIDIOC_S_PRIORITY after verifying the device with +the &VIDIOC-QUERYCAP; ioctl. + + Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, +return an &EBUSY; after another application obtained higher priority. +An event mechanism to notify applications about asynchronous property +changes has been proposed but not added yet. +
+ +
+ Video Inputs and Outputs + + Video inputs and outputs are physical connectors of a +device. These can be for example RF connectors (antenna/cable), CVBS +a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI +capture devices have inputs, output devices have outputs, at least one +each. Radio devices have no video inputs or outputs. + + To learn about the number and attributes of the +available inputs and outputs applications can enumerate them with the +&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The +&v4l2-input; returned by the VIDIOC_ENUMINPUT +ioctl also contains signal status information applicable when the +current video input is queried. + + The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the +index of the current video input or output. To select a different +input or output applications call the &VIDIOC-S-INPUT; and +&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls +when the device has one or more inputs, all the output ioctls when the +device has one or more outputs. + + + + + Information about the current video input + + +&v4l2-input; input; +int index; + +if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +memset (&input, 0, sizeof (input)); +input.index = index; + +if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { + perror ("VIDIOC_ENUMINPUT"); + exit (EXIT_FAILURE); +} + +printf ("Current input: %s\n", input.name); + + + + + Switching to the first video input + + +int index; + +index = 0; + +if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &index)) { + perror ("VIDIOC_S_INPUT"); + exit (EXIT_FAILURE); +} + + +
+ +
+ Audio Inputs and Outputs + + Audio inputs and outputs are physical connectors of a +device. Video capture devices have inputs, output devices have +outputs, zero or more each. Radio devices have no audio inputs or +outputs. They have exactly one tuner which in fact +is an audio source, but this API associates +tuners with video inputs or outputs only, and radio devices have +none of these. + Actually &v4l2-audio; ought to have a +tuner field like &v4l2-input;, not only +making the API more consistent but also permitting radio devices with +multiple tuners. + A connector on a TV card to loop back the received +audio signal to a sound card is not considered an audio output. + + Audio and video inputs and outputs are associated. Selecting +a video source also selects an audio source. This is most evident when +the video and audio source is a tuner. Further audio connectors can +combine with more than one video input or output. Assumed two +composite video inputs and two audio inputs exist, there may be up to +four valid combinations. The relation of video and audio connectors +is defined in the audioset field of the +respective &v4l2-input; or &v4l2-output;, where each bit represents +the index number, starting at zero, of one audio input or output. + + To learn about the number and attributes of the +available inputs and outputs applications can enumerate them with the +&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The +&v4l2-audio; returned by the VIDIOC_ENUMAUDIO ioctl +also contains signal status information applicable when the current +audio input is queried. + + The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report +the current audio input and output, respectively. Note that, unlike +&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure +as VIDIOC_ENUMAUDIO and +VIDIOC_ENUMAUDOUT do, not just an index. + + To select an audio input and change its properties +applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio +output (which presently has no changeable properties) applications +call the &VIDIOC-S-AUDOUT; ioctl. + + Drivers must implement all input ioctls when the device +has one or more inputs, all output ioctls when the device has one +or more outputs. When the device has any audio inputs or outputs the +driver must set the V4L2_CAP_AUDIO flag in the +&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. + + + Information about the current audio input + + +&v4l2-audio; audio; + +memset (&audio, 0, sizeof (audio)); + +if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &audio)) { + perror ("VIDIOC_G_AUDIO"); + exit (EXIT_FAILURE); +} + +printf ("Current input: %s\n", audio.name); + + + + + Switching to the first audio input + + +&v4l2-audio; audio; + +memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */ + +audio.index = 0; + +if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &audio)) { + perror ("VIDIOC_S_AUDIO"); + exit (EXIT_FAILURE); +} + + +
+ +
+ Tuners and Modulators + +
+ Tuners + + Video input devices can have one or more tuners +demodulating a RF signal. Each tuner is associated with one or more +video inputs, depending on the number of RF connectors on the tuner. +The type field of the respective +&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to +V4L2_INPUT_TYPE_TUNER and its +tuner field contains the index number of +the tuner. + + Radio input devices have exactly one tuner with index zero, no +video inputs. + + To query and change tuner properties applications use the +&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The +&v4l2-tuner; returned by VIDIOC_G_TUNER also +contains signal status information applicable when the tuner of the +current video or radio input is queried. Note that +VIDIOC_S_TUNER does not switch the current tuner, +when there is more than one at all. The tuner is solely determined by +the current video input. Drivers must support both ioctls and set the +V4L2_CAP_TUNER flag in the &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or +more tuners. +
+ +
+ Modulators + + Video output devices can have one or more modulators, uh, +modulating a video signal for radiation or connection to the antenna +input of a TV set or video recorder. Each modulator is associated with +one or more video outputs, depending on the number of RF connectors on +the modulator. The type field of the +respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is +set to V4L2_OUTPUT_TYPE_MODULATOR and its +modulator field contains the index number +of the modulator. + + Radio output devices have exactly one modulator with index +zero, no video outputs. + + A video or radio device cannot support both a tuner and a +modulator. Two separate device nodes will have to be used for such +hardware, one that supports the tuner functionality and one that supports +the modulator functionality. The reason is a limitation with the +&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency +is for a tuner or a modulator. + + To query and change modulator properties applications use +the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that +VIDIOC_S_MODULATOR does not switch the current +modulator, when there is more than one at all. The modulator is solely +determined by the current video output. Drivers must support both +ioctls and set the V4L2_CAP_MODULATOR flag in +the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the +device has one or more modulators. +
+ +
+ Radio Frequency + + To get and set the tuner or modulator radio frequency +applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY; +ioctl which both take a pointer to a &v4l2-frequency;. These ioctls +are used for TV and radio devices alike. Drivers must support both +ioctls when the tuner or modulator ioctls are supported, or +when the device is a radio device. +
+
+ +
+ Video Standards + + Video devices typically support one or more different video +standards or variations of standards. Each video input and output may +support another set of standards. This set is reported by the +std field of &v4l2-input; and +&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and +&VIDIOC-ENUMOUTPUT; ioctl, respectively. + + V4L2 defines one bit for each analog video standard +currently in use worldwide, and sets aside bits for driver defined +standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs +and vice versa. Applications can use the predefined bits to select a +particular standard, although presenting the user a menu of supported +standards is preferred. To enumerate and query the attributes of the +supported standards applications use the &VIDIOC-ENUMSTD; ioctl. + + Many of the defined standards are actually just variations +of a few major standards. The hardware may in fact not distinguish +between them, or do so internal and switch automatically. Therefore +enumerated standards also contain sets of one or more standard +bits. + + Assume a hypothetic tuner capable of demodulating B/PAL, +G/PAL and I/PAL signals. The first enumerated standard is a set of B +and G/PAL, switched automatically depending on the selected radio +frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" +choice. Similar a Composite input may collapse standards, enumerating +"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K". + Some users are already confused by technical terms PAL, +NTSC and SECAM. There is no point asking them to distinguish between +B, G, D, or K when the software or hardware can do that +automatically. + + + To query and select the standard used by the current video +input or output applications call the &VIDIOC-G-STD; and +&VIDIOC-S-STD; ioctl, respectively. The received +standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), not an index into the standard enumeration. + An alternative to the current scheme is to use pointers +to indices as arguments of VIDIOC_G_STD and +VIDIOC_S_STD, the &v4l2-input; and +&v4l2-output; std field would be a set of +indices like audioset. + Indices are consistent with the rest of the API +and identify the standard unambiguously. In the present scheme of +things an enumerated standard is looked up by &v4l2-std-id;. Now the +standards supported by the inputs of a device can overlap. Just +assume the tuner and composite input in the example above both +exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests +a choice which does not exist. We cannot merge or omit sets, because +applications would be unable to find the standards reported by +VIDIOC_G_STD. That leaves separate enumerations +for each input. Also selecting a standard by &v4l2-std-id; can be +ambiguous. Advantage of this method is that applications need not +identify the standard indirectly, after enumerating.So in +summary, the lookup itself is unavoidable. The difference is only +whether the lookup is necessary to find an enumerated standard or to +switch to a standard by &v4l2-std-id;. + Drivers must implement all video standard ioctls +when the device has one or more video inputs or outputs. + + Special rules apply to devices such as USB cameras where the notion of video +standards makes little sense. More generally for any capture or output device +which is: + + incapable of capturing fields or frames at the nominal +rate of the video standard, or + + + that does not support the video standard formats at all. + + Here the driver shall set the +std field of &v4l2-input; and &v4l2-output; +to zero and the VIDIOC_G_STD, +VIDIOC_S_STD, +VIDIOC_QUERYSTD and +VIDIOC_ENUMSTD ioctls shall return the +&ENOTTY;. + See for a rationale. + Applications can make use of the and + flags to determine whether the video standard ioctls +are available for the device. + + See for a rationale. Probably +even USB cameras follow some well known video standard. It might have +been better to explicitly indicate elsewhere if a device cannot live +up to normal expectations, instead of this exception. + + + + Information about the current video standard + + +&v4l2-std-id; std_id; +&v4l2-standard; standard; + +if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { + /* Note when VIDIOC_ENUMSTD always returns ENOTTY this + is no video device or it falls under the USB exception, + and VIDIOC_G_STD returning ENOTTY is no error. */ + + perror ("VIDIOC_G_STD"); + exit (EXIT_FAILURE); +} + +memset (&standard, 0, sizeof (standard)); +standard.index = 0; + +while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { + if (standard.id & std_id) { + printf ("Current video standard: %s\n", standard.name); + exit (EXIT_SUCCESS); + } + + standard.index++; +} + +/* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + +if (errno == EINVAL || standard.index == 0) { + perror ("VIDIOC_ENUMSTD"); + exit (EXIT_FAILURE); +} + + + + + Listing the video standards supported by the current +input + + +&v4l2-input; input; +&v4l2-standard; standard; + +memset (&input, 0, sizeof (input)); + +if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { + perror ("VIDIOC_ENUM_INPUT"); + exit (EXIT_FAILURE); +} + +printf ("Current input %s supports:\n", input.name); + +memset (&standard, 0, sizeof (standard)); +standard.index = 0; + +while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { + if (standard.id & input.std) + printf ("%s\n", standard.name); + + standard.index++; +} + +/* EINVAL indicates the end of the enumeration, which cannot be + empty unless this device falls under the USB exception. */ + +if (errno != EINVAL || standard.index == 0) { + perror ("VIDIOC_ENUMSTD"); + exit (EXIT_FAILURE); +} + + + + + Selecting a new video standard + + +&v4l2-input; input; +&v4l2-std-id; std_id; + +memset (&input, 0, sizeof (input)); + +if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { + perror ("VIDIOC_G_INPUT"); + exit (EXIT_FAILURE); +} + +if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { + perror ("VIDIOC_ENUM_INPUT"); + exit (EXIT_FAILURE); +} + +if (0 == (input.std & V4L2_STD_PAL_BG)) { + fprintf (stderr, "Oops. B/G PAL is not supported.\n"); + exit (EXIT_FAILURE); +} + +/* Note this is also supposed to work when only B + or G/PAL is supported. */ + +std_id = V4L2_STD_PAL_BG; + +if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { + perror ("VIDIOC_S_STD"); + exit (EXIT_FAILURE); +} + + +
+
+ Digital Video (DV) Timings + + The video standards discussed so far have been dealing with Analog TV and the +corresponding video timings. Today there are many more different hardware interfaces +such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry +video signals and there is a need to extend the API to select the video timings +for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to +the limited bits available, a new set of IOCTLs was added to set/get video timings at +the input and output: + + DV Timings: This will allow applications to define detailed +video timings for the interface. This includes parameters such as width, height, +polarities, frontporch, backporch etc. The linux/v4l2-dv-timings.h +header can be used to get the timings of the formats in the and + standards. + + + + To enumerate and query the attributes of the DV timings supported by a device, + applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. + To set DV timings for the device, applications use the +&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the +&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications +use the &VIDIOC-QUERY-DV-TIMINGS; ioctl. + Applications can make use of the and + flags to decide what ioctls are available to set the +video timings for the device. +
+ + &sub-controls; + +
+ Data Formats + +
+ Data Format Negotiation + + Different devices exchange different kinds of data with +applications, for example video images, raw or sliced VBI data, RDS +datagrams. Even within one kind many different formats are possible, +in particular an abundance of image formats. Although drivers must +provide a default and the selection persists across closing and +reopening a device, applications should always negotiate a data format +before engaging in data exchange. Negotiation means the application +asks for a particular format and the driver selects and reports the +best the hardware can do to satisfy the request. Of course +applications can also just query the current selection. + + A single mechanism exists to negotiate all data formats +using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and +&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be +used to examine what the hardware could do, +without actually selecting a new data format. The data formats +supported by the V4L2 API are covered in the respective device section +in . For a closer look at image formats see +. + + The VIDIOC_S_FMT ioctl is a major +turning-point in the initialization sequence. Prior to this point +multiple panel applications can access the same device concurrently to +select the current input, change controls or modify other properties. +The first VIDIOC_S_FMT assigns a logical stream +(video data, VBI data etc.) exclusively to one file descriptor. + + Exclusive means no other application, more precisely no +other file descriptor, can grab this stream or change device +properties inconsistent with the negotiated parameters. A video +standard change for example, when the new standard uses a different +number of scan lines, can invalidate the selected image format. +Therefore only the file descriptor owning the stream can make +invalidating changes. Accordingly multiple file descriptors which +grabbed different logical streams prevent each other from interfering +with their settings. When for example video overlay is about to start +or already in progress, simultaneous video capturing may be restricted +to the same cropping and image size. + + When applications omit the +VIDIOC_S_FMT ioctl its locking side effects are +implied by the next step, the selection of an I/O method with the +&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or +&func-write; call. + + Generally only one logical stream can be assigned to a +file descriptor, the exception being drivers permitting simultaneous +video capturing and overlay using the same file descriptor for +compatibility with V4L and earlier versions of V4L2. Switching the +logical stream or returning into "panel mode" is possible by closing +and reopening the device. Drivers may support a +switch using VIDIOC_S_FMT. + + All drivers exchanging data with +applications must support the VIDIOC_G_FMT and +VIDIOC_S_FMT ioctl. Implementation of the +VIDIOC_TRY_FMT is highly recommended but +optional. +
+ +
+ Image Format Enumeration + + Apart of the generic format negotiation functions +a special ioctl to enumerate all image formats supported by video +capture, overlay or output devices is available. + Enumerating formats an application has no a-priori +knowledge of (otherwise it could explicitly ask for them and need not +enumerate) seems useless, but there are applications serving as proxy +between drivers and the actual video applications for which this is +useful. + + + The &VIDIOC-ENUM-FMT; ioctl must be supported +by all drivers exchanging image data with applications. + + + Drivers are not supposed to convert image formats in +kernel space. They must enumerate only formats directly supported by +the hardware. If necessary driver writers should publish an example +conversion routine or library for integration into applications. + +
+
+ + &sub-planar-apis; + +
+ Image Cropping, Insertion and Scaling + + Some video capture devices can sample a subsection of the +picture and shrink or enlarge it to an image of arbitrary size. We +call these abilities cropping and scaling. Some video output devices +can scale an image up or down and insert it at an arbitrary scan line +and horizontal offset into a video signal. + + Applications can use the following API to select an area in +the video signal, query the default area and the hardware limits. +Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP; +and &VIDIOC-S-CROP; ioctls apply to input as well as output +devices. + + Scaling requires a source and a target. On a video capture +or overlay device the source is the video signal, and the cropping +ioctls determine the area actually sampled. The target are images +read by the application or overlaid onto the graphics screen. Their +size (and position for an overlay) is negotiated with the +&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls. + + On a video output device the source are the images passed in +by the application, and their size is again negotiated with the +VIDIOC_G/S_FMT ioctls, or may be encoded in a +compressed video stream. The target is the video signal, and the +cropping ioctls determine the area where the images are +inserted. + + Source and target rectangles are defined even if the device +does not support scaling or the VIDIOC_G/S_CROP +ioctls. Their size (and position where applicable) will be fixed in +this case. All capture and output device must support the +VIDIOC_CROPCAP ioctl such that applications can +determine if scaling takes place. + +
+ Cropping Structures + +
+ Image Cropping, Insertion and Scaling + + + + + + + + + The cropping, insertion and scaling process + + +
+ + For capture devices the coordinates of the top left +corner, width and height of the area which can be sampled is given by +the bounds substructure of the +&v4l2-cropcap; returned by the VIDIOC_CROPCAP +ioctl. To support a wide range of hardware this specification does not +define an origin or units. However by convention drivers should +horizontally count unscaled samples relative to 0H (the leading edge +of the horizontal sync pulse, see ). +Vertically ITU-R line +numbers of the first field (, ), multiplied by two if the driver can capture both +fields. + + The top left corner, width and height of the source +rectangle, that is the area actually sampled, is given by &v4l2-crop; +using the same coordinate system as &v4l2-cropcap;. Applications can +use the VIDIOC_G_CROP and +VIDIOC_S_CROP ioctls to get and set this +rectangle. It must lie completely within the capture boundaries and +the driver may further adjust the requested size and/or position +according to hardware limitations. + + Each capture device has a default source rectangle, given +by the defrect substructure of +&v4l2-cropcap;. The center of this rectangle shall align with the +center of the active picture area of the video signal, and cover what +the driver writer considers the complete picture. Drivers shall reset +the source rectangle to the default when the driver is first loaded, +but not later. + + For output devices these structures and ioctls are used +accordingly, defining the target rectangle where +the images will be inserted into the video signal. + +
+ +
+ Scaling Adjustments + + Video hardware can have various cropping, insertion and +scaling limitations. It may only scale up or down, support only +discrete scaling factors, or have different scaling abilities in +horizontal and vertical direction. Also it may not support scaling at +all. At the same time the &v4l2-crop; rectangle may have to be +aligned, and both the source and target rectangles may have arbitrary +upper and lower size limits. In particular the maximum +width and height +in &v4l2-crop; may be smaller than the +&v4l2-cropcap;.bounds area. Therefore, as +usual, drivers are expected to adjust the requested parameters and +return the actual values selected. + + Applications can change the source or the target rectangle +first, as they may prefer a particular image size or a certain area in +the video signal. If the driver has to adjust both to satisfy hardware +limitations, the last requested rectangle shall take priority, and the +driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT; +ioctl however shall not change the driver state and therefore only +adjust the requested rectangle. + + Suppose scaling on a video capture device is restricted to +a factor 1:1 or 2:1 in either direction and the target image size must +be a multiple of 16 × 16 pixels. The source cropping +rectangle is set to defaults, which are also the upper limit in this +example, of 640 × 400 pixels at offset 0, 0. An +application requests an image size of 300 × 225 +pixels, assuming video will be scaled down from the "full picture" +accordingly. The driver sets the image size to the closest possible +values 304 × 224, then chooses the cropping rectangle +closest to the requested size, that is 608 × 224 +(224 × 2:1 would exceed the limit 400). The offset +0, 0 is still valid, thus unmodified. Given the default cropping +rectangle reported by VIDIOC_CROPCAP the +application can easily propose another offset to center the cropping +rectangle. + + Now the application may insist on covering an area using a +picture aspect ratio closer to the original request, so it asks for a +cropping rectangle of 608 × 456 pixels. The present +scaling factors limit cropping to 640 × 384, so the +driver returns the cropping size 608 × 384 and adjusts +the image size to closest possible 304 × 192. + +
+ +
+ Examples + + Source and target rectangles shall remain unchanged across +closing and reopening a device, such that piping data into or out of a +device will work without special preparations. More advanced +applications should ensure the parameters are suitable before starting +I/O. + + + Resetting the cropping parameters + + (A video capture device is assumed; change +V4L2_BUF_TYPE_VIDEO_CAPTURE for other +devices.) + + +&v4l2-cropcap; cropcap; +&v4l2-crop; crop; + +memset (&cropcap, 0, sizeof (cropcap)); +cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); +} + +memset (&crop, 0, sizeof (crop)); +crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +crop.c = cropcap.defrect; + +/* Ignore if cropping is not supported (EINVAL). */ + +if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); +} + + + + + Simple downscaling + + (A video capture device is assumed.) + + +&v4l2-cropcap; cropcap; +&v4l2-format; format; + +reset_cropping_parameters (); + +/* Scale down to 1/4 size of full picture. */ + +memset (&format, 0, sizeof (format)); /* defaults */ + +format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +format.fmt.pix.width = cropcap.defrect.width >> 1; +format.fmt.pix.height = cropcap.defrect.height >> 1; +format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + +if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { + perror ("VIDIOC_S_FORMAT"); + exit (EXIT_FAILURE); +} + +/* We could check the actual image size now, the actual scaling factor + or if the driver can scale at all. */ + + + + + Selecting an output area + + +&v4l2-cropcap; cropcap; +&v4l2-crop; crop; + +memset (&cropcap, 0, sizeof (cropcap)); +cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + +if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); +} + +memset (&crop, 0, sizeof (crop)); + +crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; +crop.c = cropcap.defrect; + +/* Scale the width and height to 50 % of their original size + and center the output. */ + +crop.c.width /= 2; +crop.c.height /= 2; +crop.c.left += crop.c.width / 2; +crop.c.top += crop.c.height / 2; + +/* Ignore if cropping is not supported (EINVAL). */ + +if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); +} + + + + + Current scaling factor and pixel aspect + + (A video capture device is assumed.) + + +&v4l2-cropcap; cropcap; +&v4l2-crop; crop; +&v4l2-format; format; +double hscale, vscale; +double aspect; +int dwidth, dheight; + +memset (&cropcap, 0, sizeof (cropcap)); +cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); +} + +memset (&crop, 0, sizeof (crop)); +crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) { + if (errno != EINVAL) { + perror ("VIDIOC_G_CROP"); + exit (EXIT_FAILURE); + } + + /* Cropping not supported. */ + crop.c = cropcap.defrect; +} + +memset (&format, 0, sizeof (format)); +format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + +if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) { + perror ("VIDIOC_G_FMT"); + exit (EXIT_FAILURE); +} + +/* The scaling applied by the driver. */ + +hscale = format.fmt.pix.width / (double) crop.c.width; +vscale = format.fmt.pix.height / (double) crop.c.height; + +aspect = cropcap.pixelaspect.numerator / + (double) cropcap.pixelaspect.denominator; +aspect = aspect * hscale / vscale; + +/* Devices following ITU-R BT.601 do not capture + square pixels. For playback on a computer monitor + we should scale the images to this size. */ + +dwidth = format.fmt.pix.width / aspect; +dheight = format.fmt.pix.height; + + +
+
+ + &sub-selection-api; + +
+ Streaming Parameters + + Streaming parameters are intended to optimize the video +capture process as well as I/O. Presently applications can request a +high quality capture mode with the &VIDIOC-S-PARM; ioctl. + + The current video standard determines a nominal number of +frames per second. If less than this number of frames is to be +captured or output, applications can request frame skipping or +duplicating on the driver side. This is especially useful when using +the &func-read; or &func-write;, which are not augmented by timestamps +or sequence counters, and to avoid unnecessary data copying. + + Finally these ioctls can be used to determine the number of +buffers used internally by a driver in read/write mode. For +implications see the section discussing the &func-read; +function. + + To get and set the streaming parameters applications call +the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take +a pointer to a &v4l2-streamparm;, which contains a union holding +separate parameters for input and output devices. + + These ioctls are optional, drivers need not implement +them. If so, they return the &EINVAL;. +
-- cgit v1.3.1