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