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.
170