About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 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	    <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 encoded 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>
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.