GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / vidioc-enum-framesizes.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _VIDIOC_ENUM_FRAMESIZES:
4
5 ****************************
6 ioctl VIDIOC_ENUM_FRAMESIZES
7 ****************************
8
9 Name
10 ====
11
12 VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
13
14
15 Synopsis
16 ========
17
18 .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp )
19     :name: VIDIOC_ENUM_FRAMESIZES
20
21
22 Arguments
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
34 Description
35 ===========
36
37 This ioctl allows applications to enumerate all frame sizes (i. e. width
38 and height in pixels) that the device supports for the given pixel
39 format.
40
41 The supported pixel formats can be obtained by using the
42 :ref:`VIDIOC_ENUM_FMT` function.
43
44 The return value and the content of the ``v4l2_frmsizeenum.type`` field
45 depend on the type of frame sizes the device supports. Here are the
46 semantics 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
68 When the application calls the function with index zero, it must check
69 the ``type`` field to determine the type of frame size enumeration the
70 device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
71 it 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
79 Applications can assume that the enumeration data does not change
80 without any interaction from the application itself. This means that the
81 enumeration data is consistent if the application does not perform any
82 other ioctl calls while it runs the frame size enumeration.
83
84
85 Structs
86 =======
87
88 In the structs below, *IN* denotes a value that has to be filled in by
89 the application, *OUT* denotes values that the driver fills in. The
90 application 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
181 Enums
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
205 Return Value
206 ============
207
208 On success 0 is returned, on error -1 and the ``errno`` variable is set
209 appropriately. The generic error codes are described at the
210 :ref:`Generic Error Codes <gen-errors>` chapter.