Mesa (master): egl: Document why EGL_OPENGL{, _ES}_API are mostly identical

[Adam Jackson]

Module: Mesa
Branch: master
Commit: a279760536be03702a3eb133c51079907a2ccc9c
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=a279760536be03702a3eb133c51079907a2ccc9c

Author: Adam Jackson <ajax at redhat.com>
Date:   Wed Sep  7 17:41:56 2016 -0400

egl: Document why EGL_OPENGL{, _ES}_API are mostly identical

Signed-off-by: Adam Jackson <ajax at redhat.com>
Reviewed-by: Alejandro Piñeiro <apinheiro at igalia.com>

---

 src/egl/main/eglcontext.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/egl/main/eglcontext.c b/src/egl/main/eglcontext.c
index ebc004d..057b60f 100644
--- a/src/egl/main/eglcontext.c
+++ b/src/egl/main/eglcontext.c
@@ -457,6 +457,16 @@ _eglParseContextAttribList(_EGLContext *ctx, _EGLDisplay *dpy,
 /**
  * Initialize the given _EGLContext object to defaults and/or the values
  * in the attrib_list.
+ *
+ * According to EGL 1.5 Section 3.7:
+ *
+ * "EGL_OPENGL_API and EGL_OPENGL_ES_API are interchangeable for all
+ *  purposes except eglCreateContext."
+ *
+ * And since we only support GL and GLES, this is the only place where the
+ * bound API matters at all. We look up the current API from the current
+ * thread, and stash that in the context we're initializing. Our caller is
+ * responsible for determining whether that's an API it supports.
  */
 EGLBoolean
 _eglInitContext(_EGLContext *ctx, _EGLDisplay *dpy, _EGLConfig *conf,