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