← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-ti-omap4/precise

« back to all changes in this revision

Viewing changes to Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml

  • Committer: Bazaar Package Importer
  • Author(s): Paolo Pisati
  • Date: 2011-06-29 15:23:51 UTC
  • mfrom: (26.1.1 natty-proposed)
  • Revision ID: james.westby@ubuntu.com-20110629152351-xs96tm303d95rpbk
Tags: 3.0.0-1200.2
* Rebased against 3.0.0-6.7
* BSP from TI based on 3.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml
 
1
<refentry id="vidioc-subdev-enum-frame-interval">
 
2
  <refmeta>
 
3
    <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
 
4
    &manvol;
 
5
  </refmeta>
 
6
 
 
7
  <refnamediv>
 
8
    <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
 
9
    <refpurpose>Enumerate frame intervals</refpurpose>
 
10
  </refnamediv>
 
11
 
 
12
  <refsynopsisdiv>
 
13
    <funcsynopsis>
 
14
      <funcprototype>
 
15
        <funcdef>int <function>ioctl</function></funcdef>
 
16
        <paramdef>int <parameter>fd</parameter></paramdef>
 
17
        <paramdef>int <parameter>request</parameter></paramdef>
 
18
        <paramdef>struct v4l2_subdev_frame_interval_enum *
 
19
        <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_SUBDEV_ENUM_FRAME_INTERVAL</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
    <note>
 
53
      <title>Experimental</title>
 
54
      <para>This is an <link linkend="experimental">experimental</link>
 
55
      interface and may change in the future.</para>
 
56
    </note>
 
57
 
 
58
    <para>This ioctl lets applications enumerate available frame intervals on a
 
59
    given sub-device pad. Frame intervals only makes sense for sub-devices that
 
60
    can control the frame period on their own. This includes, for instance,
 
61
    image sensors and TV tuners.</para>
 
62
 
 
63
    <para>For the common use case of image sensors, the frame intervals
 
64
    available on the sub-device output pad depend on the frame format and size
 
65
    on the same pad. Applications must thus specify the desired format and size
 
66
    when enumerating frame intervals.</para>
 
67
 
 
68
    <para>To enumerate frame intervals applications initialize the
 
69
    <structfield>index</structfield>, <structfield>pad</structfield>,
 
70
    <structfield>code</structfield>, <structfield>width</structfield> and
 
71
    <structfield>height</structfield> fields of
 
72
    &v4l2-subdev-frame-interval-enum; and call the
 
73
    <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
 
74
    to this structure. Drivers fill the rest of the structure or return
 
75
    an &EINVAL; if one of the input fields is invalid. All frame intervals are
 
76
    enumerable by beginning at index zero and incrementing by one until
 
77
    <errorcode>EINVAL</errorcode> is returned.</para>
 
78
 
 
79
    <para>Available frame intervals may depend on the current 'try' formats
 
80
    at other pads of the sub-device, as well as on the current active links. See
 
81
    &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
 
82
 
 
83
    <para>Sub-devices that support the frame interval enumeration ioctl should
 
84
    implemented it on a single pad only. Its behaviour when supported on
 
85
    multiple pads of the same sub-device is not defined.</para>
 
86
 
 
87
    <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
 
88
      <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
 
89
      <tgroup cols="3">
 
90
        &cs-str;
 
91
        <tbody valign="top">
 
92
          <row>
 
93
            <entry>__u32</entry>
 
94
            <entry><structfield>index</structfield></entry>
 
95
            <entry>Number of the format in the enumeration, set by the
 
96
            application.</entry>
 
97
          </row>
 
98
          <row>
 
99
            <entry>__u32</entry>
 
100
            <entry><structfield>pad</structfield></entry>
 
101
            <entry>Pad number as reported by the media controller API.</entry>
 
102
          </row>
 
103
          <row>
 
104
            <entry>__u32</entry>
 
105
            <entry><structfield>code</structfield></entry>
 
106
            <entry>The media bus format code, as defined in
 
107
            <xref linkend="v4l2-mbus-format" />.</entry>
 
108
          </row>
 
109
          <row>
 
110
            <entry>__u32</entry>
 
111
            <entry><structfield>width</structfield></entry>
 
112
            <entry>Frame width, in pixels.</entry>
 
113
          </row>
 
114
          <row>
 
115
            <entry>__u32</entry>
 
116
            <entry><structfield>height</structfield></entry>
 
117
            <entry>Frame height, in pixels.</entry>
 
118
          </row>
 
119
          <row>
 
120
            <entry>&v4l2-fract;</entry>
 
121
            <entry><structfield>interval</structfield></entry>
 
122
            <entry>Period, in seconds, between consecutive video frames.</entry>
 
123
          </row>
 
124
          <row>
 
125
            <entry>__u32</entry>
 
126
            <entry><structfield>reserved</structfield>[9]</entry>
 
127
            <entry>Reserved for future extensions. Applications and drivers must
 
128
            set the array to zero.</entry>
 
129
          </row>
 
130
        </tbody>
 
131
      </tgroup>
 
132
    </table>
 
133
  </refsect1>
 
134
 
 
135
  <refsect1>
 
136
    &return-value;
 
137
 
 
138
    <variablelist>
 
139
      <varlistentry>
 
140
        <term><errorcode>EINVAL</errorcode></term>
 
141
        <listitem>
 
142
          <para>The &v4l2-subdev-frame-interval-enum;
 
143
          <structfield>pad</structfield> references a non-existing pad, one of
 
144
          the <structfield>code</structfield>, <structfield>width</structfield>
 
145
          or <structfield>height</structfield> fields are invalid for the given
 
146
          pad or the <structfield>index</structfield> field is out of bounds.
 
147
          </para>
 
148
        </listitem>
 
149
      </varlistentry>
 
150
    </variablelist>
 
151
  </refsect1>
 
152
</refentry>