vidioc-subdev-g-frame-interval.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
  5
  6********************************************************************
  7ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
  8********************************************************************
  9
 10Name
 11====
 12
 13VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
 14
 15Synopsis
 16========
 17
 18.. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL
 19
 20``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
 21
 22.. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL
 23
 24``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
 25
 26Arguments
 27=========
 28
 29``fd``
 30    File descriptor returned by :c:func:`open()`.
 31
 32``argp``
 33    Pointer to struct :c:type:`v4l2_subdev_frame_interval`.
 34
 35Description
 36===========
 37
 38These ioctls are used to get and set the frame interval at specific
 39subdev pads in the image pipeline. The frame interval only makes sense
 40for sub-devices that can control the frame period on their own. This
 41includes, for instance, image sensors and TV tuners. Sub-devices that
 42don't support frame intervals must not implement these ioctls.
 43
 44To retrieve the current frame interval applications set the ``pad``
 45field of a struct
 46:c:type:`v4l2_subdev_frame_interval` to
 47the desired pad number as reported by the media controller API. When
 48they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
 49this structure the driver fills the members of the ``interval`` field.
 50
 51To change the current frame interval applications set both the ``pad``
 52field and all members of the ``interval`` field. When they call the
 53``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
 54structure the driver verifies the requested interval, adjusts it based
 55on the hardware capabilities and configures the device. Upon return the
 56struct
 57:c:type:`v4l2_subdev_frame_interval`
 58contains the current frame interval as would be returned by a
 59``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
 60
 61If the subdev device node has been registered in read-only mode, calls to
 62``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` are only valid if the ``which`` field is set
 63to ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
 64variable is set to ``-EPERM``.
 65
 66Drivers must not return an error solely because the requested interval
 67doesn't match the device capabilities. They must instead modify the
 68interval to match what the hardware can provide. The modified interval
 69should be as close as possible to the original request.
 70
 71Changing the frame interval shall never change the format. Changing the
 72format, on the other hand, may change the frame interval.
 73
 74Sub-devices that support the frame interval ioctls should implement them
 75on a single pad only. Their behaviour when supported on multiple pads of
 76the same sub-device is not defined.
 77
 78.. c:type:: v4l2_subdev_frame_interval
 79
 80.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
 81
 82.. flat-table:: struct v4l2_subdev_frame_interval
 83    :header-rows:  0
 84    :stub-columns: 0
 85    :widths:       1 1 2
 86
 87    * - __u32
 88      - ``pad``
 89      - Pad number as reported by the media controller API.
 90    * - struct :c:type:`v4l2_fract`
 91      - ``interval``
 92      - Period, in seconds, between consecutive video frames.
 93    * - __u32
 94      - ``stream``
 95      - Stream identifier.
 96    * - __u32
 97      - ``which``
 98      - Active or try frame interval, from enum
 99	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
100    * - __u32
101      - ``reserved``\ [7]
102      - Reserved for future extensions. Applications and drivers must set
103	the array to zero.
104
105Return Value
106============
107
108On success 0 is returned, on error -1 and the ``errno`` variable is set
109appropriately. The generic error codes are described at the
110:ref:`Generic Error Codes <gen-errors>` chapter.
111
112EBUSY
113    The frame interval can't be changed because the pad is currently
114    busy. This can be caused, for instance, by an active video stream on
115    the pad. The ioctl must not be retried without performing another
116    action to fix the problem first. Only returned by
117    ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
118
119EINVAL
120    The struct :c:type:`v4l2_subdev_frame_interval` ``pad`` references a
121    non-existing pad, the ``which`` field has an unsupported value, or the pad
122    doesn't support frame intervals.
123
124EPERM
125    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
126    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.