Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml

   1 <refentry id="vidioc-subdev-enum-frame-interval">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
   9     <refpurpose>Enumerate frame intervals</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct v4l2_subdev_frame_interval_enum *
  19         <parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Arguments</title>
  26
  27     <variablelist>
  28       <varlistentry>
  29         <term><parameter>fd</parameter></term>
  30         <listitem>
  31           <para>&fd;</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <note>
  53       <title>Experimental</title>
  54       <para>This is an <link linkend="experimental">experimental</link>
  55       interface and may change in the future.</para>
  56     </note>
  57
  58     <para>This ioctl lets applications enumerate available frame intervals on a
  59     given sub-device pad. Frame intervals only makes sense for sub-devices that
  60     can control the frame period on their own. This includes, for instance,
  61     image sensors and TV tuners.</para>
  62
  63     <para>For the common use case of image sensors, the frame intervals
  64     available on the sub-device output pad depend on the frame format and size
  65     on the same pad. Applications must thus specify the desired format and size
  66     when enumerating frame intervals.</para>
  67
  68     <para>To enumerate frame intervals applications initialize the
  69     <structfield>index</structfield>, <structfield>pad</structfield>,
  70     <structfield>which</structfield>, <structfield>code</structfield>,
  71     <structfield>width</structfield> and <structfield>height</structfield>
  72     fields of &v4l2-subdev-frame-interval-enum; and call the
  73     <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
  74     to this structure. Drivers fill the rest of the structure or return
  75     an &EINVAL; if one of the input fields is invalid. All frame intervals are
  76     enumerable by beginning at index zero and incrementing by one until
  77     <errorcode>EINVAL</errorcode> is returned.</para>
  78
  79     <para>Available frame intervals may depend on the current 'try' formats
  80     at other pads of the sub-device, as well as on the current active links. See
  81     &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
  82
  83     <para>Sub-devices that support the frame interval enumeration ioctl should
  84     implemented it on a single pad only. Its behaviour when supported on
  85     multiple pads of the same sub-device is not defined.</para>
  86
  87     <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
  88       <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
  89       <tgroup cols="3">
  90         &cs-str;
  91         <tbody valign="top">
  92           <row>
  93             <entry>__u32</entry>
  94             <entry><structfield>index</structfield></entry>
  95             <entry>Number of the format in the enumeration, set by the
  96             application.</entry>
  97           </row>
  98           <row>
  99             <entry>__u32</entry>
 100             <entry><structfield>pad</structfield></entry>
 101             <entry>Pad number as reported by the media controller API.</entry>
 102           </row>
 103           <row>
 104             <entry>__u32</entry>
 105             <entry><structfield>code</structfield></entry>
 106             <entry>The media bus format code, as defined in
 107             <xref linkend="v4l2-mbus-format" />.</entry>
 108           </row>
 109           <row>
 110             <entry>__u32</entry>
 111             <entry><structfield>width</structfield></entry>
 112             <entry>Frame width, in pixels.</entry>
 113           </row>
 114           <row>
 115             <entry>__u32</entry>
 116             <entry><structfield>height</structfield></entry>
 117             <entry>Frame height, in pixels.</entry>
 118           </row>
 119           <row>
 120             <entry>&v4l2-fract;</entry>
 121             <entry><structfield>interval</structfield></entry>
 122             <entry>Period, in seconds, between consecutive video frames.</entry>
 123           </row>
 124           <row>
 125             <entry>__u32</entry>
 126             <entry><structfield>which</structfield></entry>
 127             <entry>Frame intervals to be enumerated, from &v4l2-subdev-format-whence;.</entry>
 128           </row>
 129           <row>
 130             <entry>__u32</entry>
 131             <entry><structfield>reserved</structfield>[8]</entry>
 132             <entry>Reserved for future extensions. Applications and drivers must
 133             set the array to zero.</entry>
 134           </row>
 135         </tbody>
 136       </tgroup>
 137     </table>
 138   </refsect1>
 139
 140   <refsect1>
 141     &return-value;
 142
 143     <variablelist>
 144       <varlistentry>
 145         <term><errorcode>EINVAL</errorcode></term>
 146         <listitem>
 147           <para>The &v4l2-subdev-frame-interval-enum;
 148           <structfield>pad</structfield> references a non-existing pad, one of
 149           the <structfield>code</structfield>, <structfield>width</structfield>
 150           or <structfield>height</structfield> fields are invalid for the given
 151           pad or the <structfield>index</structfield> field is out of bounds.
 152           </para>
 153         </listitem>
 154       </varlistentry>
 155     </variablelist>
 156   </refsect1>
 157 </refentry>