Helper classes and functions for working with OpenGL. More...

Collaboration diagram for Utilities:

Detailed Description

Helper classes and functions for working with OpenGL.

Classes
class	ImFusion::GL::Blending
	Helper class to configure the OpenGL blending stage. More...
class	ImFusion::GL::ObjectPicking
	Helper class to consolidate functionality for implementing object picking of rendered geometry. More...
class	ImFusion::GL::OffscreenRenderHelper
	Helper class to perform deferred off-screen rendering. More...
class	ImFusion::GL::StateGuard
	Guard to easily save and restore critical (modern) OpenGL state. More...
class	ImFusion::GL::SyncObject
	Helper class to synchronize between multiple OpenGL contexts or a context and the application. More...
struct	ImFusion::GL::PlatformInfo
	Structure storing information on the GPU/driver/OpenGL context configuration. More...
struct	ImFusion::GL::MemoryInfo
	Structure storing information about the available video memory as reported by OpenGL. More...
struct	ImFusion::GL::Viewport
	Structure describing an OpenGL viewport. More...
class	ImFusion::GL::ViewState
	Encapsulates the OpenGL view state defined by the viewport, a projection matrix and a model-view matrix. More...
class	ImFusion::GL::OrderIndependentTransparency
	Helper class to consolidate functionality for implementing order-independent transparency of rendered geometry. More...

Enumerations
enum class	ImFusion::GL::PixelFormat : uint32_t { ImFusion::GL::PixelFormat::Red = 0x1903 , ImFusion::GL::PixelFormat::RG = 0x8227 , ImFusion::GL::PixelFormat::RGB = 0x1907 , ImFusion::GL::PixelFormat::RGBA = 0x1908 , ImFusion::GL::PixelFormat::RedInteger = 0x8D94 , ImFusion::GL::PixelFormat::RGInteger = 0x8228 , ImFusion::GL::PixelFormat::RGBInteger = 0x8D98 , ImFusion::GL::PixelFormat::RGBAInteger = 0x8D99 , ImFusion::GL::PixelFormat::DepthComponent = 0x1902 , ImFusion::GL::PixelFormat::DepthStencil = 0x84F9 , ImFusion::GL::PixelFormat::BGRA = 0x80E1 , ImFusion::GL::PixelFormat::BGRAInteger = 0x8D9B , ImFusion::GL::PixelFormat::StencilIndex = 0x1901 }
	Describes the host pixel format during OpenGL texture upload/download. More...
enum class	ImFusion::GL::PixelType : uint32_t { ImFusion::GL::PixelType::Byte = 0x1400 , ImFusion::GL::PixelType::UByte = 0x1401 , ImFusion::GL::PixelType::Short = 0x1402 , ImFusion::GL::PixelType::UShort = 0x1403 , ImFusion::GL::PixelType::Int = 0x1404 , ImFusion::GL::PixelType::UInt = 0x1405 , ImFusion::GL::PixelType::Float = 0x1406 , ImFusion::GL::PixelType::HFloat = 0x140B , ImFusion::GL::PixelType::Double = 0x140A }
	Describes the host pixel type during OpenGL texture upload/download. More...
enum class	ImFusion::GL::Primitive : uint32_t { ImFusion::GL::Primitive::Points = 0x0000 , ImFusion::GL::Primitive::Lines = 0x0001 , ImFusion::GL::Primitive::LineLoop = 0x0002 , ImFusion::GL::Primitive::LineStrip = 0x0003 , ImFusion::GL::Primitive::Triangles = 0x0004 , ImFusion::GL::Primitive::TriangleStrip = 0x0005 , ImFusion::GL::Primitive::TriangleFan = 0x0006 , ImFusion::GL::Primitive::LinesAdjacency = 0x000A , ImFusion::GL::Primitive::LineStripAdjacency = 0x000B , ImFusion::GL::Primitive::TrianglesAdjacency = 0x000C , ImFusion::GL::Primitive::TriangleStripAdjacency = 0x000D }
	Primitive type to render, to be used with GL::VertexBuffer::draw(). More...
enum class	ImFusion::GL::Barrier : uint32_t { ImFusion::GL::Barrier::VertexAttribArray = 0x00000001 , ImFusion::GL::Barrier::ElementArray = 0x00000002 , ImFusion::GL::Barrier::Uniform = 0x00000004 , ImFusion::GL::Barrier::TextureFetch = 0x00000008 , ImFusion::GL::Barrier::ShaderImageAccess = 0x00000020 , ImFusion::GL::Barrier::Command = 0x00000040 , ImFusion::GL::Barrier::PixelBuffer = 0x00000080 , ImFusion::GL::Barrier::TextureUpdate = 0x00000100 , ImFusion::GL::Barrier::BufferUpdate = 0x00000200 , ImFusion::GL::Barrier::Framebuffer = 0x00000400 , ImFusion::GL::Barrier::TransformFeedback = 0x00000800 , ImFusion::GL::Barrier::AtomicCounter = 0x00001000 , ImFusion::GL::Barrier::ShaderStorage = 0x00002000 , ImFusion::GL::Barrier::ClientMappedBuffer = 0x00004000 , ImFusion::GL::Barrier::QueryBuffer = 0x00008000 , ImFusion::GL::Barrier::All = 0xFFFFFFFF }
	Bitflag enum to describe how you intend to use the data after issuing the memoryBarrier() command. More...
enum class	ImFusion::GL::GraphicsResetStatus { ImFusion::GL::GraphicsResetStatus::NoError = 0 , ImFusion::GL::GraphicsResetStatus::GuiltyContextReset = 0x8253 , ImFusion::GL::GraphicsResetStatus::InnocentContextReset = 0x8254 , ImFusion::GL::GraphicsResetStatus::UnknownContextReset = 0x8255 }
	Return value of GL::getGraphicsResetStatus(). More...

Functions
void	ImFusion::GL::init (std::unique_ptr< Context >=nullptr)
	Initializes the OpenGL backend.
void	ImFusion::GL::deinit ()
	Properly deinitializes all OpenGL resources.
bool	ImFusion::GL::getBool (uint32_t param)
	Convenience wrapper for glGetBoolean_v() that directly returns the result.
int32_t	ImFusion::GL::getInt (uint32_t param)
	Convenience wrapper for glGetInteger_v() that directly returns the result.
int32_t	ImFusion::GL::getIntIndexed (uint32_t param, uint32_t index)
	Convenience wrapper for indexed glGetIntegeri_v() that directly returns the result.
float	ImFusion::GL::getFloat (uint32_t param)
	Convenience wrapper for glGetFloat_v() that directly returns the result.
std::string	ImFusion::GL::getString (uint32_t param)
	Convenience wrapper for glGetString() that directly returns the result.
GraphicsResetStatus	ImFusion::GL::getGraphicsResetStatus ()
	Checks if the current context has been lost due to software or hardware issues.
void	ImFusion::GL::clearColorBuffer (const vec4f &color)
	Clears all color buffers attached to the current framebuffer by calling glClearColor(color) and glClear(GL_COLOR_BUFFER_BIT);.
void	ImFusion::GL::clearDepthBuffer (double value)
	Clears the depth buffer attached to the current framebuffer by calling glClearDepth(value) and glClear(GL_DEPTH_BUFFER_BIT);.
void	ImFusion::GL::memoryBarrier (Flags< Barrier > barriers)
	Inserts a barrier into the OpenGL command stream to order memory transactions.
void	ImFusion::GL::flush ()
	Calls glFlush() to block until all OpenGL commands have been transferred to the GPU.
void	ImFusion::GL::finish ()
	Calls glFinish() to block until all OpenGL execution is complete.
mat4	ImFusion::GL::createOrtho (double left, double right, double bottom, double top, double pnear, double pfar)
	Generates an orthographic projection matrix, the same as glOrtho() would do.
mat4	ImFusion::GL::createOrtho2d (int width, int height)
	Generates a pixel-perfect 2D orthographic projection matrix for the given viewport size.
mat4	ImFusion::GL::createPerspective (double fov, double aspect, double pnear, double pfar)
	Generates an perspective projection matrix, the same as glPerspective() would do.
PlatformInfo	ImFusion::GL::platformInfo ()
	Returns information about the currently active OpenGL platform.
MemoryInfo	ImFusion::GL::memoryInfo ()
	Returns information about the currently available and total GPU memory.
Utils::Version	ImFusion::GL::versionInfo ()
	Returns the available OpenGL version of the current context.
void	ImFusion::GL::setDpiScale (double dpiScale)
	Sets the global DPI scaling factor that should be used by DPI-sensitive OpenGL renderings.
double	ImFusion::GL::dpiScale ()
	Queries the global DPI scaling factor that should be used by DPI-sensitive OpenGL renderings.

Enumeration Type Documentation

◆ PixelFormat

enum class ImFusion::GL::PixelFormat : uint32_t

strong

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

Describes the host pixel format during OpenGL texture upload/download.

Note: OpenGL is quite strict wrt. matching pixel format and internal texture format. For instance, when working with an integer texture you must use the corresponding Integer pixel format. Same goes for depth- and stencil textures. You can use InternalFormat::matchingPixelFormat() to get a matching pixel format that OpenGL accepts.

See also: https://www.khronos.org/opengl/wiki/Pixel_Transfer#Pixel_format

Enumerator
Red	Single-channel normalized.
RG	Two-channel normalized.
RGB	Three-channel normalized.
RGBA	Regular four-channel RGBA normalized.
RedInteger	Single-channel integer.
RGInteger	Two-channel integer.
RGBInteger	Three-channel integer.
RGBAInteger	Regular four-channel RGBA integer.
DepthComponent	Depth texture format.
DepthStencil	Combined depth-stencil texture format.
BGRA	Swapped four-channel BGRA normalized.
BGRAInteger	Swapped four-channel BGRA integer.
StencilIndex	Stencil texture format.

◆ PixelType

enum class ImFusion::GL::PixelType : uint32_t

strong

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

Describes the host pixel type during OpenGL texture upload/download.

See also: https://www.khronos.org/opengl/wiki/Pixel_Transfer#Pixel_type

Enumerator
Byte	signed 8 bit integer
UByte	unsigned 8 bit integer
Short	signed 16 bit integer
UShort	unsigned 16 bit integer
Int	signed 32 bit integer
UInt	unsigned 32 bit integer
Float	single-precision (32 bit) floating point
HFloat	half-precision (16 bit) floating point, Attention: Not supported on CPU side!
Double	double-precision (64 bit) floating point

◆ Primitive

enum class ImFusion::GL::Primitive : uint32_t

strong

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

Primitive type to render, to be used with GL::VertexBuffer::draw().

See also: https://www.khronos.org/opengl/wiki/Primitive

Enumerator
Points	Rasterize each vertex as a single point.
Lines	Vertices 0 and 1 are considered a line. Vertices 2 and 3 are considered a line. And so on.
LineLoop	Same as line strips, except that the first and last vertices are also used as a line. Thus, you get n lines for n input vertices.
LineStrip	The adjacent vertices are considered lines. Thus, if you pass n vertices, you will get n-1 lines.
Triangles	Vertices 0, 1, and 2 form a triangle. Vertices 3, 4, and 5 form a triangle. And so on.
TriangleStrip	Every group of 3 adjacent vertices forms a triangle. A vertex stream of n length will generate n-2 triangles.
TriangleFan	The first vertex is always held fixed. From there on, every group of 2 adjacent vertices form a triangle with the first. A vertex stream of n length will generate n-2 triangles.
LinesAdjacency	Independent line segments described by 4 vertices per line; vertices 4i+1 and 4i+2 describe the line segments, 4i and 4i+3 the adjacency information.
LineStripAdjacency	A regular line strip but with additional adjacency information at the beginning and the end. Thus, if you pass n vertices, you will get n-3 lines.
TrianglesAdjacency	Independent triangles with adjacency information described by 6 vertices; vertices 6i through 6i+2 describe the triangle, vertices 6i+3 through 6i+5 the adjacency information.
TriangleStripAdjacency	A regular triangle strip but with additional adjacency information interleaved in the vertex stream; even indices describe the triangle vertices, odd indices the adjacency information.

◆ Barrier

enum class ImFusion::GL::Barrier : uint32_t

strong

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

Bitflag enum to describe how you intend to use the data after issuing the memoryBarrier() command.

See also: https://www.khronos.org/opengl/wiki/GLAPI/glMemoryBarrier

Enumerator
VertexAttribArray	Vertex data sourced from buffer objects after the barrier will reflect data written by shaders prior to the barrier.
ElementArray	Vertex array indices sourced from buffer objects after the barrier will reflect data written by shaders prior to the barrier.
Uniform	Shader uniforms sourced from buffer objects after the barrier will reflect data written by shaders prior to the barrier.
TextureFetch	Texture fetches from shaders, including fetches from buffer object memory via buffer textures, after the barrier will reflect data written by shaders prior to the barrier.
ShaderImageAccess	Memory accesses using shader image load, store, and atomic built-in functions issued after the barrier will reflect data written by shaders prior to the barrier. Additionally, image stores and atomics issued after the barrier will not execute until all memory accesses (e.g., loads, stores, texture fetches, vertex fetches) initiated prior to the barrier complete.
Command	Command data sourced from buffer objects by Draw*Indirect commands after the barrier will reflect data written by shaders prior to the barrier.
PixelBuffer	Reads and writes of buffer objects via the GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER bindings (via glReadPixels, glTexSubImage2D, etc.) after the barrier will reflect data written by shaders prior to the barrier. Additionally, buffer object writes issued after the barrier will wait on the completion of all shader writes initiated prior to the barrier.
TextureUpdate	Writes to a texture via glTex(Sub)Image, glCopyTex(Sub)Image, glClearTexImage, glCompressedTex(Sub)Image, and reads via glGetTexImage after the barrier will reflect data written by shaders prior to the barrier. Additionally, texture writes from these commands issued after the barrier will not execute until all shader writes initiated prior to the barrier complete.
BufferUpdate	Reads or writes to buffer objects via any OpenGL API functions that allow modifying their contents reflect data written by shaders prior to the barrier. Additionally, writes via these commands issued after the barrier will wait on the completion of any shader writes to the same memory initiated prior to the barrier.
Framebuffer	Reads and writes via framebuffer object attachments after the barrier will reflect data written by shaders prior to the barrier. Additionally, framebuffer writes issued after the barrier will wait on the completion of all shader writes issued prior to the barrier.
TransformFeedback	Writes via transform feedback bindings after the barrier will reflect data written by shaders prior to the barrier. Additionally, transform feedback writes issued after the barrier will wait on the completion of all shader writes issued prior to the barrier.
AtomicCounter	Accesses to atomic counters after the barrier will reflect writes prior to the barrier.
ShaderStorage	Accesses to shader storage blocks after the barrier will reflect writes prior to the barrier.
ClientMappedBuffer	Access by the client to persistent mapped regions of buffer objects will reflect data written by shaders prior to the barrier. Note that this may cause additional synchronization operations.
QueryBuffer	Writes of buffer objects via the GL_QUERY_BUFFER binding after the barrier will reflect data written by shaders prior to the barrier. Additionally, buffer object writes issued after the barrier will wait on the completion of all shader writes initiated prior to the barrier.
All	Combines all flags above.

◆ GraphicsResetStatus

enum class ImFusion::GL::GraphicsResetStatus

strong

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

Return value of GL::getGraphicsResetStatus().

Enumerator
NoError	Context has not been reset since last call.
GuiltyContextReset	A reset has been detected that is attributable to the current GL context.
InnocentContextReset	A reset has been detected that is not attributable to the current GL context.
UnknownContextReset	Indicates a detected graphics reset whose cause is unknown.

Function Documentation

◆ init()

void ImFusion::GL::init ( std::unique_ptr< Context > = nullptr )

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

Initializes the OpenGL backend.

You can provide an optional OpenGL context to use as main context. Otherwise, it will create a new default context with the following settings:

highest available OpenGL version
core context unless the IMFUSION_USE_OPENGL_COMPATIBILITY environment variable is defined
debug context only if the IMFUSION_USE_OPENGL_DEBUG_CONTEXT environment variable is defined

Exceptions

OpenGLNotFoundException if the OpenGL could not be initialized.

Examples: ExamplePlugin.cpp.

◆ deinit()

void ImFusion::GL::deinit ( )

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

Properly deinitializes all OpenGL resources.

Deinitialize the logging framework.

◆ getGraphicsResetStatus()

GraphicsResetStatus ImFusion::GL::getGraphicsResetStatus ( )

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

Checks if the current context has been lost due to software or hardware issues.

Note: This functionality requires the current context to be created with the Context::CreateInfo::enableResetNotification flag enabled. Otherwise, it will always return NoError. You can query support using getInt(GL_RESET_NOTIFICATION_STRATEGY).

See also: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glGetGraphicsResetStatus.xhtml

◆ memoryBarrier()

void ImFusion::GL::memoryBarrier ( Flags< Barrier > barriers )

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

Inserts a barrier into the OpenGL command stream to order memory transactions.

Parameters

barriers Bitflag describing how you intend to use the data after issueing this command.

See also: https://www.khronos.org/opengl/wiki/GLAPI/glMemoryBarrier

◆ createOrtho2d()

mat4 ImFusion::GL::createOrtho2d	(	int	width,
		int	height )

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

Generates a pixel-perfect 2D orthographic projection matrix for the given viewport size.

Same as calling createOrtho(0, width, 0, height, -1, 1).

◆ memoryInfo()

MemoryInfo ImFusion::GL::memoryInfo ( )

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

Returns information about the currently available and total GPU memory.

This function requires the GL_NVX_gpu_memory_info extension. If it is not supported by the current platform it may return a ByteSize of 0 to indicate failure.

◆ versionInfo()

Utils::Version ImFusion::GL::versionInfo ( )

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

Returns the available OpenGL version of the current context.

Will return {-1, -1} in case of any error.

◆ setDpiScale()

void ImFusion::GL::setDpiScale ( double dpiScale )

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

Sets the global DPI scaling factor that should be used by DPI-sensitive OpenGL renderings.

This scaling factor is usually the product of a user defined scaling and the pixel ratio of the underlying device (e.g. retina displays). Since ImFusionGL has no access abstraction to the windowing system, this value must be set from the outside.

◆ dpiScale()

double ImFusion::GL::dpiScale ( )

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

Queries the global DPI scaling factor that should be used by DPI-sensitive OpenGL renderings.

Entities of the ImFusion SDK (such as FixedFunctionPipeline, TextRenderer, ...) already consider this setting internally, so that users do not need to worry about it. However, if you need to perform custom DPI-sensitive rendering, use this function.

Detailed Description

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ PixelFormat

◆ PixelType

◆ Primitive

◆ Barrier

◆ GraphicsResetStatus

Function Documentation

◆ init()

◆ deinit()

◆ getGraphicsResetStatus()

◆ memoryBarrier()

◆ createOrtho2d()

◆ memoryInfo()

◆ versionInfo()

◆ setDpiScale()

◆ dpiScale()