1WAFFLE_CONFIG(3) Waffle Manual WAFFLE_CONFIG(3)
2
6 waffle_config, waffle_config_choose, waffle_config_destroy,
7 waffle_config_get_native - class waffle_config
8
10 #include <waffle.h>
11 struct waffle_config;
13 struct waffle_config*
16 waffle_config_choose(struct waffle_display *display,
17 const int32_t attrib_list[]);
18 bool waffle_config_destroy(struct waffle_config *self);
20 union waffle_native_config*
22 waffle_config_get_native(struct waffle_config *self);
23
25 struct waffle_config
26 An opaque type.
27 waffle_config_choose()
29 Choose a config on display that satifisfies the set of attributes
30 specified by attrib_list. The config can later be used to create
31 surfaces and contexts with waffle_window_create(3) and
32 waffle_context_create(3).
33 attrib_list consists of a zero-terminated sequence of name/value
35 pairs. If an attribute is absent from attrib_list, then it assumes
36 its default value. If attrib_list is null, then it is intrepreted
37 the same as the empty list, which is the list that contains only
38 the terminal zero. See the section called “ATTRIBUTES” below for
39 details on the set of attributes that may appear in attrib_list.
40 waffle_config_destroy()
43 Destroy the config and release its memory.
44 waffle_config_get_native()
46 Get the config's underlying native objects. Use free(3) to
47 deallocate the returned pointer. See waffle_native(3) for the
48 definition of union waffle_native_config.
49
51 The context attributes (WAFFLE_CONTEXT_*) have quirks that are specific
52 to the native platform. Waffle attempts to accomdate those quirks in a
53 platform-neutral way as much as possible, but not all quirks can be
54 eliminated through a platform abstraction layer. The quirks are
55 documented below in detail.
56 For example, one quirk that Waffle is able to accommodate is that some
58 platforms require specification of context attributes at different
59 times. GLX requires that the context attributes be specified at time of
60 context creation [glXCreateContextAttribsARB(3)] but MacOS requires the
61 attributes to be specified when choosing a config
62 [CGLChoosePixelFormat]. Therefore, Waffle is constrained by MacOS to
63 require the attributes at time of waffle_config_choose().
64 For additional documentation on the behavior of context attributes on
66 each platform, refer to the following:
67 For GLX, refer to the GLX 1.4 Specification[1] and the
69 specifications for extensions GLX_ARB_create_context_profile[2] and
70 GLX_EXT_create_context_es2_profile[3].
71 For EGL, refer to the EGL 1.4 Specification[4] and the
73 specifications for extension EGL_KHR_create_context[5].
74 For CGL, refer to the documentation of kCGLPFAOpenGLProfile in the
76 CGL Reference[6].
77
79 WAFFLE_CONTEXT_API
80 This is a required attribute; it has no default value. It must be
81 one of:
82 WAFFLE_CONTEXT_OPENGL
83 WAFFLE_CONTEXT_OPENGL_ES1
84 WAFFLE_CONTEXT_OPENGL_ES2
85 WAFFLE_CONTEXT_OPENGL_ES3
86 The actual set of supported values depends on the native platform.
88 To check if the system supports a given API, use
89 waffle_display_supports_context_api(3). Invariants and expectations
90 for each platform are discussed below.
91 On Android, WAFFLE_CONTEXT_OPENGL_ES1 is always supported.
93 Beginning with Ice Cream Sandwich (that is, Android 4.0),
94 WAFFLE_CONTEXT_OPENGL_ES2 is also supported. Use
95 waffle_display_supports_context_api(3) to check if additional APIs
96 are supported.
97 On GLX, WAFFLE_CONTEXT_OPENGL is always supported. The system may
99 optionally support additional APIs.
100 On EGL platforms other than Android, no API is guaranteed to be
102 supported. One must use waffle_display_supports_context_api(3) to
103 check for supported APIs.
104 On MacOS, only WAFFLE_CONTEXT_OPENGL is supported. This may change
106 in the future if Apple adds support for additional APIs.
107 WAFFLE_CONTEXT_MAJOR_VERSION
109 WAFFLE_CONTEXT_MINOR_VERSION
110 This pair of attributes is optional. They specify the context
111 version that waffle_context_create(3) will request.
112 The pair's default value and set of accepted values depend on the
114 value of WAFFLE_CONTEXT_API and the native platform. Below is
115 described in detail the rules by which waffle filters the set of
116 accepted values according to the value of WAFFLE_CONTEXT_API. Even
117 if waffle_config_choose() accepts the requested version and
118 successfully returns a config, the native platform may later reject
119 the requested version when waffle_context_create(3) is called.
120 If the requested API is WAFFLE_CONTEXT_OPENGL_ES1, then the default
122 value is 1.0. The only accepted values are 1.0 and 1.1.
123 If the requested API is WAFFLE_CONTEXT_OPENGL_ES2, then the default
125 value is 2.0. Waffle accepts any value that is at least 2.0 and
126 strictly less than 3.0.
127 If the requested API is WAFFLE_CONTEXT_OPENGL_ES3, then the default
129 value is 3.0. Waffle accepts any value that is at least 3.0 and
130 strictly less than 4.0.
131 If the requested API is WAFFLE_CONTEXT_OPENGL, then the default and
133 minimum accepted value is 1.0.
134 WAFFLE_CONTEXT_PROFILE
136 This attributes is optional. It specifies the context profile that
137 waffle_context_create(3) will request.
138 The attribute's default value and set of accepted values depend on
140 the values of WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_MAJOR_VERSION,
141 WAFFLE_CONTEXT_MINOR_VERSION, and the native platform. Below is
142 described in detail the rules by which waffle decides the default
143 value and the set of accepted values. Even if
144 waffle_config_choose() accepts the requested profile and
145 successfully returns a config, the native platform may later reject
146 the requested profile when waffle_context_create(3) is called.
147 If the requested API is WAFFLE_CONTEXT_OPENGL_ES1,
149 WAFFLE_CONTEXT_OPENGL_ES2, or WAFFLE_CONTEXT_OPENGL_ES3, then the
150 default and only accepted value is WAFFLE_NONE.
151 If the requested API is WAFFLE_CONTEXT_OPENGL and the requested
153 version is less than 3.2, then the default and only accepted value
154 is WAFFLE_NONE.
155 If the requested API is WAFFLE_CONTEXT_OPENGL and the requested
157 version is at least 3.2, then default value is
158 WAFFLE_CONTEXT_CORE_PROFILE. The set of accepted values is
159 WAFFLE_CONTEXT_CORE_PROFILE and
160 WAFFLE_CONTEXT_COMPATIBILITY_PROFILE.
161 WAFFLE_CONTEXT_FORWARD_COMPATIBLE
163 This attribute, if true, instructs waffle_context_create(3) to
164 create a forward-compatible context. However, even if
165 waffle_config_choose() successfully returns a config for a
166 forward-compatible context, the native platform may later reject it
167 when waffle_context_create(3) is called.
168 Forward-compatible contexts do not support functionality marked as
170 deprecated by that version of the API. A non-forward-compatible
171 context supports all functionality in that version, deprecated or
172 not.
173 This attribute is optional and its default value is false(0). Valid
175 values are true(1), false(0), and WAFFLE_DONT_CARE. However,
176 true(1) is valid only if the requested context API is
177 WAFFLE_CONTEXT_OPENGL and its version is at least 3.0.
178 WAFFLE_CONTEXT_DEBUG
180 This attribute, if true, instructs waffle_context_create(3) to
181 create a debug context. However, even if waffle_config_choose()
182 successfully returns a config for a debug context, the native
183 platform may later reject it when waffle_context_create(3) is
184 called.
185 Debug contexts are intended for use during application development,
187 to provide additional runtime checking, validation, and logging
188 functionality while possibly incurring performance penalties. The
189 additional functionality provided by debug contexts may vary
190 according to the implementation. In some cases a debug context may
191 be identical to a non-debug context.
192 This attribute is optional and its default value is false(0). Valid
194 values are true(1), false(0), and WAFFLE_DONT_CARE.
195 WAFFLE_CONTEXT_ROBUST_ACCESS
197 This attribute, if true, instructs waffle_context_create(3) to
198 create a robust access context.
199 Robust access contexts can implement additional runtime checks,
201 such as bounds checks for various operations.
202 This attribute is optional and its default value is false(0). Valid
204 values are true(1), false(0), and WAFFLE_DONT_CARE.
205 WAFFLE_RED_SIZE
207 WAFFLE_GREEN_SIZE
208 WAFFLE_BLUE_SIZE
209 WAFFLE_ALPHA_SIZE
210 WAFFLE_DEPTH_SIZE
211 WAFFLE_STENCIL_SIZE
212 The default value for each size attribute is 0. Valid values are
213 the non-negative integers and WAFFLE_DONT_CARE. If the requested
214 size for a channel is 0, then any surface created with the config
215 will lack that channel. If the requested size for a channel is
216 positive, then the number of bits in that channel for any surface
217 created with the config will be at least the requested size.
218 WAFFLE_SAMPLE_BUFFERS
220 WAFFLE_SAMPLES
221 The default value of WAFFLE_SAMPLE_BUFFERS is false(0). Valid
222 values are true(1), false(0), and WAFFLE_DONT_CARE. The attribute
223 specifies if a surface created with this config is double-buffered.
224 If false, then any surface created with the config will not be
225 multisampled. If true, the any surface created with the config will
226 be multisampled, where the number of samples will be at least
227 WAFFLE_SAMPLES.
228 The default value of WAFFLE_SAMPLES is 0. Valid values are the
230 non-negative integers and WAFFLE_DONT_CARE.
231 WAFFLE_DOUBLE_BUFFERED
233 The default value is true(1). Valid values are true(1), false(0),
234 and WAFFLE_DONT_CARE. This attribute specifies if a surface created
235 with this config is double-buffered.
236 WAFFLE_ACCUM_BUFFER
238 The default value is false(0). Valid values are true(1), false(0),
239 and WAFFLE_DONT_CARE. This attribute specifies if a surface created
240 with this config possesses an accumulation buffer.
241
243 Functions whose return type is bool return true on success and false on
244 failure. Functions whose return type is a pointer return NULL on
245 failure. Use waffle_error_get_info(3) to get information about any
246 errors.
247
249 See waffle_error(3) for the complete list of waffle's error codes.
250 Listed below are the errors specific to the waffle_config functions.
252 waffle_config_choose()
254 WAFFLE_ERROR_BAD_ATTRIBUTE
256 An item in attrib_list is unrecognized or has an invalid value,
257 or a required attribute is missing.
258 WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM
260 If the native platform does not expose the necessary
261 functionality to create a context with the properties specified
262 by config or if waffle can predetermine that the native
263 platform will reject the config at context creation, but
264 otherwise the requested attributes are valid, then
265 WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM is emitted.
266 For example,
268 • GLX supports creation of an OpenGL ES2 context only if
270 libGLESv2.so.2 is installed and if
271 GLX_EXT_create_context_es2_profile is exposed as both a
272 server and client extension.
273 • MacOS does not support the OpenGL 3.2 Compatibility
275 Profile, and it supports the OpenGL 3.2 Core Profile only
276 for MacOS >= 10.7 on select GPU's.
277
280 Example 1
281 Choose a config for an OpenGL legacy context that has at least 8 bits
282 in each of the RGBA channels.
283 #include <stdlib.h>
286 #include <waffle.h>
287 static const int32_t init_attrib_list[] = {
289 WAFFLE_PLATFORM, WAFFLE_PLATFORM_GLX,
290 0,
291 };
292 static const int32_t config_attrib_list[] = {
294 WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
295 WAFFLE_RED_SIZE, 8,
297 WAFFLE_GREEN_SIZE, 8,
298 WAFFLE_BLUE_SIZE, 8,
299 WAFFLE_ALPHA_SIZE, 8,
300 0,
302 };
303 int
305 main()
306 {
307 struct waffle_display *display;
308 struct waffle_config *config;
309 bool ok;
310 ok = waffle_init(init_attrib_list);
313 if (!ok)
314 exit(EXIT_FAILURE);
315 display = waffle_display_connect(NULL);
317 if (!display)
318 exit(EXIT_FAILURE);
319 config = waffle_config_choose(config_attrib_list);
321 if (!config)
322 exit(EXIT_FAILURE);
323 // Now clean up.
325 waffle_config_destroy(config);
326 waffle_display_disconnect(display);
327 return EXIT_SUCCESS;
328 }
329 Example 2
334 An attribute list for creating an OpenGL 3.2 Core Profile context that
335 has depth and stencil buffers and some non-zero number of bits in each
336 of the RGB channels. Since the default value of WAFFLE_ALPHA_SIZE is
337 WAFFLE_DONT_CARE, the config may not have an alpha channel.
338 const int32_t attrib_list[] = {
341 WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
342 WAFFLE_CONTEXT_MAJOR_VERSION, 3,
343 WAFFLE_CONTEXT_MINOR_VERSION, 2,
344 WAFFLE_CONTEXT_PROFILE, WAFFLE_CONTEXT_CORE_PROFILE,
345 WAFFLE_RED_SIZE, 1,
347 WAFFLE_GREEN_SIZE, 1,
348 WAFFLE_BLUE_SIZE, 1,
349 WAFFLE_DEPTH_SIZE, 24,
351 WAFFLE_STENCIL_SIZE, 8,
352 0,
354 };
355
360 Please report bugs or and feature requests to
361 https://gitlab.freedesktop.org/mesa/waffle/issues.
362
364 waffle(7) waffle_context_create(3) waffle_window_create(3)
365
367 Chad Versace <chad.versace@linux.intel.com>
368 Maintainer
369
371 Copyright © 2013 Intel
372 This manual page is licensed under the Creative Commons
374 Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0). To
375 view a copy of this license, visit
376 http://creativecommons.org.license/by-sa/3.0/us.
377
380 1. GLX 1.4 Specification
381 http://www.opengl.org/registry/doc/glx1.4.pdf
382 2. GLX_ARB_create_context_profile
384 http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
385 3. GLX_EXT_create_context_es2_profile
387 http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
388 4. EGL 1.4 Specification
390 http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
391 5. EGL_KHR_create_context
393 http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt
394 6. CGL Reference
396 https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html
397waffle 07/22/2023 WAFFLE_CONFIG(3)