1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_ENUM_FRAMESIZES:
11
12****************************
13ioctl VIDIOC_ENUM_FRAMESIZES
14****************************
15
16Name
17====
18
19VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp )
26    :name: VIDIOC_ENUM_FRAMESIZES
27
28
29Arguments
30=========
31
32``fd``
33    File descriptor returned by :ref:`open() <func-open>`.
34
35``argp``
36    Pointer to struct :c:type:`v4l2_frmsizeenum`
37    that contains an index and pixel format and receives a frame width
38    and height.
39
40
41Description
42===========
43
44This ioctl allows applications to enumerate all frame sizes (i. e. width
45and height in pixels) that the device supports for the given pixel
46format.
47
48The supported pixel formats can be obtained by using the
49:ref:`VIDIOC_ENUM_FMT` function.
50
51The return value and the content of the ``v4l2_frmsizeenum.type`` field
52depend on the type of frame sizes the device supports. Here are the
53semantics of the function for the different cases:
54
55-  **Discrete:** The function returns success if the given index value
56   (zero-based) is valid. The application should increase the index by
57   one for each call until ``EINVAL`` is returned. The
58   ``v4l2_frmsizeenum.type`` field is set to
59   ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
60   ``discrete`` member is valid.
61
62-  **Step-wise:** The function returns success if the given index value
63   is zero and ``EINVAL`` for any other index value. The
64   ``v4l2_frmsizeenum.type`` field is set to
65   ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
66   ``stepwise`` member is valid.
67
68-  **Continuous:** This is a special case of the step-wise type above.
69   The function returns success if the given index value is zero and
70   ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
71   field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
72   the union only the ``stepwise`` member is valid and the
73   ``step_width`` and ``step_height`` values are set to 1.
74
75When the application calls the function with index zero, it must check
76the ``type`` field to determine the type of frame size enumeration the
77device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
78it make sense to increase the index value to receive more frame sizes.
79
80.. note::
81
82   The order in which the frame sizes are returned has no special
83   meaning. In particular does it not say anything about potential default
84   format sizes.
85
86Applications can assume that the enumeration data does not change
87without any interaction from the application itself. This means that the
88enumeration data is consistent if the application does not perform any
89other ioctl calls while it runs the frame size enumeration.
90
91
92Structs
93=======
94
95In the structs below, *IN* denotes a value that has to be filled in by
96the application, *OUT* denotes values that the driver fills in. The
97application should zero out all members except for the *IN* fields.
98
99
100.. c:type:: v4l2_frmsize_discrete
101
102.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
103
104.. flat-table:: struct v4l2_frmsize_discrete
105    :header-rows:  0
106    :stub-columns: 0
107    :widths:       1 1 2
108
109    * - __u32
110      - ``width``
111      - Width of the frame [pixel].
112    * - __u32
113      - ``height``
114      - Height of the frame [pixel].
115
116
117
118.. c:type:: v4l2_frmsize_stepwise
119
120.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
121
122.. flat-table:: struct v4l2_frmsize_stepwise
123    :header-rows:  0
124    :stub-columns: 0
125    :widths:       1 1 2
126
127    * - __u32
128      - ``min_width``
129      - Minimum frame width [pixel].
130    * - __u32
131      - ``max_width``
132      - Maximum frame width [pixel].
133    * - __u32
134      - ``step_width``
135      - Frame width step size [pixel].
136    * - __u32
137      - ``min_height``
138      - Minimum frame height [pixel].
139    * - __u32
140      - ``max_height``
141      - Maximum frame height [pixel].
142    * - __u32
143      - ``step_height``
144      - Frame height step size [pixel].
145
146
147
148.. c:type:: v4l2_frmsizeenum
149
150.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}|
151
152.. flat-table:: struct v4l2_frmsizeenum
153    :header-rows:  0
154    :stub-columns: 0
155
156    * - __u32
157      - ``index``
158      - IN: Index of the given frame size in the enumeration.
159    * - __u32
160      - ``pixel_format``
161      - IN: Pixel format for which the frame sizes are enumerated.
162    * - __u32
163      - ``type``
164      - OUT: Frame size type the device supports.
165    * - union {
166      - (anonymous)
167      - OUT: Frame size with the given index.
168    * - struct :c:type:`v4l2_frmsize_discrete`
169      - ``discrete``
170      -
171    * - struct :c:type:`v4l2_frmsize_stepwise`
172      - ``stepwise``
173      -
174    * - }
175      -
176      -
177    * - __u32
178      - ``reserved[2]``
179      - Reserved space for future use. Must be zeroed by drivers and
180	applications.
181
182
183
184Enums
185=====
186
187
188.. c:type:: v4l2_frmsizetypes
189
190.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
191
192.. flat-table:: enum v4l2_frmsizetypes
193    :header-rows:  0
194    :stub-columns: 0
195    :widths:       3 1 4
196
197    * - ``V4L2_FRMSIZE_TYPE_DISCRETE``
198      - 1
199      - Discrete frame size.
200    * - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
201      - 2
202      - Continuous frame size.
203    * - ``V4L2_FRMSIZE_TYPE_STEPWISE``
204      - 3
205      - Step-wise defined frame size.
206
207
208Return Value
209============
210
211On success 0 is returned, on error -1 and the ``errno`` variable is set
212appropriately. The generic error codes are described at the
213:ref:`Generic Error Codes <gen-errors>` chapter.
214