Getting Started

To install Fwog, run the following commands in your friendly neighborhood terminal:

git clone https://github.com/JuanDiegoMontoya/Fwog.git
cd Fwog
mkdir build
cd build
cmake ..

Creating a Fwog

To create a Fwog (context), you will first need an OpenGL 4.6 context (e.g., one created with GLFW) and have loaded OpenGL function pointers in the appropriate location. Then, you can call Fwog::Initialize().

#include “Fwog/Context.h”

namespace Fwog

Functions

void Initialize(const ContextInitializeInfo &contextInfo = {})

Initializes Fwog’s internal structures.

Call at program start to initialize Fwog’s internal state. Must be called after an OpenGL context has been acquired.

Note

Making any calls to Fwog before this function has been called will result in undefined behavior.

void Terminate()

Destroys Fwog’s internal structures.

Call at program exit or before Initialize is called again.

void InvalidatePipelineState()

Invalidates assumptions Fwog has made about the OpenGL context state.

Call when OpenGL context state has been changed outside of Fwog (e.g., when using raw OpenGL or using an external library that calls OpenGL). This invalidates assumptions Fwog has made about the pipeline state for the purpose of state deduplication.

const DeviceProperties &GetDeviceProperties()

Query device properties.

Note

This call can replace most calls to glGet.

Returns:: A DeviceProperties struct containing information about the OpenGL context and device limits

Debugging

Fwog helps you debug by enabling certain features in debug builds (unless overridden).

First, assert macros are generously sprinkled throughout the source to catch programming bugs. These will catch things like trying to clear a render target with an incompatible clear color or trying to call rendering commands outside of a rendering scope.

Fwog also clears all resource bindings at the end of each pass to ensure there is no reliance on leaked state.

These debugging features are disabled in release builds to ensure maximum performance, but it also means the programming bugs they catch will result in undefined behavior rather than an instant crash.

Configuring

Fwog can be configured by adding certain defines to your compile command:

FWOG_FORCE_DEBUG: If defined, debug functionality will be enabled in all builds.
FWOG_ASSERT <assert-like-construct>: Defines a custom assert function/macro for Fwog to use internally. By default, Fwog will use assert.
FWOG_UNREACHABLE <unreachable-like-construct>: Defines a custom unreachable function/macro for Fwog to use internally. By default, Fwog will simply use FWOG_ASSERT(0) for unreachable paths.
FWOG_OPENGL_HEADER <header-string>: Allows the user to define where OpenGL function declarations can be found. By default, Fwog will search for <glad/gl.h>.
FWOG_DEFAULT_CLIP_DEPTH_RANGE_ZERO_TO_ONE: If defined, the default value for Viewport::depthRange will be Fwog::ClipDepthRange::ZeroToOne. Otherwise, its default value will be Fwog::ClipDepthRange::NegativeOneToOne.

Errors

Fwog uses exceptions to propagate errors. Currently, exceptions are only used in a few places.

namespace Fwog

class Exception : public exception

#include <Exception.h>

Base type for all exceptions.

Subclassed by Fwog::PipelineCompilationException, Fwog::ShaderCompilationException

Public Functions

Exception() = default

inline explicit Exception(std::string message)

inline const char *what() const noexcept override

Protected Attributes

std::string message_

class PipelineCompilationException : public Fwog::Exception 

#include <Exception.h>

Exception type thrown when a pipeline encounters a compilation error.

These can be thrown if OpenGL encounters a linker error when linking two or more shaders into a program.

class ShaderCompilationException : public Fwog::Exception 

#include <Exception.h>

Exception type thrown when a shader encounters a compilation error.

The exception string will contain the error message

Device Properties

Sometimes, it can be useful to query some information about the device. Fwog provides Fwog::GetDeviceProperties() to query the following information:

struct DeviceLimits

Public Members

int32_t maxTextureSize

int32_t maxTextureSize3D

int32_t maxTextureSizeCube

float maxSamplerLodBias

float maxSamplerAnisotropy

int32_t maxArrayTextureLayers

int32_t maxViewportDims[2]

int32_t subpixelBits

int32_t maxFramebufferWidth

int32_t maxFramebufferHeight

int32_t maxFramebufferLayers

int32_t maxColorAttachments

int32_t maxSamples

int32_t maxSamplesNoAttachments

float interpolationOffsetRange[2]

float pointSizeGranularity

float pointSizeRange[2]

float lineWidthRange[2]

int32_t maxElementIndex

int32_t maxVertexAttribs

int32_t maxVertexAttribBindings

int32_t maxVertexAttribStride

int32_t maxVertexAttribRelativeOffset

int32_t maxVertexOutputComponents

int32_t maxTessellationControlPerVertexInputComponents

int32_t maxTessellationControlPerVertexOutputComponents

int32_t maxTessellationControlPerPatchOutputComponents

int32_t maxTessellationControlTotalOutputComponents

int32_t maxTessellationEvaluationInputComponents

int32_t maxTessellationEvaluationOutputComponents

int32_t maxFragmentInputComponents

int32_t texelOffsetRange[2]

int32_t textureGatherOffsetRange[2]

int32_t maxTessellationGenerationLevel

int32_t maxPatchSize

int32_t maxUniformBufferBindings

int32_t maxUniformBlockSize

int32_t uniformBufferOffsetAlignment

int32_t maxCombinedUniformBlocks

int32_t maxShaderStorageBufferBindings

int32_t maxShaderStorageBlockSize

int32_t shaderStorageBufferOffsetAlignment

int32_t maxCombinedShaderStorageBlocks

int32_t maxCombinedShaderOutputResources

int32_t maxCombinedTextureImageUnits

int32_t maxComputeSharedMemorySize

int32_t maxComputeWorkGroupInvocations

int32_t maxComputeWorkGroupCount[3]

int32_t maxComputeWorkGroupSize[3]

int32_t maxImageUnits

int32_t maxFragmentCombinedOutputResources

int32_t maxCombinedImageUniforms

int32_t maxServerWaitTimeout

SubgroupLimits subgroupLimits = {}

struct DeviceFeatures

Public Members

bool bindlessTextures = {}

bool shaderSubgroup = {}

struct DeviceProperties

Public Members

std::string_view vendor

std::string_view renderer

std::string_view version

std::string_view shadingLanguageVersion

int32_t glVersionMajor

int32_t glVersionMinor

DeviceLimits limits

DeviceFeatures features