Debugging

Access to OpenGL Debug context facilities. More...

Collaboration diagram for Debugging:

Detailed Description

Access to OpenGL Debug context facilities.

Due to the globally stateful nature of OpenGL and its indirect error reporting it is easy to accidentally misuse its API. Traditionally, you would need to regularly check the error flag of the current OpenGL context.

More recent OpenGL versions have introduced the "Debug Output" feature that enables programmers to get direct feedback on errors in the form of a callback, and additionally insert custom debug messages into the command stream. In order to use these debug facilities you must request a "debug context" by setting the corresponding flag in the GL::Context::CreateInfo struct when creating the OpenGL context (cf. GL::init()). Be advised that some GPU/driver combinations (e.g. MacOS) do not support creating an OpenGL Debug context and all facilities except for Debug::check() and Debug::checkAndThrow() in this namespace will have no effect in this case.

Note

Debug contexts are disabled by default for production + release builds of the ImFusion SDK. In case you don't control OpenGL context creation yourself but rely on the default behavior of our library you can set the IMFUSION_USE_OPENGL_DEBUG_CONTEXT environment variable to request a debug context also in release builds.

See also

https://www.khronos.org/opengl/wiki/Debug_Output

Namespaces
namespace	ImFusion::GL::Debug
	The GL::Debug namespace contains functions and class to help with debugging OpenGL calls.

Classes
class	OpenGlException
	Specialization of std::runtime_error that also stores the original OpenGL error code. More...
class	Group
	The Group class allows to group a set of OpenGL calls together. More...

Typedefs
using	MessageCallback
	Typedef for a debug callback emitted OpenGl.

Enumerations
enum class	MessageSource {   API = 0x8246 , WindowSystem = 0x8247 , ShaderCompiler = 0x8248 , ThirdParty = 0x8249 ,   Application = 0x824A , Other = 0x824B }
	Enumeration to describe the source of an OpenGL debug message callback. More...
enum class	MessageType {   Error = 0x824C , DeprecatedBehavior = 0x824D , UndefinedBehavior = 0x824E , Portability = 0x824F ,   Performance = 0x8250 , Marker = 0x8268 , PushGroup = 0x8269 , PopGroup = 0x826A ,   Other = 0x8250 }
	Enumeration to describe the type of the OpenGL debug message callback. More...
enum class	MessageSeverity { High = 0x9146 , Medium = 0x9147 , Low = 0x9148 , Notification = 0x826B }
	Enumeration to describe the severity of the OpenGL debug message callback. More...
enum class	Error {   None = 0 , InvalidEnum = 0x0500 , InvalidValue = 0x0501 , InvalidOperation = 0x0502 ,   InvalidFramebufferOp = 0x0506 , OutOfMemory = 0x0505 , StackUnderflow = 0x0504 , StackOverflow = 0x0503 }
	Enumeration of all error flag types that OpenGL supports. More...
enum class	FramebufferStatus {   Complete = 0x8CD5 , FramebufferUndefined = 0x8219 , IncompleteAttachment = 0x8CD6 , MissingAttachment = 0x8CD7 ,   IncompleteDrawBuffer = 0x8CDB , IncompleteReadBuffer = 0x8CDC , Unsupported = 0x8CDD , IncompleteMultisample = 0x8D56 ,   IncompleteLayerTargets = 0x8DA8 }
	Enumeration of all OpenGL Framebuffer status/error flag types. More...

Functions
void	defaultMessageCallback (Debug::MessageSource source, Debug::MessageType type, uint32_t id, Debug::MessageSeverity severity, const std::string &message)
	The default OpenGL debug message callback used by ImFusionGL.
void	setMessageCallback (const MessageCallback &mc, bool synchronous)
	Sets the OpenGL debug message callback to use for the current context.
Error	check (bool log=true, const char *file=0, int line=-1)
	Convenience function wrapping glGetError() to check and return the OpenGL context error flag.
void	checkAndThrow (bool log=true, const char *file=0, int line=-1)
	Implements the same functionality as check() but throws an OpenGlException in case of an error.
FramebufferStatus	checkFramebufferStatus (bool log=true)
	Convenience function wrapping glCheckFramebufferStatus() to check the completeness of the currently bound framebuffer.
void	insertMessage (const std::string &message)
	Inserts a message into the OpenGL command stream.

Typedef Documentation

MessageCallback

using MessageCallback

#include <ImFusion/Core/GL/Debug.h>

Initial value:

 std::function<void(MessageSource source,
                                                       MessageType type,
                                                       uint32_t id,
                                                       MessageSeverity severity,
                                                       const std::string& message)>

Typedef for a debug callback emitted OpenGl.

See also

https://www.khronos.org/opengl/wiki/Debug_Output#Getting_messages

Enumeration Type Documentation

MessageSource

enum class MessageSource

strong

#include <ImFusion/Core/GL/Debug.h>

Enumeration to describe the source of an OpenGL debug message callback.

Enumerator
API	Calls to the OpenGL API.
WindowSystem	Calls to a window-system API.
ShaderCompiler	A compiler for a shading language.
ThirdParty	An application associated with OpenGL.
Application	Generated by the user of this application.
Other	Some source that isn't one of the others.

MessageType

enum class MessageType

strong

#include <ImFusion/Core/GL/Debug.h>

Enumeration to describe the type of the OpenGL debug message callback.

Enumerator
Error	An error, typically from the API.
DeprecatedBehavior	Some behavior marked deprecated has been used.
UndefinedBehavior	Something has invoked undefined behavior.
Portability	Some functionality the user relies upon is not portable.
Performance	Code has triggered possible performance issues.
Marker	Command stream annotation.
PushGroup	Begin of a command stream group annotation.
PopGroup	Ende of a command stream group annotation.
Other	Some type that isn't one of the others.

MessageSeverity

enum class MessageSeverity

strong

#include <ImFusion/Core/GL/Debug.h>

Enumeration to describe the severity of the OpenGL debug message callback.

Enumerator
High	All OpenGL Errors, shader compilation/linking errors, or highly-dangerous undefined behavior.
Medium	Major performance warnings, shader compilation/linking warnings, or the use of deprecated functionality.
Low	Redundant state change performance warning, or unimportant undefined behavior.
Notification	Anything that isn't an error or performance issue.

Error

enum class Error

strong

#include <ImFusion/Core/GL/Debug.h>

Enumeration of all error flag types that OpenGL supports.

Enumerator
None	No error has been recorded.
InvalidEnum	An unacceptable value is specified for an enumerated argument. The offending command is ignored and has no other side effect than to set the error flag.
InvalidValue	A numeric argument is out of range. The offending command is ignored and has no other side effect than to set the error flag.
InvalidOperation	The specified operation is not allowed in the current state. The offending command is ignored and has no other side effect than to set the error flag.
InvalidFramebufferOp	The framebuffer object is not complete. The offending command is ignored and has no other side effect than to set the error flag.
OutOfMemory	There is not enough memory left to execute the command. The state of the GL is undefined, except for the state of the error flags, after this error is recorded.
StackUnderflow	An attempt has been made to perform an operation that would cause an internal stack to underflow.
StackOverflow	An attempt has been made to perform an operation that would cause an internal stack to overflow.

FramebufferStatus

enum class FramebufferStatus

strong

#include <ImFusion/Core/GL/Debug.h>

Enumeration of all OpenGL Framebuffer status/error flag types.

Enumerator
Complete	Framebuffer status is good, no errors reported by the device.
FramebufferUndefined	The specified framebuffer is the default read or draw framebuffer, but the default framebuffer does not exist.
IncompleteAttachment	Any of the framebuffer attachment points are framebuffer incomplete.
MissingAttachment	The framebuffer does not have at least one image attached to it.
IncompleteDrawBuffer	The value of GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is GL_NONE for any color attachment point(s) named by GL_DRAW_BUFFERi.
IncompleteReadBuffer	The value of GL_READ_BUFFER is not GL_NONE and the value of GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is GL_NONE for the color attachment point named by GL_READ_BUFFER.
Unsupported	The combination of internal formats of the attached images violates an implementation-dependent set of restrictions.
IncompleteMultisample	The value of GL_RENDERBUFFER_SAMPLES is not the same for all attached renderbuffers, the value of GL_TEXTURE_SAMPLES is the not same for all attached textures, or the attached images are a mix of renderbuffers and textures and the value of GL_RENDERBUFFER_SAMPLES does not match the value of GL_TEXTURE_SAMPLES.
IncompleteLayerTargets	Any framebuffer attachment is layered, and any populated attachment is not layered, or if all populated color attachments are not from textures of the same target.

Function Documentation

defaultMessageCallback()

void defaultMessageCallback	(	Debug::MessageSource	source,
		Debug::MessageType	type,
		uint32_t	id,
		Debug::MessageSeverity	severity,
		const std::string &	message )

#include <ImFusion/Core/GL/Debug.h>

The default OpenGL debug message callback used by ImFusionGL.

This function will drop all messages with MessageSeverity::Low, MessageSeverity::Notification, MessageType::PopGroup, MessageType::PushGroup, or MessageType::Marker. All other messages will be forwarded to ImFusionLog.

setMessageCallback()

void setMessageCallback	(	const MessageCallback &	mc,
		bool	synchronous )

#include <ImFusion/Core/GL/Debug.h>

Sets the OpenGL debug message callback to use for the current context.

Parameters

mc	Callback function to use.
synchronous	If true, OpenGL guarantees that the callback is called from the same thread as the context and in the scope of the causing function, which is usually helpful during debugging.

check()

Error check	(	bool	log = true,
		const char *	file = 0,
		int	line = -1 )

#include <ImFusion/Core/GL/Debug.h>

Convenience function wrapping glGetError() to check and return the OpenGL context error flag.

If log is true, this function will record an error log message with a human readable description, optionally including source location information if file and line are set.

Note

Relying on excessive error checking based on this function is discouraged. We recommend using the debug message callback functionality instead.

checkAndThrow()

void checkAndThrow	(	bool	log = true,
		const char *	file = 0,
		int	line = -1 )

#include <ImFusion/Core/GL/Debug.h>

Implements the same functionality as check() but throws an OpenGlException in case of an error.

Note

Relying on excessive error checking based on this function is discouraged. We recommend using the debug message callback functionality instead.

Exceptions

OpenGlException

if check() returns an error code that is not Error::None.

checkFramebufferStatus()

FramebufferStatus checkFramebufferStatus

(

bool

log = true

)

#include <ImFusion/Core/GL/Debug.h>

Convenience function wrapping glCheckFramebufferStatus() to check the completeness of the currently bound framebuffer.

If log is true, this function will record an error log message with a human readable description.

insertMessage()

void insertMessage

(

const std::string &

message

)

#include <ImFusion/Core/GL/Debug.h>

Inserts a message into the OpenGL command stream.

The message will appear in tracing programs like APITrance or gDebugger but does not affect the command stream otherwise.

See also

GL::Debug::Group