1 .. SPDX-License-Identifier: GPL-2.0
5 *************************************************
6 Memory-to-Memory Stateful Video Decoder Interface
7 *************************************************
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 decodes them into raw video frames in
11 display order. The decoder is expected not to require any additional information
12 from the client to process these buffers.
14 Performing software parsing, processing etc. of the stream in the driver in
15 order to support this interface is strongly discouraged. In case such
16 operations are needed, use of the Stateless Video Decoder Interface (in
17 development) is strongly advised.
19 Conventions and Notations Used in This Document
20 ===============================================
22 1. The general V4L2 API rules apply if not specified in this document
25 2. The meaning of words "must", "may", "should", etc. is as per `RFC
26 2119 <https://tools.ietf.org/html/rfc2119>`_.
28 3. All steps not marked "optional" are required.
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` and :c:func:`VIDIOC_S_CTRL`,
32 unless specified otherwise.
34 5. 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.
38 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
41 7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE``
42 queue containing data that resulted from processing buffer A.
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.
57 the application communicating with the decoder or encoder implementing
61 encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see
65 height for given coded 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.
73 width for given coded resolution.
76 processing unit of the HEVC codec (corresponds to macroblock units in
78 can use block structures of up to 64×64 pixels.
79 Good at sub-partitioning the picture into variable sized structures.
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.
88 data resulting from the decode process; see ``CAPTURE``.
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.
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.
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).
107 an encoded frame that does not reference frames decoded earlier, i.e.
108 can be decoded fully on its own.
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).
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.
124 Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
127 uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
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.
136 data fed to the decoder or encoder; see ``OUTPUT``.
139 height in pixels for given source resolution; relevant to encoders only.
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
147 width in pixels for given source resolution; relevant to encoders only.
150 Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
153 additional (non-visual) information contained inside encoded bytestream;
154 for example: coded resolution, visible resolution, codec profile.
157 height for given visible resolution; display height.
160 stream resolution of the visible picture, in pixels, to be used for
161 display purposes; must be smaller or equal to coded resolution;
165 width for given visible resolution; display width.
170 .. kernel-render:: DOT
171 :alt: DOT digraph of decoder state machine
172 :caption: Decoder State Machine
174 digraph decoder_state_machine {
175 node [shape = doublecircle, label="Decoding"] Decoding;
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;
185 node [shape = point]; qi
186 qi -> Initialization [ label = "open()" ];
188 Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
190 CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
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;
199 ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
200 ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
202 EoS -> Drain [ label = "Implicit\ndrain" ];
204 Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
205 Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
207 Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
208 Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
210 Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
211 Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
214 Querying Capabilities
215 =====================
217 1. To enumerate the set of coded formats supported by the decoder, the
218 client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
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.
227 2. To enumerate the set of supported raw formats, the client may call
228 :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
230 * Only the formats supported for the format currently active on ``OUTPUT``
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``.
237 3. 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``.
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.
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
250 4. 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`.
257 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
259 * **Required fields:**
262 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
265 a coded pixel format.
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.
274 desired size of ``OUTPUT`` buffers; the decoder may adjust it to
275 match hardware requirements.
278 follow standard semantics.
280 * **Returned fields:**
283 adjusted size of ``OUTPUT`` buffers.
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
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.
300 2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on
303 * **Required fields:**
306 requested number of buffers to allocate; greater than zero.
309 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
312 follows standard semantics.
314 * **Returned fields:**
317 the actual number of buffers allocated.
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
325 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
326 used to have more control over buffer allocation.
328 * **Required fields:**
331 requested number of buffers to allocate; greater than zero.
334 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
337 follows standard semantics.
340 follows standard semantics.
342 * **Returned fields:**
345 adjusted to the number of allocated buffers.
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
353 3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
355 4. **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``.
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
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.
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.
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.
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.
398 No decoded frames are produced during this phase.
400 5. Continue with the `Capture Setup` sequence.
405 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
406 destination buffers parsed/decoded from the bytestream.
408 * **Required fields:**
411 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
413 * **Returned fields:**
415 ``width``, ``height``
416 frame buffer resolution for the decoded frames.
419 pixel format for decoded frames.
421 ``num_planes`` (for _MPLANE ``type`` only)
422 number of planes for pixelformat.
424 ``sizeimage``, ``bytesperline``
425 as per standard semantics; matching frame buffer format.
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.
435 2. **Optional.** Acquire the visible resolution via
436 :c:func:`VIDIOC_G_SELECTION`.
438 * **Required fields:**
441 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
444 set to ``V4L2_SEL_TGT_COMPOSE``.
446 * **Returned fields:**
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``.
452 * The following selection targets are supported on ``CAPTURE``:
454 ``V4L2_SEL_TGT_CROP_BOUNDS``
455 corresponds to the coded resolution of the stream.
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.
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.
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.
472 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
473 equal to ``V4L2_SEL_TGT_CROP``.
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.
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.
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.
491 3. **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`.
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.
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.
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.
517 4. **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`.
521 * **Required fields:**
524 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
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.
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
538 5. **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.
542 * **Required fields:**
545 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
548 set to ``V4L2_SEL_TGT_COMPOSE``.
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.
555 * **Returned fields:**
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``.
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`.
567 6. If all the following conditions are met, the client may resume the decoding
570 * ``sizeimage`` of the new format (determined in previous steps) is less
571 than or equal to the size of currently allocated buffers,
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
578 In that case, the remaining steps do not apply and the client may resume
579 the decoding by one of the following actions:
581 * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
582 with the ``V4L2_DEC_CMD_START`` command,
584 * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
585 on the ``CAPTURE`` queue.
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
591 7. **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.
595 8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
596 on the ``CAPTURE`` queue to stop streaming.
600 The ``OUTPUT`` queue must remain streaming. Calling
601 :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
604 9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
605 buffers using :c:func:`VIDIOC_REQBUFS`.
607 * **Required fields:**
613 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
616 follows standard semantics.
618 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
621 * **Required fields:**
624 requested number of buffers to allocate; greater than zero.
627 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
630 follows standard semantics.
632 * **Returned fields:**
635 actual number of buffers allocated.
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
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`.
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.
656 * **Required fields:**
659 requested number of buffers to allocate; greater than zero.
662 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
665 follows standard semantics.
668 a format representing the maximum framebuffer resolution to be
669 accommodated by newly allocated buffers.
671 * **Returned fields:**
674 adjusted to the number of allocated buffers.
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
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:
688 * set width and height of the ``OUTPUT`` format to desired coded resolution to
689 let the decoder configure the ``CAPTURE`` format appropriately,
691 * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
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.
697 11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
703 This state is reached after the `Capture Setup` sequence finishes successfully.
704 In 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
708 The content of the source ``OUTPUT`` buffers depends on the active coded pixel
709 format and may be affected by codec-specific extended controls, as stated in
710 the documentation of each format.
712 Both queues operate independently, following the standard behavior of V4L2
713 buffer queues and memory-to-memory devices. In addition, the order of decoded
714 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
715 coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
716 format, e.g. frame reordering.
718 The client must not assume any direct relationship between ``CAPTURE``
719 and ``OUTPUT`` buffers and any specific timing of buffers becoming
720 available to dequeue. Specifically:
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),
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),
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
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.
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.
749 In addition to the straightforward case of one ``OUTPUT`` buffer producing
750 one ``CAPTURE`` buffer, the following cases are defined:
752 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
753 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
755 * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
756 the ``OUTPUT`` buffer queued first will be copied.
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.
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.
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.
779 During the decoding, the decoder may initiate one of the special sequences, as
780 listed below. The sequences will result in the decoder returning all the
781 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
782 before 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
784 must check if there is any pending event and:
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,
790 * if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
793 Some of the sequences can be intermixed with each other and need to be handled
794 as they happen. The exact operation is documented for each sequence.
796 Should a decoding error occur, it will be reported to the client with the level
797 of details depending on the decoder capabilities. Specifically:
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,
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
806 In case of a fatal failure that does not allow the decoding to continue, any
807 further operations on corresponding decoder file handle will return the -EIO
808 error code. The client may close the file handle and open a new one, or
809 alternatively reinitialize the instance by stopping streaming on both queues,
810 releasing all buffers and performing the Initialization sequence again.
815 Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
816 The seek does not require any specific operation on the ``CAPTURE`` queue, but
817 it may be affected as per normal decoder operation.
819 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
820 :c:func:`VIDIOC_STREAMOFF`.
822 * **Required fields:**
825 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
827 * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
828 treated as returned to the client (following standard semantics).
830 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
832 * **Required fields:**
835 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
837 * The decoder will start accepting new source bytestream buffers after the
840 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
841 queue until a suitable resume point is found.
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.
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.
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
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.
871 4. After a resume point is found, the decoder will start returning ``CAPTURE``
872 buffers containing decoded frames.
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.
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.
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.
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
897 QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
899 any of the following results on the ``CAPTURE`` queue is allowed:
901 {A', B', G', H'}, {A', G', H'}, {G', H'}.
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
910 To achieve instantaneous seek, the client may restart streaming on the
911 ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
913 Dynamic Resolution Change
914 =========================
916 Streams that include resolution metadata in the bytestream may require switching
917 to a different resolution during the decoding.
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.
925 The sequence starts when the decoder detects a coded frame with one or more of
926 the following parameters different from those previously established (and
927 reflected by corresponding queries):
929 * coded resolution (``OUTPUT`` width and height),
931 * visible resolution (selection rectangles),
933 * the minimum number of buffers needed for decoding,
935 * bit-depth of the bitstream has been changed.
937 Whenever that happens, the decoder must proceed as follows:
939 1. 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``.
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.
949 2. The decoder will then process and decode all remaining buffers from before
950 the resolution change point.
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.
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.
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`.
967 The client must continue the sequence as described below to continue the
970 1. Dequeue the source change event.
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.
981 2. Continue with the `Capture Setup` sequence.
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.
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
993 The client should, for best performance and simplicity, keep queuing/dequeuing
994 buffers to/from the ``OUTPUT`` queue even while processing this sequence.
999 To 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
1001 sequence described below. After the drain sequence ends, the client has
1002 received all decoded frames for all ``OUTPUT`` buffers queued before the
1003 sequence was started.
1005 1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
1007 * **Required fields:**
1010 set to ``V4L2_DEC_CMD_STOP``.
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.
1026 2. 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:
1031 * handling any operations triggered as a result of processing those buffers,
1032 such as the `Dynamic Resolution Change` sequence, before continuing with
1035 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1036 ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
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.
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`.
1050 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
1051 before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
1053 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
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.
1062 3. 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:
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,
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
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.
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.
1088 Although not mandatory, the availability of decoder commands may be queried
1089 using :c:func:`VIDIOC_TRY_DECODER_CMD`.
1094 If the decoder encounters an end of stream marking in the stream, the decoder
1095 will initiate the `Drain` sequence, which the client must handle as described
1096 above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
1101 Setting formats and allocating buffers trigger changes in the behavior of the
1104 1. 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.
1109 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
1110 supported for the current ``OUTPUT`` format.
1112 3. 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
1118 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
1119 supported coded formats, irrespectively of the current ``CAPTURE`` format.
1121 5. 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.
1125 To summarize, setting formats and allocation must always start with the
1126 ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
1127 set of supported formats for the ``CAPTURE`` queue.
projects / linux-modified.git / blob