From 8587afaca73e2ea405dfbbf9e88d9688e8082a69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 16 Aug 2019 12:24:26 +0200
Subject: [PATCH] GL: improve Attribute docs with clear integer/double
 unavailablility errors.

---
 doc/snippets/MagnumGL.cpp             |  9 ++++-
 src/Magnum/GL/AbstractShaderProgram.h |  4 +-
 src/Magnum/GL/Attribute.h             | 54 +++++++++++++++++++--------
 3 files changed, 47 insertions(+), 20 deletions(-)

diff --git a/doc/snippets/MagnumGL.cpp b/doc/snippets/MagnumGL.cpp
index af8e7f9d8..2e2f79b67 100644
--- a/doc/snippets/MagnumGL.cpp
+++ b/doc/snippets/MagnumGL.cpp
@@ -312,11 +312,16 @@ MyShader& bindSpecularTexture(GL::Texture2D& texture) {
 /* [AbstractShaderProgram-textures] */
 
 /* [AbstractShaderProgram-xfb] */
-MyShader& setTransformFeedback(GL::TransformFeedback& feedback, GL::Buffer& positions, GL::Buffer& data) {
+MyShader& setTransformFeedback(GL::TransformFeedback& feedback,
+    GL::Buffer& positions, GL::Buffer& data)
+{
     feedback.attachBuffers(0, {&positions, &data});
     return *this;
 }
-MyShader& setTransformFeedback(GL::TransformFeedback& feedback, Int totalCount, GL::Buffer& positions, GLintptr positionsOffset, GL::Buffer& data, GLintptr dataOffset) {
+MyShader& setTransformFeedback(GL::TransformFeedback& feedback, Int totalCount,
+    GL::Buffer& positions, GLintptr positionsOffset, GL::Buffer& data,
+    GLintptr dataOffset)
+{
     feedback.attachBuffers(0, {
         std::make_tuple(&positions, positionsOffset, totalCount*sizeof(Vector3)),
         std::make_tuple(&data, dataOffset, totalCount*sizeof(Vector2ui))
diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h
index c1a3781bd..eca93e92e 100644
--- a/src/Magnum/GL/AbstractShaderProgram.h
+++ b/src/Magnum/GL/AbstractShaderProgram.h
@@ -54,8 +54,8 @@ This class is designed to be used via subclassing. Subclasses define these
 functions and properties:
 
 <ul>
-<li> **Attribute definitions** with location and type for
-    configuring meshes, for example:
+<li> **Attribute definitions** using @ref Attribute typedefs with location and
+    type for configuring meshes, for example:
 
     @snippet MagnumGL.cpp AbstractShaderProgram-input-attributes
 </li>
diff --git a/src/Magnum/GL/Attribute.h b/src/Magnum/GL/Attribute.h
index 87ce033f3..64ad2000d 100644
--- a/src/Magnum/GL/Attribute.h
+++ b/src/Magnum/GL/Attribute.h
@@ -34,6 +34,7 @@
 #include "Magnum/Magnum.h"
 #include "Magnum/GL/OpenGL.h"
 #include "Magnum/GL/visibility.h"
+#include "Magnum/Math/TypeTraits.h"
 
 namespace Magnum { namespace GL {
 
@@ -42,28 +43,36 @@ namespace Implementation { template<class> struct Attribute; }
 /**
 @brief Base class for vertex attribute location and type
 
-For use in @ref AbstractShaderProgram subclasses. Template parameter @p location
-is vertex attribute location, number between @cpp 0 @ce and
+For use in @ref AbstractShaderProgram subclasses. The @p location template
+parameter is vertex attribute location, a number between @cpp 0 @ce and
 @ref AbstractShaderProgram::maxVertexAttributes(). To ensure compatibility, you
-should always have vertex attribute with location @cpp 0 @ce.
+should always have a vertex attribute with location @cpp 0 @ce.
 
-Template parameter @p T is the type which is used for shader attribute, e.g.
-@ref Magnum::Vector4i "Vector4i" for @glsl ivec4 @ce. DataType is type of
-passed data when adding vertex buffers to mesh. By default it is the same as
-type used in shader (e.g. @ref DataType::Int for @ref Magnum::Vector4i "Vector4i").
-It's also possible to pass integer data to floating-point shader inputs. In
-this case you may want to normalize the values (e.g. color components from
-@cpp 0 @ce -- @cpp 255 @ce to @cpp 0.0f @ce -- @cpp 1.0f @ce) --- see
-@ref DataOption::Normalized.
+The @p T template parameter is the type which is used for shader attribute,
+e.g. @ref Magnum::Vector4i "Vector4i" for @glsl ivec4 @ce. @ref DataType is
+type of passed data when adding vertex buffers to mesh. By default it is the
+same as type used in shader (e.g. @ref DataType::Int for
+@ref Magnum::Vector4i "Vector4i"). It's also possible to pass integer data to
+floating-point shader inputs. In this case you may want to normalize the values
+(e.g. color components from @cpp 0 @ce -- @cpp 255 @ce to @cpp 0.0f @ce --
+@cpp 1.0f @ce) --- see @ref DataOption::Normalized.
 
-Only some types are allowed as attribute types, see @ref GL-AbstractShaderProgram-types
-for more information.
+@attention Only some types are allowed as attribute types and there are
+    additional restrictions applied for OpenGL ES and WebGL, see
+    @ref GL-AbstractShaderProgram-types for more information.
 
 See @ref GL-AbstractShaderProgram-subclassing for example usage in shaders and
-@ref GL-Mesh-configuration for example usage when adding vertex buffers to
+@ref GL-Mesh-configuration for example usage when adding vertex buffers to a
 mesh.
 */
 template<UnsignedInt location, class T> class Attribute {
+    #ifdef MAGNUM_TARGET_GLES2
+    static_assert(!Math::IsIntegral<T>::value, "integral attributes are not available on OpenGL ES 2.0 and WebGL 1");
+    #endif
+    #ifdef MAGNUM_TARGET_GLES
+    static_assert(!std::is_same<Math::UnderlyingTypeOf<T>, Double>::value, "double attributes and uniforms are not available in OpenGL ES and WebGL");
+    #endif
+
     public:
         enum: UnsignedInt {
             /**
@@ -343,11 +352,24 @@ class DynamicAttribute {
             GenericNormalized,
 
             #ifndef MAGNUM_TARGET_GLES2
-            /** Integral, matches integral shader type */
+            /**
+             * Integral, matches integral shader type
+             *
+             * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4}
+             * @requires_gles30 Integral attributes are not available in OpenGL
+             *      ES 2.0.
+             * @requires_webgl20 Integral attributes are not available in WebGL
+             *      1.0.
+             */
             Integral,
             #ifndef MAGNUM_TARGET_GLES
 
-            /** Long, matches double-precision shader type */
+            /**
+             * Long, matches double-precision shader type
+             * @requires_gl40 Extension @gl_extension{ARB,gpu_shader_fp64}
+             * @requires_gl Double attributes and uniforms are not available in
+             *      OpenGL ES and WebGL.
+             */
             Long
             #endif
             #endif