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