Lines Matching +full:output +full:- +full:only
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``
44 .. _decoder-glossary:
79 Good at sub-partitioning the picture into variable sized structures.
84 ``OUTPUT`` buffers must be queued by the client in decode order; for
91 the order in which frames must be displayed; for encoders, ``OUTPUT``
103 Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
112 block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
116 OUTPUT
121 from ``OUTPUT`` buffers.
136 data fed to the decoder or encoder; see ``OUTPUT``.
139 height in pixels for given source resolution; relevant to encoders only.
144 encoders only.
147 width in pixels for given source resolution; relevant to encoders only.
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)" ];
218 client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
224 In particular whether or not the decoder has a full-fledged bytestream
230 * Only the formats supported for the format currently active on ``OUTPUT``
234 the client must first set that coded format on ``OUTPUT`` and then
248 ``OUTPUT``.
251 ``OUTPUT``, if applicable, may be queried using their respective controls
257 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
262 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
268 coded resolution of the stream; required only if it cannot be parsed
274 desired size of ``OUTPUT`` buffers; the decoder may adjust it to
283 adjusted size of ``OUTPUT`` buffers.
296 Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
301 ``OUTPUT``.
309 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
325 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
334 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
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
357 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
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
421 ``num_planes`` (for _MPLANE ``type`` only)
463 the rectangle within the coded resolution to be output to
464 ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
478 read-only on hardware without additional compose/scaling capabilities.
487 The values are guaranteed to be meaningful only after the decoder
498 The decoder will return only formats supported for the currently
499 established coded format, as per the ``OUTPUT`` format and/or stream
506 1920x1088 and lower, but only YUV for higher resolutions (due to
553 read-only on hardware without additional compose/scaling capabilities.
600 The ``OUTPUT`` queue must remain streaming. Calling
688 * set width and height of the ``OUTPUT`` format to desired coded resolution to
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
713 buffer queues and memory-to-memory devices. In addition, the order of decoded
715 coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
719 and ``OUTPUT`` buffers and any specific timing of buffers becoming
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
726 * a buffer queued to ``OUTPUT`` may result in more than one buffer produced
731 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
733 ``OUTPUT`` buffers, or be returned out of order, e.g. if display
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
743 To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
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
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.
759 buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
760 timestamps will not retain the order of ``OUTPUT`` timestamps.
781 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
802 * if the decoder is able to precisely report the OUTPUT buffer that triggered
807 further operations on corresponding decoder file handle will return the -EIO
815 Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
819 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
825 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
827 * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
830 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
835 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
840 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
846 from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
851 Some hardware is known to mishandle seeks to a non-resume point. Such an
864 decode output.
884 containing decoded data from the ``OUTPUT`` buffers queued after the seek,
885 as it operates independently from the ``OUTPUT`` queue.
888 decoded frames originating from the ``OUTPUT`` buffers queued before the
892 ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
895 ``OUTPUT`` queue:
904 seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
929 * coded resolution (``OUTPUT`` width and height),
935 * bit-depth of the bitstream has been changed.
964 with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
985 During the resolution change sequence, the ``OUTPUT`` queue must remain
986 streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
989 In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
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
1002 received all decoded frames for all ``OUTPUT`` buffers queued before the
1020 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
1026 2. Any ``OUTPUT`` buffers queued by the client before the
1047 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1050 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
1062 3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
1064 stopped and it will accept, but not process, any newly queued ``OUTPUT``
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
1083 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
1086 will fail with -EBUSY error code if attempted.
1104 1. Setting the format on the ``OUTPUT`` queue may change the set of formats
1109 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
1110 supported for the current ``OUTPUT`` format.
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
1118 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
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.
1126 ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the