1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_ENUM_FMT:
4
5*********************
6ioctl VIDIOC_ENUM_FMT
7*********************
8
9Name
10====
11
12VIDIOC_ENUM_FMT - Enumerate image formats
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp )
19    :name: VIDIOC_ENUM_FMT
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_fmtdesc`.
30
31
32Description
33===========
34
35To enumerate image formats applications initialize the ``type``, ``mbus_code``
36and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
37the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
38fill the rest of the structure or return an ``EINVAL`` error code. All
39formats are enumerable by beginning at index zero and incrementing by
40one until ``EINVAL`` is returned. If applicable, drivers shall return
41formats in preference order, where preferred formats are returned before
42(that is, with lower ``index`` value) less-preferred formats.
43
44Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
45the ``mbus_code`` field is handled differently:
46
471) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
48
49   Applications shall initialize the ``mbus_code`` field to zero and drivers
50   shall ignore the value of the field.
51
52   Drivers shall enumerate all image formats.
53
54   .. note::
55
56      After switching the input or output the list of enumerated image
57      formats may be different.
58
592) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
60
61   If the ``mbus_code`` field is zero, then all image formats
62   shall be enumerated.
63
64   If the ``mbus_code`` field is initialized to a valid (non-zero)
65   :ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers
66   shall restrict enumeration to only the image formats that can produce
67   (for video output devices) or be produced from (for video capture
68   devices) that media bus code. If the ``mbus_code`` is unsupported by
69   the driver, then ``EINVAL`` shall be returned.
70
71   Regardless of the value of the ``mbus_code`` field, the enumerated image
72   formats shall not depend on the active configuration of the video device
73   or device pipeline.
74
75
76.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
77
78.. c:type:: v4l2_fmtdesc
79
80.. flat-table:: struct v4l2_fmtdesc
81    :header-rows:  0
82    :stub-columns: 0
83    :widths:       1 1 2
84
85    * - __u32
86      - ``index``
87      - Number of the format in the enumeration, set by the application.
88	This is in no way related to the ``pixelformat`` field.
89    * - __u32
90      - ``type``
91      - Type of the data stream, set by the application. Only these types
92	are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
93	``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
94	``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
95	``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
96	``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
97	``V4L2_BUF_TYPE_SDR_CAPTURE``,
98	``V4L2_BUF_TYPE_SDR_OUTPUT``,
99	``V4L2_BUF_TYPE_META_CAPTURE`` and
100	``V4L2_BUF_TYPE_META_OUTPUT``.
101	See :c:type:`v4l2_buf_type`.
102    * - __u32
103      - ``flags``
104      - See :ref:`fmtdesc-flags`
105    * - __u8
106      - ``description``\ [32]
107      - Description of the format, a NUL-terminated ASCII string. This
108	information is intended for the user, for example: "YUV 4:2:2".
109    * - __u32
110      - ``pixelformat``
111      - The image format identifier. This is a four character code as
112	computed by the v4l2_fourcc() macro:
113    * - :cspan:`2`
114
115	.. _v4l2-fourcc:
116
117	``#define v4l2_fourcc(a,b,c,d)``
118
119	``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
120
121	Several image formats are already defined by this specification in
122	:ref:`pixfmt`.
123
124	.. attention::
125
126	   These codes are not the same as those used
127	   in the Windows world.
128    * - __u32
129      - ``mbus_code``
130      - Media bus code restricting the enumerated formats, set by the
131        application. Only applicable to drivers that advertise the
132        ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, shall be 0
133        otherwise.
134    * - __u32
135      - ``reserved``\ [3]
136      - Reserved for future extensions. Drivers must set the array to
137	zero.
138
139
140
141.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
142
143.. _fmtdesc-flags:
144
145.. flat-table:: Image Format Description Flags
146    :header-rows:  0
147    :stub-columns: 0
148    :widths:       3 1 4
149
150    * - ``V4L2_FMT_FLAG_COMPRESSED``
151      - 0x0001
152      - This is a compressed format.
153    * - ``V4L2_FMT_FLAG_EMULATED``
154      - 0x0002
155      - This format is not native to the device but emulated through
156	software (usually libv4l2), where possible try to use a native
157	format instead for better performance.
158    * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
159      - 0x0004
160      - The hardware decoder for this compressed bytestream format (aka coded
161	format) is capable of parsing a continuous bytestream. Applications do
162	not need to parse the bytestream themselves to find the boundaries
163	between frames/fields.
164
165	This flag can only be used in combination with the
166	``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
167	formats only. This flag is valid for stateful decoders only.
168    * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
169      - 0x0008
170      - Dynamic resolution switching is supported by the device for this
171	compressed bytestream format (aka coded format). It will notify the user
172	via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
173	parameters are detected.
174
175	This flag can only be used in combination with the
176	``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
177	compressed formats only. This flag is valid for stateful codecs only.
178    * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL``
179      - 0x0010
180      - The hardware encoder supports setting the ``CAPTURE`` coded frame
181	interval separately from the ``OUTPUT`` raw frame interval.
182	Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>`
183	also sets the ``CAPTURE`` coded frame interval to the same value.
184	If this flag is set, then the ``CAPTURE`` coded frame interval can be
185	set to a different value afterwards. This is typically used for
186	offline encoding where the ``OUTPUT`` raw frame interval is used as
187	a hint for reserving hardware encoder resources and the ``CAPTURE`` coded
188	frame interval is the actual frame rate embedded in the encoded video
189	stream.
190
191	This flag can only be used in combination with the
192	``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
193        compressed formats only. This flag is valid for stateful encoders only.
194    * - ``V4L2_FMT_FLAG_CSC_COLORSPACE``
195      - 0x0020
196      - The driver allows the application to try to change the default
197	colorspace. This flag is relevant only for capture devices.
198	The application can ask to configure the colorspace of the capture device
199	when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
200	:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
201    * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC``
202      - 0x0040
203      - The driver allows the application to try to change the default
204	transfer function. This flag is relevant only for capture devices.
205	The application can ask to configure the transfer function of the capture
206	device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
207	:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
208    * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC``
209      - 0x0080
210      - The driver allows the application to try to change the default
211	Y'CbCr encoding. This flag is relevant only for capture devices.
212	The application can ask to configure the Y'CbCr encoding of the capture device
213	when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
214	:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
215    * - ``V4L2_FMT_FLAG_CSC_HSV_ENC``
216      - 0x0080
217      - The driver allows the application to try to change the default
218	HSV encoding. This flag is relevant only for capture devices.
219	The application can ask to configure the HSV encoding of the capture device
220	when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
221	:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
222    * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION``
223      - 0x0100
224      - The driver allows the application to try to change the default
225	quantization. This flag is relevant only for capture devices.
226	The application can ask to configure the quantization of the capture
227	device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
228	:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
229
230
231Return Value
232============
233
234On success 0 is returned, on error -1 and the ``errno`` variable is set
235appropriately. The generic error codes are described at the
236:ref:`Generic Error Codes <gen-errors>` chapter.
237
238EINVAL
239    The struct :c:type:`v4l2_fmtdesc` ``type`` is not
240    supported or the ``index`` is out of bounds.
241
242    If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
243    is unsupported, then also return this error code.
244