1 .. -*- coding: utf-8; mode: rst -*-
3 .. _VIDIOC_ENUM_FRAMEINTERVALS:
5 ********************************
6 ioctl VIDIOC_ENUM_FRAMEINTERVALS
7 ********************************
12 VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp )
25 File descriptor returned by :ref:`open() <func-open>`.
28 VIDIOC_ENUM_FRAMEINTERVALS
31 Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>`
32 structure that contains a pixel format and size and receives a frame
39 This ioctl allows applications to enumerate all frame intervals that the
40 device supports for the given pixel format and frame size.
42 The supported pixel formats and frame sizes can be obtained by using the
43 :ref:`VIDIOC_ENUM_FMT` and
44 :ref:`VIDIOC_ENUM_FRAMESIZES` functions.
46 The return value and the content of the ``v4l2_frmivalenum.type`` field
47 depend on the type of frame intervals the device supports. Here are the
48 semantics of the function for the different cases:
50 - **Discrete:** The function returns success if the given index value
51 (zero-based) is valid. The application should increase the index by
52 one for each call until ``EINVAL`` is returned. The
53 `v4l2_frmivalenum.type` field is set to
54 `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
55 the `discrete` member is valid.
57 - **Step-wise:** The function returns success if the given index value
58 is zero and ``EINVAL`` for any other index value. The
59 ``v4l2_frmivalenum.type`` field is set to
60 ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
61 ``stepwise`` member is valid.
63 - **Continuous:** This is a special case of the step-wise type above.
64 The function returns success if the given index value is zero and
65 ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
66 field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
67 the union only the ``stepwise`` member is valid and the ``step``
70 When the application calls the function with index zero, it must check
71 the ``type`` field to determine the type of frame interval enumeration
72 the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
73 does it make sense to increase the index value to receive more frame
78 The order in which the frame intervals are returned has no
79 special meaning. In particular does it not say anything about potential
80 default frame intervals.
82 Applications can assume that the enumeration data does not change
83 without any interaction from the application itself. This means that the
84 enumeration data is consistent if the application does not perform any
85 other ioctl calls while it runs the frame interval enumeration.
89 **Frame intervals and frame rates:** The V4L2 API uses frame
90 intervals instead of frame rates. Given the frame interval the frame
91 rate can be computed as follows:
95 frame_rate = 1 / frame_interval
101 In the structs below, *IN* denotes a value that has to be filled in by
102 the application, *OUT* denotes values that the driver fills in. The
103 application should zero out all members except for the *IN* fields.
106 .. _v4l2-frmival-stepwise:
108 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
110 .. flat-table:: struct v4l2_frmival_stepwise
118 - struct :ref:`v4l2_fract <v4l2-fract>`
122 - Minimum frame interval [s].
126 - struct :ref:`v4l2_fract <v4l2-fract>`
130 - Maximum frame interval [s].
134 - struct :ref:`v4l2_fract <v4l2-fract>`
138 - Frame interval step size [s].
142 .. _v4l2-frmivalenum:
144 .. flat-table:: struct v4l2_frmivalenum
156 - IN: Index of the given frame interval in the enumeration.
165 - IN: Pixel format for which the frame intervals are enumerated.
174 - IN: Frame width for which the frame intervals are enumerated.
183 - IN: Frame height for which the frame intervals are enumerated.
192 - OUT: Frame interval type the device supports.
200 - OUT: Frame interval with the given index.
205 - struct :ref:`v4l2_fract <v4l2-fract>`
209 - Frame interval [s].
214 - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>`
227 - Reserved space for future use. Must be zeroed by drivers and
236 .. _v4l2-frmivaltypes:
238 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
240 .. flat-table:: enum v4l2_frmivaltypes
248 - ``V4L2_FRMIVAL_TYPE_DISCRETE``
252 - Discrete frame interval.
256 - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
260 - Continuous frame interval.
264 - ``V4L2_FRMIVAL_TYPE_STEPWISE``
268 - Step-wise defined frame interval.
274 On success 0 is returned, on error -1 and the ``errno`` variable is set
275 appropriately. The generic error codes are described at the
276 :ref:`Generic Error Codes <gen-errors>` chapter.