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