summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml
blob: 79ce42b7c60cf87b363fa5bc02ad1281358b83d8 (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
153
154
<refentry id="vidioc-subdev-enum-frame-size">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refname>
    <refpurpose>Enumerate media bus frame sizes</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_size_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_SIZE</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 allows applications to enumerate all frame sizes
    supported by a sub-device on the given pad for the given media bus format.
    Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE;
    ioctl.</para>

    <para>To enumerate frame sizes applications initialize the
    <structfield>pad</structfield>, <structfield>code</structfield> and
    <structfield>index</structfield> fields of the
    &v4l2-subdev-mbus-code-enum; and call the
    <constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant> ioctl with a pointer to
    the structure. Drivers fill the minimum and maximum frame sizes or return
    an &EINVAL; if one of the input parameters is invalid.</para>

    <para>Sub-devices that only support discrete frame sizes (such as most
    sensors) will return one or more frame sizes with identical minimum and
    maximum values.</para>

    <para>Not all possible sizes in given [minimum, maximum] ranges need to be
    supported. For instance, a scaler that uses a fixed-point scaling ratio
    might not be able to produce every frame size between the minimum and
    maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to
    try the sub-device for an exact supported frame size.</para>

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

    <table pgwide="1" frame="none" id="v4l2-subdev-frame-size-enum">
      <title>struct <structname>v4l2_subdev_frame_size_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>min_width</structfield></entry>
	    <entry>Minimum frame width, in pixels.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>max_width</structfield></entry>
	    <entry>Maximum frame width, in pixels.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>min_height</structfield></entry>
	    <entry>Minimum frame height, in pixels.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>max_height</structfield></entry>
	    <entry>Maximum frame height, in pixels.</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-size-enum; <structfield>pad</structfield>
	  references a non-existing pad, the <structfield>code</structfield> is
	  invalid for the given pad or the <structfield>index</structfield>
	  field is out of bounds.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>