^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_ENCODER_CMD:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) .. c:macro:: VIDIOC_ENCODER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) .. c:macro:: VIDIOC_TRY_ENCODER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Pointer to struct :c:type:`v4l2_encoder_cmd`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) These ioctls control an audio/video (usually MPEG-) encoder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) executing it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) To send a command applications must initialize all fields of a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) :c:type:`v4l2_encoder_cmd` and call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) this structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) The ``cmd`` field must contain the command code. Some commands use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) ``flags`` field for additional information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) After a STOP command, :c:func:`read()` calls will read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) the remaining data buffered by the driver. When the buffer is empty,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) :c:func:`read()` will return zero and the next :c:func:`read()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) call will restart the encoder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) call sends an implicit START command to the encoder if it has not been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) started yet. Applies to both queues of mem2mem encoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) call of a streaming file descriptor sends an implicit immediate STOP to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) the encoder, and all buffered data is discarded. Applies to both queues of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) mem2mem encoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) These ioctls are optional, not all drivers may support them. They were
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) encoders (as further documented in :ref:`encoder`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) .. c:type:: v4l2_encoder_cmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) .. flat-table:: struct v4l2_encoder_cmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) - ``cmd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) - The encoder command, see :ref:`encoder-cmds`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) - Flags to go with the command, see :ref:`encoder-flags`. If no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) flags are defined for this command, drivers and applications must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) set this field to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) - ``data``\ [8]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) - Reserved for future extensions. Drivers and applications must set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) the array to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) .. _encoder-cmds:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) .. flat-table:: Encoder Commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) * - ``V4L2_ENC_CMD_START``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) - Start the encoder. When the encoder is already running or paused,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) this command does nothing. No flags are defined for this command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) For a device implementing the :ref:`encoder`, once the drain sequence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) to completion before this command can be invoked. Any attempt to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) invoke the command while the drain sequence is in progress will trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) an ``EBUSY`` error code. See :ref:`encoder` for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) * - ``V4L2_ENC_CMD_STOP``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) is set, encoding will continue until the end of the current *Group
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Of Pictures*, otherwise encoding will stop immediately. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) encoder is already stopped, this command does nothing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) For a device implementing the :ref:`encoder`, the command will initiate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) the drain sequence as documented in :ref:`encoder`. No flags or other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) arguments are accepted in this case. Any attempt to invoke the command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) again before the sequence completes will trigger an ``EBUSY`` error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) * - ``V4L2_ENC_CMD_PAUSE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) - Pause the encoder. When the encoder has not been started yet, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) driver will return an ``EPERM`` error code. When the encoder is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) already paused, this command does nothing. No flags are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) for this command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) * - ``V4L2_ENC_CMD_RESUME``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) - Resume encoding after a PAUSE command. When the encoder has not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) been started yet, the driver will return an ``EPERM`` error code. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) the encoder is already running, this command does nothing. No
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) flags are defined for this command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) .. _encoder-flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) .. flat-table:: Encoder Command Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) - 0x0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) - Stop encoding at the end of the current *Group Of Pictures*,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) rather than immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Does not apply to :ref:`encoder`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) EBUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) A drain sequence of a device implementing the :ref:`encoder` is still in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) progress. It is not allowed to issue another encoder command until it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) The ``cmd`` field is invalid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) EPERM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) The application sent a PAUSE or RESUME command when the encoder was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) not running.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags