0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
0005
0006 ***********************************
0007 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
0008 ***********************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
0019
0020 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`.
0030
0031 Description
0032 ===========
0033
0034 This ioctl allows applications to enumerate all frame sizes supported by
0035 a sub-device on the given pad for the given media bus format. Supported
0036 formats can be retrieved with the
0037 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
0038 ioctl.
0039
0040 To enumerate frame sizes applications initialize the ``pad``, ``which``
0041 , ``code`` and ``index`` fields of the struct
0042 :c:type:`v4l2_subdev_mbus_code_enum` and
0043 call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
0044 structure. Drivers fill the minimum and maximum frame sizes or return an
0045 EINVAL error code if one of the input parameters is invalid.
0046
0047 Sub-devices that only support discrete frame sizes (such as most
0048 sensors) will return one or more frame sizes with identical minimum and
0049 maximum values.
0050
0051 Not all possible sizes in given [minimum, maximum] ranges need to be
0052 supported. For instance, a scaler that uses a fixed-point scaling ratio
0053 might not be able to produce every frame size between the minimum and
0054 maximum values. Applications must use the
0055 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
0056 sub-device for an exact supported frame size.
0057
0058 Available frame sizes may depend on the current 'try' formats at other
0059 pads of the sub-device, as well as on the current active links and the
0060 current values of V4L2 controls. See
0061 :ref:`VIDIOC_SUBDEV_G_FMT` for more
0062 information about try formats.
0063
0064 .. c:type:: v4l2_subdev_frame_size_enum
0065
0066 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0067
0068 .. flat-table:: struct v4l2_subdev_frame_size_enum
0069 :header-rows: 0
0070 :stub-columns: 0
0071 :widths: 1 1 2
0072
0073 * - __u32
0074 - ``index``
0075 - Number of the format in the enumeration, set by the application.
0076 * - __u32
0077 - ``pad``
0078 - Pad number as reported by the media controller API.
0079 * - __u32
0080 - ``code``
0081 - The media bus format code, as defined in
0082 :ref:`v4l2-mbus-format`.
0083 * - __u32
0084 - ``min_width``
0085 - Minimum frame width, in pixels.
0086 * - __u32
0087 - ``max_width``
0088 - Maximum frame width, in pixels.
0089 * - __u32
0090 - ``min_height``
0091 - Minimum frame height, in pixels.
0092 * - __u32
0093 - ``max_height``
0094 - Maximum frame height, in pixels.
0095 * - __u32
0096 - ``which``
0097 - Frame sizes to be enumerated, from enum
0098 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
0099 * - __u32
0100 - ``reserved``\ [8]
0101 - Reserved for future extensions. Applications and drivers must set
0102 the array to zero.
0103
0104 Return Value
0105 ============
0106
0107 On success 0 is returned, on error -1 and the ``errno`` variable is set
0108 appropriately. The generic error codes are described at the
0109 :ref:`Generic Error Codes <gen-errors>` chapter.
0110
0111 EINVAL
0112 The struct
0113 :c:type:`v4l2_subdev_frame_size_enum`
0114 ``pad`` references a non-existing pad, the ``code`` is invalid for
0115 the given pad or the ``index`` field is out of bounds.
