1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="user-func.html" title="Appendix A. Function Reference"><link rel="prev" href="vidioc-dv-timings-cap.html" title="ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP"><link rel="next" href="vidioc-enumaudio.html" title="ioctl VIDIOC_ENUMAUDIO"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vidioc-dv-timings-cap.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="vidioc-enumaudio.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="vidioc-encoder-cmd"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD — Execute an encoder command</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>struct v4l2_encoder_cmd *<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="id-1.4.11.11.4"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a>.</p></dd><dt><span class="term"><em class="parameter"><code>request</code></em></span></dt><dd><p>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</p></dd><dt><span class="term"><em class="parameter"><code>argp</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1"><a name="id-1.4.11.11.5"></a><h2>Description</h2><p>These ioctls control an audio/video (usually MPEG-) encoder.
2<code class="constant">VIDIOC_ENCODER_CMD</code> sends a command to the
3encoder, <code class="constant">VIDIOC_TRY_ENCODER_CMD</code> can be used to
4try a command without actually executing it.</p><p>To send a command applications must initialize all fields of a
5    struct <a class="link" href="vidioc-encoder-cmd.html#v4l2-encoder-cmd" title="Table A.24. struct v4l2_encoder_cmd">v4l2_encoder_cmd</a> and call
6    <code class="constant">VIDIOC_ENCODER_CMD</code> or
7    <code class="constant">VIDIOC_TRY_ENCODER_CMD</code> with a pointer to this
8    structure.</p><p>The <em class="structfield"><code>cmd</code></em> field must contain the
9command code. The <em class="structfield"><code>flags</code></em> field is currently
10only used by the STOP command and contains one bit: If the
11<code class="constant">V4L2_ENC_CMD_STOP_AT_GOP_END</code> flag is set,
12encoding will continue until the end of the current <em class="wordasword">Group
13Of Pictures</em>, otherwise it will stop immediately.</p><p>A <code class="function">read</code>() or <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> call sends an implicit
14START command to the encoder if it has not been started yet. After a STOP command,
15<code class="function">read</code>() calls will read the remaining data
16buffered by the driver. When the buffer is empty,
17<code class="function">read</code>() will return zero and the next
18<code class="function">read</code>() call will restart the encoder.</p><p>A <code class="function">close</code>() or <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> call of a streaming
19file descriptor sends an implicit immediate STOP to the encoder, and all buffered
20data is discarded.</p><p>These ioctls are optional, not all drivers may support
21them. They were introduced in Linux 2.6.21.</p><div class="table"><a name="v4l2-encoder-cmd"></a><p class="title"><b>Table A.24. struct <span class="structname">v4l2_encoder_cmd</span></b></p><div class="table-contents"><table summary="struct v4l2_encoder_cmd" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>cmd</code></em></td><td valign="top">The encoder command, see <a class="xref" href="vidioc-encoder-cmd.html#encoder-cmds" title="Table A.25. Encoder Commands">Table A.25, “Encoder Commands”</a>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top">Flags to go with the command, see <a class="xref" href="vidioc-encoder-cmd.html#encoder-flags" title="Table A.26. Encoder Command Flags">Table A.26, “Encoder Command Flags”</a>. If no flags are defined for
22this command, drivers and applications must set this field to
23zero.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>data</code></em>[8]</td><td valign="top">Reserved for future extensions. Drivers and
24applications must set the array to zero.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="encoder-cmds"></a><p class="title"><b>Table A.25. Encoder Commands</b></p><div class="table-contents"><table summary="Encoder Commands" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_ENC_CMD_START</code></td><td valign="top">0</td><td valign="top">Start the encoder. When the encoder is already
25running or paused, this command does nothing. No flags are defined for
26this command.</td></tr><tr><td valign="top"><code class="constant">V4L2_ENC_CMD_STOP</code></td><td valign="top">1</td><td valign="top">Stop the encoder. When the
27<code class="constant">V4L2_ENC_CMD_STOP_AT_GOP_END</code> flag is set,
28encoding will continue until the end of the current <em class="wordasword">Group
29Of Pictures</em>, otherwise encoding will stop immediately.
30When the encoder is already stopped, this command does
31nothing. mem2mem encoders will send a <code class="constant">V4L2_EVENT_EOS</code> event
32when the last frame has been encoded and all frames are ready to be dequeued and
33will set the <code class="constant">V4L2_BUF_FLAG_LAST</code> buffer flag on the last
34buffer of the capture queue to indicate there will be no new buffers produced to
35dequeue. This buffer may be empty, indicated by the driver setting the
36<em class="structfield"><code>bytesused</code></em> field to 0. Once the
37<code class="constant">V4L2_BUF_FLAG_LAST</code> flag was set, the
38<a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_DQBUF</a> ioctl will not block anymore,
39but return an <span class="errorcode">EPIPE</span> error code.</td></tr><tr><td valign="top"><code class="constant">V4L2_ENC_CMD_PAUSE</code></td><td valign="top">2</td><td valign="top">Pause the encoder. When the encoder has not been
40started yet, the driver will return an <span class="errorcode">EPERM</span> error code. When the encoder is
41already paused, this command does nothing. No flags are defined for
42this command.</td></tr><tr><td valign="top"><code class="constant">V4L2_ENC_CMD_RESUME</code></td><td valign="top">3</td><td valign="top">Resume encoding after a PAUSE command. When the
43encoder has not been started yet, the driver will return an <span class="errorcode">EPERM</span> error code.
44When the encoder is already running, this command does nothing. No
45flags are defined for this command.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="encoder-flags"></a><p class="title"><b>Table A.26. Encoder Command Flags</b></p><div class="table-contents"><table summary="Encoder Command Flags" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_ENC_CMD_STOP_AT_GOP_END</code></td><td valign="top">0x0001</td><td valign="top">Stop encoding at the end of the current <em class="wordasword">Group Of
46Pictures</em>, rather than immediately.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="id-1.4.11.11.6"></a><h2>Return Value</h2><p>On success <span class="returnvalue">0</span> is returned, on error <span class="returnvalue">-1</span> and the <code class="varname">errno</code> variable is set appropriately. The generic error codes are described at the <a class="link" href="gen_errors.html#gen-errors" title="Table 17.1. Generic error codes">Generic Error Codes</a> chapter.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">EINVAL</span></span></dt><dd><p>The <em class="structfield"><code>cmd</code></em> field is invalid.</p></dd><dt><span class="term"><span class="errorcode">EPERM</span></span></dt><dd><p>The application sent a PAUSE or RESUME command when
47the encoder was not running.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vidioc-dv-timings-cap.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-func.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vidioc-enumaudio.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_ENUMAUDIO</td></tr></table></div></body></html>
48