1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: 4 .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
5 5
6 *********************************** 6 ***********************************
7 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE 7 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
8 *********************************** 8 ***********************************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate medi 13 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE 18 .. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
19 19
20 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_S 20 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)``
21 21
22 Arguments 22 Arguments
23 ========= 23 =========
24 24
25 ``fd`` 25 ``fd``
26 File descriptor returned by :c:func:`open( 26 File descriptor returned by :c:func:`open()`.
27 27
28 ``argp`` 28 ``argp``
29 Pointer to struct :c:type:`v4l2_subdev_fra 29 Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`.
30 30
31 Description 31 Description
32 =========== 32 ===========
33 33
34 This ioctl allows applications to access the e 34 This ioctl allows applications to access the enumeration of frame sizes
35 supported by a sub-device on the specified pad 35 supported by a sub-device on the specified pad
36 for the specified media bus format. 36 for the specified media bus format.
37 Supported formats can be retrieved with the 37 Supported formats can be retrieved with the
38 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` 38 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
39 ioctl. 39 ioctl.
40 40
41 The enumerations are defined by the driver, an 41 The enumerations are defined by the driver, and indexed using the ``index`` field
42 of the struct :c:type:`v4l2_subdev_frame_size_ 42 of the struct :c:type:`v4l2_subdev_frame_size_enum`.
43 Each pair of ``pad`` and ``code`` correspond t 43 Each pair of ``pad`` and ``code`` correspond to a separate enumeration.
44 Each enumeration starts with the ``index`` of 44 Each enumeration starts with the ``index`` of 0, and
45 the lowest invalid index marks the end of the 45 the lowest invalid index marks the end of the enumeration.
46 46
47 Therefore, to enumerate frame sizes allowed on 47 Therefore, to enumerate frame sizes allowed on the specified pad
48 and using the specified mbus format, initializ 48 and using the specified mbus format, initialize the
49 ``pad``, ``which``, and ``code`` fields to des 49 ``pad``, ``which``, and ``code`` fields to desired values,
50 and set ``index`` to 0. 50 and set ``index`` to 0.
51 Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_S 51 Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
52 structure. 52 structure.
53 53
54 A successful call will return with minimum and 54 A successful call will return with minimum and maximum frame sizes filled in.
55 Repeat with increasing ``index`` until ``EINVA 55 Repeat with increasing ``index`` until ``EINVAL`` is received.
56 ``EINVAL`` means that either no more entries a 56 ``EINVAL`` means that either no more entries are available in the enumeration,
57 or that an input parameter was invalid. 57 or that an input parameter was invalid.
58 58
59 Sub-devices that only support discrete frame s 59 Sub-devices that only support discrete frame sizes (such as most
60 sensors) will return one or more frame sizes w 60 sensors) will return one or more frame sizes with identical minimum and
61 maximum values. 61 maximum values.
62 62
63 Not all possible sizes in given [minimum, maxi 63 Not all possible sizes in given [minimum, maximum] ranges need to be
64 supported. For instance, a scaler that uses a 64 supported. For instance, a scaler that uses a fixed-point scaling ratio
65 might not be able to produce every frame size 65 might not be able to produce every frame size between the minimum and
66 maximum values. Applications must use the 66 maximum values. Applications must use the
67 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT 67 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
68 sub-device for an exact supported frame size. 68 sub-device for an exact supported frame size.
69 69
70 Available frame sizes may depend on the curren 70 Available frame sizes may depend on the current 'try' formats at other
71 pads of the sub-device, as well as on the curr 71 pads of the sub-device, as well as on the current active links and the
72 current values of V4L2 controls. See 72 current values of V4L2 controls. See
73 :ref:`VIDIOC_SUBDEV_G_FMT` for more 73 :ref:`VIDIOC_SUBDEV_G_FMT` for more
74 information about try formats. 74 information about try formats.
75 75
76 .. c:type:: v4l2_subdev_frame_size_enum 76 .. c:type:: v4l2_subdev_frame_size_enum
77 77
78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm 78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
79 79
80 .. flat-table:: struct v4l2_subdev_frame_size_ 80 .. flat-table:: struct v4l2_subdev_frame_size_enum
81 :header-rows: 0 81 :header-rows: 0
82 :stub-columns: 0 82 :stub-columns: 0
83 :widths: 1 1 2 83 :widths: 1 1 2
84 84
85 * - __u32 85 * - __u32
86 - ``index`` 86 - ``index``
87 - Index of the frame size in the enumera 87 - Index of the frame size in the enumeration belonging to the given pad
88 and format. Filled in by the applicati 88 and format. Filled in by the application.
89 * - __u32 89 * - __u32
90 - ``pad`` 90 - ``pad``
91 - Pad number as reported by the media co 91 - Pad number as reported by the media controller API.
92 Filled in by the application. 92 Filled in by the application.
93 * - __u32 93 * - __u32
94 - ``code`` 94 - ``code``
95 - The media bus format code, as defined 95 - The media bus format code, as defined in
96 :ref:`v4l2-mbus-format`. Filled in by 96 :ref:`v4l2-mbus-format`. Filled in by the application.
97 * - __u32 97 * - __u32
98 - ``min_width`` 98 - ``min_width``
99 - Minimum frame width, in pixels. Filled 99 - Minimum frame width, in pixels. Filled in by the driver.
100 * - __u32 100 * - __u32
101 - ``max_width`` 101 - ``max_width``
102 - Maximum frame width, in pixels. Filled 102 - Maximum frame width, in pixels. Filled in by the driver.
103 * - __u32 103 * - __u32
104 - ``min_height`` 104 - ``min_height``
105 - Minimum frame height, in pixels. Fille 105 - Minimum frame height, in pixels. Filled in by the driver.
106 * - __u32 106 * - __u32
107 - ``max_height`` 107 - ``max_height``
108 - Maximum frame height, in pixels. Fille 108 - Maximum frame height, in pixels. Filled in by the driver.
109 * - __u32 109 * - __u32
110 - ``which`` 110 - ``which``
111 - Frame sizes to be enumerated, from enu 111 - Frame sizes to be enumerated, from enum
112 :ref:`v4l2_subdev_format_whence <v4l2- 112 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
113 * - __u32 113 * - __u32
114 - ``stream`` 114 - ``stream``
115 - Stream identifier. 115 - Stream identifier.
116 * - __u32 116 * - __u32
117 - ``reserved``\ [7] 117 - ``reserved``\ [7]
118 - Reserved for future extensions. Applic 118 - Reserved for future extensions. Applications and drivers must set
119 the array to zero. 119 the array to zero.
120 120
121 Return Value 121 Return Value
122 ============ 122 ============
123 123
124 On success 0 is returned, on error -1 and the 124 On success 0 is returned, on error -1 and the ``errno`` variable is set
125 appropriately. The generic error codes are des 125 appropriately. The generic error codes are described at the
126 :ref:`Generic Error Codes <gen-errors>` chapte 126 :ref:`Generic Error Codes <gen-errors>` chapter.
127 127
128 EINVAL 128 EINVAL
129 The struct :c:type:`v4l2_subdev_frame_size 129 The struct :c:type:`v4l2_subdev_frame_size_enum` ``pad`` references a
130 non-existing pad, the ``which`` field has 130 non-existing pad, the ``which`` field has an unsupported value, the ``code``
131 is invalid for the given pad, or the ``ind 131 is invalid for the given pad, or the ``index`` field is out of bounds.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.