0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENUM_FRAMESIZES:
0005
0006 ****************************
0007 ioctl VIDIOC_ENUM_FRAMESIZES
0008 ****************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENUM_FRAMESIZES
0019
0020 ``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_frmsizeenum`
0030 that contains an index and pixel format and receives a frame width
0031 and height.
0032
0033 Description
0034 ===========
0035
0036 This ioctl allows applications to enumerate all frame sizes (i. e. width
0037 and height in pixels) that the device supports for the given pixel
0038 format.
0039
0040 The supported pixel formats can be obtained by using the
0041 :ref:`VIDIOC_ENUM_FMT` function.
0042
0043 The return value and the content of the ``v4l2_frmsizeenum.type`` field
0044 depend on the type of frame sizes the device supports. Here are the
0045 semantics of the function for the different cases:
0046
0047 - **Discrete:** The function returns success if the given index value
0048 (zero-based) is valid. The application should increase the index by
0049 one for each call until ``EINVAL`` is returned. The
0050 ``v4l2_frmsizeenum.type`` field is set to
0051 ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
0052 ``discrete`` member is valid.
0053
0054 - **Step-wise:** The function returns success if the given index value
0055 is zero and ``EINVAL`` for any other index value. The
0056 ``v4l2_frmsizeenum.type`` field is set to
0057 ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
0058 ``stepwise`` member is valid.
0059
0060 - **Continuous:** This is a special case of the step-wise type above.
0061 The function returns success if the given index value is zero and
0062 ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
0063 field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
0064 the union only the ``stepwise`` member is valid and the
0065 ``step_width`` and ``step_height`` values are set to 1.
0066
0067 When the application calls the function with index zero, it must check
0068 the ``type`` field to determine the type of frame size enumeration the
0069 device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
0070 it make sense to increase the index value to receive more frame sizes.
0071
0072 .. note::
0073
0074 The order in which the frame sizes are returned has no special
0075 meaning. In particular does it not say anything about potential default
0076 format sizes.
0077
0078 Applications can assume that the enumeration data does not change
0079 without any interaction from the application itself. This means that the
0080 enumeration data is consistent if the application does not perform any
0081 other ioctl calls while it runs the frame size enumeration.
0082
0083 Structs
0084 =======
0085
0086 In the structs below, *IN* denotes a value that has to be filled in by
0087 the application, *OUT* denotes values that the driver fills in. The
0088 application should zero out all members except for the *IN* fields.
0089
0090 .. c:type:: v4l2_frmsize_discrete
0091
0092 .. flat-table:: struct v4l2_frmsize_discrete
0093 :header-rows: 0
0094 :stub-columns: 0
0095 :widths: 1 1 2
0096
0097 * - __u32
0098 - ``width``
0099 - Width of the frame [pixel].
0100 * - __u32
0101 - ``height``
0102 - Height of the frame [pixel].
0103
0104
0105 .. c:type:: v4l2_frmsize_stepwise
0106
0107 .. flat-table:: struct v4l2_frmsize_stepwise
0108 :header-rows: 0
0109 :stub-columns: 0
0110 :widths: 1 1 2
0111
0112 * - __u32
0113 - ``min_width``
0114 - Minimum frame width [pixel].
0115 * - __u32
0116 - ``max_width``
0117 - Maximum frame width [pixel].
0118 * - __u32
0119 - ``step_width``
0120 - Frame width step size [pixel].
0121 * - __u32
0122 - ``min_height``
0123 - Minimum frame height [pixel].
0124 * - __u32
0125 - ``max_height``
0126 - Maximum frame height [pixel].
0127 * - __u32
0128 - ``step_height``
0129 - Frame height step size [pixel].
0130
0131
0132 .. c:type:: v4l2_frmsizeenum
0133
0134 .. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}|
0135
0136 .. flat-table:: struct v4l2_frmsizeenum
0137 :header-rows: 0
0138 :stub-columns: 0
0139
0140 * - __u32
0141 - ``index``
0142 - IN: Index of the given frame size in the enumeration.
0143 * - __u32
0144 - ``pixel_format``
0145 - IN: Pixel format for which the frame sizes are enumerated.
0146 * - __u32
0147 - ``type``
0148 - OUT: Frame size type the device supports.
0149 * - union {
0150 - (anonymous)
0151 - OUT: Frame size with the given index.
0152 * - struct :c:type:`v4l2_frmsize_discrete`
0153 - ``discrete``
0154 -
0155 * - struct :c:type:`v4l2_frmsize_stepwise`
0156 - ``stepwise``
0157 -
0158 * - }
0159 -
0160 -
0161 * - __u32
0162 - ``reserved[2]``
0163 - Reserved space for future use. Must be zeroed by drivers and
0164 applications.
0165
0166
0167 Enums
0168 =====
0169
0170 .. c:type:: v4l2_frmsizetypes
0171
0172 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0173
0174 .. flat-table:: enum v4l2_frmsizetypes
0175 :header-rows: 0
0176 :stub-columns: 0
0177 :widths: 3 1 4
0178
0179 * - ``V4L2_FRMSIZE_TYPE_DISCRETE``
0180 - 1
0181 - Discrete frame size.
0182 * - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
0183 - 2
0184 - Continuous frame size.
0185 * - ``V4L2_FRMSIZE_TYPE_STEPWISE``
0186 - 3
0187 - Step-wise defined frame size.
0188
0189 Return Value
0190 ============
0191
0192 On success 0 is returned, on error -1 and the ``errno`` variable is set
0193 appropriately. The generic error codes are described at the
0194 :ref:`Generic Error Codes <gen-errors>` chapter.
