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        -  :cspan:`2` Digital Video
 276
 277     -  .. row 12
 278
 279        -  ``V4L2_IN_ST_NO_SYNC``
 280
 281        -  0x00010000
 282
 283        -  No synchronization lock.
 284
 285     -  .. row 13
 286
 287        -  ``V4L2_IN_ST_NO_EQU``
 288
 289        -  0x00020000
 290
 291        -  No equalizer lock.
 292
 293     -  .. row 14
 294
 295        -  ``V4L2_IN_ST_NO_CARRIER``
 296
 297        -  0x00040000
 298
 299        -  Carrier recovery failed.
 300
 301     -  .. row 15
 302
 303        -  :cspan:`2` VCR and Set-Top Box
 304
 305     -  .. row 16
 306
 307        -  ``V4L2_IN_ST_MACROVISION``
 308
 309        -  0x01000000
 310
 311        -  Macrovision is an analog copy prevention system mangling the video
 312           signal to confuse video recorders. When this flag is set
 313           Macrovision has been detected.
 314
 315     -  .. row 17
 316
 317        -  ``V4L2_IN_ST_NO_ACCESS``
 318
 319        -  0x02000000
 320
 321        -  Conditional access denied.
 322
 323     -  .. row 18
 324
 325        -  ``V4L2_IN_ST_VTR``
 326
 327        -  0x04000000
 328
 329        -  VTR time constant. [?]
 330
 331
 332
 333 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 334
 335 .. _input-capabilities:
 336
 337 .. flat-table:: Input capabilities
 338     :header-rows:  0
 339     :stub-columns: 0
 340     :widths:       3 1 4
 341
 342
 343     -  .. row 1
 344
 345        -  ``V4L2_IN_CAP_DV_TIMINGS``
 346
 347        -  0x00000002
 348
 349        -  This input supports setting video timings by using
 350           VIDIOC_S_DV_TIMINGS.
 351
 352     -  .. row 2
 353
 354        -  ``V4L2_IN_CAP_STD``
 355
 356        -  0x00000004
 357
 358        -  This input supports setting the TV standard by using
 359           VIDIOC_S_STD.
 360
 361     -  .. row 3
 362
 363        -  ``V4L2_IN_CAP_NATIVE_SIZE``
 364
 365        -  0x00000008
 366
 367        -  This input supports setting the native size using the
 368           ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 369           :ref:`v4l2-selections-common`.
 370
 371
 372 Return Value
 373 ============
 374
 375 On success 0 is returned, on error -1 and the ``errno`` variable is set
 376 appropriately. The generic error codes are described at the
 377 :ref:`Generic Error Codes <gen-errors>` chapter.
 378
 379 EINVAL
 380     The struct :c:type:`v4l2_input` ``index`` is out of
 381     bounds.