Documentation/DocBook/v4l/vidioc-g-enc-index.xml

   1 <refentry id="vidioc-g-enc-index">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_G_ENC_INDEX</refname>
   9     <refpurpose>Get meta data about a compressed video stream</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_enc_idx *<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_G_ENC_INDEX</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
  54       <para>This is an <link linkend="experimental">experimental</link>
  55 interface and may change in the future.</para>
  56     </note>
  57
  58     <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides
  59 meta data about a compressed video stream the same or another
  60 application currently reads from the driver, which is useful for
  61 random access into the stream without decoding it.</para>
  62
  63     <para>To read the data applications must call
  64 <constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a
  65 &v4l2-enc-idx;. On success the driver fills the
  66 <structfield>entry</structfield> array, stores the number of elements
  67 written in the <structfield>entries</structfield> field, and
  68 initializes the <structfield>entries_cap</structfield> field.</para>
  69
  70     <para>Each element of the <structfield>entry</structfield> array
  71 contains meta data about one picture. A
  72 <constant>VIDIOC_G_ENC_INDEX</constant> call reads up to
  73 <constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver
  74 buffer, which can hold up to <structfield>entries_cap</structfield>
  75 entries. This number can be lower or higher than
  76 <constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the
  77 application fails to read the meta data in time the oldest entries
  78 will be lost. When the buffer is empty or no capturing/encoding is in
  79 progress, <structfield>entries</structfield> will be zero.</para>
  80
  81     <para>Currently this ioctl is only defined for MPEG-2 program
  82 streams and video elementary streams.</para>
  83
  84     <table pgwide="1" frame="none" id="v4l2-enc-idx">
  85       <title>struct <structname>v4l2_enc_idx</structname></title>
  86       <tgroup cols="3">
  87         &cs-str;
  88         <tbody valign="top">
  89           <row>
  90             <entry>__u32</entry>
  91             <entry><structfield>entries</structfield></entry>
  92             <entry>The number of entries the driver stored in the
  93 <structfield>entry</structfield> array.</entry>
  94           </row>
  95           <row>
  96             <entry>__u32</entry>
  97             <entry><structfield>entries_cap</structfield></entry>
  98             <entry>The number of entries the driver can
  99 buffer. Must be greater than zero.</entry>
 100           </row>
 101           <row>
 102             <entry>__u32</entry>
 103             <entry><structfield>reserved</structfield>[4]</entry>
 104             <entry spanname="hspan">Reserved for future extensions.
 105 Drivers must set the array to zero.</entry>
 106           </row>
 107           <row>
 108             <entry>&v4l2-enc-idx-entry;</entry>
 109             <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry>
 110             <entry>Meta data about a compressed video stream. Each
 111 element of the array corresponds to one picture, sorted in ascending
 112 order by their <structfield>offset</structfield>.</entry>
 113           </row>
 114         </tbody>
 115       </tgroup>
 116     </table>
 117
 118     <table pgwide="1" frame="none" id="v4l2-enc-idx-entry">
 119       <title>struct <structname>v4l2_enc_idx_entry</structname></title>
 120       <tgroup cols="3">
 121         &cs-str;
 122         <tbody valign="top">
 123           <row>
 124             <entry>__u64</entry>
 125             <entry><structfield>offset</structfield></entry>
 126             <entry>The offset in bytes from the beginning of the
 127 compressed video stream to the beginning of this picture, that is a
 128 <wordasword>PES packet header</wordasword> as defined in <xref
 129             linkend="mpeg2part1" /> or a <wordasword>picture
 130 header</wordasword> as defined in <xref linkend="mpeg2part2" />. When
 131 the encoder is stopped, the driver resets the offset to zero.</entry>
 132           </row>
 133           <row>
 134             <entry>__u64</entry>
 135             <entry><structfield>pts</structfield></entry>
 136             <entry>The 33 bit <wordasword>Presentation Time
 137 Stamp</wordasword> of this picture as defined in <xref
 138                 linkend="mpeg2part1" />.</entry>
 139           </row>
 140           <row>
 141             <entry>__u32</entry>
 142             <entry><structfield>length</structfield></entry>
 143             <entry>The length of this picture in bytes.</entry>
 144           </row>
 145           <row>
 146             <entry>__u32</entry>
 147             <entry><structfield>flags</structfield></entry>
 148             <entry>Flags containing the coding type of this picture, see <xref
 149                 linkend="enc-idx-flags" />.</entry>
 150           </row>
 151           <row>
 152             <entry>__u32</entry>
 153             <entry><structfield>reserved</structfield>[2]</entry>
 154             <entry>Reserved for future extensions.
 155 Drivers must set the array to zero.</entry>
 156           </row>
 157         </tbody>
 158       </tgroup>
 159     </table>
 160
 161     <table pgwide="1" frame="none" id="enc-idx-flags">
 162       <title>Index Entry Flags</title>
 163       <tgroup cols="3">
 164         &cs-def;
 165         <tbody valign="top">
 166           <row>
 167             <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry>
 168             <entry>0x00</entry>
 169             <entry>This is an Intra-coded picture.</entry>
 170           </row>
 171           <row>
 172             <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry>
 173             <entry>0x01</entry>
 174             <entry>This is a Predictive-coded picture.</entry>
 175           </row>
 176           <row>
 177             <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry>
 178             <entry>0x02</entry>
 179             <entry>This is a Bidirectionally predictive-coded
 180 picture.</entry>
 181           </row>
 182           <row>
 183             <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry>
 184             <entry>0x0F</entry>
 185             <entry><wordasword>AND</wordasword> the flags field with
 186 this mask to obtain the picture coding type.</entry>
 187           </row>
 188        </tbody>
 189       </tgroup>
 190     </table>
 191   </refsect1>
 192
 193   <refsect1>
 194     &return-value;
 195
 196     <variablelist>
 197       <varlistentry>
 198         <term><errorcode>EINVAL</errorcode></term>
 199         <listitem>
 200           <para>The driver does not support this ioctl.</para>
 201         </listitem>
 202       </varlistentry>
 203     </variablelist>
 204   </refsect1>
 205 </refentry>
 206
 207 <!--
 208 Local Variables:
 209 mode: sgml
 210 sgml-parent-document: "v4l2.sgml"
 211 indent-tabs-mode: nil
 212 End:
 213 -->