Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst

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