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