Lines Matching +full:capture +full:- +full:only
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,
41 7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE``
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)" ];
88 client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
96 * Only the formats supported for the format currently active on ``CAPTURE``
100 the client must first set that coded format on ``CAPTURE`` and then
114 ``CAPTURE``.
130 ``CAPTURE``.
137 ``CAPTURE``, if applicable, may be queried using their respective controls
146 1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`.
151 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
157 desired size of ``CAPTURE`` buffers; the encoder may adjust it to
161 ignored (read-only).
169 adjusted size of ``CAPTURE`` buffers.
173 ``OUTPUT`` format, selection rectangles, etc. (read-only).
177 Changing the ``CAPTURE`` format may change the currently set ``OUTPUT``
196 the ``CAPTURE`` queue.
234 ``CAPTURE`` queue to the same value.
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
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
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.
290 a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``.
292 ``parm.capture``
293 set all fields except ``parm.capture.timeperframe`` to 0.
295 ``parm.capture.timeperframe``
301 ``parm.capture.timeperframe``
306 Changing the ``CAPTURE`` frame interval sets the framerate for the
308 ``CAPTURE`` queue, that depends on how fast the encoder is and how
358 ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``.
375 7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via
385 ``CAPTURE``.
428 8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via
434 If the client stops the ``CAPTURE`` queue during the encode process and then
454 The content of encoded ``CAPTURE`` buffers depends on the active coded pixel
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
460 dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw
464 The client must not assume any direct relationship between ``CAPTURE`` and
469 ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder
474 ``CAPTURE`` later into encode process, and/or after processing further
478 * buffers may become available on the ``CAPTURE`` queue without additional
480 ``OUTPUT`` buffers queued in the past whose encoding results are only
484 after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the
489 To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they
492 ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer
496 one ``CAPTURE`` buffer, the following cases are defined:
498 * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same
499 ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers,
502 ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers):
503 ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps.
509 ``CAPTURE`` buffers will have corresponding flag bits set in their
517 * the ``CAPTURE`` buffer (if any) that contains the results of the failed encode
526 If a ``CAPTURE`` buffer is too small then it is just returned with the
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
554 (:ref:`media-request-api`) should be considered, if supported by the encoder.
560 related ``CAPTURE`` buffers are given to the client, the client must follow the
580 The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE``
591 * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the
602 Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer
603 marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from
619 dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped
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
639 issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE``
642 will fail with -EBUSY error code if attempted.
648 immediately and the encoder returns an empty ``CAPTURE`` buffer with the
651 * In case of no buffer in the ``CAPTURE`` queue at the time the drain
652 sequence completes, the next time the client queues a ``CAPTURE`` buffer
656 * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the
658 ``CAPTURE`` buffers are implicitly returned to the client.
662 next ``CAPTURE`` buffer will be returned empty with the
683 1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes
686 2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This
687 will return all currently queued ``CAPTURE`` buffers to the client, without
690 3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and
692 ``CAPTURE`` buffers from now on will contain a standalone stream that can be
706 1. Setting the format on the ``CAPTURE`` queue may change the set of formats
711 2. Enumerating formats on the ``OUTPUT`` queue always returns only formats
712 supported for the current ``CAPTURE`` format.
715 formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT``
716 format that is not supported for the currently selected ``CAPTURE`` format
720 4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of
723 5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues,
724 the client must not change the format on the ``CAPTURE`` queue. Drivers will
725 return the -EBUSY error code for any such format change attempt.
728 ``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the