1.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 3.. _encoder: 4 5************************************************* 6Memory-to-Memory Stateful Video Encoder Interface 7************************************************* 8 9A stateful video encoder takes raw video frames in display order and encodes 10them into a bytestream. It generates complete chunks of the bytestream, including 11all metadata, headers, etc. The resulting bytestream does not require any 12further post-processing by the client. 13 14Performing software stream processing, header generation etc. in the driver 15in order to support this interface is strongly discouraged. In case such 16operations are needed, use of the Stateless Video Encoder 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 encoder 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 44Glossary 45======== 46 47Refer to :ref:`decoder-glossary`. 48 49State Machine 50============= 51 52.. kernel-render:: DOT 53 :alt: DOT digraph of encoder state machine 54 :caption: Encoder State Machine 55 56 digraph encoder_state_machine { 57 node [shape = doublecircle, label="Encoding"] Encoding; 58 59 node [shape = circle, label="Initialization"] Initialization; 60 node [shape = circle, label="Stopped"] Stopped; 61 node [shape = circle, label="Drain"] Drain; 62 node [shape = circle, label="Reset"] Reset; 63 64 node [shape = point]; qi 65 qi -> Initialization [ label = "open()" ]; 66 67 Initialization -> Encoding [ label = "Both queues streaming" ]; 68 69 Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ]; 70 Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; 71 Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; 72 Encoding -> Encoding; 73 74 Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ]; 75 Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; 76 77 Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ]; 78 Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; 79 80 Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ]; 81 Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; 82 } 83 84Querying Capabilities 85===================== 86 871. To enumerate the set of coded formats supported by the encoder, the 88 client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. 89 90 * The full set of supported formats will be returned, regardless of the 91 format set on ``OUTPUT``. 92 932. To enumerate the set of supported raw formats, the client may call 94 :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. 95 96 * Only the formats supported for the format currently active on ``CAPTURE`` 97 will be returned. 98 99 * In order to enumerate raw formats supported by a given coded format, 100 the client must first set that coded format on ``CAPTURE`` and then 101 enumerate the formats on ``OUTPUT``. 102 1033. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported 104 resolutions for a given format, passing the desired pixel format in 105 :c:type:`v4l2_frmsizeenum` ``pixel_format``. 106 107 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel 108 format will include all possible coded resolutions supported by the 109 encoder for the given coded pixel format. 110 111 * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format 112 will include all possible frame buffer resolutions supported by the 113 encoder for the given raw pixel format and coded format currently set on 114 ``CAPTURE``. 115 1164. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported 117 frame intervals for a given format and resolution, passing the desired pixel 118 format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution 119 in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum` 120 ``height``. 121 122 * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel 123 format and coded resolution will include all possible frame intervals 124 supported by the encoder for the given coded pixel format and resolution. 125 126 * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel 127 format and resolution will include all possible frame intervals supported 128 by the encoder for the given raw pixel format and resolution and for the 129 coded format, coded resolution and coded frame interval currently set on 130 ``CAPTURE``. 131 132 * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is 133 not implemented, then there are no special restrictions other than the 134 limits of the codec itself. 135 1365. Supported profiles and levels for the coded format currently set on 137 ``CAPTURE``, if applicable, may be queried using their respective controls 138 via :c:func:`VIDIOC_QUERYCTRL`. 139 1406. Any additional encoder capabilities may be discovered by querying 141 their respective controls. 142 143Initialization 144============== 145 1461. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`. 147 148 * **Required fields:** 149 150 ``type`` 151 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. 152 153 ``pixelformat`` 154 the coded format to be produced. 155 156 ``sizeimage`` 157 desired size of ``CAPTURE`` buffers; the encoder may adjust it to 158 match hardware requirements. 159 160 ``width``, ``height`` 161 ignored (read-only). 162 163 other fields 164 follow standard semantics. 165 166 * **Returned fields:** 167 168 ``sizeimage`` 169 adjusted size of ``CAPTURE`` buffers. 170 171 ``width``, ``height`` 172 the coded size selected by the encoder based on current state, e.g. 173 ``OUTPUT`` format, selection rectangles, etc. (read-only). 174 175 .. important:: 176 177 Changing the ``CAPTURE`` format may change the currently set ``OUTPUT`` 178 format. How the new ``OUTPUT`` format is determined is up to the encoder 179 and the client must ensure it matches its needs afterwards. 180 1812. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for 182 source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`. 183 184 * **Required fields:** 185 186 ``type`` 187 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. 188 189 other fields 190 follow standard semantics. 191 192 * **Returned fields:** 193 194 ``pixelformat`` 195 raw format supported for the coded format currently selected on 196 the ``CAPTURE`` queue. 197 198 other fields 199 follow standard semantics. 200 2013. Set the raw source format on the ``OUTPUT`` queue via 202 :c:func:`VIDIOC_S_FMT`. 203 204 * **Required fields:** 205 206 ``type`` 207 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. 208 209 ``pixelformat`` 210 raw format of the source. 211 212 ``width``, ``height`` 213 source resolution. 214 215 other fields 216 follow standard semantics. 217 218 * **Returned fields:** 219 220 ``width``, ``height`` 221 may be adjusted to match encoder minimums, maximums and alignment 222 requirements, as required by the currently selected formats, as 223 reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`. 224 225 other fields 226 follow standard semantics. 227 228 * Setting the ``OUTPUT`` format will reset the selection rectangles to their 229 default values, based on the new resolution, as described in the next 230 step. 231 2324. Set the raw frame interval on the ``OUTPUT`` queue via 233 :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the 234 ``CAPTURE`` queue to the same value. 235 236 * **Required fields:** 237 238 ``type`` 239 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. 240 241 ``parm.output`` 242 set all fields except ``parm.output.timeperframe`` to 0. 243 244 ``parm.output.timeperframe`` 245 the desired frame interval; the encoder may adjust it to 246 match hardware requirements. 247 248 * **Returned fields:** 249 250 ``parm.output.timeperframe`` 251 the adjusted frame interval. 252 253 .. important:: 254 255 Changing the ``OUTPUT`` frame interval *also* sets the framerate that 256 the encoder uses to encode the video. So setting the frame interval 257 to 1/24 (or 24 frames per second) will produce a coded video stream 258 that can be played back at that speed. The frame interval for the 259 ``OUTPUT`` queue is just a hint, the application may provide raw 260 frames at a different rate. It can be used by the driver to help 261 schedule multiple encoders running in parallel. 262 263 In the next step the ``CAPTURE`` frame interval can optionally be 264 changed to a different value. This is useful for off-line encoding 265 were the coded frame interval can be different from the rate at 266 which raw frames are supplied. 267 268 .. important:: 269 270 ``timeperframe`` deals with *frames*, not fields. So for interlaced 271 formats this is the time per two fields, since a frame consists of 272 a top and a bottom field. 273 274 .. note:: 275 276 It is due to historical reasons that changing the ``OUTPUT`` frame 277 interval also changes the coded frame interval on the ``CAPTURE`` 278 queue. Ideally these would be independent settings, but that would 279 break the existing API. 280 2815. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via 282 :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame 283 interval is different from the raw frame interval, which is typically 284 the case for off-line encoding. Support for this feature is signalled 285 by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. 286 287 * **Required fields:** 288 289 ``type`` 290 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. 291 292 ``parm.capture`` 293 set all fields except ``parm.capture.timeperframe`` to 0. 294 295 ``parm.capture.timeperframe`` 296 the desired coded frame interval; the encoder may adjust it to 297 match hardware requirements. 298 299 * **Returned fields:** 300 301 ``parm.capture.timeperframe`` 302 the adjusted frame interval. 303 304 .. important:: 305 306 Changing the ``CAPTURE`` frame interval sets the framerate for the 307 coded video. It does *not* set the rate at which buffers arrive on the 308 ``CAPTURE`` queue, that depends on how fast the encoder is and how 309 fast raw frames are queued on the ``OUTPUT`` queue. 310 311 .. important:: 312 313 ``timeperframe`` deals with *frames*, not fields. So for interlaced 314 formats this is the time per two fields, since a frame consists of 315 a top and a bottom field. 316 317 .. note:: 318 319 Not all drivers support this functionality, in that case just set 320 the desired coded frame interval for the ``OUTPUT`` queue. 321 322 However, drivers that can schedule multiple encoders based on the 323 ``OUTPUT`` frame interval must support this optional feature. 324 3256. **Optional.** Set the visible resolution for the stream metadata via 326 :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired 327 to be different than the full OUTPUT resolution. 328 329 * **Required fields:** 330 331 ``type`` 332 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. 333 334 ``target`` 335 set to ``V4L2_SEL_TGT_CROP``. 336 337 ``r.left``, ``r.top``, ``r.width``, ``r.height`` 338 visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS` 339 rectangle and may be subject to adjustment to match codec and 340 hardware constraints. 341 342 * **Returned fields:** 343 344 ``r.left``, ``r.top``, ``r.width``, ``r.height`` 345 visible rectangle adjusted by the encoder. 346 347 * The following selection targets are supported on ``OUTPUT``: 348 349 ``V4L2_SEL_TGT_CROP_BOUNDS`` 350 equal to the full source frame, matching the active ``OUTPUT`` 351 format. 352 353 ``V4L2_SEL_TGT_CROP_DEFAULT`` 354 equal to ``V4L2_SEL_TGT_CROP_BOUNDS``. 355 356 ``V4L2_SEL_TGT_CROP`` 357 rectangle within the source buffer to be encoded into the 358 ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``. 359 360 .. note:: 361 362 A common use case for this selection target is encoding a source 363 video with a resolution that is not a multiple of a macroblock, 364 e.g. the common 1920x1080 resolution may require the source 365 buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock 366 size. To avoid encoding the padding, the client needs to explicitly 367 configure this selection target to 1920x1080. 368 369 .. warning:: 370 371 The encoder may adjust the crop/compose rectangles to the nearest 372 supported ones to meet codec and hardware requirements. The client needs 373 to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. 374 3757. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via 376 :c:func:`VIDIOC_REQBUFS`. This may be performed in any order. 377 378 * **Required fields:** 379 380 ``count`` 381 requested number of buffers to allocate; greater than zero. 382 383 ``type`` 384 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or 385 ``CAPTURE``. 386 387 other fields 388 follow standard semantics. 389 390 * **Returned fields:** 391 392 ``count`` 393 actual number of buffers allocated. 394 395 .. warning:: 396 397 The actual number of allocated buffers may differ from the ``count`` 398 given. The client must check the updated value of ``count`` after the 399 call returns. 400 401 .. note:: 402 403 To allocate more than the minimum number of OUTPUT buffers (for pipeline 404 depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` 405 control to get the minimum number of buffers required, and pass the 406 obtained value plus the number of additional buffers needed in the 407 ``count`` field to :c:func:`VIDIOC_REQBUFS`. 408 409 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more 410 control over buffer allocation. 411 412 * **Required fields:** 413 414 ``count`` 415 requested number of buffers to allocate; greater than zero. 416 417 ``type`` 418 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. 419 420 other fields 421 follow standard semantics. 422 423 * **Returned fields:** 424 425 ``count`` 426 adjusted to the number of allocated buffers. 427 4288. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via 429 :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual 430 encoding process starts when both queues start streaming. 431 432.. note:: 433 434 If the client stops the ``CAPTURE`` queue during the encode process and then 435 restarts it again, the encoder will begin generating a stream independent 436 from the stream generated before the stop. The exact constraints depend 437 on the coded format, but may include the following implications: 438 439 * encoded frames produced after the restart must not reference any 440 frames produced before the stop, e.g. no long term references for 441 H.264/HEVC, 442 443 * any headers that must be included in a standalone stream must be 444 produced again, e.g. SPS and PPS for H.264/HEVC. 445 446Encoding 447======== 448 449This state is reached after the `Initialization` sequence finishes 450successfully. In this state, the client queues and dequeues buffers to both 451queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the 452standard semantics. 453 454The content of encoded ``CAPTURE`` buffers depends on the active coded pixel 455format and may be affected by codec-specific extended controls, as stated 456in the documentation of each format. 457 458Both queues operate independently, following standard behavior of V4L2 buffer 459queues and memory-to-memory devices. In addition, the order of encoded frames 460dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw 461frames to the ``OUTPUT`` queue, due to properties of the selected coded format, 462e.g. frame reordering. 463 464The client must not assume any direct relationship between ``CAPTURE`` and 465``OUTPUT`` buffers and any specific timing of buffers becoming 466available to dequeue. Specifically: 467 468* a buffer queued to ``OUTPUT`` may result in more than one buffer produced on 469 ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder 470 to return a frame that preceded it in display, but succeeded it in the decode 471 order; however, there may be other reasons for this as well), 472 473* a buffer queued to ``OUTPUT`` may result in a buffer being produced on 474 ``CAPTURE`` later into encode process, and/or after processing further 475 ``OUTPUT`` buffers, or be returned out of order, e.g. if display 476 reordering is used, 477 478* buffers may become available on the ``CAPTURE`` queue without additional 479 buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the 480 ``OUTPUT`` buffers queued in the past whose encoding results are only 481 available at later time, due to specifics of the encoding process, 482 483* buffers queued to ``OUTPUT`` may not become available to dequeue instantly 484 after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the 485 encoder needs to use the frame as a reference for encoding further frames. 486 487.. note:: 488 489 To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they 490 originated from, the client can set the ``timestamp`` field of the 491 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The 492 ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer 493 will have their ``timestamp`` field set to the same value when dequeued. 494 495 In addition to the straightforward case of one ``OUTPUT`` buffer producing 496 one ``CAPTURE`` buffer, the following cases are defined: 497 498 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same 499 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers, 500 501 * the encoding order differs from the presentation order (i.e. the 502 ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers): 503 ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. 504 505.. note:: 506 507 To let the client distinguish between frame types (keyframes, intermediate 508 frames; the exact list of types depends on the coded format), the 509 ``CAPTURE`` buffers will have corresponding flag bits set in their 510 :c:type:`v4l2_buffer` struct when dequeued. See the documentation of 511 :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags 512 and their meanings. 513 514Should an encoding error occur, it will be reported to the client with the level 515of details depending on the encoder capabilities. Specifically: 516 517* the ``CAPTURE`` buffer (if any) that contains the results of the failed encode 518 operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set, 519 520* if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered 521 the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag 522 set. 523 524.. note:: 525 526 If a ``CAPTURE`` buffer is too small then it is just returned with the 527 ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this 528 error occurred because the buffer was too small, and to provide support to 529 free existing buffers that were too small. 530 531In case of a fatal failure that does not allow the encoding to continue, any 532further operations on corresponding encoder file handle will return the -EIO 533error code. The client may close the file handle and open a new one, or 534alternatively reinitialize the instance by stopping streaming on both queues, 535releasing all buffers and performing the Initialization sequence again. 536 537Encoding Parameter Changes 538========================== 539 540The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder 541parameters at any time. The availability of parameters is encoder-specific 542and the client must query the encoder to find the set of available controls. 543 544The ability to change each parameter during encoding is encoder-specific, as 545per the standard semantics of the V4L2 control interface. The client may 546attempt to set a control during encoding and if the operation fails with the 547-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the 548configuration change to be allowed. To do this, it may follow the `Drain` 549sequence to avoid losing the already queued/encoded frames. 550 551The timing of parameter updates is encoder-specific, as per the standard 552semantics of the V4L2 control interface. If the client needs to apply the 553parameters exactly at specific frame, using the Request API 554(:ref:`media-request-api`) should be considered, if supported by the encoder. 555 556Drain 557===== 558 559To ensure that all the queued ``OUTPUT`` buffers have been processed and the 560related ``CAPTURE`` buffers are given to the client, the client must follow the 561drain sequence described below. After the drain sequence ends, the client has 562received all encoded frames for all ``OUTPUT`` buffers queued before the 563sequence was started. 564 5651. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`. 566 567 * **Required fields:** 568 569 ``cmd`` 570 set to ``V4L2_ENC_CMD_STOP``. 571 572 ``flags`` 573 set to 0. 574 575 ``pts`` 576 set to 0. 577 578 .. warning:: 579 580 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` 581 queues are streaming. For compatibility reasons, the call to 582 :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is 583 not streaming, but at the same time it will not initiate the `Drain` 584 sequence and so the steps described below would not be applicable. 585 5862. Any ``OUTPUT`` buffers queued by the client before the 587 :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as 588 normal. The client must continue to handle both queues independently, 589 similarly to normal encode operation. This includes: 590 591 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the 592 ``V4L2_BUF_FLAG_LAST`` flag is dequeued, 593 594 .. warning:: 595 596 The last buffer may be empty (with :c:type:`v4l2_buffer` 597 ``bytesused`` = 0) and in that case it must be ignored by the client, 598 as it does not contain an encoded frame. 599 600 .. note:: 601 602 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer 603 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from 604 :c:func:`VIDIOC_DQBUF`. 605 606 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued 607 before the ``V4L2_ENC_CMD_STOP`` command are dequeued, 608 609 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it. 610 611 .. note:: 612 613 For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS`` 614 event when the last frame has been encoded and all frames are ready to be 615 dequeued. It is deprecated behavior and the client must not rely on it. 616 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. 617 6183. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are 619 dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped 620 and it will accept, but not process any newly queued ``OUTPUT`` buffers 621 until the client issues any of the following operations: 622 623 * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume 624 operation normally, with all the state from before the drain, 625 626 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the 627 ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence) 628 and then resume encoding, 629 630 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the 631 ``OUTPUT`` queue - the encoder will resume operation normally, however any 632 source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP`` 633 and :c:func:`VIDIOC_STREAMOFF` will be discarded. 634 635.. note:: 636 637 Once the drain sequence is initiated, the client needs to drive it to 638 completion, as described by the steps above, unless it aborts the process by 639 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` 640 queues. The client is not allowed to issue ``V4L2_ENC_CMD_START`` or 641 ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they 642 will fail with -EBUSY error code if attempted. 643 644 For reference, handling of various corner cases is described below: 645 646 * In case of no buffer in the ``OUTPUT`` queue at the time the 647 ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes 648 immediately and the encoder returns an empty ``CAPTURE`` buffer with the 649 ``V4L2_BUF_FLAG_LAST`` flag set. 650 651 * In case of no buffer in the ``CAPTURE`` queue at the time the drain 652 sequence completes, the next time the client queues a ``CAPTURE`` buffer 653 it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST`` 654 flag set. 655 656 * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the 657 middle of the drain sequence, the drain sequence is canceled and all 658 ``CAPTURE`` buffers are implicitly returned to the client. 659 660 * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the 661 middle of the drain sequence, the drain sequence completes immediately and 662 next ``CAPTURE`` buffer will be returned empty with the 663 ``V4L2_BUF_FLAG_LAST`` flag set. 664 665 Although not mandatory, the availability of encoder commands may be queried 666 using :c:func:`VIDIOC_TRY_ENCODER_CMD`. 667 668Reset 669===== 670 671The client may want to request the encoder to reinitialize the encoding, so 672that the following stream data becomes independent from the stream data 673generated before. Depending on the coded format, that may imply that: 674 675* encoded frames produced after the restart must not reference any frames 676 produced before the stop, e.g. no long term references for H.264/HEVC, 677 678* any headers that must be included in a standalone stream must be produced 679 again, e.g. SPS and PPS for H.264/HEVC. 680 681This can be achieved by performing the reset sequence. 682 6831. Perform the `Drain` sequence to ensure all the in-flight encoding finishes 684 and respective buffers are dequeued. 685 6862. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This 687 will return all currently queued ``CAPTURE`` buffers to the client, without 688 valid frame data. 689 6903. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and 691 continue with regular encoding sequence. The encoded frames produced into 692 ``CAPTURE`` buffers from now on will contain a standalone stream that can be 693 decoded without the need for frames encoded before the reset sequence, 694 starting at the first ``OUTPUT`` buffer queued after issuing the 695 `V4L2_ENC_CMD_STOP` of the `Drain` sequence. 696 697This sequence may be also used to change encoding parameters for encoders 698without the ability to change the parameters on the fly. 699 700Commit Points 701============= 702 703Setting formats and allocating buffers triggers changes in the behavior of the 704encoder. 705 7061. Setting the format on the ``CAPTURE`` queue may change the set of formats 707 supported/advertised on the ``OUTPUT`` queue. In particular, it also means 708 that the ``OUTPUT`` format may be reset and the client must not rely on the 709 previously set format being preserved. 710 7112. Enumerating formats on the ``OUTPUT`` queue always returns only formats 712 supported for the current ``CAPTURE`` format. 713 7143. Setting the format on the ``OUTPUT`` queue does not change the list of 715 formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT`` 716 format that is not supported for the currently selected ``CAPTURE`` format 717 will result in the encoder adjusting the requested ``OUTPUT`` format to a 718 supported one. 719 7204. Enumerating formats on the ``CAPTURE`` queue always returns the full set of 721 supported coded formats, irrespective of the current ``OUTPUT`` format. 722 7235. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, 724 the client must not change the format on the ``CAPTURE`` queue. Drivers will 725 return the -EBUSY error code for any such format change attempt. 726 727To summarize, setting formats and allocation must always start with the 728``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the 729set of supported formats for the ``OUTPUT`` queue. 730