Documentation/DocBook/media/v4l/vidioc-g-fmt.xml - kernel/bruno - Git at Google

 <refentry id="vidioc-g-fmt">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
 VIDIOC_TRY_FMT</refentrytitle>
     &manvol;
   </refmeta>

   <refnamediv>
     <refname>VIDIOC_G_FMT</refname>
     <refname>VIDIOC_S_FMT</refname>
     <refname>VIDIOC_TRY_FMT</refname>
     <refpurpose>Get or set the data format, try a format</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_format
 *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>

   <refsect1>
     <title>Arguments</title>

     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>Description</title>

     <para>These ioctls are used to negotiate the format of data
 (typically image format) exchanged between driver and
 application.</para>

     <para>To query the current parameters applications set the
 <structfield>type</structfield> field of a struct
 <structname>v4l2_format</structname> to the respective buffer (stream)
 type. For example video capture devices use
 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
 calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
 this structure the driver fills the respective member of the
 <structfield>fmt</structfield> union. In case of video capture devices
 that is either the &v4l2-pix-format; <structfield>pix</structfield> or
 the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
 When the requested buffer type is not supported drivers return an
 &EINVAL;.</para>

     <para>To change the current format parameters applications
 initialize the <structfield>type</structfield> field and all
 fields of the respective <structfield>fmt</structfield>
 union member. For details see the documentation of the various devices
 types in <xref linkend="devices" />. Good practice is to query the
 current parameters first, and to
 modify only those parameters not suitable for the application. When
 the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
 with a pointer to a <structname>v4l2_format</structname> structure
 the driver checks
 and adjusts the parameters against hardware abilities. Drivers
 should not return an error code unless the <structfield>type</structfield> field is invalid, this is
 a mechanism to fathom device capabilities and to approach parameters
 acceptable for both the application and driver. On success the driver
 may program the hardware, allocate resources and generally prepare for
 data exchange.
 Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
 current format parameters as <constant>VIDIOC_G_FMT</constant> does.
 Very simple, inflexible devices may even ignore all input and always
 return the default parameters. However all V4L2 devices exchanging
 data with the application must implement the
 <constant>VIDIOC_G_FMT</constant> and
 <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
 type is not supported drivers return an &EINVAL; on a
 <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
 progress or the resource is not available for other reasons drivers
 return the &EBUSY;.</para>

     <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
 to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
 change driver state. It can also be called at any time, never
 returning <errorcode>EBUSY</errorcode>. This function is provided to
 negotiate parameters, to learn about hardware limitations, without
 disabling I/O or possibly time consuming hardware preparations.
 Although strongly recommended drivers are not required to implement
 this ioctl.</para>

     <para>The format as returned by <constant>VIDIOC_TRY_FMT</constant>
 must be identical to what <constant>VIDIOC_S_FMT</constant> returns for
 the same input or output.</para>

     <table pgwide="1" frame="none" id="v4l2-format">
       <title>struct <structname>v4l2_format</structname></title>
       <tgroup cols="4">
 	<colspec colname="c1" />
 	<colspec colname="c2" />
 	<colspec colname="c3" />
 	<colspec colname="c4" />
 	<tbody valign="top">
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>type</structfield></entry>
 	    <entry></entry>
 	    <entry>Type of the data stream, see <xref
 		linkend="v4l2-buf-type" />.</entry>
 	  </row>
 	  <row>
 	    <entry>union</entry>
 	    <entry><structfield>fmt</structfield></entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-pix-format;</entry>
 	    <entry><structfield>pix</structfield></entry>
 	    <entry>Definition of an image format, see <xref
 		linkend="pixfmt" />, used by video capture and output
 devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-pix-format-mplane;</entry>
 	    <entry><structfield>pix_mp</structfield></entry>
 	    <entry>Definition of an image format, see <xref
 		linkend="pixfmt" />, used by video capture and output
 devices that support the <link linkend="planar-apis">multi-planar
 version of the API</link>.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-window;</entry>
 	    <entry><structfield>win</structfield></entry>
 	    <entry>Definition of an overlaid image, see <xref
 	    linkend="overlay" />, used by video overlay devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-vbi-format;</entry>
 	    <entry><structfield>vbi</structfield></entry>
 	    <entry>Raw VBI capture or output parameters. This is
 discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
 capture and output devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-sliced-vbi-format;</entry>
 	    <entry><structfield>sliced</structfield></entry>
 	    <entry>Sliced VBI capture or output parameters. See
 <xref linkend="sliced" /> for details. Used by sliced VBI
 capture and output devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>&v4l2-sdr-format;</entry>
 	    <entry><structfield>sdr</structfield></entry>
 	    <entry>Definition of a data format, see
 <xref linkend="pixfmt" />, used by SDR capture devices.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry>__u8</entry>
 	    <entry><structfield>raw_data</structfield>[200]</entry>
 	    <entry>Place holder for future extensions.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </refsect1>

   <refsect1>
     &return-value;

     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The &v4l2-format; <structfield>type</structfield>
 field is invalid or the requested buffer type not supported.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
	<refentry id="vidioc-g-fmt">
	<refmeta>
	<refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
	VIDIOC_TRY_FMT</refentrytitle>
	&manvol;
	</refmeta>

	<refnamediv>
	<refname>VIDIOC_G_FMT</refname>
	<refname>VIDIOC_S_FMT</refname>
	<refname>VIDIOC_TRY_FMT</refname>
	<refpurpose>Get or set the data format, try a format</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<funcsynopsis>
	<funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_format
	*<parameter>argp</parameter></paramdef>
	</funcprototype>
	</funcsynopsis>
	</refsynopsisdiv>

	<refsect1>
	<title>Arguments</title>

	<variablelist>
	<varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	<para>&fd;</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	<para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	<para></para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>Description</title>

	<para>These ioctls are used to negotiate the format of data
	(typically image format) exchanged between driver and
	application.</para>

	<para>To query the current parameters applications set the
	<structfield>type</structfield> field of a struct
	<structname>v4l2_format</structname> to the respective buffer (stream)
	type. For example video capture devices use
	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
	calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
	this structure the driver fills the respective member of the
	<structfield>fmt</structfield> union. In case of video capture devices
	that is either the &v4l2-pix-format; <structfield>pix</structfield> or
	the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
	When the requested buffer type is not supported drivers return an
	&EINVAL;.</para>

	<para>To change the current format parameters applications
	initialize the <structfield>type</structfield> field and all
	fields of the respective <structfield>fmt</structfield>
	union member. For details see the documentation of the various devices
	types in <xref linkend="devices" />. Good practice is to query the
	current parameters first, and to
	modify only those parameters not suitable for the application. When
	the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
	with a pointer to a <structname>v4l2_format</structname> structure
	the driver checks
	and adjusts the parameters against hardware abilities. Drivers
	should not return an error code unless the <structfield>type</structfield> field is invalid, this is
	a mechanism to fathom device capabilities and to approach parameters
	acceptable for both the application and driver. On success the driver
	may program the hardware, allocate resources and generally prepare for
	data exchange.
	Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
	current format parameters as <constant>VIDIOC_G_FMT</constant> does.
	Very simple, inflexible devices may even ignore all input and always
	return the default parameters. However all V4L2 devices exchanging
	data with the application must implement the
	<constant>VIDIOC_G_FMT</constant> and
	<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
	type is not supported drivers return an &EINVAL; on a
	<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
	progress or the resource is not available for other reasons drivers
	return the &EBUSY;.</para>

	<para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
	to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
	change driver state. It can also be called at any time, never
	returning <errorcode>EBUSY</errorcode>. This function is provided to
	negotiate parameters, to learn about hardware limitations, without
	disabling I/O or possibly time consuming hardware preparations.
	Although strongly recommended drivers are not required to implement
	this ioctl.</para>

	<para>The format as returned by <constant>VIDIOC_TRY_FMT</constant>
	must be identical to what <constant>VIDIOC_S_FMT</constant> returns for
	the same input or output.</para>

	<table pgwide="1" frame="none" id="v4l2-format">
	<title>struct <structname>v4l2_format</structname></title>
	<tgroup cols="4">
	<colspec colname="c1" />
	<colspec colname="c2" />
	<colspec colname="c3" />
	<colspec colname="c4" />
	<tbody valign="top">
	<row>
	<entry>__u32</entry>
	<entry><structfield>type</structfield></entry>
	<entry></entry>
	<entry>Type of the data stream, see <xref
	linkend="v4l2-buf-type" />.</entry>
	</row>
	<row>
	<entry>union</entry>
	<entry><structfield>fmt</structfield></entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-pix-format;</entry>
	<entry><structfield>pix</structfield></entry>
	<entry>Definition of an image format, see <xref
	linkend="pixfmt" />, used by video capture and output
	devices.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-pix-format-mplane;</entry>
	<entry><structfield>pix_mp</structfield></entry>
	<entry>Definition of an image format, see <xref
	linkend="pixfmt" />, used by video capture and output
	devices that support the <link linkend="planar-apis">multi-planar
	version of the API</link>.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-window;</entry>
	<entry><structfield>win</structfield></entry>
	<entry>Definition of an overlaid image, see <xref
	linkend="overlay" />, used by video overlay devices.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-vbi-format;</entry>
	<entry><structfield>vbi</structfield></entry>
	<entry>Raw VBI capture or output parameters. This is
	discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
	capture and output devices.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-sliced-vbi-format;</entry>
	<entry><structfield>sliced</structfield></entry>
	<entry>Sliced VBI capture or output parameters. See
	<xref linkend="sliced" /> for details. Used by sliced VBI
	capture and output devices.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>&v4l2-sdr-format;</entry>
	<entry><structfield>sdr</structfield></entry>
	<entry>Definition of a data format, see
	<xref linkend="pixfmt" />, used by SDR capture devices.</entry>
	</row>
	<row>
	<entry></entry>
	<entry>__u8</entry>
	<entry><structfield>raw_data</structfield>[200]</entry>
	<entry>Place holder for future extensions.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</refsect1>

	<refsect1>
	&return-value;

	<variablelist>
	<varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	<para>The &v4l2-format; <structfield>type</structfield>
	field is invalid or the requested buffer type not supported.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>
	</refentry>