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     * - __u32
  68       - ``entries``
  69       - The number of entries the driver stored in the ``entry`` array.
  70     * - __u32
  71       - ``entries_cap``
  72       - The number of entries the driver can buffer. Must be greater than
  73         zero.
  74     * - __u32
  75       - ``reserved``\ [4]
  76       - Reserved for future extensions. Drivers must set the
  77         array to zero.
  78     * - struct :c:type:`v4l2_enc_idx_entry`
  79       - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
  80       - Meta data about a compressed video stream. Each element of the
  81         array corresponds to one picture, sorted in ascending order by
  82         their ``offset``.
  83
  84
  85
  86 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  87
  88 .. c:type:: v4l2_enc_idx_entry
  89
  90 .. flat-table:: struct v4l2_enc_idx_entry
  91     :header-rows:  0
  92     :stub-columns: 0
  93     :widths:       1 1 2
  94
  95     * - __u64
  96       - ``offset``
  97       - The offset in bytes from the beginning of the compressed video
  98         stream to the beginning of this picture, that is a *PES packet
  99         header* as defined in :ref:`mpeg2part1` or a *picture header* as
 100         defined in :ref:`mpeg2part2`. When the encoder is stopped, the
 101         driver resets the offset to zero.
 102     * - __u64
 103       - ``pts``
 104       - The 33 bit *Presentation Time Stamp* of this picture as defined in
 105         :ref:`mpeg2part1`.
 106     * - __u32
 107       - ``length``
 108       - The length of this picture in bytes.
 109     * - __u32
 110       - ``flags``
 111       - Flags containing the coding type of this picture, see
 112         :ref:`enc-idx-flags`.
 113     * - __u32
 114       - ``reserved``\ [2]
 115       - Reserved for future extensions. Drivers must set the array to
 116         zero.
 117
 118
 119 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 120
 121 .. _enc-idx-flags:
 122
 123 .. flat-table:: Index Entry Flags
 124     :header-rows:  0
 125     :stub-columns: 0
 126     :widths:       3 1 4
 127
 128     * - ``V4L2_ENC_IDX_FRAME_I``
 129       - 0x00
 130       - This is an Intra-coded picture.
 131     * - ``V4L2_ENC_IDX_FRAME_P``
 132       - 0x01
 133       - This is a Predictive-coded picture.
 134     * - ``V4L2_ENC_IDX_FRAME_B``
 135       - 0x02
 136       - This is a Bidirectionally predictive-coded picture.
 137     * - ``V4L2_ENC_IDX_FRAME_MASK``
 138       - 0x0F
 139       - *AND* the flags field with this mask to obtain the picture coding
 140         type.
 141
 142
 143 Return Value
 144 ============
 145
 146 On success 0 is returned, on error -1 and the ``errno`` variable is set
 147 appropriately. The generic error codes are described at the
 148 :ref:`Generic Error Codes <gen-errors>` chapter.