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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
   4
   5 ***********************************
   6 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
   7 ***********************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_SUBDEV_ENUM_FRAME_SIZE
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 This ioctl allows applications to enumerate all frame sizes supported by
  37 a sub-device on the given pad for the given media bus format. Supported
  38 formats can be retrieved with the
  39 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
  40 ioctl.
  41
  42 To enumerate frame sizes applications initialize the ``pad``, ``which``
  43 , ``code`` and ``index`` fields of the struct
  44 :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
  45 call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
  46 structure. Drivers fill the minimum and maximum frame sizes or return an
  47 EINVAL error code if one of the input parameters is invalid.
  48
  49 Sub-devices that only support discrete frame sizes (such as most
  50 sensors) will return one or more frame sizes with identical minimum and
  51 maximum values.
  52
  53 Not all possible sizes in given [minimum, maximum] ranges need to be
  54 supported. For instance, a scaler that uses a fixed-point scaling ratio
  55 might not be able to produce every frame size between the minimum and
  56 maximum values. Applications must use the
  57 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
  58 sub-device for an exact supported frame size.
  59
  60 Available frame sizes may depend on the current 'try' formats at other
  61 pads of the sub-device, as well as on the current active links and the
  62 current values of V4L2 controls. See
  63 :ref:`VIDIOC_SUBDEV_G_FMT` for more
  64 information about try formats.
  65
  66
  67 .. _v4l2-subdev-frame-size-enum:
  68
  69 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  70
  71 .. flat-table:: struct v4l2_subdev_frame_size_enum
  72     :header-rows:  0
  73     :stub-columns: 0
  74     :widths:       1 1 2
  75
  76
  77     -  .. row 1
  78
  79        -  __u32
  80
  81        -  ``index``
  82
  83        -  Number of the format in the enumeration, set by the application.
  84
  85     -  .. row 2
  86
  87        -  __u32
  88
  89        -  ``pad``
  90
  91        -  Pad number as reported by the media controller API.
  92
  93     -  .. row 3
  94
  95        -  __u32
  96
  97        -  ``code``
  98
  99        -  The media bus format code, as defined in
 100           :ref:`v4l2-mbus-format`.
 101
 102     -  .. row 4
 103
 104        -  __u32
 105
 106        -  ``min_width``
 107
 108        -  Minimum frame width, in pixels.
 109
 110     -  .. row 5
 111
 112        -  __u32
 113
 114        -  ``max_width``
 115
 116        -  Maximum frame width, in pixels.
 117
 118     -  .. row 6
 119
 120        -  __u32
 121
 122        -  ``min_height``
 123
 124        -  Minimum frame height, in pixels.
 125
 126     -  .. row 7
 127
 128        -  __u32
 129
 130        -  ``max_height``
 131
 132        -  Maximum frame height, in pixels.
 133
 134     -  .. row 8
 135
 136        -  __u32
 137
 138        -  ``which``
 139
 140        -  Frame sizes to be enumerated, from enum
 141           :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
 142
 143     -  .. row 9
 144
 145        -  __u32
 146
 147        -  ``reserved``\ [8]
 148
 149        -  Reserved for future extensions. Applications and drivers must set
 150           the array to zero.
 151
 152
 153 Return Value
 154 ============
 155
 156 On success 0 is returned, on error -1 and the ``errno`` variable is set
 157 appropriately. The generic error codes are described at the
 158 :ref:`Generic Error Codes <gen-errors>` chapter.
 159
 160 EINVAL
 161     The struct
 162     :ref:`v4l2_subdev_frame_size_enum <v4l2-subdev-frame-size-enum>`
 163     ``pad`` references a non-existing pad, the ``code`` is invalid for
 164     the given pad or the ``index`` field is out of bounds.