Lines Matching full:the
10 them into a bytestream. It generates complete chunks of the bytestream, including
11 all metadata, headers, etc. The resulting bytestream does not require any
12 further post-processing by the client.
14 Performing software stream processing, header generation etc. in the driver
16 operations are needed, use of the Stateless Video Encoder Interface (in
22 1. The general V4L2 API rules apply if not specified in this document
25 2. The meaning of words "must", "may", "should", etc. is as per `RFC
36 depending on encoder capabilities and following the general V4L2 guidelines.
41 7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE``
87 1. To enumerate the set of coded formats supported by the encoder, the
90 * The full set of supported formats will be returned, regardless of the
93 2. To enumerate the set of supported raw formats, the client may call
96 * Only the formats supported for the format currently active on ``CAPTURE``
100 the client must first set that coded format on ``CAPTURE`` and then
101 enumerate the formats on ``OUTPUT``.
103 3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
104 resolutions for a given format, passing the desired pixel format in
108 format will include all possible coded resolutions supported by the
109 encoder for the given coded 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
116 4. 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
124 supported by the encoder for the given coded pixel format and resolution.
128 by the encoder for the given raw pixel format and resolution and for the
133 not implemented, then there are no special restrictions other than the
134 limits of the codec itself.
136 5. Supported profiles and levels for the coded format currently set on
146 1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`.
154 the coded format to be produced.
157 desired size of ``CAPTURE`` buffers; the encoder may adjust it to
172 the coded size selected by the encoder based on current state, e.g.
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.
182 source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`.
195 raw format supported for the coded format currently selected on
196 the ``CAPTURE`` queue.
201 3. Set the raw source format on the ``OUTPUT`` queue via
210 raw format of the source.
222 requirements, as required by the currently selected formats, as
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
232 4. 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.
245 the desired frame interval; the encoder may adjust it to
251 the adjusted frame interval.
255 Changing the ``OUTPUT`` frame interval *also* sets the framerate that
256 the encoder uses to encode the video. So setting the frame interval
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
263 In the next step the ``CAPTURE`` frame interval can optionally be
265 were the coded frame interval can be different from the rate at
271 formats this is the time per two fields, since a frame consists of
276 It is due to historical reasons that changing the ``OUTPUT`` frame
277 interval also changes the coded frame interval on the ``CAPTURE``
279 break the existing API.
281 5. **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.
296 the desired coded frame interval; the encoder may adjust it to
302 the adjusted frame interval.
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.
314 formats this is the time per two fields, since a frame consists of
320 the desired coded frame interval for the ``OUTPUT`` queue.
322 However, drivers that can schedule multiple encoders based on the
325 6. **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.
338 visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS`
345 visible rectangle adjusted by the encoder.
347 * The following selection targets are supported on ``OUTPUT``:
350 equal to the full source frame, matching the active ``OUTPUT``
357 rectangle within the source buffer to be encoded into the
364 e.g. the common 1920x1080 resolution may require the source
366 size. To avoid encoding the padding, the client needs to explicitly
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`.
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
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
426 adjusted to the number of allocated buffers.
429 :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual
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:
439 * encoded frames produced after the restart must not reference any
440 frames produced before the stop, e.g. no long term references for
449 This state is reached after the `Initialization` sequence finishes
450 successfully. In this state, the client queues and dequeues buffers to both
451 queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the
454 The content of encoded ``CAPTURE`` buffers depends on the active coded pixel
456 in the documentation of each format.
459 queues and memory-to-memory devices. In addition, the order of encoded frames
460 dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw
461 frames to the ``OUTPUT`` queue, due to properties of the selected coded format,
464 The client must not assume any direct relationship between ``CAPTURE`` and
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
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,
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.
490 originated from, the client can set the ``timestamp`` field of the
491 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
493 will have their ``timestamp`` field set to the same value when dequeued.
495 In addition to the straightforward case of one ``OUTPUT`` buffer producing
496 one ``CAPTURE`` buffer, the following cases are defined:
498 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
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.
507 To let the client distinguish between frame types (keyframes, intermediate
508 frames; the exact list of types depends on the coded format), the
510 :c:type:`v4l2_buffer` struct when dequeued. See the documentation of
514 Should an encoding error occur, it will be reported to the client with the level
515 of details depending on the encoder capabilities. Specifically:
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,
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
526 If a ``CAPTURE`` buffer is too small then it is just returned with the
528 error occurred because the buffer was too small, and to provide support to
531 In case of a fatal failure that does not allow the encoding to continue, any
532 further operations on corresponding encoder file handle will return the -EIO
533 error code. The client may close the file handle and open a new one, or
534 alternatively reinitialize the instance by stopping streaming on both queues,
535 releasing all buffers and performing the Initialization sequence again.
540 The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder
541 parameters at any time. The availability of parameters is encoder-specific
542 and the client must query the encoder to find the set of available controls.
544 The ability to change each parameter during encoding is encoder-specific, as
545 per the standard semantics of the V4L2 control interface. The client may
546 attempt 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
548 configuration change to be allowed. To do this, it may follow the `Drain`
549 sequence to avoid losing the already queued/encoded frames.
551 The timing of parameter updates is encoder-specific, as per the standard
552 semantics of the V4L2 control interface. If the client needs to apply the
553 parameters exactly at specific frame, using the Request API
554 (:ref:`media-request-api`) should be considered, if supported by the encoder.
559 To ensure that all the queued ``OUTPUT`` buffers have been processed and the
560 related ``CAPTURE`` buffers are given to the client, the client must follow the
561 drain sequence described below. After the drain sequence ends, the client has
562 received all encoded frames for all ``OUTPUT`` buffers queued before the
565 1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`.
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.
586 2. Any ``OUTPUT`` buffers queued by the client before the
588 normal. The client must continue to handle both queues independently,
591 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
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,
602 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
606 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
607 before the ``V4L2_ENC_CMD_STOP`` command are dequeued,
609 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it.
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.
618 3. 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
621 until the client issues any of the following operations:
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,
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)
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``
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
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
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``
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.
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
665 Although not mandatory, the availability of encoder commands may be queried
671 The client may want to request the encoder to reinitialize the encoding, so
672 that the following stream data becomes independent from the stream data
673 generated before. Depending on the coded format, that may imply that:
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,
681 This can be achieved by performing the reset sequence.
683 1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
686 2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This
687 will return all currently queued ``CAPTURE`` buffers to the client, without
690 3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and
691 continue with regular encoding sequence. The encoded frames produced into
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.
698 without the ability to change the parameters on the fly.
703 Setting formats and allocating buffers triggers changes in the behavior of the
706 1. 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
711 2. Enumerating formats on the ``OUTPUT`` queue always returns only formats
712 supported for the current ``CAPTURE`` format.
714 3. 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
720 4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
721 supported coded formats, irrespective of the current ``OUTPUT`` format.
723 5. 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.
727 To summarize, setting formats and allocation must always start with the
728 ``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the
729 set of supported formats for the ``OUTPUT`` queue.