media/v4l/dev-decoder.rst

41 7. Given an ``OUTPUT`` buffer A, then A’ represents a buffer on the ``CAPTURE``
49 CAPTURE
54    into ``CAPTURE`` buffers.
79    encoders ``CAPTURE`` buffers must be returned by the encoder in decode order.
82    data resulting from the decode process; see ``CAPTURE``.
87    ``CAPTURE`` buffers must be returned by the decoder in display order.
171        node [shape = circle, label="Capture\nsetup"] CaptureSetup;
181        Initialization -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
183        CaptureSetup -> Stopped [ label = "CAPTURE\nbuffers\nready" ];
189        Decoding -> Stopped [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
192        ResChange -> CaptureSetup [ label = "CAPTURE\nformat\nestablished" ];
197        Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(CAPTURE)" ];
203        Stopped -> Decoding [ label = "V4L2_DEC_CMD_START\nor\nVIDIOC_STREAMON(CAPTURE)" ];
214      format set on ``CAPTURE``.
221    :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
228      enumerate formats on ``CAPTURE``.
278    * The ``CAPTURE`` format will be updated with an appropriate frame buffer
283      update the ``CAPTURE`` format with new values and signal a source change
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
352     required metadata to configure the ``CAPTURE`` queue are found. This is
366       :c:func:`VIDIOC_TRY_FMT` or :c:func:`VIDIOC_REQBUFS` on the ``CAPTURE``
382        and continue with the `Capture Setup` sequence. However, it must not
393 5.  Continue with the `Capture Setup` sequence.
395 Capture Setup
398 1.  Call :c:func:`VIDIOC_G_FMT` on the ``CAPTURE`` queue to get format for the
404           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
434           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
443           returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
445     * The following selection targets are supported on ``CAPTURE``:
451           the rectangle covering the part of the ``CAPTURE`` buffer that
457           ``CAPTURE``; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``; read-only on
461           the maximum rectangle within a ``CAPTURE`` buffer, which the cropped
469           the rectangle inside a ``CAPTURE`` buffer into which the cropped
474           the rectangle inside a ``CAPTURE`` buffer which is overwritten by the
484 3.  **Optional.** Enumerate ``CAPTURE`` formats via :c:func:`VIDIOC_ENUM_FMT` on
485     the ``CAPTURE`` queue. Once the stream information is parsed and known, the
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
517           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
527    * Setting the ``CAPTURE`` format will reset the compose selection rectangles
532    the ``CAPTURE`` queue if it is desired and if the decoder has compose and/or
538          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
544          the rectangle inside a ``CAPTURE`` buffer into which the cropped
552          returned by :c:func:`VIDIOC_G_FMT` on ``CAPTURE``.
574     * if the ``CAPTURE`` queue is streaming, call :c:func:`VIDIOC_DECODER_CMD`
577     * if the ``CAPTURE`` queue is not streaming, call :c:func:`VIDIOC_STREAMON`
578       on the ``CAPTURE`` queue.
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.
597 9.  **If the** ``CAPTURE`` **queue has buffers allocated,** free the ``CAPTURE``
606           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
611 10. Allocate ``CAPTURE`` buffers via :c:func:`VIDIOC_REQBUFS` on the
612     ``CAPTURE`` queue.
620           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
644     Alternatively, :c:func:`VIDIOC_CREATE_BUFS` on the ``CAPTURE`` queue can be
646     allocating buffers larger than the current ``CAPTURE`` format, future
655           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
682          let the decoder configure the ``CAPTURE`` format appropriately,
684        * query the ``CAPTURE`` format using :c:func:`VIDIOC_G_FMT` and save it
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.
707 frames dequeued from the ``CAPTURE`` queue may differ from the order of queuing
711 The client must not assume any direct relationship between ``CAPTURE``
716   on ``CAPTURE`` (e.g. if it does not contain encoded data, or if only
720   on ``CAPTURE`` (if the encoded data contained more than one frame, or if
725   ``CAPTURE`` later into decode process, and/or after processing further
729 * buffers may become available on the ``CAPTURE`` queue without additional
736    To allow matching decoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
739    ``CAPTURE`` buffer(s), which resulted from decoding that ``OUTPUT`` buffer
743    one ``CAPTURE`` buffer, the following cases are defined:
745    * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
746      ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers.
748    * multiple ``OUTPUT`` buffers generate one ``CAPTURE`` buffer: timestamp of
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``
757 ``CAPTURE`` buffers that originated from all the ``OUTPUT`` buffers processed
775 * the CAPTURE buffer that contains the results of the failed decode operation
792 The seek does not require any specific operation on the ``CAPTURE`` queue, but
825       should not produce any decoded frames into ``CAPTURE`` buffers.
829       being made available on the ``CAPTURE`` queue. Drivers must ensure that
847 4. After a resume point is found, the decoder will start returning ``CAPTURE``
859    It is not specified when the ``CAPTURE`` queue starts producing buffers
863    The decoder may return a number of remaining ``CAPTURE`` buffers containing
869    queued before the seek sequence may have matching ``CAPTURE`` buffers
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
887    ``CAPTURE`` queue too to discard decoded, but not yet dequeued buffers.
939        Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer marked
954        ``CAPTURE`` queue, or a call to :c:func:`VIDIOC_DECODER_CMD` with the
957 2.  Continue with the `Capture Setup` sequence.
965    In principle, the ``OUTPUT`` queue operates separately from the ``CAPTURE``
976 ``CAPTURE`` buffers are given to the client, the client must follow the drain
996       The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
1011    * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
1022         Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
1039    are dequeued and the last ``CAPTURE`` buffer is dequeued, the decoder is
1047      ``CAPTURE`` queue - the decoder will resume the operation normally,
1048      however any ``CAPTURE`` buffers still in the queue will be returned to the
1059    issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
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
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``
1091    will result in the decoder adjusting the requested ``CAPTURE`` format to a
1095    supported coded formats, irrespectively of the current ``CAPTURE`` format.
1097 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
1103 set of supported formats for the ``CAPTURE`` queue.