Lines Matching full:the
9 A stateful video decoder takes complete chunks of the bytestream (e.g. Annex-B
11 display order. The decoder is expected not to require any additional information
12 from the client to process these buffers.
14 Performing software parsing, processing etc. of the stream in the driver in
16 operations are needed, use of the Stateless Video Decoder 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 decoder capabilities and following the general V4L2 guidelines.
41 7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
50 the destination buffer queue; for decoders, the queue of buffers containing
51 decoded frames; for encoders, the queue of buffers containing an encoded
53 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; data is captured from the hardware
57 the application communicating with the decoder or encoder implementing
76 the order in which frames are decoded; may differ from display order if the
78 ``OUTPUT`` buffers must be queued by the client in decode order; for
79 encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
82 data resulting from the decode process; see ``CAPTURE``.
85 the order in which frames must be displayed; for encoders, ``OUTPUT``
86 buffers must be queued by the client in display order; for decoders,
87 ``CAPTURE`` buffers must be returned by the decoder in display order.
98 stream, which clears the list of earlier reference frames (DPBs).
107 popular codecs the size is 16x16 samples (pixels).
110 the source buffer queue; for decoders, the queue of buffers containing
111 an encoded bytestream; for encoders, the queue of buffers containing raw
113 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the hardware is fed with data
123 a point in the bytestream from which decoding may start/continue, without
129 data fed to the decoder or encoder; see ``OUTPUT``.
135 resolution in pixels of source frames being source to the encoder and
136 subject to further cropping to the bounds of visible resolution; relevant to
153 stream resolution of the visible picture, in pixels, to be used for
187 Decoding -> EoS [ label = "EoS mark\nin the stream" ];
210 1. To enumerate the set of coded formats supported by the decoder, the
213 * The full set of supported formats will be returned, regardless of the
215 * Check the flags field of :c:type:`v4l2_fmtdesc` for more information
216 about the decoder's capabilities with respect to each coded format.
217 In particular whether or not the decoder has a full-fledged bytestream
218 parser and if the decoder supports dynamic resolution changes.
220 2. To enumerate the set of supported raw formats, the client may call
223 * Only the formats supported for the format currently active on ``OUTPUT``
227 the client must first set that coded format on ``OUTPUT`` and then
230 3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported
235 format will include all possible coded resolutions supported by the
239 will include all possible frame buffer resolutions supported by the
240 decoder for given raw pixel format and the coded format currently set on
243 4. Supported profiles and levels for the coded format currently set on
250 1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`.
261 coded resolution of the stream; required only if it cannot be parsed
262 from the stream for the given coded format; otherwise the decoder will
264 as soon as it can parse the actual coded resolution from the stream.
267 desired size of ``OUTPUT`` buffers; the decoder may adjust it to
278 * The ``CAPTURE`` format will be updated with an appropriate frame buffer
279 resolution instantly based on the width and height returned by
282 after the decoder is done parsing the information from the stream, it will
283 update the ``CAPTURE`` format with new values and signal a source change
284 event, regardless of whether they match the values set by the client or
289 Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
290 format. How the new ``CAPTURE`` format is determined is up to the decoder
291 and the client must ensure it matches its needs afterwards.
310 the actual number of buffers allocated.
314 The actual number of allocated buffers may differ from the ``count``
315 given. The client must check the updated value of ``count`` after the
318 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``OUTPUT`` queue can be
338 adjusted to the number of allocated buffers.
342 The actual number of allocated buffers may differ from the ``count``
343 given. The client must check the updated value of ``count`` after the
346 3. Start streaming on the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
349 in the stream.** Continue queuing/dequeuing bytestream buffers to/from the
350 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`. The
351 buffers will be processed and returned to the client in order, until
352 required metadata to configure the ``CAPTURE`` queue are found. This is
353 indicated by the decoder sending a ``V4L2_EVENT_SOURCE_CHANGE`` event with
356 * It is not an error if the first buffer does not contain enough data for
357 this to occur. Processing of the buffers will continue as long as more
360 * If data in a buffer that triggers the event is required to decode the
361 first frame, it will not be returned to the client, until the
362 initialization sequence completes and the frame is decoded.
364 * If the client has not set the coded resolution of the stream on its own,
366 :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
367 queue will not return the real values for the stream until a
373 Any client query issued after the decoder queues the event will return
374 values applying to the just parsed stream, including queue formats,
379 A client capable of acquiring stream parameters from the bytestream on
380 its own may attempt to set the width and height of the ``OUTPUT`` format
381 to non-zero values matching the coded size of the stream, skip this step
382 and continue with the `Capture Setup` sequence. However, it must not
384 selection rectangles and controls, since the decoder has not parsed them
385 from the stream yet. If the values configured by the client do not match
386 those parsed by the decoder, a `Dynamic Resolution Change` will be
393 5. Continue with the `Capture Setup` sequence.
398 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
399 destination buffers parsed/decoded from the bytestream.
409 frame buffer resolution for the decoded frames.
422 The value of ``pixelformat`` may be any pixel format supported by the
423 decoder for the current stream. The decoder should choose a
424 preferred/optimal format for the default configuration. For example, a
426 conversion step would be required for the latter.
428 2. **Optional.** Acquire the visible resolution via
442 the visible rectangle; it must fit within the frame buffer resolution
445 * The following selection targets are supported on ``CAPTURE``:
448 corresponds to the coded resolution of the stream.
451 the rectangle covering the part of the ``CAPTURE`` buffer that
453 will be equal to the visible resolution of the stream.
456 the rectangle within the coded resolution to be output to
461 the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
462 frame can be composed into; equal to ``V4L2_SEL_TGT_CROP`` if the
469 the rectangle inside a ``CAPTURE`` buffer into which the cropped
474 the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
475 hardware; equal to ``V4L2_SEL_TGT_COMPOSE`` if the hardware does not
480 The values are guaranteed to be meaningful only after the decoder
481 successfully parses the stream metadata. The client must not rely on the
485 the ``CAPTURE`` queue. Once the stream information is parsed and known, the
491 The decoder will return only formats supported for the currently
492 established coded format, as per the ``OUTPUT`` format and/or stream
494 may be supported by the decoder in general. In other words, the set
495 returned will be a subset of the initial query mentioned in the
502 but after parsing resolution higher than 1920x1088, the decoder will not
506 discovering a resolution change within the same stream may switch
507 the stream into a lower resolution and :c:func:`VIDIOC_ENUM_FMT`
510 4. **Optional.** Set the ``CAPTURE`` format via :c:func:`VIDIOC_S_FMT` on the
511 ``CAPTURE`` queue. The client may choose a different format than
512 selected/suggested by the decoder in :c:func:`VIDIOC_G_FMT`.
523 frame buffer resolution of the decoded stream; typically unchanged from
525 if the hardware supports composition and/or scaling.
527 * Setting the ``CAPTURE`` format will reset the compose selection rectangles
528 to their default values, based on the new resolution, as described in the
531 5. **Optional.** Set the compose rectangle via :c:func:`VIDIOC_S_SELECTION` on
532 the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
544 the rectangle inside a ``CAPTURE`` buffer into which the cropped
551 the visible rectangle; it must fit within the frame buffer resolution
556 The decoder may adjust the compose rectangle to the nearest
557 supported one to meet codec and hardware requirements. The client needs
558 to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`.
560 6. If all the following conditions are met, the client may resume the decoding
563 * ``sizeimage`` of the new format (determined in previous steps) is less
564 than or equal to the size of currently allocated buffers,
566 * the number of buffers currently allocated is greater than or equal to the
568 requirement, the client may use :c:func:`VIDIOC_CREATE_BUFS` to add new
571 In that case, the remaining steps do not apply and the client may resume
572 the decoding by one of the following actions:
574 * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
575 with the ``V4L2_DEC_CMD_START`` command,
577 * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
578 on the ``CAPTURE`` queue.
580 However, if the client intends to change the buffer set, to lower
582 the steps below.
584 7. **If the** ``CAPTURE`` **queue is streaming,** keep queuing and dequeuing
585 buffers on the ``CAPTURE`` queue until a buffer marked with the
588 8. **If the** ``CAPTURE`` **queue is streaming,** call :c:func:`VIDIOC_STREAMOFF`
589 on the ``CAPTURE`` queue to stop streaming.
593 The ``OUTPUT`` queue must remain streaming. Calling
594 :c:func:`VIDIOC_STREAMOFF` on it would abort the sequence and trigger a
597 9. **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
611 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
632 The actual number of allocated buffers may differ from the ``count``
633 given. The client must check the updated value of ``count`` after the
638 To allocate more than the minimum number of buffers (for pipeline
639 depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE``
640 control to get the minimum number of buffers required, and pass the
641 obtained value plus the number of additional buffers needed in the
644 Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
646 allocating buffers larger than the current ``CAPTURE`` format, future
661 a format representing the maximum framebuffer resolution to be
667 adjusted to the number of allocated buffers.
671 The actual number of allocated buffers may differ from the ``count``
672 given. The client must check the updated value of ``count`` after the
677 To allocate buffers for a format different than parsed from the stream
678 metadata, the client must proceed as follows, before the metadata
681 * set width and height of the ``OUTPUT`` format to desired coded resolution to
682 let the decoder configure the ``CAPTURE`` format appropriately,
684 * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
687 The format obtained in the query may be then used with
688 :c:func:`VIDIOC_CREATE_BUFS` in this step to allocate the buffers.
690 11. Call :c:func:`VIDIOC_STREAMON` on the ``CAPTURE`` queue to start decoding
696 This state is reached after the `Capture Setup` sequence finishes successfully.
697 In this state, the client queues and dequeues buffers to both queues via
698 :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the standard
701 The content of the source ``OUTPUT`` buffers depends on the active coded pixel
703 the documentation of each format.
705 Both queues operate independently, following the standard behavior of V4L2
706 buffer queues and memory-to-memory devices. In addition, the order of decoded
707 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
708 coded frames to the ``OUTPUT`` queue, due to properties of the selected coded
711 The client must not assume any direct relationship between ``CAPTURE``
720 on ``CAPTURE`` (if the encoded data contained more than one frame, or if
721 returning a decoded frame allowed the decoder to return a frame that
722 preceded it in decode, but succeeded it in the display order),
729 * buffers may become available on the ``CAPTURE`` queue without additional
730 buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the
731 ``OUTPUT`` buffers queued in the past whose decoding results are only
732 available at later time, due to specifics of the decoding process.
737 originated from, the client can set the ``timestamp`` field of the
738 :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The
740 will have their ``timestamp`` field set to the same value when dequeued.
742 In addition to the straightforward case of one ``OUTPUT`` buffer producing
743 one ``CAPTURE`` buffer, the following cases are defined:
745 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
749 the ``OUTPUT`` buffer queued first will be copied.
751 * the decoding order differs from the display order (i.e. the ``CAPTURE``
752 buffers are out-of-order compared to the ``OUTPUT`` buffers): ``CAPTURE``
753 timestamps will not retain the order of ``OUTPUT`` timestamps.
755 During the decoding, the decoder may initiate one of the special sequences, as
756 listed below. The sequences will result in the decoder returning all the
757 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
758 before the sequence started. Last of the buffers will have the
759 ``V4L2_BUF_FLAG_LAST`` flag set. To determine the sequence to follow, the client
763 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending, the `Dynamic Resolution
766 * if a ``V4L2_EVENT_EOS`` event is pending, the `End of Stream` sequence needs
769 Some of the sequences can be intermixed with each other and need to be handled
770 as they happen. The exact operation is documented for each sequence.
772 Should a decoding error occur, it will be reported to the client with the level
773 of details depending on the decoder capabilities. Specifically:
775 * the CAPTURE buffer that contains the results of the failed decode operation
776 will be returned with the V4L2_BUF_FLAG_ERROR flag set,
778 * if the decoder is able to precisely report the OUTPUT buffer that triggered
779 the error, such buffer will be returned with the V4L2_BUF_FLAG_ERROR flag
782 In case of a fatal failure that does not allow the decoding to continue, any
783 further operations on corresponding decoder file handle will return the -EIO
784 error code. The client may close the file handle and open a new one, or
785 alternatively reinitialize the instance by stopping streaming on both queues,
786 releasing all buffers and performing the Initialization sequence again.
791 Seek is controlled by the ``OUTPUT`` queue, as it is the source of coded data.
792 The seek does not require any specific operation on the ``CAPTURE`` queue, but
795 1. Stop the ``OUTPUT`` queue to begin the seek sequence via
803 * The decoder will drop all the pending ``OUTPUT`` buffers and they must be
804 treated as returned to the client (following standard semantics).
806 2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`.
813 * The decoder will start accepting new source bytestream buffers after the
816 3. Start queuing buffers containing coded data after the seek to the ``OUTPUT``
823 buffers will be processed and returned to the client until a suitable
824 resume point is found. While looking for a resume point, the decoder
829 being made available on the ``CAPTURE`` queue. Drivers must ensure that
835 In case of the H.264/HEVC codec, the client must take care not to seek
836 over a change of SPS/PPS. Even though the target frame could be a
837 keyframe, the stale SPS/PPS inside decoder state would lead to undefined
838 results when decoding. Although the decoder must handle that case without
839 a crash or a fatal decode error, the client must not expect a sensible
842 If the hardware can detect such corrupted decoded frames, then
843 corresponding buffers will be returned to the client with the
844 V4L2_BUF_FLAG_ERROR set. See the `Decoding` section for further
847 4. After a resume point is found, the decoder will start returning ``CAPTURE``
852 A seek may result in the `Dynamic Resolution Change` sequence being
853 initiated, due to the seek target having decoding parameters different from
854 the part of the stream decoded before the seek. The sequence must be handled
859 It is not specified when the ``CAPTURE`` queue starts producing buffers
860 containing decoded data from the ``OUTPUT`` buffers queued after the seek,
861 as it operates independently from the ``OUTPUT`` queue.
863 The decoder may return a number of remaining ``CAPTURE`` buffers containing
864 decoded frames originating from the ``OUTPUT`` buffers queued before the
867 The ``VIDIOC_STREAMOFF`` operation discards any remaining queued
868 ``OUTPUT`` buffers, which means that not all of the ``OUTPUT`` buffers
869 queued before the seek sequence may have matching ``CAPTURE`` buffers
870 produced. For example, given the sequence of operations on the
875 any of the following results on the ``CAPTURE`` queue is allowed:
879 To determine the CAPTURE buffer containing the first decoded frame after the
880 seek, the client may observe the timestamps to match the CAPTURE and OUTPUT
881 buffers or use V4L2_DEC_CMD_STOP and V4L2_DEC_CMD_START to drain the
886 To achieve instantaneous seek, the client may restart streaming on the
892 Streams that include resolution metadata in the bytestream may require switching
893 to a different resolution during the decoding.
897 Not all decoders can detect resolution changes. Those that do set the
898 ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for the coded format when
901 The sequence starts when the decoder detects a coded frame with one or more of
902 the following parameters different from those previously established (and
909 * the minimum number of buffers needed for decoding,
911 * bit-depth of the bitstream has been changed.
913 Whenever that happens, the decoder must proceed as follows:
915 1. After encountering a resolution change in the stream, the decoder sends a
921 Any client query issued after the decoder queues the event will return
922 values applying to the stream after the resolution change, including
925 2. The decoder will then process and decode all remaining buffers from before
926 the resolution change point.
928 * The last buffer from before the change must be marked with the
929 ``V4L2_BUF_FLAG_LAST`` flag, similarly to the `Drain` sequence above.
933 The last buffer may be empty (with :c:type:`v4l2_buffer` ``bytesused``
934 = 0) and in that case it must be ignored by the client, as it does not
939 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
943 The client must continue the sequence as described below to continue the
946 1. Dequeue the source change event.
950 A source change triggers an implicit decoder drain, similar to the
951 explicit `Drain` sequence. The decoder is stopped after it completes.
952 The decoding process must be resumed with either a pair of calls to
953 :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
954 ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
957 2. Continue with the `Capture Setup` sequence.
961 During the resolution change sequence, the ``OUTPUT`` queue must remain
962 streaming. Calling :c:func:`VIDIOC_STREAMOFF` on the ``OUTPUT`` queue would
963 abort the sequence and initiate a seek.
965 In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
966 queue and this remains true for the duration of the entire resolution change
969 The client should, for best performance and simplicity, keep queuing/dequeuing
970 buffers to/from the ``OUTPUT`` queue even while processing this sequence.
976 ``CAPTURE`` buffers are given to the client, the client must follow the drain
977 sequence described below. After the drain sequence ends, the client has
978 received all decoded frames for all ``OUTPUT`` buffers queued before the
996 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
997 queues are streaming. For compatibility reasons, the call to
998 :c:func:`VIDIOC_DECODER_CMD` will not fail even if any of the queues is
999 not streaming, but at the same time it will not initiate the `Drain`
1000 sequence and so the steps described below would not be applicable.
1002 2. Any ``OUTPUT`` buffers queued by the client before the
1004 normal. The client must continue to handle both queues independently,
1008 such as the `Dynamic Resolution Change` sequence, before continuing with
1009 the drain sequence,
1011 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1016 The last buffer may be empty (with :c:type:`v4l2_buffer`
1017 ``bytesused`` = 0) and in that case it must be ignored by the client,
1022 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
1026 * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued
1027 before the ``V4L2_DEC_CMD_STOP`` command are dequeued,
1029 * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribed to it.
1033 For backwards compatibility, the decoder will signal a ``V4L2_EVENT_EOS``
1034 event when the last frame has been decoded and all frames are ready to be
1035 dequeued. It is a deprecated behavior and the client must not rely on it.
1036 The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead.
1038 3. Once all the ``OUTPUT`` buffers queued before the ``V4L2_DEC_CMD_STOP`` call
1039 are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
1041 buffers until the client issues any of the following operations:
1043 * ``V4L2_DEC_CMD_START`` - the decoder will not be reset and will resume
1044 operation normally, with all the state from before the drain,
1046 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
1047 ``CAPTURE`` queue - the decoder will resume the operation normally,
1048 however any ``CAPTURE`` buffers still in the queue will be returned to the
1051 * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the
1052 ``OUTPUT`` queue - any pending source buffers will be returned to the
1053 client and the `Seek` sequence will be triggered.
1057 Once the drain sequence is initiated, the client needs to drive it to
1058 completion, as described by the steps above, unless it aborts the process by
1059 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
1060 queues. The client is not allowed to issue ``V4L2_DEC_CMD_START`` or
1061 ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they
1064 Although not mandatory, the availability of decoder commands may be queried
1070 If the decoder encounters an end of stream marking in the stream, the decoder
1071 will initiate the `Drain` sequence, which the client must handle as described
1072 above, skipping the initial :c:func:`VIDIOC_DECODER_CMD`.
1077 Setting formats and allocating buffers trigger changes in the behavior of the
1080 1. Setting the format on the ``OUTPUT`` queue may change the set of formats
1081 supported/advertised on the ``CAPTURE`` queue. In particular, it also means
1082 that the ``CAPTURE`` format may be reset and the client must not rely on the
1085 2. Enumerating formats on the ``CAPTURE`` queue always returns only formats
1086 supported for the current ``OUTPUT`` format.
1088 3. Setting the format on the ``CAPTURE`` queue does not change the list of
1089 formats available on the ``OUTPUT`` queue. An attempt to set a ``CAPTURE``
1090 format that is not supported for the currently selected ``OUTPUT`` format
1091 will result in the decoder adjusting the requested ``CAPTURE`` format to a
1094 4. Enumerating formats on the ``OUTPUT`` queue always returns the full set of
1095 supported coded formats, irrespectively of the current ``CAPTURE`` format.
1097 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
1098 the client must not change the format on the ``OUTPUT`` queue. Drivers will
1099 return the -EBUSY error code for any such format change attempt.
1101 To summarize, setting formats and allocation must always start with the
1102 ``OUTPUT`` queue and the ``OUTPUT`` queue is the master that governs the
1103 set of supported formats for the ``CAPTURE`` queue.