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.</entry>
133	  </row>
134	  <row>
135	    <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
136	    <entry>2</entry>
137	    <entry>Pause the encoder. When the encoder has not been
138started yet, the driver will return an &EPERM;. When the encoder is
139already paused, this command does nothing. No flags are defined for
140this command.</entry>
141	  </row>
142	  <row>
143	    <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry>
144	    <entry>3</entry>
145	    <entry>Resume encoding after a PAUSE command. When the
146encoder has not been started yet, the driver will return an &EPERM;.
147When the encoder is already running, this command does nothing. No
148flags are defined for this command.</entry>
149	  </row>
150	</tbody>
151      </tgroup>
152    </table>
153
154    <table pgwide="1" frame="none" id="encoder-flags">
155      <title>Encoder Command Flags</title>
156      <tgroup cols="3">
157	&cs-def;
158	<tbody valign="top">
159	  <row>
160	    <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry>
161	    <entry>0x0001</entry>
162	    <entry>Stop encoding at the end of the current <wordasword>Group Of
163Pictures</wordasword>, rather than immediately.</entry>
164	  </row>
165       </tbody>
166      </tgroup>
167    </table>
168  </refsect1>
169
170  <refsect1>
171    &return-value;
172
173    <variablelist>
174      <varlistentry>
175	<term><errorcode>EINVAL</errorcode></term>
176	<listitem>
177	  <para>The <structfield>cmd</structfield> field is invalid.</para>
178	</listitem>
179      </varlistentry>
180      <varlistentry>
181	<term><errorcode>EPERM</errorcode></term>
182	<listitem>
183	  <para>The application sent a PAUSE or RESUME command when
184the encoder was not running.</para>
185	</listitem>
186      </varlistentry>
187    </variablelist>
188  </refsect1>
189</refentry>
190