Magnum::DebugTools namespace

Debug tools.

Debugging helpers, renderers and profilers.

This library is built if MAGNUM_WITH_DEBUGTOOLS is enabled when building Magnum. To use this library with CMake, 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 PRIVATE Magnum::DebugTools)

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

Namespaces

namespace ColorMap new in 2020.06
Color maps.

Classes

class CompareFileToImage
File-to-image comparator for Corrade::TestSuite.
class CompareImage
Image comparator for Corrade::TestSuite.
class CompareImageFile
Image file comparator for Corrade::TestSuite.
class CompareImageToFile
Image-to-file comparator for Corrade::TestSuite.
class CompareMaterial new in Git master
Material comparator for Corrade::TestSuite.
template<UnsignedInt dimensions>
class ForceRenderer
Force renderer.
class ForceRendererOptions
Force renderer options.
class FrameProfiler new in 2020.06
Frame profiler.
class FrameProfilerGL new in 2020.06
OpenGL frame profiler.
template<UnsignedInt dimensions>
class ObjectRenderer
Object renderer.
class ObjectRendererOptions
Object renderer options.
class Profiler deprecated in 2020.06
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 GLFrameProfiler = FrameProfilerGL deprecated in Git master
OpenGL frame profiler.
using ObjectRenderer2D = ObjectRenderer<2>
Two-dimensional object renderer.
using ObjectRenderer3D = ObjectRenderer<3>
Three-dimensional object renderer.

Functions

auto bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) -> Containers::Array<char>
Buffer subdata.
template<class T>
auto bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size, void* doxygenIsCrapAtOverloadResolution = nullptr) -> Containers::Array<T> deprecated in Git master
Buffer subdata.
auto bufferData(GL::Buffer& buffer) -> Containers::Array<char>
Buffer data.
template<class T>
auto bufferData(GL::Buffer& buffer, void* doxygenIsCrapAtOverloadResolution = nullptr) -> Containers::Array<T> deprecated in Git master
Buffer data.
auto operator<<(Debug& debug, FrameProfiler::Units value) -> Debug& new in 2020.06
Debug output operator.
auto operator<<(Debug& debug, FrameProfilerGL::Value value) -> Debug& new in 2020.06
Debug output operator.
auto operator<<(Debug& debug, FrameProfilerGL::Values value) -> Debug& new in 2020.06
Debug output operator.
auto screenshot(GL::AbstractFramebuffer& framebuffer, Containers::StringView filename) -> bool new in 2019.10
Save a screenshot to a file.
auto screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, Containers::StringView filename) -> bool new in 2019.10
auto screenshot(GL::AbstractFramebuffer& framebuffer, PixelFormat format, Containers::StringView filename) -> bool new in 2019.10
Save a screenshot in requested pixel format to a file.
auto screenshot(PluginManager::Manager<Trade::AbstractImageConverter>& manager, GL::AbstractFramebuffer& framebuffer, PixelFormat format, Containers::StringView filename) -> bool new in 2019.10
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::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::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, 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
#include <Magnum/DebugTools/ForceRenderer.h>

Two-dimensional force renderer.

typedef ForceRenderer<3> Magnum::DebugTools::ForceRenderer3D
#include <Magnum/DebugTools/ForceRenderer.h>

Three-dimensional force renderer.

typedef FrameProfilerGL Magnum::DebugTools::GLFrameProfiler
#include <Magnum/DebugTools/FrameProfiler.h>

OpenGL frame profiler.

typedef ObjectRenderer<2> Magnum::DebugTools::ObjectRenderer2D
#include <Magnum/DebugTools/ObjectRenderer.h>

Two-dimensional object renderer.

typedef ObjectRenderer<3> Magnum::DebugTools::ObjectRenderer3D
#include <Magnum/DebugTools/ObjectRenderer.h>

Three-dimensional object renderer.

Function documentation

Containers::Array<char> Magnum::DebugTools::bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size)
#include <Magnum/DebugTools/BufferData.h>

Buffer subdata.

Emulates GL::Buffer::subData() call on platforms that don't support it (such as OpenGL ES) by using GL::Buffer::mapRead() and copying the memory to a newly-allocated array. On desktop GL and WebGL 2.0 it's just an alias to GL::Buffer::subData().

#include <Magnum/DebugTools/BufferData.h>
template<class T>
Containers::Array<T> Magnum::DebugTools::bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size, void* doxygenIsCrapAtOverloadResolution = nullptr)

Buffer subdata.

Containers::Array<char> Magnum::DebugTools::bufferData(GL::Buffer& buffer)
#include <Magnum/DebugTools/BufferData.h>

Buffer data.

Emulates GL::Buffer::data() call on platforms that don't support it (such as OpenGL ES) by using GL::Buffer::mapRead() and copying the memory to a newly-allocated array. On desktop GL and WebGL 2.0 it's just an alias to GL::Buffer::data().

#include <Magnum/DebugTools/BufferData.h>
template<class T>
Containers::Array<T> Magnum::DebugTools::bufferData(GL::Buffer& buffer, void* doxygenIsCrapAtOverloadResolution = nullptr)

Buffer data.

Debug& Magnum::DebugTools::operator<<(Debug& debug, FrameProfiler::Units value) new in 2020.06
#include <Magnum/DebugTools/FrameProfiler.h>

Debug output operator.

Debug& Magnum::DebugTools::operator<<(Debug& debug, FrameProfilerGL::Value value) new in 2020.06
#include <Magnum/DebugTools/FrameProfiler.h>

Debug output operator.

Debug& Magnum::DebugTools::operator<<(Debug& debug, FrameProfilerGL::Values value) new in 2020.06
#include <Magnum/DebugTools/FrameProfiler.h>

Debug output operator.

bool Magnum::DebugTools::screenshot(GL::AbstractFramebuffer& framebuffer, Containers::StringView filename) new in 2019.10
#include <Magnum/DebugTools/Screenshot.h>

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, Containers::StringView) 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, Containers::StringView filename) new in 2019.10
#include <Magnum/DebugTools/Screenshot.h>

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, Containers::StringView filename) new in 2019.10
#include <Magnum/DebugTools/Screenshot.h>

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, Containers::StringView) 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, Containers::StringView filename) new in 2019.10
#include <Magnum/DebugTools/Screenshot.h>

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)
#include <Magnum/DebugTools/TextureImage.h>

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().

The function expects that texture has a GL::TextureFormat that's framebuffer-readable and that the GL::PixelFormat and GL::PixelType combination or the generic PixelFormat is compatible with it. 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)
#include <Magnum/DebugTools/TextureImage.h>

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::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D& image)
#include <Magnum/DebugTools/TextureImage.h>

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().

The function expects that texture has a GL::TextureFormat that's framebuffer-readable and that the GL::PixelFormat and GL::PixelType combination or the generic PixelFormat is compatible with it

Image2D Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, Image2D&& image)
#include <Magnum/DebugTools/TextureImage.h>

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::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D& image, GL::BufferUsage usage)
#include <Magnum/DebugTools/TextureImage.h>

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().

The function expects that texture has a GL::TextureFormat that's framebuffer-readable and that the GL::PixelFormat and GL::PixelType combination or the generic PixelFormat is compatible with it

GL::BufferImage2D Magnum::DebugTools::textureSubImage(GL::Texture2D& texture, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage)
#include <Magnum/DebugTools/TextureImage.h>

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, GL::BufferImage2D& image, GL::BufferUsage usage)
#include <Magnum/DebugTools/TextureImage.h>

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().

The function expects that texture has a GL::TextureFormat that's framebuffer-readable and that the GL::PixelFormat and GL::PixelType combination or the generic PixelFormat is compatible with it

GL::BufferImage2D Magnum::DebugTools::textureSubImage(GL::CubeMapTexture& texture, GL::CubeMapCoordinate coordinate, Int level, const Range2Di& range, GL::BufferImage2D&& image, GL::BufferUsage usage)
#include <Magnum/DebugTools/TextureImage.h>

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);