1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _VIDIOC_ENUM_FMT: 4 .. _VIDIOC_ENUM_FMT:
5 5
6 ********************* 6 *********************
7 ioctl VIDIOC_ENUM_FMT 7 ioctl VIDIOC_ENUM_FMT
8 ********************* 8 *********************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 VIDIOC_ENUM_FMT - Enumerate image formats 13 VIDIOC_ENUM_FMT - Enumerate image formats
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: VIDIOC_ENUM_FMT 18 .. c:macro:: VIDIOC_ENUM_FMT
19 19
20 ``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4 20 ``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)``
21 21
22 Arguments 22 Arguments
23 ========= 23 =========
24 24
25 ``fd`` 25 ``fd``
26 File descriptor returned by :c:func:`open( 26 File descriptor returned by :c:func:`open()`.
27 27
28 ``argp`` 28 ``argp``
29 Pointer to struct :c:type:`v4l2_fmtdesc`. 29 Pointer to struct :c:type:`v4l2_fmtdesc`.
30 30
31 Description 31 Description
32 =========== 32 ===========
33 33
34 To enumerate image formats applications initia 34 To enumerate image formats applications initialize the ``type``, ``mbus_code``
35 and ``index`` fields of struct :c:type:`v4l2_f 35 and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
36 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointe 36 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
37 fill the rest of the structure or return an `` 37 fill the rest of the structure or return an ``EINVAL`` error code. All
38 formats are enumerable by beginning at index z 38 formats are enumerable by beginning at index zero and incrementing by
39 one until ``EINVAL`` is returned. If applicabl 39 one until ``EINVAL`` is returned. If applicable, drivers shall return
40 formats in preference order, where preferred f 40 formats in preference order, where preferred formats are returned before
41 (that is, with lower ``index`` value) less-pre 41 (that is, with lower ``index`` value) less-preferred formats.
42 42
43 Depending on the ``V4L2_CAP_IO_MC`` :ref:`capa 43 Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
44 the ``mbus_code`` field is handled differently 44 the ``mbus_code`` field is handled differently:
45 45
46 1) ``V4L2_CAP_IO_MC`` is not set (also known a 46 1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
47 47
48 Applications shall initialize the ``mbus_co 48 Applications shall initialize the ``mbus_code`` field to zero and drivers
49 shall ignore the value of the field. 49 shall ignore the value of the field.
50 50
51 Drivers shall enumerate all image formats. 51 Drivers shall enumerate all image formats.
52 52
53 .. note:: 53 .. note::
54 54
55 After switching the input or output the 55 After switching the input or output the list of enumerated image
56 formats may be different. 56 formats may be different.
57 57
58 2) ``V4L2_CAP_IO_MC`` is set (also known as an 58 2) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
59 59
60 If the ``mbus_code`` field is zero, then al 60 If the ``mbus_code`` field is zero, then all image formats
61 shall be enumerated. 61 shall be enumerated.
62 62
63 If the ``mbus_code`` field is initialized t 63 If the ``mbus_code`` field is initialized to a valid (non-zero)
64 :ref:`media bus format code <v4l2-mbus-pixe 64 :ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers
65 shall restrict enumeration to only the imag 65 shall restrict enumeration to only the image formats that can produce
66 (for video output devices) or be produced f 66 (for video output devices) or be produced from (for video capture
67 devices) that media bus code. If the ``mbus 67 devices) that media bus code. If the ``mbus_code`` is unsupported by
68 the driver, then ``EINVAL`` shall be return 68 the driver, then ``EINVAL`` shall be returned.
69 69
70 Regardless of the value of the ``mbus_code` 70 Regardless of the value of the ``mbus_code`` field, the enumerated image
71 formats shall not depend on the active conf 71 formats shall not depend on the active configuration of the video device
72 or device pipeline. 72 or device pipeline.
73 73
74 .. c:type:: v4l2_fmtdesc 74 .. c:type:: v4l2_fmtdesc
75 75
76 .. cssclass:: longtable 76 .. cssclass:: longtable
77 77
78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm 78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
79 79
80 .. flat-table:: struct v4l2_fmtdesc 80 .. flat-table:: struct v4l2_fmtdesc
81 :header-rows: 0 81 :header-rows: 0
82 :stub-columns: 0 82 :stub-columns: 0
83 :widths: 1 1 2 83 :widths: 1 1 2
84 84
85 * - __u32 85 * - __u32
86 - ``index`` 86 - ``index``
87 - Number of the format in the enumeratio 87 - Number of the format in the enumeration, set by the application.
88 This is in no way related to the ``pix 88 This is in no way related to the ``pixelformat`` field.
89 * - __u32 89 * - __u32
90 - ``type`` 90 - ``type``
91 - Type of the data stream, set by the ap 91 - Type of the data stream, set by the application. Only these types
92 are valid here: ``V4L2_BUF_TYPE_VIDEO_ 92 are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
93 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` 93 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
94 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, 94 ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
95 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, 95 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
96 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, 96 ``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
97 ``V4L2_BUF_TYPE_SDR_CAPTURE``, 97 ``V4L2_BUF_TYPE_SDR_CAPTURE``,
98 ``V4L2_BUF_TYPE_SDR_OUTPUT``, 98 ``V4L2_BUF_TYPE_SDR_OUTPUT``,
99 ``V4L2_BUF_TYPE_META_CAPTURE`` and 99 ``V4L2_BUF_TYPE_META_CAPTURE`` and
100 ``V4L2_BUF_TYPE_META_OUTPUT``. 100 ``V4L2_BUF_TYPE_META_OUTPUT``.
101 See :c:type:`v4l2_buf_type`. 101 See :c:type:`v4l2_buf_type`.
102 * - __u32 102 * - __u32
103 - ``flags`` 103 - ``flags``
104 - See :ref:`fmtdesc-flags` 104 - See :ref:`fmtdesc-flags`
105 * - __u8 105 * - __u8
106 - ``description``\ [32] 106 - ``description``\ [32]
107 - Description of the format, a NUL-termi 107 - Description of the format, a NUL-terminated ASCII string. This
108 information is intended for the user, 108 information is intended for the user, for example: "YUV 4:2:2".
109 * - __u32 109 * - __u32
110 - ``pixelformat`` 110 - ``pixelformat``
111 - The image format identifier. This is a 111 - The image format identifier. This is a four character code as
112 computed by the v4l2_fourcc() macro: 112 computed by the v4l2_fourcc() macro:
113 * - :cspan:`2` 113 * - :cspan:`2`
114 114
115 .. _v4l2-fourcc: 115 .. _v4l2-fourcc:
116 116
117 ``#define v4l2_fourcc(a,b,c,d)`` 117 ``#define v4l2_fourcc(a,b,c,d)``
118 118
119 ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((_ 119 ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
120 120
121 Several image formats are already defi 121 Several image formats are already defined by this specification in
122 :ref:`pixfmt`. 122 :ref:`pixfmt`.
123 123
124 .. attention:: 124 .. attention::
125 125
126 These codes are not the same as tho 126 These codes are not the same as those used
127 in the Windows world. 127 in the Windows world.
128 * - __u32 128 * - __u32
129 - ``mbus_code`` 129 - ``mbus_code``
130 - Media bus code restricting the enumera 130 - Media bus code restricting the enumerated formats, set by the
131 application. Only applicable to driver 131 application. Only applicable to drivers that advertise the
132 ``V4L2_CAP_IO_MC`` :ref:`capability <d 132 ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, shall be 0
133 otherwise. 133 otherwise.
134 * - __u32 134 * - __u32
135 - ``reserved``\ [3] 135 - ``reserved``\ [3]
136 - Reserved for future extensions. Driver 136 - Reserved for future extensions. Drivers must set the array to
137 zero. 137 zero.
138 138
139 139
140 .. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm 140 .. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}|
141 141
142 .. cssclass:: longtable 142 .. cssclass:: longtable
143 143
144 .. _fmtdesc-flags: 144 .. _fmtdesc-flags:
145 145
146 .. flat-table:: Image Format Description Flags 146 .. flat-table:: Image Format Description Flags
147 :header-rows: 0 147 :header-rows: 0
148 :stub-columns: 0 148 :stub-columns: 0
149 :widths: 3 1 4 149 :widths: 3 1 4
150 150
151 * - ``V4L2_FMT_FLAG_COMPRESSED`` 151 * - ``V4L2_FMT_FLAG_COMPRESSED``
152 - 0x0001 152 - 0x0001
153 - This is a compressed format. 153 - This is a compressed format.
154 * - ``V4L2_FMT_FLAG_EMULATED`` 154 * - ``V4L2_FMT_FLAG_EMULATED``
155 - 0x0002 155 - 0x0002
156 - This format is not native to the devic 156 - This format is not native to the device but emulated through
157 software (usually libv4l2), where poss 157 software (usually libv4l2), where possible try to use a native
158 format instead for better performance. 158 format instead for better performance.
159 * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM` 159 * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
160 - 0x0004 160 - 0x0004
161 - The hardware decoder for this compress 161 - The hardware decoder for this compressed bytestream format (aka coded
162 format) is capable of parsing a contin 162 format) is capable of parsing a continuous bytestream. Applications do
163 not need to parse the bytestream thems 163 not need to parse the bytestream themselves to find the boundaries
164 between frames/fields. 164 between frames/fields.
165 165
166 This flag can only be used in combinat 166 This flag can only be used in combination with the
167 ``V4L2_FMT_FLAG_COMPRESSED`` flag, sin 167 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
168 formats only. This flag is valid for s 168 formats only. This flag is valid for stateful decoders only.
169 * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` 169 * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
170 - 0x0008 170 - 0x0008
171 - Dynamic resolution switching is suppor 171 - Dynamic resolution switching is supported by the device for this
172 compressed bytestream format (aka code 172 compressed bytestream format (aka coded format). It will notify the user
173 via the event ``V4L2_EVENT_SOURCE_CHAN 173 via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
174 parameters are detected. 174 parameters are detected.
175 175
176 This flag can only be used in combinat 176 This flag can only be used in combination with the
177 ``V4L2_FMT_FLAG_COMPRESSED`` flag, sin 177 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
178 compressed formats only. This flag is 178 compressed formats only. This flag is valid for stateful codecs only.
179 * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL 179 * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL``
180 - 0x0010 180 - 0x0010
181 - The hardware encoder supports setting 181 - The hardware encoder supports setting the ``CAPTURE`` coded frame
182 interval separately from the ``OUTPUT` 182 interval separately from the ``OUTPUT`` raw frame interval.
183 Setting the ``OUTPUT`` raw frame inter 183 Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>`
184 also sets the ``CAPTURE`` coded frame 184 also sets the ``CAPTURE`` coded frame interval to the same value.
185 If this flag is set, then the ``CAPTUR 185 If this flag is set, then the ``CAPTURE`` coded frame interval can be
186 set to a different value afterwards. T 186 set to a different value afterwards. This is typically used for
187 offline encoding where the ``OUTPUT`` 187 offline encoding where the ``OUTPUT`` raw frame interval is used as
188 a hint for reserving hardware encoder 188 a hint for reserving hardware encoder resources and the ``CAPTURE`` coded
189 frame interval is the actual frame rat 189 frame interval is the actual frame rate embedded in the encoded video
190 stream. 190 stream.
191 191
192 This flag can only be used in combinat 192 This flag can only be used in combination with the
193 ``V4L2_FMT_FLAG_COMPRESSED`` flag, sin 193 ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
194 compressed formats only. This flag is 194 compressed formats only. This flag is valid for stateful encoders only.
195 * - ``V4L2_FMT_FLAG_CSC_COLORSPACE`` 195 * - ``V4L2_FMT_FLAG_CSC_COLORSPACE``
196 - 0x0020 196 - 0x0020
197 - The driver allows the application to t 197 - The driver allows the application to try to change the default
198 colorspace. This flag is relevant only 198 colorspace. This flag is relevant only for capture devices.
199 The application can ask to configure t 199 The application can ask to configure the colorspace of the capture device
200 when calling the :ref:`VIDIOC_S_FMT <V 200 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
201 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2- 201 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
202 * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC`` 202 * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC``
203 - 0x0040 203 - 0x0040
204 - The driver allows the application to t 204 - The driver allows the application to try to change the default
205 transfer function. This flag is releva 205 transfer function. This flag is relevant only for capture devices.
206 The application can ask to configure t 206 The application can ask to configure the transfer function of the capture
207 device when calling the :ref:`VIDIOC_S 207 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
208 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2- 208 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
209 * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC`` 209 * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC``
210 - 0x0080 210 - 0x0080
211 - The driver allows the application to t 211 - The driver allows the application to try to change the default
212 Y'CbCr encoding. This flag is relevant 212 Y'CbCr encoding. This flag is relevant only for capture devices.
213 The application can ask to configure t 213 The application can ask to configure the Y'CbCr encoding of the capture device
214 when calling the :ref:`VIDIOC_S_FMT <V 214 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
215 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2- 215 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
216 * - ``V4L2_FMT_FLAG_CSC_HSV_ENC`` 216 * - ``V4L2_FMT_FLAG_CSC_HSV_ENC``
217 - 0x0080 217 - 0x0080
218 - The driver allows the application to t 218 - The driver allows the application to try to change the default
219 HSV encoding. This flag is relevant on 219 HSV encoding. This flag is relevant only for capture devices.
220 The application can ask to configure t 220 The application can ask to configure the HSV encoding of the capture device
221 when calling the :ref:`VIDIOC_S_FMT <V 221 when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
222 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2- 222 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
223 * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION`` 223 * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION``
224 - 0x0100 224 - 0x0100
225 - The driver allows the application to t 225 - The driver allows the application to try to change the default
226 quantization. This flag is relevant on 226 quantization. This flag is relevant only for capture devices.
227 The application can ask to configure t 227 The application can ask to configure the quantization of the capture
228 device when calling the :ref:`VIDIOC_S 228 device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
229 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2- 229 :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
230 * - ``V4L2_FMT_FLAG_META_LINE_BASED`` 230 * - ``V4L2_FMT_FLAG_META_LINE_BASED``
231 - 0x0200 231 - 0x0200
232 - The metadata format is line-based. In 232 - The metadata format is line-based. In this case the ``width``,
233 ``height`` and ``bytesperline`` fields 233 ``height`` and ``bytesperline`` fields of :c:type:`v4l2_meta_format` are
234 valid. The buffer consists of ``height 234 valid. The buffer consists of ``height`` lines, each having ``width``
235 Data Units of data and the offset (in 235 Data Units of data and the offset (in bytes) between the beginning of
236 each two consecutive lines is ``bytesp 236 each two consecutive lines is ``bytesperline``.
237 237
238 Return Value 238 Return Value
239 ============ 239 ============
240 240
241 On success 0 is returned, on error -1 and the 241 On success 0 is returned, on error -1 and the ``errno`` variable is set
242 appropriately. The generic error codes are des 242 appropriately. The generic error codes are described at the
243 :ref:`Generic Error Codes <gen-errors>` chapte 243 :ref:`Generic Error Codes <gen-errors>` chapter.
244 244
245 EINVAL 245 EINVAL
246 The struct :c:type:`v4l2_fmtdesc` ``type`` 246 The struct :c:type:`v4l2_fmtdesc` ``type`` is not
247 supported or the ``index`` is out of bound 247 supported or the ``index`` is out of bounds.
248 248
249 If ``V4L2_CAP_IO_MC`` is set and the speci 249 If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
250 is unsupported, then also return this erro 250 is unsupported, then also return this error code.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.