diff --git a/doc/best-practices.dox b/doc/best-practices.dox index b1f17c9a0..3079ebf12 100644 --- a/doc/best-practices.dox +++ b/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 diff --git a/doc/opengl-support.dox b/doc/opengl-support.dox index 7a6a4e8bd..9da8957c3 100644 --- a/doc/opengl-support.dox +++ b/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. diff --git a/src/Magnum/AbstractTexture.h b/src/Magnum/AbstractTexture.h index ace81fc3a..670edbed8 100644 --- a/src/Magnum/AbstractTexture.h +++ b/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 diff --git a/src/Magnum/Buffer.h b/src/Magnum/Buffer.h index 35d5d1e5d..bbd3d01a6 100644 --- a/src/Magnum/Buffer.h +++ b/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 diff --git a/src/Magnum/Mesh.h b/src/Magnum/Mesh.h index 692b1940b..223de085d 100644 --- a/src/Magnum/Mesh.h +++ b/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}, diff --git a/src/Magnum/Renderer.h b/src/Magnum/Renderer.h index d36e956b5..ff2226294 100644 --- a/src/Magnum/Renderer.h +++ b/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} diff --git a/src/Magnum/Texture.h b/src/Magnum/Texture.h index 5551e8f88..00e726294 100644 --- a/src/Magnum/Texture.h +++ b/src/Magnum/Texture.h @@ -299,6 +299,8 @@ template 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 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