media/v4l/dev-stateless-decoder.rst

1 .. SPDX-License-Identifier: GPL-2.0
6 Memory-to-memory Stateless Video Decoder Interface
18 This section describes how user-space ("the client") is expected to communicate
24 Stateless decoders make use of the :ref:`media-request-api`. A stateless
26 ``OUTPUT`` queue when :c:func:`VIDIOC_REQBUFS` or :c:func:`VIDIOC_CREATE_BUFS`
33 ``OUTPUT`` queue.
39    calls :c:func:`VIDIOC_ENUM_FMT` on the ``OUTPUT`` queue.
41    * The driver must always return the full set of supported ``OUTPUT`` formats,
45      codec-specific capability controls (such as H.264 profiles) to the set
51    * The driver must return only the formats supported for the format currently
52      active on the ``OUTPUT`` queue.
54    * Depending on the currently set ``OUTPUT`` format, the set of supported raw
55      formats may depend on the value of some codec-dependent controls.
65 4. Supported profiles and levels for the current ``OUTPUT`` format, if
72 1. Set the coded format on the ``OUTPUT`` queue via :c:func:`VIDIOC_S_FMT`.
77          a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
90       Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
92       ``OUTPUT`` format being set, including resolution, colorimetry
97    etc.) required by the ``OUTPUT`` format to enumerate the ``CAPTURE`` formats.
115      ``num_planes`` (for _MPLANE ``type`` only)
124       ``OUTPUT`` format, based on the hardware capabilities. It is suggested
131    alternative raw formats are supported for the current ``OUTPUT`` format and
136       The driver will return only formats supported for the currently selected
137       ``OUTPUT`` format and currently set controls, even if more formats may be
141       resolutions 1920x1088 and lower, but only YUV for higher resolutions (due
143       as the ``OUTPUT`` format, :c:func:`VIDIOC_ENUM_FMT` may return a set of
167    to obtain up-to-date information about the buffers size and layout.
170    ``OUTPUT`` queue.
178           a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``.
189       minimum of required number of ``OUTPUT`` buffers for the given format and
222 8. Allocate requests (likely one per ``OUTPUT`` buffer) via
225 9. Start streaming on both ``OUTPUT`` and ``CAPTURE`` queues via
235   configuration, as a buffer submitted to the ``OUTPUT`` queue. Typically, this
241 The amount of data and contents of the source ``OUTPUT`` buffer, as well as the
243 format and might be affected by codec-specific extended controls, as stated in
248 must set the ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag on the ``OUTPUT``
251 request if the timestamp of the next ``OUTPUT`` buffer has not changed.
255 1. Queue an ``OUTPUT`` buffer containing one unit of encoded bytestream data for
282           frame, then the timestamps of all the ``OUTPUT`` buffers for a given
287 2. Set the codec-specific controls for the decoding request, using
300           array must contain all the codec-specific controls required to decode
317     If the request is submitted without an ``OUTPUT`` buffer, or if some of the
319     :c:func:`MEDIA_REQUEST_IOC_QUEUE` will return ``-ENOENT``. If more than one
320     ``OUTPUT`` buffer is queued, then it will return ``-EINVAL``.
321     :c:func:`MEDIA_REQUEST_IOC_QUEUE` returning non-zero means that no
326 frames were submitted to the ``OUTPUT`` queue).
337 buffer management: it only guarantees that dequeued ``CAPTURE`` buffers can be
345 and storing it into the relevant member of a codec-dependent control structure.
348 its units of encoded data are successfully submitted to the ``OUTPUT`` queue.
355 order, then user-space can take advantage of this guarantee and queue a
379 from the pre-seek position.
384 In order to pause, the client can just cease queuing buffers onto the ``OUTPUT``
401    corresponding output buffers.
403 3. Call :c:func:`VIDIOC_STREAMOFF` on both the ``OUTPUT`` and ``CAPTURE``
410    ``OUTPUT`` buffers), with the new resolution set on the ``OUTPUT`` queue.