Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENCODER_CMD: |
5377d91f MH |
4 | |
5 | ************************************************ | |
6 | ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD | |
7 | ************************************************ | |
8 | ||
9 | *man VIDIOC_ENCODER_CMD(2)* | |
10 | ||
11 | VIDIOC_TRY_ENCODER_CMD | |
12 | Execute an encoder command | |
13 | ||
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp ) |
5377d91f MH |
19 | |
20 | Arguments | |
21 | ========= | |
22 | ||
23 | ``fd`` | |
24 | File descriptor returned by :ref:`open() <func-open>`. | |
25 | ||
26 | ``request`` | |
27 | VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD | |
28 | ||
29 | ``argp`` | |
30 | ||
31 | ||
32 | Description | |
33 | =========== | |
34 | ||
35 | These ioctls control an audio/video (usually MPEG-) encoder. | |
36 | ``VIDIOC_ENCODER_CMD`` sends a command to the encoder, | |
37 | ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually | |
38 | executing it. | |
39 | ||
40 | To send a command applications must initialize all fields of a struct | |
41 | :ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call | |
42 | ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to | |
43 | this structure. | |
44 | ||
45 | The ``cmd`` field must contain the command code. The ``flags`` field is | |
46 | currently only used by the STOP command and contains one bit: If the | |
47 | ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue | |
48 | until the end of the current *Group Of Pictures*, otherwise it will stop | |
49 | immediately. | |
50 | ||
7347081e | 51 | A :c:func:`read()`() or :ref:`VIDIOC_STREAMON` |
5377d91f MH |
52 | call sends an implicit START command to the encoder if it has not been |
53 | started yet. After a STOP command, :c:func:`read()`() calls will read | |
54 | the remaining data buffered by the driver. When the buffer is empty, | |
55 | :c:func:`read()`() will return zero and the next :c:func:`read()`() | |
56 | call will restart the encoder. | |
57 | ||
af4a4d0d | 58 | A :c:func:`close()`() or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` |
5377d91f MH |
59 | call of a streaming file descriptor sends an implicit immediate STOP to |
60 | the encoder, and all buffered data is discarded. | |
61 | ||
62 | These ioctls are optional, not all drivers may support them. They were | |
63 | introduced in Linux 2.6.21. | |
64 | ||
65 | ||
66 | .. _v4l2-encoder-cmd: | |
67 | ||
68 | .. flat-table:: struct v4l2_encoder_cmd | |
69 | :header-rows: 0 | |
70 | :stub-columns: 0 | |
71 | :widths: 1 1 2 | |
72 | ||
73 | ||
74 | - .. row 1 | |
75 | ||
76 | - __u32 | |
77 | ||
78 | - ``cmd`` | |
79 | ||
80 | - The encoder command, see :ref:`encoder-cmds`. | |
81 | ||
82 | - .. row 2 | |
83 | ||
84 | - __u32 | |
85 | ||
86 | - ``flags`` | |
87 | ||
88 | - Flags to go with the command, see :ref:`encoder-flags`. If no | |
89 | flags are defined for this command, drivers and applications must | |
90 | set this field to zero. | |
91 | ||
92 | - .. row 3 | |
93 | ||
94 | - __u32 | |
95 | ||
96 | - ``data``\ [8] | |
97 | ||
98 | - Reserved for future extensions. Drivers and applications must set | |
99 | the array to zero. | |
100 | ||
101 | ||
102 | ||
103 | .. _encoder-cmds: | |
104 | ||
105 | .. flat-table:: Encoder Commands | |
106 | :header-rows: 0 | |
107 | :stub-columns: 0 | |
108 | :widths: 3 1 4 | |
109 | ||
110 | ||
111 | - .. row 1 | |
112 | ||
113 | - ``V4L2_ENC_CMD_START`` | |
114 | ||
115 | - 0 | |
116 | ||
117 | - Start the encoder. When the encoder is already running or paused, | |
118 | this command does nothing. No flags are defined for this command. | |
119 | ||
120 | - .. row 2 | |
121 | ||
122 | - ``V4L2_ENC_CMD_STOP`` | |
123 | ||
124 | - 1 | |
125 | ||
126 | - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag | |
127 | is set, encoding will continue until the end of the current *Group | |
128 | Of Pictures*, otherwise encoding will stop immediately. When the | |
129 | encoder is already stopped, this command does nothing. mem2mem | |
130 | encoders will send a ``V4L2_EVENT_EOS`` event when the last frame | |
131 | has been encoded and all frames are ready to be dequeued and will | |
132 | set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of | |
133 | the capture queue to indicate there will be no new buffers | |
134 | produced to dequeue. This buffer may be empty, indicated by the | |
135 | driver setting the ``bytesused`` field to 0. Once the | |
136 | ``V4L2_BUF_FLAG_LAST`` flag was set, the | |
af4a4d0d | 137 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, |
5377d91f MH |
138 | but return an EPIPE error code. |
139 | ||
140 | - .. row 3 | |
141 | ||
142 | - ``V4L2_ENC_CMD_PAUSE`` | |
143 | ||
144 | - 2 | |
145 | ||
146 | - Pause the encoder. When the encoder has not been started yet, the | |
147 | driver will return an EPERM error code. When the encoder is | |
148 | already paused, this command does nothing. No flags are defined | |
149 | for this command. | |
150 | ||
151 | - .. row 4 | |
152 | ||
153 | - ``V4L2_ENC_CMD_RESUME`` | |
154 | ||
155 | - 3 | |
156 | ||
157 | - Resume encoding after a PAUSE command. When the encoder has not | |
158 | been started yet, the driver will return an EPERM error code. When | |
159 | the encoder is already running, this command does nothing. No | |
160 | flags are defined for this command. | |
161 | ||
162 | ||
163 | ||
164 | .. _encoder-flags: | |
165 | ||
166 | .. flat-table:: Encoder Command Flags | |
167 | :header-rows: 0 | |
168 | :stub-columns: 0 | |
169 | :widths: 3 1 4 | |
170 | ||
171 | ||
172 | - .. row 1 | |
173 | ||
174 | - ``V4L2_ENC_CMD_STOP_AT_GOP_END`` | |
175 | ||
176 | - 0x0001 | |
177 | ||
178 | - Stop encoding at the end of the current *Group Of Pictures*, | |
179 | rather than immediately. | |
180 | ||
181 | ||
182 | ||
183 | Return Value | |
184 | ============ | |
185 | ||
186 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
187 | appropriately. The generic error codes are described at the | |
188 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
189 | ||
190 | EINVAL | |
191 | The ``cmd`` field is invalid. | |
192 | ||
193 | EPERM | |
194 | The application sent a PAUSE or RESUME command when the encoder was | |
195 | not running. | |
196 | ||
197 | ||
198 | .. ------------------------------------------------------------------------------ | |
199 | .. This file was automatically converted from DocBook-XML with the dbxml | |
200 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
201 | .. from the linux kernel, refer to: | |
202 | .. | |
203 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
204 | .. ------------------------------------------------------------------------------ |