vidioc-enum-dv-timings.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _VIDIOC_ENUM_DV_TIMINGS:
  5
  6***********************************************************
  7ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
  8***********************************************************
  9
 10Name
 11====
 12
 13VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
 14
 15Synopsis
 16========
 17
 18.. c:macro:: VIDIOC_ENUM_DV_TIMINGS
 19
 20``int ioctl(int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp)``
 21
 22.. c:macro:: VIDIOC_SUBDEV_ENUM_DV_TIMINGS
 23
 24``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *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_enum_dv_timings`.
 34
 35Description
 36===========
 37
 38While some DV receivers or transmitters support a wide range of timings,
 39others support only a limited number of timings. With this ioctl
 40applications can enumerate a list of known supported timings. Call
 41:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
 42also supports other standards or even custom timings that are not in
 43this list.
 44
 45To query the available timings, applications initialize the ``index``
 46field, set the ``pad`` field to 0, zero the reserved array of struct
 47:c:type:`v4l2_enum_dv_timings` and call the
 48``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
 49structure. Drivers fill the rest of the structure or return an ``EINVAL``
 50error code when the index is out of bounds. To enumerate all supported
 51DV timings, applications shall begin at index zero, incrementing by one
 52until the driver returns ``EINVAL``.
 53
 54.. note::
 55
 56   Drivers may enumerate a different set of DV timings after
 57   switching the video input or output.
 58
 59When implemented by the driver DV timings of subdevices can be queried
 60by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
 61subdevice node. The DV timings are specific to inputs (for DV receivers)
 62or outputs (for DV transmitters), applications must specify the desired
 63pad number in the struct
 64:c:type:`v4l2_enum_dv_timings` ``pad`` field.
 65Attempts to enumerate timings on a pad that doesn't support them will
 66return an ``EINVAL`` error code.
 67
 68.. c:type:: v4l2_enum_dv_timings
 69
 70.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
 71
 72.. flat-table:: struct v4l2_enum_dv_timings
 73    :header-rows:  0
 74    :stub-columns: 0
 75    :widths:       1 1 2
 76
 77    * - __u32
 78      - ``index``
 79      - Number of the DV timings, set by the application.
 80    * - __u32
 81      - ``pad``
 82      - Pad number as reported by the media controller API. This field is
 83	only used when operating on a subdevice node. When operating on a
 84	video node applications must set this field to zero.
 85    * - __u32
 86      - ``reserved``\ [2]
 87      - Reserved for future extensions. Drivers and applications must set
 88	the array to zero.
 89    * - struct :c:type:`v4l2_dv_timings`
 90      - ``timings``
 91      - The timings.
 92
 93Return Value
 94============
 95
 96On success 0 is returned, on error -1 and the ``errno`` variable is set
 97appropriately. The generic error codes are described at the
 98:ref:`Generic Error Codes <gen-errors>` chapter.
 99
100EINVAL
101    The struct :c:type:`v4l2_enum_dv_timings`
102    ``index`` is out of bounds or the ``pad`` number is invalid.
103
104ENODATA
105    Digital video presets are not supported for this input or output.