1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Data Formats</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="common.html" title="Chapter 1. Common API Elements"><link rel="prev" href="extended-controls.html" title="Extended Controls"><link rel="next" href="planar-apis.html" title="Single- and multi-planar APIs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Data Formats</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extended-controls.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Common API Elements</th><td width="20%" align="right"> <a accesskey="n" href="planar-apis.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="format"></a>Data Formats</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="format.html#idp1098923212">Data Format Negotiation</a></span></dt><dt><span class="section"><a href="format.html#idp1098942900">Image Format Enumeration</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1098923212"></a>Data Format Negotiation</h3></div></div></div><p>Different devices exchange different kinds of data with 2applications, for example video images, raw or sliced VBI data, RDS 3datagrams. Even within one kind many different formats are possible, 4in particular an abundance of image formats. Although drivers must 5provide a default and the selection persists across closing and 6reopening a device, applications should always negotiate a data format 7before engaging in data exchange. Negotiation means the application 8asks for a particular format and the driver selects and reports the 9best the hardware can do to satisfy the request. Of course 10applications can also just query the current selection.</p><p>A single mechanism exists to negotiate all data formats 11using the aggregate struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> and the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> and 12<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctls. Additionally the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a> ioctl can be 13used to examine what the hardware <span class="emphasis"><em>could</em></span> do, 14without actually selecting a new data format. The data formats 15supported by the V4L2 API are covered in the respective device section 16in <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a>. For a closer look at image formats see 17<a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>.</p><p>The <code class="constant">VIDIOC_S_FMT</code> ioctl is a major 18turning-point in the initialization sequence. Prior to this point 19multiple panel applications can access the same device concurrently to 20select the current input, change controls or modify other properties. 21The first <code class="constant">VIDIOC_S_FMT</code> assigns a logical stream 22(video data, VBI data etc.) exclusively to one file descriptor.</p><p>Exclusive means no other application, more precisely no 23other file descriptor, can grab this stream or change device 24properties inconsistent with the negotiated parameters. A video 25standard change for example, when the new standard uses a different 26number of scan lines, can invalidate the selected image format. 27Therefore only the file descriptor owning the stream can make 28invalidating changes. Accordingly multiple file descriptors which 29grabbed different logical streams prevent each other from interfering 30with their settings. When for example video overlay is about to start 31or already in progress, simultaneous video capturing may be restricted 32to the same cropping and image size.</p><p>When applications omit the 33<code class="constant">VIDIOC_S_FMT</code> ioctl its locking side effects are 34implied by the next step, the selection of an I/O method with the 35<a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl or implicit with the first <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> or 36<a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> call.</p><p>Generally only one logical stream can be assigned to a 37file descriptor, the exception being drivers permitting simultaneous 38video capturing and overlay using the same file descriptor for 39compatibility with V4L and earlier versions of V4L2. Switching the 40logical stream or returning into "panel mode" is possible by closing 41and reopening the device. Drivers <span class="emphasis"><em>may</em></span> support a 42switch using <code class="constant">VIDIOC_S_FMT</code>.</p><p>All drivers exchanging data with 43applications must support the <code class="constant">VIDIOC_G_FMT</code> and 44<code class="constant">VIDIOC_S_FMT</code> ioctl. Implementation of the 45<code class="constant">VIDIOC_TRY_FMT</code> is highly recommended but 46optional.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1098942900"></a>Image Format Enumeration</h3></div></div></div><p>Apart of the generic format negotiation functions 47a special ioctl to enumerate all image formats supported by video 48capture, overlay or output devices is available.<a href="#ftn.idp1098943556" class="footnote" name="idp1098943556"><sup class="footnote">[7]</sup></a></p><p>The <a class="link" href="vidioc-enum-fmt.html" title="ioctl VIDIOC_ENUM_FMT"><code class="constant">VIDIOC_ENUM_FMT</code></a> ioctl must be supported 49by all drivers exchanging image data with applications.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Drivers are not supposed to convert image formats in 50kernel space. They must enumerate only formats directly supported by 51the hardware. If necessary driver writers should publish an example 52conversion routine or library for integration into applications.</p></div></div><div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp1098943556" class="footnote"><p><a href="#idp1098943556" class="para"><sup class="para">[7] </sup></a>Enumerating formats an application has no a-priori 53knowledge of (otherwise it could explicitly ask for them and need not 54enumerate) seems useless, but there are applications serving as proxy 55between drivers and the actual video applications for which this is 56useful.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extended-controls.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="common.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="planar-apis.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extended Controls </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Single- and multi-planar APIs</td></tr></table></div></body></html> 57