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_SUBDEV_ENUM_FRAME_SIZE:
11
12***********************************
13ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
14***********************************
15
16Name
17====
18
19VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp )
26    :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
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_subdev_frame_size_enum`.
37
38
39Description
40===========
41
42This ioctl allows applications to enumerate all frame sizes supported by
43a sub-device on the given pad for the given media bus format. Supported
44formats can be retrieved with the
45:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
46ioctl.
47
48To enumerate frame sizes applications initialize the ``pad``, ``which``
49, ``code`` and ``index`` fields of the struct
50:c:type:`v4l2_subdev_mbus_code_enum` and
51call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
52structure. Drivers fill the minimum and maximum frame sizes or return an
53EINVAL error code if one of the input parameters is invalid.
54
55Sub-devices that only support discrete frame sizes (such as most
56sensors) will return one or more frame sizes with identical minimum and
57maximum values.
58
59Not all possible sizes in given [minimum, maximum] ranges need to be
60supported. For instance, a scaler that uses a fixed-point scaling ratio
61might not be able to produce every frame size between the minimum and
62maximum values. Applications must use the
63:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
64sub-device for an exact supported frame size.
65
66Available frame sizes may depend on the current 'try' formats at other
67pads of the sub-device, as well as on the current active links and the
68current values of V4L2 controls. See
69:ref:`VIDIOC_SUBDEV_G_FMT` for more
70information about try formats.
71
72
73.. c:type:: v4l2_subdev_frame_size_enum
74
75.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
76
77.. flat-table:: struct v4l2_subdev_frame_size_enum
78    :header-rows:  0
79    :stub-columns: 0
80    :widths:       1 1 2
81
82    * - __u32
83      - ``index``
84      - Number of the format in the enumeration, set by the application.
85    * - __u32
86      - ``pad``
87      - Pad number as reported by the media controller API.
88    * - __u32
89      - ``code``
90      - The media bus format code, as defined in
91	:ref:`v4l2-mbus-format`.
92    * - __u32
93      - ``min_width``
94      - Minimum frame width, in pixels.
95    * - __u32
96      - ``max_width``
97      - Maximum frame width, in pixels.
98    * - __u32
99      - ``min_height``
100      - Minimum frame height, in pixels.
101    * - __u32
102      - ``max_height``
103      - Maximum frame height, in pixels.
104    * - __u32
105      - ``which``
106      - Frame sizes to be enumerated, from enum
107	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
108    * - __u32
109      - ``reserved``\ [8]
110      - Reserved for future extensions. Applications and drivers must set
111	the array to zero.
112
113
114Return Value
115============
116
117On success 0 is returned, on error -1 and the ``errno`` variable is set
118appropriately. The generic error codes are described at the
119:ref:`Generic Error Codes <gen-errors>` chapter.
120
121EINVAL
122    The struct
123    :c:type:`v4l2_subdev_frame_size_enum`
124    ``pad`` references a non-existing pad, the ``code`` is invalid for
125    the given pad or the ``index`` field is out of bounds.
126