doc/spec/r8724.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>ioctl VIDIOC_ENUM_FRAMEINTERVALS</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_ENUM_FRAMESIZES"
HREF="r8494.htm"><LINK
REL="NEXT"
TITLE="ioctl VIDIOC_ENUMINPUT"
HREF="r8936.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="r8494.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r8936.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="VIDIOC-ENUM-FRAMEINTERVALS"
></A
>ioctl VIDIOC_ENUM_FRAMEINTERVALS</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8728"
></A
><H2
>Name</H2
>VIDIOC_ENUM_FRAMEINTERVALS&nbsp;--&nbsp;Enumerate frame intervals</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8731"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN8732"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_frmivalenum *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8742"
></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_ENUM_FRAMEINTERVALS</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>argp</CODE
></DT
><DD
><P
>Pointer to a struct&nbsp;<A
HREF="r8724.htm#V4L2-FRMIVALENUM"
>v4l2_frmivalenum</A
> structure that
contains a pixel format and size and receives a frame interval.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8763"
></A
><H2
>Description</H2
><P
>This ioctl allows applications to enumerate all frame
intervals that the device supports for the given pixel format and
frame size.</P
><P
>The supported pixel formats and frame sizes can be obtained
by using the <A
HREF="r8367.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FMT</CODE
></A
> and <A
HREF="r8494.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUM_FRAMESIZES</CODE
></A
>
functions.</P
><P
>The return value and the content of the
<CODE
CLASS="STRUCTFIELD"
>v4l2_frmivalenum.type</CODE
> field depend on the
type of frame intervals the device supports. Here are the semantics of
the function for the different cases:</P
><P
></P
><UL
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="EMPHASIS"
>Discrete:</B
></SPAN
> The function
returns success if the given index value (zero-based) is valid. The
application should increase the index by one for each call until
<CODE
CLASS="CONSTANT"
>EINVAL</CODE
> is returned. The `v4l2_frmivalenum.type`
field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the
union only the `discrete` member is valid.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="EMPHASIS"
>Step-wise:</B
></SPAN
> The function
returns success if the given index value is zero and
<CODE
CLASS="CONSTANT"
>EINVAL</CODE
> for any other index value. The
<CODE
CLASS="STRUCTFIELD"
>v4l2_frmivalenum.type</CODE
> field is set to
<CODE
CLASS="CONSTANT"
>V4L2_FRMIVAL_TYPE_STEPWISE</CODE
> by the driver. Of the
union only the <CODE
CLASS="STRUCTFIELD"
>stepwise</CODE
> member is
valid.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="EMPHASIS"
>Continuous:</B
></SPAN
> This is a
special case of the step-wise type above. The function returns success
if the given index value is zero and <CODE
CLASS="CONSTANT"
>EINVAL</CODE
> for
any other index value. The
<CODE
CLASS="STRUCTFIELD"
>v4l2_frmivalenum.type</CODE
> field is set to
<CODE
CLASS="CONSTANT"
>V4L2_FRMIVAL_TYPE_CONTINUOUS</CODE
> by the driver. Of
the union only the <CODE
CLASS="STRUCTFIELD"
>stepwise</CODE
> member is valid
and the <CODE
CLASS="STRUCTFIELD"
>step</CODE
> value is set to 1.</P
></LI
></UL
><P
>When the application calls the function with index zero, it
must check the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field to determine the
type of frame interval enumeration the device supports. Only for the
<CODE
CLASS="CONSTANT"
>V4L2_FRMIVAL_TYPE_DISCRETE</CODE
> type does it make
sense to increase the index value to receive more frame
intervals.</P
><P
>Note that the order in which the frame intervals are
returned has no special meaning. In particular does it not say
anything about potential default frame intervals.</P
><P
>Applications can assume that the enumeration data does not
change without any interaction from the application itself. This means
that the enumeration data is consistent if the application does not
perform any other ioctl calls while it runs the frame interval
enumeration.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8798"
></A
><H2
>Notes</H2
><P
></P
><UL
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="EMPHASIS"
>Frame intervals and frame
rates:</B
></SPAN
> The V4L2 API uses frame intervals instead of frame
rates. Given the frame interval the frame rate can be computed as
follows:<PRE
CLASS="SCREEN"
>frame_rate = 1 / frame_interval</PRE
></P
></LI
></UL
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8805"
></A
><H2
>Structs</H2
><P
>In the structs below, <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>IN</I
></SPAN
> denotes a
value that has to be filled in by the application,
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>OUT</I
></SPAN
> denotes values that the driver fills in. The
application should zero out all members except for the
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>IN</I
></SPAN
> fields.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FRMIVAL-STEPWISE"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_frmival_stepwise</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
>struct&nbsp;<A
HREF="r9288.htm#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>min</CODE
></TD
><TD
>Minimum frame interval [s].</TD
></TR
><TR
><TD
>struct&nbsp;<A
HREF="r9288.htm#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>max</CODE
></TD
><TD
>Maximum frame interval [s].</TD
></TR
><TR
><TD
>struct&nbsp;<A
HREF="r9288.htm#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>step</CODE
></TD
><TD
>Frame interval step size [s].</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FRMIVALENUM"
></A
><P
><B
>Table 2. struct <CODE
CLASS="STRUCTNAME"
>v4l2_frmivalenum</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="25%"
TITLE="C3"><COL
WIDTH="25%"
TITLE="C4"><TBODY
VALIGN="TOP"
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>index</CODE
></TD
><TD
>&nbsp;</TD
><TD
>IN: Index of the given frame interval in the
enumeration.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>pixel_format</CODE
></TD
><TD
>&nbsp;</TD
><TD
>IN: Pixel format for which the frame intervals are
enumerated.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>width</CODE
></TD
><TD
>&nbsp;</TD
><TD
>IN: Frame width for which the frame intervals are
enumerated.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>height</CODE
></TD
><TD
>&nbsp;</TD
><TD
>IN: Frame height for which the frame intervals are
enumerated.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>&nbsp;</TD
><TD
>OUT: Frame interval type the device supports.</TD
></TR
><TR
><TD
>union</TD
><TD
>&nbsp;</TD
><TD
>&nbsp;</TD
><TD
>OUT: Frame interval with the given index.</TD
></TR
><TR
><TD
>&nbsp;</TD
><TD
>struct&nbsp;<A
HREF="r9288.htm#V4L2-FRACT"
>v4l2_fract</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>discrete</CODE
></TD
><TD
>Frame interval [s].</TD
></TR
><TR
><TD
>&nbsp;</TD
><TD
>struct&nbsp;<A
HREF="r8724.htm#V4L2-FRMIVAL-STEPWISE"
>v4l2_frmival_stepwise</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>stepwise</CODE
></TD
><TD
>&nbsp;</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved[2]</CODE
></TD
><TD
>&nbsp;</TD
><TD
>Reserved space for future use.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8902"
></A
><H2
>Enums</H2
><DIV
CLASS="TABLE"
><A
NAME="V4L2-FRMIVALTYPES"
></A
><P
><B
>Table 3. enum <CODE
CLASS="STRUCTNAME"
>v4l2_frmivaltypes</CODE
></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_FRMIVAL_TYPE_DISCRETE</CODE
></TD
><TD
>1</TD
><TD
>Discrete frame interval.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FRMIVAL_TYPE_CONTINUOUS</CODE
></TD
><TD
>2</TD
><TD
>Continuous frame interval.</TD
></TR
><TR
><TD
><CODE
CLASS="CONSTANT"
>V4L2_FRMIVAL_TYPE_STEPWISE</CODE
></TD
><TD
>3</TD
><TD
>Step-wise defined frame interval.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8928"
></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
>See the description section above for a list of return
values that <CODE
CLASS="VARNAME"
>errno</CODE
> can have.</P
></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="r8494.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="r8936.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>ioctl VIDIOC_ENUM_FRAMESIZES</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_ENUMINPUT</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>