Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst

   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     * - __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 .. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}|
 141
 142 .. cssclass:: longtable
 143
 144 .. _fmtdesc-flags:
 145
 146 .. flat-table:: Image Format Description Flags
 147     :header-rows:  0
 148     :stub-columns: 0
 149     :widths:       3 1 4
 150
 151     * - ``V4L2_FMT_FLAG_COMPRESSED``
 152       - 0x0001
 153       - This is a compressed format.
 154     * - ``V4L2_FMT_FLAG_EMULATED``
 155       - 0x0002
 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``
 160       - 0x0004
 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.
 165
 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``
 170       - 0x0008
 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.
 175
 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``
 180       - 0x0010
 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
 190         stream.
 191
 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``
 196       - 0x0020
 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``
 203       - 0x0040
 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``
 210       - 0x0080
 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``
 217       - 0x0080
 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``
 224       - 0x0100
 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.
 230
 231 Return Value
 232 ============
 233
 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.
 237
 238 EINVAL
 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.