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