Deprecate MAGNUM_TARGET_GLES3.

Originally (2012? 2013?) I expected that there would eventually be
OpenGL ES 4.0, thus it made sense to differentiate between ES2, ES3 and
something else ES yet unknown. But as ES4 was increasingly unlikely to
happen, the internal code treated MAGNUM_TARGET_GLES3 as a simple
inverse of MAGNUM_TARGET_GLES2, and only in a very few places,
only adding confusion.

Thus it's now deprecated and defined as a simple inverse of
MAGNUM_TARGET_GLES2 on MAGNUM_TARGET_GLES builds, and none of the
internal code uses it anymore.

CMakeLists.txt

@@ -594,7 +594,7 @@ endif()
 
 # Dependent configuration variables
 if(MAGNUM_TARGET_GLES)
-    if(NOT MAGNUM_TARGET_GLES2)
+    if(MAGNUM_BUILD_DEPRECATED AND NOT MAGNUM_TARGET_GLES2)
         set(MAGNUM_TARGET_GLES3 1)
     endif()
     if(CORRADE_TARGET_EMSCRIPTEN)

doc/changelog.dox

@@ -1198,6 +1198,11 @@ See also:
     disabling it on GLES will force creation of a GLES context using the GLX /
     WGL libraries (if available); enabling it on desktop GL will allow running
     windowless applications on headless machines.
+-   The @cpp MAGNUM_TARGET_GLES3 @&e CMake and preprocessor variable existed
+    solely in anticipation of there eventually being OpenGL ES 4.0. That is
+    increasingly unlikely to happen and most of the internal code treated it as
+    a simple inverse of @ref MAGNUM_TARGET_GLES2, thus it's deprecated in favor
+    of that.
 -   All @ref building-features "CMake build options" are now prefixed with
     `MAGNUM_`. For backwards compatibility, unless @ref MAGNUM_BUILD_DEPRECATED
     is disabled and unless a prefixed option is already set during the initial

doc/cmake.dox

@@ -326,9 +326,9 @@ are also available as preprocessor variables if including
 -   `MAGNUM_TARGET_GL` --- Defined if compiled with OpenGL interoperability
     enabled
 -   `MAGNUM_TARGET_GLES` --- Defined if compiled for OpenGL ES
--   `MAGNUM_TARGET_GLES2` --- Defined if compiled for OpenGL ES 2.0
--   `MAGNUM_TARGET_GLES3` --- Defined if compiled for OpenGL ES 3.0
 -   `MAGNUM_TARGET_WEBGL` --- Defined if compiled for WebGL
+-   `MAGNUM_TARGET_GLES2` --- Defined if compiled for OpenGL ES 2.0 / WebGL 1
+    instead of OpenGL ES 3.0+ / WebGL 2
 -   `MAGNUM_TARGET_EGL` --- Defined if compiled for EGL instead of a
     platform-specific OpenGL support library such as CGL, EAGL, GLX or WGL.
 -   `MAGNUM_TARGET_VK` --- Defined if compiled with Vulkan interoperability
@@ -344,6 +344,8 @@ release:
     Android, Emscripten or Windows RT. Use @ref MAGNUM_TARGET_EGL instead.
 -   `MAGNUM_TARGET_DESKTOP_GLES` --- Defined if compiled for OpenGL ES but
     GLX / WGL is used instead of EGL. Use @ref MAGNUM_TARGET_EGL instead.
+-   `MAGNUM_TARGET_GLES3` --- Defined if compiled for OpenGL ES 3.0+ / WebGL 2.
+    Use an inverse of the @ref MAGNUM_TARGET_GLES2 variable instead.
 
 Corrade library provides also its own set of CMake macros and variables, see
 @ref corrade-cmake "its documentation" for more information.

doc/opengl.dox

@@ -146,10 +146,8 @@ The following symbols are not defined when targeting OpenGL ES or WebGL.
 */
 
 /** @page requires-gles30 Functionality requiring OpenGL ES 3.0
-@m_footernavigation
+ * @m_footernavigation
-
+ */
-@see @ref MAGNUM_TARGET_GLES3
-*/
 
 /** @page requires-gles31 Functionality requiring OpenGL ES 3.1
 @m_footernavigation

doc/portability.dox

@@ -42,9 +42,9 @@ format is not supported.
 If you include @ref Magnum.h, you get these predefined macros:
 
 -   @ref MAGNUM_TARGET_GLES if targeting OpenGL ES
--   @ref MAGNUM_TARGET_GLES2 if targeting OpenGL ES 2.0
--   @ref MAGNUM_TARGET_GLES3 if targeting OpenGL ES 3.0
 -   @ref MAGNUM_TARGET_WEBGL if targeting WebGL
+-   @ref MAGNUM_TARGET_GLES2 if targeting OpenGL ES 2.0 / WebGL 1 instead of
+    OpenGL ES 3.0+ / WebGL 2
 
 Example usage:
 

modules/FindMagnum.cmake

@@ -135,9 +135,9 @@
 #   globals unique even across different shared libraries
 #  MAGNUM_TARGET_GL             - Defined if compiled with OpenGL interop
 #  MAGNUM_TARGET_GLES           - Defined if compiled for OpenGL ES
-#  MAGNUM_TARGET_GLES2          - Defined if compiled for OpenGL ES 2.0
-#  MAGNUM_TARGET_GLES3          - Defined if compiled for OpenGL ES 3.0
 #  MAGNUM_TARGET_WEBGL          - Defined if compiled for WebGL
+#  MAGNUM_TARGET_GLES2          - Defined if compiled for OpenGL ES 2.0 / WebGL
+#   1 instead of OpenGL ES 3.0+ / WebGL 2
 #  MAGNUM_TARGET_EGL            - Defined if compiled for EGL instead of a
 #   platform-specific OpenGL support library like CGL, EAGL, GLX or WGL
 #  MAGNUM_TARGET_VK             - Defined if compiled with Vulkan interop
@@ -152,6 +152,8 @@
 #   Android, Emscripten or Windows RT. Use MAGNUM_TARGET_EGL instead.
 #  MAGNUM_TARGET_DESKTOP_GLES`  - Defined if compiled for OpenGL ES but
 #   GLX / WGL is used instead of EGL. Use MAGNUM_TARGET_EGL instead.
+#  MAGNUM_TARGET_GLES3          - Defined if compiled for OpenGL ES 3.0+ /
+#   WebGL 2. Use an inverse of the MAGNUM_TARGET_GLES2 variable instead.
 #
 # Additionally these variables are defined for internal usage:
 #
@@ -917,7 +919,7 @@ foreach(_component ${Magnum_FIND_COMPONENTS})
                 find_package(OpenGLES2 REQUIRED)
                 set_property(TARGET Magnum::${_component} APPEND PROPERTY
                     INTERFACE_LINK_LIBRARIES OpenGLES2::OpenGLES2)
-            elseif(MAGNUM_TARGET_GLES3)
+            else()
                 find_package(OpenGLES3 REQUIRED)
                 set_property(TARGET Magnum::${_component} APPEND PROPERTY
                     INTERFACE_LINK_LIBRARIES OpenGLES3::OpenGLES3)

src/Magnum/GL/Context.cpp

@@ -1137,7 +1137,7 @@ Containers::Array<Containers::StringView> Context::extensionStrings() const {
        on GL 2.1. Happens with Mesa's zink that's just 2.1 currently (Apr 2020)
        even though for other backends Mesa exposes this. */
     #ifndef MAGNUM_TARGET_GLES2
-    #ifndef MAGNUM_TARGET_GLES3
+    #ifndef MAGNUM_TARGET_GLES
     if(isVersionSupported(Version::GL300))
     #endif
     {
@@ -1148,14 +1148,15 @@ Containers::Array<Containers::StringView> Context::extensionStrings() const {
             extensions[i] = {reinterpret_cast<const char*>(glGetStringi(GL_EXTENSIONS, i)), Containers::StringViewFlag::Global};
         return extensions;
     }
-    #ifndef MAGNUM_TARGET_GLES3
+    #ifndef MAGNUM_TARGET_GLES
     else
     #endif
     #endif
-
+    #if !defined(MAGNUM_TARGET_GLES) || defined(MAGNUM_TARGET_GLES2)
-    #ifndef MAGNUM_TARGET_GLES3
+    {
-    /* OpenGL 2.1 / OpenGL ES 2.0 doesn't have glGetStringi() */
+        /* OpenGL 2.1 / OpenGL ES 2.0 doesn't have glGetStringi() */
-    return Containers::StringView{reinterpret_cast<const char*>(glGetString(GL_EXTENSIONS)), Containers::StringViewFlag::Global}.splitOnWhitespaceWithoutEmptyParts();
+        return Containers::StringView{reinterpret_cast<const char*>(glGetString(GL_EXTENSIONS)), Containers::StringViewFlag::Global}.splitOnWhitespaceWithoutEmptyParts();
+    }
     #endif
 }
 

src/Magnum/Magnum.h

@@ -139,7 +139,7 @@ Enabled by default in a static build. On Windows see also the
 Defined if the engine is built with OpenGL interoperability enabled --- extra
 APIs in various libraries interacting with the @ref Magnum::GL "GL" library.
 Enabled by default in case the @ref Magnum::GL "GL" library is built.
-@see @ref MAGNUM_TARGET_GLES2, @ref MAGNUM_TARGET_GLES3,
+@see @ref MAGNUM_TARGET_GLES, @ref MAGNUM_TARGET_GLES2,
     @ref MAGNUM_TARGET_EGL, @ref building, @ref cmake
 */
 #define MAGNUM_TARGET_GL
@@ -149,47 +149,45 @@ Enabled by default in case the @ref Magnum::GL "GL" library is built.
 @brief OpenGL ES target
 
 Defined if the engine is built for OpenGL ES 3.0 or OpenGL ES 2.0.
-@see @ref MAGNUM_TARGET_GLES2, @ref MAGNUM_TARGET_GLES3,
+@see @ref MAGNUM_TARGET_GLES2, @ref MAGNUM_TARGET_EGL, @ref building,
-    @ref MAGNUM_TARGET_EGL, @ref building, @ref cmake
+    @ref cmake
 */
 #define MAGNUM_TARGET_GLES
 #undef MAGNUM_TARGET_GLES
 
 /**
-@brief OpenGL ES 2.0 target
+@brief WebGL target
 
-Defined if the engine is built for OpenGL ES 2.0. Implies also
+Defined if the engine is built for WebGL (using Emscripten). WebGL 1 is nearly
-@ref MAGNUM_TARGET_GLES.
+equivalent to OpenGL ES 2.0 and WebGL 2 to OpenGL ES 3.0, thus in most cases
-@see @ref MAGNUM_TARGET_GLES3, @ref MAGNUM_TARGET_EGL, @ref building,
+you don't need to treat it differently, but there are some specific
-    @ref cmake
+restrictions and differences [compared to OpenGL ES 2.0](http://www.khronos.org/registry/webgl/specs/latest/1.0/#6)
+and to [OpenGL ES 3.0](https://registry.khronos.org/webgl/specs/latest/2.0/#5)
+which you might want to be aware of. Implies also @ref MAGNUM_TARGET_GLES.
+@see @ref MAGNUM_TARGET_GLES2 @ref CORRADE_TARGET_EMSCRIPTEN, @ref building, @ref cmake
 */
-#define MAGNUM_TARGET_GLES2
+#define MAGNUM_TARGET_WEBGL
-#undef MAGNUM_TARGET_GLES2
+#undef MAGNUM_TARGET_WEBGL
 
 /**
-@brief OpenGL ES 3.0 target
+@brief OpenGL ES 2.0 / WebGL 1.0 target
 
-Defined if the engine is built for OpenGL ES 3.0. Implies also
+Defined if the engine is built for OpenGL ES 2.0 / WebGL 1.0 instead of OpenGL
-@ref MAGNUM_TARGET_GLES.
+ES 3.0+ / WebGL 2. Implies also @ref MAGNUM_TARGET_GLES.
-@see @ref MAGNUM_TARGET_GLES2, @ref MAGNUM_TARGET_EGL, @ref building,
+@see @ref MAGNUM_TARGET_EGL, @ref building, @ref cmake
-    @ref cmake
 */
-#define MAGNUM_TARGET_GLES3
+#define MAGNUM_TARGET_GLES2
-#undef MAGNUM_TARGET_GLES3
+#undef MAGNUM_TARGET_GLES2
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 /**
-@brief WebGL target
+@brief OpenGL ES 3.0+ / WebGL 2.0 target
-
+@m_deprecated_since_latest This macro is simply an inverse of
-Defined if the engine is built for WebGL (using Emscripten). WebGL is nearly
+    @ref MAGNUM_TARGET_GLES2, use that one instead.
-equivalent to OpenGL ES 2.0, thus in most cases you don't need to treat it
-differently, but there are some
-[specific restrictions and features](http://www.khronos.org/registry/webgl/specs/latest/1.0/#6)
-which you might want to be aware of. Implies also @ref MAGNUM_TARGET_GLES and
-@ref MAGNUM_TARGET_GLES2.
-@see @ref CORRADE_TARGET_EMSCRIPTEN, @ref building, @ref cmake
 */
-#define MAGNUM_TARGET_WEBGL
+#define MAGNUM_TARGET_GLES3
-#undef MAGNUM_TARGET_WEBGL
+#undef MAGNUM_TARGET_GLES3
+#endif
 
 /**
 @brief EGL target

src/Magnum/Platform/AndroidApplication.cpp

@@ -153,7 +153,7 @@ bool AndroidApplication::tryCreate(const Configuration& configuration, const GLC
     const EGLint contextAttributes[] = {
         #ifdef MAGNUM_TARGET_GLES2
         EGL_CONTEXT_CLIENT_VERSION, 2,
-        #elif defined(MAGNUM_TARGET_GLES3)
+        #elif defined(MAGNUM_TARGET_GLES)
         EGL_CONTEXT_CLIENT_VERSION, 3,
         #else
         #error Android with desktop OpenGL? Wow, that is a new thing.

src/Magnum/Platform/EmscriptenApplication.cpp

@@ -373,12 +373,10 @@ bool EmscriptenApplication::tryCreate(const Configuration& configuration, const
     attrs.enableExtensionsByDefault =
         !!(glConfiguration.flags() & GLConfiguration::Flag::EnableExtensionsByDefault);
 
-    #ifdef MAGNUM_TARGET_GLES3 /* WebGL 2 */
+    #ifdef MAGNUM_TARGET_GLES2 /* WebGL 1 */
-    attrs.majorVersion = 2;
+    attrs.majorVersion = 1;
-    #elif defined(MAGNUM_TARGET_GLES2) /* WebGL 1 */
+    #else                      /* WebGL 2 */
-    attrs.minorVersion = 1;
+    attrs.minorVersion = 2;
-    #else
-    #error unsupported OpenGL ES version
     #endif
 
     std::ostream* verbose = _verboseLog ? Debug::output() : nullptr;

src/Magnum/Platform/GlfwApplication.cpp

@@ -494,12 +494,10 @@ bool GlfwApplication::tryCreate(const Configuration& configuration, const GLConf
         glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, glFlags >= GLConfiguration::Flag::ForwardCompatible);
         #else
         /* For ES the major context version is compile-time constant */
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
-        #elif defined(MAGNUM_TARGET_GLES2)
         glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 2);
         #else
-        #error unsupported OpenGL ES version
+        glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
         #endif
         glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 0);
         glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);

src/Magnum/Platform/Implementation/EglContextHandler.cpp

@@ -67,12 +67,10 @@ VisualId EglContextHandler::getVisualId(EGLNativeDisplayType nativeDisplay) {
         EGL_DEPTH_SIZE, 1,
         #ifndef MAGNUM_TARGET_GLES
         EGL_RENDERABLE_TYPE, EGL_OPENGL_BIT,
-        #elif defined(MAGNUM_TARGET_GLES3)
-        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT_KHR,
         #elif defined(MAGNUM_TARGET_GLES2)
         EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
         #else
-        #error unsupported OpenGL edition
+        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT_KHR,
         #endif
         EGL_NONE
     };
@@ -130,12 +128,10 @@ void EglContextHandler::createContext(const AbstractXApplication::GLConfiguratio
     #ifdef MAGNUM_TARGET_GLES
     else {
         attributes[0] = EGL_CONTEXT_CLIENT_VERSION;
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        attributes[1] = 3;
-        #elif defined(MAGNUM_TARGET_GLES2)
         attributes[1] = 2;
         #else
-        #error unsupported OpenGL ES version
+        attributes[1] = 3;
         #endif
     }
     #endif

src/Magnum/Platform/Implementation/GlxContextHandler.cpp

@@ -107,12 +107,10 @@ void GlxContextHandler::createContext(const AbstractXApplication::GLConfiguratio
     #ifdef MAGNUM_TARGET_GLES
     else {
         attributes[0] = GLX_CONTEXT_MAJOR_VERSION_ARB;
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        attributes[1] = 3;
-        #elif defined(MAGNUM_TARGET_GLES2)
         attributes[1] = 2;
         #else
-        #error unsupported OpenGL ES version
+        attributes[1] = 3;
         #endif
         attributes[2] = GLX_CONTEXT_MINOR_VERSION_ARB;
         attributes[3] = 0;

src/Magnum/Platform/Sdl2Application.cpp

@@ -549,12 +549,10 @@ bool Sdl2Application::tryCreate(const Configuration& configuration, const GLConf
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, int(UnsignedLong(glFlags) & 0xffffffffu));
         #else
         /* For ES the major context version is compile-time constant */
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
-        #elif defined(MAGNUM_TARGET_GLES2)
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 2);
         #else
-        #error unsupported OpenGL ES version
+        SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
         #endif
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 0);
         SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_ES);

src/Magnum/Platform/WindowlessEglApplication.cpp

@@ -337,10 +337,8 @@ WindowlessEglContext::WindowlessEglContext(const Configuration& configuration, G
            the `-s USE_WEBGL2=1` flag anyway, so it doesn't matter that we ask
            for ES2 on WebGL 2 as well. */
         EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
-        #elif defined(MAGNUM_TARGET_GLES3)
-        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT_KHR,
         #else
-        #error unsupported OpenGL edition
+        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT_KHR,
         #endif
         EGL_NONE
     };
@@ -376,10 +374,8 @@ WindowlessEglContext::WindowlessEglContext(const Configuration& configuration, G
                anyway, so it doesn't matter that we ask for ES2 on WebGL 2 as
                well. https://github.com/emscripten-core/emscripten/pull/7858 */
             2,
-            #elif defined(MAGNUM_TARGET_GLES3)
-            3,
             #else
-            #error unsupported OpenGL ES version
+            3,
             #endif
             #else
             3,

src/Magnum/Platform/WindowlessGlxApplication.cpp

@@ -123,12 +123,10 @@ WindowlessGlxContext::WindowlessGlxContext(const WindowlessGlxContext::Configura
     /* Optimistically choose core context first */
     GLint contextAttributes[11] = {
         #ifdef MAGNUM_TARGET_GLES
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        GLX_CONTEXT_MAJOR_VERSION_ARB, 3,
-        #elif defined(MAGNUM_TARGET_GLES2)
         GLX_CONTEXT_MAJOR_VERSION_ARB, 2,
         #else
-        #error unsupported OpenGL ES version
+        GLX_CONTEXT_MAJOR_VERSION_ARB, 3,
         #endif
         GLX_CONTEXT_MINOR_VERSION_ARB, 0,
         GLX_CONTEXT_PROFILE_MASK_ARB, GLX_CONTEXT_ES2_PROFILE_BIT_EXT,

src/Magnum/Platform/WindowlessWglApplication.cpp

@@ -136,12 +136,10 @@ WindowlessWglContext::WindowlessWglContext(const Configuration& configuration, G
     /* Optimistically choose core context first */
     GLint contextAttributes[11] = {
         #ifdef MAGNUM_TARGET_GLES
-        #ifdef MAGNUM_TARGET_GLES3
+        #ifdef MAGNUM_TARGET_GLES2
-        WGL_CONTEXT_MAJOR_VERSION_ARB, 3,
-        #elif defined(MAGNUM_TARGET_GLES2)
         WGL_CONTEXT_MAJOR_VERSION_ARB, 2,
         #else
-        #error unsupported OpenGL ES version
+        WGL_CONTEXT_MAJOR_VERSION_ARB, 3,
         #endif
         WGL_CONTEXT_MINOR_VERSION_ARB, 0,
         WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_ES2_PROFILE_BIT_EXT,

src/Magnum/configure.h.cmake

@@ -31,7 +31,6 @@
 #cmakedefine MAGNUM_TARGET_GL
 #cmakedefine MAGNUM_TARGET_GLES
 #cmakedefine MAGNUM_TARGET_GLES2
-#cmakedefine MAGNUM_TARGET_GLES3
 #cmakedefine MAGNUM_TARGET_WEBGL
 #cmakedefine MAGNUM_TARGET_EGL
 #cmakedefine MAGNUM_TARGET_VK
@@ -61,6 +60,14 @@
 #define  MAGNUM_TARGET_DESKTOP_GLES
 #endif
 #endif
+/* MAGNUM_TARGET_GLES3 used to be an inverse of MAGNUM_TARGET_GLES2 in an
+   anticipation of there eventually being GLES 4. Used very rarely in the
+   internals and only led to confusion. Deliberate double space after the
+   #define to avoid being unconditionally matched by older FindMagnum
+   modules. */
+#if defined(MAGNUM_TARGET_GLES) && !defined(MAGNUM_TARGET_GLES2)
+#define  MAGNUM_TARGET_GLES3
+#endif
 #endif
 
 #endif // kate: hl c++