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 <note> 53 <title>Experimental</title> 54 55 <para>This is an <link linkend="experimental">experimental</link> 56interface and may change in the future.</para> 57 </note> 58 59 <para>These ioctls control an audio/video (usually MPEG-) encoder. 60<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the 61encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to 62try a command without actually executing it.</para> 63 64 <para>To send a command applications must initialize all fields of a 65 &v4l2-encoder-cmd; and call 66 <constant>VIDIOC_ENCODER_CMD</constant> or 67 <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this 68 structure.</para> 69 70 <para>The <structfield>cmd</structfield> field must contain the 71command code. The <structfield>flags</structfield> field is currently 72only used by the STOP command and contains one bit: If the 73<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, 74encoding will continue until the end of the current <wordasword>Group 75Of Pictures</wordasword>, otherwise it will stop immediately.</para> 76 77 <para>A <function>read</function>() call sends a START command to 78the encoder if it has not been started yet. After a STOP command, 79<function>read</function>() calls will read the remaining data 80buffered by the driver. When the buffer is empty, 81<function>read</function>() will return zero and the next 82<function>read</function>() call will restart the encoder.</para> 83 84 <para>A <function>close</function>() call sends an immediate STOP 85to the encoder, and all buffered data is discarded.</para> 86 87 <para>These ioctls are optional, not all drivers may support 88them. They were introduced in Linux 2.6.21.</para> 89 90 <table pgwide="1" frame="none" id="v4l2-encoder-cmd"> 91 <title>struct <structname>v4l2_encoder_cmd</structname></title> 92 <tgroup cols="3"> 93 &cs-str; 94 <tbody valign="top"> 95 <row> 96 <entry>__u32</entry> 97 <entry><structfield>cmd</structfield></entry> 98 <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> 99 </row> 100 <row> 101 <entry>__u32</entry> 102 <entry><structfield>flags</structfield></entry> 103 <entry>Flags to go with the command, see <xref 104 linkend="encoder-flags" />. If no flags are defined for 105this command, drivers and applications must set this field to 106zero.</entry> 107 </row> 108 <row> 109 <entry>__u32</entry> 110 <entry><structfield>data</structfield>[8]</entry> 111 <entry>Reserved for future extensions. Drivers and 112applications must set the array to zero.</entry> 113 </row> 114 </tbody> 115 </tgroup> 116 </table> 117 118 <table pgwide="1" frame="none" id="encoder-cmds"> 119 <title>Encoder Commands</title> 120 <tgroup cols="3"> 121 &cs-def; 122 <tbody valign="top"> 123 <row> 124 <entry><constant>V4L2_ENC_CMD_START</constant></entry> 125 <entry>0</entry> 126 <entry>Start the encoder. When the encoder is already 127running or paused, this command does nothing. No flags are defined for 128this command.</entry> 129 </row> 130 <row> 131 <entry><constant>V4L2_ENC_CMD_STOP</constant></entry> 132 <entry>1</entry> 133 <entry>Stop the encoder. When the 134<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, 135encoding will continue until the end of the current <wordasword>Group 136Of Pictures</wordasword>, otherwise encoding will stop immediately. 137When the encoder is already stopped, this command does 138nothing.</entry> 139 </row> 140 <row> 141 <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry> 142 <entry>2</entry> 143 <entry>Pause the encoder. When the encoder has not been 144started yet, the driver will return an &EPERM;. When the encoder is 145already paused, this command does nothing. No flags are defined for 146this command.</entry> 147 </row> 148 <row> 149 <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry> 150 <entry>3</entry> 151 <entry>Resume encoding after a PAUSE command. When the 152encoder has not been started yet, the driver will return an &EPERM;. 153When the encoder is already running, this command does nothing. No 154flags are defined for this command.</entry> 155 </row> 156 </tbody> 157 </tgroup> 158 </table> 159 160 <table pgwide="1" frame="none" id="encoder-flags"> 161 <title>Encoder Command Flags</title> 162 <tgroup cols="3"> 163 &cs-def; 164 <tbody valign="top"> 165 <row> 166 <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry> 167 <entry>0x0001</entry> 168 <entry>Stop encoding at the end of the current <wordasword>Group Of 169Pictures</wordasword>, rather than immediately.</entry> 170 </row> 171 </tbody> 172 </tgroup> 173 </table> 174 </refsect1> 175 176 <refsect1> 177 &return-value; 178 179 <variablelist> 180 <varlistentry> 181 <term><errorcode>EINVAL</errorcode></term> 182 <listitem> 183 <para>The driver does not support this ioctl, or the 184<structfield>cmd</structfield> field is invalid.</para> 185 </listitem> 186 </varlistentry> 187 <varlistentry> 188 <term><errorcode>EPERM</errorcode></term> 189 <listitem> 190 <para>The application sent a PAUSE or RESUME command when 191the encoder was not running.</para> 192 </listitem> 193 </varlistentry> 194 </variablelist> 195 </refsect1> 196</refentry> 197 198<!-- 199Local Variables: 200mode: sgml 201sgml-parent-document: "v4l2.sgml" 202indent-tabs-mode: nil 203End: 204--> 205