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_frmsizeenum` ``pixel_format`` and the resolution
119   in :c:type:`v4l2_frmsizeenum` ``width`` and :c:type:`v4l2_frmsizeenum`
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   * **Return 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   * **Return 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   * **Return 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   * **Return 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   * **Return 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   * **Return 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   * **Return 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   * **Return 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