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     <para>This ioctl lets applications enumerate available frame intervals on a
  53     given sub-device pad. Frame intervals only makes sense for sub-devices that
  54     can control the frame period on their own. This includes, for instance,
  55     image sensors and TV tuners.</para>
  56
  57     <para>For the common use case of image sensors, the frame intervals
  58     available on the sub-device output pad depend on the frame format and size
  59     on the same pad. Applications must thus specify the desired format and size
  60     when enumerating frame intervals.</para>
  61
  62     <para>To enumerate frame intervals applications initialize the
  63     <structfield>index</structfield>, <structfield>pad</structfield>,
  64     <structfield>which</structfield>, <structfield>code</structfield>,
  65     <structfield>width</structfield> and <structfield>height</structfield>
  66     fields of &v4l2-subdev-frame-interval-enum; and call the
  67     <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
  68     to this structure. Drivers fill the rest of the structure or return
  69     an &EINVAL; if one of the input fields is invalid. All frame intervals are
  70     enumerable by beginning at index zero and incrementing by one until
  71     <errorcode>EINVAL</errorcode> is returned.</para>
  72
  73     <para>Available frame intervals may depend on the current 'try' formats
  74     at other pads of the sub-device, as well as on the current active links. See
  75     &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
  76
  77     <para>Sub-devices that support the frame interval enumeration ioctl should
  78     implemented it on a single pad only. Its behaviour when supported on
  79     multiple pads of the same sub-device is not defined.</para>
  80
  81     <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
  82       <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
  83       <tgroup cols="3">
  84         &cs-str;
  85         <tbody valign="top">
  86           <row>
  87             <entry>__u32</entry>
  88             <entry><structfield>index</structfield></entry>
  89             <entry>Number of the format in the enumeration, set by the
  90             application.</entry>
  91           </row>
  92           <row>
  93             <entry>__u32</entry>
  94             <entry><structfield>pad</structfield></entry>
  95             <entry>Pad number as reported by the media controller API.</entry>
  96           </row>
  97           <row>
  98             <entry>__u32</entry>
  99             <entry><structfield>code</structfield></entry>
 100             <entry>The media bus format code, as defined in
 101             <xref linkend="v4l2-mbus-format" />.</entry>
 102           </row>
 103           <row>
 104             <entry>__u32</entry>
 105             <entry><structfield>width</structfield></entry>
 106             <entry>Frame width, in pixels.</entry>
 107           </row>
 108           <row>
 109             <entry>__u32</entry>
 110             <entry><structfield>height</structfield></entry>
 111             <entry>Frame height, in pixels.</entry>
 112           </row>
 113           <row>
 114             <entry>&v4l2-fract;</entry>
 115             <entry><structfield>interval</structfield></entry>
 116             <entry>Period, in seconds, between consecutive video frames.</entry>
 117           </row>
 118           <row>
 119             <entry>__u32</entry>
 120             <entry><structfield>which</structfield></entry>
 121             <entry>Frame intervals to be enumerated, from &v4l2-subdev-format-whence;.</entry>
 122           </row>
 123           <row>
 124             <entry>__u32</entry>
 125             <entry><structfield>reserved</structfield>[8]</entry>
 126             <entry>Reserved for future extensions. Applications and drivers must
 127             set the array to zero.</entry>
 128           </row>
 129         </tbody>
 130       </tgroup>
 131     </table>
 132   </refsect1>
 133
 134   <refsect1>
 135     &return-value;
 136
 137     <variablelist>
 138       <varlistentry>
 139         <term><errorcode>EINVAL</errorcode></term>
 140         <listitem>
 141           <para>The &v4l2-subdev-frame-interval-enum;
 142           <structfield>pad</structfield> references a non-existing pad, one of
 143           the <structfield>code</structfield>, <structfield>width</structfield>
 144           or <structfield>height</structfield> fields are invalid for the given
 145           pad or the <structfield>index</structfield> field is out of bounds.
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149     </variablelist>
 150   </refsect1>
 151 </refentry>