doc: document all WebGL restrictions.

doc/best-practices.dox

@@ -54,21 +54,22 @@ information.
 - [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html)
 - [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3)
 
-@subsection best-practices-nacl Google Chrome Native Client
+@subsection best-practices-webgl WebGL (Emscripten)
 
-- [Best practices for 3D graphics](https://developers.google.com/native-client/beta/devguide/coding/3D-graphics#best-practices)
+WebGL is subset of OpenGL ES 2.0 with some [specific restrictions and features](http://www.khronos.org/registry/webgl/specs/latest/1.0/#6), namely requirement
+for unique buffer target binding, aligned buffer offset and stride and some
+other restrictions and also support for combined depth/stencil buffer
+attachments. See @ref Buffer, @ref Framebuffer, @ref Texture::setSubImage() "*Texture::setSubImage()",
+@ref Mesh::addVertexBuffer(), @ref Renderer::setStencilFunction(),
+@ref Renderer::setStencilMask() and @ref Renderer::setBlendFunction()
+documentation for more information.
 
-@subsection best-practices-web-buffer-types Native Client and Emscripten require unique buffer binding
+@subsection best-practices-nacl Google Chrome Native Client
 
-As noted in the above link, buffers in NaCl implementation and and also in
-WebGL need to be bound only to one unique target, i.e., @ref Buffer bound to
-@ref Buffer::Target::Array cannot be later rebound to @ref Buffer::Target::ElementArray.
-However, %Magnum by default uses any sufficient target when binding the buffer
-internally (e.g. for setting data or copying). To avoid this, set target hint
-to desired target, either in constructor or using @ref Buffer::setTargetHint().
+- [Best practices for 3D graphics](https://developers.google.com/native-client/beta/devguide/coding/3D-graphics#best-practices)
 
-To ease up the development, @ref Mesh checks proper target hint when adding
-vertex and index buffers in both Native Client and Emscripten.
+Similarly to WebGL, buffers in NaCl implementation need to be bound only to one
+unique target. See @ref Buffer class documentation for more information.
 
 @section best-practices-hw Hardware-specific
 

doc/opengl-support.dox

@@ -325,7 +325,8 @@ add any performance gains, is not supported in %Magnum. See also
     with serious performance drops. Multisampling is far superior solution.
 -   Fixed precision data types (`GL_FIXED` in OpenGL ES) are not supported, as
     they occupy the same memory as floats and they aren't faster than floats on
-    current hardware anymore.
+    current hardware anymore. They are also not available in WebGL or desktop
+    GL.
 -   Shader compiler is assumed to be present (`GL_SHADER_COMPILER` returning
     true), as all desktop GL implementations and also ES3 are required to
     support it.

src/Magnum/AbstractTexture.h

@@ -43,6 +43,12 @@ Encapsulates one OpenGL texture object. See @ref Texture, @ref CubeMapTexture
 and @ref CubeMapTextureArray documentation for more information and usage
 examples.
 
+@section AbstractTexture-webgl-restrictions WebGL restrictions
+
+@ref MAGNUM_TARGET_WEBGL "WebGL" puts some restrictions on type of data
+submitted to @ref Texture::setSubImage() "*Texture::setSubImage()", see its
+documentation for details.
+
 @section AbstractTexture-performance-optimization Performance optimizations and security
 
 The engine tracks currently bound textures in all available layers to avoid

src/Magnum/Buffer.h

@@ -166,6 +166,23 @@ for(std::size_t i: {7, 27, 56, 128}) {
 CORRADE_INTERNAL_ASSERT_OUTPUT(buffer.unmap());
 @endcode
 
+@section Buffer-webgl-restrictions WebGL and NaCl restrictions
+
+Buffers in @ref MAGNUM_TARGET_WEBGL "WebGL" and @ref CORRADE_TARGET_NACL "NaCl"
+need to be bound only to one unique target, i.e., @ref Buffer bound to
+@ref Buffer::Target::Array cannot be later rebound to
+@ref Buffer::Target::ElementArray. However, %Magnum by default uses any
+sufficient target when binding the buffer internally (e.g. for setting data).
+To avoid GL errors, set target hint to desired target, either in constructor or
+using @ref Buffer::setTargetHint():
+@code
+Buffer vertices{Buffer::Target::Array};
+Buffer indices{Buffer::Target::ElementArray};
+@endcode
+
+To ease up the development, @ref Mesh checks proper target hint when adding
+vertex and index buffers in both WebGL and NaCl.
+
 @section Buffer-performance-optimization Performance optimizations
 
 The engine tracks currently bound buffers to avoid unnecessary calls to

src/Magnum/Mesh.h

@@ -291,6 +291,11 @@ respective shader, bind required textures (see
 @ref AbstractShaderProgram-rendering-workflow "AbstractShaderProgram documentation"
 for more infromation) and call @ref Mesh::draw().
 
+@section Mesh-webgl-restrictions WebGL restrictions
+
+@ref MAGNUM_TARGET_WEBGL "WebGL" puts some restrictions on vertex buffer
+layout, see @ref addVertexBuffer() for details.
+
 @section Mesh-performance-optimization Performance optimizations
 
 If @extension{APPLE,vertex_array_object} (part of OpenGL 3.0), OpenGL ES 3.0 or
@@ -553,6 +558,12 @@ class MAGNUM_EXPORT Mesh: public AbstractObject {
          *      mesh, you must ensure it will exist for whole lifetime of the
          *      mesh and delete it afterwards.
          *
+         * @attention In @ref MAGNUM_TARGET_WEBGL "WebGL" the data must be
+         *      properly aligned (e.g. all float data must start at addresses
+         *      divisible by four). Also the maximum stride of attribute data
+         *      must be at most 255 bytes. This is not required anywhere else,
+         *      but doing so may have performance benefits.
+         *
          * @see @ref maxVertexAttributes(), @ref setPrimitive(),
          *      @ref setVertexCount(), @fn_gl{BindVertexArray},
          *      @fn_gl{EnableVertexAttribArray}, @fn_gl{BindBuffer},

src/Magnum/Renderer.h

@@ -519,6 +519,9 @@ class MAGNUM_EXPORT Renderer {
          * @param mask              Mask for both reference and buffer value.
          *      Initial value is all `1`s.
          *
+         * @attention In @ref MAGNUM_TARGET_WEBGL "WebGL" the reference value
+         *      and mask must be the same for both front and back polygon
+         *      facing.
          * @see @ref Feature::StencilTest, @ref setStencilFunction(StencilFunction, Int, UnsignedInt),
          *      @ref setStencilOperation(), @fn_gl{StencilFuncSeparate}
          */
@@ -606,6 +609,9 @@ class MAGNUM_EXPORT Renderer {
          *
          * Set given bit to `0` to disallow writing stencil value for given
          * faces to it. Initial value is all `1`s.
+         *
+         * @attention In @ref MAGNUM_TARGET_WEBGL "WebGL" the mask must be the
+         *      same for both front and back polygon facing.
          * @see setStencilMask(UnsignedInt), setColorMask(), setDepthMask(),
          *      @fn_gl{StencilMaskSeparate}
          */
@@ -812,6 +818,9 @@ class MAGNUM_EXPORT Renderer {
          * @param destination   How the destination blending factor is
          *      computed from framebuffer. Initial value is @ref BlendFunction::Zero.
          *
+         * @attention In @ref MAGNUM_TARGET_WEBGL "WebGL", constant color and
+         *      constant alpha cannot be used together as source and
+         *      destination factors.
          * @see @ref Feature::Blending, @ref setBlendFunction(BlendFunction, BlendFunction, BlendFunction, BlendFunction),
          *      @ref setBlendEquation(), @ref setBlendColor(),
          *      @fn_gl{BlendFunc}

src/Magnum/Texture.h

@@ -299,6 +299,8 @@ template<UnsignedInt dimensions> class Texture: public AbstractTexture {
          * (part of OpenGL 4.2), OpenGL ES 3.0 or @es_extension{EXT,texture_storage}
          * in OpenGL ES 2.0 is not available, the feature is emulated with
          * sequence of @ref setImage() calls.
+         * @todo allow the user to specify ColorType explicitly to avoid
+         *      issues in WebGL (see setSubImage())
          * @see @fn_gl{ActiveTexture}, @fn_gl{BindTexture} and
          *      @fn_gl{TexStorage1D}/@fn_gl{TexStorage2D}/@fn_gl{TexStorage3D}
          *      or @fn_gl_extension{TextureStorage1D,EXT,direct_state_access}/
@@ -404,6 +406,12 @@ template<UnsignedInt dimensions> class Texture: public AbstractTexture {
          *
          * If @extension{EXT,direct_state_access} is not available, the
          * texture is bound to some layer before the operation.
+         *
+         * @attention In @ref MAGNUM_TARGET_WEBGL "WebGL" the @ref ColorType of
+         *      data passed in @p image must match the original one specified
+         *      in @ref setImage(). It means that you might not be able to use
+         *      @ref setStorage() as it uses implicit @ref ColorType value.
+         *
          * @see @ref setStorage(), @ref setImage(), @fn_gl{ActiveTexture},
          *      @fn_gl{BindTexture} and @fn_gl{TexSubImage1D}/
          *      @fn_gl{TexSubImage2D}/@fn_gl{TexSubImage3D} or