| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _VIDIOC_ENUM_FMT: |
| 5 |
|
| 6 |
********************* |
| 7 |
ioctl VIDIOC_ENUM_FMT |
| 8 |
********************* |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
VIDIOC_ENUM_FMT - Enumerate image formats |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. c:macro:: VIDIOC_ENUM_FMT |
| 19 |
|
| 20 |
``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *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_fmtdesc`. |
| 30 |
|
| 31 |
Description |
| 32 |
=========== |
| 33 |
|
| 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. |
| 42 |
|
| 43 |
Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, |
| 44 |
the ``mbus_code`` field is handled differently: |
| 45 |
|
| 46 |
1) ``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 |
|
| 58 |
2) ``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 |
.. c:type:: v4l2_fmtdesc |
| 75 |
|
| 76 |
.. cssclass:: longtable |
| 77 |
|
| 78 |
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| |
| 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 |
When the index is ORed with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` the |
| 90 |
driver clears the flag and enumerates all the possible formats, |
| 91 |
ignoring any limitations from the current configuration. Drivers |
| 92 |
which do not support this flag always return an ``EINVAL`` |
| 93 |
error code without clearing this flag. |
| 94 |
Formats enumerated when using ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag |
| 95 |
shouldn't be used when calling :c:func:`VIDIOC_ENUM_FRAMESIZES` |
| 96 |
or :c:func:`VIDIOC_ENUM_FRAMEINTERVALS`. |
| 97 |
``V4L2_FMTDESC_FLAG_ENUM_ALL`` should only be used by drivers that |
| 98 |
can return different format list depending on this flag. |
| 99 |
* - __u32 |
| 100 |
- ``type`` |
| 101 |
- Type of the data stream, set by the application. Only these types |
| 102 |
are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, |
| 103 |
``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, |
| 104 |
``V4L2_BUF_TYPE_VIDEO_OUTPUT``, |
| 105 |
``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, |
| 106 |
``V4L2_BUF_TYPE_VIDEO_OVERLAY``, |
| 107 |
``V4L2_BUF_TYPE_SDR_CAPTURE``, |
| 108 |
``V4L2_BUF_TYPE_SDR_OUTPUT``, |
| 109 |
``V4L2_BUF_TYPE_META_CAPTURE`` and |
| 110 |
``V4L2_BUF_TYPE_META_OUTPUT``. |
| 111 |
See :c:type:`v4l2_buf_type`. |
| 112 |
* - __u32 |
| 113 |
- ``flags`` |
| 114 |
- See :ref:`fmtdesc-flags` |
| 115 |
* - __u8 |
| 116 |
- ``description``\ [32] |
| 117 |
- Description of the format, a NUL-terminated ASCII string. This |
| 118 |
information is intended for the user, for example: "YUV 4:2:2". |
| 119 |
* - __u32 |
| 120 |
- ``pixelformat`` |
| 121 |
- The image format identifier. This is a four character code as |
| 122 |
computed by the v4l2_fourcc() macro: |
| 123 |
* - :cspan:`2` |
| 124 |
|
| 125 |
.. _v4l2-fourcc: |
| 126 |
|
| 127 |
``#define v4l2_fourcc(a,b,c,d)`` |
| 128 |
|
| 129 |
``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))`` |
| 130 |
|
| 131 |
Several image formats are already defined by this specification in |
| 132 |
:ref:`pixfmt`. |
| 133 |
|
| 134 |
.. attention:: |
| 135 |
|
| 136 |
These codes are not the same as those used |
| 137 |
in the Windows world. |
| 138 |
* - __u32 |
| 139 |
- ``mbus_code`` |
| 140 |
- Media bus code restricting the enumerated formats, set by the |
| 141 |
application. Only applicable to drivers that advertise the |
| 142 |
``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, shall be 0 |
| 143 |
otherwise. |
| 144 |
* - __u32 |
| 145 |
- ``reserved``\ [3] |
| 146 |
- Reserved for future extensions. Drivers must set the array to |
| 147 |
zero. |
| 148 |
|
| 149 |
|
| 150 |
.. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}| |
| 151 |
|
| 152 |
.. cssclass:: longtable |
| 153 |
|
| 154 |
.. _fmtdesc-flags: |
| 155 |
|
| 156 |
.. flat-table:: Image Format Description Flags |
| 157 |
:header-rows: 0 |
| 158 |
:stub-columns: 0 |
| 159 |
:widths: 3 1 4 |
| 160 |
|
| 161 |
* - ``V4L2_FMT_FLAG_COMPRESSED`` |
| 162 |
- 0x0001 |
| 163 |
- This is a compressed format. |
| 164 |
* - ``V4L2_FMT_FLAG_EMULATED`` |
| 165 |
- 0x0002 |
| 166 |
- This format is not native to the device but emulated through |
| 167 |
software (usually libv4l2), where possible try to use a native |
| 168 |
format instead for better performance. |
| 169 |
* - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` |
| 170 |
- 0x0004 |
| 171 |
- The hardware decoder for this compressed bytestream format (aka coded |
| 172 |
format) is capable of parsing a continuous bytestream. Applications do |
| 173 |
not need to parse the bytestream themselves to find the boundaries |
| 174 |
between frames/fields. |
| 175 |
|
| 176 |
This flag can only be used in combination with the |
| 177 |
``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed |
| 178 |
formats only. This flag is valid for stateful decoders only. |
| 179 |
* - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` |
| 180 |
- 0x0008 |
| 181 |
- Dynamic resolution switching is supported by the device for this |
| 182 |
compressed bytestream format (aka coded format). It will notify the user |
| 183 |
via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video |
| 184 |
parameters are detected. |
| 185 |
|
| 186 |
This flag can only be used in combination with the |
| 187 |
``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to |
| 188 |
compressed formats only. This flag is valid for stateful codecs only. |
| 189 |
* - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL`` |
| 190 |
- 0x0010 |
| 191 |
- The hardware encoder supports setting the ``CAPTURE`` coded frame |
| 192 |
interval separately from the ``OUTPUT`` raw frame interval. |
| 193 |
Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` |
| 194 |
also sets the ``CAPTURE`` coded frame interval to the same value. |
| 195 |
If this flag is set, then the ``CAPTURE`` coded frame interval can be |
| 196 |
set to a different value afterwards. This is typically used for |
| 197 |
offline encoding where the ``OUTPUT`` raw frame interval is used as |
| 198 |
a hint for reserving hardware encoder resources and the ``CAPTURE`` coded |
| 199 |
frame interval is the actual frame rate embedded in the encoded video |
| 200 |
stream. |
| 201 |
|
| 202 |
This flag can only be used in combination with the |
| 203 |
``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to |
| 204 |
compressed formats only. This flag is valid for stateful encoders only. |
| 205 |
* - ``V4L2_FMT_FLAG_CSC_COLORSPACE`` |
| 206 |
- 0x0020 |
| 207 |
- The driver allows the application to try to change the default |
| 208 |
colorspace. This flag is relevant only for capture devices. |
| 209 |
The application can ask to configure the colorspace 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_XFER_FUNC`` |
| 213 |
- 0x0040 |
| 214 |
- The driver allows the application to try to change the default |
| 215 |
transfer function. This flag is relevant only for capture devices. |
| 216 |
The application can ask to configure the transfer function of the capture |
| 217 |
device 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_YCBCR_ENC`` |
| 220 |
- 0x0080 |
| 221 |
- The driver allows the application to try to change the default |
| 222 |
Y'CbCr encoding. This flag is relevant only for capture devices. |
| 223 |
The application can ask to configure the Y'CbCr encoding of the capture device |
| 224 |
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 |
* - ``V4L2_FMT_FLAG_CSC_HSV_ENC`` |
| 227 |
- 0x0080 |
| 228 |
- The driver allows the application to try to change the default |
| 229 |
HSV encoding. This flag is relevant only for capture devices. |
| 230 |
The application can ask to configure the HSV encoding of the capture device |
| 231 |
when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with |
| 232 |
:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. |
| 233 |
* - ``V4L2_FMT_FLAG_CSC_QUANTIZATION`` |
| 234 |
- 0x0100 |
| 235 |
- The driver allows the application to try to change the default |
| 236 |
quantization. This flag is relevant only for capture devices. |
| 237 |
The application can ask to configure the quantization of the capture |
| 238 |
device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with |
| 239 |
:ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set. |
| 240 |
* - ``V4L2_FMT_FLAG_META_LINE_BASED`` |
| 241 |
- 0x0200 |
| 242 |
- The metadata format is line-based. In this case the ``width``, |
| 243 |
``height`` and ``bytesperline`` fields of :c:type:`v4l2_meta_format` are |
| 244 |
valid. The buffer consists of ``height`` lines, each having ``width`` |
| 245 |
Data Units of data and the offset (in bytes) between the beginning of |
| 246 |
each two consecutive lines is ``bytesperline``. |
| 247 |
* - ``V4L2_FMTDESC_FLAG_ENUM_ALL`` |
| 248 |
- 0x80000000 |
| 249 |
- When the applications ORs ``index`` with ``V4L2_FMTDESC_FLAG_ENUM_ALL`` flag |
| 250 |
the driver enumerates all the possible pixel formats without taking care |
| 251 |
of any already set configuration. Drivers which do not support this flag, |
| 252 |
always return ``EINVAL`` without clearing this flag. |
| 253 |
|
| 254 |
Return Value |
| 255 |
============ |
| 256 |
|
| 257 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 258 |
appropriately. The generic error codes are described at the |
| 259 |
:ref:`Generic Error Codes <gen-errors>` chapter. |
| 260 |
|
| 261 |
EINVAL |
| 262 |
The struct :c:type:`v4l2_fmtdesc` ``type`` is not |
| 263 |
supported or the ``index`` is out of bounds. |
| 264 |
|
| 265 |
If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code`` |
| 266 |
is unsupported, then also return this error code. |