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