1.. Permission is granted to copy, distribute and/or modify this 2.. document under the terms of the GNU Free Documentation License, 3.. Version 1.1 or any later version published by the Free Software 4.. Foundation, with no Invariant Sections, no Front-Cover Texts 5.. and no Back-Cover Texts. A copy of the license is included at 6.. Documentation/media/uapi/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _VIDIOC_ENUM_FMT: 11 12********************* 13ioctl VIDIOC_ENUM_FMT 14********************* 15 16Name 17==== 18 19VIDIOC_ENUM_FMT - Enumerate image formats 20 21 22Synopsis 23======== 24 25.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp ) 26 :name: VIDIOC_ENUM_FMT 27 28 29Arguments 30========= 31 32``fd`` 33 File descriptor returned by :ref:`open() <func-open>`. 34 35``argp`` 36 Pointer to struct :c:type:`v4l2_fmtdesc`. 37 38 39Description 40=========== 41 42To enumerate image formats applications initialize the ``type`` and 43``index`` field of struct :c:type:`v4l2_fmtdesc` and call 44the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers 45fill the rest of the structure or return an ``EINVAL`` error code. All 46formats are enumerable by beginning at index zero and incrementing by 47one until ``EINVAL`` is returned. 48 49.. note:: 50 51 After switching input or output the list of enumerated image 52 formats may be different. 53 54 55.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 56 57.. c:type:: v4l2_fmtdesc 58 59.. flat-table:: struct v4l2_fmtdesc 60 :header-rows: 0 61 :stub-columns: 0 62 :widths: 1 1 2 63 64 * - __u32 65 - ``index`` 66 - Number of the format in the enumeration, set by the application. 67 This is in no way related to the ``pixelformat`` field. 68 * - __u32 69 - ``type`` 70 - Type of the data stream, set by the application. Only these types 71 are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, 72 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, 73 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, 74 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, 75 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, 76 ``V4L2_BUF_TYPE_SDR_CAPTURE``, 77 ``V4L2_BUF_TYPE_SDR_OUTPUT`` and 78 ``V4L2_BUF_TYPE_META_CAPTURE``. 79 See :c:type:`v4l2_buf_type`. 80 * - __u32 81 - ``flags`` 82 - See :ref:`fmtdesc-flags` 83 * - __u8 84 - ``description``\ [32] 85 - Description of the format, a NUL-terminated ASCII string. This 86 information is intended for the user, for example: "YUV 4:2:2". 87 * - __u32 88 - ``pixelformat`` 89 - The image format identifier. This is a four character code as 90 computed by the v4l2_fourcc() macro: 91 * - :cspan:`2` 92 93 .. _v4l2-fourcc: 94 95 ``#define v4l2_fourcc(a,b,c,d)`` 96 97 ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))`` 98 99 Several image formats are already defined by this specification in 100 :ref:`pixfmt`. 101 102 .. attention:: 103 104 These codes are not the same as those used 105 in the Windows world. 106 * - __u32 107 - ``reserved``\ [4] 108 - Reserved for future extensions. Drivers must set the array to 109 zero. 110 111 112 113.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 114 115.. _fmtdesc-flags: 116 117.. flat-table:: Image Format Description Flags 118 :header-rows: 0 119 :stub-columns: 0 120 :widths: 3 1 4 121 122 * - ``V4L2_FMT_FLAG_COMPRESSED`` 123 - 0x0001 124 - This is a compressed format. 125 * - ``V4L2_FMT_FLAG_EMULATED`` 126 - 0x0002 127 - This format is not native to the device but emulated through 128 software (usually libv4l2), where possible try to use a native 129 format instead for better performance. 130 * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM`` 131 - 0x0004 132 - The hardware decoder for this compressed bytestream format (aka coded 133 format) is capable of parsing a continuous bytestream. Applications do 134 not need to parse the bytestream themselves to find the boundaries 135 between frames/fields. This flag can only be used in combination with 136 the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed 137 formats only. This flag is valid for stateful decoders only. 138 * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` 139 - 0x0008 140 - Dynamic resolution switching is supported by the device for this 141 compressed bytestream format (aka coded format). It will notify the user 142 via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video 143 parameters are detected. This flag can only be used in combination 144 with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to 145 compressed formats only. It is also only applies to stateful codecs. 146 147 148Return Value 149============ 150 151On success 0 is returned, on error -1 and the ``errno`` variable is set 152appropriately. The generic error codes are described at the 153:ref:`Generic Error Codes <gen-errors>` chapter. 154 155EINVAL 156 The struct :c:type:`v4l2_fmtdesc` ``type`` is not 157 supported or the ``index`` is out of bounds. 158