1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_G_ENC_INDEX: 4 5************************ 6ioctl VIDIOC_G_ENC_INDEX 7************************ 8 9Name 10==== 11 12VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream 13 14 15Synopsis 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 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :ref:`open() <func-open>`. 27 28``argp`` 29 Pointer to struct :c:type:`v4l2_enc_idx`. 30 31 32Description 33=========== 34 35The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed 36video stream the same or another application currently reads from the 37driver, which is useful for random access into the stream without 38decoding it. 39 40To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a 41pointer to a struct :c:type:`v4l2_enc_idx`. On success 42the driver fills the ``entry`` array, stores the number of elements 43written in the ``entries`` field, and initializes the ``entries_cap`` 44field. 45 46Each element of the ``entry`` array contains meta data about one 47picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to 48``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up 49to ``entries_cap`` entries. This number can be lower or higher than 50``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to 51read the meta data in time the oldest entries will be lost. When the 52buffer is empty or no capturing/encoding is in progress, ``entries`` 53will be zero. 54 55Currently this ioctl is only defined for MPEG-2 program streams and 56video elementary streams. 57 58 59.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| 60 61.. c:type:: v4l2_enc_idx 62 63.. flat-table:: struct v4l2_enc_idx 64 :header-rows: 0 65 :stub-columns: 0 66 :widths: 1 3 8 67 68 * - __u32 69 - ``entries`` 70 - The number of entries the driver stored in the ``entry`` array. 71 * - __u32 72 - ``entries_cap`` 73 - The number of entries the driver can buffer. Must be greater than 74 zero. 75 * - __u32 76 - ``reserved``\ [4] 77 - Reserved for future extensions. Drivers must set the 78 array to zero. 79 * - struct :c:type:`v4l2_enc_idx_entry` 80 - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``] 81 - Meta data about a compressed video stream. Each element of the 82 array corresponds to one picture, sorted in ascending order by 83 their ``offset``. 84 85 86 87.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 88 89.. c:type:: v4l2_enc_idx_entry 90 91.. flat-table:: struct v4l2_enc_idx_entry 92 :header-rows: 0 93 :stub-columns: 0 94 :widths: 1 1 2 95 96 * - __u64 97 - ``offset`` 98 - The offset in bytes from the beginning of the compressed video 99 stream to the beginning of this picture, that is a *PES packet 100 header* as defined in :ref:`mpeg2part1` or a *picture header* as 101 defined in :ref:`mpeg2part2`. When the encoder is stopped, the 102 driver resets the offset to zero. 103 * - __u64 104 - ``pts`` 105 - The 33 bit *Presentation Time Stamp* of this picture as defined in 106 :ref:`mpeg2part1`. 107 * - __u32 108 - ``length`` 109 - The length of this picture in bytes. 110 * - __u32 111 - ``flags`` 112 - Flags containing the coding type of this picture, see 113 :ref:`enc-idx-flags`. 114 * - __u32 115 - ``reserved``\ [2] 116 - Reserved for future extensions. Drivers must set the array to 117 zero. 118 119 120.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 121 122.. _enc-idx-flags: 123 124.. flat-table:: Index Entry Flags 125 :header-rows: 0 126 :stub-columns: 0 127 :widths: 3 1 4 128 129 * - ``V4L2_ENC_IDX_FRAME_I`` 130 - 0x00 131 - This is an Intra-coded picture. 132 * - ``V4L2_ENC_IDX_FRAME_P`` 133 - 0x01 134 - This is a Predictive-coded picture. 135 * - ``V4L2_ENC_IDX_FRAME_B`` 136 - 0x02 137 - This is a Bidirectionally predictive-coded picture. 138 * - ``V4L2_ENC_IDX_FRAME_MASK`` 139 - 0x0F 140 - *AND* the flags field with this mask to obtain the picture coding 141 type. 142 143 144Return Value 145============ 146 147On success 0 is returned, on error -1 and the ``errno`` variable is set 148appropriately. The generic error codes are described at the 149:ref:`Generic Error Codes <gen-errors>` chapter. 150