From d380e07ac529c6be3f62e7fee31eda5782e95aaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 24 Oct 2013 15:47:01 +0200 Subject: [PATCH] Separated deprecated API and deprecated GL API in the docs. New code may not use deprecated API, but for some reasons (support for old GL versions) might use deprecated GL API. --- Doxyfile | 1 + doc/unsupported.dox | 8 +++++++- src/AbstractShaderProgram.h | 6 +++--- src/Buffer.h | 6 +++--- src/ColorFormat.h | 4 ++-- src/RenderbufferFormat.h | 24 ++++++++++++------------ src/TextureFormat.h | 36 ++++++++++++++++++------------------ 7 files changed, 46 insertions(+), 39 deletions(-) diff --git a/Doxyfile b/Doxyfile index 90af7401d..82e41c360 100644 --- a/Doxyfile +++ b/Doxyfile @@ -210,6 +210,7 @@ ALIASES = \ "fn_gl_extension{3}=gl\1\2()" \ "fn_gles_extension{3}=gl\1\2()" \ "def_gl{1}=`GL_\1`" \ + "deprecated_gl=@xrefitem deprecated-gl \"Deprecated OpenGL API\" \"Deprecated OpenGL API list\"" \ "requires_gl30=@xrefitem requires-gl30 \"Requires OpenGL 3.0\" \"Functionality requiring OpenGL 3.0\"" \ "requires_gl31=@xrefitem requires-gl31 \"Requires OpenGL 3.1\" \"Functionality requiring OpenGL 3.1\"" \ "requires_gl32=@xrefitem requires-gl32 \"Requires OpenGL 3.2\" \"Functionality requiring OpenGL 3.2\"" \ diff --git a/doc/unsupported.dox b/doc/unsupported.dox index 3fb080cdf..2458ca039 100644 --- a/doc/unsupported.dox +++ b/doc/unsupported.dox @@ -25,7 +25,7 @@ /** @page unsupported Unsupported OpenGL features Some functionality, which is either soon-to-be deprecated or isn't proven to -add any performance gains, is not supported in %Magnum. +add any performance gains, is not supported in %Magnum. See also @ref deprecated-gl. @section unsupported-features Unsupported features @@ -48,3 +48,9 @@ add any performance gains, is not supported in %Magnum. doesn't make any full-screen postprocessing easier, as shaders are excluded. */ + +/** @page deprecated-gl Deprecated OpenGL API list + +See also @ref unsupported. + +*/ diff --git a/src/AbstractShaderProgram.h b/src/AbstractShaderProgram.h index 90eff3d60..76f947b49 100644 --- a/src/AbstractShaderProgram.h +++ b/src/AbstractShaderProgram.h @@ -544,7 +544,7 @@ class MAGNUM_EXPORT AbstractShaderProgram { * * Binds attribute to location which is used later for binding vertex * buffers. - * @deprecated Preferred usage is to specify attribute location + * @deprecated_gl Preferred usage is to specify attribute location * explicitly in the shader instead of using this function. See * @ref AbstractShaderProgram-attribute-location "class documentation" * for more information. @@ -562,7 +562,7 @@ class MAGNUM_EXPORT AbstractShaderProgram { * Binds fragment data to location which is used later for framebuffer * operations. See also Framebuffer::BlendFunction for more * information about using color input index. - * @deprecated Preferred usage is to specify attribute location + * @deprecated_gl Preferred usage is to specify attribute location * explicitly in the shader instead of using this function. See * @ref AbstractShaderProgram-attribute-location "class documentation" * for more information. @@ -604,7 +604,7 @@ class MAGNUM_EXPORT AbstractShaderProgram { * @brief Get uniform location * @param name Uniform name * - * @deprecated Preferred usage is to specify uniform location + * @deprecated_gl Preferred usage is to specify uniform location * explicitly in the shader instead of using this function. See * @ref AbstractShaderProgram-uniform-location "class documentation" * for more information. diff --git a/src/Buffer.h b/src/Buffer.h index 6fbc7180a..aa479b3c5 100644 --- a/src/Buffer.h +++ b/src/Buffer.h @@ -319,7 +319,7 @@ class MAGNUM_EXPORT Buffer { /** * @brief Memory mapping access * - * @deprecated Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" + * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead, as it has more complete set of features. * @see map(MapAccess), mapSub() * @requires_es_extension %Extension @es_extension{OES,mapbuffer} or @@ -769,7 +769,7 @@ class MAGNUM_EXPORT Buffer { * If @extension{EXT,direct_state_access} is not available and the * buffer is not already bound somewhere, it is bound to hinted target * before the operation. - * @deprecated Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" + * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead, as it has more complete set of features. * @see @ref minMapAlignment(), @ref unmap(), @ref setTargetHint(), * @fn_gl{BindBuffer} and @fn_gl{MapBuffer} or @@ -793,7 +793,7 @@ class MAGNUM_EXPORT Buffer { * * If the buffer is not already bound somewhere, it is bound to hinted * target before the operation. - * @deprecated Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" + * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)" * instead, as it has more complete set of features. * @see unmapSub(), setTargetHint(), @fn_gl_extension{MapBufferSubData,CHROMIUM,map_sub} * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use diff --git a/src/ColorFormat.h b/src/ColorFormat.h index a1150e10f..918ff0d42 100644 --- a/src/ColorFormat.h +++ b/src/ColorFormat.h @@ -74,7 +74,7 @@ enum class ColorFormat: GLenum { /** * Floating-point luminance channel. The value is used for all RGB * channels. - * @deprecated Included for compatibility reasons only, use + * @deprecated_gl Included for compatibility reasons only, use * @ref Magnum::ColorFormat "ColorFormat::Red" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use * @ref Magnum::ColorFormat "ColorFormat::Red" instead. @@ -98,7 +98,7 @@ enum class ColorFormat: GLenum { /** * Floating-point luminance and alpha channel. First value is used for all * RGB channels, second value is used for alpha channel. - * @deprecated Included for compatibility reasons only, use + * @deprecated_gl Included for compatibility reasons only, use * @ref Magnum::ColorFormat "ColorFormat::RG" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use * @ref Magnum::ColorFormat "ColorFormat::RG" instead. diff --git a/src/RenderbufferFormat.h b/src/RenderbufferFormat.h index 9cb0add81..9397bab46 100644 --- a/src/RenderbufferFormat.h +++ b/src/RenderbufferFormat.h @@ -43,8 +43,8 @@ enum class RenderbufferFormat: GLenum { #ifndef MAGNUM_TARGET_GLES /** * Red component, normalized unsigned, size implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::R8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::R8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gl Use exactly specified format in OpenGL ES instead. */ @@ -66,8 +66,8 @@ enum class RenderbufferFormat: GLenum { /** * Red and green component, normalized unsigned, size * implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RG8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RG8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gl Use exactly specified format in OpenGL ES instead. */ @@ -88,8 +88,8 @@ enum class RenderbufferFormat: GLenum { #ifndef MAGNUM_TARGET_GLES /** * RGBA, normalized unsigned, size implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RGBA8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::RGBA8". * @requires_gl Use exactly specified format in OpenGL ES 2.0 instead. */ RGBA = GL_RGBA, @@ -383,8 +383,8 @@ enum class RenderbufferFormat: GLenum { /** * Depth component, size implementation-dependent. * @todo is this allowed in core? - * @deprecated Prefer to use exactly specified version of this format, e.g. - * @ref Magnum::RenderbufferFormat "RenderbufferFormat::DepthComponent16". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::DepthComponent16". * @requires_gl Use exactly specified format in OpenGL ES instead. */ DepthComponent = GL_DEPTH_COMPONENT, @@ -428,8 +428,8 @@ enum class RenderbufferFormat: GLenum { #ifndef MAGNUM_TARGET_GLES /** * Stencil index, size implementation-dependent. - * @deprecated Prefer to use exactly specified version of this format, e.g. - * @ref Magnum::RenderbufferFormat "RenderbufferFormat::StencilIndex8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::StencilIndex8". * @requires_gl Use exactly specified format in OpenGL ES instead. */ StencilIndex = GL_STENCIL_INDEX, @@ -469,8 +469,8 @@ enum class RenderbufferFormat: GLenum { /** * Depth and stencil component, size implementation-dependent. - * @deprecated Prefer to use exactly specified version of this format, e.g. - * @ref Magnum::RenderbufferFormat "RenderbufferFormat::Depth24Stencil8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::RenderbufferFormat "RenderbufferFormat::Depth24Stencil8". * @requires_gl Use exactly specified format in OpenGL ES instead. */ DepthStencil = GL_DEPTH_STENCIL, diff --git a/src/TextureFormat.h b/src/TextureFormat.h index 8a9732f71..c5be28182 100644 --- a/src/TextureFormat.h +++ b/src/TextureFormat.h @@ -40,8 +40,8 @@ namespace Magnum { enum class TextureFormat: GLenum { /** * Red component, normalized unsigned, size implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::TextureFormat "TextureFormat::R8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::TextureFormat "TextureFormat::R8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gles30 %Extension @es_extension{EXT,texture_rg} */ @@ -64,8 +64,8 @@ enum class TextureFormat: GLenum { /** * Red and green component, normalized unsigned, size * implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::TextureFormat "TextureFormat::RG8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RG8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gles30 %Extension @es_extension{EXT,texture_rg} */ @@ -87,8 +87,8 @@ enum class TextureFormat: GLenum { /** * RGB, normalized unsigned, size implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::TextureFormat "TextureFormat::RGB8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RGB8". */ RGB = GL_RGB, @@ -104,8 +104,8 @@ enum class TextureFormat: GLenum { /** * RGBA, normalized unsigned, size implementation-dependent. - * @deprecated Prefer to use the exactly specified version of this format, - * e.g. @ref Magnum::TextureFormat "TextureFormat::RGBA8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RGBA8". */ RGBA = GL_RGBA, @@ -475,7 +475,7 @@ enum class TextureFormat: GLenum { /** * Luminance, normalized unsigned, single value used for all RGB channels. * Size implementation-dependent. - * @deprecated Included for compatibility reasons only, use + * @deprecated_gl Included for compatibility reasons only, use * @ref Magnum::TextureFormat "TextureFormat::R8" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use * @ref Magnum::TextureFormat "TextureFormat::R8" instead. @@ -486,7 +486,7 @@ enum class TextureFormat: GLenum { * Floating-point luminance and alpha channel. First value is used for all * RGB channels, second value is used for alpha channel. Size * implementation-dependent. - * @deprecated Included for compatibility reasons only, use + * @deprecated_gl Included for compatibility reasons only, use * @ref Magnum::TextureFormat "TextureFormat::RG8" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use * @ref Magnum::TextureFormat "TextureFormat::RG8" instead. @@ -564,8 +564,8 @@ enum class TextureFormat: GLenum { /** * sRGB, normalized unsigned, size implementation-dependent. * @todo is this allowed in core? - * @deprecated Prefer to use the exactly specified version of this format, - * i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8". * @requires_es_extension %Extension @es_extension{EXT,sRGB} in OpenGL ES * 2.0, use @ref Magnum::TextureFormat "TextureFormat::SRGB8" in * OpenGL ES 3.0 instead. @@ -639,8 +639,8 @@ enum class TextureFormat: GLenum { /** * sRGBA, normalized unsigned, size implementation-dependent. * @todo is this allowed in core? - * @deprecated Prefer to use the exactly specified version of this format, - * i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8Alpha8". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8Alpha8". * @requires_es_extension %Extension @es_extension{EXT,sRGB} in OpenGL ES * 2.0, use @ref Magnum::TextureFormat "TextureFormat::SRGB8Alpha8" in * OpenGL ES 3.0 instead. @@ -751,8 +751,8 @@ enum class TextureFormat: GLenum { /** * Depth component, size implementation-dependent. - * @deprecated Prefer to use exactly specified version of this format, e.g. - * @ref Magnum::TextureFormat "TextureFormat::DepthComponent16". + * @deprecated_gl Prefer to use the exactly specified version of this + * format, e.g. @ref Magnum::TextureFormat "TextureFormat::DepthComponent16". * @requires_gles30 %Extension @es_extension{OES,depth_texture} or * @es_extension{ANGLE,depth_texture} */ @@ -812,8 +812,8 @@ enum class TextureFormat: GLenum { /** * Depth and stencil component, size implementation-dependent. - * @deprecated Prefer to use exactly specified version of this format, e.g. - * @ref Magnum::TextureFormat "TextureFormat::Depth24Stencil8". + * @deprecated_gl Prefer to use exactly specified version of this format, + * e.g. @ref Magnum::TextureFormat "TextureFormat::Depth24Stencil8". * @requires_gles30 %Extension @es_extension{OES,packed_depth_stencil} */ #ifndef MAGNUM_TARGET_GLES2