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 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_ENUMINPUT
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 To query the attributes of a video input applications initialize the
  37 ``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
  38 :ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
  39 fill the rest of the structure or return an ``EINVAL`` error code when the
  40 index is out of bounds. To enumerate all inputs applications shall begin
  41 at index zero, incrementing by one until the driver returns ``EINVAL``.
  42
  43
  44 .. _v4l2-input:
  45
  46 .. flat-table:: struct v4l2_input
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 1 2
  50
  51
  52     -  .. row 1
  53
  54        -  __u32
  55
  56        -  ``index``
  57
  58        -  Identifies the input, set by the application.
  59
  60     -  .. row 2
  61
  62        -  __u8
  63
  64        -  ``name``\ [32]
  65
  66        -  Name of the video input, a NUL-terminated ASCII string, for
  67           example: "Vin (Composite 2)". This information is intended for the
  68           user, preferably the connector label on the device itself.
  69
  70     -  .. row 3
  71
  72        -  __u32
  73
  74        -  ``type``
  75
  76        -  Type of the input, see :ref:`input-type`.
  77
  78     -  .. row 4
  79
  80        -  __u32
  81
  82        -  ``audioset``
  83
  84        -  Drivers can enumerate up to 32 video and audio inputs. This field
  85           shows which audio inputs were selectable as audio source if this
  86           was the currently selected video input. It is a bit mask. The LSB
  87           corresponds to audio input 0, the MSB to input 31. Any number of
  88           bits can be set, or none.
  89
  90           When the driver does not enumerate audio inputs no bits must be
  91           set. Applications shall not interpret this as lack of audio
  92           support. Some drivers automatically select audio sources and do
  93           not enumerate them since there is no choice anyway.
  94
  95           For details on audio inputs and how to select the current input
  96           see :ref:`audio`.
  97
  98     -  .. row 5
  99
 100        -  __u32
 101
 102        -  ``tuner``
 103
 104        -  Capture devices can have zero or more tuners (RF demodulators).
 105           When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
 106           RF connector and this field identifies the tuner. It corresponds
 107           to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
 108           details on tuners see :ref:`tuner`.
 109
 110     -  .. row 6
 111
 112        -  :ref:`v4l2_std_id <v4l2-std-id>`
 113
 114        -  ``std``
 115
 116        -  Every video input supports one or more different video standards.
 117           This field is a set of all supported standards. For details on
 118           video standards and how to switch see :ref:`standard`.
 119
 120     -  .. row 7
 121
 122        -  __u32
 123
 124        -  ``status``
 125
 126        -  This field provides status information about the input. See
 127           :ref:`input-status` for flags. With the exception of the sensor
 128           orientation bits ``status`` is only valid when this is the current
 129           input.
 130
 131     -  .. row 8
 132
 133        -  __u32
 134
 135        -  ``capabilities``
 136
 137        -  This field provides capabilities for the input. See
 138           :ref:`input-capabilities` for flags.
 139
 140     -  .. row 9
 141
 142        -  __u32
 143
 144        -  ``reserved``\ [3]
 145
 146        -  Reserved for future extensions. Drivers must set the array to
 147           zero.
 148
 149
 150
 151 .. _input-type:
 152
 153 .. flat-table:: Input Types
 154     :header-rows:  0
 155     :stub-columns: 0
 156     :widths:       3 1 4
 157
 158
 159     -  .. row 1
 160
 161        -  ``V4L2_INPUT_TYPE_TUNER``
 162
 163        -  1
 164
 165        -  This input uses a tuner (RF demodulator).
 166
 167     -  .. row 2
 168
 169        -  ``V4L2_INPUT_TYPE_CAMERA``
 170
 171        -  2
 172
 173        -  Analog baseband input, for example CVBS / Composite Video,
 174           S-Video, RGB.
 175
 176
 177
 178 .. _input-status:
 179
 180 .. flat-table:: Input Status Flags
 181     :header-rows:  0
 182     :stub-columns: 0
 183
 184
 185     -  .. row 1
 186
 187        -  :cspan:`2` General
 188
 189     -  .. row 2
 190
 191        -  ``V4L2_IN_ST_NO_POWER``
 192
 193        -  0x00000001
 194
 195        -  Attached device is off.
 196
 197     -  .. row 3
 198
 199        -  ``V4L2_IN_ST_NO_SIGNAL``
 200
 201        -  0x00000002
 202
 203        -
 204
 205     -  .. row 4
 206
 207        -  ``V4L2_IN_ST_NO_COLOR``
 208
 209        -  0x00000004
 210
 211        -  The hardware supports color decoding, but does not detect color
 212           modulation in the signal.
 213
 214     -  .. row 5
 215
 216        -  :cspan:`2` Sensor Orientation
 217
 218     -  .. row 6
 219
 220        -  ``V4L2_IN_ST_HFLIP``
 221
 222        -  0x00000010
 223
 224        -  The input is connected to a device that produces a signal that is
 225           flipped horizontally and does not correct this before passing the
 226           signal to userspace.
 227
 228     -  .. row 7
 229
 230        -  ``V4L2_IN_ST_VFLIP``
 231
 232        -  0x00000020
 233
 234        -  The input is connected to a device that produces a signal that is
 235           flipped vertically and does not correct this before passing the
 236           signal to userspace.
 237           .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
 238
 239     -  .. row 8
 240
 241        -  :cspan:`2` Analog Video
 242
 243     -  .. row 9
 244
 245        -  ``V4L2_IN_ST_NO_H_LOCK``
 246
 247        -  0x00000100
 248
 249        -  No horizontal sync lock.
 250
 251     -  .. row 10
 252
 253        -  ``V4L2_IN_ST_COLOR_KILL``
 254
 255        -  0x00000200
 256
 257        -  A color killer circuit automatically disables color decoding when
 258           it detects no color modulation. When this flag is set the color
 259           killer is enabled *and* has shut off color decoding.
 260
 261     -  .. row 11
 262
 263        -  :cspan:`2` Digital Video
 264
 265     -  .. row 12
 266
 267        -  ``V4L2_IN_ST_NO_SYNC``
 268
 269        -  0x00010000
 270
 271        -  No synchronization lock.
 272
 273     -  .. row 13
 274
 275        -  ``V4L2_IN_ST_NO_EQU``
 276
 277        -  0x00020000
 278
 279        -  No equalizer lock.
 280
 281     -  .. row 14
 282
 283        -  ``V4L2_IN_ST_NO_CARRIER``
 284
 285        -  0x00040000
 286
 287        -  Carrier recovery failed.
 288
 289     -  .. row 15
 290
 291        -  :cspan:`2` VCR and Set-Top Box
 292
 293     -  .. row 16
 294
 295        -  ``V4L2_IN_ST_MACROVISION``
 296
 297        -  0x01000000
 298
 299        -  Macrovision is an analog copy prevention system mangling the video
 300           signal to confuse video recorders. When this flag is set
 301           Macrovision has been detected.
 302
 303     -  .. row 17
 304
 305        -  ``V4L2_IN_ST_NO_ACCESS``
 306
 307        -  0x02000000
 308
 309        -  Conditional access denied.
 310
 311     -  .. row 18
 312
 313        -  ``V4L2_IN_ST_VTR``
 314
 315        -  0x04000000
 316
 317        -  VTR time constant. [?]
 318
 319
 320
 321 .. _input-capabilities:
 322
 323 .. flat-table:: Input capabilities
 324     :header-rows:  0
 325     :stub-columns: 0
 326     :widths:       3 1 4
 327
 328
 329     -  .. row 1
 330
 331        -  ``V4L2_IN_CAP_DV_TIMINGS``
 332
 333        -  0x00000002
 334
 335        -  This input supports setting video timings by using
 336           VIDIOC_S_DV_TIMINGS.
 337
 338     -  .. row 2
 339
 340        -  ``V4L2_IN_CAP_STD``
 341
 342        -  0x00000004
 343
 344        -  This input supports setting the TV standard by using
 345           VIDIOC_S_STD.
 346
 347     -  .. row 3
 348
 349        -  ``V4L2_IN_CAP_NATIVE_SIZE``
 350
 351        -  0x00000008
 352
 353        -  This input supports setting the native size using the
 354           ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 355           :ref:`v4l2-selections-common`.
 356
 357
 358 Return Value
 359 ============
 360
 361 On success 0 is returned, on error -1 and the ``errno`` variable is set
 362 appropriately. The generic error codes are described at the
 363 :ref:`Generic Error Codes <gen-errors>` chapter.
 364
 365 EINVAL
 366     The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
 367     bounds.