DebugTools,MeshTools: unify how GL-only APIs are advertised.

src/Magnum/DebugTools/BufferData.h

@@ -27,19 +27,13 @@
     DEALINGS IN THE SOFTWARE.
 */
 
-#if defined(MAGNUM_TARGET_GL) && !(defined(MAGNUM_TARGET_WEBGL) && defined(MAGNUM_TARGET_GLES2))
+#if defined(MAGNUM_TARGET_GL) && !(defined(MAGNUM_TARGET_WEBGL) && (defined(MAGNUM_TARGET_GLES2) || __EMSCRIPTEN_major__*10000 + __EMSCRIPTEN_minor__*100 + __EMSCRIPTEN_tiny__ < 20017))
 /** @file
  * @brief Function @ref Magnum::DebugTools::bufferData(), @ref Magnum::DebugTools::bufferSubData()
  */
 #endif
 
-#include <Corrade/Containers/Containers.h>
-
-#include "Magnum/Magnum.h"
-#include "Magnum/GL/GL.h"
-#include "Magnum/GL/OpenGL.h"
-#include "Magnum/DebugTools/visibility.h"
-
+#include "Magnum/configure.h"
 /* The __EMSCRIPTEN_major__ etc macros used to be passed implicitly, version
    3.1.4 moved them to a version header and version 3.1.23 dropped the
    backwards compatibility. To work consistently on all versions, including the
@@ -50,6 +44,14 @@
 #include <emscripten/version.h>
 #endif
 
+#if defined(MAGNUM_TARGET_GL) && !(defined(MAGNUM_TARGET_WEBGL) && (defined(MAGNUM_TARGET_GLES2) || __EMSCRIPTEN_major__*10000 + __EMSCRIPTEN_minor__*100 + __EMSCRIPTEN_tiny__ < 20017))
+#include <Corrade/Containers/Containers.h>
+
+#include "Magnum/Magnum.h"
+#include "Magnum/GL/GL.h"
+#include "Magnum/GL/OpenGL.h"
+#include "Magnum/DebugTools/visibility.h"
+
 #ifdef MAGNUM_BUILD_DEPRECATED
 #include <Corrade/Containers/Array.h>
 #include <Corrade/Utility/Macros.h>
@@ -57,7 +59,6 @@
 #include "Magnum/GL/Buffer.h"
 #endif
 
-#if defined(MAGNUM_TARGET_GL) && !(defined(MAGNUM_TARGET_WEBGL) && (defined(MAGNUM_TARGET_GLES2) || __EMSCRIPTEN_major__*10000 + __EMSCRIPTEN_minor__*100 + __EMSCRIPTEN_tiny__ < 20017))
 namespace Magnum { namespace DebugTools {
 
 #ifdef MAGNUM_BUILD_DEPRECATED

src/Magnum/DebugTools/ForceRenderer.h

@@ -32,6 +32,9 @@
  */
 #endif
 
+#include "Magnum/configure.h"
+
+#ifdef MAGNUM_TARGET_GL
 #include "Magnum/Resource.h"
 #include "Magnum/DebugTools/DebugTools.h"
 #include "Magnum/DebugTools/visibility.h"
@@ -40,7 +43,6 @@
 #include "Magnum/SceneGraph/Drawable.h"
 #include "Magnum/Shaders/Shaders.h"
 
-#ifdef MAGNUM_TARGET_GL
 namespace Magnum { namespace DebugTools {
 
 /**
@@ -145,10 +147,22 @@ template<UnsignedInt dimensions> class ForceRenderer: public SceneGraph::Drawabl
         Resource<GL::Mesh> _mesh;
 };
 
-/** @brief Two-dimensional force renderer */
+/**
+@brief Two-dimensional force renderer
+
+@note This typedef is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+*/
 typedef ForceRenderer<2> ForceRenderer2D;
 
-/** @brief Three-dimensional force renderer */
+/**
+@brief Three-dimensional force renderer
+
+@note This typedef is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+*/
 typedef ForceRenderer<3> ForceRenderer3D;
 
 }}

src/Magnum/DebugTools/ObjectRenderer.h

@@ -32,6 +32,9 @@
  */
 #endif
 
+#include "Magnum/configure.h"
+
+#ifdef MAGNUM_TARGET_GL
 #include "Magnum/Resource.h"
 #include "Magnum/DebugTools/DebugTools.h"
 #include "Magnum/DebugTools/visibility.h"
@@ -39,7 +42,6 @@
 #include "Magnum/SceneGraph/Drawable.h"
 #include "Magnum/Shaders/Shaders.h"
 
-#ifdef MAGNUM_TARGET_GL
 namespace Magnum { namespace DebugTools {
 
 /**
@@ -116,10 +118,22 @@ template<UnsignedInt dimensions> class ObjectRenderer: public SceneGraph::Drawab
         Resource<GL::Mesh> _mesh;
 };
 
-/** @brief Two-dimensional object renderer */
+/**
+@brief Two-dimensional object renderer
+
+@note This typedef is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+*/
 typedef ObjectRenderer<2> ObjectRenderer2D;
 
-/** @brief Three-dimensional object renderer */
+/**
+@brief Three-dimensional object renderer
+
+@note This typedef is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+*/
 typedef ObjectRenderer<3> ObjectRenderer3D;
 
 }}

src/Magnum/DebugTools/ResourceManager.h

@@ -32,6 +32,9 @@
  */
 #endif
 
+#include "Magnum/configure.h"
+
+#ifdef MAGNUM_TARGET_GL
 #include "Magnum/ResourceManager.h"
 
 #include "Magnum/Magnum.h"
@@ -50,7 +53,6 @@
 #include "Magnum/GL/MeshView.h"
 #endif
 
-#ifdef MAGNUM_TARGET_GL
 namespace Magnum { namespace DebugTools {
 
 /**

src/Magnum/DebugTools/Screenshot.h

@@ -26,10 +26,15 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#ifdef MAGNUM_TARGET_GL
 /** @file
  * @brief Function @ref Magnum::DebugTools::screenshot()
  */
+#endif
+
+#include "Magnum/configure.h"
 
+#ifdef MAGNUM_TARGET_GL
 #include <Corrade/PluginManager/PluginManager.h>
 
 #include "Magnum/Magnum.h"
@@ -70,6 +75,10 @@ map the detected pixel format back to a generic format, if either the
 @ref Trade::AnyImageConverter "AnyImageConverter" or the corresponding plugin
 for given file format could not be loaded, or if the file saving fails (for
 example due to unsupported pixel format). A message is printed in each case.
+
+@note This function is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
 */
 bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(GL::AbstractFramebuffer& framebuffer, Containers::StringView filename);
 
@@ -79,6 +88,10 @@ bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(GL::AbstractFramebuffer& framebuffer, C
 Useful in case you already have an instance of the converter plugin manager in
 your application or if you intend to save screenshots often, as the operation
 doesn't involve costly dynamic library loading and unloading on every call.
+
+@note This function is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
 */
 bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, Containers::StringView filename);
 
@@ -93,6 +106,10 @@ Similar to @ref screenshot(GL::AbstractFramebuffer&, PixelFormat, Containers::St
 but with an explicit pixel format. Useful in cases where the driver-suggested
 pixel format is not desired, however note that supplying a format that's
 incompatible with the framebuffer may result in GL errors.
+
+@note This function is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
 */
 bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(GL::AbstractFramebuffer& framebuffer, PixelFormat format, Containers::StringView filename);
 
@@ -102,9 +119,16 @@ bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(GL::AbstractFramebuffer& framebuffer, P
 Useful in case you already have an instance of the converter plugin manager in
 your application or if you intend to save screenshots often, as the operation
 doesn't involve costly dynamic library loading and unloading on every call.
+
+@note This function is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
 */
 bool MAGNUM_DEBUGTOOLS_EXPORT screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, PixelFormat format, Containers::StringView filename);
 
 }}
+#else
+#error this header is available only in the OpenGL build
+#endif
 
 #endif

src/Magnum/DebugTools/TextureImage.h

@@ -32,11 +32,13 @@
  */
 #endif
 
+#include "Magnum/configure.h"
+
+#ifdef MAGNUM_TARGET_GL
 #include "Magnum/Magnum.h"
 #include "Magnum/DebugTools/visibility.h"
 #include "Magnum/GL/GL.h"
 
-#ifdef MAGNUM_TARGET_GL
 namespace Magnum { namespace DebugTools {
 
 /**

src/Magnum/MeshTools/Compile.h

@@ -26,9 +26,11 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#ifdef MAGNUM_TARGET_GL
 /** @file
  * @brief Function @ref Magnum::MeshTools::compile()
  */
+#endif
 
 #include "Magnum/configure.h"
 
@@ -50,6 +52,10 @@ namespace Magnum { namespace MeshTools {
 @brief Mesh compilation flag
 @m_since{2019,10}
 
+@note This enum is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+
 @see @ref CompileFlags, @ref compile(const Trade::MeshData&, CompileFlags)
 */
 enum class CompileFlag: UnsignedByte {
@@ -89,6 +95,10 @@ enum class CompileFlag: UnsignedByte {
 @brief Mesh compilation flags
 @m_since{2019,10}
 
+@note This enum set is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+
 @see @ref compile(const Trade::MeshData&, CompileFlags)
 */
 typedef Containers::EnumSet<CompileFlag> CompileFlags;
@@ -205,6 +215,10 @@ Compared to @ref compile(const Trade::MeshData&, CompileFlags), this function
 implicitly enables the @ref CompileFlag::NoWarnOnCustomAttributes flag,
 assuming that custom attributes and attributes with implementation-specific
 formats are explicitly handled on the application side.
+
+@note This function is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
 */
 MAGNUM_MESHTOOLS_EXPORT GL::Mesh compile(const Trade::MeshData& mesh, GL::Buffer& indices, GL::Buffer& vertices);
 

src/Magnum/TextureTools/DistanceFieldGL.h

@@ -56,6 +56,10 @@ You can also use the @ref magnum-distancefieldconverter "magnum-distancefieldcon
 utility to do distance field conversion on command-line. This functionality is
 also used inside the @ref magnum-fontconverter "magnum-fontconverter" utility.
 
+@note This class is available only if Magnum is compiled with
+    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
+    for more information.
+
 @section TextureTools-DistanceFieldGL-algorithm The algorithm
 
 For each pixel inside the @p output sub-rectangle the algorithm looks at
@@ -78,10 +82,6 @@ http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnifica
 
 @attention This is a GPU-only implementation, so it expects an active GL
     context.
-
-@note This function is available only if Magnum is compiled with
-    @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features
-    for more information.
 */
 class MAGNUM_TEXTURETOOLS_EXPORT DistanceFieldGL {
     public: