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************************
  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{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
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.