Documentation/media/uapi/v4l/vidioc-enum-framesizes.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/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_ENUM_FRAMESIZES:
  11
  12 ****************************
  13 ioctl VIDIOC_ENUM_FRAMESIZES
  14 ****************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp )
  26     :name: VIDIOC_ENUM_FRAMESIZES
  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_frmsizeenum`
  37     that contains an index and pixel format and receives a frame width
  38     and height.
  39
  40
  41 Description
  42 ===========
  43
  44 This ioctl allows applications to enumerate all frame sizes (i. e. width
  45 and height in pixels) that the device supports for the given pixel
  46 format.
  47
  48 The supported pixel formats can be obtained by using the
  49 :ref:`VIDIOC_ENUM_FMT` function.
  50
  51 The return value and the content of the ``v4l2_frmsizeenum.type`` field
  52 depend on the type of frame sizes the device supports. Here are the
  53 semantics of the function for the different cases:
  54
  55 -  **Discrete:** The function returns success if the given index value
  56    (zero-based) is valid. The application should increase the index by
  57    one for each call until ``EINVAL`` is returned. The
  58    ``v4l2_frmsizeenum.type`` field is set to
  59    ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
  60    ``discrete`` member is valid.
  61
  62 -  **Step-wise:** The function returns success if the given index value
  63    is zero and ``EINVAL`` for any other index value. The
  64    ``v4l2_frmsizeenum.type`` field is set to
  65    ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
  66    ``stepwise`` member is valid.
  67
  68 -  **Continuous:** This is a special case of the step-wise type above.
  69    The function returns success if the given index value is zero and
  70    ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
  71    field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
  72    the union only the ``stepwise`` member is valid and the
  73    ``step_width`` and ``step_height`` values are set to 1.
  74
  75 When the application calls the function with index zero, it must check
  76 the ``type`` field to determine the type of frame size enumeration the
  77 device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
  78 it make sense to increase the index value to receive more frame sizes.
  79
  80 .. note::
  81
  82    The order in which the frame sizes are returned has no special
  83    meaning. In particular does it not say anything about potential default
  84    format sizes.
  85
  86 Applications can assume that the enumeration data does not change
  87 without any interaction from the application itself. This means that the
  88 enumeration data is consistent if the application does not perform any
  89 other ioctl calls while it runs the frame size enumeration.
  90
  91
  92 Structs
  93 =======
  94
  95 In the structs below, *IN* denotes a value that has to be filled in by
  96 the application, *OUT* denotes values that the driver fills in. The
  97 application should zero out all members except for the *IN* fields.
  98
  99
 100 .. c:type:: v4l2_frmsize_discrete
 101
 102 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 103
 104 .. flat-table:: struct v4l2_frmsize_discrete
 105     :header-rows:  0
 106     :stub-columns: 0
 107     :widths:       1 1 2
 108
 109     * - __u32
 110       - ``width``
 111       - Width of the frame [pixel].
 112     * - __u32
 113       - ``height``
 114       - Height of the frame [pixel].
 115
 116
 117
 118 .. c:type:: v4l2_frmsize_stepwise
 119
 120 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 121
 122 .. flat-table:: struct v4l2_frmsize_stepwise
 123     :header-rows:  0
 124     :stub-columns: 0
 125     :widths:       1 1 2
 126
 127     * - __u32
 128       - ``min_width``
 129       - Minimum frame width [pixel].
 130     * - __u32
 131       - ``max_width``
 132       - Maximum frame width [pixel].
 133     * - __u32
 134       - ``step_width``
 135       - Frame width step size [pixel].
 136     * - __u32
 137       - ``min_height``
 138       - Minimum frame height [pixel].
 139     * - __u32
 140       - ``max_height``
 141       - Maximum frame height [pixel].
 142     * - __u32
 143       - ``step_height``
 144       - Frame height step size [pixel].
 145
 146
 147
 148 .. c:type:: v4l2_frmsizeenum
 149
 150 .. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}|
 151
 152 .. flat-table:: struct v4l2_frmsizeenum
 153     :header-rows:  0
 154     :stub-columns: 0
 155
 156     * - __u32
 157       - ``index``
 158       -
 159       - IN: Index of the given frame size in the enumeration.
 160     * - __u32
 161       - ``pixel_format``
 162       -
 163       - IN: Pixel format for which the frame sizes are enumerated.
 164     * - __u32
 165       - ``type``
 166       -
 167       - OUT: Frame size type the device supports.
 168     * - union
 169       -
 170       -
 171       - OUT: Frame size with the given index.
 172     * -
 173       - struct :c:type:`v4l2_frmsize_discrete`
 174       - ``discrete``
 175       -
 176     * -
 177       - struct :c:type:`v4l2_frmsize_stepwise`
 178       - ``stepwise``
 179       -
 180     * - __u32
 181       - ``reserved[2]``
 182       -
 183       - Reserved space for future use. Must be zeroed by drivers and
 184         applications.
 185
 186
 187
 188 Enums
 189 =====
 190
 191
 192 .. c:type:: v4l2_frmsizetypes
 193
 194 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 195
 196 .. flat-table:: enum v4l2_frmsizetypes
 197     :header-rows:  0
 198     :stub-columns: 0
 199     :widths:       3 1 4
 200
 201     * - ``V4L2_FRMSIZE_TYPE_DISCRETE``
 202       - 1
 203       - Discrete frame size.
 204     * - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
 205       - 2
 206       - Continuous frame size.
 207     * - ``V4L2_FRMSIZE_TYPE_STEPWISE``
 208       - 3
 209       - Step-wise defined frame size.
 210
 211
 212 Return Value
 213 ============
 214
 215 On success 0 is returned, on error -1 and the ``errno`` variable is set
 216 appropriately. The generic error codes are described at the
 217 :ref:`Generic Error Codes <gen-errors>` chapter.