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 Feature test macro: WAFFLE_API_VERSION >= 0x0103. (See
164 waffle_feature_test_macros(7)).
165 This attribute, if true, instructs waffle_context_create(3) to
167 create a forward-compatible context. However, even if
168 waffle_config_choose() successfully returns a config for a
169 forward-compatible context, the native platform may later reject it
170 when waffle_context_create(3) is called.
171 Forward-compatible contexts do not support functionality marked as
173 deprecated by that version of the API. A non-forward-compatible
174 context supports all functionality in that version, deprecated or
175 not.
176 This attribute is optional and its default value is false(0). Valid
178 values are true(1), false(0), and WAFFLE_DONT_CARE. However,
179 true(1) is valid only if the requested context API is
180 WAFFLE_CONTEXT_OPENGL and its version is at least 3.0.
181 WAFFLE_CONTEXT_DEBUG
183 Feature test macro: WAFFLE_API_VERSION >= 0x0103. (See
184 waffle_feature_test_macros(7)).
185 This attribute, if true, instructs waffle_context_create(3) to
187 create a debug context. However, even if waffle_config_choose()
188 successfully returns a config for a debug context, the native
189 platform may later reject it when waffle_context_create(3) is
190 called.
191 Debug contexts are intended for use during application development,
193 to provide additional runtime checking, validation, and logging
194 functionality while possibly incurring performance penalties. The
195 additional functionality provided by debug contexts may vary
196 according to the implementation. In some cases a debug context may
197 be identical to a non-debug context.
198 This attribute is optional and its default value is false(0). Valid
200 values are true(1), false(0), and WAFFLE_DONT_CARE.
201 WAFFLE_RED_SIZE
203 WAFFLE_GREEN_SIZE
204 WAFFLE_BLUE_SIZE
205 WAFFLE_ALPHA_SIZE
206 WAFFLE_DEPTH_SIZE
207 WAFFLE_STENCIL_SIZE
208 The default value for each size attribute is 0. Valid values are
209 the non-negative integers and WAFFLE_DONT_CARE. If the requested
210 size for a channel is 0, then any surface created with the config
211 will lack that channel. If the requested size for a channel is
212 positive, then the number of bits in that channel for any surface
213 created with the config will be at least the requested size.
214 WAFFLE_SAMPLE_BUFFERS
216 WAFFLE_SAMPLES
217 The default value of WAFFLE_SAMPLE_BUFFERS is false(0). Valid
218 values are true(1), false(0), and WAFFLE_DONT_CARE. The attribute
219 specifies if a surface created with this config is double-buffered.
220 If false, then any surface created with the config will not be
221 multisampled. If true, the any surface created with the config will
222 be multisampled, where the number of samples will be at least
223 WAFFLE_SAMPLES.
224 The default value of WAFFLE_SAMPLES is 0. Valid values are the
226 non-negative integers and WAFFLE_DONT_CARE.
227 WAFFLE_DOUBLE_BUFFERED
229 The default value is true(1). Valid values are true(1), false(0),
230 and WAFFLE_DONT_CARE. This attribute specifies if a surface created
231 with this config is double-buffered.
232 WAFFLE_ACCUM_BUFFER
234 The default value is false(0). Valid values are true(1), false(0),
235 and WAFFLE_DONT_CARE. This attribute specifies if a surface created
236 with this config possesses an accumulation buffer.
237
239 Functions whose return type is bool return true on success and false on
240 failure. Functions whose return type is a pointer return NULL on
241 failure. Use waffle_error_get_info(3) to get information about any
242 errors.
243
245 See waffle_error(3) for the complete list of waffle's error codes.
246 Listed below are the errors specific to the waffle_config functions.
248 waffle_config_choose()
250 WAFFLE_ERROR_BAD_ATTRIBUTE
252 An item in attrib_list is unrecognized or has an invalid value,
253 or a required attribute is missing.
254 WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM
256 If the native platform does not expose the necessary
257 functionality to create a context with the properties specified
258 by config or if waffle can predetermine that the native
259 platform will reject the config at context creation, but
260 otherwise the requested attributes are valid, then
261 WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM is emitted.
262 For example,
264 · GLX supports creation of an OpenGL ES2 context only if
266 libGLESv2.so.2 is installed and if
267 GLX_EXT_create_context_es2_profile is exposed as both a
268 server and client extension.
269 · MacOS does not support the OpenGL 3.2 Compatibility
271 Profile, and it supports the OpenGL 3.2 Core Profile only
272 for MacOS >= 10.7 on select GPU's.
273
276 Example 1
277 Choose a config for an OpenGL legacy context that has at least 8 bits
278 in each of the RGBA channels.
279 #include <stdlib.h>
282 #include <waffle.h>
283 static const int32_t init_attrib_list[] = {
285 WAFFLE_PLATFORM, WAFFLE_PLATFORM_GLX,
286 0,
287 };
288 static const int32_t config_attrib_list[] = {
290 WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
291 WAFFLE_RED_SIZE, 8,
293 WAFFLE_GREEN_SIZE, 8,
294 WAFFLE_BLUE_SIZE, 8,
295 WAFFLE_ALPHA_SIZE, 8,
296 0,
298 };
299 int
301 main()
302 {
303 struct waffle_display *display;
304 struct waffle_config *config;
305 bool ok;
306 ok = waffle_init(init_attrib_list);
309 if (!ok)
310 exit(EXIT_FAILURE);
311 display = waffle_display_connect(NULL);
313 if (!display)
314 exit(EXIT_FAILURE);
315 config = waffle_config_choose(config_attrib_list);
317 if (!config)
318 exit(EXIT_FAILURE);
319 // Now clean up.
321 waffle_config_destroy(config);
322 waffle_display_disconnect(display);
323 return EXIT_SUCCESS;
324 }
325 Example 2
330 An attribute list for creating an OpenGL 3.2 Core Profile context that
331 has depth and stencil buffers and some non-zero number of bits in each
332 of the RGB channels. Since the default value of WAFFLE_ALPHA_SIZE is
333 WAFFLE_DONT_CARE, the config may not have an alpha channel.
334 const int32_t attrib_list[] = {
337 WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
338 WAFFLE_CONTEXT_MAJOR_VERSION, 3,
339 WAFFLE_CONTEXT_MINOR_VERSION, 2,
340 WAFFLE_CONTEXT_PROFILE, WAFFLE_CONTEXT_CORE_PROFILE,
341 WAFFLE_RED_SIZE, 1,
343 WAFFLE_GREEN_SIZE, 1,
344 WAFFLE_BLUE_SIZE, 1,
345 WAFFLE_DEPTH_SIZE, 24,
347 WAFFLE_STENCIL_SIZE, 8,
348 0,
350 };
351
356 Please report bugs or and feature requests to
357 https://github.com/waffle-gl/waffle/issues.
358
360 waffle(7) waffle_context_create(3) waffle_window_create(3)
361
363 Chad Versace <chad.versace@linux.intel.com>
364 Maintainer
365
367 Copyright © 2013 Intel
368 This manual page is licensed under the Creative Commons
370 Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0). To
371 view a copy of this license, visit
372 http://creativecommons.org.license/by-sa/3.0/us.
373
376 1. GLX 1.4 Specification
377 http://www.opengl.org/registry/doc/glx1.4.pdf
378 2. GLX_ARB_create_context_profile
380 http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
381 3. GLX_EXT_create_context_es2_profile
383 http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
384 4. EGL 1.4 Specification
386 http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
387 5. EGL_KHR_create_context
389 http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt
390 6. CGL Reference
392 https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html
393waffle 07/27/2019 WAFFLE_CONFIG(3)