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