1<refentry id="vidioc-encoder-cmd"> 2 <refmeta> 3 <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>VIDIOC_ENCODER_CMD</refname> 9 <refname>VIDIOC_TRY_ENCODER_CMD</refname> 10 <refpurpose>Execute an encoder command</refpurpose> 11 </refnamediv> 12 13 <refsynopsisdiv> 14 <funcsynopsis> 15 <funcprototype> 16 <funcdef>int <function>ioctl</function></funcdef> 17 <paramdef>int <parameter>fd</parameter></paramdef> 18 <paramdef>int <parameter>request</parameter></paramdef> 19 <paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef> 20 </funcprototype> 21 </funcsynopsis> 22 </refsynopsisdiv> 23 24 <refsect1> 25 <title>Arguments</title> 26 27 <variablelist> 28 <varlistentry> 29 <term><parameter>fd</parameter></term> 30 <listitem> 31 <para>&fd;</para> 32 </listitem> 33 </varlistentry> 34 <varlistentry> 35 <term><parameter>request</parameter></term> 36 <listitem> 37 <para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>argp</parameter></term> 42 <listitem> 43 <para></para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 49 <refsect1> 50 <title>Description</title> 51 52 <para>These ioctls control an audio/video (usually MPEG-) encoder. 53<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the 54encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to 55try a command without actually executing it.</para> 56 57 <para>To send a command applications must initialize all fields of a 58 &v4l2-encoder-cmd; and call 59 <constant>VIDIOC_ENCODER_CMD</constant> or 60 <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this 61 structure.</para> 62 63 <para>The <structfield>cmd</structfield> field must contain the 64command code. The <structfield>flags</structfield> field is currently 65only used by the STOP command and contains one bit: If the 66<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, 67encoding will continue until the end of the current <wordasword>Group 68Of Pictures</wordasword>, otherwise it will stop immediately.</para> 69 70 <para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit 71START command to the encoder if it has not been started yet. After a STOP command, 72<function>read</function>() calls will read the remaining data 73buffered by the driver. When the buffer is empty, 74<function>read</function>() will return zero and the next 75<function>read</function>() call will restart the encoder.</para> 76 77 <para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming 78file descriptor sends an implicit immediate STOP to the encoder, and all buffered 79data is discarded.</para> 80 81 <para>These ioctls are optional, not all drivers may support 82them. They were introduced in Linux 2.6.21.</para> 83 84 <table pgwide="1" frame="none" id="v4l2-encoder-cmd"> 85 <title>struct <structname>v4l2_encoder_cmd</structname></title> 86 <tgroup cols="3"> 87 &cs-str; 88 <tbody valign="top"> 89 <row> 90 <entry>__u32</entry> 91 <entry><structfield>cmd</structfield></entry> 92 <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> 93 </row> 94 <row> 95 <entry>__u32</entry> 96 <entry><structfield>flags</structfield></entry> 97 <entry>Flags to go with the command, see <xref 98 linkend="encoder-flags" />. If no flags are defined for 99this command, drivers and applications must set this field to 100zero.</entry> 101 </row> 102 <row> 103 <entry>__u32</entry> 104 <entry><structfield>data</structfield>[8]</entry> 105 <entry>Reserved for future extensions. Drivers and 106applications must set the array to zero.</entry> 107 </row> 108 </tbody> 109 </tgroup> 110 </table> 111 112 <table pgwide="1" frame="none" id="encoder-cmds"> 113 <title>Encoder Commands</title> 114 <tgroup cols="3"> 115 &cs-def; 116 <tbody valign="top"> 117 <row> 118 <entry><constant>V4L2_ENC_CMD_START</constant></entry> 119 <entry>0</entry> 120 <entry>Start the encoder. When the encoder is already 121running or paused, this command does nothing. No flags are defined for 122this command.</entry> 123 </row> 124 <row> 125 <entry><constant>V4L2_ENC_CMD_STOP</constant></entry> 126 <entry>1</entry> 127 <entry>Stop the encoder. When the 128<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, 129encoding will continue until the end of the current <wordasword>Group 130Of Pictures</wordasword>, otherwise encoding will stop immediately. 131When the encoder is already stopped, this command does 132nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event 133when the last frame has been encoded and all frames are ready to be dequeued and 134will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last 135buffer of the capture queue to indicate there will be no new buffers produced to 136dequeue. This buffer may be empty, indicated by the driver setting the 137<structfield>bytesused</structfield> field to 0. Once the 138<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the 139<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore, 140but return an &EPIPE;.</entry> 141 </row> 142 <row> 143 <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry> 144 <entry>2</entry> 145 <entry>Pause the encoder. When the encoder has not been 146started yet, the driver will return an &EPERM;. When the encoder is 147already paused, this command does nothing. No flags are defined for 148this command.</entry> 149 </row> 150 <row> 151 <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry> 152 <entry>3</entry> 153 <entry>Resume encoding after a PAUSE command. When the 154encoder has not been started yet, the driver will return an &EPERM;. 155When the encoder is already running, this command does nothing. No 156flags are defined for this command.</entry> 157 </row> 158 </tbody> 159 </tgroup> 160 </table> 161 162 <table pgwide="1" frame="none" id="encoder-flags"> 163 <title>Encoder Command Flags</title> 164 <tgroup cols="3"> 165 &cs-def; 166 <tbody valign="top"> 167 <row> 168 <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry> 169 <entry>0x0001</entry> 170 <entry>Stop encoding at the end of the current <wordasword>Group Of 171Pictures</wordasword>, rather than immediately.</entry> 172 </row> 173 </tbody> 174 </tgroup> 175 </table> 176 </refsect1> 177 178 <refsect1> 179 &return-value; 180 181 <variablelist> 182 <varlistentry> 183 <term><errorcode>EINVAL</errorcode></term> 184 <listitem> 185 <para>The <structfield>cmd</structfield> field is invalid.</para> 186 </listitem> 187 </varlistentry> 188 <varlistentry> 189 <term><errorcode>EPERM</errorcode></term> 190 <listitem> 191 <para>The application sent a PAUSE or RESUME command when 192the encoder was not running.</para> 193 </listitem> 194 </varlistentry> 195 </variablelist> 196 </refsect1> 197</refentry> 198