Welcome to Fwog’s documentation!

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 maxFramebufferSamples

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

Pipelines

Pipeline objects are a concept that are familiar to Vulkan or D3D12 users, but new to OpenGL users. Essentially, they allow us to specify the entire state of the graphics pipeline (shaders, vertex input, blending, depth stencil, etc.) up-front.

To use a pipeline, we first bind it in a rendering scope. All draw calls issued thereafter will use the state encapsulated in the pipeline.

Fwog::BeginRendering(...);
Fwog::Cmd::BindGraphicsPipeline(fooPipeline);
Fwog::Cmd::Draw(...); // Will use the state from fooPipeline
Fwog::Cmd::BindGraphicsPipeline(barPipeline);
Fwog::Cmd::Draw(...); // Will use the state from barPipeline
Fwog::EndRendering();

Note that it’s illegal to issue a draw in a rendering scope without first binding a pipeline. This means you cannot rely on stale bindings from other scopes.

Under the Hood

Internally, Fwog tracks relevant OpenGL state to ensure that binding pipelines won’t set redundant state. Pipeline binding will only incur the cost of setting the difference between that pipeline and the previous (and the cost to find the difference).

#include “Fwog/Pipeline.h”

namespace Fwog

struct ColorBlendAttachmentState

Public Functions

bool operator==(const ColorBlendAttachmentState&) const noexcept = default

Public Members

bool blendEnable = false

BlendFactor srcColorBlendFactor = BlendFactor::ONE 

BlendFactor dstColorBlendFactor = BlendFactor::ZERO 

BlendOp colorBlendOp = BlendOp::ADD 

BlendFactor srcAlphaBlendFactor = BlendFactor::ONE 

BlendFactor dstAlphaBlendFactor = BlendFactor::ZERO 

BlendOp alphaBlendOp = BlendOp::ADD 

ColorComponentFlags colorWriteMask = ColorComponentFlag::RGBA_BITS 

struct ColorBlendState

Public Members

bool logicOpEnable = false

LogicOp logicOp = LogicOp::COPY 

std::span<const ColorBlendAttachmentState> attachments = {}

float blendConstants[4] = {0, 0, 0, 0}

struct ComputePipeline

#include <Pipeline.h>

An object that encapsulates the state needed to issue dispatches.

Public Functions

explicit ComputePipeline(const ComputePipelineInfo &info)

Throws:: PipelineCompilationException –

~ComputePipeline()

ComputePipeline(ComputePipeline &&old) noexcept

ComputePipeline &operator=(ComputePipeline &&old) noexcept

ComputePipeline(const ComputePipeline&) = delete

ComputePipeline &operator=(const ComputePipeline&) = delete

bool operator==(const ComputePipeline&) const = default

Extent3D WorkgroupSize() const

inline uint64_t Handle() const

Gets the handle of the underlying OpenGL program object.

Returns:: The program

Private Members

uint64_t id_

struct ComputePipelineInfo

#include <Pipeline.h>

Parameters for the constructor of ComputePipeline.

Public Members

std::string_view name: An optional name for viewing in a graphics debugger.

const Shader *shader: Non-null pointer to a compute shader.

struct DepthState

Public Members

bool depthTestEnable = false

bool depthWriteEnable = false

CompareOp depthCompareOp = CompareOp::LESS 

struct GraphicsPipeline

#include <Pipeline.h>

An object that encapsulates the state needed to issue draws.

Public Functions

explicit GraphicsPipeline(const GraphicsPipelineInfo &info)

Throws:: PipelineCompilationException –

~GraphicsPipeline()

GraphicsPipeline(GraphicsPipeline &&old) noexcept

GraphicsPipeline &operator=(GraphicsPipeline &&old) noexcept

GraphicsPipeline(const GraphicsPipeline&) = delete

GraphicsPipeline &operator=(const GraphicsPipeline&) = delete

bool operator==(const GraphicsPipeline&) const = default

inline uint64_t Handle() const

Gets the handle of the underlying OpenGL program object.

Returns:: The program

Private Members

uint64_t id_

struct GraphicsPipelineInfo

#include <Pipeline.h>

Parameters for the constructor of GraphicsPipeline.

Public Members

std::string_view name: An optional name for viewing in a graphics debugger.

const Shader *vertexShader = nullptr: Non-null pointer to a vertex shader.

const Shader *fragmentShader = nullptr: Optional pointer to a fragment shader.

const Shader *tessellationControlShader = nullptr: Optional pointer to a tessellation control shader.

const Shader *tessellationEvaluationShader = nullptr: Optional pointer to a tessellation evaluation shader.

InputAssemblyState inputAssemblyState = {}

VertexInputState vertexInputState = {}

TessellationState tessellationState = {}

RasterizationState rasterizationState = {}

MultisampleState multisampleState = {}

DepthState depthState = {}

StencilState stencilState = {}

ColorBlendState colorBlendState = {}

struct InputAssemblyState

Public Members

PrimitiveTopology topology = PrimitiveTopology::TRIANGLE_LIST 

bool primitiveRestartEnable = false

struct MultisampleState

Public Members

bool sampleShadingEnable = false

float minSampleShading = 1

uint32_t sampleMask = 0xFFFFFFFF

bool alphaToCoverageEnable = false

bool alphaToOneEnable = false

struct RasterizationState

Public Members

bool depthClampEnable = false

PolygonMode polygonMode = PolygonMode::FILL 

CullMode cullMode = CullMode::BACK 

FrontFace frontFace = FrontFace::COUNTERCLOCKWISE 

bool depthBiasEnable = false

float depthBiasConstantFactor = 0

float depthBiasSlopeFactor = 0

float lineWidth = 1

float pointSize = 1

struct StencilOpState

Public Functions

bool operator==(const StencilOpState&) const noexcept = default

Public Members

StencilOp passOp = StencilOp::KEEP 

StencilOp failOp = StencilOp::KEEP 

StencilOp depthFailOp = StencilOp::KEEP 

CompareOp compareOp = CompareOp::ALWAYS 

uint32_t compareMask = 0

uint32_t writeMask = 0

uint32_t reference = 0

struct StencilState

Public Members

bool stencilTestEnable = false

StencilOpState front = {}

StencilOpState back = {}

struct TessellationState

Public Members

uint32_t patchControlPoints

struct VertexInputBindingDescription

Public Members

uint32_t location

uint32_t binding

Format format

uint32_t offset

struct VertexInputState

Public Members

std::span<const VertexInputBindingDescription> vertexBindingDescriptions = {}

Rendering

Fwog forgoes framebuffers in favor of specifying a list of render targets at draw time, taking inspiration from VK_KHR_dynamic_rendering.

Color attachments are bound in the order in which they’re provided, which means your fragment shader outputs should use sequential explicit locations starting at zero.

Fwog::RenderColorAttachments colorAttachments[] = {aAlbedo, aNormal, aMaterial};

and the corresponding fragment shader outputs:

layout(location = 0) out vec3 o_albedo;
layout(location = 1) out vec3 o_normal;
layout(location = 2) out vec3 o_material;

To bind the render targets and begin a rendering pass, call Fwog::Render().

Fwog::Render({
    .colorAttachments = colorAttachments,
    .depthAttachment = &depthAttachment,
}
[&] {
    // Bind pipelines, resources, and make draw calls here
});

Then, you can bind pipelines and resources and issue draw calls inside of the callable that is passed.

If you wish to render to the screen, call Fwog::RenderToSwapchain().

Compute

Compute piplines are similar to graphics pipelines, except they only encapsulate a compute shader. To issue dispatches, call Fwog::BeginCompute() to begin a compute scope.

Color Spaces

Fwog enables GL_FRAMEBUFFER_SRGB by default. Fwog::TextureView can be used to view an image in a different color space if desired. This follows the same rules as glTextureView.

Synchronization

Like in plain OpenGL, most operations are automatically synchronized with respect to each other. However, there are certain instances where the driver may not automatically resolve a hazard. These can be dealt with by calling Fwog::MemoryBarrier() and Fwog::TextureBarrier(). Consult the OpenGL specification for more information.

#include “Fwog/Rendering.h”

namespace Fwog

Enums

enum AttachmentLoadOp

Tells Fwog what to do with a render target at the beginning of a pass.

Values:

enumerator LOAD: The previous contents of the image will be preserved.

enumerator CLEAR: The contents of the image will be cleared to a uniform value.

enumerator DONT_CARE: The previous contents of the image need not be preserved (they may be discarded)

Functions

void RenderToSwapchain(const SwapchainRenderInfo &renderInfo, const std::function<void()> &func)

Renders to the swapchain.

The swapchain can be thought of as “the window”. This function is provided because OpenGL nor windowing libraries provide a simple mechanism to access the swapchain as a set of images without interop with an explicit API like Vulkan or D3D12.

Parameters:

renderInfo – Rendering parameters
func – A callback that invokes rendering commands

void Render(const RenderInfo &renderInfo, const std::function<void()> &func)

Renders to a set of textures.

Parameters:

renderInfo – Rendering parameters
func – A callback that invokes rendering commands

void RenderNoAttachments(const RenderNoAttachmentsInfo &renderInfo, const std::function<void()> &func)

Renders to a virtual texture.

Parameters:

renderInfo – Rendering parameters
func – A callback that invokes rendering commands

void Compute(std::string_view name, const std::function<void()> &func)

Begins a compute scope.

Parameters:: func – A callback that invokes dispatch commands

void BlitTexture(const Texture &source, const Texture &target, Offset3D sourceOffset, Offset3D targetOffset, Extent3D sourceExtent, Extent3D targetExtent, Filter filter, AspectMask aspect = AspectMaskBit::COLOR_BUFFER_BIT): Blits a texture to another texture. Supports minification and magnification.

void BlitTextureToSwapchain(const Texture &source, Offset3D sourceOffset, Offset3D targetOffset, Extent3D sourceExtent, Extent3D targetExtent, Filter filter, AspectMask aspect = AspectMaskBit::COLOR_BUFFER_BIT): Blits a texture to the swapchain. Supports minification and magnification.

void CopyTexture(const CopyTextureInfo &copy)

Copies data between textures.

No format conversion is applied, as in memcpy.

void MemoryBarrier(MemoryBarrierBits accessBits)

Defines a barrier ordering memory transactions.

This call is used to ensure that incoherent writes (SSBO writes and image stores) from a shader are reflected in subsequent accesses.

Parameters:: accessBits – The barriers to insert

void TextureBarrier()

Allows subsequent draw commands to read the result of texels written in a previous draw operation.

See the ARB_texture_barrier spec for potential uses.

void CopyBuffer(const CopyBufferInfo &copy): Copies data between buffers.

void CopyTextureToBuffer(const CopyTextureToBufferInfo &copy): Copies texture data into a buffer.

void CopyBufferToTexture(const CopyBufferToTextureInfo &copy): Copies buffer data into a texture.

struct ClearColorValue

#include <Rendering.h>

Describes a clear color value.

The clear color value can be up to four of float, uint32_t, or int32_t. Use of a type that does not match the render target format may result in undefined behavior.

Public Functions

ClearColorValue() = default

template<typename... Args> inline requires (sizeof...(Args)<=4) ClearColorValue(const Args &... args)

Public Members

std::variant<std::array<float, 4>, std::array<uint32_t, 4>, std::array<int32_t, 4>> data

struct ClearDepthStencilValue

Public Members

float depth = {}

int32_t stencil = {}

struct CopyBufferInfo

#include <Rendering.h>

Parameters for CopyBuffer()

Public Members

const Buffer &source

Buffer &target

uint64_t sourceOffset = 0

uint64_t targetOffset = 0

uint64_t size = WHOLE_BUFFER : The amount of data to copy, in bytes. If size is WHOLE_BUFFER, the size of the source buffer is used.

struct CopyBufferToTextureInfo

Public Members

const Buffer &sourceBuffer

Texture &targetTexture

uint32_t level = 0

uint64_t sourceOffset = {}

Offset3D targetOffset = {}

Extent3D extent = {}

UploadFormat format = UploadFormat::INFER_FORMAT : The arrangement of components of texels in the source buffer. DEPTH_STENCIL is not allowed here.

UploadType type = UploadType::INFER_TYPE : The data type of the texel data.

uint32_t bufferRowLength = 0: Specifies, in texels, the size of rows in the buffer (for 2D and 3D images). If zero, it is assumed to be tightly packed according to extent.

uint32_t bufferImageHeight = 0: Specifies, in texels, the number of rows in the buffer (for 3D images. If zero, it is assumed to be tightly packed according to extent.

struct CopyTextureInfo

Public Members

const Texture &source

Texture &target

uint32_t sourceLevel = 0

uint32_t targetLevel = 0

Offset3D sourceOffset = {}

Offset3D targetOffset = {}

Extent3D extent = {}

struct CopyTextureToBufferInfo

#include <Rendering.h>

Parameters for CopyTextureToBuffer.

Public Members

const Texture &sourceTexture

Buffer &targetBuffer

uint32_t level = 0

Offset3D sourceOffset = {}

uint64_t targetOffset = {}

Extent3D extent = {}

UploadFormat format = UploadFormat::INFER_FORMAT 

UploadType type = UploadType::INFER_TYPE 

uint32_t bufferRowLength = 0: Specifies, in texels, the size of rows in the buffer (for 2D and 3D images). If zero, it is assumed to be tightly packed according to extent.

uint32_t bufferImageHeight = 0: Specifies, in texels, the number of rows in the buffer (for 3D images. If zero, it is assumed to be tightly packed according to extent.

template<class T> class ReferenceWrapper

Public Types

using type = T 

Public Functions

template<class U> inline constexpr ReferenceWrapper(U &&val) noexcept

inline constexpr operator T&() const noexcept

inline constexpr T &get() const noexcept

Private Members

T *ptr = {}

struct RenderColorAttachment

Public Members

ReferenceWrapper<const Texture> texture

AttachmentLoadOp loadOp = AttachmentLoadOp::LOAD 

ClearColorValue clearValue

struct RenderDepthStencilAttachment

Public Members

ReferenceWrapper<const Texture> texture

AttachmentLoadOp loadOp = AttachmentLoadOp::LOAD 

ClearDepthStencilValue clearValue

struct RenderInfo

Public Members

std::string_view name: An optional name to demarcate the pass in a graphics debugger.

std::optional<Viewport> viewport = std::nullopt

An optional viewport.

If empty, the viewport size will be the minimum the render targets’ size and the offset will be 0.

std::span<const RenderColorAttachment> colorAttachments

std::optional<RenderDepthStencilAttachment> depthAttachment = std::nullopt

std::optional<RenderDepthStencilAttachment> stencilAttachment = std::nullopt

struct RenderNoAttachmentsInfo

Public Members

std::string_view name: An optional name to demarcate the pass in a graphics debugger.

Viewport viewport = {}

Fwog::Extent3D framebufferSize = {}

Fwog::SampleCount framebufferSamples = {}

struct SwapchainRenderInfo

Public Members

std::string_view name: An optional name to demarcate the pass in a graphics debugger.

Viewport viewport = {}

AttachmentLoadOp colorLoadOp = AttachmentLoadOp::LOAD 

ClearColorValue clearColorValue

AttachmentLoadOp depthLoadOp = AttachmentLoadOp::LOAD 

float clearDepthValue = 0.0f

AttachmentLoadOp stencilLoadOp = AttachmentLoadOp::LOAD 

int32_t clearStencilValue = 0

bool enableSrgb = true

If true, the linear->nonlinear sRGB OETF will be applied to pixels when rendering to the swapchain.

This facility is provided because OpenGL does not expose the swapchain as an image we can interact with in the usual manner.

struct Viewport

Public Functions

bool operator==(const Viewport&) const noexcept = default

Public Members

Rect2D drawRect = {}

float minDepth = 0.0f

float maxDepth = 1.0f

ClipDepthRange depthRange = Fwog::ClipDepthRange::ZERO_TO_ONE 

namespace Cmd

Functions that set pipeline state, binds resources, or issues draws or dispatches.

These functions are analogous to Vulkan vkCmd* calls, which can only be made inside of an active command buffer.

Note

Calling functions in this namespace outside of a rendering or compute scope will result in undefined behavior

Functions

void BindGraphicsPipeline(const GraphicsPipeline &pipeline)

Binds a graphics pipeline to be used for future draw operations.

Valid in rendering scopes.

Parameters:: pipeline – The pipeline to bind

void BindComputePipeline(const ComputePipeline &pipeline)

Binds a compute pipeline to be used for future dispatch operations.

Valid in compute scopes.

Parameters:: pipeline – The pipeline to bind

void SetViewport(const Viewport &viewport)

Dynamically sets the viewport.

Similar to glViewport. Valid in rendering scopes.

Parameters:: viewport – The new viewport

void SetScissor(const Rect2D &scissor)

Dynamically sets the scissor rect.

Similar to glScissor. Valid in rendering scopes.

Parameters:: scissor – The new scissor rect

void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t firstVertex, uint32_t firstInstance)

Equivalent to glDrawArraysInstancedBaseInstance or vkCmdDraw.

Valid in rendering scopes.

Parameters:

vertexCount – The number of vertices to draw
instanceCount – The number of instances to draw
firstVertex – The index of the first vertex to draw
firstInstance – The instance ID of the first instance to draw

void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t firstIndex, int32_t vertexOffset, uint32_t firstInstance)

Equivalent to glDrawElementsInstancedBaseVertexBaseInstance or vkCmdDrawIndexed.

Valid in rendering scopes.

Parameters:

indexCount – The number of vertices to draw
instanceCount – The number of instances to draw
firstIndex – The base index within the index buffer
vertexOffset – The value added to the vertex index before indexing into the vertex buffer
firstInstance – The instance ID of the first instance to draw

void DrawIndirect(const Buffer &commandBuffer, uint64_t commandBufferOffset, uint32_t drawCount, uint32_t stride)

Equivalent to glMultiDrawArraysIndirect or vkCmdDrawDrawIndirect.

Valid in rendering scopes.

Parameters:

commandBuffer – The buffer containing draw parameters
commandBufferOffset – The byte offset into commandBuffer where parameters begin
drawCount – The number of draws to execute
stride – The byte stride between successive sets of draw parameters

void DrawIndirectCount(const Buffer &commandBuffer, uint64_t commandBufferOffset, const Buffer &countBuffer, uint64_t countBufferOffset, uint32_t maxDrawCount, uint32_t stride)

Equivalent to glMultiDrawArraysIndirectCount or vkCmdDrawIndirectCount.

Valid in rendering scopes.

Parameters:

commandBuffer – The buffer containing draw parameters
commandBufferOffset – The byte offset into commandBuffer where parameters begin
countBuffer – The buffer containing the draw count
countBufferOffset – The byte offset into countBuffer where the draw count begins
maxDrawCount – The maximum number of draws that will be executed
stride – The byte stride between successive sets of draw parameters

void DrawIndexedIndirect(const Buffer &commandBuffer, uint64_t commandBufferOffset, uint32_t drawCount, uint32_t stride)

Equivalent to glMultiDrawElementsIndirect or vkCmdDrawIndexedIndirect.

Valid in rendering scopes.

Parameters:

commandBuffer – The buffer containing draw parameters
commandBufferOffset – The byte offset into commandBuffer where parameters begin
drawCount – The number of draws to execute
stride – The byte stride between successive sets of draw parameters

void DrawIndexedIndirectCount(const Buffer &commandBuffer, uint64_t commandBufferOffset, const Buffer &countBuffer, uint64_t countBufferOffset, uint32_t maxDrawCount, uint32_t stride)

Equivalent to glMultiDrawElementsIndirectCount or vkCmdDrawIndexedIndirectCount.

Valid in rendering scopes.

Parameters:

commandBuffer – The buffer containing draw parameters
commandBufferOffset – The byte offset into commandBuffer where parameters begin
countBuffer – The buffer containing the draw count
countBufferOffset – The byte offset into countBuffer where the draw count begins
maxDrawCount – The maximum number of draws that will be executed
stride – The byte stride between successive sets of draw parameters

void BindVertexBuffer(uint32_t bindingIndex, const Buffer &buffer, uint64_t offset, uint64_t stride)

Binds a buffer to a vertex buffer binding point.

Similar to glVertexArrayVertexBuffer. Valid in rendering scopes.

void BindIndexBuffer(const Buffer &buffer, IndexType indexType)

Binds an index buffer.

Similar to glVertexArrayElementBuffer. Valid in rendering scopes.

void BindUniformBuffer(uint32_t index, const Buffer &buffer, uint64_t offset = 0, uint64_t size = WHOLE_BUFFER)

Binds a range within a buffer as a uniform buffer.

Similar to glBindBufferRange(GL_UNIFORM_BUFFER, …)

void BindUniformBuffer(std::string_view block, const Buffer &buffer, uint64_t offset = 0, uint64_t size = WHOLE_BUFFER)

Binds a range within a buffer as a uniform buffer.

Note

Must be called after a pipeline is bound in order to get reflected program info

Parameters:: block – The name of the uniform block whose index to bind to

void BindStorageBuffer(uint32_t index, const Buffer &buffer, uint64_t offset = 0, uint64_t size = WHOLE_BUFFER)

Binds a range within a buffer as a storage buffer.

Similar to glBindBufferRange(GL_SHADER_STORAGE_BUFFER, …)

void BindStorageBuffer(std::string_view block, const Buffer &buffer, uint64_t offset = 0, uint64_t size = WHOLE_BUFFER)

Binds a range within a buffer as a storage buffer.

Note

Must be called after a pipeline is bound in order to get reflected program info

Parameters:: block – The name of the storage block whose index to bind to

void BindSampledImage(uint32_t index, const Texture &texture, const Sampler &sampler)

Binds a texture and a sampler to a texture unit.

Similar to glBindTextureUnit + glBindSampler

void BindSampledImage(std::string_view uniform, const Texture &texture, const Sampler &sampler)

Binds a texture and a sampler to a texture unit.

Note

Must be called after a pipeline is bound in order to get reflected program info

Parameters:: uniform – The name of the uniform whose index to bind to

void BindImage(uint32_t index, const Texture &texture, uint32_t level)

Binds a texture to an image unit.

Similar to glBindImageTexture{s}

void BindImage(std::string_view uniform, const Texture &texture, uint32_t level)

Binds a texture to an image unit.

Note

Must be called after a pipeline is bound in order to get reflected program info

Parameters:: uniform – The name of the uniform whose index to bind to

void Dispatch(uint32_t groupCountX, uint32_t groupCountY, uint32_t groupCountZ)

Invokes a compute shader.

Valid in compute scopes.

Parameters:

groupCountX – The number of local workgroups to dispatch in the X dimension
groupCountY – The number of local workgroups to dispatch in the Y dimension
groupCountZ – The number of local workgroups to dispatch in the Z dimension

void Dispatch(Extent3D groupCount)

Invokes a compute shader.

Valid in compute scopes.

Parameters:: groupCount – The number of local workgroups to dispatch

void DispatchInvocations(uint32_t invocationCountX, uint32_t invocationCountY, uint32_t invocationCountZ)

Invokes a compute shader a specified number of times.

Automatically computes the number of workgroups to invoke based on the formula groupCount = (invocationCount + workgroupSize - 1) / workgroupSize. Valid in compute scopes.

Parameters:

invocationCountX – The minimum number of invocations in the X dimension
invocationCountY – The minimum number of invocations in the Y dimension
invocationCountZ – The minimum number of invocations in the Z dimension

void DispatchInvocations(Extent3D invocationCount)

Invokes a compute shader a specified number of times.

Automatically computes the number of workgroups to invoke based on the formula groupCount = (invocationCount + workgroupSize - 1) / workgroupSize. Valid in compute scopes.

Parameters:: invocationCount – The minimum number of invocations

void DispatchIndirect(const Buffer &commandBuffer, uint64_t commandBufferOffset)

Invokes a compute shader with the group count provided by a buffer.

Valid in compute scopes.

Parameters:

commandBuffer – The buffer containing dispatch parameters
commandBufferOffset – The byte offset into commandBuffer where the parameters begin

namespace detail

Functions

void BeginSwapchainRendering(const SwapchainRenderInfo &renderInfo)

void BeginRendering(const RenderInfo &renderInfo)

void BeginRenderingNoAttachments(const RenderNoAttachmentsInfo &info)

void EndRendering()

void BeginCompute(std::string_view name)

void EndCompute()

API Reference

This file contains a reference for headers that weren’t documented elsewhere.

BasicTypes.h

namespace Fwog

Enums

enum ImageType

Values:

enumerator TEX_1D

enumerator TEX_2D

enumerator TEX_3D

enumerator TEX_1D_ARRAY

enumerator TEX_2D_ARRAY

enumerator TEX_CUBEMAP

enumerator TEX_CUBEMAP_ARRAY

enumerator TEX_2D_MULTISAMPLE

enumerator TEX_2D_MULTISAMPLE_ARRAY

enum ComponentSwizzle

Specifies how a component is swizzled.

Values:

enumerator ZERO

enumerator ONE

enumerator R

enumerator G

enumerator B

enumerator A

enum Format

Values:

enumerator UNDEFINED

enumerator R8_UNORM

enumerator R8_SNORM

enumerator R16_UNORM

enumerator R16_SNORM

enumerator R8G8_UNORM

enumerator R8G8_SNORM

enumerator R16G16_UNORM

enumerator R16G16_SNORM

enumerator R3G3B2_UNORM

enumerator R4G4B4_UNORM

enumerator R5G5B5_UNORM

enumerator R8G8B8_UNORM

enumerator R8G8B8_SNORM

enumerator R10G10B10_UNORM

enumerator R12G12B12_UNORM

enumerator R16G16B16_SNORM

enumerator R2G2B2A2_UNORM

enumerator R4G4B4A4_UNORM

enumerator R5G5B5A1_UNORM

enumerator R8G8B8A8_UNORM

enumerator R8G8B8A8_SNORM

enumerator R10G10B10A2_UNORM

enumerator R10G10B10A2_UINT

enumerator R12G12B12A12_UNORM

enumerator R16G16B16A16_UNORM

enumerator R16G16B16A16_SNORM

enumerator R8G8B8_SRGB

enumerator R8G8B8A8_SRGB

enumerator R16_FLOAT

enumerator R16G16_FLOAT

enumerator R16G16B16_FLOAT

enumerator R16G16B16A16_FLOAT

enumerator R32_FLOAT

enumerator R32G32_FLOAT

enumerator R32G32B32_FLOAT

enumerator R32G32B32A32_FLOAT

enumerator R11G11B10_FLOAT

enumerator R9G9B9_E5

enumerator R8_SINT

enumerator R8_UINT

enumerator R16_SINT

enumerator R16_UINT

enumerator R32_SINT

enumerator R32_UINT

enumerator R8G8_SINT

enumerator R8G8_UINT

enumerator R16G16_SINT

enumerator R16G16_UINT

enumerator R32G32_SINT

enumerator R32G32_UINT

enumerator R8G8B8_SINT

enumerator R8G8B8_UINT

enumerator R16G16B16_SINT

enumerator R16G16B16_UINT

enumerator R32G32B32_SINT

enumerator R32G32B32_UINT

enumerator R8G8B8A8_SINT

enumerator R8G8B8A8_UINT

enumerator R16G16B16A16_SINT

enumerator R16G16B16A16_UINT

enumerator R32G32B32A32_SINT

enumerator R32G32B32A32_UINT

enumerator D32_FLOAT

enumerator D32_UNORM

enumerator D24_UNORM

enumerator D16_UNORM

enumerator D32_FLOAT_S8_UINT

enumerator D24_UNORM_S8_UINT

enumerator BC1_RGB_UNORM

enumerator BC1_RGB_SRGB

enumerator BC1_RGBA_UNORM

enumerator BC1_RGBA_SRGB

enumerator BC2_RGBA_UNORM

enumerator BC2_RGBA_SRGB

enumerator BC3_RGBA_UNORM

enumerator BC3_RGBA_SRGB

enumerator BC4_R_UNORM

enumerator BC4_R_SNORM

enumerator BC5_RG_UNORM

enumerator BC5_RG_SNORM

enumerator BC6H_RGB_UFLOAT

enumerator BC6H_RGB_SFLOAT

enumerator BC7_RGBA_UNORM

enumerator BC7_RGBA_SRGB

enum SampleCount

Values:

enumerator SAMPLES_1

enumerator SAMPLES_2

enumerator SAMPLES_4

enumerator SAMPLES_8

enumerator SAMPLES_16

enumerator SAMPLES_32

enum UploadFormat

Values:

enumerator UNDEFINED

enumerator R

enumerator RG

enumerator RGB

enumerator BGR

enumerator RGBA

enumerator BGRA

enumerator R_INTEGER

enumerator RG_INTEGER

enumerator RGB_INTEGER

enumerator BGR_INTEGER

enumerator RGBA_INTEGER

enumerator BGRA_INTEGER

enumerator DEPTH_COMPONENT

enumerator STENCIL_INDEX

enumerator DEPTH_STENCIL

enumerator INFER_FORMAT: For CopyTextureToBuffer and CopyBufferToTexture.

enum UploadType

Values:

enumerator UNDEFINED

enumerator UBYTE

enumerator SBYTE

enumerator USHORT

enumerator SSHORT

enumerator UINT

enumerator SINT

enumerator FLOAT

enumerator UBYTE_3_3_2

enumerator UBYTE_2_3_3_REV

enumerator USHORT_5_6_5

enumerator USHORT_5_6_5_REV

enumerator USHORT_4_4_4_4

enumerator USHORT_4_4_4_4_REV

enumerator USHORT_5_5_5_1

enumerator USHORT_1_5_5_5_REV

enumerator UINT_8_8_8_8

enumerator UINT_8_8_8_8_REV

enumerator UINT_10_10_10_2

enumerator UINT_2_10_10_10_REV

enumerator INFER_TYPE: For CopyTextureToBuffer and CopyBufferToTexture.

enum Filter

Values:

enumerator NONE

enumerator NEAREST

enumerator LINEAR

enum AddressMode

Values:

enumerator REPEAT

enumerator MIRRORED_REPEAT

enumerator CLAMP_TO_EDGE

enumerator CLAMP_TO_BORDER

enumerator MIRROR_CLAMP_TO_EDGE

enum BorderColor

Values:

enumerator FLOAT_TRANSPARENT_BLACK

enumerator INT_TRANSPARENT_BLACK

enumerator FLOAT_OPAQUE_BLACK

enumerator INT_OPAQUE_BLACK

enumerator FLOAT_OPAQUE_WHITE

enumerator INT_OPAQUE_WHITE

enum AspectMaskBit

Values:

enumerator COLOR_BUFFER_BIT

enumerator DEPTH_BUFFER_BIT

enumerator STENCIL_BUFFER_BIT

enum PrimitiveTopology

Values:

enumerator POINT_LIST

enumerator LINE_LIST

enumerator LINE_STRIP

enumerator TRIANGLE_LIST

enumerator TRIANGLE_STRIP

enumerator TRIANGLE_FAN

enumerator PATCH_LIST: Note

Available only in pipelines with tessellation shaders

enum PolygonMode

Values:

enumerator FILL

enumerator LINE

enumerator POINT

enum CullMode

Values:

enumerator NONE

enumerator FRONT

enumerator BACK

enumerator FRONT_AND_BACK

enum FrontFace

Values:

enumerator CLOCKWISE

enumerator COUNTERCLOCKWISE

enum CompareOp

Values:

enumerator NEVER

enumerator LESS

enumerator EQUAL

enumerator LESS_OR_EQUAL

enumerator GREATER

enumerator NOT_EQUAL

enumerator GREATER_OR_EQUAL

enumerator ALWAYS

enum LogicOp

Values:

enumerator CLEAR

enumerator SET

enumerator COPY

enumerator COPY_INVERTED

enumerator NO_OP

enumerator INVERT

enumerator AND

enumerator NAND

enumerator OR

enumerator NOR

enumerator XOR

enumerator EQUIVALENT

enumerator AND_REVERSE

enumerator OR_REVERSE

enumerator AND_INVERTED

enumerator OR_INVERTED

enum BlendFactor

Values:

enumerator ZERO

enumerator ONE

enumerator SRC_COLOR

enumerator ONE_MINUS_SRC_COLOR

enumerator DST_COLOR

enumerator ONE_MINUS_DST_COLOR

enumerator SRC_ALPHA

enumerator ONE_MINUS_SRC_ALPHA

enumerator DST_ALPHA

enumerator ONE_MINUS_DST_ALPHA

enumerator CONSTANT_COLOR

enumerator ONE_MINUS_CONSTANT_COLOR

enumerator CONSTANT_ALPHA

enumerator ONE_MINUS_CONSTANT_ALPHA

enumerator SRC_ALPHA_SATURATE

enumerator SRC1_COLOR

enumerator ONE_MINUS_SRC1_COLOR

enumerator SRC1_ALPHA

enumerator ONE_MINUS_SRC1_ALPHA

enum BlendOp

Values:

enumerator ADD

enumerator SUBTRACT

enumerator REVERSE_SUBTRACT

enumerator MIN

enumerator MAX

enum ColorComponentFlag

Values:

enumerator NONE

enumerator R_BIT

enumerator G_BIT

enumerator B_BIT

enumerator A_BIT

enumerator RGBA_BITS

enum IndexType

Values:

enumerator UNSIGNED_BYTE

enumerator UNSIGNED_SHORT

enumerator UNSIGNED_INT

enum MemoryBarrierBit

Values:

enumerator NONE

enumerator VERTEX_BUFFER_BIT

enumerator INDEX_BUFFER_BIT

enumerator UNIFORM_BUFFER_BIT

enumerator TEXTURE_FETCH_BIT

enumerator IMAGE_ACCESS_BIT

enumerator COMMAND_BUFFER_BIT

enumerator TEXTURE_UPDATE_BIT

enumerator BUFFER_UPDATE_BIT

enumerator MAPPED_BUFFER_BIT

enumerator FRAMEBUFFER_BIT

enumerator SHADER_STORAGE_BIT

enumerator QUERY_COUNTER_BIT

enumerator ALL_BITS

enum StencilOp

Values:

enumerator KEEP

enumerator ZERO

enumerator REPLACE

enumerator INCREMENT_AND_CLAMP

enumerator DECREMENT_AND_CLAMP

enumerator INVERT

enumerator INCREMENT_AND_WRAP

enumerator DECREMENT_AND_WRAP

enum ClipDepthRange

Values:

enumerator NEGATIVE_ONE_TO_ONE

enumerator ZERO_TO_ONE

Functions

inline Extent2D operator+(uint32_t val, Extent2D ext)

inline Extent2D operator-(uint32_t val, Extent2D ext)

inline Extent2D operator*(uint32_t val, Extent2D ext)

inline Extent2D operator/(uint32_t val, Extent2D ext)

inline Extent2D operator>>(uint32_t val, Extent2D ext)

inline Extent2D operator<<(uint32_t val, Extent2D ext)

inline Extent3D operator+(uint32_t val, Extent3D ext)

inline Extent3D operator-(uint32_t val, Extent3D ext)

inline Extent3D operator*(uint32_t val, Extent3D ext)

inline Extent3D operator/(uint32_t val, Extent3D ext)

inline Extent3D operator>>(uint32_t val, Extent3D ext)

inline Extent3D operator<<(uint32_t val, Extent3D ext)

inline Offset2D operator+(uint32_t val, Offset2D ext)

inline Offset2D operator-(uint32_t val, Offset2D ext)

inline Offset2D operator*(uint32_t val, Offset2D ext)

inline Offset2D operator/(uint32_t val, Offset2D ext)

inline Offset2D operator>>(uint32_t val, Offset2D ext)

inline Offset2D operator<<(uint32_t val, Offset2D ext)

inline Offset3D operator+(uint32_t val, Offset3D ext)

inline Offset3D operator-(uint32_t val, Offset3D ext)

inline Offset3D operator*(uint32_t val, Offset3D ext)

inline Offset3D operator/(uint32_t val, Offset3D ext)

inline Offset3D operator>>(uint32_t val, Offset3D ext)

inline Offset3D operator<<(uint32_t val, Offset3D ext)

Variables

constexpr uint64_t WHOLE_BUFFER = static_cast<uint64_t>(-1)

Convenience constant to allow binding the whole buffer in Cmd::BindUniformBuffer and Cmd::BindStorageBuffer.

If an offset is provided with this constant, then the range [offset, buffer.Size()) will be bound.

struct DispatchIndirectCommand

Public Members

uint32_t groupCountX

uint32_t groupCountY

uint32_t groupCountZ

struct DrawIndexedIndirectCommand

Public Members

uint32_t indexCount

uint32_t instanceCount

uint32_t firstIndex

int32_t vertexOffset

uint32_t firstInstance

struct DrawIndirectCommand

Public Members

uint32_t vertexCount

uint32_t instanceCount

uint32_t firstVertex

uint32_t firstInstance

struct Extent2D

Public Functions

bool operator==(const Extent2D&) const noexcept = default

inline Extent2D operator+(const Extent2D &other) const

inline Extent2D operator-(const Extent2D &other) const

inline Extent2D operator*(const Extent2D &other) const

inline Extent2D operator/(const Extent2D &other) const

inline Extent2D operator>>(const Extent2D &other) const

inline Extent2D operator<<(const Extent2D &other) const

inline Extent2D operator+(uint32_t val) const

inline Extent2D operator-(uint32_t val) const

inline Extent2D operator*(uint32_t val) const

inline Extent2D operator/(uint32_t val) const

inline Extent2D operator>>(uint32_t val) const

inline Extent2D operator<<(uint32_t val) const

Public Members

uint32_t width = {}

uint32_t height = {}

struct Extent3D

Public Functions

inline operator Extent2D() const

bool operator==(const Extent3D&) const noexcept = default

inline Extent3D operator+(const Extent3D &other) const

inline Extent3D operator-(const Extent3D &other) const

inline Extent3D operator*(const Extent3D &other) const

inline Extent3D operator/(const Extent3D &other) const

inline Extent3D operator>>(const Extent3D &other) const

inline Extent3D operator<<(const Extent3D &other) const

inline Extent3D operator+(uint32_t val) const

inline Extent3D operator-(uint32_t val) const

inline Extent3D operator*(uint32_t val) const

inline Extent3D operator/(uint32_t val) const

inline Extent3D operator>>(uint32_t val) const

inline Extent3D operator<<(uint32_t val) const

Public Members

uint32_t width = {}

uint32_t height = {}

uint32_t depth = {}

struct Offset2D

Public Functions

bool operator==(const Offset2D&) const noexcept = default

inline Offset2D operator+(const Offset2D &other) const

inline Offset2D operator-(const Offset2D &other) const

inline Offset2D operator*(const Offset2D &other) const

inline Offset2D operator/(const Offset2D &other) const

inline Offset2D operator>>(const Offset2D &other) const

inline Offset2D operator<<(const Offset2D &other) const

inline Offset2D operator+(uint32_t val) const

inline Offset2D operator-(uint32_t val) const

inline Offset2D operator*(uint32_t val) const

inline Offset2D operator/(uint32_t val) const

inline Offset2D operator>>(uint32_t val) const

inline Offset2D operator<<(uint32_t val) const

Public Members

uint32_t x = {}

uint32_t y = {}

struct Offset3D

Public Functions

inline operator Offset2D() const

bool operator==(const Offset3D&) const noexcept = default

inline Offset3D operator+(const Offset3D &other) const

inline Offset3D operator-(const Offset3D &other) const

inline Offset3D operator*(const Offset3D &other) const

inline Offset3D operator/(const Offset3D &other) const

inline Offset3D operator>>(const Offset3D &other) const

inline Offset3D operator<<(const Offset3D &other) const

inline Offset3D operator+(uint32_t val) const

inline Offset3D operator-(uint32_t val) const

inline Offset3D operator*(uint32_t val) const

inline Offset3D operator/(uint32_t val) const

inline Offset3D operator>>(uint32_t val) const

inline Offset3D operator<<(uint32_t val) const

Public Members

uint32_t x = {}

uint32_t y = {}

uint32_t z = {}

struct Rect2D

Public Functions

bool operator==(const Rect2D&) const noexcept = default

Public Members

Offset2D offset

Extent2D extent

Buffer.h

namespace Fwog

Enums

enum BufferStorageFlag

Values:

enumerator NONE

enumerator DYNAMIC_STORAGE: Allows the user to update the buffer’s contents with Buffer::UpdateData.

enumerator CLIENT_STORAGE: Hints to the implementation to place the buffer storage in host memory.

enumerator MAP_MEMORY: Maps the buffer (persistently and coherently) upon creation.

class Buffer

#include <Buffer.h>

Encapsulates an OpenGL buffer.

Public Functions

explicit Buffer(size_t size, BufferStorageFlags storageFlags = BufferStorageFlag::NONE, std::string_view name = "")

explicit Buffer(TriviallyCopyableByteSpan data, BufferStorageFlags storageFlags = BufferStorageFlag::NONE, std::string_view name = "")

Buffer(Buffer &&old) noexcept

Buffer &operator=(Buffer &&old) noexcept

Buffer(const Buffer&) = delete

Buffer &operator=(const Buffer&) = delete

~Buffer()

void UpdateData(TriviallyCopyableByteSpan data, size_t destOffsetBytes = 0)

void FillData(const BufferFillInfo &clear = {})

inline void *GetMappedPointer() noexcept

Gets a pointer that is mapped to the buffer’s data store.

Returns:: A pointer to mapped memory if the buffer was created with BufferStorageFlag::MAP_MEMORY, otherwise nullptr

inline const void *GetMappedPointer() const noexcept

inline auto Handle() const noexcept

inline auto Size() const noexcept

inline bool IsMapped() const noexcept

void Invalidate()

Invalidates the content of the buffer’s data store.

This call can be used to optimize driver synchronization in certain cases.

Protected Functions

Buffer(const void *data, size_t size, BufferStorageFlags storageFlags, std::string_view name)

void UpdateData(const void *data, size_t size, size_t offset = 0)

Protected Attributes

size_t size_ = {}

BufferStorageFlags storageFlags_ = {}

uint32_t id_ = {}

void *mappedMemory_ = {}

struct BufferFillInfo

#include <Buffer.h>

Parameters for Buffer::FillData.

Public Members

uint64_t offset = 0

uint64_t size = WHOLE_BUFFER 

uint32_t data = 0

class TriviallyCopyableByteSpan : public std::span<const std::byte>

#include <Buffer.h>

Used to constrain the types accpeted by Buffer.

Public Functions

template<typename T> inline requires std::is_trivially_copyable_v< T > TriviallyCopyableByteSpan (const T &t)

template<typename T> inline requires std::is_trivially_copyable_v< T > TriviallyCopyableByteSpan (std::span< const T > t)

template<typename T> inline requires std::is_trivially_copyable_v< T > TriviallyCopyableByteSpan (std::span< T > t)

DebugMarker.h

namespace Fwog

class ScopedDebugMarker

#include <DebugMarker.h>

Use to demarcate a scope for viewing in a graphics debugger.

Public Functions

ScopedDebugMarker(const char *message)

~ScopedDebugMarker()

ScopedDebugMarker(const ScopedDebugMarker&) = delete

Fence.h

namespace Fwog

class Fence

#include <Fence.h>

An object used for CPU-GPU synchronization.

Public Functions

explicit Fence()

Fence(Fence &&old) noexcept

Fence &operator=(Fence &&old) noexcept

Fence(const Fence&) = delete

Fence &operator=(const Fence&) = delete

~Fence()

void Signal(): Inserts a fence into the command stream.

uint64_t Wait()

Waits for the fence to be signaled and returns.

Todo:: Add timeout parameter

Returns:: How long (in nanoseconds) the fence blocked

Private Functions

void DeleteSync()

Private Members

void *sync_ = {}

Shader.h

namespace Fwog

Enums

enum PipelineStage

Values:

enumerator VERTEX_SHADER

enumerator TESSELLATION_CONTROL_SHADER

enumerator TESSELLATION_EVALUATION_SHADER

enumerator FRAGMENT_SHADER

enumerator COMPUTE_SHADER

class Shader

#include <Shader.h>

A shader object to be used in one or more GraphicsPipeline or ComputePipeline objects.

Public Functions

explicit Shader(PipelineStage stage, std::string_view source, std::string_view name = "")

Constructs the shader.

Parameters:

stage – A pipeline stage
source – A GLSL source string

Throws:

ShaderCompilationException – if the shader is malformed

Shader(const Shader&) = delete

Shader(Shader &&old) noexcept

Shader &operator=(const Shader&) = delete

Shader &operator=(Shader &&old) noexcept

~Shader()

inline uint32_t Handle() const

Gets the handle of the underlying OpenGL shader object.

Returns:: The shader

Private Members

uint32_t id_ = {}

Texture.h

namespace Fwog

Functions

Texture CreateTexture2D(Extent2D size, Format format, std::string_view name = "")

Texture CreateTexture2DMip(Extent2D size, Format format, uint32_t mipLevels, std::string_view name = "")

struct ComponentMapping

#include <Texture.h>

Specifies a color component mapping.

Public Members

ComponentSwizzle r = ComponentSwizzle::R 

ComponentSwizzle g = ComponentSwizzle::G 

ComponentSwizzle b = ComponentSwizzle::B 

ComponentSwizzle a = ComponentSwizzle::A 

struct CompressedTextureUpdateInfo

#include <Texture.h>

Parameters for Texture::UpdateCompressedImage.

Public Members

uint32_t level = 0

Offset3D offset = {}

Extent3D extent = {}

const void *data = nullptr

class Sampler

#include <Texture.h>

Encapsulates an OpenGL sampler.

Public Functions

explicit Sampler(const SamplerState &samplerState)

inline uint32_t Handle() const

Gets the handle of the underlying OpenGL sampler object.

Returns:: The sampler

Private Functions

Sampler() = default

inline explicit Sampler(uint32_t id)

Private Members

uint32_t id_ = {}

Friends

friend class detail::SamplerCache

struct SamplerState

#include <Texture.h>

Parameters for the constructor of Sampler.

Public Functions

bool operator==(const SamplerState &rhs) const noexcept = default

Public Members

float lodBias = {0}

float minLod = {-1000}

float maxLod = {1000}

Filter minFilter = Filter::LINEAR 

Filter magFilter = Filter::LINEAR 

Filter mipmapFilter = Filter::NONE 

AddressMode addressModeU = AddressMode::CLAMP_TO_EDGE 

AddressMode addressModeV = AddressMode::CLAMP_TO_EDGE 

AddressMode addressModeW = AddressMode::CLAMP_TO_EDGE 

BorderColor borderColor = BorderColor::FLOAT_OPAQUE_WHITE 

SampleCount anisotropy = SampleCount::SAMPLES_1 

bool compareEnable = false

CompareOp compareOp = CompareOp::NEVER 

class Texture

#include <Texture.h>

Encapsulates an immutable OpenGL texture.

Subclassed by Fwog::TextureView

Public Functions

explicit Texture(const TextureCreateInfo &createInfo, std::string_view name = "")

Constructs the texture.

Parameters:

createInfo – Parameters to construct the texture
name – An optional name for viewing the resource in a graphics debugger

Texture(Texture &&old) noexcept

Texture &operator=(Texture &&old) noexcept

Texture(const Texture&) = delete

Texture &operator=(const Texture&) = delete

virtual ~Texture()

bool operator==(const Texture&) const noexcept = default

Todo:: Remove

void UpdateImage(const TextureUpdateInfo &info)

Updates a subresource of the image.

Note

info.format must not be a compressed image format

Parameters:: info – The subresource and data to upload

void UpdateCompressedImage(const CompressedTextureUpdateInfo &info)

Updates a subresource of the image.

Note

Image must be in a compressed image format

Note

info.data must be in a compatible compressed image format

Parameters:: info – The subresource and data to upload

void ClearImage(const TextureClearInfo &info)

Clears a subresource of the image to a specified value.

Parameters:: info – The subresource and value to clear it with

void GenMipmaps(): Automatically generates LoDs of the image. All mip levels beyond 0 are filled with the generated LoDs.

TextureView CreateSingleMipView(uint32_t level): Creates a view of a single mip level of the image.

TextureView CreateSingleLayerView(uint32_t layer): Creates a view of a single array layer of the image.

TextureView CreateFormatView(Format newFormat)

Reinterpret the data of this texture.

Parameters:: newFormat – The format to reinterpret the data as
Returns:: A new texture view

TextureView CreateSwizzleView(ComponentMapping components)

Creates a view of the texture with a new component mapping.

Parameters:: components – The swizzled components
Returns:: A new texture view

uint64_t GetBindlessHandle(Sampler sampler)

Generates and makes resident a bindless handle from the image and a sampler. Only available if GL_ARB_bindless_texture is supported.

Todo:: Improve this

Parameters:: sampler – The sampler to bind to the texture
Returns:: A bindless texture handle that can be placed in a buffer and used to construct a combined texture sampler in a shader

inline const TextureCreateInfo &GetCreateInfo() const noexcept

inline Extent3D Extent() const noexcept

inline uint32_t Handle() noexcept

Gets the handle of the underlying OpenGL texture object.

Returns:: The texture

Protected Functions

void subImageInternal(const TextureUpdateInfo &info)

void subCompressedImageInternal(const CompressedTextureUpdateInfo &info)

Texture() = default

Protected Attributes

uint32_t id_ = {}

TextureCreateInfo createInfo_ = {}

uint64_t bindlessHandle_ = 0

Friends

friend void CopyBufferToTexture(const CopyBufferToTextureInfo &copy): Copies buffer data into a texture.

struct TextureClearInfo

#include <Texture.h>

Parameters for Texture::ClearImage.

Public Members

uint32_t level = 0

Offset3D offset = {}

Extent3D extent = {}

UploadFormat format = UploadFormat::INFER_FORMAT 

UploadType type = UploadType::INFER_TYPE 

const void *data = nullptr: If null, then the subresource will be cleared with zeroes.

struct TextureCreateInfo

#include <Texture.h>

Parameters for the constructor of Texture.

Public Functions

bool operator==(const TextureCreateInfo&) const noexcept = default

Public Members

ImageType imageType = {}

Format format = {}

Extent3D extent = {}

uint32_t mipLevels = 0

uint32_t arrayLayers = 0

SampleCount sampleCount = {}

struct TextureUpdateInfo

#include <Texture.h>

Parameters for Texture::UpdateImage.

Public Members

uint32_t level = 0

Offset3D offset = {}

Extent3D extent = {}

UploadFormat format = UploadFormat::INFER_FORMAT 

UploadType type = UploadType::INFER_TYPE 

const void *pixels = nullptr

uint32_t rowLength = 0: Specifies, in texels, the size of rows in the array (for 2D and 3D images). If zero, it is assumed to be tightly packed according to size.

uint32_t imageHeight = 0: Specifies, in texels, the number of rows in the array (for 3D images. If zero, it is assumed to be tightly packed according to size.

class TextureView : public Fwog::Texture 

#include <Texture.h>

Encapsulates an OpenGL texture view.

Public Functions

explicit TextureView(const TextureViewCreateInfo &viewInfo, Texture &texture, std::string_view name = "")

Constructs the texture view with explicit parameters.

Parameters:

viewInfo – Parameters to construct the texture
texture – A texture of which to construct a view
name – An optional name for viewing the resource in a graphics debugger

explicit TextureView(const TextureViewCreateInfo &viewInfo, TextureView &textureView, std::string_view name = "")

explicit TextureView(Texture &texture, std::string_view name = "")

TextureView(TextureView &&old) noexcept

TextureView &operator=(TextureView &&old) noexcept

TextureView(const TextureView &other) = delete

TextureView &operator=(const TextureView &other) = delete

~TextureView()

inline TextureViewCreateInfo GetViewInfo() const noexcept

Private Functions

TextureView()

Private Members

TextureViewCreateInfo viewInfo_ = {}

struct TextureViewCreateInfo

#include <Texture.h>

Parameters for the constructor of TextureView.

Public Members

ImageType viewType = {}: Note

Must be an image type compatible with the base texture as defined by table 8.21 in the OpenGL spec

Format format = {}: Note

Must be a format compatible with the base texture as defined by table 8.22 in the OpenGL spec

ComponentMapping components = {}

uint32_t minLevel = 0

uint32_t numLevels = 0

uint32_t minLayer = 0

uint32_t numLayers = 0

namespace detail

Functions

uint32_t GetHandle(const Texture &texture)

Timer.h

namespace Fwog

class TimerQuery

#include <Timer.h>

Synchronous single-buffered GPU-timeline timer. Querying the timer will result in a stall as commands are flushed and waited on to complete.

Use sparingly, and only if detailed perf data is needed for a particular draw.

Todo:: This class is in desparate need of an update

Public Functions

TimerQuery()

~TimerQuery()

TimerQuery(const TimerQuery&) = delete

TimerQuery(TimerQuery&&) = delete

TimerQuery &operator=(const TimerQuery&) = delete

TimerQuery &operator=(TimerQuery&&) = delete

uint64_t GetTimestamp()

Private Members

uint32_t queries[2]

class TimerQueryAsync

#include <Timer.h>

Async N-buffered timer query that does not induce pipeline stalls.

Useful for measuring performance of passes every frame without causing stalls. However, the results returned may be from multiple frames ago, and results are not guaranteed to be available. In practice, setting N to 5 should allow at least one query to be available every frame.

Public Functions

TimerQueryAsync(uint32_t N)

~TimerQueryAsync()

TimerQueryAsync(const TimerQueryAsync&) = delete

TimerQueryAsync(TimerQueryAsync&&) = delete

TimerQueryAsync &operator=(const TimerQueryAsync&) = delete

TimerQueryAsync &operator=(TimerQueryAsync&&) = delete

void BeginZone(): Begins a query zone.

Note

EndZone must be called before another zone can begin

void EndZone(): Ends a query zone.

Note

BeginZone must be called before a zone can end

std::optional<uint64_t> PopTimestamp()

Gets the latest available query.

Returns:: The latest query, if available. Otherwise, std::nullopt is returned

Private Members

uint32_t start_ = {}

uint32_t count_ = {}

const uint32_t capacity_ = {}

uint32_t *queries = {}

template<typename T> class TimerScoped

#include <Timer.h>

RAII wrapper for TimerQueryAsync.

Public Functions

inline TimerScoped(T &zone)

inline ~TimerScoped()

Private Members

T &zone_

Summary

Fwog is a low-level OpenGL 4.6 abstraction written in C++20 which aims to offer improved ergonomics and eliminate deprecated functionality. The goal is to wrap OpenGL in an expressive, type-safe, and easy-to-use wrapper.

The design of Fwog is motivated by some of the shortcomings of OpenGL that I identified in my blog post. For example, Fwog wraps OpenGL’s integer constants with strongly-typed enumerations. Fwog also offers RAII wrappers for most OpenGL object types (buffers, textures, shaders, fences, and timer queries). Other types, like vertex arrays and framebuffers, are completely abstracted away in favor of a cleaner programming model.

Fwog uses pipeline objects to encapsulate what would otherwise be global OpenGL state. These objects are bound before drawing to set the state of the pipeline, making it clear to the reader which state will be used and preventing subtle bugs where state leaks from one pass to the next. Pipelines also offer the potential benefit of reduced stuttering by providing more information to the driver up-front (source).

Caveats

Given Fwog’s goals, there are a number of features that the API does not expose:

The default uniform block (i.e., uniforms set with glUniform*)
Geometry shaders
Multi-viewport/layered rendering
Multisampled rasterization
Transform feedback
Hardware occlusion queries
SPIR-V shaders
All deprecated OpenGL features

Some of these (such as multisampled rasterization and geo/tess shaders) have not been implemented due to a lack of perceived interest, while others (such as glUniform and transform feedback) aren’t due to their orthogonality to Fwog’s design. Please raise an issue if you would like a feature to be implemented. Otherwise, it’s possible to use certain unsupported features alongside Fwog’s abstraction.

Indices and tables

Index