include: Add new enums WAFFLE_CONTEXT_* and document

This patch mostly consists of documentation in waffle_config.h for the new
enums.

The new enums are not yet used. Some refactoring is needed before that is
possible.

The new context attributes are associated with waffle_config_choose rather
than waffle_context_create because, on Apple, the context profile
attributes must be given to CGLChoosePixelFormat.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>

2 files changed, 145 insertions, 15 deletions

diff --git a/include/waffle/waffle_config.h b/include/waffle/waffle_config.h
index 3a309d6..f5eeab6 100644
--- a/include/waffle/waffle_config.h
+++ b/include/waffle/waffle_config.h
@@ -44,20 +44,125 @@ struct waffle_display;
 /// attrib_list is null or empty, then all attributes assume their default
 /// values.
 ///
-/// | Name                                    | Type | Default          |
-/// |:----------------------------------------|-----:|-----------------:|
-/// | WAFFLE_RED_SIZE                         |  int | WAFFLE_DONT_CARE |
-/// | WAFFLE_GREEN_SIZE                       |  int | WAFFLE_DONT_CARE |
-/// | WAFFLE_BLUE_SIZE                        |  int | WAFFLE_DONT_CARE |
-/// | WAFFLE_ALPHA_SIZE                       |  int | WAFFLE_DONT_CARE |
-/// | .                                       |    . |                . |
-/// | WAFFLE_DEPTH_SIZE                       |  int | WAFFLE_DONT_CARE |
-/// | WAFFLE_STENCIL_SIZE                     |  int | WAFFLE_DONT_CARE |
-/// | .                                       |    . |                . |
-/// | WAFFLE_SAMPLE_BUFFERS                   | bool |            false |
-/// | WAFFLE_SAMPLES                          |  int |                0 |
-/// | .                                       |    . |                . |
-/// | WAFFLE_DOUBLE_BUFFERED                  | bool |             true |
+/// Individual attributes are discussed below.
+///
+/// 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 additional documentation on the behavior of the
+/// contxt attributes on each platform, refer to the following: for GLX, refer
+/// to the [GLX_ARB_create_context_profile] and
+/// [GLX_EXT_create_context_es2_profile] extensions; for EGL, refer to the
+/// [EGL 1.4 specification]; for CGL, refer to the documentation of
+/// `kCGLPFAOpenGLProfile` in Apple's [CGL Reference].
+///
+/// For example, one quirk that Waffle is able to accomodate 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`), but MacOS requires the attributes
+/// to be specified when choosing a config (`CGLChoosePixelFormat`).
+/// Therefore, Waffle is constrained by MacOS to require the attributes at
+/// `waffle_config_choose`.
+///
+/// [GLX_ARB_create_context_profile]: http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
+/// [GLX_EXT_create_context_es2_profile]: http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
+/// [EGL 1.4 specification]: http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
+/// [CGL Reference]: https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html
+///
+///
+/// ##### `WAFFLE_CONTEXT_API` #####
+///
+/// The set of supported values for the `WAFFLE_CONTEXT_API` attribute depends
+/// on the native system.  To check if the system supports a given API, call
+/// waffle_display_supports_context_api().  Invariants and expectations for
+/// each platform are discussed below.
+///
+/// On Android, `WAFFLE_CONTEXT_OPENGL_ES1` is always supported.  If the
+/// Android version is at least 4.0, then `WAFFLE_CONTEXT_OPENGL_ES2` is
+/// supported.  Systems with earlier versions of Android may support
+/// `WAFFLE_CONTEXT_OPENGL_ES2`. No other API is supported.
+///
+/// On GLX, `WAFFLE_CONTEXT_OPENGL` is always supported. The system may
+/// support other APIs.
+///
+/// On X11/EGL and Wayland, no API is guaranteed to be supported. One must
+/// call waffle_display_supports_context_api() 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` and `WAFFLE_CONTEXT_MINOR_VERSION` #####
+///
+/// The default and supported values of the requested context version depend
+/// on the native system and the value of `WAFFLE_CONTEXT_API`.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES1` then the default and
+/// only supported version is 1.0.  The system may promote the version to 1.1.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES2`, then the default and
+/// only supported version is 2.0.
+///
+/// For all platforms, if the requested API is `WAFFLE_CONTEXT_OPENGL` then
+/// the default version is 1.0.  If the requested version is less than 3.0
+/// then the native system may promote the requested version to any greater
+/// version that is legacy-compatible.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
+/// MacOS, then the requested version must be 1.0 or 3.2.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
+/// GLX, then the version is unchecked by Waffle and passed directly to GLX at
+/// time of context creation.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
+/// an EGL platform (that is, one of Android, X11/EGL, or Wayland), then the
+/// version must be 1.0. (This restriction may be removed if, in the future,
+/// EGL allows selection of the context version).
+///
+/// ##### `WAFFLE_CONTEXT_PROFILE` #####
+///
+/// The default and supported values for the `WAFFLE_CONTEXT_PROFILE`
+/// attribute depend on the native system and the requested value of
+/// `WAFFLE_CONTEXT_API`.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES1` or
+/// `WAFFLE_CONTEXT_OPENGL_ES2`, then the default and only supported value is
+/// `WAFFLE_NONE`.
+///
+/// If the requested API is `WAFFLE_CONTEXT_OPENGL`. the the default value is
+/// `WAFFLE_CONTEXT_CORE_PROFILE`. If the requested version is less than 3.2,
+/// then `WAFFLE_CONTEXT_PROFILE` is ignored.
+///
+///
+/// | Name                                    | Type | Default          | Choices                                       |
+/// |:----------------------------------------|-----:|-----------------:|:----------------------------------------------|
+/// | WAFFLE_CONTEXT_API                      | enum |         required | (see discussion)                              |
+/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL                         |
+/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL_ES1                     |
+/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL_ES2                     |
+/// | .                                       |    . |                . | .                                             |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_CONTEXT_MAJOR_VERSION            |  int | (see discussion) | .                                             |
+/// | WAFFLE_CONTEXT_MINOR_VERSION            |  int | (see discussion) | .                                             |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_CONTEXT_PROFILE                  | enum | (see discussion) | .                                             |
+/// | .                                       |    . |                . | WAFFLE_NONE                                   |
+/// | .                                       |    . |                . | WAFFLE_CONTEXT_CORE_PROFILE                   |
+/// | .                                       |    . |                . | WAFFLE_CONTEXT_COMPATIBILITY_PROFILE          |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_RED_SIZE                         |  int | WAFFLE_DONT_CARE | .                                             |
+/// | WAFFLE_GREEN_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
+/// | WAFFLE_BLUE_SIZE                        |  int | WAFFLE_DONT_CARE | .                                             |
+/// | WAFFLE_ALPHA_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_DEPTH_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
+/// | WAFFLE_STENCIL_SIZE                     |  int | WAFFLE_DONT_CARE | .                                             |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_SAMPLE_BUFFERS                   | bool |            false | .                                             |
+/// | WAFFLE_SAMPLES                          |  int |                0 | .                                             |
+/// | .                                       |    . |                . | .                                             |
+/// | WAFFLE_DOUBLE_BUFFERED                  | bool |             true | .                                             |
 ///
 ///
 /// ### Example Attribute Lists ###
@@ -65,12 +170,25 @@ struct waffle_display;
 /// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
 /// const int32_t empty_list[] = {0};
 ///
-/// const int32_t rgb565[] = {
+/// const int32_t opengl32_rgb565[] = {
+///     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,    5,
 ///     WAFFLE_GREEN_SIZE,  6,
 ///     WAFFLE_BLUE_SIZE,   5,
 ///     0,
 /// };
+///
+/// const int32_t opengles2_z24s8[] = {
+///     WAFFLE_CONTEXT_API,      WAFFLE_CONTEXT_OPENGL_ES2,
+///
+///     WAFFLE_DEPTH_SIZE,      24,
+///     WAFFLE_STENCIL_SIZE,     8,
+///     0,
+/// };
 /// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ///
 ///
diff --git a/include/waffle/waffle_enum.h b/include/waffle/waffle_enum.h
index 3adfcab..76decad 100644
--- a/include/waffle/waffle_enum.h
+++ b/include/waffle/waffle_enum.h
@@ -69,6 +69,18 @@ enum waffle_enum {
     // For waffle_config_choose()
     // -----------------------------------------
 
+    WAFFLE_CONTEXT_API                                          = 0x020a,
+        WAFFLE_CONTEXT_OPENGL                                   = 0x020b,
+        WAFFLE_CONTEXT_OPENGL_ES1                               = 0x020c,
+        WAFFLE_CONTEXT_OPENGL_ES2                               = 0x020d,
+
+    WAFFLE_CONTEXT_MAJOR_VERSION                                = 0x020e,
+    WAFFLE_CONTEXT_MINOR_VERSION                                = 0x020f,
+
+    WAFFLE_CONTEXT_PROFILE                                      = 0x0210,
+        WAFFLE_CONTEXT_CORE_PROFILE                             = 0x0211,
+        WAFFLE_CONTEXT_COMPATIBILITY_PROFILE                    = 0x0212,
+
     WAFFLE_RED_SIZE                     = 0x0201,
     WAFFLE_GREEN_SIZE                   = 0x0202,
     WAFFLE_BLUE_SIZE                    = 0x0203,