Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml

   1 <refentry id="vidioc-enum-dv-timings">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_ENUM_DV_TIMINGS</refname>
   9     <refpurpose>Enumerate supported Digital Video timings</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_enum_dv_timings *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>&fd;</para>
  31         </listitem>
  32       </varlistentry>
  33       <varlistentry>
  34         <term><parameter>request</parameter></term>
  35         <listitem>
  36           <para>VIDIOC_ENUM_DV_TIMINGS</para>
  37         </listitem>
  38       </varlistentry>
  39       <varlistentry>
  40         <term><parameter>argp</parameter></term>
  41         <listitem>
  42           <para></para>
  43         </listitem>
  44       </varlistentry>
  45     </variablelist>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <note>
  52       <title>Experimental</title>
  53       <para>This is an <link linkend="experimental"> experimental </link>
  54       interface and may change in the future.</para>
  55     </note>
  56
  57     <para>While some DV receivers or transmitters support a wide range of timings, others
  58 support only a limited number of timings. With this ioctl applications can enumerate a list
  59 of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other
  60 standards or even custom timings that are not in this list.</para>
  61
  62     <para>To query the available timings, applications initialize the
  63 <structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
  64 and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this
  65 structure. Drivers fill the rest of the structure or return an
  66 &EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
  67 applications shall begin at index zero, incrementing by one until the
  68 driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
  69 different set of DV timings after switching the video input or
  70 output.</para>
  71
  72     <table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
  73       <title>struct <structname>v4l2_enum_dv_timings</structname></title>
  74       <tgroup cols="3">
  75         &cs-str;
  76         <tbody valign="top">
  77           <row>
  78             <entry>__u32</entry>
  79             <entry><structfield>index</structfield></entry>
  80             <entry>Number of the DV timings, set by the
  81 application.</entry>
  82           </row>
  83           <row>
  84             <entry>__u32</entry>
  85             <entry><structfield>reserved</structfield>[3]</entry>
  86             <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
  87           </row>
  88           <row>
  89             <entry>&v4l2-dv-timings;</entry>
  90             <entry><structfield>timings</structfield></entry>
  91             <entry>The timings.</entry>
  92           </row>
  93         </tbody>
  94       </tgroup>
  95     </table>
  96   </refsect1>
  97
  98   <refsect1>
  99     &return-value;
 100
 101     <variablelist>
 102       <varlistentry>
 103         <term><errorcode>EINVAL</errorcode></term>
 104         <listitem>
 105           <para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
 106 is out of bounds.</para>
 107         </listitem>
 108       </varlistentry>
 109       <varlistentry>
 110         <term><errorcode>ENODATA</errorcode></term>
 111         <listitem>
 112           <para>Digital video presets are not supported for this input or output.</para>
 113         </listitem>
 114       </varlistentry>
 115     </variablelist>
 116   </refsect1>
 117 </refentry>
 118
 119 <!--
 120 Local Variables:
 121 mode: sgml
 122 sgml-parent-document: "v4l2.sgml"
 123 indent-tabs-mode: nil
 124 End:
 125 -->