About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.0.4. Page generated on 2011-10-03 22:07 EST.

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>
56	interface 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
61	encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
62	try 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
71	command code. The <structfield>flags</structfield> field is currently
72	only used by the STOP command and contains one bit: If the
73	<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
74	encoding will continue until the end of the current <wordasword>Group
75	Of Pictures</wordasword>, otherwise it will stop immediately.</para>
76	
77	    <para>A <function>read</function>() call sends a START command to
78	the encoder if it has not been started yet. After a STOP command,
79	<function>read</function>() calls will read the remaining data
80	buffered 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
85	to the encoder, and all buffered data is discarded.</para>
86	
87	    <para>These ioctls are optional, not all drivers may support
88	them. 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
105	this command, drivers and applications must set this field to
106	zero.</entry>
107		  </row>
108		  <row>
109		    <entry>__u32</entry>
110		    <entry><structfield>data</structfield>[8]</entry>
111		    <entry>Reserved for future extensions. Drivers and
112	applications 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
127	running or paused, this command does nothing. No flags are defined for
128	this 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,
135	encoding will continue until the end of the current <wordasword>Group
136	Of Pictures</wordasword>, otherwise encoding will stop immediately.
137	When the encoder is already stopped, this command does
138	nothing.</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
144	started yet, the driver will return an &EPERM;. When the encoder is
145	already paused, this command does nothing. No flags are defined for
146	this 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
152	encoder has not been started yet, the driver will return an &EPERM;.
153	When the encoder is already running, this command does nothing. No
154	flags 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
169	Pictures</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
191	the encoder was not running.</para>
192		</listitem>
193	      </varlistentry>
194	    </variablelist>
195	  </refsect1>
196	</refentry>
197	
198	<!--
199	Local Variables:
200	mode: sgml
201	sgml-parent-document: "v4l2.sgml"
202	indent-tabs-mode: nil
203	End:
204	-->
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.