Documentation/media/uapi/v4l/vidioc-enuminput.rst

   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/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_ENUMINPUT:
  11
  12 **********************
  13 ioctl VIDIOC_ENUMINPUT
  14 **********************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_ENUMINPUT - Enumerate video inputs
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp )
  26     :name: VIDIOC_ENUMINPUT
  27
  28
  29 Arguments
  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
  39 Description
  40 ===========
  41
  42 To 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
  45 fill the rest of the structure or return an ``EINVAL`` error code when the
  46 index is out of bounds. To enumerate all inputs applications shall begin
  47 at 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
 233 Return Value
 234 ============
 235
 236 On success 0 is returned, on error -1 and the ``errno`` variable is set
 237 appropriately. The generic error codes are described at the
 238 :ref:`Generic Error Codes <gen-errors>` chapter.
 239
 240 EINVAL
 241     The struct :c:type:`v4l2_input` ``index`` is out of
 242     bounds.