Documentation/userspace-api/media/v4l/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 ***********************************
   7 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
   8 ***********************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
  14
  15 Synopsis
  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
  22 Arguments
  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
  31 Description
  32 ===========
  33
  34 This ioctl allows applications to access the enumeration of frame sizes
  35 supported by a sub-device on the specified pad
  36 for the specified media bus format.
  37 Supported formats can be retrieved with the
  38 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
  39 ioctl.
  40
  41 The enumerations are defined by the driver, and indexed using the ``index`` field
  42 of the struct :c:type:`v4l2_subdev_frame_size_enum`.
  43 Each pair of ``pad`` and ``code`` correspond to a separate enumeration.
  44 Each enumeration starts with the ``index`` of 0, and
  45 the lowest invalid index marks the end of the enumeration.
  46
  47 Therefore, to enumerate frame sizes allowed on the specified pad
  48 and using the specified mbus format, initialize the
  49 ``pad``, ``which``, and ``code`` fields to desired values,
  50 and set ``index`` to 0.
  51 Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
  52 structure.
  53
  54 A successful call will return with minimum and maximum frame sizes filled in.
  55 Repeat with increasing ``index`` until ``EINVAL`` is received.
  56 ``EINVAL`` means that either no more entries are available in the enumeration,
  57 or that an input parameter was invalid.
  58
  59 Sub-devices that only support discrete frame sizes (such as most
  60 sensors) will return one or more frame sizes with identical minimum and
  61 maximum values.
  62
  63 Not all possible sizes in given [minimum, maximum] ranges need to be
  64 supported. For instance, a scaler that uses a fixed-point scaling ratio
  65 might not be able to produce every frame size between the minimum and
  66 maximum values. Applications must use the
  67 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
  68 sub-device for an exact supported frame size.
  69
  70 Available frame sizes may depend on the current 'try' formats at other
  71 pads of the sub-device, as well as on the current active links and the
  72 current values of V4L2 controls. See
  73 :ref:`VIDIOC_SUBDEV_G_FMT` for more
  74 information 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
 121 Return Value
 122 ============
 123
 124 On success 0 is returned, on error -1 and the ``errno`` variable is set
 125 appropriately. The generic error codes are described at the
 126 :ref:`Generic Error Codes <gen-errors>` chapter.
 127
 128 EINVAL
 129     The struct
 130     :c:type:`v4l2_subdev_frame_size_enum`
 131     ``pad`` references a non-existing pad, the ``code`` is invalid for
 132     the given pad or the ``index`` field is out of bounds.