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************************************************
  7ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
  8************************************************
  9
 10Name
 11====
 12
 13VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
 14
 15Synopsis
 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
 26Arguments
 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
 35Description
 36===========
 37
 38These 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
 41executing it.
 42
 43To 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
 46this structure.
 47
 48The ``cmd`` field must contain the command code. Some commands use the
 49``flags`` field for additional information.
 50
 51After a STOP command, :c:func:`read()` calls will read
 52the remaining data buffered by the driver. When the buffer is empty,
 53:c:func:`read()` will return zero and the next :c:func:`read()`
 54call will restart the encoder.
 55
 56A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
 57call sends an implicit START command to the encoder if it has not been
 58started yet. Applies to both queues of mem2mem encoders.
 59
 60A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
 61call of a streaming file descriptor sends an implicit immediate STOP to
 62the encoder, and all buffered data is discarded. Applies to both queues of
 63mem2mem encoders.
 64
 65These ioctls are optional, not all drivers may support them. They were
 66introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
 67encoders (as further documented in :ref:`encoder`).
 68
 69.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
 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.5cm}|
 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.5cm}|
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
152Return Value
153============
154
155On success 0 is returned, on error -1 and the ``errno`` variable is set
156appropriately. The generic error codes are described at the
157:ref:`Generic Error Codes <gen-errors>` chapter.
158
159EBUSY
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
164EINVAL
165    The ``cmd`` field is invalid.
166
167EPERM
168    The application sent a PAUSE or RESUME command when the encoder was
169    not running.