Documentation/linux_tv/media/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 *man VIDIOC_G_ENC_INDEX(2)*
  10
  11 Get meta data about a compressed video stream
  12
  13
  14 Synopsis
  15 ========
  16
  17 .. c:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
  18
  19 Arguments
  20 =========
  21
  22 ``fd``
  23     File descriptor returned by :ref:`open() <func-open>`.
  24
  25 ``request``
  26     VIDIOC_G_ENC_INDEX
  27
  28 ``argp``
  29
  30
  31 Description
  32 ===========
  33
  34 The ``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 ``VIDIOC_G_ENC_INDEX`` with a
  40 pointer to a struct :ref:`v4l2_enc_idx <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 ``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 .. _v4l2-enc-idx:
  59
  60 .. flat-table:: struct v4l2_enc_idx
  61     :header-rows:  0
  62     :stub-columns: 0
  63     :widths:       1 1 2 1 1
  64
  65
  66     -  .. row 1
  67
  68        -  __u32
  69
  70        -  ``entries``
  71
  72        -  The number of entries the driver stored in the ``entry`` array.
  73
  74     -  .. row 2
  75
  76        -  __u32
  77
  78        -  ``entries_cap``
  79
  80        -  The number of entries the driver can buffer. Must be greater than
  81           zero.
  82
  83     -  .. row 3
  84
  85        -  __u32
  86
  87        -  ``reserved``\ [4]
  88
  89        -  :cspan:`2` Reserved for future extensions. Drivers must set the
  90           array to zero.
  91
  92     -  .. row 4
  93
  94        -  struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
  95
  96        -  ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
  97
  98        -  Meta data about a compressed video stream. Each element of the
  99           array corresponds to one picture, sorted in ascending order by
 100           their ``offset``.
 101
 102
 103
 104 .. _v4l2-enc-idx-entry:
 105
 106 .. flat-table:: struct v4l2_enc_idx_entry
 107     :header-rows:  0
 108     :stub-columns: 0
 109     :widths:       1 1 2
 110
 111
 112     -  .. row 1
 113
 114        -  __u64
 115
 116        -  ``offset``
 117
 118        -  The offset in bytes from the beginning of the compressed video
 119           stream to the beginning of this picture, that is a *PES packet
 120           header* as defined in :ref:`mpeg2part1` or a *picture header* as
 121           defined in :ref:`mpeg2part2`. When the encoder is stopped, the
 122           driver resets the offset to zero.
 123
 124     -  .. row 2
 125
 126        -  __u64
 127
 128        -  ``pts``
 129
 130        -  The 33 bit *Presentation Time Stamp* of this picture as defined in
 131           :ref:`mpeg2part1`.
 132
 133     -  .. row 3
 134
 135        -  __u32
 136
 137        -  ``length``
 138
 139        -  The length of this picture in bytes.
 140
 141     -  .. row 4
 142
 143        -  __u32
 144
 145        -  ``flags``
 146
 147        -  Flags containing the coding type of this picture, see
 148           :ref:`enc-idx-flags`.
 149
 150     -  .. row 5
 151
 152        -  __u32
 153
 154        -  ``reserved``\ [2]
 155
 156        -  Reserved for future extensions. Drivers must set the array to
 157           zero.
 158
 159
 160
 161 .. _enc-idx-flags:
 162
 163 .. flat-table:: Index Entry Flags
 164     :header-rows:  0
 165     :stub-columns: 0
 166     :widths:       3 1 4
 167
 168
 169     -  .. row 1
 170
 171        -  ``V4L2_ENC_IDX_FRAME_I``
 172
 173        -  0x00
 174
 175        -  This is an Intra-coded picture.
 176
 177     -  .. row 2
 178
 179        -  ``V4L2_ENC_IDX_FRAME_P``
 180
 181        -  0x01
 182
 183        -  This is a Predictive-coded picture.
 184
 185     -  .. row 3
 186
 187        -  ``V4L2_ENC_IDX_FRAME_B``
 188
 189        -  0x02
 190
 191        -  This is a Bidirectionally predictive-coded picture.
 192
 193     -  .. row 4
 194
 195        -  ``V4L2_ENC_IDX_FRAME_MASK``
 196
 197        -  0x0F
 198
 199        -  *AND* the flags field with this mask to obtain the picture coding
 200           type.
 201
 202
 203
 204 Return Value
 205 ============
 206
 207 On success 0 is returned, on error -1 and the ``errno`` variable is set
 208 appropriately. The generic error codes are described at the
 209 :ref:`Generic Error Codes <gen-errors>` chapter.
 210
 211
 212 .. ------------------------------------------------------------------------------
 213 .. This file was automatically converted from DocBook-XML with the dbxml
 214 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 215 .. from the linux kernel, refer to:
 216 ..
 217 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 218 .. ------------------------------------------------------------------------------