1WAFFLE_CONFIG(3)                 Waffle Manual                WAFFLE_CONFIG(3)
2
3
4

NAME

6       waffle_config, waffle_config_choose, waffle_config_destroy,
7       waffle_config_get_native - class waffle_config
8

SYNOPSIS

10       #include <waffle.h>
11
12       struct waffle_config;
13
14
15       struct waffle_config*
16                                                  waffle_config_choose(struct waffle_display *display,
17                                                  const int32_t attrib_list[]);
18
19       bool waffle_config_destroy(struct waffle_config *self);
20
21       union waffle_native_config*
22                                                            waffle_config_get_native(struct waffle_config *self);
23

DESCRIPTION

25       struct waffle_config
26           An opaque type.
27
28       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
34           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
41
42       waffle_config_destroy()
43           Destroy the config and release its memory.
44
45       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

DISCUSSION

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
57       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
65       For additional documentation on the behavior of context attributes on
66       each platform, refer to the following:
67
68           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
72           For EGL, refer to the EGL 1.4 Specification[4] and the
73           specifications for extension EGL_KHR_create_context[5].
74
75           For CGL, refer to the documentation of kCGLPFAOpenGLProfile in the
76           CGL Reference[6].
77

ATTRIBUTES

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
87           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
92           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
98           On GLX, WAFFLE_CONTEXT_OPENGL is always supported. The system may
99           optionally support additional APIs.
100
101           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
105           On MacOS, only WAFFLE_CONTEXT_OPENGL is supported. This may change
106           in the future if Apple adds support for additional APIs.
107
108       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
113           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
121           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
124           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
128           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
132           If the requested API is WAFFLE_CONTEXT_OPENGL, then the default and
133           minimum accepted value is 1.0.
134
135       WAFFLE_CONTEXT_PROFILE
136           This attributes is optional. It specifies the context profile that
137           waffle_context_create(3) will request.
138
139           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
148           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
152           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
156           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
162       WAFFLE_CONTEXT_FORWARD_COMPATIBLE
163           Feature test macro: WAFFLE_API_VERSION >= 0x0103. (See
164           waffle_feature_test_macros(7)).
165
166           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
172           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
177           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
182       WAFFLE_CONTEXT_DEBUG
183           Feature test macro: WAFFLE_API_VERSION >= 0x0103. (See
184           waffle_feature_test_macros(7)).
185
186           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
192           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
199           This attribute is optional and its default value is false(0). Valid
200           values are true(1), false(0), and WAFFLE_DONT_CARE.
201
202       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
215       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
225           The default value of WAFFLE_SAMPLES is 0. Valid values are the
226           non-negative integers and WAFFLE_DONT_CARE.
227
228       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
233       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

RETURN VALUE

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

ERRORS

245       See waffle_error(3) for the complete list of waffle's error codes.
246
247       Listed below are the errors specific to the waffle_config functions.
248
249       waffle_config_choose()
250
251           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
255           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
263               For example,
264
265               ·   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
270               ·   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
274

EXAMPLES

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
280
281           #include <stdlib.h>
282           #include <waffle.h>
283
284           static const int32_t init_attrib_list[] = {
285               WAFFLE_PLATFORM, WAFFLE_PLATFORM_GLX,
286               0,
287           };
288
289           static const int32_t config_attrib_list[] = {
290               WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,
291
292               WAFFLE_RED_SIZE,    8,
293               WAFFLE_GREEN_SIZE,  8,
294               WAFFLE_BLUE_SIZE,   8,
295               WAFFLE_ALPHA_SIZE,  8,
296
297               0,
298           };
299
300           int
301           main()
302           {
303               struct waffle_display *display;
304               struct waffle_config *config;
305               bool ok;
306
307
308               ok = waffle_init(init_attrib_list);
309               if (!ok)
310                 exit(EXIT_FAILURE);
311
312               display = waffle_display_connect(NULL);
313               if (!display)
314                 exit(EXIT_FAILURE);
315
316               config = waffle_config_choose(config_attrib_list);
317               if (!config)
318                 exit(EXIT_FAILURE);
319
320               // Now clean up.
321               waffle_config_destroy(config);
322               waffle_display_disconnect(display);
323               return EXIT_SUCCESS;
324           }
325
326
327
328
329   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
335
336           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
342               WAFFLE_RED_SIZE,                1,
343               WAFFLE_GREEN_SIZE,              1,
344               WAFFLE_BLUE_SIZE,               1,
345
346               WAFFLE_DEPTH_SIZE,             24,
347               WAFFLE_STENCIL_SIZE,            8,
348
349               0,
350           };
351
352
353
354

ISSUES

356       Please report bugs or and feature requests to
357       https://github.com/waffle-gl/waffle/issues.
358

SEE ALSO

360       waffle(7) waffle_context_create(3) waffle_window_create(3)
361

AUTHOR

363       Chad Versace <chad.versace@linux.intel.com>
364           Maintainer
365
367       Copyright © 2013 Intel
368
369       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
374

NOTES

376        1. GLX 1.4 Specification
377           http://www.opengl.org/registry/doc/glx1.4.pdf
378
379        2. GLX_ARB_create_context_profile
380           http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
381
382        3. GLX_EXT_create_context_es2_profile
383           http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
384
385        4. EGL 1.4 Specification
386           http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
387
388        5. EGL_KHR_create_context
389           http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt
390
391        6. CGL Reference
392           https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html
393
394
395
396waffle                            07/15/2018                  WAFFLE_CONFIG(3)
Impressum