1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_G_ENC_INDEX: 5 6************************ 7ioctl VIDIOC_G_ENC_INDEX 8************************ 9 10Name 11==== 12 13VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream 14 15Synopsis 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 22Arguments 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 31Description 32=========== 33 34The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed 35video stream the same or another application currently reads from the 36driver, which is useful for random access into the stream without 37decoding it. 38 39To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a 40pointer to a struct :c:type:`v4l2_enc_idx`. On success 41the driver fills the ``entry`` array, stores the number of elements 42written in the ``entries`` field, and initializes the ``entries_cap`` 43field. 44 45Each element of the ``entry`` array contains meta data about one 46picture. 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 48to ``entries_cap`` entries. This number can be lower or higher than 49``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to 50read the meta data in time the oldest entries will be lost. When the 51buffer is empty or no capturing/encoding is in progress, ``entries`` 52will be zero. 53 54Currently this ioctl is only defined for MPEG-2 program streams and 55video elementary streams. 56 57.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| 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.7cm}| 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.7cm}| 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 139Return Value 140============ 141 142On success 0 is returned, on error -1 and the ``errno`` variable is set 143appropriately. The generic error codes are described at the 144:ref:`Generic Error Codes <gen-errors>` chapter. 145