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
42      irrespective of the format currently set on the ``CAPTURE`` queue.
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
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.
62    resolutions for a given format, passing desired pixel format in
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`.
80          a coded pixel format.
90       Changing the ``OUTPUT`` format may change the currently set ``CAPTURE``
91       format. The driver will derive a new ``CAPTURE`` format from the
92       ``OUTPUT`` format being set, including resolution, colorimetry
93       parameters, etc. If the client needs a specific ``CAPTURE`` format,
97    etc.) required by the ``OUTPUT`` format to enumerate the ``CAPTURE`` formats.
99 3. Call :c:func:`VIDIOC_G_FMT` for ``CAPTURE`` queue to get the format for the
113          pixel format for decoded frames.
119          as per standard semantics; matching frame buffer format.
123       The value of ``pixelformat`` may be any pixel format supported for the
124       ``OUTPUT`` format, based on the hardware capabilities. It is suggested
125       that the driver chooses the preferred/optimal format for the current
126       configuration. For example, a YUV format may be preferred over an RGB
127       format, if an additional conversion step would be required for RGB.
131    alternative raw formats are supported for the current ``OUTPUT`` format and
137       ``OUTPUT`` format and currently set controls, even if more formats may be
143       as the ``OUTPUT`` format, :c:func:`VIDIOC_ENUM_FMT` may return a set of
144       YUV and RGB pixel formats, but after setting a resolution higher than
145       1920x1088, the driver will not return RGB pixel formats, since they are
148 5. *[optional]* Choose a different ``CAPTURE`` format than suggested via
150    choose a different format than selected/suggested by the driver in
159           a raw pixel format.
167    to obtain up-to-date information about the buffers size and layout.
189       minimum of required number of ``OUTPUT`` buffers for the given format and
193 7. Allocate destination (raw format) buffers via :c:func:`VIDIOC_REQBUFS` on the
218       ``CAPTURE`` buffers for the current format, stream configuration and
239   controls relevant to the format being decoded.
242 controls that must be set on the request, depend on the active coded pixel
243 format and might be affected by codec-specific extended controls, as stated in
244 documentation of each format.
287 2. Set the codec-specific controls for the decoding request, using
300           array must contain all the codec-specific controls required to decode
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
345 and storing it into the relevant member of a codec-dependent control structure.
355 order, then user-space can take advantage of this guarantee and queue a
379 from the pre-seek position.
411    Note that due to resolution constraints, a different format may need to be