Documentation/media/uapi/v4l/vidioc-g-enc-index.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_ENC_INDEX:
   4
   5 ************************
   6 ioctl VIDIOC_G_ENC_INDEX
   7 ************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_G_ENC_INDEX
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
  37 video stream the same or another application currently reads from the
  38 driver, which is useful for random access into the stream without
  39 decoding it.
  40
  41 To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
  42 pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success
  43 the driver fills the ``entry`` array, stores the number of elements
  44 written in the ``entries`` field, and initializes the ``entries_cap``
  45 field.
  46
  47 Each element of the ``entry`` array contains meta data about one
  48 picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
  49 ``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
  50 to ``entries_cap`` entries. This number can be lower or higher than
  51 ``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
  52 read the meta data in time the oldest entries will be lost. When the
  53 buffer is empty or no capturing/encoding is in progress, ``entries``
  54 will be zero.
  55
  56 Currently this ioctl is only defined for MPEG-2 program streams and
  57 video elementary streams.
  58
  59
  60 .. _v4l2-enc-idx:
  61
  62 .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
  63
  64 .. flat-table:: struct v4l2_enc_idx
  65     :header-rows:  0
  66     :stub-columns: 0
  67     :widths:       1 1 2 1 1
  68
  69
  70     -  .. row 1
  71
  72        -  __u32
  73
  74        -  ``entries``
  75
  76        -  The number of entries the driver stored in the ``entry`` array.
  77
  78     -  .. row 2
  79
  80        -  __u32
  81
  82        -  ``entries_cap``
  83
  84        -  The number of entries the driver can buffer. Must be greater than
  85           zero.
  86
  87     -  .. row 3
  88
  89        -  __u32
  90
  91        -  ``reserved``\ [4]
  92
  93        -  :cspan:`2` Reserved for future extensions. Drivers must set the
  94           array to zero.
  95
  96     -  .. row 4
  97
  98        -  struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
  99
 100        -  ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
 101
 102        -  Meta data about a compressed video stream. Each element of the
 103           array corresponds to one picture, sorted in ascending order by
 104           their ``offset``.
 105
 106
 107
 108 .. _v4l2-enc-idx-entry:
 109
 110 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 111
 112 .. flat-table:: struct v4l2_enc_idx_entry
 113     :header-rows:  0
 114     :stub-columns: 0
 115     :widths:       1 1 2
 116
 117
 118     -  .. row 1
 119
 120        -  __u64
 121
 122        -  ``offset``
 123
 124        -  The offset in bytes from the beginning of the compressed video
 125           stream to the beginning of this picture, that is a *PES packet
 126           header* as defined in :ref:`mpeg2part1` or a *picture header* as
 127           defined in :ref:`mpeg2part2`. When the encoder is stopped, the
 128           driver resets the offset to zero.
 129
 130     -  .. row 2
 131
 132        -  __u64
 133
 134        -  ``pts``
 135
 136        -  The 33 bit *Presentation Time Stamp* of this picture as defined in
 137           :ref:`mpeg2part1`.
 138
 139     -  .. row 3
 140
 141        -  __u32
 142
 143        -  ``length``
 144
 145        -  The length of this picture in bytes.
 146
 147     -  .. row 4
 148
 149        -  __u32
 150
 151        -  ``flags``
 152
 153        -  Flags containing the coding type of this picture, see
 154           :ref:`enc-idx-flags`.
 155
 156     -  .. row 5
 157
 158        -  __u32
 159
 160        -  ``reserved``\ [2]
 161
 162        -  Reserved for future extensions. Drivers must set the array to
 163           zero.
 164
 165
 166
 167 .. _enc-idx-flags:
 168
 169 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 170
 171 .. flat-table:: Index Entry Flags
 172     :header-rows:  0
 173     :stub-columns: 0
 174     :widths:       3 1 4
 175
 176
 177     -  .. row 1
 178
 179        -  ``V4L2_ENC_IDX_FRAME_I``
 180
 181        -  0x00
 182
 183        -  This is an Intra-coded picture.
 184
 185     -  .. row 2
 186
 187        -  ``V4L2_ENC_IDX_FRAME_P``
 188
 189        -  0x01
 190
 191        -  This is a Predictive-coded picture.
 192
 193     -  .. row 3
 194
 195        -  ``V4L2_ENC_IDX_FRAME_B``
 196
 197        -  0x02
 198
 199        -  This is a Bidirectionally predictive-coded picture.
 200
 201     -  .. row 4
 202
 203        -  ``V4L2_ENC_IDX_FRAME_MASK``
 204
 205        -  0x0F
 206
 207        -  *AND* the flags field with this mask to obtain the picture coding
 208           type.
 209
 210
 211 Return Value
 212 ============
 213
 214 On success 0 is returned, on error -1 and the ``errno`` variable is set
 215 appropriately. The generic error codes are described at the
 216 :ref:`Generic Error Codes <gen-errors>` chapter.