145 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_G_ENC_INDEX:5 6************************7ioctl VIDIOC_G_ENC_INDEX8************************9 10Name11====12 13VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream14 15Synopsis16========17 18.. c:macro:: VIDIOC_G_ENC_INDEX19 20``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``21 22Arguments23=========24 25``fd``26 File descriptor returned by :c:func:`open()`.27 28``argp``29 Pointer to struct :c:type:`v4l2_enc_idx`.30 31Description32===========33 34The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed35video stream the same or another application currently reads from the36driver, which is useful for random access into the stream without37decoding it.38 39To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a40pointer to a struct :c:type:`v4l2_enc_idx`. On success41the driver fills the ``entry`` array, stores the number of elements42written in the ``entries`` field, and initializes the ``entries_cap``43field.44 45Each element of the ``entry`` array contains meta data about one46picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to47``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up48to ``entries_cap`` entries. This number can be lower or higher than49``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to50read the meta data in time the oldest entries will be lost. When the51buffer 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 and55video elementary streams.56 57.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}|58 59.. c:type:: v4l2_enc_idx60 61.. flat-table:: struct v4l2_enc_idx62 :header-rows: 063 :stub-columns: 064 :widths: 1 3 865 66 * - __u3267 - ``entries``68 - The number of entries the driver stored in the ``entry`` array.69 * - __u3270 - ``entries_cap``71 - The number of entries the driver can buffer. Must be greater than72 zero.73 * - __u3274 - ``reserved``\ [4]75 - Reserved for future extensions. Drivers must set the76 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 the80 array corresponds to one picture, sorted in ascending order by81 their ``offset``.82 83 84.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|85 86.. c:type:: v4l2_enc_idx_entry87 88.. flat-table:: struct v4l2_enc_idx_entry89 :header-rows: 090 :stub-columns: 091 :widths: 1 1 292 93 * - __u6494 - ``offset``95 - The offset in bytes from the beginning of the compressed video96 stream to the beginning of this picture, that is a *PES packet97 header* as defined in :ref:`mpeg2part1` or a *picture header* as98 defined in :ref:`mpeg2part2`. When the encoder is stopped, the99 driver resets the offset to zero.100 * - __u64101 - ``pts``102 - The 33 bit *Presentation Time Stamp* of this picture as defined in103 :ref:`mpeg2part1`.104 * - __u32105 - ``length``106 - The length of this picture in bytes.107 * - __u32108 - ``flags``109 - Flags containing the coding type of this picture, see110 :ref:`enc-idx-flags`.111 * - __u32112 - ``reserved``\ [2]113 - Reserved for future extensions. Drivers must set the array to114 zero.115 116.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|117 118.. _enc-idx-flags:119 120.. flat-table:: Index Entry Flags121 :header-rows: 0122 :stub-columns: 0123 :widths: 3 1 4124 125 * - ``V4L2_ENC_IDX_FRAME_I``126 - 0x00127 - This is an Intra-coded picture.128 * - ``V4L2_ENC_IDX_FRAME_P``129 - 0x01130 - This is a Predictive-coded picture.131 * - ``V4L2_ENC_IDX_FRAME_B``132 - 0x02133 - This is a Bidirectionally predictive-coded picture.134 * - ``V4L2_ENC_IDX_FRAME_MASK``135 - 0x0F136 - *AND* the flags field with this mask to obtain the picture coding137 type.138 139Return Value140============141 142On success 0 is returned, on error -1 and the ``errno`` variable is set143appropriately. The generic error codes are described at the144:ref:`Generic Error Codes <gen-errors>` chapter.145