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.