Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst

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