Lines Matching +full:frame +full:- +full:buffer
1 .. SPDX-License-Identifier: GPL-2.0
6 Memory-to-Memory Stateful Video Decoder Interface
9 A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
34 5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
35 used interchangeably with multi-planar API, unless specified otherwise,
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.
44 .. _decoder-glossary:
50 the destination buffer queue; for decoders, the queue of buffers containing
79 Good at sub-partitioning the picture into variable sized structures.
83 coded format includes a feature of frame reordering; for decoders,
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
107 an encoded frame that does not reference frames decoded earlier, i.e.
112 block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
117 the source buffer queue; for decoders, the queue of buffers containing
153 additional (non-visual) information contained inside encoded bytestream;
170 .. kernel-render:: DOT
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)" ];
224 In particular whether or not the decoder has a full-fledged bytestream
246 will include all possible frame buffer resolutions supported by the
285 * The ``CAPTURE`` format will be updated with an appropriate frame buffer
326 used to have more control over buffer allocation.
363 * It is not an error if the first buffer does not contain enough data for
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.
388 to non-zero values matching the coded size of the stream, skip this step
416 frame buffer resolution for the decoded frames.
425 as per standard semantics; matching frame buffer format.
449 the visible rectangle; it must fit within the frame buffer resolution
458 the rectangle covering the part of the ``CAPTURE`` buffer that
464 ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
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
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.
481 the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
530 frame buffer resolution of the decoded stream; typically unchanged from
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.
558 the visible rectangle; it must fit within the frame buffer resolution
587 However, if the client intends to change the buffer set, to lower
592 buffers on the ``CAPTURE`` queue until a buffer marked with the
652 used to have more control over buffer allocation. For example, by
709 format and may be affected by codec-specific extended controls, as stated in
713 buffer queues and memory-to-memory devices. In addition, the order of decoded
716 format, e.g. frame reordering.
722 * a buffer queued to ``OUTPUT`` may result in no buffers being produced
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
731 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
745 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
746 ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
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
755 * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
756 the ``OUTPUT`` buffer queued first will be copied.
759 buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
771 client should make sure that each ``CAPTURE`` buffer is always queued with
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
799 * the CAPTURE buffer that contains the results of the failed decode operation
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
807 further operations on corresponding decoder file handle will return the -EIO
851 Some hardware is known to mishandle seeks to a non-resume point. Such an
860 over a change of SPS/PPS. Even though the target frame could be a
903 To determine the CAPTURE buffer containing the first decoded frame after the
925 The sequence starts when the decoder detects a coded frame with one or more of
935 * bit-depth of the bitstream has been changed.
952 * The last buffer from before the change must be marked with the
957 The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
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
1035 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1040 The last buffer may be empty (with :c:type:`v4l2_buffer`
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
1058 event when the last frame has been decoded and all frames are ready to be
1060 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
1063 are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
1067 * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
1071 ``CAPTURE`` queue - the decoder will resume the operation normally,
1076 ``OUTPUT`` queue - any pending source buffers will be returned to the
1086 will fail with -EBUSY error code if attempted.
1123 return the -EBUSY error code for any such format change attempt.