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/userspace-api/media/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``, ``mbus_code``
43and ``index`` fields 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. If applicable, drivers shall return
48formats in preference order, where preferred formats are returned before
49(that is, with lower ``index`` value) less-preferred formats.
50
51Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
52the ``mbus_code`` field is handled differently:
53
541) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
55
56   Applications shall initialize the ``mbus_code`` field to zero and drivers
57   shall ignore the value of the field.
58
59   Drivers shall enumerate all image formats.
60
61   .. note::
62
63      After switching the input or output the list of enumerated image
64      formats may be different.
65
662) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
67
68   If the ``mbus_code`` field is zero, then all image formats
69   shall be enumerated.
70
71   If the ``mbus_code`` field is initialized to a valid (non-zero)
72   :ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers
73   shall restrict enumeration to only the image formats that can produce
74   (for video output devices) or be produced from (for video capture
75   devices) that media bus code. If the ``mbus_code`` is unsupported by
76   the driver, then ``EINVAL`` shall be returned.
77
78   Regardless of the value of the ``mbus_code`` field, the enumerated image
79   formats shall not depend on the active configuration of the video device
80   or device pipeline.
81
82
83.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
84
85.. c:type:: v4l2_fmtdesc
86
87.. flat-table:: struct v4l2_fmtdesc
88    :header-rows:  0
89    :stub-columns: 0
90    :widths:       1 1 2
91
92    * - __u32
93      - ``index``
94      - Number of the format in the enumeration, set by the application.
95	This is in no way related to the ``pixelformat`` field.
96    * - __u32
97      - ``type``
98      - Type of the data stream, set by the application. Only these types
99	are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
100	``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
101	``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
102	``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
103	``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
104	``V4L2_BUF_TYPE_SDR_CAPTURE``,
105	``V4L2_BUF_TYPE_SDR_OUTPUT``,
106	``V4L2_BUF_TYPE_META_CAPTURE`` and
107	``V4L2_BUF_TYPE_META_OUTPUT``.
108	See :c:type:`v4l2_buf_type`.
109    * - __u32
110      - ``flags``
111      - See :ref:`fmtdesc-flags`
112    * - __u8
113      - ``description``\ [32]
114      - Description of the format, a NUL-terminated ASCII string. This
115	information is intended for the user, for example: "YUV 4:2:2".
116    * - __u32
117      - ``pixelformat``
118      - The image format identifier. This is a four character code as
119	computed by the v4l2_fourcc() macro:
120    * - :cspan:`2`
121
122	.. _v4l2-fourcc:
123
124	``#define v4l2_fourcc(a,b,c,d)``
125
126	``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
127
128	Several image formats are already defined by this specification in
129	:ref:`pixfmt`.
130
131	.. attention::
132
133	   These codes are not the same as those used
134	   in the Windows world.
135    * - __u32
136      - ``mbus_code``
137      - Media bus code restricting the enumerated formats, set by the
138        application. Only applicable to drivers that advertise the
139        ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, shall be 0
140        otherwise.
141    * - __u32
142      - ``reserved``\ [3]
143      - Reserved for future extensions. Drivers must set the array to
144	zero.
145
146
147
148.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
149
150.. _fmtdesc-flags:
151
152.. flat-table:: Image Format Description Flags
153    :header-rows:  0
154    :stub-columns: 0
155    :widths:       3 1 4
156
157    * - ``V4L2_FMT_FLAG_COMPRESSED``
158      - 0x0001
159      - This is a compressed format.
160    * - ``V4L2_FMT_FLAG_EMULATED``
161      - 0x0002
162      - This format is not native to the device but emulated through
163	software (usually libv4l2), where possible try to use a native
164	format instead for better performance.
165    * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
166      - 0x0004
167      - The hardware decoder for this compressed bytestream format (aka coded
168	format) is capable of parsing a continuous bytestream. Applications do
169	not need to parse the bytestream themselves to find the boundaries
170	between frames/fields. This flag can only be used in combination with
171	the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
172	formats only. This flag is valid for stateful decoders only.
173    * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
174      - 0x0008
175      - Dynamic resolution switching is supported by the device for this
176	compressed bytestream format (aka coded format). It will notify the user
177	via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
178	parameters are detected. This flag can only be used in combination
179	with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
180	compressed formats only. It is also only applies to stateful codecs.
181
182
183Return Value
184============
185
186On success 0 is returned, on error -1 and the ``errno`` variable is set
187appropriately. The generic error codes are described at the
188:ref:`Generic Error Codes <gen-errors>` chapter.
189
190EINVAL
191    The struct :c:type:`v4l2_fmtdesc` ``type`` is not
192    supported or the ``index`` is out of bounds.
193
194    If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
195    is unsupported, then also return this error code.
196