Lines Matching +full:capture +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:
49 CAPTURE
54 into ``CAPTURE`` buffers.
79 Good at sub-partitioning the picture into variable sized structures.
85 encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
88 data resulting from the decode process; see ``CAPTURE``.
93 ``CAPTURE`` buffers must be returned by the decoder in display order.
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
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
178 node [shape = circle, label="Capture\nsetup"] CaptureSetup;
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)" ];
221 format set on ``CAPTURE``.
224 In particular whether or not the decoder has a full-fledged bytestream
228 :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
230 * Only the formats supported for the format currently active on ``OUTPUT``
235 enumerate formats on ``CAPTURE``.
268 coded resolution of the stream; required only if it cannot be parsed
285 * The ``CAPTURE`` format will be updated with an appropriate frame buffer
290 update the ``CAPTURE`` format with new values and signal a source change
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
355 4. **This step only applies to coded formats that contain resolution information
359 required metadata to configure the ``CAPTURE`` queue are found. This is
373 :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
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
400 5. Continue with the `Capture Setup` sequence.
402 Capture Setup
405 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
411 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
421 ``num_planes`` (for _MPLANE ``type`` only)
441 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
450 returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
452 * The following selection targets are supported on ``CAPTURE``:
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
476 the rectangle inside a ``CAPTURE`` buffer into which the cropped
478 read-only on hardware without additional compose/scaling capabilities.
481 the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
487 The values are guaranteed to be meaningful only after the decoder
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
498 The decoder will return only formats supported for the currently
506 1920x1088 and lower, but only YUV for higher resolutions (due to
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
524 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
534 * Setting the ``CAPTURE`` format will reset the compose selection rectangles
539 the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
545 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
551 the rectangle inside a ``CAPTURE`` buffer into which the cropped
553 read-only on hardware without additional compose/scaling capabilities.
559 returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
581 * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
584 * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
585 on the ``CAPTURE`` queue.
591 7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
592 buffers on the ``CAPTURE`` queue until a buffer marked with the
595 8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
596 on the ``CAPTURE`` queue to stop streaming.
604 9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
613 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
618 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
619 ``CAPTURE`` queue.
627 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
651 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
653 allocating buffers larger than the current ``CAPTURE`` format, future
662 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
689 let the decoder configure the ``CAPTURE`` format appropriately,
691 * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
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.
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
714 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
718 The client must not assume any direct relationship between ``CAPTURE``
723 on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
727 on ``CAPTURE`` (if the encoded data contained more than one frame, or if
732 ``CAPTURE`` later into decode process, and/or after processing further
736 * buffers may become available on the ``CAPTURE`` queue without additional
738 ``OUTPUT`` buffers queued in the past whose decoding results are only
743 To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
746 ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
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
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``
764 The backing memory of ``CAPTURE`` buffers that are used as reference frames
767 ``CAPTURE`` queue is streaming. Failure to observe this may result in
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.
781 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
799 * the CAPTURE buffer that contains the results of the failed decode operation
807 further operations on corresponding decoder file handle will return the -EIO
816 The seek does not require any specific operation on the ``CAPTURE`` queue, but
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
853 being made available on the ``CAPTURE`` queue. Drivers must ensure that
871 4. After a resume point is found, the decoder will start returning ``CAPTURE``
883 It is not specified when the ``CAPTURE`` queue starts producing buffers
887 The decoder may return a number of remaining ``CAPTURE`` buffers containing
893 queued before the seek sequence may have matching ``CAPTURE`` buffers
899 any of the following results on the ``CAPTURE`` queue is allowed:
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
911 ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
935 * bit-depth of the bitstream has been changed.
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
978 ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
981 2. Continue with the `Capture Setup` sequence.
989 In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
1000 ``CAPTURE`` buffers are given to the client, the client must follow the drain
1020 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
1035 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
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
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,
1072 however any ``CAPTURE`` buffers still in the queue will be returned to the
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.
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
1109 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
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``
1115 will result in the decoder adjusting the requested ``CAPTURE`` format to a
1119 supported coded formats, irrespectively of the current ``CAPTURE`` format.
1121 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
1123 return the -EBUSY error code for any such format change attempt.
1127 set of supported formats for the ``CAPTURE`` queue.