Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_DECODER_CMD: |
5377d91f MH |
4 | |
5 | ************************************************ | |
6 | ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD | |
7 | ************************************************ | |
8 | ||
9 | *man VIDIOC_DECODER_CMD(2)* | |
10 | ||
11 | VIDIOC_TRY_DECODER_CMD | |
12 | Execute an decoder command | |
13 | ||
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_decoder_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_DECODER_CMD, VIDIOC_TRY_DECODER_CMD | |
28 | ||
29 | ``argp`` | |
30 | ||
31 | ||
32 | Description | |
33 | =========== | |
34 | ||
35 | These ioctls control an audio/video (usually MPEG-) decoder. | |
36 | ``VIDIOC_DECODER_CMD`` sends a command to the decoder, | |
37 | ``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually | |
38 | executing it. To send a command applications must initialize all fields | |
39 | of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call | |
40 | ``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to | |
41 | this structure. | |
42 | ||
43 | The ``cmd`` field must contain the command code. Some commands use the | |
44 | ``flags`` field for additional information. | |
45 | ||
760c7010 | 46 | A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` |
5377d91f MH |
47 | call sends an implicit START command to the decoder if it has not been |
48 | started yet. | |
49 | ||
760c7010 | 50 | A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` |
5377d91f MH |
51 | call of a streaming file descriptor sends an implicit immediate STOP |
52 | command to the decoder, and all buffered data is discarded. | |
53 | ||
54 | These ioctls are optional, not all drivers may support them. They were | |
55 | introduced in Linux 3.3. | |
56 | ||
57 | ||
58 | .. _v4l2-decoder-cmd: | |
59 | ||
60 | .. flat-table:: struct v4l2_decoder_cmd | |
61 | :header-rows: 0 | |
62 | :stub-columns: 0 | |
63 | :widths: 1 1 2 1 1 | |
64 | ||
65 | ||
66 | - .. row 1 | |
67 | ||
68 | - __u32 | |
69 | ||
70 | - ``cmd`` | |
71 | ||
0579e6e3 MCC |
72 | - |
73 | - | |
5377d91f MH |
74 | - The decoder command, see :ref:`decoder-cmds`. |
75 | ||
76 | - .. row 2 | |
77 | ||
78 | - __u32 | |
79 | ||
80 | - ``flags`` | |
81 | ||
0579e6e3 MCC |
82 | - |
83 | - | |
5377d91f | 84 | - Flags to go with the command. If no flags are defined for this |
0579e6e3 | 85 | command, drivers and applications must set this field to zero. |
5377d91f MH |
86 | |
87 | - .. row 3 | |
88 | ||
89 | - union | |
90 | ||
91 | - (anonymous) | |
92 | ||
0579e6e3 MCC |
93 | - |
94 | - | |
95 | - | |
5377d91f MH |
96 | |
97 | - .. row 4 | |
98 | ||
0579e6e3 | 99 | - |
5377d91f MH |
100 | - struct |
101 | ||
102 | - ``start`` | |
103 | ||
0579e6e3 | 104 | - |
5377d91f | 105 | - Structure containing additional data for the |
0579e6e3 | 106 | ``V4L2_DEC_CMD_START`` command. |
5377d91f MH |
107 | |
108 | - .. row 5 | |
109 | ||
0579e6e3 MCC |
110 | - |
111 | - | |
5377d91f MH |
112 | - __s32 |
113 | ||
114 | - ``speed`` | |
115 | ||
116 | - Playback speed and direction. The playback speed is defined as | |
0579e6e3 MCC |
117 | ``speed``/1000 of the normal speed. So 1000 is normal playback. |
118 | Negative numbers denote reverse playback, so -1000 does reverse | |
119 | playback at normal speed. Speeds -1, 0 and 1 have special | |
120 | meanings: speed 0 is shorthand for 1000 (normal playback). A speed | |
121 | of 1 steps just one frame forward, a speed of -1 steps just one | |
122 | frame back. | |
5377d91f MH |
123 | |
124 | - .. row 6 | |
125 | ||
0579e6e3 MCC |
126 | - |
127 | - | |
5377d91f MH |
128 | - __u32 |
129 | ||
130 | - ``format`` | |
131 | ||
132 | - Format restrictions. This field is set by the driver, not the | |
0579e6e3 MCC |
133 | application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if |
134 | there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if | |
135 | the decoder operates on full GOPs (*Group Of Pictures*). This is | |
136 | usually the case for reverse playback: the decoder needs full | |
137 | GOPs, which it can then play in reverse order. So to implement | |
138 | reverse playback the application must feed the decoder the last | |
139 | GOP in the video file, then the GOP before that, etc. etc. | |
5377d91f MH |
140 | |
141 | - .. row 7 | |
142 | ||
0579e6e3 | 143 | - |
5377d91f MH |
144 | - struct |
145 | ||
146 | - ``stop`` | |
147 | ||
0579e6e3 | 148 | - |
5377d91f | 149 | - Structure containing additional data for the ``V4L2_DEC_CMD_STOP`` |
0579e6e3 | 150 | command. |
5377d91f MH |
151 | |
152 | - .. row 8 | |
153 | ||
0579e6e3 MCC |
154 | - |
155 | - | |
5377d91f MH |
156 | - __u64 |
157 | ||
158 | - ``pts`` | |
159 | ||
160 | - Stop playback at this ``pts`` or immediately if the playback is | |
0579e6e3 MCC |
161 | already past that timestamp. Leave to 0 if you want to stop after |
162 | the last frame was decoded. | |
5377d91f MH |
163 | |
164 | - .. row 9 | |
165 | ||
0579e6e3 | 166 | - |
5377d91f MH |
167 | - struct |
168 | ||
169 | - ``raw`` | |
170 | ||
0579e6e3 MCC |
171 | - |
172 | - | |
5377d91f MH |
173 | |
174 | - .. row 10 | |
175 | ||
0579e6e3 MCC |
176 | - |
177 | - | |
5377d91f MH |
178 | - __u32 |
179 | ||
180 | - ``data``\ [16] | |
181 | ||
182 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 183 | the array to zero. |
5377d91f MH |
184 | |
185 | ||
186 | ||
187 | .. _decoder-cmds: | |
188 | ||
189 | .. flat-table:: Decoder Commands | |
190 | :header-rows: 0 | |
191 | :stub-columns: 0 | |
192 | :widths: 3 1 4 | |
193 | ||
194 | ||
195 | - .. row 1 | |
196 | ||
197 | - ``V4L2_DEC_CMD_START`` | |
198 | ||
199 | - 0 | |
200 | ||
201 | - Start the decoder. When the decoder is already running or paused, | |
0579e6e3 MCC |
202 | this command will just change the playback speed. That means that |
203 | calling ``V4L2_DEC_CMD_START`` when the decoder was paused will | |
204 | *not* resume the decoder. You have to explicitly call | |
205 | ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: | |
206 | ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be | |
207 | muted when playing back at a non-standard speed. | |
5377d91f MH |
208 | |
209 | - .. row 2 | |
210 | ||
211 | - ``V4L2_DEC_CMD_STOP`` | |
212 | ||
213 | - 1 | |
214 | ||
215 | - Stop the decoder. When the decoder is already stopped, this | |
0579e6e3 MCC |
216 | command does nothing. This command has two flags: if |
217 | ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set | |
218 | the picture to black after it stopped decoding. Otherwise the last | |
219 | image will repeat. mem2mem decoders will stop producing new frames | |
220 | altogether. They will send a ``V4L2_EVENT_EOS`` event when the | |
221 | last frame has been decoded and all frames are ready to be | |
222 | dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on | |
223 | the last buffer of the capture queue to indicate there will be no | |
224 | new buffers produced to dequeue. This buffer may be empty, | |
225 | indicated by the driver setting the ``bytesused`` field to 0. Once | |
226 | the ``V4L2_BUF_FLAG_LAST`` flag was set, the | |
227 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, | |
228 | but return an ``EPIPE`` error code. If | |
229 | ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops | |
230 | immediately (ignoring the ``pts`` value), otherwise it will keep | |
231 | decoding until timestamp >= pts or until the last of the pending | |
232 | data from its internal buffers was decoded. | |
5377d91f MH |
233 | |
234 | - .. row 3 | |
235 | ||
236 | - ``V4L2_DEC_CMD_PAUSE`` | |
237 | ||
238 | - 2 | |
239 | ||
240 | - Pause the decoder. When the decoder has not been started yet, the | |
0579e6e3 MCC |
241 | driver will return an ``EPERM`` error code. When the decoder is |
242 | already paused, this command does nothing. This command has one | |
243 | flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the | |
244 | decoder output to black when paused. | |
5377d91f MH |
245 | |
246 | - .. row 4 | |
247 | ||
248 | - ``V4L2_DEC_CMD_RESUME`` | |
249 | ||
250 | - 3 | |
251 | ||
252 | - Resume decoding after a PAUSE command. When the decoder has not | |
0579e6e3 MCC |
253 | been started yet, the driver will return an ``EPERM`` error code. When |
254 | the decoder is already running, this command does nothing. No | |
255 | flags are defined for this command. | |
5377d91f MH |
256 | |
257 | ||
258 | ||
259 | Return Value | |
260 | ============ | |
261 | ||
262 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
263 | appropriately. The generic error codes are described at the | |
264 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
265 | ||
266 | EINVAL | |
267 | The ``cmd`` field is invalid. | |
268 | ||
269 | EPERM | |
270 | The application sent a PAUSE or RESUME command when the decoder was | |
271 | not running. |