Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml

   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
  54 encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
  55 try 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
  64 command code. The <structfield>flags</structfield> field is currently
  65 only used by the STOP command and contains one bit: If the
  66 <constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
  67 encoding will continue until the end of the current <wordasword>Group
  68 Of Pictures</wordasword>, otherwise it will stop immediately.</para>
  69
  70     <para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit
  71 START 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
  73 buffered 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
  78 file descriptor sends an implicit immediate STOP to the encoder, and all buffered
  79 data is discarded.</para>
  80
  81     <para>These ioctls are optional, not all drivers may support
  82 them. 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
  99 this command, drivers and applications must set this field to
 100 zero.</entry>
 101           </row>
 102           <row>
 103             <entry>__u32</entry>
 104             <entry><structfield>data</structfield>[8]</entry>
 105             <entry>Reserved for future extensions. Drivers and
 106 applications 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
 121 running or paused, this command does nothing. No flags are defined for
 122 this 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,
 129 encoding will continue until the end of the current <wordasword>Group
 130 Of Pictures</wordasword>, otherwise encoding will stop immediately.
 131 When the encoder is already stopped, this command does
 132 nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event
 133 when the last frame has been decoded and all frames are ready to be dequeued and
 134 will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last
 135 buffer of the capture queue to indicate there will be no new buffers produced to
 136 dequeue. 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,
 140 but 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
 146 started yet, the driver will return an &EPERM;. When the encoder is
 147 already paused, this command does nothing. No flags are defined for
 148 this 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
 154 encoder has not been started yet, the driver will return an &EPERM;.
 155 When the encoder is already running, this command does nothing. No
 156 flags 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
 171 Pictures</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
 192 the encoder was not running.</para>
 193         </listitem>
 194       </varlistentry>
 195     </variablelist>
 196   </refsect1>
 197 </refentry>