vidioc-enuminput.rst 7.1 KB
Newer Older
1 2
.. -*- coding: utf-8; mode: rst -*-

3
.. _VIDIOC_ENUMINPUT:
4 5 6 7 8

**********************
ioctl VIDIOC_ENUMINPUT
**********************

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 25 26 27 28 29 30 31 32
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_ENUMINPUT

``argp``


33
Description
34 35 36 37
===========

To query the attributes of a video input applications initialize the
``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 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66


.. _v4l2-input:

.. flat-table:: struct v4l2_input
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``index``

       -  Identifies the input, set by the application.

    -  .. row 2

       -  __u8

       -  ``name``\ [32]

       -  Name of the video input, a NUL-terminated ASCII string, for
67 68
	  example: "Vin (Composite 2)". This information is intended for the
	  user, preferably the connector label on the device itself.
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84

    -  .. row 3

       -  __u32

       -  ``type``

       -  Type of the input, see :ref:`input-type`.

    -  .. row 4

       -  __u32

       -  ``audioset``

       -  Drivers can enumerate up to 32 video and audio inputs. This field
85 86 87 88
	  shows which audio inputs were selectable as audio source if this
	  was the currently selected video input. It is a bit mask. The LSB
	  corresponds to audio input 0, the MSB to input 31. Any number of
	  bits can be set, or none.
89

90 91 92 93
	  When the driver does not enumerate audio inputs no bits must be
	  set. Applications shall not interpret this as lack of audio
	  support. Some drivers automatically select audio sources and do
	  not enumerate them since there is no choice anyway.
94

95 96
	  For details on audio inputs and how to select the current input
	  see :ref:`audio`.
97 98 99 100 101 102 103 104

    -  .. row 5

       -  __u32

       -  ``tuner``

       -  Capture devices can have zero or more tuners (RF demodulators).
105 106 107 108
	  When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
	  RF connector and this field identifies the tuner. It corresponds
	  to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
	  details on tuners see :ref:`tuner`.
109 110 111 112 113 114 115 116

    -  .. row 6

       -  :ref:`v4l2_std_id <v4l2-std-id>`

       -  ``std``

       -  Every video input supports one or more different video standards.
117 118
	  This field is a set of all supported standards. For details on
	  video standards and how to switch see :ref:`standard`.
119 120 121 122 123 124 125 126

    -  .. row 7

       -  __u32

       -  ``status``

       -  This field provides status information about the input. See
127 128 129
	  :ref:`input-status` for flags. With the exception of the sensor
	  orientation bits ``status`` is only valid when this is the current
	  input.
130 131 132 133 134 135 136 137

    -  .. row 8

       -  __u32

       -  ``capabilities``

       -  This field provides capabilities for the input. See
138
	  :ref:`input-capabilities` for flags.
139 140 141 142 143 144 145 146

    -  .. row 9

       -  __u32

       -  ``reserved``\ [3]

       -  Reserved for future extensions. Drivers must set the array to
147
	  zero.
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173



.. _input-type:

.. flat-table:: Input Types
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_INPUT_TYPE_TUNER``

       -  1

       -  This input uses a tuner (RF demodulator).

    -  .. row 2

       -  ``V4L2_INPUT_TYPE_CAMERA``

       -  2

       -  Analog baseband input, for example CVBS / Composite Video,
174
	  S-Video, RGB.
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202



.. _input-status:

.. flat-table:: Input Status Flags
    :header-rows:  0
    :stub-columns: 0


    -  .. row 1

       -  :cspan:`2` General

    -  .. row 2

       -  ``V4L2_IN_ST_NO_POWER``

       -  0x00000001

       -  Attached device is off.

    -  .. row 3

       -  ``V4L2_IN_ST_NO_SIGNAL``

       -  0x00000002

203
       -
204 205 206 207 208 209 210 211

    -  .. row 4

       -  ``V4L2_IN_ST_NO_COLOR``

       -  0x00000004

       -  The hardware supports color decoding, but does not detect color
212
	  modulation in the signal.
213 214 215 216 217 218 219 220 221 222 223 224

    -  .. row 5

       -  :cspan:`2` Sensor Orientation

    -  .. row 6

       -  ``V4L2_IN_ST_HFLIP``

       -  0x00000010

       -  The input is connected to a device that produces a signal that is
225 226
	  flipped horizontally and does not correct this before passing the
	  signal to userspace.
227 228 229 230 231 232 233 234

    -  .. row 7

       -  ``V4L2_IN_ST_VFLIP``

       -  0x00000020

       -  The input is connected to a device that produces a signal that is
235 236 237
	  flipped vertically and does not correct this before passing the
	  signal to userspace. Note that a 180 degree rotation is the same
	  as HFLIP | VFLIP
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257

    -  .. row 8

       -  :cspan:`2` Analog Video

    -  .. row 9

       -  ``V4L2_IN_ST_NO_H_LOCK``

       -  0x00000100

       -  No horizontal sync lock.

    -  .. row 10

       -  ``V4L2_IN_ST_COLOR_KILL``

       -  0x00000200

       -  A color killer circuit automatically disables color decoding when
258 259
	  it detects no color modulation. When this flag is set the color
	  killer is enabled *and* has shut off color decoding.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299

    -  .. row 11

       -  :cspan:`2` Digital Video

    -  .. row 12

       -  ``V4L2_IN_ST_NO_SYNC``

       -  0x00010000

       -  No synchronization lock.

    -  .. row 13

       -  ``V4L2_IN_ST_NO_EQU``

       -  0x00020000

       -  No equalizer lock.

    -  .. row 14

       -  ``V4L2_IN_ST_NO_CARRIER``

       -  0x00040000

       -  Carrier recovery failed.

    -  .. row 15

       -  :cspan:`2` VCR and Set-Top Box

    -  .. row 16

       -  ``V4L2_IN_ST_MACROVISION``

       -  0x01000000

       -  Macrovision is an analog copy prevention system mangling the video
300 301
	  signal to confuse video recorders. When this flag is set
	  Macrovision has been detected.
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335

    -  .. row 17

       -  ``V4L2_IN_ST_NO_ACCESS``

       -  0x02000000

       -  Conditional access denied.

    -  .. row 18

       -  ``V4L2_IN_ST_VTR``

       -  0x04000000

       -  VTR time constant. [?]



.. _input-capabilities:

.. flat-table:: Input capabilities
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_IN_CAP_DV_TIMINGS``

       -  0x00000002

       -  This input supports setting video timings by using
336
	  VIDIOC_S_DV_TIMINGS.
337 338 339 340 341 342 343 344

    -  .. row 2

       -  ``V4L2_IN_CAP_STD``

       -  0x00000004

       -  This input supports setting the TV standard by using
345
	  VIDIOC_S_STD.
346 347 348 349 350 351 352 353

    -  .. row 3

       -  ``V4L2_IN_CAP_NATIVE_SIZE``

       -  0x00000008

       -  This input supports setting the native size using the
354 355
	  ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
	  :ref:`v4l2-selections-common`.
356 357


358
Return Value
359 360 361 362 363 364 365 366 367
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
    bounds.