Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_ENC_INDEX:
   5
   6 ************************
   7 ioctl VIDIOC_G_ENC_INDEX
   8 ************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_ENC_INDEX
  19
  20 ``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_enc_idx`.
  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 .. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}|
  58
  59 .. c:type:: v4l2_enc_idx
  60
  61 .. flat-table:: struct v4l2_enc_idx
  62     :header-rows:  0
  63     :stub-columns: 0
  64     :widths:       1 3 8
  65
  66     * - __u32
  67       - ``entries``
  68       - The number of entries the driver stored in the ``entry`` array.
  69     * - __u32
  70       - ``entries_cap``
  71       - The number of entries the driver can buffer. Must be greater than
  72         zero.
  73     * - __u32
  74       - ``reserved``\ [4]
  75       - Reserved for future extensions. Drivers must set the
  76         array to zero.
  77     * - struct :c:type:`v4l2_enc_idx_entry`
  78       - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
  79       - Meta data about a compressed video stream. Each element of the
  80         array corresponds to one picture, sorted in ascending order by
  81         their ``offset``.
  82
  83
  84 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
  85
  86 .. c:type:: v4l2_enc_idx_entry
  87
  88 .. flat-table:: struct v4l2_enc_idx_entry
  89     :header-rows:  0
  90     :stub-columns: 0
  91     :widths:       1 1 2
  92
  93     * - __u64
  94       - ``offset``
  95       - The offset in bytes from the beginning of the compressed video
  96         stream to the beginning of this picture, that is a *PES packet
  97         header* as defined in :ref:`mpeg2part1` or a *picture header* as
  98         defined in :ref:`mpeg2part2`. When the encoder is stopped, the
  99         driver resets the offset to zero.
 100     * - __u64
 101       - ``pts``
 102       - The 33 bit *Presentation Time Stamp* of this picture as defined in
 103         :ref:`mpeg2part1`.
 104     * - __u32
 105       - ``length``
 106       - The length of this picture in bytes.
 107     * - __u32
 108       - ``flags``
 109       - Flags containing the coding type of this picture, see
 110         :ref:`enc-idx-flags`.
 111     * - __u32
 112       - ``reserved``\ [2]
 113       - Reserved for future extensions. Drivers must set the array to
 114         zero.
 115
 116 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
 117
 118 .. _enc-idx-flags:
 119
 120 .. flat-table:: Index Entry Flags
 121     :header-rows:  0
 122     :stub-columns: 0
 123     :widths:       3 1 4
 124
 125     * - ``V4L2_ENC_IDX_FRAME_I``
 126       - 0x00
 127       - This is an Intra-coded picture.
 128     * - ``V4L2_ENC_IDX_FRAME_P``
 129       - 0x01
 130       - This is a Predictive-coded picture.
 131     * - ``V4L2_ENC_IDX_FRAME_B``
 132       - 0x02
 133       - This is a Bidirectionally predictive-coded picture.
 134     * - ``V4L2_ENC_IDX_FRAME_MASK``
 135       - 0x0F
 136       - *AND* the flags field with this mask to obtain the picture coding
 137         type.
 138
 139 Return Value
 140 ============
 141
 142 On success 0 is returned, on error -1 and the ``errno`` variable is set
 143 appropriately. The generic error codes are described at the
 144 :ref:`Generic Error Codes <gen-errors>` chapter.