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