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 .. 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
 227 Return Value
 228 ============
 229
 230 On success 0 is returned, on error -1 and the ``errno`` variable is set
 231 appropriately. The generic error codes are described at the
 232 :ref:`Generic Error Codes <gen-errors>` chapter.
 233
 234 EINVAL
 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.