1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</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="user-func.html" title="Appendix A. Function Reference"><link rel="prev" href="vidioc-g-fbuf.html" title="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF"><link rel="next" href="vidioc-g-frequency.html" title="ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY"></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">ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, 2VIDIOC_TRY_FMT</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vidioc-g-fbuf.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="vidioc-g-frequency.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="vidioc-g-fmt"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT — Get or set the data format, try a format</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>struct v4l2_format 3*<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1114521540"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a>.</p></dd><dt><span class="term"><em class="parameter"><code>request</code></em></span></dt><dd><p>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</p></dd><dt><span class="term"><em class="parameter"><code>argp</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1"><a name="idp1114525612"></a><h2>Description</h2><p>These ioctls are used to negotiate the format of data 4(typically image format) exchanged between driver and 5application.</p><p>To query the current parameters applications set the 6<em class="structfield"><code>type</code></em> field of a struct 7<span class="structname">v4l2_format</span> to the respective buffer (stream) 8type. For example video capture devices use 9<code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code> or 10<code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</code>. When the application 11calls the <code class="constant">VIDIOC_G_FMT</code> ioctl with a pointer to 12this structure the driver fills the respective member of the 13<em class="structfield"><code>fmt</code></em> union. In case of video capture devices 14that is either the struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a> <em class="structfield"><code>pix</code></em> or 15the struct <a class="link" href="ch02s02.html#v4l2-pix-format-mplane" title="Table 2.3. struct v4l2_pix_format_mplane">v4l2_pix_format_mplane</a> <em class="structfield"><code>pix_mp</code></em> member. 16When the requested buffer type is not supported drivers return an 17<span class="errorcode">EINVAL</span> error code.</p><p>To change the current format parameters applications 18initialize the <em class="structfield"><code>type</code></em> field and all 19fields of the respective <em class="structfield"><code>fmt</code></em> 20union member. For details see the documentation of the various devices 21types in <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a>. Good practice is to query the 22current parameters first, and to 23modify only those parameters not suitable for the application. When 24the application calls the <code class="constant">VIDIOC_S_FMT</code> ioctl 25with a pointer to a <span class="structname">v4l2_format</span> structure 26the driver checks 27and adjusts the parameters against hardware abilities. Drivers 28should not return an error code unless the <em class="structfield"><code>type</code></em> field is invalid, this is 29a mechanism to fathom device capabilities and to approach parameters 30acceptable for both the application and driver. On success the driver 31may program the hardware, allocate resources and generally prepare for 32data exchange. 33Finally the <code class="constant">VIDIOC_S_FMT</code> ioctl returns the 34current format parameters as <code class="constant">VIDIOC_G_FMT</code> does. 35Very simple, inflexible devices may even ignore all input and always 36return the default parameters. However all V4L2 devices exchanging 37data with the application must implement the 38<code class="constant">VIDIOC_G_FMT</code> and 39<code class="constant">VIDIOC_S_FMT</code> ioctl. When the requested buffer 40type is not supported drivers return an <span class="errorcode">EINVAL</span> error code on a 41<code class="constant">VIDIOC_S_FMT</code> attempt. When I/O is already in 42progress or the resource is not available for other reasons drivers 43return the <span class="errorcode">EBUSY</span> error code.</p><p>The <code class="constant">VIDIOC_TRY_FMT</code> ioctl is equivalent 44to <code class="constant">VIDIOC_S_FMT</code> with one exception: it does not 45change driver state. It can also be called at any time, never 46returning <span class="errorcode">EBUSY</span>. This function is provided to 47negotiate parameters, to learn about hardware limitations, without 48disabling I/O or possibly time consuming hardware preparations. 49Although strongly recommended drivers are not required to implement 50this ioctl.</p><p>The format as returned by <code class="constant">VIDIOC_TRY_FMT</code> 51must be identical to what <code class="constant">VIDIOC_S_FMT</code> returns for 52the same input or output.</p><div class="table"><a name="v4l2-format"></a><p class="title"><b>Table A.72. struct <span class="structname">v4l2_format</span></b></p><div class="table-contents"><table summary="struct v4l2_format" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top"> </td><td valign="top">Type of the data stream, see <a class="xref" href="buffer.html#v4l2-buf-type" title="Table 3.3. enum v4l2_buf_type">Table 3.3, “enum v4l2_buf_type”</a>.</td></tr><tr><td valign="top">union</td><td valign="top"><em class="structfield"><code>fmt</code></em></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a></td><td valign="top"><em class="structfield"><code>pix</code></em></td><td valign="top">Definition of an image format, see <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>, used by video capture and output 53devices.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="ch02s02.html#v4l2-pix-format-mplane" title="Table 2.3. struct v4l2_pix_format_mplane">v4l2_pix_format_mplane</a></td><td valign="top"><em class="structfield"><code>pix_mp</code></em></td><td valign="top">Definition of an image format, see <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>, used by video capture and output 54devices that support the <a class="link" href="planar-apis.html" title="Single- and multi-planar APIs">multi-planar 55version of the API</a>.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="overlay.html#v4l2-window" title="Table 4.1. struct v4l2_window">v4l2_window</a></td><td valign="top"><em class="structfield"><code>win</code></em></td><td valign="top">Definition of an overlaid image, see <a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>, used by video overlay devices.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="raw-vbi.html#v4l2-vbi-format" title="Table 4.4. struct v4l2_vbi_format">v4l2_vbi_format</a></td><td valign="top"><em class="structfield"><code>vbi</code></em></td><td valign="top">Raw VBI capture or output parameters. This is 56discussed in more detail in <a class="xref" href="raw-vbi.html" title="Raw VBI Data Interface">the section called “Raw VBI Data Interface”</a>. Used by raw VBI 57capture and output devices.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="sliced.html#v4l2-sliced-vbi-format" title="Table 4.6. struct v4l2_sliced_vbi_format">v4l2_sliced_vbi_format</a></td><td valign="top"><em class="structfield"><code>sliced</code></em></td><td valign="top">Sliced VBI capture or output parameters. See 58<a class="xref" href="sliced.html" title="Sliced VBI Data Interface">the section called “Sliced VBI Data Interface”</a> for details. Used by sliced VBI 59capture and output devices.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="sdr.html#v4l2-sdr-format" title="Table 4.18. struct v4l2_sdr_format">v4l2_sdr_format</a></td><td valign="top"><em class="structfield"><code>sdr</code></em></td><td valign="top">Definition of a data format, see 60<a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>, used by SDR capture devices.</td></tr><tr><td valign="top"> </td><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>raw_data</code></em>[200]</td><td valign="top">Place holder for future extensions.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idp1114553020"></a><h2>Return Value</h2><p>On success <span class="returnvalue">0</span> is returned, on error <span class="returnvalue">-1</span> and the <code class="varname">errno</code> variable is set appropriately. The generic error codes are described at the <a class="link" href="gen_errors.html#gen-errors" title="Table 19.1. Generic error codes">Generic Error Codes</a> chapter.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">EINVAL</span></span></dt><dd><p>The struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> <em class="structfield"><code>type</code></em> 61field is invalid or the requested buffer type not supported.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vidioc-g-fbuf.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-func.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vidioc-g-frequency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</td></tr></table></div></body></html> 62