1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: 4 5*************************************** 6ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL 7*************************************** 8 9Name 10==== 11 12VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp ) 19 :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL 20 21 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :ref:`open() <func-open>`. 27 28``argp`` 29 Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`. 30 31 32Description 33=========== 34 35This ioctl lets applications enumerate available frame intervals on a 36given sub-device pad. Frame intervals only makes sense for sub-devices 37that can control the frame period on their own. This includes, for 38instance, image sensors and TV tuners. 39 40For the common use case of image sensors, the frame intervals available 41on the sub-device output pad depend on the frame format and size on the 42same pad. Applications must thus specify the desired format and size 43when enumerating frame intervals. 44 45To enumerate frame intervals applications initialize the ``index``, 46``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct 47:c:type:`v4l2_subdev_frame_interval_enum` 48and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer 49to this structure. Drivers fill the rest of the structure or return an 50EINVAL error code if one of the input fields is invalid. All frame 51intervals are enumerable by beginning at index zero and incrementing by 52one until ``EINVAL`` is returned. 53 54Available frame intervals may depend on the current 'try' formats at 55other pads of the sub-device, as well as on the current active links. 56See :ref:`VIDIOC_SUBDEV_G_FMT` for more 57information about the try formats. 58 59Sub-devices that support the frame interval enumeration ioctl should 60implemented it on a single pad only. Its behaviour when supported on 61multiple pads of the same sub-device is not defined. 62 63.. c:type:: v4l2_subdev_frame_interval_enum 64 65.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 66 67.. flat-table:: struct v4l2_subdev_frame_interval_enum 68 :header-rows: 0 69 :stub-columns: 0 70 :widths: 1 1 2 71 72 * - __u32 73 - ``index`` 74 - Number of the format in the enumeration, set by the application. 75 * - __u32 76 - ``pad`` 77 - Pad number as reported by the media controller API. 78 * - __u32 79 - ``code`` 80 - The media bus format code, as defined in 81 :ref:`v4l2-mbus-format`. 82 * - __u32 83 - ``width`` 84 - Frame width, in pixels. 85 * - __u32 86 - ``height`` 87 - Frame height, in pixels. 88 * - struct :c:type:`v4l2_fract` 89 - ``interval`` 90 - Period, in seconds, between consecutive video frames. 91 * - __u32 92 - ``which`` 93 - Frame intervals to be enumerated, from enum 94 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. 95 * - __u32 96 - ``reserved``\ [8] 97 - Reserved for future extensions. Applications and drivers must set 98 the array to zero. 99 100 101Return Value 102============ 103 104On success 0 is returned, on error -1 and the ``errno`` variable is set 105appropriately. The generic error codes are described at the 106:ref:`Generic Error Codes <gen-errors>` chapter. 107 108EINVAL 109 The struct 110 :c:type:`v4l2_subdev_frame_interval_enum` 111 ``pad`` references a non-existing pad, one of the ``code``, 112 ``width`` or ``height`` fields are invalid for the given pad or the 113 ``index`` field is out of bounds. 114