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
77 coded format includes a feature of frame reordering; for decoders,
90 Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
91 raw frame available for reference in further decoding steps.
97 Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
101 an encoded frame that does not reference frames decoded earlier, i.e.
106 block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
110 the source buffer queue; for decoders, the queue of buffers containing
146 additional (non-visual) information contained inside encoded bytestream;
163 .. kernel-render:: DOT
179 qi -> Initialization [ label = "open()" ];
181 Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
183 CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
185 Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
186 Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
187 Decoding -> EoS [ label = "EoS mark\nin the stream" ];
188 Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
189 Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
190 Decoding -> Decoding;
192 ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
193 ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
195 EoS -> Drain [ label = "Implicit\ndrain" ];
197 Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
198 Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
200 Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
201 Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
203 Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
204 Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
217 In particular whether or not the decoder has a full-fledged bytestream
239 will include all possible frame buffer resolutions supported by the
278 * The ``CAPTURE`` format will be updated with an appropriate frame buffer
319 used to have more control over buffer allocation.
356 * It is not an error if the first buffer does not contain enough data for
360 * If data in a buffer that triggers the event is required to decode the
361 first frame, it will not be returned to the client, until the
362 initialization sequence completes and the frame is decoded.
381 to non-zero values matching the coded size of the stream, skip this step
409 frame buffer resolution for the decoded frames.
418 as per standard semantics; matching frame buffer format.
442 the visible rectangle; it must fit within the frame buffer resolution
451 the rectangle covering the part of the ``CAPTURE`` buffer that
457 ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
461 the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
462 frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
469 the rectangle inside a ``CAPTURE`` buffer into which the cropped
470 frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
471 read-only on hardware without additional compose/scaling capabilities.
474 the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
523 frame buffer resolution of the decoded stream; typically unchanged from
544 the rectangle inside a ``CAPTURE`` buffer into which the cropped
545 frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
546 read-only on hardware without additional compose/scaling capabilities.
551 the visible rectangle; it must fit within the frame buffer resolution
580 However, if the client intends to change the buffer set, to lower
585 buffers on the ``CAPTURE`` queue until a buffer marked with the
645 used to have more control over buffer allocation. For example, by
702 format and may be affected by codec-specific extended controls, as stated in
706 buffer queues and memory-to-memory devices. In addition, the order of decoded
709 format, e.g. frame reordering.
715 * a buffer queued to ``OUTPUT`` may result in no buffers being produced
719 * a buffer queued to ``OUTPUT`` may result in more than one buffer produced
720 on ``CAPTURE`` (if the encoded data contained more than one frame, or if
721 returning a decoded frame allowed the decoder to return a frame that
724 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
738 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
739 ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
742 In addition to the straightforward case of one ``OUTPUT`` buffer producing
743 one ``CAPTURE`` buffer, the following cases are defined:
745 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
748 * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
749 the ``OUTPUT`` buffer queued first will be copied.
752 buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
775 * the CAPTURE buffer that contains the results of the failed decode operation
778 * if the decoder is able to precisely report the OUTPUT buffer that triggered
779 the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
783 further operations on corresponding decoder file handle will return the -EIO
827 Some hardware is known to mishandle seeks to a non-resume point. Such an
836 over a change of SPS/PPS. Even though the target frame could be a
879 To determine the CAPTURE buffer containing the first decoded frame after the
901 The sequence starts when the decoder detects a coded frame with one or more of
911 * bit-depth of the bitstream has been changed.
928 * The last buffer from before the change must be marked with the
933 The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
935 contain a decoded frame.
939 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
940 with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1011 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1016 The last buffer may be empty (with :c:type:`v4l2_buffer`
1018 as it does not contain a decoded frame.
1022 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
1023 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1034 event when the last frame has been decoded and all frames are ready to be
1036 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
1039 are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
1043 * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
1047 ``CAPTURE`` queue - the decoder will resume the operation normally,
1052 ``OUTPUT`` queue - any pending source buffers will be returned to the
1062 will fail with -EBUSY error code if attempted.
1099 return the -EBUSY error code for any such format change attempt.