1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
13 VIDIOC_ENUM_FMT - Enumerate image formats
18 .. c:macro:: VIDIOC_ENUM_FMT
20 ``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)``
26 File descriptor returned by :c:func:`open()`.
29 Pointer to struct :c:type:`v4l2_fmtdesc`.
34 To enumerate image formats applications initialize the ``type``, ``mbus_code``
35 and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
36 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
37 fill the rest of the structure or return an ``EINVAL`` error code. All
38 formats are enumerable by beginning at index zero and incrementing by
39 one until ``EINVAL`` is returned. If applicable, drivers shall return
40 formats in preference order, where preferred formats are returned before
41 (that is, with lower ``index`` value) less-preferred formats.
43 Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
44 the ``mbus_code`` field is handled differently:
46 1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
48 Applications shall initialize the ``mbus_code`` field to zero and drivers
49 shall ignore the value of the field.
51 Drivers shall enumerate all image formats.
55 After switching the input or output the list of enumerated image
56 formats may be different.
58 2) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
60 If the ``mbus_code`` field is zero, then all image formats
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.
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
74 .. c:type:: v4l2_fmtdesc
76 .. cssclass:: longtable
78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
80 .. flat-table:: struct v4l2_fmtdesc
87 - Number of the format in the enumeration, set by the application.
88 This is in no way related to the ``pixelformat`` field.
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`.
104 - See :ref:`fmtdesc-flags`
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".
111 - The image format identifier. This is a four character code as
112 computed by the v4l2_fourcc() macro:
117 ``#define v4l2_fourcc(a,b,c,d)``
119 ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
121 Several image formats are already defined by this specification in
126 These codes are not the same as those used
127 in the Windows world.
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
136 - Reserved for future extensions. Drivers must set the array to
140 .. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}|
142 .. cssclass:: longtable
146 .. flat-table:: Image Format Description Flags
151 * - ``V4L2_FMT_FLAG_COMPRESSED``
153 - This is a compressed format.
154 * - ``V4L2_FMT_FLAG_EMULATED``
156 - This format is not native to the device but emulated through
157 software (usually libv4l2), where possible try to use a native
158 format instead for better performance.
159 * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
161 - The hardware decoder for this compressed bytestream format (aka coded
162 format) is capable of parsing a continuous bytestream. Applications do
163 not need to parse the bytestream themselves to find the boundaries
164 between frames/fields.
166 This flag can only be used in combination with the
167 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
168 formats only. This flag is valid for stateful decoders only.
169 * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
171 - Dynamic resolution switching is supported by the device for this
172 compressed bytestream format (aka coded format). It will notify the user
173 via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
174 parameters are detected.
176 This flag can only be used in combination with the
177 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
178 compressed formats only. This flag is valid for stateful codecs only.
179 * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL``
181 - The hardware encoder supports setting the ``CAPTURE`` coded frame
182 interval separately from the ``OUTPUT`` raw frame interval.
183 Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>`
184 also sets the ``CAPTURE`` coded frame interval to the same value.
185 If this flag is set, then the ``CAPTURE`` coded frame interval can be
186 set to a different value afterwards. This is typically used for
187 offline encoding where the ``OUTPUT`` raw frame interval is used as
188 a hint for reserving hardware encoder resources and the ``CAPTURE`` coded
189 frame interval is the actual frame rate embedded in the encoded video
192 This flag can only be used in combination with the
193 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
194 compressed formats only. This flag is valid for stateful encoders only.
195 * - ``V4L2_FMT_FLAG_CSC_COLORSPACE``
197 - The driver allows the application to try to change the default
198 colorspace. This flag is relevant only for capture devices.
199 The application can ask to configure the colorspace of the capture device
200 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
201 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
202 * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC``
204 - The driver allows the application to try to change the default
205 transfer function. This flag is relevant only for capture devices.
206 The application can ask to configure the transfer function of the capture
207 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
208 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
209 * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC``
211 - The driver allows the application to try to change the default
212 Y'CbCr encoding. This flag is relevant only for capture devices.
213 The application can ask to configure the Y'CbCr encoding of the capture device
214 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
215 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
216 * - ``V4L2_FMT_FLAG_CSC_HSV_ENC``
218 - The driver allows the application to try to change the default
219 HSV encoding. This flag is relevant only for capture devices.
220 The application can ask to configure the HSV encoding of the capture device
221 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
222 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
223 * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION``
225 - The driver allows the application to try to change the default
226 quantization. This flag is relevant only for capture devices.
227 The application can ask to configure the quantization of the capture
228 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
229 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
234 On success 0 is returned, on error -1 and the ``errno`` variable is set
235 appropriately. The generic error codes are described at the
236 :ref:`Generic Error Codes <gen-errors>` chapter.
239 The struct :c:type:`v4l2_fmtdesc` ``type`` is not
240 supported or the ``index`` is out of bounds.
242 If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
243 is unsupported, then also return this error code.