media/v4l/dev-decoder.rst

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,
44 .. _decoder-glossary:
76    the order in which frames are decoded; may differ from display order if the
97    Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
106    block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
146    additional (non-visual) information contained inside encoded bytestream;
163 .. kernel-render:: DOT
179        qi -> Initialization [ label = "open()" ];
181        Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
183        CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
185        Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
186        Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
187        Decoding -> EoS [ label = "EoS mark\nin the stream" ];
188        Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
189        Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
190        Decoding -> Decoding;
192        ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
193        ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
195        EoS -> Drain [ label = "Implicit\ndrain" ];
197        Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
198        Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
200        Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
201        Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
203        Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
204        Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
217      In particular whether or not the decoder has a full-fledged bytestream
314        The actual number of allocated buffers may differ from the ``count``
342        The actual number of allocated buffers may differ from the ``count``
381        to non-zero values matching the coded size of the stream, skip this step
457           ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
471           read-only on hardware without additional compose/scaling capabilities.
546          read-only on hardware without additional compose/scaling capabilities.
632        The actual number of allocated buffers may differ from the ``count``
671         The actual number of allocated buffers may differ from the ``count``
702 format and may be affected by codec-specific extended controls, as stated in
706 buffer queues and memory-to-memory devices. In addition, the order of decoded
707 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
752      buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
783 further operations on corresponding decoder file handle will return the -EIO
827       Some hardware is known to mishandle seeks to a non-resume point. Such an
911 * bit-depth of the bitstream has been changed.
940        with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1023         marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
1043    * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
1047      ``CAPTURE`` queue - the decoder will resume the operation normally,
1052      ``OUTPUT`` queue - any pending source buffers will be returned to the
1062    will fail with -EBUSY error code if attempted.
1099    return the -EBUSY error code for any such format change attempt.