Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
   4
   5 ***************************************
   6 ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
   7 ***************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
  13
  14
  15 Synopsis
  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
  22 Arguments
  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
  32 Description
  33 ===========
  34
  35 This ioctl lets applications enumerate available frame intervals on a
  36 given sub-device pad. Frame intervals only makes sense for sub-devices
  37 that can control the frame period on their own. This includes, for
  38 instance, image sensors and TV tuners.
  39
  40 For the common use case of image sensors, the frame intervals available
  41 on the sub-device output pad depend on the frame format and size on the
  42 same pad. Applications must thus specify the desired format and size
  43 when enumerating frame intervals.
  44
  45 To 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`
  48 and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
  49 to this structure. Drivers fill the rest of the structure or return an
  50 EINVAL error code if one of the input fields is invalid. All frame
  51 intervals are enumerable by beginning at index zero and incrementing by
  52 one until ``EINVAL`` is returned.
  53
  54 Available frame intervals may depend on the current 'try' formats at
  55 other pads of the sub-device, as well as on the current active links.
  56 See :ref:`VIDIOC_SUBDEV_G_FMT` for more
  57 information about the try formats.
  58
  59 Sub-devices that support the frame interval enumeration ioctl should
  60 implemented it on a single pad only. Its behaviour when supported on
  61 multiple 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
 101 Return Value
 102 ============
 103
 104 On success 0 is returned, on error -1 and the ``errno`` variable is set
 105 appropriately. The generic error codes are described at the
 106 :ref:`Generic Error Codes <gen-errors>` chapter.
 107
 108 EINVAL
 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.