diff options
Diffstat (limited to 'v4l2-spec/vidioc-g-fmt.sgml')
| -rw-r--r-- | v4l2-spec/vidioc-g-fmt.sgml | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/v4l2-spec/vidioc-g-fmt.sgml b/v4l2-spec/vidioc-g-fmt.sgml deleted file mode 100644 index 7c7d1b72c..000000000 --- a/v4l2-spec/vidioc-g-fmt.sgml +++ /dev/null @@ -1,201 +0,0 @@ -<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>. 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 the &v4l2-pix-format; <structfield>pix</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 input is ambiguous, 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> - - <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>&v4l2-buf-type;</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-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>__u8</entry> - <entry><structfield>raw_data</structfield>[200]</entry> - <entry>Place holder for future extensions and custom -(driver defined) formats with <structfield>type</structfield> -<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The data format cannot be changed at this -time, for example because I/O is already in progress.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-format; <structfield>type</structfield> -field is invalid, the requested buffer type not supported, or -<constant>VIDIOC_TRY_FMT</constant> was called and is not -supported with this buffer type.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> |