0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_G_ENC_INDEX:
0005
0006 ************************
0007 ioctl VIDIOC_G_ENC_INDEX
0008 ************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_G_ENC_INDEX
0019
0020 ``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_enc_idx`.
0030
0031 Description
0032 ===========
0033
0034 The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
0035 video stream the same or another application currently reads from the
0036 driver, which is useful for random access into the stream without
0037 decoding it.
0038
0039 To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
0040 pointer to a struct :c:type:`v4l2_enc_idx`. On success
0041 the driver fills the ``entry`` array, stores the number of elements
0042 written in the ``entries`` field, and initializes the ``entries_cap``
0043 field.
0044
0045 Each element of the ``entry`` array contains meta data about one
0046 picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
0047 ``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
0048 to ``entries_cap`` entries. This number can be lower or higher than
0049 ``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
0050 read the meta data in time the oldest entries will be lost. When the
0051 buffer is empty or no capturing/encoding is in progress, ``entries``
0052 will be zero.
0053
0054 Currently this ioctl is only defined for MPEG-2 program streams and
0055 video elementary streams.
0056
0057 .. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}|
0058
0059 .. c:type:: v4l2_enc_idx
0060
0061 .. flat-table:: struct v4l2_enc_idx
0062 :header-rows: 0
0063 :stub-columns: 0
0064 :widths: 1 3 8
0065
0066 * - __u32
0067 - ``entries``
0068 - The number of entries the driver stored in the ``entry`` array.
0069 * - __u32
0070 - ``entries_cap``
0071 - The number of entries the driver can buffer. Must be greater than
0072 zero.
0073 * - __u32
0074 - ``reserved``\ [4]
0075 - Reserved for future extensions. Drivers must set the
0076 array to zero.
0077 * - struct :c:type:`v4l2_enc_idx_entry`
0078 - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
0079 - Meta data about a compressed video stream. Each element of the
0080 array corresponds to one picture, sorted in ascending order by
0081 their ``offset``.
0082
0083
0084 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0085
0086 .. c:type:: v4l2_enc_idx_entry
0087
0088 .. flat-table:: struct v4l2_enc_idx_entry
0089 :header-rows: 0
0090 :stub-columns: 0
0091 :widths: 1 1 2
0092
0093 * - __u64
0094 - ``offset``
0095 - The offset in bytes from the beginning of the compressed video
0096 stream to the beginning of this picture, that is a *PES packet
0097 header* as defined in :ref:`mpeg2part1` or a *picture header* as
0098 defined in :ref:`mpeg2part2`. When the encoder is stopped, the
0099 driver resets the offset to zero.
0100 * - __u64
0101 - ``pts``
0102 - The 33 bit *Presentation Time Stamp* of this picture as defined in
0103 :ref:`mpeg2part1`.
0104 * - __u32
0105 - ``length``
0106 - The length of this picture in bytes.
0107 * - __u32
0108 - ``flags``
0109 - Flags containing the coding type of this picture, see
0110 :ref:`enc-idx-flags`.
0111 * - __u32
0112 - ``reserved``\ [2]
0113 - Reserved for future extensions. Drivers must set the array to
0114 zero.
0115
0116 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0117
0118 .. _enc-idx-flags:
0119
0120 .. flat-table:: Index Entry Flags
0121 :header-rows: 0
0122 :stub-columns: 0
0123 :widths: 3 1 4
0124
0125 * - ``V4L2_ENC_IDX_FRAME_I``
0126 - 0x00
0127 - This is an Intra-coded picture.
0128 * - ``V4L2_ENC_IDX_FRAME_P``
0129 - 0x01
0130 - This is a Predictive-coded picture.
0131 * - ``V4L2_ENC_IDX_FRAME_B``
0132 - 0x02
0133 - This is a Bidirectionally predictive-coded picture.
0134 * - ``V4L2_ENC_IDX_FRAME_MASK``
0135 - 0x0F
0136 - *AND* the flags field with this mask to obtain the picture coding
0137 type.
0138
0139 Return Value
0140 ============
0141
0142 On success 0 is returned, on error -1 and the ``errno`` variable is set
0143 appropriately. The generic error codes are described at the
0144 :ref:`Generic Error Codes <gen-errors>` chapter.
