Documentation/media/uapi/v4l/vidioc-enuminput.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUMINPUT:
   4
   5 **********************
   6 ioctl VIDIOC_ENUMINPUT
   7 **********************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_ENUMINPUT - Enumerate video inputs
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp )
  19     :name: VIDIOC_ENUMINPUT
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  27
  28 ``argp``
  29
  30
  31 Description
  32 ===========
  33
  34 To query the attributes of a video input applications initialize the
  35 ``index`` field of struct :c:type:`v4l2_input` and call the
  36 :ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
  37 fill the rest of the structure or return an ``EINVAL`` error code when the
  38 index is out of bounds. To enumerate all inputs applications shall begin
  39 at index zero, incrementing by one until the driver returns ``EINVAL``.
  40
  41
  42 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  43
  44 .. c:type:: v4l2_input
  45
  46 .. flat-table:: struct v4l2_input
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 1 2
  50
  51     * - __u32
  52       - ``index``
  53       - Identifies the input, set by the application.
  54     * - __u8
  55       - ``name``\ [32]
  56       - Name of the video input, a NUL-terminated ASCII string, for
  57         example: "Vin (Composite 2)". This information is intended for the
  58         user, preferably the connector label on the device itself.
  59     * - __u32
  60       - ``type``
  61       - Type of the input, see :ref:`input-type`.
  62     * - __u32
  63       - ``audioset``
  64       - Drivers can enumerate up to 32 video and audio inputs. This field
  65         shows which audio inputs were selectable as audio source if this
  66         was the currently selected video input. It is a bit mask. The LSB
  67         corresponds to audio input 0, the MSB to input 31. Any number of
  68         bits can be set, or none.
  69
  70         When the driver does not enumerate audio inputs no bits must be
  71         set. Applications shall not interpret this as lack of audio
  72         support. Some drivers automatically select audio sources and do
  73         not enumerate them since there is no choice anyway.
  74
  75         For details on audio inputs and how to select the current input
  76         see :ref:`audio`.
  77     * - __u32
  78       - ``tuner``
  79       - Capture devices can have zero or more tuners (RF demodulators).
  80         When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
  81         RF connector and this field identifies the tuner. It corresponds
  82         to struct :c:type:`v4l2_tuner` field ``index``. For
  83         details on tuners see :ref:`tuner`.
  84     * - :ref:`v4l2_std_id <v4l2-std-id>`
  85       - ``std``
  86       - Every video input supports one or more different video standards.
  87         This field is a set of all supported standards. For details on
  88         video standards and how to switch see :ref:`standard`.
  89     * - __u32
  90       - ``status``
  91       - This field provides status information about the input. See
  92         :ref:`input-status` for flags. With the exception of the sensor
  93         orientation bits ``status`` is only valid when this is the current
  94         input.
  95     * - __u32
  96       - ``capabilities``
  97       - This field provides capabilities for the input. See
  98         :ref:`input-capabilities` for flags.
  99     * - __u32
 100       - ``reserved``\ [3]
 101       - Reserved for future extensions. Drivers must set the array to
 102         zero.
 103
 104
 105
 106 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 107
 108 .. _input-type:
 109
 110 .. flat-table:: Input Types
 111     :header-rows:  0
 112     :stub-columns: 0
 113     :widths:       3 1 4
 114
 115     * - ``V4L2_INPUT_TYPE_TUNER``
 116       - 1
 117       - This input uses a tuner (RF demodulator).
 118     * - ``V4L2_INPUT_TYPE_CAMERA``
 119       - 2
 120       - Any non-tuner video input, for example Composite Video,
 121         S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
 122         today we would have called it ``_TYPE_VIDEO``.
 123     * - ``V4L2_INPUT_TYPE_TOUCH``
 124       - 3
 125       - This input is a touch device for capturing raw touch data.
 126
 127
 128
 129 .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
 130
 131 .. _input-status:
 132
 133 .. flat-table:: Input Status Flags
 134     :header-rows:  0
 135     :stub-columns: 0
 136
 137     * - :cspan:`2` General
 138     * - ``V4L2_IN_ST_NO_POWER``
 139       - 0x00000001
 140       - Attached device is off.
 141     * - ``V4L2_IN_ST_NO_SIGNAL``
 142       - 0x00000002
 143       -
 144     * - ``V4L2_IN_ST_NO_COLOR``
 145       - 0x00000004
 146       - The hardware supports color decoding, but does not detect color
 147         modulation in the signal.
 148     * - :cspan:`2` Sensor Orientation
 149     * - ``V4L2_IN_ST_HFLIP``
 150       - 0x00000010
 151       - The input is connected to a device that produces a signal that is
 152         flipped horizontally and does not correct this before passing the
 153         signal to userspace.
 154     * - ``V4L2_IN_ST_VFLIP``
 155       - 0x00000020
 156       - The input is connected to a device that produces a signal that is
 157         flipped vertically and does not correct this before passing the
 158         signal to userspace.
 159         .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
 160     * - :cspan:`2` Analog Video
 161     * - ``V4L2_IN_ST_NO_H_LOCK``
 162       - 0x00000100
 163       - No horizontal sync lock.
 164     * - ``V4L2_IN_ST_COLOR_KILL``
 165       - 0x00000200
 166       - A color killer circuit automatically disables color decoding when
 167         it detects no color modulation. When this flag is set the color
 168         killer is enabled *and* has shut off color decoding.
 169     * - ``V4L2_IN_ST_NO_V_LOCK``
 170       - 0x00000400
 171       - No vertical sync lock.
 172     * - ``V4L2_IN_ST_NO_STD_LOCK``
 173       - 0x00000800
 174       - No standard format lock in case of auto-detection format
 175         by the component.
 176     * - :cspan:`2` Digital Video
 177     * - ``V4L2_IN_ST_NO_SYNC``
 178       - 0x00010000
 179       - No synchronization lock.
 180     * - ``V4L2_IN_ST_NO_EQU``
 181       - 0x00020000
 182       - No equalizer lock.
 183     * - ``V4L2_IN_ST_NO_CARRIER``
 184       - 0x00040000
 185       - Carrier recovery failed.
 186     * - :cspan:`2` VCR and Set-Top Box
 187     * - ``V4L2_IN_ST_MACROVISION``
 188       - 0x01000000
 189       - Macrovision is an analog copy prevention system mangling the video
 190         signal to confuse video recorders. When this flag is set
 191         Macrovision has been detected.
 192     * - ``V4L2_IN_ST_NO_ACCESS``
 193       - 0x02000000
 194       - Conditional access denied.
 195     * - ``V4L2_IN_ST_VTR``
 196       - 0x04000000
 197       - VTR time constant. [?]
 198
 199
 200
 201 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 202
 203 .. _input-capabilities:
 204
 205 .. flat-table:: Input capabilities
 206     :header-rows:  0
 207     :stub-columns: 0
 208     :widths:       3 1 4
 209
 210     * - ``V4L2_IN_CAP_DV_TIMINGS``
 211       - 0x00000002
 212       - This input supports setting video timings by using
 213         ``VIDIOC_S_DV_TIMINGS``.
 214     * - ``V4L2_IN_CAP_STD``
 215       - 0x00000004
 216       - This input supports setting the TV standard by using
 217         ``VIDIOC_S_STD``.
 218     * - ``V4L2_IN_CAP_NATIVE_SIZE``
 219       - 0x00000008
 220       - This input supports setting the native size using the
 221         ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 222         :ref:`v4l2-selections-common`.
 223
 224
 225 Return Value
 226 ============
 227
 228 On success 0 is returned, on error -1 and the ``errno`` variable is set
 229 appropriately. The generic error codes are described at the
 230 :ref:`Generic Error Codes <gen-errors>` chapter.
 231
 232 EINVAL
 233     The struct :c:type:`v4l2_input` ``index`` is out of
 234     bounds.