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