0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENUM_FRAMEINTERVALS:
0005
0006 ********************************
0007 ioctl VIDIOC_ENUM_FRAMEINTERVALS
0008 ********************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS
0019
0020 ``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *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_frmivalenum`
0030 that contains a pixel format and size and receives a frame interval.
0031
0032 Description
0033 ===========
0034
0035 This ioctl allows applications to enumerate all frame intervals that the
0036 device supports for the given pixel format and frame size.
0037
0038 The supported pixel formats and frame sizes can be obtained by using the
0039 :ref:`VIDIOC_ENUM_FMT` and
0040 :ref:`VIDIOC_ENUM_FRAMESIZES` functions.
0041
0042 The return value and the content of the ``v4l2_frmivalenum.type`` field
0043 depend on the type of frame intervals the device supports. Here are the
0044 semantics of the function for the different cases:
0045
0046 - **Discrete:** The function returns success if the given index value
0047 (zero-based) is valid. The application should increase the index by
0048 one for each call until ``EINVAL`` is returned. The
0049 `v4l2_frmivalenum.type` field is set to
0050 `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
0051 the `discrete` member is valid.
0052
0053 - **Step-wise:** The function returns success if the given index value
0054 is zero and ``EINVAL`` for any other index value. The
0055 ``v4l2_frmivalenum.type`` field is set to
0056 ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
0057 ``stepwise`` member is valid.
0058
0059 - **Continuous:** This is a special case of the step-wise type above.
0060 The function returns success if the given index value is zero and
0061 ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
0062 field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
0063 the union only the ``stepwise`` member is valid and the ``step``
0064 value is set to 1.
0065
0066 When the application calls the function with index zero, it must check
0067 the ``type`` field to determine the type of frame interval enumeration
0068 the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
0069 does it make sense to increase the index value to receive more frame
0070 intervals.
0071
0072 .. note::
0073
0074 The order in which the frame intervals are returned has no
0075 special meaning. In particular does it not say anything about potential
0076 default frame intervals.
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 interval enumeration.
0082
0083 .. note::
0084
0085 **Frame intervals and frame rates:** The V4L2 API uses frame
0086 intervals instead of frame rates. Given the frame interval the frame
0087 rate can be computed as follows:
0088
0089 ::
0090
0091 frame_rate = 1 / frame_interval
0092
0093 Structs
0094 =======
0095
0096 In the structs below, *IN* denotes a value that has to be filled in by
0097 the application, *OUT* denotes values that the driver fills in. The
0098 application should zero out all members except for the *IN* fields.
0099
0100 .. c:type:: v4l2_frmival_stepwise
0101
0102 .. flat-table:: struct v4l2_frmival_stepwise
0103 :header-rows: 0
0104 :stub-columns: 0
0105 :widths: 1 1 2
0106
0107 * - struct :c:type:`v4l2_fract`
0108 - ``min``
0109 - Minimum frame interval [s].
0110 * - struct :c:type:`v4l2_fract`
0111 - ``max``
0112 - Maximum frame interval [s].
0113 * - struct :c:type:`v4l2_fract`
0114 - ``step``
0115 - Frame interval step size [s].
0116
0117
0118 .. c:type:: v4l2_frmivalenum
0119
0120 .. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}|
0121
0122 .. flat-table:: struct v4l2_frmivalenum
0123 :header-rows: 0
0124 :stub-columns: 0
0125
0126 * - __u32
0127 - ``index``
0128 - IN: Index of the given frame interval in the enumeration.
0129 * - __u32
0130 - ``pixel_format``
0131 - IN: Pixel format for which the frame intervals are enumerated.
0132 * - __u32
0133 - ``width``
0134 - IN: Frame width for which the frame intervals are enumerated.
0135 * - __u32
0136 - ``height``
0137 - IN: Frame height for which the frame intervals are enumerated.
0138 * - __u32
0139 - ``type``
0140 - OUT: Frame interval type the device supports.
0141 * - union {
0142 - (anonymous)
0143 - OUT: Frame interval with the given index.
0144 * - struct :c:type:`v4l2_fract`
0145 - ``discrete``
0146 - Frame interval [s].
0147 * - struct :c:type:`v4l2_frmival_stepwise`
0148 - ``stepwise``
0149 -
0150 * - }
0151 -
0152 -
0153 * - __u32
0154 - ``reserved[2]``
0155 - Reserved space for future use. Must be zeroed by drivers and
0156 applications.
0157
0158
0159 Enums
0160 =====
0161
0162 .. c:type:: v4l2_frmivaltypes
0163
0164 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0165
0166 .. flat-table:: enum v4l2_frmivaltypes
0167 :header-rows: 0
0168 :stub-columns: 0
0169 :widths: 3 1 4
0170
0171 * - ``V4L2_FRMIVAL_TYPE_DISCRETE``
0172 - 1
0173 - Discrete frame interval.
0174 * - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
0175 - 2
0176 - Continuous frame interval.
0177 * - ``V4L2_FRMIVAL_TYPE_STEPWISE``
0178 - 3
0179 - Step-wise defined frame interval.
0180
0181 Return Value
0182 ============
0183
0184 On success 0 is returned, on error -1 and the ``errno`` variable is set
0185 appropriately. The generic error codes are described at the
0186 :ref:`Generic Error Codes <gen-errors>` chapter.
