Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WAFFLE_CONFIG(3)		 Waffle	Manual		      WAFFLE_CONFIG(3)

NAME
       waffle_config, waffle_config_choose, waffle_config_destroy,
       waffle_config_get_native	- class	waffle_config

SYNOPSIS
       #include	<waffle.h>

       struct waffle_config;

       struct waffle_config*
						  waffle_config_choose(struct waffle_display *display,
						  const	int32_t	attrib_list[]);

       bool waffle_config_destroy(struct waffle_config *self);

       union waffle_native_config*
							    waffle_config_get_native(struct waffle_config *self);

DESCRIPTION
       struct waffle_config
	   An opaque type.

       waffle_config_choose()
	   Choose a config on display that satifisfies the set of attributes
	   specified by	attrib_list. The config	can later be used to create
	   surfaces and	contexts with waffle_window_create(3) and
	   waffle_context_create(3).

	   attrib_list consists	of a zero-terminated sequence of name/value
	   pairs. If an	attribute is absent from attrib_list, then it assumes
	   its default value. If attrib_list is	null, then it is intrepreted
	   the same as the empty list, which is	the list that contains only
	   the terminal	zero. See the section called "ATTRIBUTES" below	for
	   details on the set of attributes that may appear in attrib_list.

       waffle_config_destroy()
	   Destroy the config and release its memory.

       waffle_config_get_native()
	   Get the config's underlying native objects. Use free(3) to
	   deallocate the returned pointer. See	waffle_native(3) for the
	   definition of union waffle_native_config.

DISCUSSION
       The context attributes (WAFFLE_CONTEXT_*) have quirks that are specific
       to the native platform. Waffle attempts to accomdate those quirks in a
       platform-neutral	way as much as possible, but not all quirks can	be
       eliminated through a platform abstraction layer.	The quirks are
       documented below	in detail.

       For example, one	quirk that Waffle is able to accommodate is that some
       platforms require specification of context attributes at	different
       times. GLX requires that	the context attributes be specified at time of
       context creation	[glXCreateContextAttribsARB(3)]	but MacOS requires the
       attributes to be	specified when choosing	a config
       [CGLChoosePixelFormat]. Therefore, Waffle is constrained	by MacOS to
       require the attributes at time of waffle_config_choose().

       For additional documentation on the behavior of context attributes on
       each platform, refer to the following:

	   For GLX, refer to the GLX 1.4 Specification[1] and the
	   specifications for extensions GLX_ARB_create_context_profile[2] and
	   GLX_EXT_create_context_es2_profile[3].

	   For EGL, refer to the EGL 1.4 Specification[4] and the
	   specifications for extension	EGL_KHR_create_context[5].

	   For CGL, refer to the documentation of kCGLPFAOpenGLProfile in the
	   CGL Reference[6].

ATTRIBUTES
       WAFFLE_CONTEXT_API
	   This	is a required attribute; it has	no default value. It must be
	   one of:
	       WAFFLE_CONTEXT_OPENGL
	       WAFFLE_CONTEXT_OPENGL_ES1
	       WAFFLE_CONTEXT_OPENGL_ES2
	       WAFFLE_CONTEXT_OPENGL_ES3

	   The actual set of supported values depends on the native platform.
	   To check if the system supports a given API,	use
	   waffle_display_supports_context_api(3). Invariants and expectations
	   for each platform are discussed below.

	   On Android, WAFFLE_CONTEXT_OPENGL_ES1 is always supported.
	   Beginning with Ice Cream Sandwich (that is, Android 4.0),
	   WAFFLE_CONTEXT_OPENGL_ES2 is	also supported.	Use
	   waffle_display_supports_context_api(3) to check if additional APIs
	   are supported.

	   On GLX, WAFFLE_CONTEXT_OPENGL is always supported. The system may
	   optionally support additional APIs.

	   On EGL platforms other than Android,	no API is guaranteed to	be
	   supported. One must use waffle_display_supports_context_api(3) to
	   check for supported APIs.

	   On MacOS, only WAFFLE_CONTEXT_OPENGL	is supported. This may change
	   in the future if Apple adds support for additional APIs.

       WAFFLE_CONTEXT_MAJOR_VERSION
       WAFFLE_CONTEXT_MINOR_VERSION
	   This	pair of	attributes is optional.	They specify the context
	   version that	waffle_context_create(3) will request.

	   The pair's default value and	set of accepted	values depend on the
	   value of WAFFLE_CONTEXT_API and the native platform.	Below is
	   described in	detail the rules by which waffle filters the set of
	   accepted values according to	the value of WAFFLE_CONTEXT_API. Even
	   if waffle_config_choose() accepts the requested version and
	   successfully	returns	a config, the native platform may later	reject
	   the requested version when waffle_context_create(3) is called.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL_ES1, then the default
	   value is 1.0. The only accepted values are 1.0 and 1.1.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL_ES2, then the default
	   value is 2.0. Waffle	accepts	any value that is at least 2.0 and
	   strictly less than 3.0.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL_ES3, then the default
	   value is 3.0. Waffle	accepts	any value that is at least 3.0 and
	   strictly less than 4.0.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL, then the default and
	   minimum accepted value is 1.0.

       WAFFLE_CONTEXT_PROFILE
	   This	attributes is optional.	It specifies the context profile that
	   waffle_context_create(3) will request.

	   The attribute's default value and set of accepted values depend on
	   the values of WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_MAJOR_VERSION,
	   WAFFLE_CONTEXT_MINOR_VERSION, and the native	platform. Below	is
	   described in	detail the rules by which waffle decides the default
	   value and the set of	accepted values. Even if
	   waffle_config_choose() accepts the requested	profile	and
	   successfully	returns	a config, the native platform may later	reject
	   the requested profile when waffle_context_create(3) is called.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL_ES1,
	   WAFFLE_CONTEXT_OPENGL_ES2, or WAFFLE_CONTEXT_OPENGL_ES3, then the
	   default and only accepted value is WAFFLE_NONE.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL and the requested
	   version is less than	3.2, then the default and only accepted	value
	   is WAFFLE_NONE.

	   If the requested API	is WAFFLE_CONTEXT_OPENGL and the requested
	   version is at least 3.2, then default value is
	   WAFFLE_CONTEXT_CORE_PROFILE.	The set	of accepted values is
	   WAFFLE_CONTEXT_CORE_PROFILE and
	   WAFFLE_CONTEXT_COMPATIBILITY_PROFILE.

       WAFFLE_CONTEXT_FORWARD_COMPATIBLE
	   This	attribute, if true, instructs waffle_context_create(3) to
	   create a forward-compatible context.	However, even if
	   waffle_config_choose() successfully returns a config	for a
	   forward-compatible context, the native platform may later reject it
	   when	waffle_context_create(3) is called.

	   Forward-compatible contexts do not support functionality marked as
	   deprecated by that version of the API. A non-forward-compatible
	   context supports all	functionality in that version, deprecated or
	   not.

	   This	attribute is optional and its default value is false(0). Valid
	   values are true(1), false(0), and WAFFLE_DONT_CARE. However,
	   true(1) is valid only if the	requested context API is
	   WAFFLE_CONTEXT_OPENGL and its version is at least 3.0.

       WAFFLE_CONTEXT_DEBUG
	   This	attribute, if true, instructs waffle_context_create(3) to
	   create a debug context. However, even if waffle_config_choose()
	   successfully	returns	a config for a debug context, the native
	   platform may	later reject it	when waffle_context_create(3) is
	   called.

	   Debug contexts are intended for use during application development,
	   to provide additional runtime checking, validation, and logging
	   functionality while possibly	incurring performance penalties. The
	   additional functionality provided by	debug contexts may vary
	   according to	the implementation. In some cases a debug context may
	   be identical	to a non-debug context.

	   This	attribute is optional and its default value is false(0). Valid
	   values are true(1), false(0), and WAFFLE_DONT_CARE.

       WAFFLE_CONTEXT_ROBUST_ACCESS
	   This	attribute, if true, instructs waffle_context_create(3) to
	   create a robust access context.

	   Robust access contexts can implement	additional runtime checks,
	   such	as bounds checks for various operations.

	   This	attribute is optional and its default value is false(0). Valid
	   values are true(1), false(0), and WAFFLE_DONT_CARE.

       WAFFLE_RED_SIZE
       WAFFLE_GREEN_SIZE
       WAFFLE_BLUE_SIZE
       WAFFLE_ALPHA_SIZE
       WAFFLE_DEPTH_SIZE
       WAFFLE_STENCIL_SIZE
	   The default value for each size attribute is	0. Valid values	are
	   the non-negative integers and WAFFLE_DONT_CARE. If the requested
	   size	for a channel is 0, then any surface created with the config
	   will	lack that channel. If the requested size for a channel is
	   positive, then the number of	bits in	that channel for any surface
	   created with	the config will	be at least the	requested size.

       WAFFLE_SAMPLE_BUFFERS
       WAFFLE_SAMPLES
	   The default value of	WAFFLE_SAMPLE_BUFFERS is false(0). Valid
	   values are true(1), false(0), and WAFFLE_DONT_CARE. The attribute
	   specifies if	a surface created with this config is double-buffered.
	   If false, then any surface created with the config will not be
	   multisampled. If true, the any surface created with the config will
	   be multisampled, where the number of	samples	will be	at least
	   WAFFLE_SAMPLES.

	   The default value of	WAFFLE_SAMPLES is 0. Valid values are the
	   non-negative	integers and WAFFLE_DONT_CARE.

       WAFFLE_DOUBLE_BUFFERED
	   The default value is	true(1). Valid values are true(1), false(0),
	   and WAFFLE_DONT_CARE. This attribute	specifies if a surface created
	   with	this config is double-buffered.

       WAFFLE_ACCUM_BUFFER
	   The default value is	false(0). Valid	values are true(1), false(0),
	   and WAFFLE_DONT_CARE. This attribute	specifies if a surface created
	   with	this config possesses an accumulation buffer.

RETURN VALUE
       Functions whose return type is bool return true on success and false on
       failure.	Functions whose	return type is a pointer return	NULL on
       failure.	Use waffle_error_get_info(3) to	get information	about any
       errors.

ERRORS
       See waffle_error(3) for the complete list of waffle's error codes.

       Listed below are	the errors specific to the waffle_config functions.

       waffle_config_choose()

	   WAFFLE_ERROR_BAD_ATTRIBUTE
	       An item in attrib_list is unrecognized or has an	invalid	value,
	       or a required attribute is missing.

	   WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM
	       If the native platform does not expose the necessary
	       functionality to	create a context with the properties specified
	       by config or if waffle can predetermine that the	native
	       platform	will reject the	config at context creation, but
	       otherwise the requested attributes are valid, then
	       WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM is emitted.

	       For example,

	       o   GLX supports	creation of an OpenGL ES2 context only if
		   libGLESv2.so.2 is installed and if
		   GLX_EXT_create_context_es2_profile is exposed as both a
		   server and client extension.

	       o   MacOS does not support the OpenGL 3.2 Compatibility
		   Profile, and	it supports the	OpenGL 3.2 Core	Profile	only
		   for MacOS >=	10.7 on	select GPU's.

EXAMPLES
   Example 1
       Choose a	config for an OpenGL legacy context that has at	least 8	bits
       in each of the RGBA channels.

	   #include <stdlib.h>
	   #include <waffle.h>

	   static const	int32_t	init_attrib_list[] = {
	       WAFFLE_PLATFORM,	WAFFLE_PLATFORM_GLX,
	       0,
	   };

	   static const	int32_t	config_attrib_list[] = {
	       WAFFLE_CONTEXT_API, WAFFLE_CONTEXT_OPENGL,

	       WAFFLE_RED_SIZE,	   8,
	       WAFFLE_GREEN_SIZE,  8,
	       WAFFLE_BLUE_SIZE,   8,
	       WAFFLE_ALPHA_SIZE,  8,

	       0,
	   };

	   int
	   main()
	   {
	       struct waffle_display *display;
	       struct waffle_config *config;
	       bool ok;

	       ok = waffle_init(init_attrib_list);
	       if (!ok)
		 exit(EXIT_FAILURE);

	       display = waffle_display_connect(NULL);
	       if (!display)
		 exit(EXIT_FAILURE);

	       config =	waffle_config_choose(config_attrib_list);
	       if (!config)
		 exit(EXIT_FAILURE);

	       // Now clean up.
	       waffle_config_destroy(config);
	       waffle_display_disconnect(display);
	       return EXIT_SUCCESS;
	   }

   Example 2
       An attribute list for creating an OpenGL	3.2 Core Profile context that
       has depth and stencil buffers and some non-zero number of bits in each
       of the RGB channels. Since the default value of WAFFLE_ALPHA_SIZE is
       WAFFLE_DONT_CARE, the config may	not have an alpha channel.

	   const int32_t attrib_list[] = {
	       WAFFLE_CONTEXT_API,	       WAFFLE_CONTEXT_OPENGL,
	       WAFFLE_CONTEXT_MAJOR_VERSION,   3,
	       WAFFLE_CONTEXT_MINOR_VERSION,   2,
	       WAFFLE_CONTEXT_PROFILE,	       WAFFLE_CONTEXT_CORE_PROFILE,

	       WAFFLE_RED_SIZE,		       1,
	       WAFFLE_GREEN_SIZE,	       1,
	       WAFFLE_BLUE_SIZE,	       1,

	       WAFFLE_DEPTH_SIZE,	      24,
	       WAFFLE_STENCIL_SIZE,	       8,

	       0,
	   };

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

SEE ALSO
       waffle(7) waffle_context_create(3) waffle_window_create(3)

AUTHOR
       Chad Versace <chad.versace@linux.intel.com>
	   Maintainer

COPYRIGHT
       Copyright (C) 2013 Intel

       This manual page	is licensed under the Creative Commons
       Attribution-ShareAlike 3.0 United States	License	(CC BY-SA 3.0).	To
       view a copy of this license, visit
       http://creativecommons.org.license/by-sa/3.0/us.

NOTES
	1. GLX 1.4 Specification
	   http://www.opengl.org/registry/doc/glx1.4.pdf

	2. GLX_ARB_create_context_profile
	   http://www.opengl.org/registry/specs/ARB/glx_create_context.txt

	3. GLX_EXT_create_context_es2_profile
	   http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt

	4. EGL 1.4 Specification
	   http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf

	5. EGL_KHR_create_context
	   http://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_create_context.txt

	6. CGL Reference
	   https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html

waffle				  08/30/2020		      WAFFLE_CONFIG(3)

NAME | SYNOPSIS | DESCRIPTION | DISCUSSION | ATTRIBUTES | RETURN VALUE | ERRORS | EXAMPLES | ISSUES | SEE ALSO | AUTHOR | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=waffle_config&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help