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.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
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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.