| <refentry id="vidioc-subdev-g-fmt"> |
| <refmeta> |
| <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle> |
| &manvol; |
| </refmeta> |
| |
| <refnamediv> |
| <refname>VIDIOC_SUBDEV_G_FMT</refname> |
| <refname>VIDIOC_SUBDEV_S_FMT</refname> |
| <refpurpose>Get or set the data format on a subdev pad</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_subdev_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_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_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 frame format at specific |
| subdev pads in the image pipeline.</para> |
| |
| <para>To retrieve the current format applications set the |
| <structfield>pad</structfield> field of a &v4l2-subdev-format; to the |
| desired pad number as reported by the media API and the |
| <structfield>which</structfield> field to |
| <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the |
| <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this |
| structure the driver fills the members of the <structfield>format</structfield> |
| field.</para> |
| |
| <para>To change the current format applications set both the |
| <structfield>pad</structfield> and <structfield>which</structfield> fields |
| and all members of the <structfield>format</structfield> field. When they |
| call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this |
| structure the driver verifies the requested format, adjusts it based on the |
| hardware capabilities and configures the device. Upon return the |
| &v4l2-subdev-format; contains the current format as would be returned by a |
| <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para> |
| |
| <para>Applications can query the device capabilities by setting the |
| <structfield>which</structfield> to |
| <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not |
| applied to the device by the driver, but are changed exactly as active |
| formats and stored in the sub-device file handle. Two applications querying |
| the same sub-device would thus not interact with each other.</para> |
| |
| <para>For instance, to try a format at the output pad of a sub-device, |
| applications would first set the try format at the sub-device input with the |
| <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either |
| retrieve the default format at the output pad with the |
| <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output |
| pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check |
| the returned value.</para> |
| |
| <para>Try formats do not depend on active formats, but can depend on the |
| current links configuration or sub-device controls value. For instance, a |
| low-pass noise filter might crop pixels at the frame boundaries, modifying |
| its output frame size.</para> |
| |
| <para>Drivers must not return an error solely because the requested format |
| doesn't match the device capabilities. They must instead modify the format |
| to match what the hardware can provide. The modified format should be as |
| close as possible to the original request.</para> |
| |
| <table pgwide="1" frame="none" id="v4l2-subdev-format"> |
| <title>struct <structname>v4l2_subdev_format</structname></title> |
| <tgroup cols="3"> |
| &cs-str; |
| <tbody valign="top"> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>pad</structfield></entry> |
| <entry>Pad number as reported by the media controller API.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>which</structfield></entry> |
| <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry> |
| </row> |
| <row> |
| <entry>&v4l2-mbus-framefmt;</entry> |
| <entry><structfield>format</structfield></entry> |
| <entry>Definition of an image format, see <xref |
| linkend="v4l2-mbus-framefmt" /> for details.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-subdev-format-whence"> |
| <title>enum <structname>v4l2_subdev_format_whence</structname></title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry>V4L2_SUBDEV_FORMAT_TRY</entry> |
| <entry>0</entry> |
| <entry>Try formats, used for querying device capabilities.</entry> |
| </row> |
| <row> |
| <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry> |
| <entry>1</entry> |
| <entry>Active formats, applied to the hardware.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </refsect1> |
| |
| <refsect1> |
| &return-value; |
| |
| <variablelist> |
| <varlistentry> |
| <term><errorcode>EBUSY</errorcode></term> |
| <listitem> |
| <para>The format can't be changed because the pad is currently busy. |
| This can be caused, for instance, by an active video stream on the |
| pad. The ioctl must not be retried without performing another action |
| to fix the problem first. Only returned by |
| <constant>VIDIOC_SUBDEV_S_FMT</constant></para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><errorcode>EINVAL</errorcode></term> |
| <listitem> |
| <para>The &v4l2-subdev-format; <structfield>pad</structfield> |
| references a non-existing pad, or the <structfield>which</structfield> |
| field references a non-existing format.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| </refentry> |