0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENUMINPUT:
0005
0006 **********************
0007 ioctl VIDIOC_ENUMINPUT
0008 **********************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENUMINPUT - Enumerate video inputs
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENUMINPUT
0019
0020 ``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_input`.
0030
0031 Description
0032 ===========
0033
0034 To query the attributes of a video input applications initialize the
0035 ``index`` field of struct :c:type:`v4l2_input` and call the
0036 :ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
0037 fill the rest of the structure or return an ``EINVAL`` error code when the
0038 index is out of bounds. To enumerate all inputs applications shall begin
0039 at index zero, incrementing by one until the driver returns ``EINVAL``.
0040
0041 .. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}|
0042
0043 .. c:type:: v4l2_input
0044
0045 .. flat-table:: struct v4l2_input
0046 :header-rows: 0
0047 :stub-columns: 0
0048 :widths: 1 1 2
0049
0050 * - __u32
0051 - ``index``
0052 - Identifies the input, set by the application.
0053 * - __u8
0054 - ``name``\ [32]
0055 - Name of the video input, a NUL-terminated ASCII string, for
0056 example: "Vin (Composite 2)". This information is intended for the
0057 user, preferably the connector label on the device itself.
0058 * - __u32
0059 - ``type``
0060 - Type of the input, see :ref:`input-type`.
0061 * - __u32
0062 - ``audioset``
0063 - Drivers can enumerate up to 32 video and audio inputs. This field
0064 shows which audio inputs were selectable as audio source if this
0065 was the currently selected video input. It is a bit mask. The LSB
0066 corresponds to audio input 0, the MSB to input 31. Any number of
0067 bits can be set, or none.
0068
0069 When the driver does not enumerate audio inputs no bits must be
0070 set. Applications shall not interpret this as lack of audio
0071 support. Some drivers automatically select audio sources and do
0072 not enumerate them since there is no choice anyway.
0073
0074 For details on audio inputs and how to select the current input
0075 see :ref:`audio`.
0076 * - __u32
0077 - ``tuner``
0078 - Capture devices can have zero or more tuners (RF demodulators).
0079 When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
0080 RF connector and this field identifies the tuner. It corresponds
0081 to struct :c:type:`v4l2_tuner` field ``index``. For
0082 details on tuners see :ref:`tuner`.
0083 * - :ref:`v4l2_std_id <v4l2-std-id>`
0084 - ``std``
0085 - Every video input supports one or more different video standards.
0086 This field is a set of all supported standards. For details on
0087 video standards and how to switch see :ref:`standard`.
0088 * - __u32
0089 - ``status``
0090 - This field provides status information about the input. See
0091 :ref:`input-status` for flags. With the exception of the sensor
0092 orientation bits ``status`` is only valid when this is the current
0093 input.
0094 * - __u32
0095 - ``capabilities``
0096 - This field provides capabilities for the input. See
0097 :ref:`input-capabilities` for flags.
0098 * - __u32
0099 - ``reserved``\ [3]
0100 - Reserved for future extensions. Drivers must set the array to
0101 zero.
0102
0103
0104 .. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}|
0105
0106 .. _input-type:
0107
0108 .. flat-table:: Input Types
0109 :header-rows: 0
0110 :stub-columns: 0
0111 :widths: 3 1 4
0112
0113 * - ``V4L2_INPUT_TYPE_TUNER``
0114 - 1
0115 - This input uses a tuner (RF demodulator).
0116 * - ``V4L2_INPUT_TYPE_CAMERA``
0117 - 2
0118 - Any non-tuner video input, for example Composite Video,
0119 S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
0120 today we would have called it ``_TYPE_VIDEO``.
0121 * - ``V4L2_INPUT_TYPE_TOUCH``
0122 - 3
0123 - This input is a touch device for capturing raw touch data.
0124
0125
0126 .. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}|
0127
0128 .. _input-status:
0129
0130 .. flat-table:: Input Status Flags
0131 :header-rows: 0
0132 :stub-columns: 0
0133
0134 * - :cspan:`2` General
0135 * - ``V4L2_IN_ST_NO_POWER``
0136 - 0x00000001
0137 - Attached device is off.
0138 * - ``V4L2_IN_ST_NO_SIGNAL``
0139 - 0x00000002
0140 -
0141 * - ``V4L2_IN_ST_NO_COLOR``
0142 - 0x00000004
0143 - The hardware supports color decoding, but does not detect color
0144 modulation in the signal.
0145 * - :cspan:`2` Sensor Orientation
0146 * - ``V4L2_IN_ST_HFLIP``
0147 - 0x00000010
0148 - The input is connected to a device that produces a signal that is
0149 flipped horizontally and does not correct this before passing the
0150 signal to userspace.
0151 * - ``V4L2_IN_ST_VFLIP``
0152 - 0x00000020
0153 - The input is connected to a device that produces a signal that is
0154 flipped vertically and does not correct this before passing the
0155 signal to userspace.
0156 .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
0157 * - :cspan:`2` Analog Video
0158 * - ``V4L2_IN_ST_NO_H_LOCK``
0159 - 0x00000100
0160 - No horizontal sync lock.
0161 * - ``V4L2_IN_ST_COLOR_KILL``
0162 - 0x00000200
0163 - A color killer circuit automatically disables color decoding when
0164 it detects no color modulation. When this flag is set the color
0165 killer is enabled *and* has shut off color decoding.
0166 * - ``V4L2_IN_ST_NO_V_LOCK``
0167 - 0x00000400
0168 - No vertical sync lock.
0169 * - ``V4L2_IN_ST_NO_STD_LOCK``
0170 - 0x00000800
0171 - No standard format lock in case of auto-detection format
0172 by the component.
0173 * - :cspan:`2` Digital Video
0174 * - ``V4L2_IN_ST_NO_SYNC``
0175 - 0x00010000
0176 - No synchronization lock.
0177 * - ``V4L2_IN_ST_NO_EQU``
0178 - 0x00020000
0179 - No equalizer lock.
0180 * - ``V4L2_IN_ST_NO_CARRIER``
0181 - 0x00040000
0182 - Carrier recovery failed.
0183 * - :cspan:`2` VCR and Set-Top Box
0184 * - ``V4L2_IN_ST_MACROVISION``
0185 - 0x01000000
0186 - Macrovision is an analog copy prevention system mangling the video
0187 signal to confuse video recorders. When this flag is set
0188 Macrovision has been detected.
0189 * - ``V4L2_IN_ST_NO_ACCESS``
0190 - 0x02000000
0191 - Conditional access denied.
0192 * - ``V4L2_IN_ST_VTR``
0193 - 0x04000000
0194 - VTR time constant. [?]
0195
0196
0197 .. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}|
0198
0199 .. _input-capabilities:
0200
0201 .. flat-table:: Input capabilities
0202 :header-rows: 0
0203 :stub-columns: 0
0204 :widths: 3 1 4
0205
0206 * - ``V4L2_IN_CAP_DV_TIMINGS``
0207 - 0x00000002
0208 - This input supports setting video timings by using
0209 ``VIDIOC_S_DV_TIMINGS``.
0210 * - ``V4L2_IN_CAP_STD``
0211 - 0x00000004
0212 - This input supports setting the TV standard by using
0213 ``VIDIOC_S_STD``.
0214 * - ``V4L2_IN_CAP_NATIVE_SIZE``
0215 - 0x00000008
0216 - This input supports setting the native size using the
0217 ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
0218 :ref:`v4l2-selections-common`.
0219
0220 Return Value
0221 ============
0222
0223 On success 0 is returned, on error -1 and the ``errno`` variable is set
0224 appropriately. The generic error codes are described at the
0225 :ref:`Generic Error Codes <gen-errors>` chapter.
0226
0227 EINVAL
0228 The struct :c:type:`v4l2_input` ``index`` is out of
0229 bounds.
