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:
78 ``OUTPUT`` buffers must be queued by the client in decode order; for
85 the order in which frames must be displayed; for encoders, ``OUTPUT``
97 Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
106 block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
109 OUTPUT
114 from ``OUTPUT`` buffers.
129 data fed to the decoder or encoder; see ``OUTPUT``.
132 height in pixels for given source resolution; relevant to encoders only.
137 encoders only.
140 width in pixels for given source resolution; relevant to encoders only.
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)" ];
211 client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
217 In particular whether or not the decoder has a full-fledged bytestream
223 * Only the formats supported for the format currently active on ``OUTPUT``
227 the client must first set that coded format on ``OUTPUT`` and then
241 ``OUTPUT``.
244 ``OUTPUT``, if applicable, may be queried using their respective controls
250 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
255 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
261 coded resolution of the stream; required only if it cannot be parsed
267 desired size of ``OUTPUT`` buffers; the decoder may adjust it to
276 adjusted size of ``OUTPUT`` buffers.
289 Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
294 ``OUTPUT``.
302 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
318 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
327 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
346 3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
348 4. **This step only applies to coded formats that contain resolution information
350 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
380 its own may attempt to set the width and height of the ``OUTPUT`` format
381 to non-zero values matching the coded size of the stream, skip this step
414 ``num_planes`` (for _MPLANE ``type`` only)
456 the rectangle within the coded resolution to be output to
457 ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
471 read-only on hardware without additional compose/scaling capabilities.
480 The values are guaranteed to be meaningful only after the decoder
491 The decoder will return only formats supported for the currently
492 established coded format, as per the ``OUTPUT`` format and/or stream
499 1920x1088 and lower, but only YUV for higher resolutions (due to
546 read-only on hardware without additional compose/scaling capabilities.
593 The ``OUTPUT`` queue must remain streaming. Calling
681 * set width and height of the ``OUTPUT`` format to desired coded resolution to
701 The content of the source ``OUTPUT`` buffers depends on the active coded pixel
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
708 coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
712 and ``OUTPUT`` buffers and any specific timing of buffers becoming
715 * a buffer queued to ``OUTPUT`` may result in no buffers being produced
716 on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
719 * a buffer queued to ``OUTPUT`` may result in more than one buffer produced
724 * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
726 ``OUTPUT`` buffers, or be returned out of order, e.g. if display
730 buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
731 ``OUTPUT`` buffers queued in the past whose decoding results are only
736 To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
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
745 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
746 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
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``
753 timestamps will not retain the order of ``OUTPUT`` timestamps.
757 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
778 * if the decoder is able to precisely report the OUTPUT buffer that triggered
783 further operations on corresponding decoder file handle will return the -EIO
791 Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
795 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
801 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
803 * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
806 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
811 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
816 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
822 from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
827 Some hardware is known to mishandle seeks to a non-resume point. Such an
840 decode output.
860 containing decoded data from the ``OUTPUT`` buffers queued after the seek,
861 as it operates independently from the ``OUTPUT`` queue.
864 decoded frames originating from the ``OUTPUT`` buffers queued before the
868 ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
871 ``OUTPUT`` queue:
880 seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
905 * coded resolution (``OUTPUT`` width and height),
911 * bit-depth of the bitstream has been changed.
940 with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
961 During the resolution change sequence, the ``OUTPUT`` queue must remain
962 streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
965 In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
970 buffers to/from the ``OUTPUT`` queue even while processing this sequence.
975 To ensure that all queued ``OUTPUT`` buffers have been processed and related
978 received all decoded frames for all ``OUTPUT`` buffers queued before the
996 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
1002 2. Any ``OUTPUT`` buffers queued by the client before the
1023 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1026 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
1038 3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
1040 stopped and it will accept, but not process, any newly queued ``OUTPUT``
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
1059 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
1062 will fail with -EBUSY error code if attempted.
1080 1. Setting the format on the ``OUTPUT`` queue may change the set of formats
1085 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
1086 supported for the current ``OUTPUT`` format.
1089 formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
1090 format that is not supported for the currently selected ``OUTPUT`` format
1094 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
1097 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
1098 the client must not change the format on the ``OUTPUT`` queue. Drivers will
1099 return the -EBUSY error code for any such format change attempt.
1102 ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the