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