media/v4l/dev-encoder.rst

1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
6 Memory-to-Memory Stateful Video Encoder Interface
12 further post-processing by the client.
34 5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be
35    used interchangeably with multi-planar API, unless specified otherwise,
47 Refer to :ref:`decoder-glossary`.
52 .. kernel-render:: DOT
65        qi -> Initialization [ label = "open()" ];
67        Initialization -> Encoding [ label = "Both queues streaming" ];
69        Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ];
70        Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
71        Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ];
72        Encoding -> Encoding;
74        Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ];
75        Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
77        Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ];
78        Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ];
80        Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ];
81        Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ];
90    * The full set of supported formats will be returned, regardless of the
112      will include all possible frame buffer resolutions supported by the
117    frame intervals for a given format and resolution, passing the desired pixel
123      format and coded resolution will include all possible frame intervals
127      format and resolution will include all possible frame intervals supported
129      coded format, coded resolution and coded frame interval currently set on
161          ignored (read-only).
173          ``OUTPUT`` format, selection rectangles, etc. (read-only).
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
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
263       In the next step the ``CAPTURE`` frame interval can optionally be
264       changed to a different value. This is useful for off-line encoding
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``
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
314       formats this is the time per two fields, since a frame consists of
320       the desired coded frame interval for the ``OUTPUT`` queue.
323       ``OUTPUT`` frame interval must support this optional feature.
327    to be different than the full OUTPUT resolution.
350          equal to the full source frame, matching the active ``OUTPUT``
455 format and may be affected by codec-specific extended controls, as stated
459 queues and memory-to-memory devices. In addition, the order of encoded frames
462 e.g. frame reordering.
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
485   encoder needs to use the frame as a reference for encoding further frames.
502      ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers):
507    To let the client distinguish between frame types (keyframes, intermediate
532 further operations on corresponding encoder file handle will return the -EIO
541 parameters at any time. The availability of parameters is encoder-specific
544 The ability to change each parameter during encoding is encoder-specific, as
547 -EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the
551 The timing of parameter updates is encoder-specific, as per the standard
553 parameters exactly at specific frame, using the Request API
554 (:ref:`media-request-api`) should be considered, if supported by the encoder.
598         as it does not contain an encoded frame.
603         marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
614       event when the last frame has been encoded and all frames are ready to be
623    * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume
627      ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence)
631      ``OUTPUT`` queue - the encoder will resume operation normally, however any
642    will fail with -EBUSY error code if attempted.
683 1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
688    valid frame data.
720 4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
725    return the -EBUSY error code for any such format change attempt.