0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENUM_FMT:
0005
0006 *********************
0007 ioctl VIDIOC_ENUM_FMT
0008 *********************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENUM_FMT - Enumerate image formats
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENUM_FMT
0019
0020 ``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_fmtdesc`.
0030
0031 Description
0032 ===========
0033
0034 To enumerate image formats applications initialize the ``type``, ``mbus_code``
0035 and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
0036 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
0037 fill the rest of the structure or return an ``EINVAL`` error code. All
0038 formats are enumerable by beginning at index zero and incrementing by
0039 one until ``EINVAL`` is returned. If applicable, drivers shall return
0040 formats in preference order, where preferred formats are returned before
0041 (that is, with lower ``index`` value) less-preferred formats.
0042
0043 Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
0044 the ``mbus_code`` field is handled differently:
0045
0046 1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
0047
0048 Applications shall initialize the ``mbus_code`` field to zero and drivers
0049 shall ignore the value of the field.
0050
0051 Drivers shall enumerate all image formats.
0052
0053 .. note::
0054
0055 After switching the input or output the list of enumerated image
0056 formats may be different.
0057
0058 2) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
0059
0060 If the ``mbus_code`` field is zero, then all image formats
0061 shall be enumerated.
0062
0063 If the ``mbus_code`` field is initialized to a valid (non-zero)
0064 :ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers
0065 shall restrict enumeration to only the image formats that can produce
0066 (for video output devices) or be produced from (for video capture
0067 devices) that media bus code. If the ``mbus_code`` is unsupported by
0068 the driver, then ``EINVAL`` shall be returned.
0069
0070 Regardless of the value of the ``mbus_code`` field, the enumerated image
0071 formats shall not depend on the active configuration of the video device
0072 or device pipeline.
0073
0074 .. c:type:: v4l2_fmtdesc
0075
0076 .. cssclass:: longtable
0077
0078 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0079
0080 .. flat-table:: struct v4l2_fmtdesc
0081 :header-rows: 0
0082 :stub-columns: 0
0083 :widths: 1 1 2
0084
0085 * - __u32
0086 - ``index``
0087 - Number of the format in the enumeration, set by the application.
0088 This is in no way related to the ``pixelformat`` field.
0089 * - __u32
0090 - ``type``
0091 - Type of the data stream, set by the application. Only these types
0092 are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
0093 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
0094 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
0095 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
0096 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
0097 ``V4L2_BUF_TYPE_SDR_CAPTURE``,
0098 ``V4L2_BUF_TYPE_SDR_OUTPUT``,
0099 ``V4L2_BUF_TYPE_META_CAPTURE`` and
0100 ``V4L2_BUF_TYPE_META_OUTPUT``.
0101 See :c:type:`v4l2_buf_type`.
0102 * - __u32
0103 - ``flags``
0104 - See :ref:`fmtdesc-flags`
0105 * - __u8
0106 - ``description``\ [32]
0107 - Description of the format, a NUL-terminated ASCII string. This
0108 information is intended for the user, for example: "YUV 4:2:2".
0109 * - __u32
0110 - ``pixelformat``
0111 - The image format identifier. This is a four character code as
0112 computed by the v4l2_fourcc() macro:
0113 * - :cspan:`2`
0114
0115 .. _v4l2-fourcc:
0116
0117 ``#define v4l2_fourcc(a,b,c,d)``
0118
0119 ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
0120
0121 Several image formats are already defined by this specification in
0122 :ref:`pixfmt`.
0123
0124 .. attention::
0125
0126 These codes are not the same as those used
0127 in the Windows world.
0128 * - __u32
0129 - ``mbus_code``
0130 - Media bus code restricting the enumerated formats, set by the
0131 application. Only applicable to drivers that advertise the
0132 ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, shall be 0
0133 otherwise.
0134 * - __u32
0135 - ``reserved``\ [3]
0136 - Reserved for future extensions. Drivers must set the array to
0137 zero.
0138
0139
0140 .. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}|
0141
0142 .. cssclass:: longtable
0143
0144 .. _fmtdesc-flags:
0145
0146 .. flat-table:: Image Format Description Flags
0147 :header-rows: 0
0148 :stub-columns: 0
0149 :widths: 3 1 4
0150
0151 * - ``V4L2_FMT_FLAG_COMPRESSED``
0152 - 0x0001
0153 - This is a compressed format.
0154 * - ``V4L2_FMT_FLAG_EMULATED``
0155 - 0x0002
0156 - This format is not native to the device but emulated through
0157 software (usually libv4l2), where possible try to use a native
0158 format instead for better performance.
0159 * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
0160 - 0x0004
0161 - The hardware decoder for this compressed bytestream format (aka coded
0162 format) is capable of parsing a continuous bytestream. Applications do
0163 not need to parse the bytestream themselves to find the boundaries
0164 between frames/fields.
0165
0166 This flag can only be used in combination with the
0167 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
0168 formats only. This flag is valid for stateful decoders only.
0169 * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
0170 - 0x0008
0171 - Dynamic resolution switching is supported by the device for this
0172 compressed bytestream format (aka coded format). It will notify the user
0173 via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
0174 parameters are detected.
0175
0176 This flag can only be used in combination with the
0177 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
0178 compressed formats only. This flag is valid for stateful codecs only.
0179 * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL``
0180 - 0x0010
0181 - The hardware encoder supports setting the ``CAPTURE`` coded frame
0182 interval separately from the ``OUTPUT`` raw frame interval.
0183 Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>`
0184 also sets the ``CAPTURE`` coded frame interval to the same value.
0185 If this flag is set, then the ``CAPTURE`` coded frame interval can be
0186 set to a different value afterwards. This is typically used for
0187 offline encoding where the ``OUTPUT`` raw frame interval is used as
0188 a hint for reserving hardware encoder resources and the ``CAPTURE`` coded
0189 frame interval is the actual frame rate embedded in the encoded video
0190 stream.
0191
0192 This flag can only be used in combination with the
0193 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
0194 compressed formats only. This flag is valid for stateful encoders only.
0195 * - ``V4L2_FMT_FLAG_CSC_COLORSPACE``
0196 - 0x0020
0197 - The driver allows the application to try to change the default
0198 colorspace. This flag is relevant only for capture devices.
0199 The application can ask to configure the colorspace of the capture device
0200 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
0201 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
0202 * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC``
0203 - 0x0040
0204 - The driver allows the application to try to change the default
0205 transfer function. This flag is relevant only for capture devices.
0206 The application can ask to configure the transfer function of the capture
0207 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
0208 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
0209 * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC``
0210 - 0x0080
0211 - The driver allows the application to try to change the default
0212 Y'CbCr encoding. This flag is relevant only for capture devices.
0213 The application can ask to configure the Y'CbCr encoding of the capture device
0214 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
0215 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
0216 * - ``V4L2_FMT_FLAG_CSC_HSV_ENC``
0217 - 0x0080
0218 - The driver allows the application to try to change the default
0219 HSV encoding. This flag is relevant only for capture devices.
0220 The application can ask to configure the HSV encoding of the capture device
0221 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
0222 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
0223 * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION``
0224 - 0x0100
0225 - The driver allows the application to try to change the default
0226 quantization. This flag is relevant only for capture devices.
0227 The application can ask to configure the quantization of the capture
0228 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
0229 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
0230
0231 Return Value
0232 ============
0233
0234 On success 0 is returned, on error -1 and the ``errno`` variable is set
0235 appropriately. The generic error codes are described at the
0236 :ref:`Generic Error Codes <gen-errors>` chapter.
0237
0238 EINVAL
0239 The struct :c:type:`v4l2_fmtdesc` ``type`` is not
0240 supported or the ``index`` is out of bounds.
0241
0242 If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
0243 is unsupported, then also return this error code.
