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