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