doc/spec/r8087.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Function Reference"
HREF="r7624.htm"><LINK
REL="PREVIOUS"
TITLE="ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER"
HREF="r7900.htm"><LINK
REL="NEXT"
TITLE="ioctl VIDIOC_ENUMAUDIO"
HREF="r8242.htm"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="r7900.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r8242.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="VIDIOC-ENCODER-CMD"
></A
>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8091"
></A
><H2
>Name</H2
>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD&nbsp;--&nbsp;Execute an encoder command</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8095"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8096"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_encoder_cmd *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8106"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="PARAMETER"
>fd</CODE
></DT
><DD
><P
>File descriptor returned by <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>request</CODE
></DT
><DD
><P
>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>argp</CODE
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8126"
></A
><H2
>Description</H2
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Experimental: </B
>This is an <A
HREF="x16453.htm"
>experimental</A
>
interface and may change in the future.</P
></BLOCKQUOTE
></DIV
><P
>These ioctls control an audio/video (usually MPEG-) encoder.
<CODE
CLASS="CONSTANT"
>VIDIOC_ENCODER_CMD</CODE
> sends a command to the
encoder, <CODE
CLASS="CONSTANT"
>VIDIOC_TRY_ENCODER_CMD</CODE
> can be used to
try a command without actually executing it.</P
><P
>To send a command applications must initialize all fields of a
    struct&nbsp;<A
HREF="r8087.htm#V4L2-ENCODER-CMD"
>v4l2_encoder_cmd</A
> and call
    <CODE
CLASS="CONSTANT"
>VIDIOC_ENCODER_CMD</CODE
> or
    <CODE
CLASS="CONSTANT"
>VIDIOC_TRY_ENCODER_CMD</CODE
> with a pointer to this
    structure.</P
><P
>The <CODE
CLASS="STRUCTFIELD"
>cmd</CODE
> field must contain the
command code. The <CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field is currently
only used by the STOP command and contains one bit: If the
<CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_STOP_AT_GOP_END</CODE
> flag is set,
encoding will continue until the end of the current <I
CLASS="WORDASWORD"
>Group
Of Pictures</I
>, otherwise it will stop immediately.</P
><P
>A <CODE
CLASS="FUNCTION"
>read</CODE
>() call sends a START command to
the encoder if it has not been started yet. After a STOP command,
<CODE
CLASS="FUNCTION"
>read</CODE
>() calls will read the remaining data
buffered by the driver. When the buffer is empty,
<CODE
CLASS="FUNCTION"
>read</CODE
>() will return zero and the next
<CODE
CLASS="FUNCTION"
>read</CODE
>() call will restart the encoder.</P
><P
>A <CODE
CLASS="FUNCTION"
>close</CODE
>() call sends an immediate STOP
to the encoder, and all buffered data is discarded.</P
><P
>These ioctls are optional, not all drivers may support
them. They were introduced in Linux 2.6.21.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-ENCODER-CMD"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_encoder_cmd</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>cmd</CODE
></TD
><TD
>The encoder command, see <A
HREF="r8087.htm#ENCODER-CMDS"
>Table 2</A
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>flags</CODE
></TD
><TD
>Flags to go with the command, see <A
HREF="r8087.htm#ENCODER-FLAGS"
>Table 3</A
>. If no flags are defined for
this command, drivers and applications must set this field to
zero.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>data</CODE
>[8]</TD
><TD
>Reserved for future extensions. Drivers and
applications must set the array to zero.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="ENCODER-CMDS"
></A
><P
><B
>Table 2. Encoder Commands</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_START</CODE
></TD
><TD
>0</TD
><TD
>Start the encoder. When the encoder is already
running or paused, this command does nothing. No flags are defined for
this command.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_STOP</CODE
></TD
><TD
>1</TD
><TD
>Stop the encoder. When the
<CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_STOP_AT_GOP_END</CODE
> flag is set,
encoding will continue until the end of the current <I
CLASS="WORDASWORD"
>Group
Of Pictures</I
>, otherwise encoding will stop immediately.
When the encoder is already stopped, this command does
nothing.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_PAUSE</CODE
></TD
><TD
>2</TD
><TD
>Pause the encoder. When the encoder has not been
started yet, the driver will return an <SPAN
CLASS="ERRORCODE"
>EPERM</SPAN
> error code. When the encoder is
already paused, this command does nothing. No flags are defined for
this command.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_RESUME</CODE
></TD
><TD
>3</TD
><TD
>Resume encoding after a PAUSE command. When the
encoder has not been started yet, the driver will return an <SPAN
CLASS="ERRORCODE"
>EPERM</SPAN
> error code.
When the encoder is already running, this command does nothing. No
flags are defined for this command.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="ENCODER-FLAGS"
></A
><P
><B
>Table 3. Encoder Command Flags</B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="38%"
TITLE="C1"><COL
WIDTH="12%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_ENC_CMD_STOP_AT_GOP_END</CODE
></TD
><TD
>0x0001</TD
><TD
>Stop encoding at the end of the current <I
CLASS="WORDASWORD"
>Group Of
Pictures</I
>, rather than immediately.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8224"
></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:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The driver does not support this ioctl, or the
<CODE
CLASS="STRUCTFIELD"
>cmd</CODE
> field is invalid.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EPERM</SPAN
></DT
><DD
><P
>The application sent a PAUSE or RESUME command when
the encoder was not running.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="r7900.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="r8242.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="r7624.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>ioctl VIDIOC_ENUMAUDIO</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>