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