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           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
169           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
174           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
179       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
186           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
193           This attribute is optional and its default value is false(0). Valid
194           values are true(1), false(0), and WAFFLE_DONT_CARE.
195
196       WAFFLE_CONTEXT_ROBUST_ACCESS
197           This attribute, if true, instructs waffle_context_create(3) to
198           create a robust access context.
199
200           Robust access contexts can implement additional runtime checks,
201           such as bounds checks for various operations.
202
203           This attribute is optional and its default value is false(0). Valid
204           values are true(1), false(0), and WAFFLE_DONT_CARE.
205
206       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
219       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
229           The default value of WAFFLE_SAMPLES is 0. Valid values are the
230           non-negative integers and WAFFLE_DONT_CARE.
231
232       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
237       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

RETURN VALUE

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

ERRORS

249       See waffle_error(3) for the complete list of waffle's error codes.
250
251       Listed below are the errors specific to the waffle_config functions.
252
253       waffle_config_choose()
254
255           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
259           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
267               For example,
268
269               •   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
274               •   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
278

EXAMPLES

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

ISSUES

360       Please report bugs or and feature requests to
361       https://gitlab.freedesktop.org/mesa/waffle/issues.
362

SEE ALSO

364       waffle(7) waffle_context_create(3) waffle_window_create(3)
365

AUTHOR

367       Chad Versace <chad.versace@linux.intel.com>
368           Maintainer
369
371       Copyright © 2013 Intel
372
373       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
378

NOTES

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