Wizt::GLBuffer Class Reference

Implements functionality related to an OpenGL buffer object. More...

#include <ocean/GLvish/GLBuffer.hpp>

Inheritance diagram for Wizt::GLBuffer:

Public Member Functions
void *	map_wo (size_t offset=0, size_t length=0) const override
	Recommended creation and usage pattern for a short-lived CPU staging buffer.
void	setSubData (size_t offset, const void *data, size_t length) const override
	Set a subset of the data, which is more efficient than setData();.
Public Member Functions inherited from Wizt::MapMemory
void	setData (size_t length, const StorageFlags &SF) const
	Reserve data only.

Detailed Description

Implements functionality related to an OpenGL buffer object.

Member Function Documentation

map_wo()

void * Wizt::GLBuffer::map_wo ( size_t offset = 0, size_t length = 0 ) const

overridevirtual

Recommended creation and usage pattern for a short-lived CPU staging buffer.

This document describes the optimal OpenGL flags and workflow for a staging buffer used exclusively as an intermediate upload source. The staging buffer is mapped once, written once, unmapped immediately, and subsequently used as the source of a GPU-side copy operation into a device-local buffer.

Purpose

A staging buffer serves as a CPU-visible temporary storage region. Data is written into the staging buffer by the CPU and then transferred into a non-mappable, device-local buffer using glCopyNamedBufferSubData(). The staging buffer itself is not used for rendering and is not accessed by the GPU outside of the copy operation.

Storage Flags

For a staging buffer that is mapped only once and unmapped before any GPU access, the recommended storage flags are:

GL_MAP_WRITE_BIT

These flags permit CPU write access and impose no additional residency or synchronization requirements. Persistent or coherent mapping flags are not required because the buffer is not kept mapped across frames and does not require GPU-visible coherence while mapped.

Mapping Flags

The corresponding mapping flags should match the storage flags:

GL_MAP_WRITE_BIT

No additional mapping flags are necessary. In particular:

• GL_MAP_PERSISTENT_BIT is unnecessary because the buffer is not kept persistently mapped.
• GL_MAP_COHERENT_BIT is unnecessary because the buffer is unmapped before the GPU copy operation, eliminating the need for CPU/GPU coherence.
• GL_MAP_INVALIDATE_RANGE_BIT and GL_MAP_INVALIDATE_BUFFER_BIT have no effect because the buffer is not remapped repeatedly.
• GL_MAP_UNSYNCHRONIZED_BIT is unnecessary because the buffer is unmapped before any GPU access, preventing synchronization hazards.

Upload Workflow

1. Create the staging buffer using glNamedBufferStorage() with GL_MAP_WRITE_BIT.
2. Map the buffer using glMapNamedBufferRange() with GL_MAP_WRITE_BIT.
3. Write the upload data into the mapped region.
4. Unmap the buffer.
5. Create a device-local buffer without mapping flags.
6. Transfer the data using:

   glCopyNamedBufferSubData(stagingBuffer, deviceLocalBuffer,
                            srcOffset, dstOffset, size);

7. Synchronize on the copy operation before using the device-local buffer for rendering.

Summary

• A staging buffer mapped once and unmapped before GPU access requires only GL_MAP_WRITE_BIT for both storage and mapping.
• Persistent, coherent, invalidate, and unsynchronized flags provide no benefit in this usage pattern.
• The staging buffer is used solely as a CPU upload source; the device-local buffer is used for rendering.

Implements Wizt::MapMemory.

References map_wo().

Referenced by map_wo().