From 342013659a43d8c9cf3fc5da341260691baa14dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 10 Mar 2025 13:34:11 +0100 Subject: [PATCH] DebugTools: fix bad wording in textureSubImage() docs. --- src/Magnum/DebugTools/TextureImage.h | 47 ++++++++++++++-------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/src/Magnum/DebugTools/TextureImage.h b/src/Magnum/DebugTools/TextureImage.h index 5b82a8a97..9e960a938 100644 --- a/src/Magnum/DebugTools/TextureImage.h +++ b/src/Magnum/DebugTools/TextureImage.h @@ -40,12 +40,12 @@ namespace Magnum { namespace DebugTools { /** -@brief Read range of given texture mip level to image +@brief Read a range of given texture mip level to an image -Emulates @ref GL::Texture2D::subImage() call on platforms that don't support it -(such as OpenGL ES) by creating a framebuffer object and using -@ref GL::Framebuffer::read(). On desktop OpenGL, if @gl_extension{ARB,get_texture_sub_image} -is available, it's just an alias to @ref GL::Texture2D::subImage(). +Emulates @ref GL::Texture2D::subImage() on OpenGL ES and WebGL platforms by +creating a framebuffer object and using @ref GL::Framebuffer::read(). On +desktop OpenGL, if @gl_extension{ARB,get_texture_sub_image} is available, it's +just an alias to @ref GL::Texture2D::subImage(). The function expects that @p texture has a @ref GL::TextureFormat that's framebuffer-readable and that the @ref GL::PixelFormat and @ref GL::PixelType @@ -65,7 +65,7 @@ treatment is done for any other types. MAGNUM_DEBUGTOOLS_EXPORT void textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D& image); /** -@brief Read range of given texture mip level to image +@brief Read a range of given texture mip level to an image Convenience alternative to the above, example usage: @@ -78,17 +78,17 @@ Convenience alternative to the above, example usage: MAGNUM_DEBUGTOOLS_EXPORT Image2D textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D&& image); /** -@brief Read range of given cube map texture coordinate mip level to image +@brief Read a range of given cube map texture coordinate mip level to an image +@m_since_latest -Emulates @ref GL::CubeMapTexture::subImage() call on platforms that don't -support it (such as OpenGL ES) by creating a framebuffer object and using +Emulates @ref GL::CubeMapTexture::subImage() call on OpenGL ES and WebGL +platforms by creating a framebuffer object and using @ref GL::Framebuffer::read(). The function expects that @p texture has a @ref GL::TextureFormat that's framebuffer-readable and that the @ref GL::PixelFormat and @ref GL::PixelType combination or the generic @relativeref{Magnum,PixelFormat} is compatible with -it - +it. @note This function is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" enabled (done by default). See @ref building-features for more information. @@ -110,7 +110,7 @@ MAGNUM_DEBUGTOOLS_EXPORT Image2D textureSubImage(GL::CubeMapTexture& texture, GL #if defined(MAGNUM_BUILD_DEPRECATED) && !defined(MAGNUM_TARGET_GLES2) /** -@brief Read range of given texture mip level to buffer image +@brief Read a range of given texture mip level to a buffer image @m_deprecated_since_latest As these APIs are mainly meant to be used for testing and verification, there's little point in having a variant that puts the data into a pixel buffer by creating a temporary framebuffer. Use @@ -119,16 +119,15 @@ MAGNUM_DEBUGTOOLS_EXPORT Image2D textureSubImage(GL::CubeMapTexture& texture, GL @ref GL::Framebuffer::read(const Range2Di&, GL::BufferImage2D&, GL::BufferUsage) on a non-temporary framebuffer. -Emulates @ref GL::Texture2D::subImage() call on platforms that don't support it -(such as OpenGL ES) by creating a framebuffer object and using -@ref GL::Framebuffer::read(). On desktop OpenGL, if -@gl_extension{ARB,get_texture_sub_image} is available, it's just an alias to -@ref GL::Texture2D::subImage(). +Emulates @ref GL::Texture2D::subImage() call on OpenGL ES and WebGL platforms +by creating a framebuffer object and using @ref GL::Framebuffer::read(). On +desktop OpenGL, if @gl_extension{ARB,get_texture_sub_image} is available, it's +just an alias to @ref GL::Texture2D::subImage(). The function expects that @p texture has a @ref GL::TextureFormat that's framebuffer-readable and that the @ref GL::PixelFormat and @ref GL::PixelType combination or the generic @relativeref{Magnum,PixelFormat} is compatible with -it +it. @requires_gles30 Pixel buffer objects are not available in OpenGL ES 2.0. @requires_webgl20 Pixel buffer objects are not available in WebGL 1.0. @@ -139,7 +138,7 @@ it MAGNUM_DEBUGTOOLS_EXPORT CORRADE_DEPRECATED("use textureSubImage(GL::Texture2D&, Int, const Range2Di&, Image2D&) instead") void textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage); /** -@brief Read range of given texture mip level to buffer image +@brief Read a range of given texture mip level to a buffer image @m_deprecated_since_latest As these APIs are mainly meant to be used for testing and verification, there's little point in having a variant that puts the data into a buffer image by creating a temporary framebuffer. Use @@ -159,7 +158,7 @@ Convenience alternative to the above, example usage: MAGNUM_DEBUGTOOLS_EXPORT CORRADE_DEPRECATED("use textureSubImage(GL::Texture2D&, Int, const Range2Di&, Image2D&&) instead") GL::BufferImage2D textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage); /** -@brief Read range of given cube map texture coordinate mip level to buffer image +@brief Read a range of given cube map texture coordinate mip level to a buffer image @m_deprecated_since_latest As these APIs are mainly meant to be used for testing and verification, there's little point in having a variant that puts the data into a buffer image by creating a temporary framebuffer. Use @@ -168,14 +167,14 @@ MAGNUM_DEBUGTOOLS_EXPORT CORRADE_DEPRECATED("use textureSubImage(GL::Texture2D&, @ref GL::Framebuffer::read(const Range2Di&, GL::BufferImage2D&, GL::BufferUsage) on a non-temporary framebuffer. -Emulates @ref GL::CubeMapTexture::subImage() call on platforms that don't -support it (such as OpenGL ES) by creating a framebuffer object and using +Emulates @ref GL::CubeMapTexture::subImage() call on OpenGL ES and WebGL +platforms by creating a framebuffer object and using @ref GL::Framebuffer::read(). The function expects that @p texture has a @ref GL::TextureFormat that's framebuffer-readable and that the @ref GL::PixelFormat and @ref GL::PixelType combination or the generic @relativeref{Magnum,PixelFormat} is compatible with -it +it. @requires_gles30 Pixel buffer objects are not available in OpenGL ES 2.0. @requires_webgl20 Pixel buffer objects are not available in WebGL 1.0. @@ -186,7 +185,7 @@ it MAGNUM_DEBUGTOOLS_EXPORT CORRADE_DEPRECATED("use textureSubImage(GL::CubeMapTexture2D&, GL::CubeMapCoordinate, Int, const Range2Di&, Image2D&) instead") void textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage); /** -@brief Read range of given cube map texture coordinate mip level to buffer image +@brief Read a range of given cube map texture coordinate mip level to a buffer image @m_deprecated_since_latest As these APIs are mainly meant to be used for testing and verification, there's little point in having a variant that puts the data into a buffer image by creating a temporary framebuffer. Use