1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<refentry id="vidioc-encoder-cmd">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENCODER_CMD</refname>
<refname>VIDIOC_TRY_ENCODER_CMD</refname>
<refpurpose>Execute an encoder command</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>These ioctls control an audio/video (usually MPEG-) encoder.
<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the
encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
try a command without actually executing it.</para>
<para>To send a command applications must initialize all fields of a
&v4l2-encoder-cmd; and call
<constant>VIDIOC_ENCODER_CMD</constant> or
<constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this
structure.</para>
<para>The <structfield>cmd</structfield> field must contain the
command code. The <structfield>flags</structfield> field is currently
only used by the STOP command and contains one bit: If the
<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
encoding will continue until the end of the current <wordasword>Group
Of Pictures</wordasword>, otherwise it will stop immediately.</para>
<para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit
START command to the encoder if it has not been started yet. After a STOP command,
<function>read</function>() calls will read the remaining data
buffered by the driver. When the buffer is empty,
<function>read</function>() will return zero and the next
<function>read</function>() call will restart the encoder.</para>
<para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming
file descriptor sends an implicit immediate STOP to the encoder, and all buffered
data is discarded.</para>
<para>These ioctls are optional, not all drivers may support
them. They were introduced in Linux 2.6.21.</para>
<table pgwide="1" frame="none" id="v4l2-encoder-cmd">
<title>struct <structname>v4l2_encoder_cmd</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>cmd</structfield></entry>
<entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>flags</structfield></entry>
<entry>Flags to go with the command, see <xref
linkend="encoder-flags" />. If no flags are defined for
this command, drivers and applications must set this field to
zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>data</structfield>[8]</entry>
<entry>Reserved for future extensions. Drivers and
applications must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="encoder-cmds">
<title>Encoder Commands</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_ENC_CMD_START</constant></entry>
<entry>0</entry>
<entry>Start the encoder. When the encoder is already
running or paused, this command does nothing. No flags are defined for
this command.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_STOP</constant></entry>
<entry>1</entry>
<entry>Stop the encoder. When the
<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
encoding will continue until the end of the current <wordasword>Group
Of Pictures</wordasword>, otherwise encoding will stop immediately.
When the encoder is already stopped, this command does
nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event
when the last frame has been encoded and all frames are ready to be dequeued and
will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last
buffer of the capture queue to indicate there will be no new buffers produced to
dequeue. This buffer may be empty, indicated by the driver setting the
<structfield>bytesused</structfield> field to 0. Once the
<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the
<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore,
but return an &EPIPE;.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
<entry>2</entry>
<entry>Pause the encoder. When the encoder has not been
started yet, the driver will return an &EPERM;. When the encoder is
already paused, this command does nothing. No flags are defined for
this command.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_RESUME</constant></entry>
<entry>3</entry>
<entry>Resume encoding after a PAUSE command. When the
encoder has not been started yet, the driver will return an &EPERM;.
When the encoder is already running, this command does nothing. No
flags are defined for this command.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="encoder-flags">
<title>Encoder Command Flags</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry>
<entry>0x0001</entry>
<entry>Stop encoding at the end of the current <wordasword>Group Of
Pictures</wordasword>, rather than immediately.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <structfield>cmd</structfield> field is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>The application sent a PAUSE or RESUME command when
the encoder was not running.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
|
