0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
0005
0006 ***************************************
0007 ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
0008 ***************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
0019
0020 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * 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_subdev_frame_interval_enum`.
0030
0031 Description
0032 ===========
0033
0034 This ioctl lets applications enumerate available frame intervals on a
0035 given sub-device pad. Frame intervals only makes sense for sub-devices
0036 that can control the frame period on their own. This includes, for
0037 instance, image sensors and TV tuners.
0038
0039 For the common use case of image sensors, the frame intervals available
0040 on the sub-device output pad depend on the frame format and size on the
0041 same pad. Applications must thus specify the desired format and size
0042 when enumerating frame intervals.
0043
0044 To enumerate frame intervals applications initialize the ``index``,
0045 ``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
0046 :c:type:`v4l2_subdev_frame_interval_enum`
0047 and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
0048 to this structure. Drivers fill the rest of the structure or return an
0049 EINVAL error code if one of the input fields is invalid. All frame
0050 intervals are enumerable by beginning at index zero and incrementing by
0051 one until ``EINVAL`` is returned.
0052
0053 Available frame intervals may depend on the current 'try' formats at
0054 other pads of the sub-device, as well as on the current active links.
0055 See :ref:`VIDIOC_SUBDEV_G_FMT` for more
0056 information about the try formats.
0057
0058 Sub-devices that support the frame interval enumeration ioctl should
0059 implemented it on a single pad only. Its behaviour when supported on
0060 multiple pads of the same sub-device is not defined.
0061
0062 .. c:type:: v4l2_subdev_frame_interval_enum
0063
0064 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0065
0066 .. flat-table:: struct v4l2_subdev_frame_interval_enum
0067 :header-rows: 0
0068 :stub-columns: 0
0069 :widths: 1 1 2
0070
0071 * - __u32
0072 - ``index``
0073 - Number of the format in the enumeration, set by the application.
0074 * - __u32
0075 - ``pad``
0076 - Pad number as reported by the media controller API.
0077 * - __u32
0078 - ``code``
0079 - The media bus format code, as defined in
0080 :ref:`v4l2-mbus-format`.
0081 * - __u32
0082 - ``width``
0083 - Frame width, in pixels.
0084 * - __u32
0085 - ``height``
0086 - Frame height, in pixels.
0087 * - struct :c:type:`v4l2_fract`
0088 - ``interval``
0089 - Period, in seconds, between consecutive video frames.
0090 * - __u32
0091 - ``which``
0092 - Frame intervals to be enumerated, from enum
0093 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
0094 * - __u32
0095 - ``reserved``\ [8]
0096 - Reserved for future extensions. Applications and drivers must set
0097 the array to zero.
0098
0099 Return Value
0100 ============
0101
0102 On success 0 is returned, on error -1 and the ``errno`` variable is set
0103 appropriately. The generic error codes are described at the
0104 :ref:`Generic Error Codes <gen-errors>` chapter.
0105
0106 EINVAL
0107 The struct
0108 :c:type:`v4l2_subdev_frame_interval_enum`
0109 ``pad`` references a non-existing pad, one of the ``code``,
0110 ``width`` or ``height`` fields are invalid for the given pad or the
0111 ``index`` field is out of bounds.
