메모리 대 메모리 상태 유지형 비디오 디코더 인터페이스

상태 유지형 디코더와 문서 규칙

상태 유지형 비디오 디코더는 Annex-B H.264/HEVC stream이나 raw VP8/VP9 stream 같은 bytestream의 완전한 chunk를 받아 display order의 raw video frame으로 디코딩합니다. 디코더는 이 buffer들을 처리하기 위해 client로부터 추가 정보를 요구하지 않아야 합니다.

이 인터페이스를 지원하려고 드라이버 내부에서 stream을 software로 parsing하거나 처리하는 구현은 강하게 권장되지 않습니다. 그런 작업이 필요하다면 Stateless Video Decoder Interface를 사용하는 것이 바람직합니다.

이 문서에서 별도로 정하지 않은 사항에는 일반 V4L2 API 규칙이 적용되고, must·may·should 등의 의미는 RFC 2119를 따릅니다. optional로 표시하지 않은 단계는 모두 필수입니다.

별도 규정이 없으면 `VIDIOC_G_EXT_CTRLS`와 `VIDIOC_S_EXT_CTRLS`는 각각 `VIDIOC_G_CTRL`과 `VIDIOC_S_CTRL` 대신 사용할 수 있고 그 반대도 가능합니다.

.. SPDX-License-Identifier: GPL-2.0

.. _decoder:

*************************************************
Memory-to-Memory Stateful Video Decoder Interface
*************************************************

A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
H.264/HEVC stream, raw VP8/9 stream) and decodes them into raw video frames in
display order. The decoder is expected not to require any additional information
from the client to process these buffers.

Performing software parsing, processing etc. of the stream in the driver in
order to support this interface is strongly discouraged. In case such
operations are needed, use of the Stateless Video Decoder Interface (in
development) is strongly advised.

Conventions and Notations Used in This Document
===============================================

1. The general V4L2 API rules apply if not specified in this document
   otherwise.

2. The meaning of words "must", "may", "should", etc. is as per `RFC
   2119 <https://tools.ietf.org/html/rfc2119>`_.

3. All steps not marked "optional" are required.

4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used
   interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`,
   unless specified otherwise.

5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
   used interchangeably with multi-planar API, unless specified otherwise,
   depending on decoder capabilities and following the general V4L2 guidelines.

6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i =
   [0..2]: i = 0, 1, 2.

7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE``
   queue containing data that resulted from processing buffer A.

디코더 용어

`OUTPUT`은 encoded bytestream을 하드웨어에 공급하는 source queue이고, `CAPTURE`는 디코딩된 raw frame을 하드웨어에서 받아 오는 destination queue입니다. encoder에서는 두 queue의 데이터 역할이 반대지만 V4L2 buffer type 이름은 같습니다.

coded resolution은 codec과 하드웨어 정렬 요구를 만족하는 stream 크기이며, 보통 visible resolution을 macroblock 또는 coding tree unit 경계까지 올림한 값입니다. visible resolution은 실제 표시할 picture 크기이므로 coded resolution보다 작거나 같아야 합니다.

decode order와 display order는 frame 재정렬을 사용하는 format에서 다를 수 있습니다. client는 decoder의 `OUTPUT` buffer를 decode order로 queue하고, decoder는 `CAPTURE` buffer를 display order로 반환합니다.

.. _decoder-glossary:

Glossary
========

CAPTURE
   the destination buffer queue; for decoders, the queue of buffers containing
   decoded frames; for encoders, the queue of buffers containing an encoded
   bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
   ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
   into ``CAPTURE`` buffers.

client
   the application communicating with the decoder or encoder implementing
   this interface.

coded format
   encoded/compressed video bytestream format (e.g. H.264, VP8, etc.); see
   also: raw format.

coded height
   height for given coded resolution.

coded resolution
   stream resolution in pixels aligned to codec and hardware requirements;
   typically visible resolution rounded up to full macroblocks;
   see also: visible resolution.

coded width
   width for given coded resolution.

coding tree unit
   processing unit of the HEVC codec (corresponds to macroblock units in
   H.264, VP8, VP9),
   can use block structures of up to 64×64 pixels.
   Good at sub-partitioning the picture into variable sized structures.

decode order
   the order in which frames are decoded; may differ from display order if the
   coded format includes a feature of frame reordering; for decoders,
   ``OUTPUT`` buffers must be queued by the client in decode order; for
   encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.

destination
   data resulting from the decode process; see ``CAPTURE``.

display order
   the order in which frames must be displayed; for encoders, ``OUTPUT``
   buffers must be queued by the client in display order; for decoders,
   ``CAPTURE`` buffers must be returned by the decoder in display order.

DPB
   Decoded Picture Buffer; an H.264/HEVC term for a buffer that stores a decoded
   raw frame available for reference in further decoding steps.

EOS
   end of stream.

IDR
   Instantaneous Decoder Refresh; a type of a keyframe in an H.264/HEVC-encoded
   stream, which clears the list of earlier reference frames (DPBs).

keyframe
   an encoded frame that does not reference frames decoded earlier, i.e.
   can be decoded fully on its own.

macroblock
   a processing unit in image and video compression formats based on linear
   block transforms (e.g. H.264, VP8, VP9); codec-specific, but for most of
   popular codecs the size is 16x16 samples (pixels). The HEVC codec uses a
   slightly more flexible processing unit called coding tree unit (CTU).

OUTPUT
   the source buffer queue; for decoders, the queue of buffers containing
   an encoded bytestream; for encoders, the queue of buffers containing raw
   frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
   ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
   from ``OUTPUT`` buffers.

PPS
   Picture Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.

raw format
   uncompressed format containing raw pixel data (e.g. YUV, RGB formats).

resume point
   a point in the bytestream from which decoding may start/continue, without
   any previous state/data present, e.g.: a keyframe (VP8/VP9) or
   SPS/PPS/IDR sequence (H.264/HEVC); a resume point is required to start decode
   of a new stream, or to resume decoding after a seek.

source
   data fed to the decoder or encoder; see ``OUTPUT``.

source height
   height in pixels for given source resolution; relevant to encoders only.

source resolution
   resolution in pixels of source frames being source to the encoder and
   subject to further cropping to the bounds of visible resolution; relevant to
   encoders only.

source width
   width in pixels for given source resolution; relevant to encoders only.

SPS
   Sequence Parameter Set; a type of metadata entity in an H.264/HEVC bytestream.

stream metadata
   additional (non-visual) information contained inside encoded bytestream;
   for example: coded resolution, visible resolution, codec profile.

visible height
   height for given visible resolution; display height.

visible resolution
   stream resolution of the visible picture, in pixels, to be used for
   display purposes; must be smaller or equal to coded resolution;
   display resolution.

visible width
   width for given visible resolution; display width.

디코더 상태 기계

상태 기계는 `open()`의 Initialization에서 시작해 CAPTURE format 확정, buffer 준비, Stopped를 거쳐 Decoding으로 이동합니다. Decoding 중에는 resolution change, drain, EOS, seek, CAPTURE 정지 같은 사건이 각각 전용 상태 전이를 일으킵니다.

원문의 DOT graph는 아래 흐름과 전이 표로 구조화했습니다. `OUTPUT` STREAMOFF는 여러 상태에서 Seek로 이동하고, `CAPTURE` STREAMOFF는 decode나 drain을 Stopped로 끝내는 핵심 차이가 있습니다.

State Machine
=============

.. kernel-render:: DOT
   :alt: DOT digraph of decoder state machine
   :caption: Decoder State Machine

   digraph decoder_state_machine {
       node [shape = doublecircle, label="Decoding"] Decoding;

       node [shape = circle, label="Initialization"] Initialization;
       node [shape = circle, label="Capture\nsetup"] CaptureSetup;
       node [shape = circle, label="Dynamic\nResolution\nChange"] ResChange;
       node [shape = circle, label="Stopped"] Stopped;
       node [shape = circle, label="Drain"] Drain;
       node [shape = circle, label="Seek"] Seek;
       node [shape = circle, label="End of Stream"] EoS;

       node [shape = point]; qi
       qi -> Initialization [ label = "open()" ];

       Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];

       CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];

       Decoding -> ResChange [ label = "Stream\nresolution\nchange" ];
       Decoding -> Drain [ label = "V4L2_DEC_CMD_STOP" ];
       Decoding -> EoS [ label = "EoS mark\nin the stream" ];
       Decoding -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
       Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
       Decoding -> Decoding;

       ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
       ResChange -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];

       EoS -> Drain [ label = "Implicit\ndrain" ];

       Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
       Drain -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];

       Seek -> Decoding [ label = "VIDIOC_STREAMON(OUTPUT)" ];
       Seek -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];

       Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
       Stopped -> Seek [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
   }

지원 format과 해상도 조회

decoder의 coded format 전체를 열거하려면 `OUTPUT`에서 `VIDIOC_ENUM_FMT`를 호출합니다. 현재 `CAPTURE` format과 관계없이 지원하는 전체 coded format이 반환됩니다. `struct v4l2_fmtdesc`의 `flags`에서 완전한 bytestream parser 보유 여부와 dynamic resolution change 지원 여부 등 format별 capability를 확인할 수 있습니다.

지원 raw format을 열거하려면 `CAPTURE`에서 `VIDIOC_ENUM_FMT`를 호출합니다. 여기서는 현재 `OUTPUT`에 활성화된 coded format과 함께 사용할 수 있는 format만 반환되므로, 특정 coded format의 raw format을 알아보려면 먼저 `OUTPUT`에 coded format을 설정해야 합니다.

`VIDIOC_ENUM_FRAMESIZES`에 원하는 pixel format을 `struct v4l2_frmsizeenum.pixel_format`으로 전달하면 지원 해상도를 확인할 수 있습니다. coded pixel format에는 decoder가 지원하는 모든 coded resolution이, raw pixel format에는 현재 `OUTPUT` coded format과 조합할 수 있는 모든 frame buffer resolution이 포함됩니다.

현재 `OUTPUT`에 설정한 coded format에 profile과 level 개념이 있다면 각각의 control을 `VIDIOC_QUERYCTRL`로 조회할 수 있습니다.

Querying Capabilities
=====================

1. To enumerate the set of coded formats supported by the decoder, the
   client may call :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``.

   * The full set of supported formats will be returned, regardless of the
     format set on ``CAPTURE``.
   * Check the flags field of :c:type:`v4l2_fmtdesc` for more information
     about the decoder's capabilities with respect to each coded format.
     In particular whether or not the decoder has a full-fledged bytestream
     parser and if the decoder supports dynamic resolution changes.

2. To enumerate the set of supported raw formats, the client may call
   :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.

   * Only the formats supported for the format currently active on ``OUTPUT``
     will be returned.

   * In order to enumerate raw formats supported by a given coded format,
     the client must first set that coded format on ``OUTPUT`` and then
     enumerate formats on ``CAPTURE``.

3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
   resolutions for a given format, passing desired pixel format in
   :c:type:`v4l2_frmsizeenum` ``pixel_format``.

   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel
     format will include all possible coded resolutions supported by the
     decoder for given coded pixel format.

   * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format
     will include all possible frame buffer resolutions supported by the
     decoder for given raw pixel format and the coded format currently set on
     ``OUTPUT``.

4. Supported profiles and levels for the coded format currently set on
   ``OUTPUT``, if applicable, may be queried using their respective controls
   via :c:func:`VIDIOC_QUERYCTRL`.

OUTPUT format과 source buffer 초기화

초기화의 첫 단계는 `VIDIOC_S_FMT`로 `OUTPUT`에 coded format을 설정하는 것입니다. 필수 입력은 OUTPUT에 맞는 `type`, coded `pixelformat`, 필요할 경우 stream의 coded `width`와 `height`, 원하는 OUTPUT buffer 크기 `sizeimage`입니다. 그 밖의 필드는 표준 의미를 따릅니다.

stream에서 해상도를 parse할 수 있는 format이면 width와 height는 실제 정보가 발견될 때까지 쓰는 placeholder일 뿐입니다. 드라이버는 하드웨어 요구에 맞춰 `sizeimage`를 조정해 반환합니다.

S_FMT가 돌려준 width와 height를 바탕으로 `CAPTURE` format의 frame buffer resolution도 즉시 갱신됩니다. stream 자체에 해상도 정보가 있다면 decoder는 이를 parse한 뒤 client가 설정한 값과 일치하는지와 관계없이 CAPTURE format을 다시 갱신하고 source change event를 보냅니다.

`OUTPUT` format을 바꾸면 현재 `CAPTURE` format도 바뀔 수 있습니다. 새 CAPTURE format을 결정하는 방식은 decoder에 달려 있으므로 client는 변경 뒤 자신의 요구와 맞는지 반드시 확인해야 합니다.

그 다음 `OUTPUT`에서 `VIDIOC_REQBUFS`로 source bytestream buffer를 할당합니다. `count`는 0보다 커야 하고 `type`은 OUTPUT용이며 `memory`는 표준 의미를 따릅니다. 반환된 실제 `count`는 요청과 다를 수 있으므로 반드시 다시 읽어야 합니다.

더 세밀한 buffer 할당이 필요하면 `OUTPUT`에서 `VIDIOC_CREATE_BUFS`를 사용할 수 있습니다. 이때 `count`, `type`, `memory`, `format`을 입력하고 조정된 실제 `count`를 확인합니다.

Initialization
==============

1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.

   * **Required fields:**

     ``type``
         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.

     ``pixelformat``
         a coded pixel format.

     ``width``, ``height``
         coded resolution of the stream; required only if it cannot be parsed
         from the stream for the given coded format; otherwise the decoder will
         use this resolution as a placeholder resolution that will likely change
         as soon as it can parse the actual coded resolution from the stream.

     ``sizeimage``
         desired size of ``OUTPUT`` buffers; the decoder may adjust it to
         match hardware requirements.

     other fields
         follow standard semantics.

   * **Returned fields:**

     ``sizeimage``
         adjusted size of ``OUTPUT`` buffers.

   * The ``CAPTURE`` format will be updated with an appropriate frame buffer
     resolution instantly based on the width and height returned by
     :c:func:`VIDIOC_S_FMT`.
     However, for coded formats that include stream resolution information,
     after the decoder is done parsing the information from the stream, it will
     update the ``CAPTURE`` format with new values and signal a source change
     event, regardless of whether they match the values set by the client or
     not.

   .. important::

      Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
      format. How the new ``CAPTURE`` format is determined is up to the decoder
      and the client must ensure it matches its needs afterwards.

2.  Allocate source (bytestream) buffers via :c:func:`VIDIOC_REQBUFS` on
    ``OUTPUT``.

    * **Required fields:**

      ``count``
          requested number of buffers to allocate; greater than zero.

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.

      ``memory``
          follows standard semantics.

    * **Returned fields:**

      ``count``
          the actual number of buffers allocated.

    .. warning::

       The actual number of allocated buffers may differ from the ``count``
       given. The client must check the updated value of ``count`` after the
       call returns.

    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
    used to have more control over buffer allocation.

    * **Required fields:**

      ``count``
          requested number of buffers to allocate; greater than zero.

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.

      ``memory``
          follows standard semantics.

      ``format``
          follows standard semantics.

    * **Returned fields:**

      ``count``
          adjusted to the number of allocated buffers.

    .. warning::

       The actual number of allocated buffers may differ from the ``count``
       given. The client must check the updated value of ``count`` after the
       call returns.

stream metadata parsing과 source change

`VIDIOC_STREAMON`으로 `OUTPUT` queue의 streaming을 시작합니다. stream 안에 resolution 정보가 들어 있는 coded format에만 이어지는 metadata parsing 단계가 적용됩니다.

client는 `VIDIOC_QBUF`와 `VIDIOC_DQBUF`로 OUTPUT bytestream buffer를 계속 넣고 돌려받습니다. CAPTURE queue를 구성하는 데 필요한 metadata를 찾으면 decoder가 `changes = V4L2_EVENT_SRC_CH_RESOLUTION`인 `V4L2_EVENT_SOURCE_CHANGE` event를 보냅니다.

첫 buffer에 충분한 정보가 없어도 오류가 아니며 필요한 만큼 처리가 계속됩니다. event를 일으킨 buffer의 데이터가 첫 frame decode에 필요하면 초기화와 첫 frame decode가 끝날 때까지 그 buffer를 client에 반환하지 않습니다.

client가 coded resolution을 직접 설정하지 않았다면 source change event 전의 CAPTURE `VIDIOC_G_FMT`, `VIDIOC_S_FMT`, `VIDIOC_TRY_FMT`, `VIDIOC_REQBUFS`는 실제 stream 값을 반환하지 않습니다. decoder가 event를 queue한 뒤의 format, selection rectangle, control 조회는 방금 parse한 stream에 적용되는 값을 반환합니다.

client가 bytestream에서 parameter를 자체 추출할 수 있다면 OUTPUT width와 height를 0이 아닌 coded size로 설정하고 parsing 대기 단계를 건너뛸 수 있습니다. 그러나 decoder가 아직 metadata를 parse하지 않았으므로 selection과 control 같은 driver 조회값에 의존해서는 안 됩니다. client 값과 나중에 parse한 값이 다르면 Dynamic Resolution Change가 발생합니다.

이 metadata 탐색 단계에서는 decoded frame을 만들지 않습니다. source change를 확인하거나 유효하게 단계를 건너뛴 뒤 Capture Setup으로 진행합니다.

3.  Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.

4.  **This step only applies to coded formats that contain resolution information
    in the stream.** Continue queuing/dequeuing bytestream buffers to/from the
    ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
    buffers will be processed and returned to the client in order, until
    required metadata to configure the ``CAPTURE`` queue are found. This is
    indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
    ``changes`` set to ``V4L2_EVENT_SRC_CH_RESOLUTION``.

    * It is not an error if the first buffer does not contain enough data for
      this to occur. Processing of the buffers will continue as long as more
      data is needed.

    * If data in a buffer that triggers the event is required to decode the
      first frame, it will not be returned to the client, until the
      initialization sequence completes and the frame is decoded.

    * If the client has not set the coded resolution of the stream on its own,
      calling :c:func:`VIDIOC_G_FMT`, :c:func:`VIDIOC_S_FMT`,
      :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
      queue will not return the real values for the stream until a
      ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
      ``V4L2_EVENT_SRC_CH_RESOLUTION`` is signaled.

    .. important::

       Any client query issued after the decoder queues the event will return
       values applying to the just parsed stream, including queue formats,
       selection rectangles and controls.

    .. note::

       A client capable of acquiring stream parameters from the bytestream on
       its own may attempt to set the width and height of the ``OUTPUT`` format
       to non-zero values matching the coded size of the stream, skip this step
       and continue with the `Capture Setup` sequence. However, it must not
       rely on any driver queries regarding stream parameters, such as
       selection rectangles and controls, since the decoder has not parsed them
       from the stream yet. If the values configured by the client do not match
       those parsed by the decoder, a `Dynamic Resolution Change` will be
       triggered to reconfigure them.

    .. note::

       No decoded frames are produced during this phase.

5.  Continue with the `Capture Setup` sequence.

CAPTURE format, selection과 raw format

Capture Setup 첫 단계에서 `CAPTURE` queue에 `VIDIOC_G_FMT`를 호출해 bytestream에서 parse되고 decode될 destination buffer format을 얻습니다. 입력은 CAPTURE용 `type`이며, 반환값은 decoded frame의 `width`, `height`, `pixelformat`, multi-planar일 때 `num_planes`, 표준 frame buffer 의미의 `sizeimage`와 `bytesperline`입니다.

기본 `pixelformat`은 현재 stream에 대해 decoder가 지원하는 어느 format이든 될 수 있으며 decoder는 최적 format을 선택해야 합니다. 예를 들어 RGB 변환이 추가로 필요하다면 YUV가 기본값으로 선호될 수 있습니다.

선택 단계로 `VIDIOC_G_SELECTION`에 CAPTURE용 `type`과 `target = V4L2_SEL_TGT_COMPOSE`를 주면 visible rectangle `r.left`, `r.top`, `r.width`, `r.height`를 얻을 수 있습니다. 이 rectangle은 CAPTURE G_FMT의 frame buffer resolution 안에 들어가야 합니다.

CAPTURE selection target은 coded bounds, 의미 있는 picture 영역, crop 결과, compose 가능 bounds, 기본 compose, 실제 compose, 하드웨어가 덮어쓰는 padded 영역을 각각 표현합니다. stream metadata parsing 전에는 이 값들의 의미가 보장되지 않습니다.

stream 정보가 확정된 뒤 `CAPTURE`에서 `VIDIOC_ENUM_FMT`를 호출하면 현재 stream에 지원되는 raw format을 열거할 수 있고, 그중 하나를 S_FMT로 선택할 수 있습니다. 이 목록은 decoder 전체 capability가 아니라 현재 OUTPUT format과 parse된 metadata에 맞는 부분집합입니다.

예를 들어 어떤 decoder가 1920x1088 이하에서는 YUV와 RGB를 모두 지원하지만 그보다 높은 해상도에서는 YUV만 지원할 수 있습니다. 높은 해상도를 parse한 뒤에는 RGB가 열거되지 않지만, 같은 stream의 후속 resolution change로 낮은 해상도로 전환되면 RGB가 다시 반환될 수 있습니다.

Capture Setup
=============

1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
    destination buffers parsed/decoded from the bytestream.

    * **Required fields:**

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

    * **Returned fields:**

      ``width``, ``height``
          frame buffer resolution for the decoded frames.

      ``pixelformat``
          pixel format for decoded frames.

      ``num_planes`` (for _MPLANE ``type`` only)
          number of planes for pixelformat.

      ``sizeimage``, ``bytesperline``
          as per standard semantics; matching frame buffer format.

    .. note::

       The value of ``pixelformat`` may be any pixel format supported by the
       decoder for the current stream. The decoder should choose a
       preferred/optimal format for the default configuration. For example, a
       YUV format may be preferred over an RGB format if an additional
       conversion step would be required for the latter.

2.  **Optional.** Acquire the visible resolution via
    :c:func:`VIDIOC_G_SELECTION`.

    * **Required fields:**

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

      ``target``
          set to ``V4L2_SEL_TGT_COMPOSE``.

    * **Returned fields:**

      ``r.left``, ``r.top``, ``r.width``, ``r.height``
          the visible rectangle; it must fit within the frame buffer resolution
          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.

    * The following selection targets are supported on ``CAPTURE``:

      ``V4L2_SEL_TGT_CROP_BOUNDS``
          corresponds to the coded resolution of the stream.

      ``V4L2_SEL_TGT_CROP_DEFAULT``
          the rectangle covering the part of the ``CAPTURE`` buffer that
          contains meaningful picture data (visible area); width and height
          will be equal to the visible resolution of the stream.

      ``V4L2_SEL_TGT_CROP``
          the rectangle within the coded resolution to be output to
          ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
          hardware without additional compose/scaling capabilities.

      ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
          the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
          frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
          hardware does not support compose/scaling.

      ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
          equal to ``V4L2_SEL_TGT_CROP``.

      ``V4L2_SEL_TGT_COMPOSE``
          the rectangle inside a ``CAPTURE`` buffer into which the cropped
          frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
          read-only on hardware without additional compose/scaling capabilities.

      ``V4L2_SEL_TGT_COMPOSE_PADDED``
          the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
          hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
          write padding pixels.

    .. warning::

       The values are guaranteed to be meaningful only after the decoder
       successfully parses the stream metadata. The client must not rely on the
       query before that happens.

3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
    the ``CAPTURE`` queue. Once the stream information is parsed and known, the
    client may use this ioctl to discover which raw formats are supported for
    given stream and select one of them via :c:func:`VIDIOC_S_FMT`.

    .. important::

       The decoder will return only formats supported for the currently
       established coded format, as per the ``OUTPUT`` format and/or stream
       metadata parsed in this initialization sequence, even if more formats
       may be supported by the decoder in general. In other words, the set
       returned will be a subset of the initial query mentioned in the
       `Querying Capabilities` section.

       For example, a decoder may support YUV and RGB formats for resolutions
       1920x1088 and lower, but only YUV for higher resolutions (due to
       hardware limitations). After parsing a resolution of 1920x1088 or lower,
       :c:func:`VIDIOC_ENUM_FMT` may return a set of YUV and RGB pixel formats,
       but after parsing resolution higher than 1920x1088, the decoder will not
       return RGB, unsupported for this resolution.

       However, subsequent resolution change event triggered after
       discovering a resolution change within the same stream may switch
       the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
       would return RGB formats again in that case.

CAPTURE format 설정과 buffer 재사용 판단

client는 선택적으로 `CAPTURE`의 `VIDIOC_S_FMT`로 G_FMT가 제안한 것과 다른 raw format을 고를 수 있습니다. 필수 필드는 CAPTURE용 `type`, raw `pixelformat`, decoded stream의 frame buffer `width`와 `height`입니다. composition 또는 scaling을 지원하면 width와 height가 G_FMT 결과와 달라질 수 있습니다.

CAPTURE format을 설정하면 새 resolution을 기준으로 compose selection rectangle이 기본값으로 초기화됩니다. compose나 scaling을 지원하는 decoder에서는 이어서 `VIDIOC_S_SELECTION`에 CAPTURE용 type, `V4L2_SEL_TGT_COMPOSE`, 원하는 rectangle을 줄 수 있습니다.

S_SELECTION은 조정된 visible rectangle을 반환합니다. codec과 하드웨어 제약 때문에 가장 가까운 지원 rectangle으로 바뀔 수 있으므로 client는 반환된 `r.left`, `r.top`, `r.width`, `r.height`를 확인해야 합니다.

새 format의 `sizeimage`가 현재 buffer 크기 이하이고, 현재 할당 수가 필요한 최소 buffer 수 이상이면 CAPTURE buffer를 다시 할당하지 않고 즉시 decode를 재개할 수 있습니다. 부족한 수만 `VIDIOC_CREATE_BUFS`로 추가해 이 조건을 만족시킬 수도 있습니다.

CAPTURE가 streaming 중이면 `V4L2_DEC_CMD_START`, 정지 상태이면 CAPTURE `VIDIOC_STREAMON`으로 재개합니다. 메모리 절약 등으로 buffer 집합을 바꾸려면 fast path 대신 이후 재할당 단계를 따릅니다.

재할당 경로에서는 CAPTURE가 streaming 중일 때 `V4L2_BUF_FLAG_LAST` buffer까지 queue/dequeue한 뒤 CAPTURE에 STREAMOFF를 호출합니다. 이때 OUTPUT은 반드시 streaming 상태를 유지해야 하며 OUTPUT STREAMOFF는 절차를 중단하고 seek를 일으킵니다. CAPTURE buffer가 있으면 REQBUFS의 `count = 0`, CAPTURE용 `type`, 표준 `memory`로 해제합니다.

4.  **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
    ``CAPTURE`` queue. The client may choose a different format than
    selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.

    * **Required fields:**

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

      ``pixelformat``
          a raw pixel format.

      ``width``, ``height``
         frame buffer resolution of the decoded stream; typically unchanged from
	 what was returned with :c:func:`VIDIOC_G_FMT`, but it may be different
	 if the hardware supports composition and/or scaling.

   * Setting the ``CAPTURE`` format will reset the compose selection rectangles
     to their default values, based on the new resolution, as described in the
     previous step.

5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
   the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
   scaling capabilities.

   * **Required fields:**

     ``type``
         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

     ``target``
         set to ``V4L2_SEL_TGT_COMPOSE``.

     ``r.left``, ``r.top``, ``r.width``, ``r.height``
         the rectangle inside a ``CAPTURE`` buffer into which the cropped
         frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``;
         read-only on hardware without additional compose/scaling capabilities.

   * **Returned fields:**

     ``r.left``, ``r.top``, ``r.width``, ``r.height``
         the visible rectangle; it must fit within the frame buffer resolution
         returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.

   .. warning::

      The decoder may adjust the compose rectangle to the nearest
      supported one to meet codec and hardware requirements. The client needs
      to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.

6.  If all the following conditions are met, the client may resume the decoding
    instantly:

    * ``sizeimage`` of the new format (determined in previous steps) is less
      than or equal to the size of currently allocated buffers,

    * the number of buffers currently allocated is greater than or equal to the
      minimum number of buffers acquired in previous steps. To fulfill this
      requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
      buffers.

    In that case, the remaining steps do not apply and the client may resume
    the decoding by one of the following actions:

    * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
      with the ``V4L2_DEC_CMD_START`` command,

    * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
      on the ``CAPTURE`` queue.

    However, if the client intends to change the buffer set, to lower
    memory usage or for any other reasons, it may be achieved by following
    the steps below.

7.  **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
    buffers on the ``CAPTURE`` queue until a buffer marked with the
    ``V4L2_BUF_FLAG_LAST`` flag is dequeued.

8.  **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
    on the ``CAPTURE`` queue to stop streaming.

    .. warning::

       The ``OUTPUT`` queue must remain streaming. Calling
       :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
       seek.

9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
    buffers using :c:func:`VIDIOC_REQBUFS`.

    * **Required fields:**

      ``count``
          set to 0.

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

      ``memory``
          follows standard semantics.

CAPTURE buffer 할당과 decode 시작

`CAPTURE`에서 `VIDIOC_REQBUFS`를 호출해 decoded frame buffer를 할당합니다. 요청 `count`는 0보다 커야 하고 `type`은 CAPTURE용이며 `memory`는 표준 의미를 따릅니다. 실제 할당 수는 요청과 다를 수 있으므로 반환된 `count`를 확인해야 합니다.

pipeline depth를 위해 최소 수보다 더 많은 buffer를 원하면 `V4L2_CID_MIN_BUFFERS_FOR_CAPTURE` control로 최소 수를 조회하고, 추가할 수를 더한 값을 REQBUFS의 `count`로 전달합니다.

더 많은 제어가 필요하면 CAPTURE의 `VIDIOC_CREATE_BUFS`를 사용할 수 있습니다. 현재 CAPTURE format보다 큰 buffer를 미리 할당하면 미래의 resolution change를 수용할 수 있습니다. 필수 입력은 `count`, CAPTURE용 `type`, `memory`, 새 buffer가 수용할 최대 frame buffer resolution을 나타내는 `format`이며 조정된 실제 count가 반환됩니다.

stream metadata parsing 전에 다른 format용 buffer를 준비하려면 먼저 OUTPUT width와 height를 원하는 coded resolution으로 설정해 decoder가 CAPTURE format을 구성하게 한 다음, CAPTURE G_FMT 결과를 저장해야 합니다. 이 저장한 format을 현재 단계의 CREATE_BUFS에 사용합니다.

할당을 마치면 CAPTURE queue에 `VIDIOC_STREAMON`을 호출해 frame decoding을 시작합니다.

10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
    ``CAPTURE`` queue.

    * **Required fields:**

      ``count``
          requested number of buffers to allocate; greater than zero.

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

      ``memory``
          follows standard semantics.

    * **Returned fields:**

      ``count``
          actual number of buffers allocated.

    .. warning::

       The actual number of allocated buffers may differ from the ``count``
       given. The client must check the updated value of ``count`` after the
       call returns.

    .. note::

       To allocate more than the minimum number of buffers (for pipeline
       depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
       control to get the minimum number of buffers required, and pass the
       obtained value plus the number of additional buffers needed in the
       ``count`` field to :c:func:`VIDIOC_REQBUFS`.

    Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
    used to have more control over buffer allocation. For example, by
    allocating buffers larger than the current ``CAPTURE`` format, future
    resolution changes can be accommodated.

    * **Required fields:**

      ``count``
          requested number of buffers to allocate; greater than zero.

      ``type``
          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.

      ``memory``
          follows standard semantics.

      ``format``
          a format representing the maximum framebuffer resolution to be
          accommodated by newly allocated buffers.

    * **Returned fields:**

      ``count``
          adjusted to the number of allocated buffers.

    .. warning::

        The actual number of allocated buffers may differ from the ``count``
        given. The client must check the updated value of ``count`` after the
        call returns.

    .. note::

       To allocate buffers for a format different than parsed from the stream
       metadata, the client must proceed as follows, before the metadata
       parsing is initiated:

       * set width and height of the ``OUTPUT`` format to desired coded resolution to
         let the decoder configure the ``CAPTURE`` format appropriately,

       * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
         until this step.

       The format obtained in the query may be then used with
       :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.

11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
    frames.

decode queue, timestamp와 reference memory

Capture Setup을 성공적으로 마치면 Decoding 상태에 도달합니다. client는 표준 의미에 따라 `VIDIOC_QBUF`와 `VIDIOC_DQBUF`로 두 queue 모두에 buffer를 넣고 빼며, OUTPUT 내용은 활성 coded pixel format과 codec별 extended control의 영향을 받습니다.

두 queue는 서로 독립적으로 동작하고 frame reordering 때문에 CAPTURE의 decoded frame 순서가 OUTPUT coded frame의 queue 순서와 다를 수 있습니다. client는 queue 사이의 직접적인 1:1 관계나 dequeue 가능 시점을 가정해서는 안 됩니다.

origin을 추적하려면 OUTPUT을 queue할 때 `struct v4l2_buffer.timestamp`를 설정할 수 있습니다. 그 OUTPUT에서 나온 CAPTURE buffer에는 dequeue 시 같은 timestamp가 복사됩니다.

하나의 OUTPUT이 여러 CAPTURE를 만들면 모두 같은 timestamp를 받고, 여러 OUTPUT이 하나의 CAPTURE를 만들면 가장 먼저 queue된 OUTPUT timestamp를 받습니다. decode order와 display order가 다르면 CAPTURE timestamp 순서도 OUTPUT timestamp 순서를 보존하지 않습니다.

reference frame으로 쓰이는 CAPTURE buffer의 backing memory는 dequeue 뒤에도 하드웨어가 읽을 수 있습니다. CAPTURE queue가 streaming인 동안 여기에 쓰면 decoded frame이 손상될 수 있습니다.

`V4L2_MEMORY_MMAP` 이외의 memory type에서는 streaming 동안 같은 CAPTURE buffer index를 항상 같은 backing memory와 함께 queue해야 합니다. 드라이버가 index로 frame을 식별하므로 reference memory를 다른 ID로 제출하면 사용 중인 메모리에 새 frame을 decode해 후속 frame을 손상할 수 있습니다.

Decoding
========

This state is reached after the `Capture Setup` sequence finishes successfully.
In this state, the client queues and dequeues buffers to both queues via
:c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
semantics.

The content of the source ``OUTPUT`` buffers depends on the active coded pixel
format and may be affected by codec-specific extended controls, as stated in
the documentation of each format.

Both queues operate independently, following the standard behavior of V4L2
buffer queues and memory-to-memory devices. In addition, the order of decoded
frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
format, e.g. frame reordering.

The client must not assume any direct relationship between ``CAPTURE``
and ``OUTPUT`` buffers and any specific timing of buffers becoming
available to dequeue. Specifically:

* a buffer queued to ``OUTPUT`` may result in no buffers being produced
  on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
  metadata syntax structures are present in it),

* a buffer queued to ``OUTPUT`` may result in more than one buffer produced
  on ``CAPTURE`` (if the encoded data contained more than one frame, or if
  returning a decoded frame allowed the decoder to return a frame that
  preceded it in decode, but succeeded it in the display order),

* a buffer queued to ``OUTPUT`` may result in a buffer being produced on
  ``CAPTURE`` later into decode process, and/or after processing further
  ``OUTPUT`` buffers, or be returned out of order, e.g. if display
  reordering is used,

* buffers may become available on the ``CAPTURE`` queue without additional
  buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
  ``OUTPUT`` buffers queued in the past whose decoding results are only
  available at later time, due to specifics of the decoding process.

.. note::

   To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
   originated from, the client can set the ``timestamp`` field of the
   :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
   ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
   will have their ``timestamp`` field set to the same value when dequeued.

   In addition to the straightforward case of one ``OUTPUT`` buffer producing
   one ``CAPTURE`` buffer, the following cases are defined:

   * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
     ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.

   * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
     the ``OUTPUT`` buffer queued first will be copied.

   * the decoding order differs from the display order (i.e. the ``CAPTURE``
     buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
     timestamps will not retain the order of ``OUTPUT`` timestamps.

.. note::

   The backing memory of ``CAPTURE`` buffers that are used as reference frames
   by the stream may be read by the hardware even after they are dequeued.
   Consequently, the client should avoid writing into this memory while the
   ``CAPTURE`` queue is streaming. Failure to observe this may result in
   corruption of decoded frames.

   Similarly, when using a memory type other than ``V4L2_MEMORY_MMAP``, the
   client should make sure that each ``CAPTURE`` buffer is always queued with
   the same backing memory for as long as the ``CAPTURE`` queue is streaming.
   The reason for this is that V4L2 buffer indices can be used by drivers to
   identify frames. Thus, if the backing memory of a reference frame is
   submitted under a different buffer ID, the driver may misidentify it and
   decode a new frame into it while it is still in use, resulting in corruption
   of the following frames.

특수 sequence와 decode 오류

decode 중 특별한 sequence가 시작되면 그 전에 처리된 모든 OUTPUT에서 유래한 CAPTURE buffer를 반환하고 마지막 buffer에 `V4L2_BUF_FLAG_LAST`를 설정합니다. client는 pending event를 확인해 SOURCE_CHANGE와 SRC_CH_RESOLUTION이면 Dynamic Resolution Change를, `V4L2_EVENT_EOS`이면 End of Stream을 수행해야 합니다. sequence들은 서로 섞여 발생할 수 있으므로 발생 순서대로 처리합니다.

decode 오류가 나면 실패 결과를 담은 CAPTURE buffer에 `V4L2_BUF_FLAG_ERROR`가 설정됩니다. decoder가 원인이 된 OUTPUT buffer를 정확히 식별할 수 있다면 그 buffer에도 같은 flag를 설정해 반환합니다.

decode를 계속할 수 없는 치명적 실패 뒤에는 해당 decoder file handle의 모든 후속 작업이 `-EIO`를 반환합니다. client는 handle을 닫고 새로 열거나, 두 queue를 STREAMOFF하고 모든 buffer를 해제한 다음 Initialization을 다시 수행해 instance를 재초기화할 수 있습니다.

During the decoding, the decoder may initiate one of the special sequences, as
listed below. The sequences will result in the decoder returning all the
``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
before the sequence started. Last of the buffers will have the
``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
must check if there is any pending event and:

* if a ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
  ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution
  Change` sequence needs to be followed,

* if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
  to be followed.

Some of the sequences can be intermixed with each other and need to be handled
as they happen. The exact operation is documented for each sequence.

Should a decoding error occur, it will be reported to the client with the level
of details depending on the decoder capabilities. Specifically:

* the CAPTURE buffer that contains the results of the failed decode operation
  will be returned with the V4L2_BUF_FLAG_ERROR flag set,

* if the decoder is able to precisely report the OUTPUT buffer that triggered
  the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
  set.

In case of a fatal failure that does not allow the decoding to continue, any
further operations on corresponding decoder file handle will return the -EIO
error code. The client may close the file handle and open a new one, or
alternatively reinitialize the instance by stopping streaming on both queues,
releasing all buffers and performing the Initialization sequence again.

Seek와 resume point

Seek는 coded data source인 `OUTPUT` queue가 제어합니다. CAPTURE에는 특별한 작업이 필수는 아니지만 독립적인 정상 decoder 동작의 영향을 받을 수 있습니다.

`VIDIOC_STREAMOFF(OUTPUT)`으로 seek를 시작하면 pending OUTPUT buffer가 모두 버려지고 표준 의미에 따라 client에 반환된 것으로 취급합니다. 이어 `VIDIOC_STREAMON(OUTPUT)`을 호출하면 새 source bytestream buffer를 받을 준비가 됩니다.

그 뒤 적절한 resume point를 찾을 때까지 seek 이후 coded data를 OUTPUT에 queue합니다. 반드시 SPS나 keyframe에서 정확히 시작할 필요는 없고, 적절한 지점을 찾을 때까지 buffer를 처리해 반환합니다. 이 탐색 중에는 CAPTURE에 decoded frame을 만들지 않아야 합니다.

일부 하드웨어는 resume point가 아닌 곳으로 seek할 때 불특정 수의 손상 frame을 CAPTURE에 낼 수 있습니다. 드라이버는 crash나 치명적 decode 오류가 일어나지 않도록 하드웨어별 처리와 workaround를 구현해야 합니다.

H.264/HEVC에서는 client가 SPS/PPS 변경을 건너뛰어 seek해서는 안 됩니다. target이 keyframe이어도 decoder에 남은 낡은 SPS/PPS 때문에 결과가 정의되지 않습니다. decoder는 crash 없이 처리해야 하지만 의미 있는 출력은 보장되지 않으며, 하드웨어가 손상을 감지하면 해당 CAPTURE buffer에 `V4L2_BUF_FLAG_ERROR`를 설정합니다.

resume point를 찾으면 decoder가 새 decoded CAPTURE buffer를 반환하기 시작합니다. target의 parameter가 이전 구간과 다르면 Dynamic Resolution Change가 일어날 수 있으며 일반 절차대로 처리해야 합니다.

CAPTURE는 OUTPUT과 독립적이므로 seek 전 OUTPUT에서 유래한 decoded buffer가 seek 뒤에도 남아 반환될 수 있고, STREAMOFF로 버린 OUTPUT은 대응 CAPTURE를 만들지 않을 수 있습니다. `QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H)` 뒤 CAPTURE 결과는 `{A', B', G', H'}`, `{A', G', H'}`, `{G', H'}` 모두 허용됩니다.

seek 이후 첫 frame은 timestamp로 OUTPUT과 CAPTURE를 맞추거나 STOP/START로 decoder를 drain해 식별할 수 있습니다. 즉시 seek가 필요하면 CAPTURE streaming도 재시작해 decode됐지만 아직 dequeue하지 않은 buffer를 버릴 수 있습니다.

Seek
====

Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
The seek does not require any specific operation on the ``CAPTURE`` queue, but
it may be affected as per normal decoder operation.

1. Stop the ``OUTPUT`` queue to begin the seek sequence via
   :c:func:`VIDIOC_STREAMOFF`.

   * **Required fields:**

     ``type``
         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.

   * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
     treated as returned to the client (following standard semantics).

2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.

   * **Required fields:**

     ``type``
         a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.

   * The decoder will start accepting new source bytestream buffers after the
     call returns.

3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
   queue until a suitable resume point is found.

   .. note::

      There is no requirement to begin queuing coded data starting exactly
      from a resume point (e.g. SPS or a keyframe). Any queued ``OUTPUT``
      buffers will be processed and returned to the client until a suitable
      resume point is found.  While looking for a resume point, the decoder
      should not produce any decoded frames into ``CAPTURE`` buffers.

      Some hardware is known to mishandle seeks to a non-resume point. Such an
      operation may result in an unspecified number of corrupted decoded frames
      being made available on the ``CAPTURE`` queue. Drivers must ensure that
      no fatal decoding errors or crashes occur, and implement any necessary
      handling and workarounds for hardware issues related to seek operations.

   .. warning::

      In case of the H.264/HEVC codec, the client must take care not to seek
      over a change of SPS/PPS. Even though the target frame could be a
      keyframe, the stale SPS/PPS inside decoder state would lead to undefined
      results when decoding. Although the decoder must handle that case without
      a crash or a fatal decode error, the client must not expect a sensible
      decode output.

      If the hardware can detect such corrupted decoded frames, then
      corresponding buffers will be returned to the client with the
      V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
      description of decode error reporting.

4. After a resume point is found, the decoder will start returning ``CAPTURE``
   buffers containing decoded frames.

.. important::

   A seek may result in the `Dynamic Resolution Change` sequence being
   initiated, due to the seek target having decoding parameters different from
   the part of the stream decoded before the seek. The sequence must be handled
   as per normal decoder operation.

.. warning::

   It is not specified when the ``CAPTURE`` queue starts producing buffers
   containing decoded data from the ``OUTPUT`` buffers queued after the seek,
   as it operates independently from the ``OUTPUT`` queue.

   The decoder may return a number of remaining ``CAPTURE`` buffers containing
   decoded frames originating from the ``OUTPUT`` buffers queued before the
   seek sequence is performed.

   The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
   ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
   queued before the seek sequence may have matching ``CAPTURE`` buffers
   produced.  For example, given the sequence of operations on the
   ``OUTPUT`` queue:

     QBUF(A), QBUF(B), STREAMOFF(), STREAMON(), QBUF(G), QBUF(H),

   any of the following results on the ``CAPTURE`` queue is allowed:

     {A', B', G', H'}, {A', G', H'}, {G', H'}.

   To determine the CAPTURE buffer containing the first decoded frame after the
   seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
   buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
   decoder.

.. note::

   To achieve instantaneous seek, the client may restart streaming on the
   ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.

동적 해상도 변경

bytestream에 resolution metadata가 있는 stream은 decode 도중 다른 해상도로 전환해야 할 수 있습니다. 이를 감지할 수 있는 decoder는 `VIDIOC_ENUM_FMT`에서 coded format에 `V4L2_FMT_FLAG_DYN_RESOLUTION`을 설정합니다.

이 sequence는 coded resolution, visible resolution selection rectangle, decode에 필요한 최소 buffer 수, bitstream bit-depth 가운데 하나 이상이 이전 확정값과 다른 coded frame을 발견할 때 시작됩니다.

decoder는 `changes = V4L2_EVENT_SRC_CH_RESOLUTION`인 `V4L2_EVENT_SOURCE_CHANGE`를 보냅니다. event가 queue된 뒤 client가 조회하는 queue format, selection rectangle, control은 변경 이후 stream에 적용되는 값을 반환합니다.

그 다음 decoder는 변경 지점 이전의 남은 buffer를 모두 처리하고 decode합니다. 마지막 이전 frame은 `V4L2_BUF_FLAG_LAST`로 표시해야 합니다. 이 buffer는 `bytesused = 0`인 빈 buffer일 수 있으며 decoded frame이 없으므로 client가 무시해야 합니다. LAST 이후 CAPTURE DQBUF는 `-EPIPE`를 반환합니다.

client는 source change event를 dequeue한 뒤 Capture Setup을 다시 수행합니다. source change는 명시적 Drain과 유사한 implicit drain을 일으켜 완료 뒤 decoder를 정지시키므로, CAPTURE에 STREAMOFF/STREAMON을 연속 호출하거나 `V4L2_DEC_CMD_START`를 호출해 decode를 재개해야 합니다.

resolution change 전체 동안 OUTPUT은 streaming 상태를 유지해야 합니다. OUTPUT STREAMOFF는 sequence를 중단하고 seek를 시작합니다. 성능과 단순성을 위해 client는 재구성 중에도 OUTPUT buffer를 계속 queue/dequeue하는 것이 좋습니다.

Dynamic Resolution Change
=========================

Streams that include resolution metadata in the bytestream may require switching
to a different resolution during the decoding.

.. note::

   Not all decoders can detect resolution changes. Those that do set the
   ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when
   :c:func:`VIDIOC_ENUM_FMT` is called.

The sequence starts when the decoder detects a coded frame with one or more of
the following parameters different from those previously established (and
reflected by corresponding queries):

* coded resolution (``OUTPUT`` width and height),

* visible resolution (selection rectangles),

* the minimum number of buffers needed for decoding,

* bit-depth of the bitstream has been changed.

Whenever that happens, the decoder must proceed as follows:

1.  After encountering a resolution change in the stream, the decoder sends a
    ``V4L2_EVENT_SOURCE_CHANGE`` event with ``changes`` set to
    ``V4L2_EVENT_SRC_CH_RESOLUTION``.

    .. important::

       Any client query issued after the decoder queues the event will return
       values applying to the stream after the resolution change, including
       queue formats, selection rectangles and controls.

2.  The decoder will then process and decode all remaining buffers from before
    the resolution change point.

    * The last buffer from before the change must be marked with the
      ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.

    .. warning::

       The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
       = 0) and in that case it must be ignored by the client, as it does not
       contain a decoded frame.

    .. note::

       Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
       with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
       :c:func:`VIDIOC_DQBUF`.

The client must continue the sequence as described below to continue the
decoding process.

1.  Dequeue the source change event.

    .. important::

       A source change triggers an implicit decoder drain, similar to the
       explicit `Drain` sequence. The decoder is stopped after it completes.
       The decoding process must be resumed with either a pair of calls to
       :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
       ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
       ``V4L2_DEC_CMD_START`` command.

2.  Continue with the `Capture Setup` sequence.

.. note::

   During the resolution change sequence, the ``OUTPUT`` queue must remain
   streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
   abort the sequence and initiate a seek.

   In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
   queue and this remains true for the duration of the entire resolution change
   sequence as well.

   The client should, for best performance and simplicity, keep queuing/dequeuing
   buffers to/from the ``OUTPUT`` queue even while processing this sequence.

Drain과 decoder 정지

Drain은 이미 queue한 모든 OUTPUT을 처리하고 관련 CAPTURE를 전부 client에 전달하는 절차입니다. 완료되면 시작 전에 넣은 모든 OUTPUT의 decoded frame을 받은 상태가 됩니다.

`VIDIOC_DECODER_CMD`에 `cmd = V4L2_DEC_CMD_STOP`, `flags = 0`, `pts = 0`을 주어 시작합니다. OUTPUT과 CAPTURE가 모두 streaming일 때만 실제 drain이 시작됩니다. 호환성 때문에 queue가 정지 상태여도 ioctl 자체는 실패하지 않지만 이후 drain 단계는 적용되지 않습니다.

STOP 전에 queue한 OUTPUT은 정상 처리합니다. client는 두 queue를 독립적으로 계속 다뤄야 하며, 중간에 Dynamic Resolution Change가 발생하면 먼저 처리합니다. CAPTURE는 `V4L2_BUF_FLAG_LAST`가 붙은 buffer까지 queue/dequeue하고, 빈 LAST는 무시합니다. LAST 이후 DQBUF는 `-EPIPE`입니다.

STOP 전에 넣은 OUTPUT도 모두 dequeue해야 합니다. 구형 호환성을 위해 마지막 frame이 준비되면 `V4L2_EVENT_EOS`도 발생할 수 있으나 이 동작은 deprecated이므로 의존하지 말고 `V4L2_BUF_FLAG_LAST`를 사용해야 합니다.

기존 OUTPUT과 마지막 CAPTURE를 모두 dequeue하면 decoder는 멈추며 새 OUTPUT을 받아도 처리하지 않습니다. `V4L2_DEC_CMD_START`는 drain 전 상태를 유지한 채 정상 재개합니다. CAPTURE STREAMOFF/STREAMON도 재개하지만 queue에 남은 CAPTURE를 client에 반환합니다. OUTPUT STREAMOFF/STREAMON은 pending source를 반환하고 Seek를 시작합니다.

drain을 시작하면 어느 queue든 STREAMOFF해 중단하지 않는 한 끝까지 진행해야 합니다. 진행 중 다시 START나 STOP을 호출할 수 없으며 시도하면 `-EBUSY`가 반환됩니다. decoder command 지원 여부는 선택적으로 `VIDIOC_TRY_DECODER_CMD`로 조회할 수 있습니다.

Drain
=====

To ensure that all queued ``OUTPUT`` buffers have been processed and related
``CAPTURE`` buffers are given to the client, the client must follow the drain
sequence described below. After the drain sequence ends, the client has
received all decoded frames for all ``OUTPUT`` buffers queued before the
sequence was started.

1. Begin drain by issuing :c:func:`VIDIOC_DECODER_CMD`.

   * **Required fields:**

     ``cmd``
         set to ``V4L2_DEC_CMD_STOP``.

     ``flags``
         set to 0.

     ``pts``
         set to 0.

   .. warning::

      The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
      queues are streaming. For compatibility reasons, the call to
      :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
      not streaming, but at the same time it will not initiate the `Drain`
      sequence and so the steps described below would not be applicable.

2. Any ``OUTPUT`` buffers queued by the client before the
   :c:func:`VIDIOC_DECODER_CMD` was issued will be processed and decoded as
   normal. The client must continue to handle both queues independently,
   similarly to normal decode operation. This includes:

   * handling any operations triggered as a result of processing those buffers,
     such as the `Dynamic Resolution Change` sequence, before continuing with
     the drain sequence,

   * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
     ``V4L2_BUF_FLAG_LAST`` flag is dequeued,

     .. warning::

        The last buffer may be empty (with :c:type:`v4l2_buffer`
        ``bytesused`` = 0) and in that case it must be ignored by the client,
        as it does not contain a decoded frame.

     .. note::

        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
        marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
        :c:func:`VIDIOC_DQBUF`.

   * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
     before the ``V4L2_DEC_CMD_STOP`` command are dequeued,

   * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.

   .. note::

      For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
      event when the last frame has been decoded and all frames are ready to be
      dequeued. It is a deprecated behavior and the client must not rely on it.
      The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.

3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
   are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
   stopped and it will accept, but not process, any newly queued ``OUTPUT``
   buffers until the client issues any of the following operations:

   * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
     operation normally, with all the state from before the drain,

   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
     ``CAPTURE`` queue - the decoder will resume the operation normally,
     however any ``CAPTURE`` buffers still in the queue will be returned to the
     client,

   * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
     ``OUTPUT`` queue - any pending source buffers will be returned to the
     client and the `Seek` sequence will be triggered.

.. note::

   Once the drain sequence is initiated, the client needs to drive it to
   completion, as described by the steps above, unless it aborts the process by
   issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
   queues.  The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
   ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
   will fail with -EBUSY error code if attempted.

   Although not mandatory, the availability of decoder commands may be queried
   using :c:func:`VIDIOC_TRY_DECODER_CMD`.

End of Stream과 format commit point

decoder가 stream 내부의 end-of-stream 표시를 만나면 client의 초기 `VIDIOC_DECODER_CMD` 호출을 생략한 채 Drain sequence를 시작합니다. client는 나머지 drain 절차를 그대로 처리해야 합니다.

format 설정과 buffer 할당은 decoder 동작을 확정하는 commit point입니다. OUTPUT format을 설정하면 CAPTURE가 광고하는 format 집합과 현재 CAPTURE format이 바뀔 수 있으므로 이전 설정 보존을 기대해서는 안 됩니다. CAPTURE ENUM_FMT는 항상 현재 OUTPUT format이 지원하는 format만 반환합니다.

CAPTURE format 설정은 OUTPUT format 목록을 바꾸지 않습니다. 현재 OUTPUT과 호환되지 않는 CAPTURE format을 요청하면 decoder가 지원 format으로 조정합니다. OUTPUT ENUM_FMT는 CAPTURE와 무관하게 전체 coded format을 반환합니다. 어느 queue든 buffer가 할당된 동안 OUTPUT format을 바꿀 수 없으며 driver는 `-EBUSY`를 반환합니다. 따라서 format 설정과 할당은 언제나 master인 OUTPUT queue에서 시작해야 합니다.

End of Stream
=============

If the decoder encounters an end of stream marking in the stream, the decoder
will initiate the `Drain` sequence, which the client must handle as described
above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.

Commit Points
=============

Setting formats and allocating buffers trigger changes in the behavior of the
decoder.

1. Setting the format on the ``OUTPUT`` queue may change the set of formats
   supported/advertised on the ``CAPTURE`` queue. In particular, it also means
   that the ``CAPTURE`` format may be reset and the client must not rely on the
   previously set format being preserved.

2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
   supported for the current ``OUTPUT`` format.

3. Setting the format on the ``CAPTURE`` queue does not change the list of
   formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
   format that is not supported for the currently selected ``OUTPUT`` format
   will result in the decoder adjusting the requested ``CAPTURE`` format to a
   supported one.

4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
   supported coded formats, irrespectively of the current ``CAPTURE`` format.

5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
   the client must not change the format on the ``OUTPUT`` queue. Drivers will
   return the -EBUSY error code for any such format change attempt.

To summarize, setting formats and allocation must always start with the
``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
set of supported formats for the ``CAPTURE`` queue.