0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENCODER_CMD:
0005
0006 ************************************************
0007 ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
0008 ************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENCODER_CMD
0019
0020 ``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
0021
0022 .. c:macro:: VIDIOC_TRY_ENCODER_CMD
0023
0024 ``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_encoder_cmd`.
0034
0035 Description
0036 ===========
0037
0038 These ioctls control an audio/video (usually MPEG-) encoder.
0039 ``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
0040 ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
0041 executing it.
0042
0043 To send a command applications must initialize all fields of a struct
0044 :c:type:`v4l2_encoder_cmd` and call
0045 ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
0046 this structure.
0047
0048 The ``cmd`` field must contain the command code. Some commands use the
0049 ``flags`` field for additional information.
0050
0051 After a STOP command, :c:func:`read()` calls will read
0052 the remaining data buffered by the driver. When the buffer is empty,
0053 :c:func:`read()` will return zero and the next :c:func:`read()`
0054 call will restart the encoder.
0055
0056 A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
0057 call sends an implicit START command to the encoder if it has not been
0058 started yet. Applies to both queues of mem2mem encoders.
0059
0060 A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
0061 call of a streaming file descriptor sends an implicit immediate STOP to
0062 the encoder, and all buffered data is discarded. Applies to both queues of
0063 mem2mem encoders.
0064
0065 These ioctls are optional, not all drivers may support them. They were
0066 introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
0067 encoders (as further documented in :ref:`encoder`).
0068
0069 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0070
0071 .. c:type:: v4l2_encoder_cmd
0072
0073 .. flat-table:: struct v4l2_encoder_cmd
0074 :header-rows: 0
0075 :stub-columns: 0
0076 :widths: 1 1 2
0077
0078 * - __u32
0079 - ``cmd``
0080 - The encoder command, see :ref:`encoder-cmds`.
0081 * - __u32
0082 - ``flags``
0083 - Flags to go with the command, see :ref:`encoder-flags`. If no
0084 flags are defined for this command, drivers and applications must
0085 set this field to zero.
0086 * - __u32
0087 - ``data``\ [8]
0088 - Reserved for future extensions. Drivers and applications must set
0089 the array to zero.
0090
0091
0092 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0093
0094 .. _encoder-cmds:
0095
0096 .. flat-table:: Encoder Commands
0097 :header-rows: 0
0098 :stub-columns: 0
0099 :widths: 3 1 4
0100
0101 * - ``V4L2_ENC_CMD_START``
0102 - 0
0103 - Start the encoder. When the encoder is already running or paused,
0104 this command does nothing. No flags are defined for this command.
0105
0106 For a device implementing the :ref:`encoder`, once the drain sequence
0107 is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven
0108 to completion before this command can be invoked. Any attempt to
0109 invoke the command while the drain sequence is in progress will trigger
0110 an ``EBUSY`` error code. See :ref:`encoder` for more details.
0111 * - ``V4L2_ENC_CMD_STOP``
0112 - 1
0113 - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
0114 is set, encoding will continue until the end of the current *Group
0115 Of Pictures*, otherwise encoding will stop immediately. When the
0116 encoder is already stopped, this command does nothing.
0117
0118 For a device implementing the :ref:`encoder`, the command will initiate
0119 the drain sequence as documented in :ref:`encoder`. No flags or other
0120 arguments are accepted in this case. Any attempt to invoke the command
0121 again before the sequence completes will trigger an ``EBUSY`` error
0122 code.
0123 * - ``V4L2_ENC_CMD_PAUSE``
0124 - 2
0125 - Pause the encoder. When the encoder has not been started yet, the
0126 driver will return an ``EPERM`` error code. When the encoder is
0127 already paused, this command does nothing. No flags are defined
0128 for this command.
0129 * - ``V4L2_ENC_CMD_RESUME``
0130 - 3
0131 - Resume encoding after a PAUSE command. When the encoder has not
0132 been started yet, the driver will return an ``EPERM`` error code. When
0133 the encoder is already running, this command does nothing. No
0134 flags are defined for this command.
0135
0136 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0137
0138 .. _encoder-flags:
0139
0140 .. flat-table:: Encoder Command Flags
0141 :header-rows: 0
0142 :stub-columns: 0
0143 :widths: 3 1 4
0144
0145 * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
0146 - 0x0001
0147 - Stop encoding at the end of the current *Group Of Pictures*,
0148 rather than immediately.
0149
0150 Does not apply to :ref:`encoder`.
0151
0152 Return Value
0153 ============
0154
0155 On success 0 is returned, on error -1 and the ``errno`` variable is set
0156 appropriately. The generic error codes are described at the
0157 :ref:`Generic Error Codes <gen-errors>` chapter.
0158
0159 EBUSY
0160 A drain sequence of a device implementing the :ref:`encoder` is still in
0161 progress. It is not allowed to issue another encoder command until it
0162 completes.
0163
0164 EINVAL
0165 The ``cmd`` field is invalid.
0166
0167 EPERM
0168 The application sent a PAUSE or RESUME command when the encoder was
0169 not running.
