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 .. flat-table:: struct v4l2_enc_idx
  63     :header-rows:  0
  64     :stub-columns: 0
  65     :widths:       1 1 2 1 1
  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        -  :cspan:`2` Reserved for future extensions. Drivers must set the
  92           array to zero.
  93
  94     -  .. row 4
  95
  96        -  struct :ref:`v4l2_enc_idx_entry <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 .. _v4l2-enc-idx-entry:
 107
 108 .. flat-table:: struct v4l2_enc_idx_entry
 109     :header-rows:  0
 110     :stub-columns: 0
 111     :widths:       1 1 2
 112
 113
 114     -  .. row 1
 115
 116        -  __u64
 117
 118        -  ``offset``
 119
 120        -  The offset in bytes from the beginning of the compressed video
 121           stream to the beginning of this picture, that is a *PES packet
 122           header* as defined in :ref:`mpeg2part1` or a *picture header* as
 123           defined in :ref:`mpeg2part2`. When the encoder is stopped, the
 124           driver resets the offset to zero.
 125
 126     -  .. row 2
 127
 128        -  __u64
 129
 130        -  ``pts``
 131
 132        -  The 33 bit *Presentation Time Stamp* of this picture as defined in
 133           :ref:`mpeg2part1`.
 134
 135     -  .. row 3
 136
 137        -  __u32
 138
 139        -  ``length``
 140
 141        -  The length of this picture in bytes.
 142
 143     -  .. row 4
 144
 145        -  __u32
 146
 147        -  ``flags``
 148
 149        -  Flags containing the coding type of this picture, see
 150           :ref:`enc-idx-flags`.
 151
 152     -  .. row 5
 153
 154        -  __u32
 155
 156        -  ``reserved``\ [2]
 157
 158        -  Reserved for future extensions. Drivers must set the array to
 159           zero.
 160
 161
 162
 163 .. _enc-idx-flags:
 164
 165 .. flat-table:: Index Entry Flags
 166     :header-rows:  0
 167     :stub-columns: 0
 168     :widths:       3 1 4
 169
 170
 171     -  .. row 1
 172
 173        -  ``V4L2_ENC_IDX_FRAME_I``
 174
 175        -  0x00
 176
 177        -  This is an Intra-coded picture.
 178
 179     -  .. row 2
 180
 181        -  ``V4L2_ENC_IDX_FRAME_P``
 182
 183        -  0x01
 184
 185        -  This is a Predictive-coded picture.
 186
 187     -  .. row 3
 188
 189        -  ``V4L2_ENC_IDX_FRAME_B``
 190
 191        -  0x02
 192
 193        -  This is a Bidirectionally predictive-coded picture.
 194
 195     -  .. row 4
 196
 197        -  ``V4L2_ENC_IDX_FRAME_MASK``
 198
 199        -  0x0F
 200
 201        -  *AND* the flags field with this mask to obtain the picture coding
 202           type.
 203
 204
 205 Return Value
 206 ============
 207
 208 On success 0 is returned, on error -1 and the ``errno`` variable is set
 209 appropriately. The generic error codes are described at the
 210 :ref:`Generic Error Codes <gen-errors>` chapter.