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