Documentation/media/uapi/v4l/dev-decoder.rst

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