From a9fe635867a8217de113e57c3efe85bd8c98e932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 12 Dec 2013 18:28:23 +0100 Subject: [PATCH] Updated and improved ColorFormat, ColorType and TextureFormat enum docs. Finishing promises made in #31. --- src/ColorFormat.h | 85 ++++++++++++++++++++++++++++----------------- src/TextureFormat.h | 58 ++++++++++++++++++------------- 2 files changed, 86 insertions(+), 57 deletions(-) diff --git a/src/ColorFormat.h b/src/ColorFormat.h index 54c014d7f..dadccf2cd 100644 --- a/src/ColorFormat.h +++ b/src/ColorFormat.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Enum Magnum::ColorFormat, Magnum::ColorType + * @brief Enum @ref Magnum::ColorFormat, @ref Magnum::ColorType */ #include "Magnum.h" @@ -38,9 +38,18 @@ namespace Magnum { @brief Format of image data Note that some formats can be used only for framebuffer reading (using -AbstractFramebuffer::read()) and some only for texture data (using Texture::setImage() -and others). -@see Image, ImageReference, BufferImage, Trade::ImageData +@ref AbstractFramebuffer::read()) and some only for texture data (using +@ref Texture::setImage() and others), the limitations are mentioned in +documentation of each particular value. + +In most cases you may want to use @ref ColorFormat::Red (for grayscale images), +@ref ColorFormat::RGB or @ref ColorFormat::RGBA along with +@ref ColorType::UnsignedByte, the matching texture format is then +@ref TextureFormat::R8, @ref TextureFormat::RGB8 or @ref TextureFormat::RGBA8. +See documentation of these values for possible limitations when using OpenGL ES +2.0 or WebGL. + +@see @ref Image, @ref ImageReference, @ref BufferImage, @ref Trade::ImageData */ enum class ColorFormat: GLenum { /** @@ -57,14 +66,14 @@ enum class ColorFormat: GLenum { #ifndef MAGNUM_TARGET_GLES /** * Floating-point green channel. - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::Red" is + * @requires_gl Only @ref Magnum::ColorFormat::Red "ColorFormat::Red" is * available in OpenGL ES. */ Green = GL_GREEN, /** * Floating-point blue channel. - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::Red" is + * @requires_gl Only @ref Magnum::ColorFormat::Red "ColorFormat::Red" is * available in OpenGL ES. */ Blue = GL_BLUE, @@ -75,9 +84,9 @@ enum class ColorFormat: GLenum { * Floating-point luminance channel. The value is used for all RGB * channels. * @deprecated_gl Included for compatibility reasons only, use - * @ref Magnum::ColorFormat "ColorFormat::Red" instead. + * @ref Magnum::ColorFormat::Red "ColorFormat::Red" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use - * @ref Magnum::ColorFormat "ColorFormat::Red" instead. + * @ref Magnum::ColorFormat::Red "ColorFormat::Red" instead. */ Luminance = GL_LUMINANCE, #endif @@ -99,9 +108,9 @@ 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_gl Included for compatibility reasons only, use - * @ref Magnum::ColorFormat "ColorFormat::RG" instead. + * @ref Magnum::ColorFormat::RG "ColorFormat::RG" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use - * @ref Magnum::ColorFormat "ColorFormat::RG" instead. + * @ref Magnum::ColorFormat::RG "ColorFormat::RG" instead. */ LuminanceAlpha = GL_LUMINANCE_ALPHA, #endif @@ -148,7 +157,7 @@ enum class ColorFormat: GLenum { /** * Integer green channel. * @requires_gl30 %Extension @extension{EXT,texture_integer} - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::RedInteger" + * @requires_gl Only @ref Magnum::ColorFormat::RedInteger "ColorFormat::RedInteger" * is available in OpenGL ES 3.0, only floating-point image data are * available in OpenGL ES 2.0. */ @@ -157,8 +166,8 @@ enum class ColorFormat: GLenum { /** * Integer blue channel. * @requires_gl30 %Extension @extension{EXT,texture_integer} - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::RedInteger" is - * available in OpenGL ES 3.0, only floating-point image data are + * @requires_gl Only @ref Magnum::ColorFormat::RedInteger "ColorFormat::RedInteger" + * is available in OpenGL ES 3.0, only floating-point image data are * available in OpenGL ES 2.0. */ BlueInteger = GL_BLUE_INTEGER, @@ -194,8 +203,8 @@ enum class ColorFormat: GLenum { /** * Integer BGR. * @requires_gl30 %Extension @extension{EXT,texture_integer} - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::RGBInteger" is - * available in OpenGL ES 3.0, only floating-point image data are + * @requires_gl Only @ref Magnum::ColorFormat::RGBInteger "ColorFormat::RGBInteger" + * is available in OpenGL ES 3.0, only floating-point image data are * available in OpenGL ES 2.0. */ BGRInteger = GL_BGR_INTEGER, @@ -203,8 +212,8 @@ enum class ColorFormat: GLenum { /** * Integer BGRA. * @requires_gl30 %Extension @extension{EXT,texture_integer} - * @requires_gl Only @ref Magnum::ColorFormat "ColorFormat::RGBAInteger" is - * available in OpenGL ES 3.0, only floating-point image data are + * @requires_gl Only @ref Magnum::ColorFormat::RGBAInteger "ColorFormat::RGBAInteger" + * is available in OpenGL ES 3.0, only floating-point image data are * available in OpenGL ES 2.0. */ BGRAInteger = GL_BGRA_INTEGER, @@ -251,9 +260,18 @@ enum class ColorFormat: GLenum { @brief Type of image data Note that some formats can be used only for framebuffer reading (using -AbstractFramebuffer::read()) and some only for texture data (using Texture::setImage() -and others). -@see Image, ImageReference, BufferImage, Trade::ImageData +@ref AbstractFramebuffer::read()) and some only for texture data (using +@ref Texture::setImage() and others), the limitations are mentioned in +documentation of each particular value. + +In most cases you may want to use @ref ColorType::UnsignedByte along with +@ref ColorFormat::Red (for grayscale images), @ref ColorFormat::RGB or +@ref ColorFormat::RGBA, the matching texture format is then +@ref TextureFormat::R8, @ref TextureFormat::RGB8 or @ref TextureFormat::RGBA8. +See documentation of these values for possible limitations when using OpenGL ES +2.0 or WebGL. + +@see @ref Image, @ref ImageReference, @ref BufferImage, @ref Trade::ImageData */ enum class ColorType: GLenum { /** Each component unsigned byte. */ @@ -263,8 +281,9 @@ enum class ColorType: GLenum { /** * Each component signed byte. * @requires_gl Can't be used for framebuffer reading in OpenGL ES. - * @requires_gles30 For texture data only, only @ref Magnum::ColorType "ColorType::UnsignedByte" - * is available in OpenGL ES 2.0. + * @requires_gles30 For texture data only, only + * @ref Magnum::ColorType::UnsignedByte "ColorType::UnsignedByte" is + * available in OpenGL ES 2.0. */ Byte = GL_BYTE, #endif @@ -281,8 +300,9 @@ enum class ColorType: GLenum { /** * Each component signed short. * @requires_gl Can't be used for framebuffer reading in OpenGL ES. - * @requires_gles30 For texture data only, only @ref Magnum::ColorType "ColorType::UnsignedShort" - * is available in OpenGL ES 2.0. + * @requires_gles30 For texture data only, only + * @ref Magnum::ColorType::UnsignedShort "ColorType::UnsignedShort" is + * available in OpenGL ES 2.0. */ Short = GL_SHORT, #endif @@ -298,7 +318,7 @@ enum class ColorType: GLenum { #ifndef MAGNUM_TARGET_GLES2 /** * Each component signed int. - * @requires_gles30 Only @ref Magnum::ColorType "ColorType::UnsignedInt" + * @requires_gles30 Only @ref Magnum::ColorType::UnsignedInt "ColorType::UnsignedInt" * is available in OpenGL ES 2.0. */ Int = GL_INT, @@ -345,7 +365,7 @@ enum class ColorType: GLenum { #ifndef MAGNUM_TARGET_GLES /** * BGR, unsigned short, red and blue 5bit, green 6bit. - * @requires_gl Only @ref Magnum::ColorType "ColorType::RGB565" is + * @requires_gl Only @ref Magnum::ColorType::RGB565 "ColorType::RGB565" is * available in OpenGL ES. */ UnsignedShort565Rev = GL_UNSIGNED_SHORT_5_6_5_REV, @@ -388,22 +408,22 @@ enum class ColorType: GLenum { #ifndef MAGNUM_TARGET_GLES /** * RGBA, unsigned int, each component 8bit. - * @requires_gl Use @ref Magnum::ColorType "ColorType::UnsignedByte" in - * OpenGL ES instead. + * @requires_gl Use @ref Magnum::ColorType::UnsignedByte "ColorType::UnsignedByte" + * in OpenGL ES instead. */ UnsignedInt8888 = GL_UNSIGNED_INT_8_8_8_8, /** * ABGR, unsigned int, each component 8bit. * @requires_gl Only RGBA component ordering is available in OpenGL ES, see - * @ref Magnum::ColorType "ColorType::UnsignedInt8888" for more - * information. + * @ref Magnum::ColorType::UnsignedInt8888 "ColorType::UnsignedInt8888" + * for more information. */ UnsignedInt8888Rev = GL_UNSIGNED_INT_8_8_8_8_REV, /** * RGBA, unsigned int, each RGB component 10bit, alpha component 2bit. - * @requires_gl Only @ref Magnum::ColorType "ColorType::UnsignedInt2101010Rev" + * @requires_gl Only @ref Magnum::ColorType::UnsignedInt2101010Rev "ColorType::UnsignedInt2101010Rev" * is available in OpenGL ES. */ UnsignedInt1010102 = GL_UNSIGNED_INT_10_10_10_2, @@ -455,7 +475,8 @@ enum class ColorType: GLenum { * Float + unsigned int, depth component 32bit float, 24bit gap, stencil * index 8bit. * @requires_gl30 %Extension @extension{ARB,depth_buffer_float} - * @requires_gles30 For texture data only, only @ref Magnum::ColorType "ColorType::UnsignedInt248" + * @requires_gles30 For texture data only, only + * @ref Magnum::ColorType::UnsignedInt248 "ColorType::UnsignedInt248" * is available in OpenGL ES 2.0. */ Float32UnsignedInt248Rev = GL_FLOAT_32_UNSIGNED_INT_24_8_REV diff --git a/src/TextureFormat.h b/src/TextureFormat.h index 57e16f9b8..e9ebe6b81 100644 --- a/src/TextureFormat.h +++ b/src/TextureFormat.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Enum Magnum::TextureFormat + * @brief Enum @ref Magnum::TextureFormat */ #include "OpenGL.h" @@ -35,13 +35,20 @@ namespace Magnum { /** @brief Internal texture format -@see Texture, CubeMapTexture, CubeMapTextureArray +In most cases you may want to use @ref TextureFormat::R8 (for grayscale +textures), @ref TextureFormat::RGB8 or @ref TextureFormat::RGBA8. The matching +color format is then @ref ColorFormat::Red, @ref ColorFormat::RGB or +@ref ColorFormat::RGBA along with @ref ColorType::UnsignedByte. See +documentation of these values for possible limitations when using OpenGL ES 2.0 +or WebGL. + +@see @ref Texture, @ref CubeMapTexture, @ref CubeMapTextureArray */ enum class TextureFormat: GLenum { /** * Red component, normalized unsigned, size implementation-dependent. * @deprecated_gl Prefer to use the exactly specified version of this - * format, e.g. @ref Magnum::TextureFormat "TextureFormat::R8". + * format, e.g. @ref Magnum::TextureFormat::R8 "TextureFormat::R8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gles30 %Extension @es_extension{EXT,texture_rg} */ @@ -55,8 +62,8 @@ enum class TextureFormat: GLenum { /** * Red component, normalized unsigned byte. * @requires_gl30 %Extension @extension{ARB,texture_rg} - * @requires_gles30 Use @ref Magnum::TextureFormat "TextureFormat::Red" in - * OpenGL ES 2.0 instead. + * @requires_gles30 Use @ref Magnum::TextureFormat::Red "TextureFormat::Red" + * in OpenGL ES 2.0 instead. */ R8 = GL_R8, #endif @@ -65,7 +72,7 @@ enum class TextureFormat: GLenum { * Red and green component, normalized unsigned, size * implementation-dependent. * @deprecated_gl Prefer to use the exactly specified version of this - * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RG8". + * format, e.g. @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8". * @requires_gl30 %Extension @extension{ARB,texture_rg} * @requires_gles30 %Extension @es_extension{EXT,texture_rg} */ @@ -79,8 +86,8 @@ enum class TextureFormat: GLenum { /** * Red and green component, each normalized unsigned byte. * @requires_gl30 %Extension @extension{ARB,texture_rg} - * @requires_gles30 Use @ref Magnum::TextureFormat "TextureFormat::RG" in - * OpenGL ES 2.0 instead. + * @requires_gles30 Use @ref Magnum::TextureFormat::RG "TextureFormat::RG" + * in OpenGL ES 2.0 instead. */ RG8 = GL_RG8, #endif @@ -88,7 +95,7 @@ enum class TextureFormat: GLenum { /** * RGB, normalized unsigned, size implementation-dependent. * @deprecated_gl Prefer to use the exactly specified version of this - * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RGB8". + * format, e.g. @ref Magnum::TextureFormat::RGB8 "TextureFormat::RGB8". */ RGB = GL_RGB, @@ -105,7 +112,7 @@ enum class TextureFormat: GLenum { /** * RGBA, normalized unsigned, size implementation-dependent. * @deprecated_gl Prefer to use the exactly specified version of this - * format, e.g. @ref Magnum::TextureFormat "TextureFormat::RGBA8". + * format, e.g. @ref Magnum::TextureFormat::RGBA8 "TextureFormat::RGBA8". */ RGBA = GL_RGBA, @@ -476,9 +483,9 @@ enum class TextureFormat: GLenum { * Luminance, normalized unsigned, single value used for all RGB channels. * Size implementation-dependent. * @deprecated_gl Included for compatibility reasons only, use - * @ref Magnum::TextureFormat "TextureFormat::R8" instead. + * @ref Magnum::TextureFormat::R8 "TextureFormat::R8" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use - * @ref Magnum::TextureFormat "TextureFormat::R8" instead. + * @ref Magnum::TextureFormat::R8 "TextureFormat::R8" instead. */ Luminance = GL_LUMINANCE, @@ -487,9 +494,9 @@ enum class TextureFormat: GLenum { * RGB channels, second value is used for alpha channel. Size * implementation-dependent. * @deprecated_gl Included for compatibility reasons only, use - * @ref Magnum::TextureFormat "TextureFormat::RG8" instead. + * @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8" instead. * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use - * @ref Magnum::TextureFormat "TextureFormat::RG8" instead. + * @ref Magnum::TextureFormat::RG8 "TextureFormat::RG8" instead. */ LuminanceAlpha = GL_LUMINANCE_ALPHA, #endif @@ -509,8 +516,9 @@ enum class TextureFormat: GLenum { /** * RGB, each component normalized unsigned 5bit. - * @requires_gl Use @ref Magnum::TextureFormat "TextureFormat::RGB5A1" or - * @ref Magnum::TextureFormat "TextureFormat::RGB565" in OpenGL ES. + * @requires_gl Use @ref Magnum::TextureFormat::RGB5A1 "TextureFormat::RGB5A1" + * or @ref Magnum::TextureFormat::RGB565 "TextureFormat::RGB565" in + * OpenGL ES. */ RGB5 = GL_RGB5, #endif @@ -552,8 +560,8 @@ enum class TextureFormat: GLenum { /** * RGB, unsigned with exponent, each RGB component 9bit, exponent 5bit. * @requires_gl30 %Extension @extension{EXT,texture_shared_exponent} - * @requires_gles30 Use @ref Magnum::TextureFormat "TextureFormat::RGB" in - * OpenGL ES 2.0 instead. + * @requires_gles30 Use @ref Magnum::TextureFormat::RGB "TextureFormat::RGB" + * in OpenGL ES 2.0 instead. */ RGB9E5 = GL_RGB9_E5, #endif @@ -562,7 +570,7 @@ enum class TextureFormat: GLenum { * sRGB, normalized unsigned, size implementation-dependent. * @todo is this allowed in core? * @deprecated_gl Prefer to use the exactly specified version of this - * format, i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8". + * format, i.e. @ref Magnum::TextureFormat::SRGB8 "TextureFormat::SRGB8". * @requires_es_extension %Extension @es_extension{EXT,sRGB} */ #ifndef MAGNUM_TARGET_GLES @@ -574,8 +582,8 @@ enum class TextureFormat: GLenum { #ifndef MAGNUM_TARGET_GLES2 /** * sRGB, each component normalized unsigned byte. - * @requires_gles30 Use @ref Magnum::TextureFormat "TextureFormat::SRGB" in - * OpenGL ES 2.0 instead. + * @requires_gles30 Use @ref Magnum::TextureFormat::SRGB "TextureFormat::SRGB" + * in OpenGL ES 2.0 instead. */ SRGB8 = GL_SRGB8, #endif @@ -633,7 +641,7 @@ enum class TextureFormat: GLenum { * sRGBA, normalized unsigned, size implementation-dependent. * @todo is this allowed in core? * @deprecated_gl Prefer to use the exactly specified version of this - * format, i.e. @ref Magnum::TextureFormat "TextureFormat::SRGB8Alpha8". + * format, i.e. @ref Magnum::TextureFormat::SRGB8Alpha8 "TextureFormat::SRGB8Alpha8". * @requires_es_extension %Extension @es_extension{EXT,sRGB} */ #ifndef MAGNUM_TARGET_GLES @@ -645,7 +653,7 @@ enum class TextureFormat: GLenum { #ifndef MAGNUM_TARGET_GLES2 /** * sRGBA, each component normalized unsigned byte. - * @requires_gles30 Use @ref Magnum::TextureFormat "TextureFormat::SRGBAlpha" + * @requires_gles30 Use @ref Magnum::TextureFormat::SRGBAlpha "TextureFormat::SRGBAlpha" * in OpenGL ES 2.0 instead. */ SRGB8Alpha8 = GL_SRGB8_ALPHA8, @@ -742,7 +750,7 @@ enum class TextureFormat: GLenum { /** * Depth component, size implementation-dependent. * @deprecated_gl Prefer to use the exactly specified version of this - * format, e.g. @ref Magnum::TextureFormat "TextureFormat::DepthComponent16". + * format, e.g. @ref Magnum::TextureFormat::DepthComponent16 "TextureFormat::DepthComponent16". * @requires_gles30 %Extension @es_extension{OES,depth_texture} or * @es_extension{ANGLE,depth_texture} */ @@ -801,7 +809,7 @@ enum class TextureFormat: GLenum { /** * Depth and stencil component, size implementation-dependent. * @deprecated_gl Prefer to use exactly specified version of this format, - * e.g. @ref Magnum::TextureFormat "TextureFormat::Depth24Stencil8". + * e.g. @ref Magnum::TextureFormat::Depth24Stencil8 "TextureFormat::Depth24Stencil8". * @requires_gles30 %Extension @es_extension{OES,packed_depth_stencil} */ #ifndef MAGNUM_TARGET_GLES2