Utilities

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

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

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

Enumeration Type Documentation

PixelFormat

enum class 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 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 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 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*, glClearTex*Image, 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 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 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.

deinit()

void deinit

(

)

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

Properly deinitializes all OpenGL resources.

Deinitialize the logging framework.

getGraphicsResetStatus()

IMFUSION_GL_API GraphicsResetStatus 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()

IMFUSION_GL_API void 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()

IMFUSION_GL_API mat4 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()

IMFUSION_GL_API MemoryInfo 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()

IMFUSION_GL_API Utils::Version 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()

IMFUSION_GL_API void 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()

IMFUSION_GL_API double 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.