Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_ENUMOUTPUT:
   5
   6 ***********************
   7 ioctl VIDIOC_ENUMOUTPUT
   8 ***********************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_ENUMOUTPUT - Enumerate video outputs
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_ENUMOUTPUT
  19
  20 ``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_output`.
  30
  31 Description
  32 ===========
  33
  34 To query the attributes of a video outputs applications initialize the
  35 ``index`` field of struct :c:type:`v4l2_output` and call
  36 the :ref:`VIDIOC_ENUMOUTPUT` with a pointer to this structure.
  37 Drivers fill the rest of the structure or return an ``EINVAL`` error code
  38 when the index is out of bounds. To enumerate all outputs applications
  39 shall begin at index zero, incrementing by one until the driver returns
  40 ``EINVAL``.
  41
  42 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  43
  44 .. c:type:: v4l2_output
  45
  46 .. flat-table:: struct v4l2_output
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 1 2
  50
  51     * - __u32
  52       - ``index``
  53       - Identifies the output, set by the application.
  54     * - __u8
  55       - ``name``\ [32]
  56       - Name of the video output, a NUL-terminated ASCII string, for
  57         example: "Vout". This information is intended for the user,
  58         preferably the connector label on the device itself.
  59     * - __u32
  60       - ``type``
  61       - Type of the output, see :ref:`output-type`.
  62     * - __u32
  63       - ``audioset``
  64       - Drivers can enumerate up to 32 video and audio outputs. This field
  65         shows which audio outputs were selectable as the current output if
  66         this was the currently selected video output. It is a bit mask.
  67         The LSB corresponds to audio output 0, the MSB to output 31. Any
  68         number of bits can be set, or none.
  69
  70         When the driver does not enumerate audio outputs no bits must be
  71         set. Applications shall not interpret this as lack of audio
  72         support. Drivers may automatically select audio outputs without
  73         enumerating them.
  74
  75         For details on audio outputs and how to select the current output
  76         see :ref:`audio`.
  77     * - __u32
  78       - ``modulator``
  79       - Output devices can have zero or more RF modulators. When the
  80         ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
  81         and this field identifies the modulator. It corresponds to struct
  82         :c:type:`v4l2_modulator` field ``index``. For
  83         details on modulators see :ref:`tuner`.
  84     * - :ref:`v4l2_std_id <v4l2-std-id>`
  85       - ``std``
  86       - Every video output supports one or more different video standards.
  87         This field is a set of all supported standards. For details on
  88         video standards and how to switch see :ref:`standard`.
  89     * - __u32
  90       - ``capabilities``
  91       - This field provides capabilities for the output. See
  92         :ref:`output-capabilities` for flags.
  93     * - __u32
  94       - ``reserved``\ [3]
  95       - Reserved for future extensions. Drivers must set the array to
  96         zero.
  97
  98
  99 .. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}|
 100
 101 .. _output-type:
 102
 103 .. flat-table:: Output Type
 104     :header-rows:  0
 105     :stub-columns: 0
 106     :widths:       3 1 4
 107
 108     * - ``V4L2_OUTPUT_TYPE_MODULATOR``
 109       - 1
 110       - This output is an analog TV modulator.
 111     * - ``V4L2_OUTPUT_TYPE_ANALOG``
 112       - 2
 113       - Any non-modulator video output, for example Composite Video,
 114         S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical,
 115         today we would have called it ``_TYPE_VIDEO``.
 116     * - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
 117       - 3
 118       - The video output will be copied to a :ref:`video overlay <overlay>`.
 119
 120
 121 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 122
 123 .. _output-capabilities:
 124
 125 .. flat-table:: Output capabilities
 126     :header-rows:  0
 127     :stub-columns: 0
 128     :widths:       3 1 4
 129
 130     * - ``V4L2_OUT_CAP_DV_TIMINGS``
 131       - 0x00000002
 132       - This output supports setting video timings by using
 133         ``VIDIOC_S_DV_TIMINGS``.
 134     * - ``V4L2_OUT_CAP_STD``
 135       - 0x00000004
 136       - This output supports setting the TV standard by using
 137         ``VIDIOC_S_STD``.
 138     * - ``V4L2_OUT_CAP_NATIVE_SIZE``
 139       - 0x00000008
 140       - This output supports setting the native size using the
 141         ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 142         :ref:`v4l2-selections-common`.
 143
 144 Return Value
 145 ============
 146
 147 On success 0 is returned, on error -1 and the ``errno`` variable is set
 148 appropriately. The generic error codes are described at the
 149 :ref:`Generic Error Codes <gen-errors>` chapter.
 150
 151 EINVAL
 152     The struct :c:type:`v4l2_output` ``index`` is out of
 153     bounds.