Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENUM_FMT: |
5377d91f MH |
4 | |
5 | ********************* | |
6 | ioctl VIDIOC_ENUM_FMT | |
7 | ********************* | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_ENUM_FMT - Enumerate image formats |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp ) |
19 | :name: VIDIOC_ENUM_FMT | |
5377d91f | 20 | |
586027ce | 21 | |
15e7d615 | 22 | Arguments |
5377d91f MH |
23 | ========= |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
5377d91f MH |
28 | ``argp`` |
29 | ||
30 | ||
15e7d615 | 31 | Description |
5377d91f MH |
32 | =========== |
33 | ||
34 | To enumerate image formats applications initialize the ``type`` and | |
e8be7e97 | 35 | ``index`` field of struct :c:type:`v4l2_fmtdesc` and call |
2212ff25 | 36 | the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers |
cdb4af0f | 37 | fill the rest of the structure or return an ``EINVAL`` error code. All |
5377d91f | 38 | formats are enumerable by beginning at index zero and incrementing by |
cdb4af0f | 39 | one until ``EINVAL`` is returned. |
5377d91f | 40 | |
b6b6e678 MCC |
41 | .. note:: |
42 | ||
43 | After switching input or output the list of enumerated image | |
706f8a99 | 44 | formats may be different. |
5377d91f MH |
45 | |
46 | ||
5bd4bb78 MCC |
47 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
48 | ||
e8be7e97 | 49 | .. c:type:: v4l2_fmtdesc |
fa92b04d | 50 | |
5377d91f MH |
51 | .. flat-table:: struct v4l2_fmtdesc |
52 | :header-rows: 0 | |
53 | :stub-columns: 0 | |
54 | :widths: 1 1 2 | |
55 | ||
5377d91f MH |
56 | - .. row 1 |
57 | ||
58 | - __u32 | |
59 | ||
60 | - ``index`` | |
61 | ||
62 | - Number of the format in the enumeration, set by the application. | |
0579e6e3 | 63 | This is in no way related to the ``pixelformat`` field. |
5377d91f MH |
64 | |
65 | - .. row 2 | |
66 | ||
67 | - __u32 | |
68 | ||
69 | - ``type`` | |
70 | ||
71 | - Type of the data stream, set by the application. Only these types | |
0579e6e3 MCC |
72 | are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, |
73 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, | |
74 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, | |
75 | ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and | |
56683d7d | 76 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. |
5377d91f MH |
77 | |
78 | - .. row 3 | |
79 | ||
80 | - __u32 | |
81 | ||
82 | - ``flags`` | |
83 | ||
84 | - See :ref:`fmtdesc-flags` | |
85 | ||
86 | - .. row 4 | |
87 | ||
88 | - __u8 | |
89 | ||
8968da9b | 90 | - ``description``\ [32] |
5377d91f MH |
91 | |
92 | - Description of the format, a NUL-terminated ASCII string. This | |
0579e6e3 | 93 | information is intended for the user, for example: "YUV 4:2:2". |
5377d91f MH |
94 | |
95 | - .. row 5 | |
96 | ||
97 | - __u32 | |
98 | ||
99 | - ``pixelformat`` | |
100 | ||
101 | - The image format identifier. This is a four character code as | |
0579e6e3 | 102 | computed by the v4l2_fourcc() macro: |
5377d91f MH |
103 | |
104 | - .. row 6 | |
105 | ||
106 | - :cspan:`2` | |
107 | ||
0579e6e3 | 108 | .. _v4l2-fourcc: |
fa92b04d | 109 | |
ef76c068 MCC |
110 | ``#define v4l2_fourcc(a,b,c,d)`` |
111 | ||
112 | ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))`` | |
5377d91f | 113 | |
0579e6e3 | 114 | Several image formats are already defined by this specification in |
706f8a99 MCC |
115 | :ref:`pixfmt`. |
116 | ||
b6b6e678 MCC |
117 | .. attention:: |
118 | ||
119 | These codes are not the same as those used | |
706f8a99 | 120 | in the Windows world. |
5377d91f MH |
121 | |
122 | - .. row 7 | |
123 | ||
124 | - __u32 | |
125 | ||
8968da9b | 126 | - ``reserved``\ [4] |
5377d91f MH |
127 | |
128 | - Reserved for future extensions. Drivers must set the array to | |
0579e6e3 | 129 | zero. |
5377d91f MH |
130 | |
131 | ||
132 | ||
5bd4bb78 MCC |
133 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
134 | ||
fa92b04d MCC |
135 | .. _fmtdesc-flags: |
136 | ||
5377d91f MH |
137 | .. flat-table:: Image Format Description Flags |
138 | :header-rows: 0 | |
139 | :stub-columns: 0 | |
140 | :widths: 3 1 4 | |
141 | ||
142 | ||
143 | - .. row 1 | |
144 | ||
145 | - ``V4L2_FMT_FLAG_COMPRESSED`` | |
146 | ||
147 | - 0x0001 | |
148 | ||
149 | - This is a compressed format. | |
150 | ||
151 | - .. row 2 | |
152 | ||
153 | - ``V4L2_FMT_FLAG_EMULATED`` | |
154 | ||
155 | - 0x0002 | |
156 | ||
157 | - This format is not native to the device but emulated through | |
0579e6e3 MCC |
158 | software (usually libv4l2), where possible try to use a native |
159 | format instead for better performance. | |
5377d91f MH |
160 | |
161 | ||
15e7d615 | 162 | Return Value |
5377d91f MH |
163 | ============ |
164 | ||
165 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
166 | appropriately. The generic error codes are described at the | |
167 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
168 | ||
169 | EINVAL | |
e8be7e97 | 170 | The struct :c:type:`v4l2_fmtdesc` ``type`` is not |
5377d91f | 171 | supported or the ``index`` is out of bounds. |