Magnum::DebugTools namespace

Debug tools.

Contents

Debugging helpers, renderers and profilers.

This library is built if WITH_DEBUGTOOLS is enabled when building Magnum. To use this library with CMake, you need to request the DebugTools component of the Magnum package and link to the Magnum::DebugTools target:

find_package(Magnum REQUIRED DebugTools)

# ...
target_link_libraries(your-app Magnum::DebugTools)

See Downloading and building, Usage with CMake and Debugging helpers for more information.

Classes

class CompareFileToImage
File-to-image comparator.
class CompareImage
Image comparator.
class CompareImageFile
Image file comparator.
class CompareImageToFile
Image-to-file comparator.
template<UnsignedInt dimensions>
class ForceRenderer
Force renderer.
class ForceRendererOptions
Force renderer options.
template<UnsignedInt dimensions>
class ObjectRenderer
Object renderer.
class ObjectRendererOptions
Object renderer options.
class Profiler
Profiler.
class ResourceManager
Resource manager for debug tools.

Typedefs

using ForceRenderer2D = ForceRenderer<2>
Two-dimensional force renderer.
using ForceRenderer3D = ForceRenderer<3>
Three-dimensional force renderer.
using ObjectRenderer2D = ObjectRenderer<2>
Two-dimensional object renderer.
using ObjectRenderer3D = ObjectRenderer<3>
Three-dimensional object renderer.

Functions

template<class T>
auto bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> Containers::Array<T>
Buffer subdata.
template<class T = char>
auto bufferData(GL::Buffer& buffer) -> Containers::Array<T>
Buffer data.
auto screenshot(GL::AbstractFramebuffer& framebuffer, const std::string& filename) -> bool
Save a screenshot to a file.
auto screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, const std::string& filename) -> bool
auto screenshot(GL::AbstractFramebuffer& framebuffer, PixelFormat format, const std::string& filename) -> bool
Save a screenshot in requested pixel format to a file.
auto screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, PixelFormat format, const std::string& filename) -> bool
void textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D& image)
Read range of given texture mip level to image.
auto textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D&& image) -> Image2D
Read range of given texture mip level to image.
void textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage)
Read range of given texture mip level to buffer image.
auto textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage) -> GL::BufferImage2D
Read range of given texture mip level to buffer image.
void textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D& image)
Read range of given cube map texture coordinate mip level to image.
auto textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D&& image) -> Image2D
Read range of given cube map texture coordinate mip level to image.
void textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage)
Read range of given cube map texture coordinate mip level to buffer image.
auto textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage) -> GL::BufferImage2D
Read range of given cube map texture coordinate mip level to buffer image.

Typedef documentation

typedef ForceRenderer<2> Magnum::DebugTools::ForceRenderer2D

Two-dimensional force renderer.

typedef ForceRenderer<3> Magnum::DebugTools::ForceRenderer3D

Three-dimensional force renderer.

typedef ObjectRenderer<2> Magnum::DebugTools::ObjectRenderer2D

Two-dimensional object renderer.

typedef ObjectRenderer<3> Magnum::DebugTools::ObjectRenderer3D

Three-dimensional object renderer.

Function documentation

template<class T>
Containers::Array<T> Magnum::DebugTools::bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size)

Buffer subdata.

Emulates GL::Buffer::subData() call on platforms that don't support it (such as OpenGL ES) by using GL::Buffer::map().

template<class T = char>
Containers::Array<T> Magnum::DebugTools::bufferData(GL::Buffer& buffer)

Buffer data.

Emulates GL::Buffer::data() call on platforms that don't support it (such as OpenGL ES) by using GL::Buffer::map().

bool Magnum::DebugTools::screenshot(GL::AbstractFramebuffer& framebuffer, const std::string& filename)

Save a screenshot to a file.

Parameters
framebuffer Framebuffer which to read
filename File where to save

Reads a rectangle of given framebuffer, defined by its viewport(). Pixel format is queried using GL::AbstractFramebuffer::implementationColorReadFormat() and GL::AbstractFramebuffer::implementationColorReadType() and then mapped back to the generic PixelFormat. If, for some reason, the driver-suggested pixel format is not desired, use the screenshot(GL::AbstractFramebuffer&, PixelFormat, const std::string&) overload instead.

The read pixel data are saved using the AnyImageConverter plugin, with format being detected from filename. Note that every file format supports a different set of pixel formats, it's the user responsibility to choose a file format that matches the framebuffer pixel format.

Returns true on success, false in case it was not possible to map the detected pixel format back to a generic format, if either the AnyImageConverter or the corresponding plugin for given file format could not be loaded, or if the file saving fails (for example due to unsupported pixel format). A message is printed in each case.

bool Magnum::DebugTools::screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, const std::string& filename)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Useful in case you already have an instance of the converter plugin manager in your application or if you intend to save screenshots often, as the operation doesn't involve costly dynamic library loading and unloading on every call.

bool Magnum::DebugTools::screenshot(GL::AbstractFramebuffer& framebuffer, PixelFormat format, const std::string& filename)

Save a screenshot in requested pixel format to a file.

Parameters
framebuffer Framebuffer which to read
format Pixel format to use
filename File where to save

Similar to screenshot(GL::AbstractFramebuffer&, PixelFormat, const std::string&) but with an explicit pixel format. Useful in cases where the driver-suggested pixel format is not desired, however note that supplying a format that's incompatible with the framebuffer may result in GL errors.

bool Magnum::DebugTools::screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, PixelFormat format, const std::string& filename)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Useful in case you already have an instance of the converter plugin manager in your application or if you intend to save screenshots often, as the operation doesn't involve costly dynamic library loading and unloading on every call.

void Magnum::DebugTools::textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D& image)

Read range of given texture mip level to image.

Emulates GL::Texture2D::subImage() call on platforms that don't support it (such as OpenGL ES) by creating a framebuffer object and using GL::Framebuffer::read(). On desktop OpenGL, if ARB_get_texture_sub_image is available, it's just an alias to GL::Texture2D::subImage().

Note that only GL::PixelFormat and GL::PixelType values that are marked as framebuffer readable are supported; their generic PixelFormat counterparts are supported as well. In addition, on OpenGL ES 3.0, images with GL::PixelType::Float are supported — they are reinterpreted as GL::PixelType::UnsignedInt using an additional shader and the floatBitsToUint() GLSL function and then reinterpreted back to GL::PixelType::Float when read to client memory.

Image2D Magnum::DebugTools::textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, Image2D&& image)

Read range of given texture mip level to image.

Convenience alternative to the above, example usage:

Image2D image = DebugTools::textureSubImage(texture, 0, rect,
    {PixelFormat::RGBA8Unorm});

void Magnum::DebugTools::textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage)

Read range of given texture mip level to buffer image.

Emulates GL::Texture2D::subImage() call on platforms that don't support it (such as OpenGL ES) by creating a framebuffer object and using GL::Framebuffer::read(). On desktop OpenGL, if ARB_get_texture_sub_image is available, it's just an alias to GL::Texture2D::subImage().

Note that only GL::PixelFormat and GL::PixelType values that are marked as framebuffer readable are supported; their generic PixelFormat counterparts are supported as well.

GL::BufferImage2D Magnum::DebugTools::textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage)

Read range of given texture mip level to buffer image.

Convenience alternative to the above, example usage:

GL::BufferImage2D image = DebugTools::textureSubImage(texture, 0, rect,
    {PixelFormat::RGBA8Unorm}, GL::BufferUsage::StaticRead);

void Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D& image)

Read range of given cube map texture coordinate mip level to image.

Emulates GL::CubeMapTexture::subImage() call on platforms that don't support it (such as OpenGL ES) by creating a framebuffer object and using GL::Framebuffer::read().

Note that only GL::PixelFormat and GL::PixelType values that are marked as framebuffer readable are supported; their generic PixelFormat counterparts are supported as well.

Image2D Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D&& image)

Read range of given cube map texture coordinate mip level to image.

Convenience alternative to the above, example usage:

Image2D image = DebugTools::textureSubImage(texture,
    GL::CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA8Unorm});

void Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage)

Read range of given cube map texture coordinate mip level to buffer image.

Emulates GL::CubeMapTexture::subImage() call on platforms that don't support it (such as OpenGL ES) by creating a framebuffer object and using GL::Framebuffer::read().

Note that only GL::PixelFormat and GL::PixelType values that are marked as framebuffer readable are supported; their generic PixelFormat counterparts are supported as well.

GL::BufferImage2D Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage)

Read range of given cube map texture coordinate mip level to buffer image.

Convenience alternative to the above, example usage:

GL::BufferImage2D image = DebugTools::textureSubImage(texture,
    GL::CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA8Unorm},
    GL::BufferUsage::StaticRead);