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