vidioc-subdev-enum-frame-size.rst

  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 access the enumeration of frame sizes
 35supported by a sub-device on the specified pad
 36for the specified media bus format.
 37Supported formats can be retrieved with the
 38:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
 39ioctl.
 40
 41The enumerations are defined by the driver, and indexed using the ``index`` field
 42of the struct :c:type:`v4l2_subdev_frame_size_enum`.
 43Each pair of ``pad`` and ``code`` correspond to a separate enumeration.
 44Each enumeration starts with the ``index`` of 0, and
 45the lowest invalid index marks the end of the enumeration.
 46
 47Therefore, to enumerate frame sizes allowed on the specified pad
 48and using the specified mbus format, initialize the
 49``pad``, ``which``, and ``code`` fields to desired values,
 50and set ``index`` to 0.
 51Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
 52structure.
 53
 54A successful call will return with minimum and maximum frame sizes filled in.
 55Repeat with increasing ``index`` until ``EINVAL`` is received.
 56``EINVAL`` means that either no more entries are available in the enumeration,
 57or that an input parameter was invalid.
 58
 59Sub-devices that only support discrete frame sizes (such as most
 60sensors) will return one or more frame sizes with identical minimum and
 61maximum values.
 62
 63Not all possible sizes in given [minimum, maximum] ranges need to be
 64supported. For instance, a scaler that uses a fixed-point scaling ratio
 65might not be able to produce every frame size between the minimum and
 66maximum values. Applications must use the
 67:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
 68sub-device for an exact supported frame size.
 69
 70Available frame sizes may depend on the current 'try' formats at other
 71pads of the sub-device, as well as on the current active links and the
 72current values of V4L2 controls. See
 73:ref:`VIDIOC_SUBDEV_G_FMT` for more
 74information about try formats.
 75
 76.. c:type:: v4l2_subdev_frame_size_enum
 77
 78.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
 79
 80.. flat-table:: struct v4l2_subdev_frame_size_enum
 81    :header-rows:  0
 82    :stub-columns: 0
 83    :widths:       1 1 2
 84
 85    * - __u32
 86      - ``index``
 87      - Index of the frame size in the enumeration belonging to the given pad
 88	and format. Filled in by the application.
 89    * - __u32
 90      - ``pad``
 91      - Pad number as reported by the media controller API.
 92	Filled in by the application.
 93    * - __u32
 94      - ``code``
 95      - The media bus format code, as defined in
 96	:ref:`v4l2-mbus-format`. Filled in by the application.
 97    * - __u32
 98      - ``min_width``
 99      - Minimum frame width, in pixels. Filled in by the driver.
100    * - __u32
101      - ``max_width``
102      - Maximum frame width, in pixels. Filled in by the driver.
103    * - __u32
104      - ``min_height``
105      - Minimum frame height, in pixels. Filled in by the driver.
106    * - __u32
107      - ``max_height``
108      - Maximum frame height, in pixels. Filled in by the driver.
109    * - __u32
110      - ``which``
111      - Frame sizes to be enumerated, from enum
112	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
113    * - __u32
114      - ``stream``
115      - Stream identifier.
116    * - __u32
117      - ``reserved``\ [7]
118      - Reserved for future extensions. Applications and drivers must set
119	the array to zero.
120
121Return Value
122============
123
124On success 0 is returned, on error -1 and the ``errno`` variable is set
125appropriately. The generic error codes are described at the
126:ref:`Generic Error Codes <gen-errors>` chapter.
127
128EINVAL
129    The struct :c:type:`v4l2_subdev_frame_size_enum` ``pad`` references a
130    non-existing pad, the ``which`` field has an unsupported value, the ``code``
131    is invalid for the given pad, or the ``index`` field is out of bounds.