Documentation/linux_tv/media/v4l/vidioc-enum-framesizes.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUM_FRAMESIZES:
   4
   5 ****************************
   6 ioctl VIDIOC_ENUM_FRAMESIZES
   7 ****************************
   8
   9 NAME
  10 ====
  11
  12 VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
  13
  14 SYNOPSIS
  15 ========
  16
  17 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp )
  18
  19
  20 ARGUMENTS
  21 =========
  22
  23 ``fd``
  24     File descriptor returned by :ref:`open() <func-open>`.
  25
  26 ``request``
  27     VIDIOC_ENUM_FRAMESIZES
  28
  29 ``argp``
  30     Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>`
  31     that contains an index and pixel format and receives a frame width
  32     and height.
  33
  34
  35 DESCRIPTION
  36 ===========
  37
  38 This ioctl allows applications to enumerate all frame sizes (i. e. width
  39 and height in pixels) that the device supports for the given pixel
  40 format.
  41
  42 The supported pixel formats can be obtained by using the
  43 :ref:`VIDIOC_ENUM_FMT` function.
  44
  45 The return value and the content of the ``v4l2_frmsizeenum.type`` field
  46 depend on the type of frame sizes the device supports. Here are the
  47 semantics of the function for the different cases:
  48
  49 -  **Discrete:** The function returns success if the given index value
  50    (zero-based) is valid. The application should increase the index by
  51    one for each call until ``EINVAL`` is returned. The
  52    ``v4l2_frmsizeenum.type`` field is set to
  53    ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
  54    ``discrete`` member is valid.
  55
  56 -  **Step-wise:** The function returns success if the given index value
  57    is zero and ``EINVAL`` for any other index value. The
  58    ``v4l2_frmsizeenum.type`` field is set to
  59    ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
  60    ``stepwise`` member is valid.
  61
  62 -  **Continuous:** This is a special case of the step-wise type above.
  63    The function returns success if the given index value is zero and
  64    ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
  65    field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
  66    the union only the ``stepwise`` member is valid and the
  67    ``step_width`` and ``step_height`` values are set to 1.
  68
  69 When the application calls the function with index zero, it must check
  70 the ``type`` field to determine the type of frame size enumeration the
  71 device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
  72 it make sense to increase the index value to receive more frame sizes.
  73
  74 Note that the order in which the frame sizes are returned has no special
  75 meaning. In particular does it not say anything about potential default
  76 format sizes.
  77
  78 Applications can assume that the enumeration data does not change
  79 without any interaction from the application itself. This means that the
  80 enumeration data is consistent if the application does not perform any
  81 other ioctl calls while it runs the frame size enumeration.
  82
  83
  84 Structs
  85 =======
  86
  87 In the structs below, *IN* denotes a value that has to be filled in by
  88 the application, *OUT* denotes values that the driver fills in. The
  89 application should zero out all members except for the *IN* fields.
  90
  91
  92 .. _v4l2-frmsize-discrete:
  93
  94 .. flat-table:: struct v4l2_frmsize_discrete
  95     :header-rows:  0
  96     :stub-columns: 0
  97     :widths:       1 1 2
  98
  99
 100     -  .. row 1
 101
 102        -  __u32
 103
 104        -  ``width``
 105
 106        -  Width of the frame [pixel].
 107
 108     -  .. row 2
 109
 110        -  __u32
 111
 112        -  ``height``
 113
 114        -  Height of the frame [pixel].
 115
 116
 117
 118 .. _v4l2-frmsize-stepwise:
 119
 120 .. flat-table:: struct v4l2_frmsize_stepwise
 121     :header-rows:  0
 122     :stub-columns: 0
 123     :widths:       1 1 2
 124
 125
 126     -  .. row 1
 127
 128        -  __u32
 129
 130        -  ``min_width``
 131
 132        -  Minimum frame width [pixel].
 133
 134     -  .. row 2
 135
 136        -  __u32
 137
 138        -  ``max_width``
 139
 140        -  Maximum frame width [pixel].
 141
 142     -  .. row 3
 143
 144        -  __u32
 145
 146        -  ``step_width``
 147
 148        -  Frame width step size [pixel].
 149
 150     -  .. row 4
 151
 152        -  __u32
 153
 154        -  ``min_height``
 155
 156        -  Minimum frame height [pixel].
 157
 158     -  .. row 5
 159
 160        -  __u32
 161
 162        -  ``max_height``
 163
 164        -  Maximum frame height [pixel].
 165
 166     -  .. row 6
 167
 168        -  __u32
 169
 170        -  ``step_height``
 171
 172        -  Frame height step size [pixel].
 173
 174
 175
 176 .. _v4l2-frmsizeenum:
 177
 178 .. flat-table:: struct v4l2_frmsizeenum
 179     :header-rows:  0
 180     :stub-columns: 0
 181
 182
 183     -  .. row 1
 184
 185        -  __u32
 186
 187        -  ``index``
 188
 189        -
 190        -  IN: Index of the given frame size in the enumeration.
 191
 192     -  .. row 2
 193
 194        -  __u32
 195
 196        -  ``pixel_format``
 197
 198        -
 199        -  IN: Pixel format for which the frame sizes are enumerated.
 200
 201     -  .. row 3
 202
 203        -  __u32
 204
 205        -  ``type``
 206
 207        -
 208        -  OUT: Frame size type the device supports.
 209
 210     -  .. row 4
 211
 212        -  union
 213
 214        -
 215        -
 216        -  OUT: Frame size with the given index.
 217
 218     -  .. row 5
 219
 220        -
 221        -  struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>`
 222
 223        -  ``discrete``
 224
 225        -
 226
 227     -  .. row 6
 228
 229        -
 230        -  struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>`
 231
 232        -  ``stepwise``
 233
 234        -
 235
 236     -  .. row 7
 237
 238        -  __u32
 239
 240        -  ``reserved[2]``
 241
 242        -
 243        -  Reserved space for future use. Must be zeroed by drivers and
 244           applications.
 245
 246
 247
 248 Enums
 249 =====
 250
 251
 252 .. _v4l2-frmsizetypes:
 253
 254 .. flat-table:: enum v4l2_frmsizetypes
 255     :header-rows:  0
 256     :stub-columns: 0
 257     :widths:       3 1 4
 258
 259
 260     -  .. row 1
 261
 262        -  ``V4L2_FRMSIZE_TYPE_DISCRETE``
 263
 264        -  1
 265
 266        -  Discrete frame size.
 267
 268     -  .. row 2
 269
 270        -  ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
 271
 272        -  2
 273
 274        -  Continuous frame size.
 275
 276     -  .. row 3
 277
 278        -  ``V4L2_FRMSIZE_TYPE_STEPWISE``
 279
 280        -  3
 281
 282        -  Step-wise defined frame size.
 283
 284
 285 RETURN VALUE
 286 ============
 287
 288 On success 0 is returned, on error -1 and the ``errno`` variable is set
 289 appropriately. The generic error codes are described at the
 290 :ref:`Generic Error Codes <gen-errors>` chapter.