^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. _decoder:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) *************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Memory-to-Memory Stateful Video Decoder Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) *************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) display order. The decoder is expected not to require any additional information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) from the client to process these buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Performing software parsing, processing etc. of the stream in the driver in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) order to support this interface is strongly discouraged. In case such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) operations are needed, use of the Stateless Video Decoder Interface (in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) development) is strongly advised.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Conventions and Notations Used in This Document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) 1. The general V4L2 API rules apply if not specified in this document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 2. The meaning of words "must", "may", "should", etc. is as per `RFC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) 2119 <https://tools.ietf.org/html/rfc2119>`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 3. All steps not marked "optional" are required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) unless specified otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) used interchangeably with multi-planar API, unless specified otherwise,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) depending on decoder capabilities and following the general V4L2 guidelines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) [0..2]: i = 0, 1, 2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) queue containing data that resulted from processing buffer A.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) .. _decoder-glossary:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Glossary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) CAPTURE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) the destination buffer queue; for decoders, the queue of buffers containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) decoded frames; for encoders, the queue of buffers containing an encoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) into ``CAPTURE`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) the application communicating with the decoder or encoder implementing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) this interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) coded format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) also: raw format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) coded height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) height for given coded resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) coded resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) stream resolution in pixels aligned to codec and hardware requirements;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) typically visible resolution rounded up to full macroblocks;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) see also: visible resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) coded width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) width for given coded resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) decode order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) the order in which frames are decoded; may differ from display order if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) coded format includes a feature of frame reordering; for decoders,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) ``OUTPUT`` buffers must be queued by the client in decode order; for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) destination
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) data resulting from the decode process; see ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) display order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) the order in which frames must be displayed; for encoders, ``OUTPUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) buffers must be queued by the client in display order; for decoders,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) ``CAPTURE`` buffers must be returned by the decoder in display order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) DPB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) raw frame available for reference in further decoding steps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) EOS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) end of stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) IDR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) stream, which clears the list of earlier reference frames (DPBs).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) keyframe
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) an encoded frame that does not reference frames decoded earlier, i.e.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) can be decoded fully on its own.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) macroblock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) a processing unit in image and video compression formats based on linear
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) popular codecs the size is 16x16 samples (pixels).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) OUTPUT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) the source buffer queue; for decoders, the queue of buffers containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) an encoded bytestream; for encoders, the queue of buffers containing raw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) from ``OUTPUT`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) PPS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) raw format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) uncompressed format containing raw pixel data (e.g. YUV, RGB formats).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) resume point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) a point in the bytestream from which decoding may start/continue, without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) any previous state/data present, e.g.: a keyframe (VP8/VP9) or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) of a new stream, or to resume decoding after a seek.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) data fed to the decoder or encoder; see ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) source height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) height in pixels for given source resolution; relevant to encoders only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) source resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) resolution in pixels of source frames being source to the encoder and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) subject to further cropping to the bounds of visible resolution; relevant to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) encoders only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) source width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) width in pixels for given source resolution; relevant to encoders only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) SPS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) stream metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) additional (non-visual) information contained inside encoded bytestream;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) for example: coded resolution, visible resolution, codec profile.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) visible height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) height for given visible resolution; display height.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) visible resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) stream resolution of the visible picture, in pixels, to be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) display purposes; must be smaller or equal to coded resolution;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) display resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) visible width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) width for given visible resolution; display width.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) State Machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) .. kernel-render:: DOT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) :alt: DOT digraph of decoder state machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) :caption: Decoder State Machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) digraph decoder_state_machine {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) node [shape = doublecircle, label="Decoding"] Decoding;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) node [shape = circle, label="Initialization"] Initialization;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) node [shape = circle, label="Capture\nsetup"] CaptureSetup;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) node [shape = circle, label="Stopped"] Stopped;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) node [shape = circle, label="Drain"] Drain;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) node [shape = circle, label="Seek"] Seek;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) node [shape = circle, label="End of Stream"] EoS;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) node [shape = point]; qi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) qi -> Initialization [ label = "open()" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) Decoding -> EoS [ label = "EoS mark\nin the stream" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Decoding -> Decoding;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) EoS -> Drain [ label = "Implicit\ndrain" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) Querying Capabilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) 1. To enumerate the set of coded formats supported by the decoder, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) * The full set of supported formats will be returned, regardless of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) format set on ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) * Check the flags field of :c:type:`v4l2_fmtdesc` for more information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) about the decoder's capabilities with respect to each coded format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) In particular whether or not the decoder has a full-fledged bytestream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) parser and if the decoder supports dynamic resolution changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 2. To enumerate the set of supported raw formats, the client may call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) * Only the formats supported for the format currently active on ``OUTPUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) * In order to enumerate raw formats supported by a given coded format,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) the client must first set that coded format on ``OUTPUT`` and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) enumerate formats on ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) 3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) resolutions for a given format, passing desired pixel format in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) :c:type:`v4l2_frmsizeenum` ``pixel_format``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) format will include all possible coded resolutions supported by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) decoder for given coded pixel format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) will include all possible frame buffer resolutions supported by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) decoder for given raw pixel format and the coded format currently set on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 4. Supported profiles and levels for the coded format currently set on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) ``OUTPUT``, if applicable, may be queried using their respective controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) via :c:func:`VIDIOC_QUERYCTRL`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) ``pixelformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) a coded pixel format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) ``width``, ``height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) coded resolution of the stream; required only if it cannot be parsed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) from the stream for the given coded format; otherwise the decoder will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) use this resolution as a placeholder resolution that will likely change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) as soon as it can parse the actual coded resolution from the stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) ``sizeimage``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) desired size of ``OUTPUT`` buffers; the decoder may adjust it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) match hardware requirements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) other fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) follow standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) ``sizeimage``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) adjusted size of ``OUTPUT`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) * The ``CAPTURE`` format will be updated with an appropriate frame buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) resolution instantly based on the width and height returned by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) :c:func:`VIDIOC_S_FMT`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) However, for coded formats that include stream resolution information,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) after the decoder is done parsing the information from the stream, it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) update the ``CAPTURE`` format with new values and signal a source change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) event, regardless of whether they match the values set by the client or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) format. How the new ``CAPTURE`` format is determined is up to the decoder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) and the client must ensure it matches its needs afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) 2. Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) requested number of buffers to allocate; greater than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) ``memory``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) the actual number of buffers allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) The actual number of allocated buffers may differ from the ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) given. The client must check the updated value of ``count`` after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) call returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) used to have more control over buffer allocation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) requested number of buffers to allocate; greater than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) ``memory``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) ``format``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) adjusted to the number of allocated buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) The actual number of allocated buffers may differ from the ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) given. The client must check the updated value of ``count`` after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) call returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) 3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) 4. **This step only applies to coded formats that contain resolution information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) in the stream.** Continue queuing/dequeuing bytestream buffers to/from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) buffers will be processed and returned to the client in order, until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) required metadata to configure the ``CAPTURE`` queue are found. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) * It is not an error if the first buffer does not contain enough data for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) this to occur. Processing of the buffers will continue as long as more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) data is needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) * If data in a buffer that triggers the event is required to decode the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) first frame, it will not be returned to the client, until the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) initialization sequence completes and the frame is decoded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) * If the client has not set the coded resolution of the stream on its own,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) queue will not return the real values for the stream until a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) Any client query issued after the decoder queues the event will return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) values applying to the just parsed stream, including queue formats,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) selection rectangles and controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) A client capable of acquiring stream parameters from the bytestream on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) its own may attempt to set the width and height of the ``OUTPUT`` format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) to non-zero values matching the coded size of the stream, skip this step
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) and continue with the `Capture Setup` sequence. However, it must not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) rely on any driver queries regarding stream parameters, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) selection rectangles and controls, since the decoder has not parsed them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) from the stream yet. If the values configured by the client do not match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) those parsed by the decoder, a `Dynamic Resolution Change` will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) triggered to reconfigure them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) No decoded frames are produced during this phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 5. Continue with the `Capture Setup` sequence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) Capture Setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) destination buffers parsed/decoded from the bytestream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) ``width``, ``height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) frame buffer resolution for the decoded frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) ``pixelformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) pixel format for decoded frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) ``num_planes`` (for _MPLANE ``type`` only)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) number of planes for pixelformat.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) ``sizeimage``, ``bytesperline``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) as per standard semantics; matching frame buffer format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) The value of ``pixelformat`` may be any pixel format supported by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) decoder for the current stream. The decoder should choose a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) preferred/optimal format for the default configuration. For example, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) YUV format may be preferred over an RGB format if an additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) conversion step would be required for the latter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) 2. **Optional.** Acquire the visible resolution via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) :c:func:`VIDIOC_G_SELECTION`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) ``target``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) set to ``V4L2_SEL_TGT_COMPOSE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) ``r.left``, ``r.top``, ``r.width``, ``r.height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) the visible rectangle; it must fit within the frame buffer resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) * The following selection targets are supported on ``CAPTURE``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) ``V4L2_SEL_TGT_CROP_BOUNDS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) corresponds to the coded resolution of the stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) ``V4L2_SEL_TGT_CROP_DEFAULT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) the rectangle covering the part of the ``CAPTURE`` buffer that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) contains meaningful picture data (visible area); width and height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) will be equal to the visible resolution of the stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) ``V4L2_SEL_TGT_CROP``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) the rectangle within the coded resolution to be output to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) hardware without additional compose/scaling capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) hardware does not support compose/scaling.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) equal to ``V4L2_SEL_TGT_CROP``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) ``V4L2_SEL_TGT_COMPOSE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) the rectangle inside a ``CAPTURE`` buffer into which the cropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) read-only on hardware without additional compose/scaling capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) ``V4L2_SEL_TGT_COMPOSE_PADDED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) write padding pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) The values are guaranteed to be meaningful only after the decoder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) successfully parses the stream metadata. The client must not rely on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) query before that happens.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) 3. **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) the ``CAPTURE`` queue. Once the stream information is parsed and known, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) client may use this ioctl to discover which raw formats are supported for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) given stream and select one of them via :c:func:`VIDIOC_S_FMT`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) The decoder will return only formats supported for the currently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) established coded format, as per the ``OUTPUT`` format and/or stream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) metadata parsed in this initialization sequence, even if more formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) may be supported by the decoder in general. In other words, the set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) returned will be a subset of the initial query mentioned in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) `Querying Capabilities` section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) For example, a decoder may support YUV and RGB formats for resolutions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) 1920x1088 and lower, but only YUV for higher resolutions (due to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) hardware limitations). After parsing a resolution of 1920x1088 or lower,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) but after parsing resolution higher than 1920x1088, the decoder will not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) return RGB, unsupported for this resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) However, subsequent resolution change event triggered after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) discovering a resolution change within the same stream may switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) would return RGB formats again in that case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) 4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) ``CAPTURE`` queue. The client may choose a different format than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) ``pixelformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) a raw pixel format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) ``width``, ``height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) frame buffer resolution of the decoded stream; typically unchanged from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) if the hardware supports composition and/or scaling.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) * Setting the ``CAPTURE`` format will reset the compose selection rectangles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) to their default values, based on the new resolution, as described in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) previous step.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) 5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) scaling capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) ``target``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) set to ``V4L2_SEL_TGT_COMPOSE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) ``r.left``, ``r.top``, ``r.width``, ``r.height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) the rectangle inside a ``CAPTURE`` buffer into which the cropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) read-only on hardware without additional compose/scaling capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) ``r.left``, ``r.top``, ``r.width``, ``r.height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) the visible rectangle; it must fit within the frame buffer resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) The decoder may adjust the compose rectangle to the nearest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) supported one to meet codec and hardware requirements. The client needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) 6. If all the following conditions are met, the client may resume the decoding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) instantly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) * ``sizeimage`` of the new format (determined in previous steps) is less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) than or equal to the size of currently allocated buffers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) * the number of buffers currently allocated is greater than or equal to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) minimum number of buffers acquired in previous steps. To fulfill this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) In that case, the remaining steps do not apply and the client may resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) the decoding by one of the following actions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) with the ``V4L2_DEC_CMD_START`` command,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) on the ``CAPTURE`` queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) However, if the client intends to change the buffer set, to lower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) memory usage or for any other reasons, it may be achieved by following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) the steps below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) 7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) buffers on the ``CAPTURE`` queue until a buffer marked with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) 8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) on the ``CAPTURE`` queue to stop streaming.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) The ``OUTPUT`` queue must remain streaming. Calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) seek.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) 9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) buffers using :c:func:`VIDIOC_REQBUFS`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) set to 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) ``memory``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) ``CAPTURE`` queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) requested number of buffers to allocate; greater than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) ``memory``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) actual number of buffers allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) The actual number of allocated buffers may differ from the ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) given. The client must check the updated value of ``count`` after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) call returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) To allocate more than the minimum number of buffers (for pipeline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) control to get the minimum number of buffers required, and pass the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) obtained value plus the number of additional buffers needed in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) ``count`` field to :c:func:`VIDIOC_REQBUFS`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) used to have more control over buffer allocation. For example, by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) allocating buffers larger than the current ``CAPTURE`` format, future
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) resolution changes can be accommodated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) requested number of buffers to allocate; greater than zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) ``memory``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) follows standard semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) ``format``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) a format representing the maximum framebuffer resolution to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) accommodated by newly allocated buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) * **Return fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) adjusted to the number of allocated buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) The actual number of allocated buffers may differ from the ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) given. The client must check the updated value of ``count`` after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) call returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) To allocate buffers for a format different than parsed from the stream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) metadata, the client must proceed as follows, before the metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) parsing is initiated:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) * set width and height of the ``OUTPUT`` format to desired coded resolution to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) let the decoder configure the ``CAPTURE`` format appropriately,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) until this step.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) The format obtained in the query may be then used with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) 11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) Decoding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) This state is reached after the `Capture Setup` sequence finishes successfully.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) In this state, the client queues and dequeues buffers to both queues via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) The content of the source ``OUTPUT`` buffers depends on the active coded pixel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) format and may be affected by codec-specific extended controls, as stated in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) the documentation of each format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) Both queues operate independently, following the standard behavior of V4L2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) buffer queues and memory-to-memory devices. In addition, the order of decoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) format, e.g. frame reordering.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) The client must not assume any direct relationship between ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) and ``OUTPUT`` buffers and any specific timing of buffers becoming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) available to dequeue. Specifically:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) * a buffer queued to ``OUTPUT`` may result in no buffers being produced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) metadata syntax structures are present in it),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) * a buffer queued to ``OUTPUT`` may result in more than one buffer produced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) on ``CAPTURE`` (if the encoded data contained more than one frame, or if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) returning a decoded frame allowed the decoder to return a frame that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) preceded it in decode, but succeeded it in the display order),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) * a buffer queued to ``OUTPUT`` may result in a buffer being produced on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) ``CAPTURE`` later into decode process, and/or after processing further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) ``OUTPUT`` buffers, or be returned out of order, e.g. if display
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) reordering is used,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) * buffers may become available on the ``CAPTURE`` queue without additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) ``OUTPUT`` buffers queued in the past whose decoding results are only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) available at later time, due to specifics of the decoding process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) originated from, the client can set the ``timestamp`` field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) will have their ``timestamp`` field set to the same value when dequeued.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) In addition to the straightforward case of one ``OUTPUT`` buffer producing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) one ``CAPTURE`` buffer, the following cases are defined:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) the ``OUTPUT`` buffer queued first will be copied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) * the decoding order differs from the display order (i.e. the ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) timestamps will not retain the order of ``OUTPUT`` timestamps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) During the decoding, the decoder may initiate one of the special sequences, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) listed below. The sequences will result in the decoder returning all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) before the sequence started. Last of the buffers will have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) ``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) must check if there is any pending event and:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) * if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) Change` sequence needs to be followed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) * if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) to be followed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) Some of the sequences can be intermixed with each other and need to be handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) as they happen. The exact operation is documented for each sequence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) Should a decoding error occur, it will be reported to the client with the level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) of details depending on the decoder capabilities. Specifically:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) * the CAPTURE buffer that contains the results of the failed decode operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) will be returned with the V4L2_BUF_FLAG_ERROR flag set,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) * if the decoder is able to precisely report the OUTPUT buffer that triggered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) In case of a fatal failure that does not allow the decoding to continue, any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) further operations on corresponding decoder file handle will return the -EIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) error code. The client may close the file handle and open a new one, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) alternatively reinitialize the instance by stopping streaming on both queues,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) releasing all buffers and performing the Initialization sequence again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) Seek
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) The seek does not require any specific operation on the ``CAPTURE`` queue, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) it may be affected as per normal decoder operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) :c:func:`VIDIOC_STREAMOFF`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) treated as returned to the client (following standard semantics).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) * The decoder will start accepting new source bytestream buffers after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) call returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) queue until a suitable resume point is found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) There is no requirement to begin queuing coded data starting exactly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) buffers will be processed and returned to the client until a suitable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) resume point is found. While looking for a resume point, the decoder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) should not produce any decoded frames into ``CAPTURE`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) Some hardware is known to mishandle seeks to a non-resume point. Such an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) operation may result in an unspecified number of corrupted decoded frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) being made available on the ``CAPTURE`` queue. Drivers must ensure that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) no fatal decoding errors or crashes occur, and implement any necessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) handling and workarounds for hardware issues related to seek operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) In case of the H.264/HEVC codec, the client must take care not to seek
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) over a change of SPS/PPS. Even though the target frame could be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) keyframe, the stale SPS/PPS inside decoder state would lead to undefined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) results when decoding. Although the decoder must handle that case without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) a crash or a fatal decode error, the client must not expect a sensible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) decode output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) If the hardware can detect such corrupted decoded frames, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) corresponding buffers will be returned to the client with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) description of decode error reporting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) 4. After a resume point is found, the decoder will start returning ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) buffers containing decoded frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) A seek may result in the `Dynamic Resolution Change` sequence being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) initiated, due to the seek target having decoding parameters different from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) the part of the stream decoded before the seek. The sequence must be handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) as per normal decoder operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) It is not specified when the ``CAPTURE`` queue starts producing buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) containing decoded data from the ``OUTPUT`` buffers queued after the seek,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) as it operates independently from the ``OUTPUT`` queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) The decoder may return a number of remaining ``CAPTURE`` buffers containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) decoded frames originating from the ``OUTPUT`` buffers queued before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) seek sequence is performed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) queued before the seek sequence may have matching ``CAPTURE`` buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) produced. For example, given the sequence of operations on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) ``OUTPUT`` queue:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) any of the following results on the ``CAPTURE`` queue is allowed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) {A’, B’, G’, H’}, {A’, G’, H’}, {G’, H’}.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) To determine the CAPTURE buffer containing the first decoded frame after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) decoder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) To achieve instantaneous seek, the client may restart streaming on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) Dynamic Resolution Change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) Streams that include resolution metadata in the bytestream may require switching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) to a different resolution during the decoding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) Not all decoders can detect resolution changes. Those that do set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) :c:func:`VIDIOC_ENUM_FMT` is called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) The sequence starts when the decoder detects a coded frame with one or more of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) the following parameters different from those previously established (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) reflected by corresponding queries):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) * coded resolution (``OUTPUT`` width and height),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) * visible resolution (selection rectangles),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) * the minimum number of buffers needed for decoding,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) * bit-depth of the bitstream has been changed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) Whenever that happens, the decoder must proceed as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) 1. After encountering a resolution change in the stream, the decoder sends a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) ``V4L2_EVENT_SRC_CH_RESOLUTION``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) Any client query issued after the decoder queues the event will return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) values applying to the stream after the resolution change, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) queue formats, selection rectangles and controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) 2. The decoder will then process and decode all remaining buffers from before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) the resolution change point.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) * The last buffer from before the change must be marked with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) = 0) and in that case it must be ignored by the client, as it does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) contain a decoded frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) :c:func:`VIDIOC_DQBUF`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) The client must continue the sequence as described below to continue the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) decoding process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) 1. Dequeue the source change event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950) A source change triggers an implicit decoder drain, similar to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) explicit `Drain` sequence. The decoder is stopped after it completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) The decoding process must be resumed with either a pair of calls to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) ``V4L2_DEC_CMD_START`` command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) 2. Continue with the `Capture Setup` sequence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) During the resolution change sequence, the ``OUTPUT`` queue must remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) abort the sequence and initiate a seek.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) queue and this remains true for the duration of the entire resolution change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) sequence as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) The client should, for best performance and simplicity, keep queuing/dequeuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) buffers to/from the ``OUTPUT`` queue even while processing this sequence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972) Drain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) To ensure that all queued ``OUTPUT`` buffers have been processed and related
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) ``CAPTURE`` buffers are given to the client, the client must follow the drain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) sequence described below. After the drain sequence ends, the client has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) received all decoded frames for all ``OUTPUT`` buffers queued before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) sequence was started.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) 1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) * **Required fields:**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) ``cmd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) set to ``V4L2_DEC_CMD_STOP``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) set to 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) ``pts``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992) set to 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) queues are streaming. For compatibility reasons, the call to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) not streaming, but at the same time it will not initiate the `Drain`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) sequence and so the steps described below would not be applicable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) 2. Any ``OUTPUT`` buffers queued by the client before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) normal. The client must continue to handle both queues independently,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) similarly to normal decode operation. This includes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) * handling any operations triggered as a result of processing those buffers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) such as the `Dynamic Resolution Change` sequence, before continuing with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) the drain sequence,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) The last buffer may be empty (with :c:type:`v4l2_buffer`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) ``bytesused`` = 0) and in that case it must be ignored by the client,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) as it does not contain a decoded frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) :c:func:`VIDIOC_DQBUF`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033) For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) event when the last frame has been decoded and all frames are ready to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) dequeued. It is a deprecated behavior and the client must not rely on it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) 3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) stopped and it will accept, but not process, any newly queued ``OUTPUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) buffers until the client issues any of the following operations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) operation normally, with all the state from before the drain,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) ``CAPTURE`` queue - the decoder will resume the operation normally,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) however any ``CAPTURE`` buffers still in the queue will be returned to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049) client,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052) ``OUTPUT`` queue - any pending source buffers will be returned to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053) client and the `Seek` sequence will be triggered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057) Once the drain sequence is initiated, the client needs to drive it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) completion, as described by the steps above, unless it aborts the process by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059) issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060) queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) will fail with -EBUSY error code if attempted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064) Although not mandatory, the availability of decoder commands may be queried
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) using :c:func:`VIDIOC_TRY_DECODER_CMD`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) End of Stream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) If the decoder encounters an end of stream marking in the stream, the decoder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) will initiate the `Drain` sequence, which the client must handle as described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072) above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) Commit Points
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077) Setting formats and allocating buffers trigger changes in the behavior of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) decoder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) 1. Setting the format on the ``OUTPUT`` queue may change the set of formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081) supported/advertised on the ``CAPTURE`` queue. In particular, it also means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082) that the ``CAPTURE`` format may be reset and the client must not rely on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083) previously set format being preserved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086) supported for the current ``OUTPUT`` format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088) 3. Setting the format on the ``CAPTURE`` queue does not change the list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089) formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) format that is not supported for the currently selected ``OUTPUT`` format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091) will result in the decoder adjusting the requested ``CAPTURE`` format to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092) supported one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094) 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095) supported coded formats, irrespectively of the current ``CAPTURE`` format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098) the client must not change the format on the ``OUTPUT`` queue. Drivers will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099) return the -EBUSY error code for any such format change attempt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101) To summarize, setting formats and allocation must always start with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) set of supported formats for the ``CAPTURE`` queue.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags
| Donate