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