1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
10 .. _VIDIOC_DECODER_CMD:
12 ************************************************
13 ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
14 ************************************************
19 VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
25 .. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp )
26 :name: VIDIOC_DECODER_CMD
29 .. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp )
30 :name: VIDIOC_TRY_DECODER_CMD
37 File descriptor returned by :ref:`open() <func-open>`.
40 pointer to struct :c:type:`v4l2_decoder_cmd`.
46 These ioctls control an audio/video (usually MPEG-) decoder.
47 ``VIDIOC_DECODER_CMD`` sends a command to the decoder,
48 ``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
49 executing it. To send a command applications must initialize all fields
50 of a struct :c:type:`v4l2_decoder_cmd` and call
51 ``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
54 The ``cmd`` field must contain the command code. Some commands use the
55 ``flags`` field for additional information.
57 A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
58 call sends an implicit START command to the decoder if it has not been
61 A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
62 call of a streaming file descriptor sends an implicit immediate STOP
63 command to the decoder, and all buffered data is discarded.
65 These ioctls are optional, not all drivers may support them. They were
66 introduced in Linux 3.3.
69 .. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}|
71 .. c:type:: v4l2_decoder_cmd
73 .. cssclass:: longtable
75 .. flat-table:: struct v4l2_decoder_cmd
78 :widths: 11 24 12 16 106
84 - The decoder command, see :ref:`decoder-cmds`.
89 - Flags to go with the command. If no flags are defined for this
90 command, drivers and applications must set this field to zero.
100 - Structure containing additional data for the
101 ``V4L2_DEC_CMD_START`` command.
106 - Playback speed and direction. The playback speed is defined as
107 ``speed``/1000 of the normal speed. So 1000 is normal playback.
108 Negative numbers denote reverse playback, so -1000 does reverse
109 playback at normal speed. Speeds -1, 0 and 1 have special
110 meanings: speed 0 is shorthand for 1000 (normal playback). A speed
111 of 1 steps just one frame forward, a speed of -1 steps just one
117 - Format restrictions. This field is set by the driver, not the
118 application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
119 there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
120 the decoder operates on full GOPs (*Group Of Pictures*). This is
121 usually the case for reverse playback: the decoder needs full
122 GOPs, which it can then play in reverse order. So to implement
123 reverse playback the application must feed the decoder the last
124 GOP in the video file, then the GOP before that, etc. etc.
129 - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
135 - Stop playback at this ``pts`` or immediately if the playback is
136 already past that timestamp. Leave to 0 if you want to stop after
137 the last frame was decoded.
147 - Reserved for future extensions. Drivers and applications must set
152 .. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}|
156 .. flat-table:: Decoder Commands
161 * - ``V4L2_DEC_CMD_START``
163 - Start the decoder. When the decoder is already running or paused,
164 this command will just change the playback speed. That means that
165 calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
166 *not* resume the decoder. You have to explicitly call
167 ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
168 ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
169 muted when playing back at a non-standard speed.
170 * - ``V4L2_DEC_CMD_STOP``
172 - Stop the decoder. When the decoder is already stopped, this
173 command does nothing. This command has two flags: if
174 ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
175 the picture to black after it stopped decoding. Otherwise the last
176 image will repeat. mem2mem decoders will stop producing new frames
177 altogether. They will send a ``V4L2_EVENT_EOS`` event when the
178 last frame has been decoded and all frames are ready to be
179 dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on
180 the last buffer of the capture queue to indicate there will be no
181 new buffers produced to dequeue. This buffer may be empty,
182 indicated by the driver setting the ``bytesused`` field to 0. Once
183 the ``V4L2_BUF_FLAG_LAST`` flag was set, the
184 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
185 but return an ``EPIPE`` error code. If
186 ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
187 immediately (ignoring the ``pts`` value), otherwise it will keep
188 decoding until timestamp >= pts or until the last of the pending
189 data from its internal buffers was decoded.
190 * - ``V4L2_DEC_CMD_PAUSE``
192 - Pause the decoder. When the decoder has not been started yet, the
193 driver will return an ``EPERM`` error code. When the decoder is
194 already paused, this command does nothing. This command has one
195 flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
196 decoder output to black when paused.
197 * - ``V4L2_DEC_CMD_RESUME``
199 - Resume decoding after a PAUSE command. When the decoder has not
200 been started yet, the driver will return an ``EPERM`` error code. When
201 the decoder is already running, this command does nothing. No
202 flags are defined for this command.
208 On success 0 is returned, on error -1 and the ``errno`` variable is set
209 appropriately. The generic error codes are described at the
210 :ref:`Generic Error Codes <gen-errors>` chapter.
213 The ``cmd`` field is invalid.
216 The application sent a PAUSE or RESUME command when the decoder was