1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _decoder: 3 .. _decoder:
4 4
5 ********************************************** 5 *************************************************
6 Memory-to-Memory Stateful Video Decoder Interf 6 Memory-to-Memory Stateful Video Decoder Interface
7 ********************************************** 7 *************************************************
8 8
9 A stateful video decoder takes complete chunks 9 A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
10 H.264/HEVC stream, raw VP8/9 stream) and decod 10 H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
11 display order. The decoder is expected not to 11 display order. The decoder is expected not to require any additional information
12 from the client to process these buffers. 12 from the client to process these buffers.
13 13
14 Performing software parsing, processing etc. o 14 Performing software parsing, processing etc. of the stream in the driver in
15 order to support this interface is strongly di 15 order to support this interface is strongly discouraged. In case such
16 operations are needed, use of the Stateless Vi 16 operations are needed, use of the Stateless Video Decoder Interface (in
17 development) is strongly advised. 17 development) is strongly advised.
18 18
19 Conventions and Notations Used in This Documen 19 Conventions and Notations Used in This Document
20 ============================================== 20 ===============================================
21 21
22 1. The general V4L2 API rules apply if not spe 22 1. The general V4L2 API rules apply if not specified in this document
23 otherwise. 23 otherwise.
24 24
25 2. The meaning of words "must", "may", "should 25 2. The meaning of words "must", "may", "should", etc. is as per `RFC
26 2119 <https://tools.ietf.org/html/rfc2119>` 26 2119 <https://tools.ietf.org/html/rfc2119>`_.
27 27
28 3. All steps not marked "optional" are require 28 3. All steps not marked "optional" are required.
29 29
30 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`V 30 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
31 interchangeably with :c:func:`VIDIOC_G_CTRL 31 interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
32 unless specified otherwise. 32 unless specified otherwise.
33 33
34 5. Single-planar API (see :ref:`planar-apis`) 34 5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
35 used interchangeably with multi-planar API, 35 used interchangeably with multi-planar API, unless specified otherwise,
36 depending on decoder capabilities and follo 36 depending on decoder capabilities and following the general V4L2 guidelines.
37 37
38 6. i = [a..b]: sequence of integers from a to 38 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
39 [0..2]: i = 0, 1, 2. 39 [0..2]: i = 0, 1, 2.
40 40
41 7. Given an ``OUTPUT`` buffer A, then A' repre !! 41 7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
42 queue containing data that resulted from pr 42 queue containing data that resulted from processing buffer A.
43 43
44 .. _decoder-glossary: 44 .. _decoder-glossary:
45 45
46 Glossary 46 Glossary
47 ======== 47 ========
48 48
49 CAPTURE 49 CAPTURE
50 the destination buffer queue; for decoders, 50 the destination buffer queue; for decoders, the queue of buffers containing
51 decoded frames; for encoders, the queue of 51 decoded frames; for encoders, the queue of buffers containing an encoded
52 bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` 52 bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
53 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; dat 53 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
54 into ``CAPTURE`` buffers. 54 into ``CAPTURE`` buffers.
55 55
56 client 56 client
57 the application communicating with the deco 57 the application communicating with the decoder or encoder implementing
58 this interface. 58 this interface.
59 59
60 coded format 60 coded format
61 encoded/compressed video bytestream format 61 encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see
62 also: raw format. 62 also: raw format.
63 63
64 coded height 64 coded height
65 height for given coded resolution. 65 height for given coded resolution.
66 66
67 coded resolution 67 coded resolution
68 stream resolution in pixels aligned to code 68 stream resolution in pixels aligned to codec and hardware requirements;
69 typically visible resolution rounded up to 69 typically visible resolution rounded up to full macroblocks;
70 see also: visible resolution. 70 see also: visible resolution.
71 71
72 coded width 72 coded width
73 width for given coded resolution. 73 width for given coded resolution.
74 74
75 coding tree unit <<
76 processing unit of the HEVC codec (correspo <<
77 H.264, VP8, VP9), <<
78 can use block structures of up to 64×64 pi <<
79 Good at sub-partitioning the picture into v <<
80 <<
81 decode order 75 decode order
82 the order in which frames are decoded; may 76 the order in which frames are decoded; may differ from display order if the
83 coded format includes a feature of frame re 77 coded format includes a feature of frame reordering; for decoders,
84 ``OUTPUT`` buffers must be queued by the cl 78 ``OUTPUT`` buffers must be queued by the client in decode order; for
85 encoders ``CAPTURE`` buffers must be return 79 encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
86 80
87 destination 81 destination
88 data resulting from the decode process; see 82 data resulting from the decode process; see ``CAPTURE``.
89 83
90 display order 84 display order
91 the order in which frames must be displayed 85 the order in which frames must be displayed; for encoders, ``OUTPUT``
92 buffers must be queued by the client in dis 86 buffers must be queued by the client in display order; for decoders,
93 ``CAPTURE`` buffers must be returned by the 87 ``CAPTURE`` buffers must be returned by the decoder in display order.
94 88
95 DPB 89 DPB
96 Decoded Picture Buffer; an H.264/HEVC term 90 Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
97 raw frame available for reference in furthe 91 raw frame available for reference in further decoding steps.
98 92
99 EOS 93 EOS
100 end of stream. 94 end of stream.
101 95
102 IDR 96 IDR
103 Instantaneous Decoder Refresh; a type of a 97 Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
104 stream, which clears the list of earlier re 98 stream, which clears the list of earlier reference frames (DPBs).
105 99
106 keyframe 100 keyframe
107 an encoded frame that does not reference fr 101 an encoded frame that does not reference frames decoded earlier, i.e.
108 can be decoded fully on its own. 102 can be decoded fully on its own.
109 103
110 macroblock 104 macroblock
111 a processing unit in image and video compre 105 a processing unit in image and video compression formats based on linear
112 block transforms (e.g. H.264, VP8, VP9); co 106 block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
113 popular codecs the size is 16x16 samples (p !! 107 popular codecs the size is 16x16 samples (pixels).
114 slightly more flexible processing unit call <<
115 108
116 OUTPUT 109 OUTPUT
117 the source buffer queue; for decoders, the 110 the source buffer queue; for decoders, the queue of buffers containing
118 an encoded bytestream; for encoders, the qu 111 an encoded bytestream; for encoders, the queue of buffers containing raw
119 frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or 112 frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
120 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the 113 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
121 from ``OUTPUT`` buffers. 114 from ``OUTPUT`` buffers.
122 115
123 PPS 116 PPS
124 Picture Parameter Set; a type of metadata e 117 Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
125 118
126 raw format 119 raw format
127 uncompressed format containing raw pixel da 120 uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
128 121
129 resume point 122 resume point
130 a point in the bytestream from which decodi 123 a point in the bytestream from which decoding may start/continue, without
131 any previous state/data present, e.g.: a ke 124 any previous state/data present, e.g.: a keyframe (VP8/VP9) or
132 SPS/PPS/IDR sequence (H.264/HEVC); a resume 125 SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
133 of a new stream, or to resume decoding afte 126 of a new stream, or to resume decoding after a seek.
134 127
135 source 128 source
136 data fed to the decoder or encoder; see ``O 129 data fed to the decoder or encoder; see ``OUTPUT``.
137 130
138 source height 131 source height
139 height in pixels for given source resolutio 132 height in pixels for given source resolution; relevant to encoders only.
140 133
141 source resolution 134 source resolution
142 resolution in pixels of source frames being 135 resolution in pixels of source frames being source to the encoder and
143 subject to further cropping to the bounds o 136 subject to further cropping to the bounds of visible resolution; relevant to
144 encoders only. 137 encoders only.
145 138
146 source width 139 source width
147 width in pixels for given source resolution 140 width in pixels for given source resolution; relevant to encoders only.
148 141
149 SPS 142 SPS
150 Sequence Parameter Set; a type of metadata 143 Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
151 144
152 stream metadata 145 stream metadata
153 additional (non-visual) information contain 146 additional (non-visual) information contained inside encoded bytestream;
154 for example: coded resolution, visible reso 147 for example: coded resolution, visible resolution, codec profile.
155 148
156 visible height 149 visible height
157 height for given visible resolution; displa 150 height for given visible resolution; display height.
158 151
159 visible resolution 152 visible resolution
160 stream resolution of the visible picture, i 153 stream resolution of the visible picture, in pixels, to be used for
161 display purposes; must be smaller or equal 154 display purposes; must be smaller or equal to coded resolution;
162 display resolution. 155 display resolution.
163 156
164 visible width 157 visible width
165 width for given visible resolution; display 158 width for given visible resolution; display width.
166 159
167 State Machine 160 State Machine
168 ============= 161 =============
169 162
170 .. kernel-render:: DOT 163 .. kernel-render:: DOT
171 :alt: DOT digraph of decoder state machine 164 :alt: DOT digraph of decoder state machine
172 :caption: Decoder State Machine 165 :caption: Decoder State Machine
173 166
174 digraph decoder_state_machine { 167 digraph decoder_state_machine {
175 node [shape = doublecircle, label="Deco 168 node [shape = doublecircle, label="Decoding"] Decoding;
176 169
177 node [shape = circle, label="Initializa 170 node [shape = circle, label="Initialization"] Initialization;
178 node [shape = circle, label="Capture\ns 171 node [shape = circle, label="Capture\nsetup"] CaptureSetup;
179 node [shape = circle, label="Dynamic\nR 172 node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange;
180 node [shape = circle, label="Stopped"] 173 node [shape = circle, label="Stopped"] Stopped;
181 node [shape = circle, label="Drain"] Dr 174 node [shape = circle, label="Drain"] Drain;
182 node [shape = circle, label="Seek"] See 175 node [shape = circle, label="Seek"] Seek;
183 node [shape = circle, label="End of Str 176 node [shape = circle, label="End of Stream"] EoS;
184 177
185 node [shape = point]; qi 178 node [shape = point]; qi
186 qi -> Initialization [ label = "open()" 179 qi -> Initialization [ label = "open()" ];
187 180
188 Initialization -> CaptureSetup [ label 181 Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
189 182
190 CaptureSetup -> Stopped [ label = "CAPT 183 CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
191 184
192 Decoding -> ResChange [ label = "Stream 185 Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
193 Decoding -> Drain [ label = "V4L2_DEC_C 186 Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
194 Decoding -> EoS [ label = "EoS mark\nin 187 Decoding -> EoS [ label = "EoS mark\nin the stream" ];
195 Decoding -> Seek [ label = "VIDIOC_STRE 188 Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
196 Decoding -> Stopped [ label = "VIDIOC_S 189 Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
197 Decoding -> Decoding; 190 Decoding -> Decoding;
198 191
199 ResChange -> CaptureSetup [ label = "CA 192 ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
200 ResChange -> Seek [ label = "VIDIOC_STR 193 ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
201 194
202 EoS -> Drain [ label = "Implicit\ndrain 195 EoS -> Drain [ label = "Implicit\ndrain" ];
203 196
204 Drain -> Stopped [ label = "All CAPTURE 197 Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
205 Drain -> Seek [ label = "VIDIOC_STREAMO 198 Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
206 199
207 Seek -> Decoding [ label = "VIDIOC_STRE 200 Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
208 Seek -> Initialization [ label = "VIDIO 201 Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
209 202
210 Stopped -> Decoding [ label = "V4L2_DEC 203 Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
211 Stopped -> Seek [ label = "VIDIOC_STREA 204 Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
212 } 205 }
213 206
214 Querying Capabilities 207 Querying Capabilities
215 ===================== 208 =====================
216 209
217 1. To enumerate the set of coded formats suppo 210 1. To enumerate the set of coded formats supported by the decoder, the
218 client may call :c:func:`VIDIOC_ENUM_FMT` o 211 client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
219 212
220 * The full set of supported formats will be 213 * The full set of supported formats will be returned, regardless of the
221 format set on ``CAPTURE``. 214 format set on ``CAPTURE``.
222 * Check the flags field of :c:type:`v4l2_fm 215 * Check the flags field of :c:type:`v4l2_fmtdesc` for more information
223 about the decoder's capabilities with res 216 about the decoder's capabilities with respect to each coded format.
224 In particular whether or not the decoder 217 In particular whether or not the decoder has a full-fledged bytestream
225 parser and if the decoder supports dynami 218 parser and if the decoder supports dynamic resolution changes.
226 219
227 2. To enumerate the set of supported raw forma 220 2. To enumerate the set of supported raw formats, the client may call
228 :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. 221 :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
229 222
230 * Only the formats supported for the format 223 * Only the formats supported for the format currently active on ``OUTPUT``
231 will be returned. 224 will be returned.
232 225
233 * In order to enumerate raw formats support 226 * In order to enumerate raw formats supported by a given coded format,
234 the client must first set that coded form 227 the client must first set that coded format on ``OUTPUT`` and then
235 enumerate formats on ``CAPTURE``. 228 enumerate formats on ``CAPTURE``.
236 229
237 3. The client may use :c:func:`VIDIOC_ENUM_FRA 230 3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
238 resolutions for a given format, passing des 231 resolutions for a given format, passing desired pixel format in
239 :c:type:`v4l2_frmsizeenum` ``pixel_format`` 232 :c:type:`v4l2_frmsizeenum` ``pixel_format``.
240 233
241 * Values returned by :c:func:`VIDIOC_ENUM_F 234 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
242 format will include all possible coded re 235 format will include all possible coded resolutions supported by the
243 decoder for given coded pixel format. 236 decoder for given coded pixel format.
244 237
245 * Values returned by :c:func:`VIDIOC_ENUM_F 238 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
246 will include all possible frame buffer re 239 will include all possible frame buffer resolutions supported by the
247 decoder for given raw pixel format and th 240 decoder for given raw pixel format and the coded format currently set on
248 ``OUTPUT``. 241 ``OUTPUT``.
249 242
250 4. Supported profiles and levels for the coded 243 4. Supported profiles and levels for the coded format currently set on
251 ``OUTPUT``, if applicable, may be queried u 244 ``OUTPUT``, if applicable, may be queried using their respective controls
252 via :c:func:`VIDIOC_QUERYCTRL`. 245 via :c:func:`VIDIOC_QUERYCTRL`.
253 246
254 Initialization 247 Initialization
255 ============== 248 ==============
256 249
257 1. Set the coded format on ``OUTPUT`` via :c:f 250 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
258 251
259 * **Required fields:** 252 * **Required fields:**
260 253
261 ``type`` 254 ``type``
262 a ``V4L2_BUF_TYPE_*`` enum appropriat 255 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
263 256
264 ``pixelformat`` 257 ``pixelformat``
265 a coded pixel format. 258 a coded pixel format.
266 259
267 ``width``, ``height`` 260 ``width``, ``height``
268 coded resolution of the stream; requi 261 coded resolution of the stream; required only if it cannot be parsed
269 from the stream for the given coded f 262 from the stream for the given coded format; otherwise the decoder will
270 use this resolution as a placeholder 263 use this resolution as a placeholder resolution that will likely change
271 as soon as it can parse the actual co 264 as soon as it can parse the actual coded resolution from the stream.
272 265
273 ``sizeimage`` 266 ``sizeimage``
274 desired size of ``OUTPUT`` buffers; t 267 desired size of ``OUTPUT`` buffers; the decoder may adjust it to
275 match hardware requirements. 268 match hardware requirements.
276 269
277 other fields 270 other fields
278 follow standard semantics. 271 follow standard semantics.
279 272
280 * **Returned fields:** !! 273 * **Return fields:**
281 274
282 ``sizeimage`` 275 ``sizeimage``
283 adjusted size of ``OUTPUT`` buffers. 276 adjusted size of ``OUTPUT`` buffers.
284 277
285 * The ``CAPTURE`` format will be updated wi 278 * The ``CAPTURE`` format will be updated with an appropriate frame buffer
286 resolution instantly based on the width a 279 resolution instantly based on the width and height returned by
287 :c:func:`VIDIOC_S_FMT`. 280 :c:func:`VIDIOC_S_FMT`.
288 However, for coded formats that include s 281 However, for coded formats that include stream resolution information,
289 after the decoder is done parsing the inf 282 after the decoder is done parsing the information from the stream, it will
290 update the ``CAPTURE`` format with new va 283 update the ``CAPTURE`` format with new values and signal a source change
291 event, regardless of whether they match t 284 event, regardless of whether they match the values set by the client or
292 not. 285 not.
293 286
294 .. important:: 287 .. important::
295 288
296 Changing the ``OUTPUT`` format may chang 289 Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
297 format. How the new ``CAPTURE`` format i 290 format. How the new ``CAPTURE`` format is determined is up to the decoder
298 and the client must ensure it matches it !! 291 and the client must ensure it matches its needs afterwards.
299 292
300 2. Allocate source (bytestream) buffers via : 293 2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on
301 ``OUTPUT``. 294 ``OUTPUT``.
302 295
303 * **Required fields:** 296 * **Required fields:**
304 297
305 ``count`` 298 ``count``
306 requested number of buffers to alloc 299 requested number of buffers to allocate; greater than zero.
307 300
308 ``type`` 301 ``type``
309 a ``V4L2_BUF_TYPE_*`` enum appropria 302 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
310 303
311 ``memory`` 304 ``memory``
312 follows standard semantics. 305 follows standard semantics.
313 306
314 * **Returned fields:** !! 307 * **Return fields:**
315 308
316 ``count`` 309 ``count``
317 the actual number of buffers allocat 310 the actual number of buffers allocated.
318 311
319 .. warning:: 312 .. warning::
320 313
321 The actual number of allocated buffers 314 The actual number of allocated buffers may differ from the ``count``
322 given. The client must check the update 315 given. The client must check the updated value of ``count`` after the
323 call returns. 316 call returns.
324 317
325 Alternatively, :c:func:`VIDIOC_CREATE_BUFS 318 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
326 used to have more control over buffer allo 319 used to have more control over buffer allocation.
327 320
328 * **Required fields:** 321 * **Required fields:**
329 322
330 ``count`` 323 ``count``
331 requested number of buffers to alloc 324 requested number of buffers to allocate; greater than zero.
332 325
333 ``type`` 326 ``type``
334 a ``V4L2_BUF_TYPE_*`` enum appropria 327 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
335 328
336 ``memory`` 329 ``memory``
337 follows standard semantics. 330 follows standard semantics.
338 331
339 ``format`` 332 ``format``
340 follows standard semantics. 333 follows standard semantics.
341 334
342 * **Returned fields:** !! 335 * **Return fields:**
343 336
344 ``count`` 337 ``count``
345 adjusted to the number of allocated 338 adjusted to the number of allocated buffers.
346 339
347 .. warning:: 340 .. warning::
348 341
349 The actual number of allocated buffers 342 The actual number of allocated buffers may differ from the ``count``
350 given. The client must check the update 343 given. The client must check the updated value of ``count`` after the
351 call returns. 344 call returns.
352 345
353 3. Start streaming on the ``OUTPUT`` queue vi 346 3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
354 347
355 4. **This step only applies to coded formats 348 4. **This step only applies to coded formats that contain resolution information
356 in the stream.** Continue queuing/dequeuin 349 in the stream.** Continue queuing/dequeuing bytestream buffers to/from the
357 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` 350 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
358 buffers will be processed and returned to 351 buffers will be processed and returned to the client in order, until
359 required metadata to configure the ``CAPTU 352 required metadata to configure the ``CAPTURE`` queue are found. This is
360 indicated by the decoder sending a ``V4L2_ 353 indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
361 ``changes`` set to ``V4L2_EVENT_SRC_CH_RES 354 ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
362 355
363 * It is not an error if the first buffer d 356 * It is not an error if the first buffer does not contain enough data for
364 this to occur. Processing of the buffers 357 this to occur. Processing of the buffers will continue as long as more
365 data is needed. 358 data is needed.
366 359
367 * If data in a buffer that triggers the ev 360 * If data in a buffer that triggers the event is required to decode the
368 first frame, it will not be returned to 361 first frame, it will not be returned to the client, until the
369 initialization sequence completes and th 362 initialization sequence completes and the frame is decoded.
370 363
371 * If the client has not set the coded reso 364 * If the client has not set the coded resolution of the stream on its own,
372 calling :c:func:`VIDIOC_G_FMT`, :c:func: 365 calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
373 :c:func:`VIDIOC_TRY_FMT` or :c:func:`VID 366 :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
374 queue will not return the real values fo 367 queue will not return the real values for the stream until a
375 ``V4L2_EVENT_SOURCE_CHANGE`` event with 368 ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
376 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is sign 369 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled.
377 370
378 .. important:: 371 .. important::
379 372
380 Any client query issued after the decod 373 Any client query issued after the decoder queues the event will return
381 values applying to the just parsed stre 374 values applying to the just parsed stream, including queue formats,
382 selection rectangles and controls. 375 selection rectangles and controls.
383 376
384 .. note:: 377 .. note::
385 378
386 A client capable of acquiring stream pa 379 A client capable of acquiring stream parameters from the bytestream on
387 its own may attempt to set the width an 380 its own may attempt to set the width and height of the ``OUTPUT`` format
388 to non-zero values matching the coded s 381 to non-zero values matching the coded size of the stream, skip this step
389 and continue with the `Capture Setup` s 382 and continue with the `Capture Setup` sequence. However, it must not
390 rely on any driver queries regarding st 383 rely on any driver queries regarding stream parameters, such as
391 selection rectangles and controls, sinc 384 selection rectangles and controls, since the decoder has not parsed them
392 from the stream yet. If the values conf 385 from the stream yet. If the values configured by the client do not match
393 those parsed by the decoder, a `Dynamic 386 those parsed by the decoder, a `Dynamic Resolution Change` will be
394 triggered to reconfigure them. 387 triggered to reconfigure them.
395 388
396 .. note:: 389 .. note::
397 390
398 No decoded frames are produced during t 391 No decoded frames are produced during this phase.
399 392
400 5. Continue with the `Capture Setup` sequence 393 5. Continue with the `Capture Setup` sequence.
401 394
402 Capture Setup 395 Capture Setup
403 ============= 396 =============
404 397
405 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTU 398 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
406 destination buffers parsed/decoded from th 399 destination buffers parsed/decoded from the bytestream.
407 400
408 * **Required fields:** 401 * **Required fields:**
409 402
410 ``type`` 403 ``type``
411 a ``V4L2_BUF_TYPE_*`` enum appropria 404 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
412 405
413 * **Returned fields:** !! 406 * **Return fields:**
414 407
415 ``width``, ``height`` 408 ``width``, ``height``
416 frame buffer resolution for the deco 409 frame buffer resolution for the decoded frames.
417 410
418 ``pixelformat`` 411 ``pixelformat``
419 pixel format for decoded frames. 412 pixel format for decoded frames.
420 413
421 ``num_planes`` (for _MPLANE ``type`` onl 414 ``num_planes`` (for _MPLANE ``type`` only)
422 number of planes for pixelformat. 415 number of planes for pixelformat.
423 416
424 ``sizeimage``, ``bytesperline`` 417 ``sizeimage``, ``bytesperline``
425 as per standard semantics; matching 418 as per standard semantics; matching frame buffer format.
426 419
427 .. note:: 420 .. note::
428 421
429 The value of ``pixelformat`` may be any 422 The value of ``pixelformat`` may be any pixel format supported by the
430 decoder for the current stream. The dec 423 decoder for the current stream. The decoder should choose a
431 preferred/optimal format for the defaul 424 preferred/optimal format for the default configuration. For example, a
432 YUV format may be preferred over an RGB 425 YUV format may be preferred over an RGB format if an additional
433 conversion step would be required for t 426 conversion step would be required for the latter.
434 427
435 2. **Optional.** Acquire the visible resoluti 428 2. **Optional.** Acquire the visible resolution via
436 :c:func:`VIDIOC_G_SELECTION`. 429 :c:func:`VIDIOC_G_SELECTION`.
437 430
438 * **Required fields:** 431 * **Required fields:**
439 432
440 ``type`` 433 ``type``
441 a ``V4L2_BUF_TYPE_*`` enum appropria 434 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
442 435
443 ``target`` 436 ``target``
444 set to ``V4L2_SEL_TGT_COMPOSE``. 437 set to ``V4L2_SEL_TGT_COMPOSE``.
445 438
446 * **Returned fields:** !! 439 * **Return fields:**
447 440
448 ``r.left``, ``r.top``, ``r.width``, ``r. 441 ``r.left``, ``r.top``, ``r.width``, ``r.height``
449 the visible rectangle; it must fit w 442 the visible rectangle; it must fit within the frame buffer resolution
450 returned by :c:func:`VIDIOC_G_FMT` o 443 returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
451 444
452 * The following selection targets are supp 445 * The following selection targets are supported on ``CAPTURE``:
453 446
454 ``V4L2_SEL_TGT_CROP_BOUNDS`` 447 ``V4L2_SEL_TGT_CROP_BOUNDS``
455 corresponds to the coded resolution 448 corresponds to the coded resolution of the stream.
456 449
457 ``V4L2_SEL_TGT_CROP_DEFAULT`` 450 ``V4L2_SEL_TGT_CROP_DEFAULT``
458 the rectangle covering the part of t 451 the rectangle covering the part of the ``CAPTURE`` buffer that
459 contains meaningful picture data (vi 452 contains meaningful picture data (visible area); width and height
460 will be equal to the visible resolut 453 will be equal to the visible resolution of the stream.
461 454
462 ``V4L2_SEL_TGT_CROP`` 455 ``V4L2_SEL_TGT_CROP``
463 the rectangle within the coded resol 456 the rectangle within the coded resolution to be output to
464 ``CAPTURE``; defaults to ``V4L2_SEL_ 457 ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
465 hardware without additional compose/ 458 hardware without additional compose/scaling capabilities.
466 459
467 ``V4L2_SEL_TGT_COMPOSE_BOUNDS`` 460 ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
468 the maximum rectangle within a ``CAP 461 the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
469 frame can be composed into; equal to 462 frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
470 hardware does not support compose/sc 463 hardware does not support compose/scaling.
471 464
472 ``V4L2_SEL_TGT_COMPOSE_DEFAULT`` 465 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
473 equal to ``V4L2_SEL_TGT_CROP``. 466 equal to ``V4L2_SEL_TGT_CROP``.
474 467
475 ``V4L2_SEL_TGT_COMPOSE`` 468 ``V4L2_SEL_TGT_COMPOSE``
476 the rectangle inside a ``CAPTURE`` b 469 the rectangle inside a ``CAPTURE`` buffer into which the cropped
477 frame is written; defaults to ``V4L2 470 frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
478 read-only on hardware without additi 471 read-only on hardware without additional compose/scaling capabilities.
479 472
480 ``V4L2_SEL_TGT_COMPOSE_PADDED`` 473 ``V4L2_SEL_TGT_COMPOSE_PADDED``
481 the rectangle inside a ``CAPTURE`` b 474 the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
482 hardware; equal to ``V4L2_SEL_TGT_CO 475 hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
483 write padding pixels. 476 write padding pixels.
484 477
485 .. warning:: 478 .. warning::
486 479
487 The values are guaranteed to be meaning 480 The values are guaranteed to be meaningful only after the decoder
488 successfully parses the stream metadata 481 successfully parses the stream metadata. The client must not rely on the
489 query before that happens. 482 query before that happens.
490 483
491 3. **Optional.** Enumerate ``CAPTURE`` format 484 3. **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
492 the ``CAPTURE`` queue. Once the stream inf 485 the ``CAPTURE`` queue. Once the stream information is parsed and known, the
493 client may use this ioctl to discover whic 486 client may use this ioctl to discover which raw formats are supported for
494 given stream and select one of them via :c 487 given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
495 488
496 .. important:: 489 .. important::
497 490
498 The decoder will return only formats su 491 The decoder will return only formats supported for the currently
499 established coded format, as per the `` 492 established coded format, as per the ``OUTPUT`` format and/or stream
500 metadata parsed in this initialization 493 metadata parsed in this initialization sequence, even if more formats
501 may be supported by the decoder in gene 494 may be supported by the decoder in general. In other words, the set
502 returned will be a subset of the initia 495 returned will be a subset of the initial query mentioned in the
503 `Querying Capabilities` section. 496 `Querying Capabilities` section.
504 497
505 For example, a decoder may support YUV 498 For example, a decoder may support YUV and RGB formats for resolutions
506 1920x1088 and lower, but only YUV for h 499 1920x1088 and lower, but only YUV for higher resolutions (due to
507 hardware limitations). After parsing a 500 hardware limitations). After parsing a resolution of 1920x1088 or lower,
508 :c:func:`VIDIOC_ENUM_FMT` may return a 501 :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
509 but after parsing resolution higher tha 502 but after parsing resolution higher than 1920x1088, the decoder will not
510 return RGB, unsupported for this resolu 503 return RGB, unsupported for this resolution.
511 504
512 However, subsequent resolution change e 505 However, subsequent resolution change event triggered after
513 discovering a resolution change within 506 discovering a resolution change within the same stream may switch
514 the stream into a lower resolution and 507 the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
515 would return RGB formats again in that 508 would return RGB formats again in that case.
516 509
517 4. **Optional.** Set the ``CAPTURE`` format v 510 4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
518 ``CAPTURE`` queue. The client may choose a 511 ``CAPTURE`` queue. The client may choose a different format than
519 selected/suggested by the decoder in :c:fu 512 selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
520 513
521 * **Required fields:** 514 * **Required fields:**
522 515
523 ``type`` 516 ``type``
524 a ``V4L2_BUF_TYPE_*`` enum appropria 517 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
525 518
526 ``pixelformat`` 519 ``pixelformat``
527 a raw pixel format. 520 a raw pixel format.
528 521
529 ``width``, ``height`` 522 ``width``, ``height``
530 frame buffer resolution of the decode 523 frame buffer resolution of the decoded stream; typically unchanged from
531 what was returned with :c:func:`VIDIO 524 what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
532 if the hardware supports composition 525 if the hardware supports composition and/or scaling.
533 526
534 * Setting the ``CAPTURE`` format will reset 527 * Setting the ``CAPTURE`` format will reset the compose selection rectangles
535 to their default values, based on the new 528 to their default values, based on the new resolution, as described in the
536 previous step. 529 previous step.
537 530
538 5. **Optional.** Set the compose rectangle via 531 5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
539 the ``CAPTURE`` queue if it is desired and 532 the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
540 scaling capabilities. 533 scaling capabilities.
541 534
542 * **Required fields:** 535 * **Required fields:**
543 536
544 ``type`` 537 ``type``
545 a ``V4L2_BUF_TYPE_*`` enum appropriat 538 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
546 539
547 ``target`` 540 ``target``
548 set to ``V4L2_SEL_TGT_COMPOSE``. 541 set to ``V4L2_SEL_TGT_COMPOSE``.
549 542
550 ``r.left``, ``r.top``, ``r.width``, ``r.h 543 ``r.left``, ``r.top``, ``r.width``, ``r.height``
551 the rectangle inside a ``CAPTURE`` bu 544 the rectangle inside a ``CAPTURE`` buffer into which the cropped
552 frame is written; defaults to ``V4L2_ 545 frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
553 read-only on hardware without additio 546 read-only on hardware without additional compose/scaling capabilities.
554 547
555 * **Returned fields:** !! 548 * **Return fields:**
556 549
557 ``r.left``, ``r.top``, ``r.width``, ``r.h 550 ``r.left``, ``r.top``, ``r.width``, ``r.height``
558 the visible rectangle; it must fit wi 551 the visible rectangle; it must fit within the frame buffer resolution
559 returned by :c:func:`VIDIOC_G_FMT` on 552 returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
560 553
561 .. warning:: 554 .. warning::
562 555
563 The decoder may adjust the compose recta 556 The decoder may adjust the compose rectangle to the nearest
564 supported one to meet codec and hardware 557 supported one to meet codec and hardware requirements. The client needs
565 to check the adjusted rectangle returned 558 to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
566 559
567 6. If all the following conditions are met, t 560 6. If all the following conditions are met, the client may resume the decoding
568 instantly: 561 instantly:
569 562
570 * ``sizeimage`` of the new format (determi 563 * ``sizeimage`` of the new format (determined in previous steps) is less
571 than or equal to the size of currently a 564 than or equal to the size of currently allocated buffers,
572 565
573 * the number of buffers currently allocate 566 * the number of buffers currently allocated is greater than or equal to the
574 minimum number of buffers acquired in pr 567 minimum number of buffers acquired in previous steps. To fulfill this
575 requirement, the client may use :c:func: 568 requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
576 buffers. 569 buffers.
577 570
578 In that case, the remaining steps do not a 571 In that case, the remaining steps do not apply and the client may resume
579 the decoding by one of the following actio 572 the decoding by one of the following actions:
580 573
581 * if the ``CAPTURE`` queue is streaming, c 574 * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
582 with the ``V4L2_DEC_CMD_START`` command, 575 with the ``V4L2_DEC_CMD_START`` command,
583 576
584 * if the ``CAPTURE`` queue is not streamin 577 * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
585 on the ``CAPTURE`` queue. 578 on the ``CAPTURE`` queue.
586 579
587 However, if the client intends to change t 580 However, if the client intends to change the buffer set, to lower
588 memory usage or for any other reasons, it 581 memory usage or for any other reasons, it may be achieved by following
589 the steps below. 582 the steps below.
590 583
591 7. **If the** ``CAPTURE`` **queue is streamin 584 7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
592 buffers on the ``CAPTURE`` queue until a b 585 buffers on the ``CAPTURE`` queue until a buffer marked with the
593 ``V4L2_BUF_FLAG_LAST`` flag is dequeued. 586 ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
594 587
595 8. **If the** ``CAPTURE`` **queue is streamin 588 8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
596 on the ``CAPTURE`` queue to stop streaming 589 on the ``CAPTURE`` queue to stop streaming.
597 590
598 .. warning:: 591 .. warning::
599 592
600 The ``OUTPUT`` queue must remain stream 593 The ``OUTPUT`` queue must remain streaming. Calling
601 :c:func:`VIDIOC_STREAMOFF` on it would 594 :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
602 seek. 595 seek.
603 596
604 9. **If the** ``CAPTURE`` **queue has buffers 597 9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
605 buffers using :c:func:`VIDIOC_REQBUFS`. 598 buffers using :c:func:`VIDIOC_REQBUFS`.
606 599
607 * **Required fields:** 600 * **Required fields:**
608 601
609 ``count`` 602 ``count``
610 set to 0. 603 set to 0.
611 604
612 ``type`` 605 ``type``
613 a ``V4L2_BUF_TYPE_*`` enum appropria 606 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
614 607
615 ``memory`` 608 ``memory``
616 follows standard semantics. 609 follows standard semantics.
617 610
618 10. Allocate ``CAPTURE`` buffers via :c:func:` 611 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
619 ``CAPTURE`` queue. 612 ``CAPTURE`` queue.
620 613
621 * **Required fields:** 614 * **Required fields:**
622 615
623 ``count`` 616 ``count``
624 requested number of buffers to alloc 617 requested number of buffers to allocate; greater than zero.
625 618
626 ``type`` 619 ``type``
627 a ``V4L2_BUF_TYPE_*`` enum appropria 620 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
628 621
629 ``memory`` 622 ``memory``
630 follows standard semantics. 623 follows standard semantics.
631 624
632 * **Returned fields:** !! 625 * **Return fields:**
633 626
634 ``count`` 627 ``count``
635 actual number of buffers allocated. 628 actual number of buffers allocated.
636 629
637 .. warning:: 630 .. warning::
638 631
639 The actual number of allocated buffers 632 The actual number of allocated buffers may differ from the ``count``
640 given. The client must check the update 633 given. The client must check the updated value of ``count`` after the
641 call returns. 634 call returns.
642 635
643 .. note:: 636 .. note::
644 637
645 To allocate more than the minimum numbe 638 To allocate more than the minimum number of buffers (for pipeline
646 depth), the client may query the ``V4L2 639 depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
647 control to get the minimum number of bu 640 control to get the minimum number of buffers required, and pass the
648 obtained value plus the number of addit 641 obtained value plus the number of additional buffers needed in the
649 ``count`` field to :c:func:`VIDIOC_REQB 642 ``count`` field to :c:func:`VIDIOC_REQBUFS`.
650 643
651 Alternatively, :c:func:`VIDIOC_CREATE_BUFS 644 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
652 used to have more control over buffer allo 645 used to have more control over buffer allocation. For example, by
653 allocating buffers larger than the current 646 allocating buffers larger than the current ``CAPTURE`` format, future
654 resolution changes can be accommodated. 647 resolution changes can be accommodated.
655 648
656 * **Required fields:** 649 * **Required fields:**
657 650
658 ``count`` 651 ``count``
659 requested number of buffers to alloc 652 requested number of buffers to allocate; greater than zero.
660 653
661 ``type`` 654 ``type``
662 a ``V4L2_BUF_TYPE_*`` enum appropria 655 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
663 656
664 ``memory`` 657 ``memory``
665 follows standard semantics. 658 follows standard semantics.
666 659
667 ``format`` 660 ``format``
668 a format representing the maximum fr 661 a format representing the maximum framebuffer resolution to be
669 accommodated by newly allocated buff 662 accommodated by newly allocated buffers.
670 663
671 * **Returned fields:** !! 664 * **Return fields:**
672 665
673 ``count`` 666 ``count``
674 adjusted to the number of allocated 667 adjusted to the number of allocated buffers.
675 668
676 .. warning:: 669 .. warning::
677 670
678 The actual number of allocated buffers 671 The actual number of allocated buffers may differ from the ``count``
679 given. The client must check the updat 672 given. The client must check the updated value of ``count`` after the
680 call returns. 673 call returns.
681 674
682 .. note:: 675 .. note::
683 676
684 To allocate buffers for a format differ 677 To allocate buffers for a format different than parsed from the stream
685 metadata, the client must proceed as fo 678 metadata, the client must proceed as follows, before the metadata
686 parsing is initiated: 679 parsing is initiated:
687 680
688 * set width and height of the ``OUTPUT` 681 * set width and height of the ``OUTPUT`` format to desired coded resolution to
689 let the decoder configure the ``CAPTU 682 let the decoder configure the ``CAPTURE`` format appropriately,
690 683
691 * query the ``CAPTURE`` format using :c 684 * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
692 until this step. 685 until this step.
693 686
694 The format obtained in the query may be 687 The format obtained in the query may be then used with
695 :c:func:`VIDIOC_CREATE_BUFS` in this st 688 :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
696 689
697 11. Call :c:func:`VIDIOC_STREAMON` on the ``CA 690 11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
698 frames. 691 frames.
699 692
700 Decoding 693 Decoding
701 ======== 694 ========
702 695
703 This state is reached after the `Capture Setup 696 This state is reached after the `Capture Setup` sequence finishes successfully.
704 In this state, the client queues and dequeues 697 In this state, the client queues and dequeues buffers to both queues via
705 :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBU 698 :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
706 semantics. 699 semantics.
707 700
708 The content of the source ``OUTPUT`` buffers d 701 The content of the source ``OUTPUT`` buffers depends on the active coded pixel
709 format and may be affected by codec-specific e 702 format and may be affected by codec-specific extended controls, as stated in
710 the documentation of each format. 703 the documentation of each format.
711 704
712 Both queues operate independently, following t 705 Both queues operate independently, following the standard behavior of V4L2
713 buffer queues and memory-to-memory devices. In 706 buffer queues and memory-to-memory devices. In addition, the order of decoded
714 frames dequeued from the ``CAPTURE`` queue may 707 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
715 coded frames to the ``OUTPUT`` queue, due to p 708 coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
716 format, e.g. frame reordering. 709 format, e.g. frame reordering.
717 710
718 The client must not assume any direct relation 711 The client must not assume any direct relationship between ``CAPTURE``
719 and ``OUTPUT`` buffers and any specific timing 712 and ``OUTPUT`` buffers and any specific timing of buffers becoming
720 available to dequeue. Specifically: 713 available to dequeue. Specifically:
721 714
722 * a buffer queued to ``OUTPUT`` may result in 715 * a buffer queued to ``OUTPUT`` may result in no buffers being produced
723 on ``CAPTURE`` (e.g. if it does not contain 716 on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
724 metadata syntax structures are present in it 717 metadata syntax structures are present in it),
725 718
726 * a buffer queued to ``OUTPUT`` may result in 719 * a buffer queued to ``OUTPUT`` may result in more than one buffer produced
727 on ``CAPTURE`` (if the encoded data containe 720 on ``CAPTURE`` (if the encoded data contained more than one frame, or if
728 returning a decoded frame allowed the decode 721 returning a decoded frame allowed the decoder to return a frame that
729 preceded it in decode, but succeeded it in t 722 preceded it in decode, but succeeded it in the display order),
730 723
731 * a buffer queued to ``OUTPUT`` may result in 724 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
732 ``CAPTURE`` later into decode process, and/o 725 ``CAPTURE`` later into decode process, and/or after processing further
733 ``OUTPUT`` buffers, or be returned out of or 726 ``OUTPUT`` buffers, or be returned out of order, e.g. if display
734 reordering is used, 727 reordering is used,
735 728
736 * buffers may become available on the ``CAPTUR 729 * buffers may become available on the ``CAPTURE`` queue without additional
737 buffers queued to ``OUTPUT`` (e.g. during dr 730 buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
738 ``OUTPUT`` buffers queued in the past whose 731 ``OUTPUT`` buffers queued in the past whose decoding results are only
739 available at later time, due to specifics of 732 available at later time, due to specifics of the decoding process.
740 733
741 .. note:: 734 .. note::
742 735
743 To allow matching decoded ``CAPTURE`` buffe 736 To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
744 originated from, the client can set the ``t 737 originated from, the client can set the ``timestamp`` field of the
745 :c:type:`v4l2_buffer` struct when queuing a 738 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
746 ``CAPTURE`` buffer(s), which resulted from 739 ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
747 will have their ``timestamp`` field set to 740 will have their ``timestamp`` field set to the same value when dequeued.
748 741
749 In addition to the straightforward case of 742 In addition to the straightforward case of one ``OUTPUT`` buffer producing
750 one ``CAPTURE`` buffer, the following cases 743 one ``CAPTURE`` buffer, the following cases are defined:
751 744
752 * one ``OUTPUT`` buffer generates multiple 745 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
753 ``OUTPUT`` timestamp will be copied to mu 746 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
754 747
755 * multiple ``OUTPUT`` buffers generate one 748 * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
756 the ``OUTPUT`` buffer queued first will b 749 the ``OUTPUT`` buffer queued first will be copied.
757 750
758 * the decoding order differs from the displ 751 * the decoding order differs from the display order (i.e. the ``CAPTURE``
759 buffers are out-of-order compared to the 752 buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
760 timestamps will not retain the order of ` 753 timestamps will not retain the order of ``OUTPUT`` timestamps.
761 754
762 .. note:: <<
763 <<
764 The backing memory of ``CAPTURE`` buffers t <<
765 by the stream may be read by the hardware e <<
766 Consequently, the client should avoid writi <<
767 ``CAPTURE`` queue is streaming. Failure to <<
768 corruption of decoded frames. <<
769 <<
770 Similarly, when using a memory type other t <<
771 client should make sure that each ``CAPTURE <<
772 the same backing memory for as long as the <<
773 The reason for this is that V4L2 buffer ind <<
774 identify frames. Thus, if the backing memor <<
775 submitted under a different buffer ID, the <<
776 decode a new frame into it while it is stil <<
777 of the following frames. <<
778 <<
779 During the decoding, the decoder may initiate 755 During the decoding, the decoder may initiate one of the special sequences, as
780 listed below. The sequences will result in the 756 listed below. The sequences will result in the decoder returning all the
781 ``CAPTURE`` buffers that originated from all t 757 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
782 before the sequence started. Last of the buffe 758 before the sequence started. Last of the buffers will have the
783 ``V4L2_BUF_FLAG_LAST`` flag set. To determine 759 ``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
784 must check if there is any pending event and: 760 must check if there is any pending event and:
785 761
786 * if a ``V4L2_EVENT_SOURCE_CHANGE`` event with 762 * if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
787 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, 763 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution
788 Change` sequence needs to be followed, 764 Change` sequence needs to be followed,
789 765
790 * if a ``V4L2_EVENT_EOS`` event is pending, th 766 * if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
791 to be followed. 767 to be followed.
792 768
793 Some of the sequences can be intermixed with e 769 Some of the sequences can be intermixed with each other and need to be handled
794 as they happen. The exact operation is documen 770 as they happen. The exact operation is documented for each sequence.
795 771
796 Should a decoding error occur, it will be repo 772 Should a decoding error occur, it will be reported to the client with the level
797 of details depending on the decoder capabiliti 773 of details depending on the decoder capabilities. Specifically:
798 774
799 * the CAPTURE buffer that contains the results 775 * the CAPTURE buffer that contains the results of the failed decode operation
800 will be returned with the V4L2_BUF_FLAG_ERRO 776 will be returned with the V4L2_BUF_FLAG_ERROR flag set,
801 777
802 * if the decoder is able to precisely report t 778 * if the decoder is able to precisely report the OUTPUT buffer that triggered
803 the error, such buffer will be returned with 779 the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
804 set. 780 set.
805 781
806 In case of a fatal failure that does not allow 782 In case of a fatal failure that does not allow the decoding to continue, any
807 further operations on corresponding decoder fi 783 further operations on corresponding decoder file handle will return the -EIO
808 error code. The client may close the file hand 784 error code. The client may close the file handle and open a new one, or
809 alternatively reinitialize the instance by sto 785 alternatively reinitialize the instance by stopping streaming on both queues,
810 releasing all buffers and performing the Initi 786 releasing all buffers and performing the Initialization sequence again.
811 787
812 Seek 788 Seek
813 ==== 789 ====
814 790
815 Seek is controlled by the ``OUTPUT`` queue, as 791 Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
816 The seek does not require any specific operati 792 The seek does not require any specific operation on the ``CAPTURE`` queue, but
817 it may be affected as per normal decoder opera 793 it may be affected as per normal decoder operation.
818 794
819 1. Stop the ``OUTPUT`` queue to begin the seek 795 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
820 :c:func:`VIDIOC_STREAMOFF`. 796 :c:func:`VIDIOC_STREAMOFF`.
821 797
822 * **Required fields:** 798 * **Required fields:**
823 799
824 ``type`` 800 ``type``
825 a ``V4L2_BUF_TYPE_*`` enum appropriat 801 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
826 802
827 * The decoder will drop all the pending ``O 803 * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
828 treated as returned to the client (follow 804 treated as returned to the client (following standard semantics).
829 805
830 2. Restart the ``OUTPUT`` queue via :c:func:`V 806 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
831 807
832 * **Required fields:** 808 * **Required fields:**
833 809
834 ``type`` 810 ``type``
835 a ``V4L2_BUF_TYPE_*`` enum appropriat 811 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
836 812
837 * The decoder will start accepting new sour 813 * The decoder will start accepting new source bytestream buffers after the
838 call returns. 814 call returns.
839 815
840 3. Start queuing buffers containing coded data 816 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
841 queue until a suitable resume point is foun 817 queue until a suitable resume point is found.
842 818
843 .. note:: 819 .. note::
844 820
845 There is no requirement to begin queuing 821 There is no requirement to begin queuing coded data starting exactly
846 from a resume point (e.g. SPS or a keyfr 822 from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
847 buffers will be processed and returned t 823 buffers will be processed and returned to the client until a suitable
848 resume point is found. While looking fo 824 resume point is found. While looking for a resume point, the decoder
849 should not produce any decoded frames in 825 should not produce any decoded frames into ``CAPTURE`` buffers.
850 826
851 Some hardware is known to mishandle seek 827 Some hardware is known to mishandle seeks to a non-resume point. Such an
852 operation may result in an unspecified n 828 operation may result in an unspecified number of corrupted decoded frames
853 being made available on the ``CAPTURE`` 829 being made available on the ``CAPTURE`` queue. Drivers must ensure that
854 no fatal decoding errors or crashes occu 830 no fatal decoding errors or crashes occur, and implement any necessary
855 handling and workarounds for hardware is 831 handling and workarounds for hardware issues related to seek operations.
856 832
857 .. warning:: 833 .. warning::
858 834
859 In case of the H.264/HEVC codec, the cli 835 In case of the H.264/HEVC codec, the client must take care not to seek
860 over a change of SPS/PPS. Even though th 836 over a change of SPS/PPS. Even though the target frame could be a
861 keyframe, the stale SPS/PPS inside decod 837 keyframe, the stale SPS/PPS inside decoder state would lead to undefined
862 results when decoding. Although the deco 838 results when decoding. Although the decoder must handle that case without
863 a crash or a fatal decode error, the cli 839 a crash or a fatal decode error, the client must not expect a sensible
864 decode output. 840 decode output.
865 841
866 If the hardware can detect such corrupte 842 If the hardware can detect such corrupted decoded frames, then
867 corresponding buffers will be returned t 843 corresponding buffers will be returned to the client with the
868 V4L2_BUF_FLAG_ERROR set. See the `Decodi 844 V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
869 description of decode error reporting. 845 description of decode error reporting.
870 846
871 4. After a resume point is found, the decoder 847 4. After a resume point is found, the decoder will start returning ``CAPTURE``
872 buffers containing decoded frames. 848 buffers containing decoded frames.
873 849
874 .. important:: 850 .. important::
875 851
876 A seek may result in the `Dynamic Resolutio 852 A seek may result in the `Dynamic Resolution Change` sequence being
877 initiated, due to the seek target having de 853 initiated, due to the seek target having decoding parameters different from
878 the part of the stream decoded before the s 854 the part of the stream decoded before the seek. The sequence must be handled
879 as per normal decoder operation. 855 as per normal decoder operation.
880 856
881 .. warning:: 857 .. warning::
882 858
883 It is not specified when the ``CAPTURE`` qu 859 It is not specified when the ``CAPTURE`` queue starts producing buffers
884 containing decoded data from the ``OUTPUT`` 860 containing decoded data from the ``OUTPUT`` buffers queued after the seek,
885 as it operates independently from the ``OUT 861 as it operates independently from the ``OUTPUT`` queue.
886 862
887 The decoder may return a number of remainin 863 The decoder may return a number of remaining ``CAPTURE`` buffers containing
888 decoded frames originating from the ``OUTPU 864 decoded frames originating from the ``OUTPUT`` buffers queued before the
889 seek sequence is performed. 865 seek sequence is performed.
890 866
891 The ``VIDIOC_STREAMOFF`` operation discards 867 The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
892 ``OUTPUT`` buffers, which means that not al 868 ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
893 queued before the seek sequence may have ma 869 queued before the seek sequence may have matching ``CAPTURE`` buffers
894 produced. For example, given the sequence 870 produced. For example, given the sequence of operations on the
895 ``OUTPUT`` queue: 871 ``OUTPUT`` queue:
896 872
897 QBUF(A), QBUF(B), STREAMOFF(), STREAMON() 873 QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
898 874
899 any of the following results on the ``CAPTU 875 any of the following results on the ``CAPTURE`` queue is allowed:
900 876
901 {A', B', G', H'}, {A', G', H'}, {G', H'}. !! 877 {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
902 878
903 To determine the CAPTURE buffer containing 879 To determine the CAPTURE buffer containing the first decoded frame after the
904 seek, the client may observe the timestamps 880 seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
905 buffers or use V4L2_DEC_CMD_STOP and V4L2_D 881 buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
906 decoder. 882 decoder.
907 883
908 .. note:: 884 .. note::
909 885
910 To achieve instantaneous seek, the client m 886 To achieve instantaneous seek, the client may restart streaming on the
911 ``CAPTURE`` queue too to discard decoded, b 887 ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
912 888
913 Dynamic Resolution Change 889 Dynamic Resolution Change
914 ========================= 890 =========================
915 891
916 Streams that include resolution metadata in th 892 Streams that include resolution metadata in the bytestream may require switching
917 to a different resolution during the decoding. 893 to a different resolution during the decoding.
918 894
919 .. note:: 895 .. note::
920 896
921 Not all decoders can detect resolution chan 897 Not all decoders can detect resolution changes. Those that do set the
922 ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for t 898 ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when
923 :c:func:`VIDIOC_ENUM_FMT` is called. 899 :c:func:`VIDIOC_ENUM_FMT` is called.
924 900
925 The sequence starts when the decoder detects a 901 The sequence starts when the decoder detects a coded frame with one or more of
926 the following parameters different from those 902 the following parameters different from those previously established (and
927 reflected by corresponding queries): 903 reflected by corresponding queries):
928 904
929 * coded resolution (``OUTPUT`` width and heigh 905 * coded resolution (``OUTPUT`` width and height),
930 906
931 * visible resolution (selection rectangles), 907 * visible resolution (selection rectangles),
932 908
933 * the minimum number of buffers needed for dec 909 * the minimum number of buffers needed for decoding,
934 910
935 * bit-depth of the bitstream has been changed. 911 * bit-depth of the bitstream has been changed.
936 912
937 Whenever that happens, the decoder must procee 913 Whenever that happens, the decoder must proceed as follows:
938 914
939 1. After encountering a resolution change in 915 1. After encountering a resolution change in the stream, the decoder sends a
940 ``V4L2_EVENT_SOURCE_CHANGE`` event with `` 916 ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
941 ``V4L2_EVENT_SRC_CH_RESOLUTION``. 917 ``V4L2_EVENT_SRC_CH_RESOLUTION``.
942 918
943 .. important:: 919 .. important::
944 920
945 Any client query issued after the decod 921 Any client query issued after the decoder queues the event will return
946 values applying to the stream after the 922 values applying to the stream after the resolution change, including
947 queue formats, selection rectangles and 923 queue formats, selection rectangles and controls.
948 924
949 2. The decoder will then process and decode a 925 2. The decoder will then process and decode all remaining buffers from before
950 the resolution change point. 926 the resolution change point.
951 927
952 * The last buffer from before the change m 928 * The last buffer from before the change must be marked with the
953 ``V4L2_BUF_FLAG_LAST`` flag, similarly t 929 ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
954 930
955 .. warning:: 931 .. warning::
956 932
957 The last buffer may be empty (with :c:t 933 The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
958 = 0) and in that case it must be ignore 934 = 0) and in that case it must be ignored by the client, as it does not
959 contain a decoded frame. 935 contain a decoded frame.
960 936
961 .. note:: 937 .. note::
962 938
963 Any attempt to dequeue more ``CAPTURE`` 939 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
964 with ``V4L2_BUF_FLAG_LAST`` will result 940 with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
965 :c:func:`VIDIOC_DQBUF`. 941 :c:func:`VIDIOC_DQBUF`.
966 942
967 The client must continue the sequence as descr 943 The client must continue the sequence as described below to continue the
968 decoding process. 944 decoding process.
969 945
970 1. Dequeue the source change event. 946 1. Dequeue the source change event.
971 947
972 .. important:: 948 .. important::
973 949
974 A source change triggers an implicit de 950 A source change triggers an implicit decoder drain, similar to the
975 explicit `Drain` sequence. The decoder 951 explicit `Drain` sequence. The decoder is stopped after it completes.
976 The decoding process must be resumed wi 952 The decoding process must be resumed with either a pair of calls to
977 :c:func:`VIDIOC_STREAMOFF` and :c:func: 953 :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
978 ``CAPTURE`` queue, or a call to :c:func 954 ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
979 ``V4L2_DEC_CMD_START`` command. 955 ``V4L2_DEC_CMD_START`` command.
980 956
981 2. Continue with the `Capture Setup` sequence 957 2. Continue with the `Capture Setup` sequence.
982 958
983 .. note:: 959 .. note::
984 960
985 During the resolution change sequence, the 961 During the resolution change sequence, the ``OUTPUT`` queue must remain
986 streaming. Calling :c:func:`VIDIOC_STREAMOF 962 streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
987 abort the sequence and initiate a seek. 963 abort the sequence and initiate a seek.
988 964
989 In principle, the ``OUTPUT`` queue operates 965 In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
990 queue and this remains true for the duratio 966 queue and this remains true for the duration of the entire resolution change
991 sequence as well. 967 sequence as well.
992 968
993 The client should, for best performance and 969 The client should, for best performance and simplicity, keep queuing/dequeuing
994 buffers to/from the ``OUTPUT`` queue even w 970 buffers to/from the ``OUTPUT`` queue even while processing this sequence.
995 971
996 Drain 972 Drain
997 ===== 973 =====
998 974
999 To ensure that all queued ``OUTPUT`` buffers h 975 To ensure that all queued ``OUTPUT`` buffers have been processed and related
1000 ``CAPTURE`` buffers are given to the client, 976 ``CAPTURE`` buffers are given to the client, the client must follow the drain
1001 sequence described below. After the drain seq 977 sequence described below. After the drain sequence ends, the client has
1002 received all decoded frames for all ``OUTPUT` 978 received all decoded frames for all ``OUTPUT`` buffers queued before the
1003 sequence was started. 979 sequence was started.
1004 980
1005 1. Begin drain by issuing :c:func:`VIDIOC_DEC 981 1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
1006 982
1007 * **Required fields:** 983 * **Required fields:**
1008 984
1009 ``cmd`` 985 ``cmd``
1010 set to ``V4L2_DEC_CMD_STOP``. 986 set to ``V4L2_DEC_CMD_STOP``.
1011 987
1012 ``flags`` 988 ``flags``
1013 set to 0. 989 set to 0.
1014 990
1015 ``pts`` 991 ``pts``
1016 set to 0. 992 set to 0.
1017 993
1018 .. warning:: 994 .. warning::
1019 995
1020 The sequence can be only initiated if b 996 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
1021 queues are streaming. For compatibility 997 queues are streaming. For compatibility reasons, the call to
1022 :c:func:`VIDIOC_DECODER_CMD` will not f 998 :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
1023 not streaming, but at the same time it 999 not streaming, but at the same time it will not initiate the `Drain`
1024 sequence and so the steps described bel 1000 sequence and so the steps described below would not be applicable.
1025 1001
1026 2. Any ``OUTPUT`` buffers queued by the clien 1002 2. Any ``OUTPUT`` buffers queued by the client before the
1027 :c:func:`VIDIOC_DECODER_CMD` was issued wi 1003 :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
1028 normal. The client must continue to handle 1004 normal. The client must continue to handle both queues independently,
1029 similarly to normal decode operation. This 1005 similarly to normal decode operation. This includes:
1030 1006
1031 * handling any operations triggered as a r 1007 * handling any operations triggered as a result of processing those buffers,
1032 such as the `Dynamic Resolution Change` 1008 such as the `Dynamic Resolution Change` sequence, before continuing with
1033 the drain sequence, 1009 the drain sequence,
1034 1010
1035 * queuing and dequeuing ``CAPTURE`` buffer 1011 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1036 ``V4L2_BUF_FLAG_LAST`` flag is dequeued, 1012 ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
1037 1013
1038 .. warning:: 1014 .. warning::
1039 1015
1040 The last buffer may be empty (with :c 1016 The last buffer may be empty (with :c:type:`v4l2_buffer`
1041 ``bytesused`` = 0) and in that case i 1017 ``bytesused`` = 0) and in that case it must be ignored by the client,
1042 as it does not contain a decoded fram 1018 as it does not contain a decoded frame.
1043 1019
1044 .. note:: 1020 .. note::
1045 1021
1046 Any attempt to dequeue more ``CAPTURE 1022 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
1047 marked with ``V4L2_BUF_FLAG_LAST`` wi 1023 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1048 :c:func:`VIDIOC_DQBUF`. 1024 :c:func:`VIDIOC_DQBUF`.
1049 1025
1050 * dequeuing processed ``OUTPUT`` buffers, 1026 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
1051 before the ``V4L2_DEC_CMD_STOP`` command 1027 before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
1052 1028
1053 * dequeuing the ``V4L2_EVENT_EOS`` event, 1029 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
1054 1030
1055 .. note:: 1031 .. note::
1056 1032
1057 For backwards compatibility, the decode 1033 For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
1058 event when the last frame has been deco 1034 event when the last frame has been decoded and all frames are ready to be
1059 dequeued. It is a deprecated behavior a 1035 dequeued. It is a deprecated behavior and the client must not rely on it.
1060 The ``V4L2_BUF_FLAG_LAST`` buffer flag 1036 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
1061 1037
1062 3. Once all the ``OUTPUT`` buffers queued bef 1038 3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
1063 are dequeued and the last ``CAPTURE`` buff 1039 are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
1064 stopped and it will accept, but not proces 1040 stopped and it will accept, but not process, any newly queued ``OUTPUT``
1065 buffers until the client issues any of the 1041 buffers until the client issues any of the following operations:
1066 1042
1067 * ``V4L2_DEC_CMD_START`` - the decoder wil 1043 * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
1068 operation normally, with all the state f 1044 operation normally, with all the state from before the drain,
1069 1045
1070 * a pair of :c:func:`VIDIOC_STREAMOFF` and 1046 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
1071 ``CAPTURE`` queue - the decoder will res 1047 ``CAPTURE`` queue - the decoder will resume the operation normally,
1072 however any ``CAPTURE`` buffers still in 1048 however any ``CAPTURE`` buffers still in the queue will be returned to the
1073 client, 1049 client,
1074 1050
1075 * a pair of :c:func:`VIDIOC_STREAMOFF` and 1051 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
1076 ``OUTPUT`` queue - any pending source bu 1052 ``OUTPUT`` queue - any pending source buffers will be returned to the
1077 client and the `Seek` sequence will be t 1053 client and the `Seek` sequence will be triggered.
1078 1054
1079 .. note:: 1055 .. note::
1080 1056
1081 Once the drain sequence is initiated, the 1057 Once the drain sequence is initiated, the client needs to drive it to
1082 completion, as described by the steps abov 1058 completion, as described by the steps above, unless it aborts the process by
1083 issuing :c:func:`VIDIOC_STREAMOFF` on any 1059 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
1084 queues. The client is not allowed to issu 1060 queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
1085 ``V4L2_DEC_CMD_STOP`` again while the drai 1061 ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
1086 will fail with -EBUSY error code if attemp 1062 will fail with -EBUSY error code if attempted.
1087 1063
1088 Although not mandatory, the availability o 1064 Although not mandatory, the availability of decoder commands may be queried
1089 using :c:func:`VIDIOC_TRY_DECODER_CMD`. 1065 using :c:func:`VIDIOC_TRY_DECODER_CMD`.
1090 1066
1091 End of Stream 1067 End of Stream
1092 ============= 1068 =============
1093 1069
1094 If the decoder encounters an end of stream ma 1070 If the decoder encounters an end of stream marking in the stream, the decoder
1095 will initiate the `Drain` sequence, which the 1071 will initiate the `Drain` sequence, which the client must handle as described
1096 above, skipping the initial :c:func:`VIDIOC_D 1072 above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
1097 1073
1098 Commit Points 1074 Commit Points
1099 ============= 1075 =============
1100 1076
1101 Setting formats and allocating buffers trigge 1077 Setting formats and allocating buffers trigger changes in the behavior of the
1102 decoder. 1078 decoder.
1103 1079
1104 1. Setting the format on the ``OUTPUT`` queue 1080 1. Setting the format on the ``OUTPUT`` queue may change the set of formats
1105 supported/advertised on the ``CAPTURE`` qu 1081 supported/advertised on the ``CAPTURE`` queue. In particular, it also means
1106 that the ``CAPTURE`` format may be reset a 1082 that the ``CAPTURE`` format may be reset and the client must not rely on the
1107 previously set format being preserved. 1083 previously set format being preserved.
1108 1084
1109 2. Enumerating formats on the ``CAPTURE`` que 1085 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
1110 supported for the current ``OUTPUT`` forma 1086 supported for the current ``OUTPUT`` format.
1111 1087
1112 3. Setting the format on the ``CAPTURE`` queu 1088 3. Setting the format on the ``CAPTURE`` queue does not change the list of
1113 formats available on the ``OUTPUT`` queue. 1089 formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
1114 format that is not supported for the curre 1090 format that is not supported for the currently selected ``OUTPUT`` format
1115 will result in the decoder adjusting the r 1091 will result in the decoder adjusting the requested ``CAPTURE`` format to a
1116 supported one. 1092 supported one.
1117 1093
1118 4. Enumerating formats on the ``OUTPUT`` queu 1094 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
1119 supported coded formats, irrespectively of 1095 supported coded formats, irrespectively of the current ``CAPTURE`` format.
1120 1096
1121 5. While buffers are allocated on any of the 1097 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
1122 the client must not change the format on t 1098 the client must not change the format on the ``OUTPUT`` queue. Drivers will
1123 return the -EBUSY error code for any such 1099 return the -EBUSY error code for any such format change attempt.
1124 1100
1125 To summarize, setting formats and allocation 1101 To summarize, setting formats and allocation must always start with the
1126 ``OUTPUT`` queue and the ``OUTPUT`` queue is 1102 ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
1127 set of supported formats for the ``CAPTURE`` 1103 set of supported formats for the ``CAPTURE`` queue.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.