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` ioctl 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
  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 :c:type:`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 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 152
 153 .. _input-type:
 154
 155 .. flat-table:: Input Types
 156     :header-rows:  0
 157     :stub-columns: 0
 158     :widths:       3 1 4
 159
 160
 161     -  .. row 1
 162
 163        -  ``V4L2_INPUT_TYPE_TUNER``
 164
 165        -  1
 166
 167        -  This input uses a tuner (RF demodulator).
 168
 169     -  .. row 2
 170
 171        -  ``V4L2_INPUT_TYPE_CAMERA``
 172
 173        -  2
 174
 175        -  Analog baseband input, for example CVBS / Composite Video,
 176           S-Video, RGB.
 177
 178     -  .. row 3
 179
 180        -  ``V4L2_INPUT_TYPE_TOUCH``
 181
 182        -  3
 183
 184        -  This input is a touch device for capturing raw touch data.
 185
 186
 187
 188 .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
 189
 190 .. _input-status:
 191
 192 .. flat-table:: Input Status Flags
 193     :header-rows:  0
 194     :stub-columns: 0
 195
 196
 197     -  .. row 1
 198
 199        -  :cspan:`2` General
 200
 201     -  .. row 2
 202
 203        -  ``V4L2_IN_ST_NO_POWER``
 204
 205        -  0x00000001
 206
 207        -  Attached device is off.
 208
 209     -  .. row 3
 210
 211        -  ``V4L2_IN_ST_NO_SIGNAL``
 212
 213        -  0x00000002
 214
 215        -
 216
 217     -  .. row 4
 218
 219        -  ``V4L2_IN_ST_NO_COLOR``
 220
 221        -  0x00000004
 222
 223        -  The hardware supports color decoding, but does not detect color
 224           modulation in the signal.
 225
 226     -  .. row 5
 227
 228        -  :cspan:`2` Sensor Orientation
 229
 230     -  .. row 6
 231
 232        -  ``V4L2_IN_ST_HFLIP``
 233
 234        -  0x00000010
 235
 236        -  The input is connected to a device that produces a signal that is
 237           flipped horizontally and does not correct this before passing the
 238           signal to userspace.
 239
 240     -  .. row 7
 241
 242        -  ``V4L2_IN_ST_VFLIP``
 243
 244        -  0x00000020
 245
 246        -  The input is connected to a device that produces a signal that is
 247           flipped vertically and does not correct this before passing the
 248           signal to userspace.
 249           .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
 250
 251     -  .. row 8
 252
 253        -  :cspan:`2` Analog Video
 254
 255     -  .. row 9
 256
 257        -  ``V4L2_IN_ST_NO_H_LOCK``
 258
 259        -  0x00000100
 260
 261        -  No horizontal sync lock.
 262
 263     -  .. row 10
 264
 265        -  ``V4L2_IN_ST_COLOR_KILL``
 266
 267        -  0x00000200
 268
 269        -  A color killer circuit automatically disables color decoding when
 270           it detects no color modulation. When this flag is set the color
 271           killer is enabled *and* has shut off color decoding.
 272
 273     -  .. row 11
 274
 275        -  ``V4L2_IN_ST_NO_V_LOCK``
 276
 277        -  0x00000400
 278
 279        -  No vertical sync lock.
 280
 281     -  .. row 12
 282
 283        -  ``V4L2_IN_ST_NO_STD_LOCK``
 284
 285        -  0x00000800
 286
 287        -  No standard format lock in case of auto-detection format
 288           by the component.
 289
 290     -  .. row 13
 291
 292        -  :cspan:`2` Digital Video
 293
 294     -  .. row 14
 295
 296        -  ``V4L2_IN_ST_NO_SYNC``
 297
 298        -  0x00010000
 299
 300        -  No synchronization lock.
 301
 302     -  .. row 15
 303
 304        -  ``V4L2_IN_ST_NO_EQU``
 305
 306        -  0x00020000
 307
 308        -  No equalizer lock.
 309
 310     -  .. row 16
 311
 312        -  ``V4L2_IN_ST_NO_CARRIER``
 313
 314        -  0x00040000
 315
 316        -  Carrier recovery failed.
 317
 318     -  .. row 17
 319
 320        -  :cspan:`2` VCR and Set-Top Box
 321
 322     -  .. row 18
 323
 324        -  ``V4L2_IN_ST_MACROVISION``
 325
 326        -  0x01000000
 327
 328        -  Macrovision is an analog copy prevention system mangling the video
 329           signal to confuse video recorders. When this flag is set
 330           Macrovision has been detected.
 331
 332     -  .. row 19
 333
 334        -  ``V4L2_IN_ST_NO_ACCESS``
 335
 336        -  0x02000000
 337
 338        -  Conditional access denied.
 339
 340     -  .. row 20
 341
 342        -  ``V4L2_IN_ST_VTR``
 343
 344        -  0x04000000
 345
 346        -  VTR time constant. [?]
 347
 348
 349
 350 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 351
 352 .. _input-capabilities:
 353
 354 .. flat-table:: Input capabilities
 355     :header-rows:  0
 356     :stub-columns: 0
 357     :widths:       3 1 4
 358
 359
 360     -  .. row 1
 361
 362        -  ``V4L2_IN_CAP_DV_TIMINGS``
 363
 364        -  0x00000002
 365
 366        -  This input supports setting video timings by using
 367           VIDIOC_S_DV_TIMINGS.
 368
 369     -  .. row 2
 370
 371        -  ``V4L2_IN_CAP_STD``
 372
 373        -  0x00000004
 374
 375        -  This input supports setting the TV standard by using
 376           VIDIOC_S_STD.
 377
 378     -  .. row 3
 379
 380        -  ``V4L2_IN_CAP_NATIVE_SIZE``
 381
 382        -  0x00000008
 383
 384        -  This input supports setting the native size using the
 385           ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 386           :ref:`v4l2-selections-common`.
 387
 388
 389 Return Value
 390 ============
 391
 392 On success 0 is returned, on error -1 and the ``errno`` variable is set
 393 appropriately. The generic error codes are described at the
 394 :ref:`Generic Error Codes <gen-errors>` chapter.
 395
 396 EINVAL
 397     The struct :c:type:`v4l2_input` ``index`` is out of
 398     bounds.