summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml
blob: 2f8f4f0a023596c5b75d0ec22e8ce3d1be9ae350 (plain)
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
<refentry id="vidioc-subdev-enum-frame-interval">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
    <refpurpose>Enumerate frame intervals</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_subdev_frame_interval_enum *
	<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_SUBDEV_ENUM_FRAME_INTERVAL</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <title>Experimental</title>
      <para>This is an <link linkend="experimental">experimental</link>
      interface and may change in the future.</para>
    </note>

    <para>This ioctl lets applications enumerate available frame intervals on a
    given sub-device pad. Frame intervals only makes sense for sub-devices that
    can control the frame period on their own. This includes, for instance,
    image sensors and TV tuners.</para>

    <para>For the common use case of image sensors, the frame intervals
    available on the sub-device output pad depend on the frame format and size
    on the same pad. Applications must thus specify the desired format and size
    when enumerating frame intervals.</para>

    <para>To enumerate frame intervals applications initialize the
    <structfield>index</structfield>, <structfield>pad</structfield>,
    <structfield>code</structfield>, <structfield>width</structfield> and
    <structfield>height</structfield> fields of
    &v4l2-subdev-frame-interval-enum; and call the
    <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
    to this structure. Drivers fill the rest of the structure or return
    an &EINVAL; if one of the input fields is invalid. All frame intervals are
    enumerable by beginning at index zero and incrementing by one until
    <errorcode>EINVAL</errorcode> is returned.</para>

    <para>Available frame intervals may depend on the current 'try' formats
    at other pads of the sub-device, as well as on the current active links. See
    &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>

    <para>Sub-devices that support the frame interval enumeration ioctl should
    implemented it on a single pad only. Its behaviour when supported on
    multiple pads of the same sub-device is not defined.</para>

    <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
      <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
      <tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>index</structfield></entry>
	    <entry>Number of the format in the enumeration, set by the
	    application.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>pad</structfield></entry>
	    <entry>Pad number as reported by the media controller API.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>code</structfield></entry>
	    <entry>The media bus format code, as defined in
	    <xref linkend="v4l2-mbus-format" />.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>width</structfield></entry>
	    <entry>Frame width, in pixels.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>height</structfield></entry>
	    <entry>Frame height, in pixels.</entry>
	  </row>
	  <row>
	    <entry>&v4l2-fract;</entry>
	    <entry><structfield>interval</structfield></entry>
	    <entry>Period, in seconds, between consecutive video frames.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>reserved</structfield>[9]</entry>
	    <entry>Reserved for future extensions. Applications and drivers must
	    set the array to zero.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The &v4l2-subdev-frame-interval-enum;
	  <structfield>pad</structfield> references a non-existing pad, one of
	  the <structfield>code</structfield>, <structfield>width</structfield>
	  or <structfield>height</structfield> fields are invalid for the given
	  pad or the <structfield>index</structfield> field is out of bounds.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>