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