gpu::Context Class Reference

#include <Context.h>

Collaboration diagram for gpu::Context:

Classes
struct	ProgramsToSync

Public Member Functions
void	shutdown ()
const std::string &	getBackendVersion () const
void	beginFrame (const glm::mat4 &renderView=glm::mat4(), const glm::mat4 &renderPose=glm::mat4())
	Creates and sets up new Frame object to which batches of renderer commands will be written. More...
void	appendFrameBatch (const BatchPointer &batch)
	Appends a batch at the end of the current frame. More...
FramePointer	endFrame ()
	Finalizes the currently recorded frame. More...
void	recycle () const
void	executeBatch (Batch &batch) const
void	executeBatch (const char *name, std::function< void(Batch &)> lambda) const
void	executeFrame (const FramePointer &frame) const
void	consumeFrameUpdates (const FramePointer &frame) const
const BackendPointer &	getBackend () const
void	enableStereo (bool enable=true)
	Enables stereo for the context. More...
bool	isStereo ()
void	setStereoProjections (const mat4 eyeProjections[2])
	Sets projection matrices for each eye. More...
void	setStereoViews (const mat4 eyeViews[2])
	Sets view matrices for each eye. More...
void	getStereoProjections (mat4 *eyeProjections) const
	Writes current stereo projection matrices to a given mat4 array. More...
void	getStereoViews (mat4 *eyeViews) const
	Writes current stereo view matrices to a given mat4 array. More...
void	downloadFramebuffer (const FramebufferPointer &srcFramebuffer, const Vec4i &region, QImage &destImage)
	Writes a region of a given framebuffer to a QImage. More...
void	resetStats () const
	Resets render statistics such as draw call count.
void	getStats (ContextStats &stats) const
	Retrieves current render statistics such as draw call count. More...
void	getFrameStats (ContextStats &stats) const
	Retrieves most recent frame render statistics such as draw call count. More...
double	getFrameTimerGPUAverage () const
double	getFrameTimerBatchAverage () const
void	pushProgramsToSync (const std::vector< uint32_t > &programIDs, std::function< void()> callback, size_t rate=0)
	Schedule shaders for loading. More...
void	pushProgramsToSync (const std::vector< gpu::ShaderPointer > &programs, std::function< void()> callback, size_t rate=0)
	Schedule shaders for loading. More...
void	processProgramsToSync ()
	Loads and compiles shaders. More...

Static Public Member Functions
template<class T >
static void	init ()
	Creates graphics-API specific Backend object. More...
static BatchPointer	acquireBatch (const char *name=nullptr)
	Acquires batch from a batch pool and sets its name. More...
static void	releaseBatch (Batch *batch)
	Clears the batch and adds it batch to the pool. More...
static PipelinePointer	createMipGenerationPipeline (const ShaderPointer &pixelShader)
	Creates a custom pipeline for generating mipmaps. More...
static Size	getFreeGPUMemSize ()
static Size	getUsedGPUMemSize ()
static uint32_t	getBufferGPUCount ()
static Size	getBufferGPUMemSize ()
static uint32_t	getTextureGPUCount ()
static uint32_t	getTextureResidentGPUCount ()
static uint32_t	getTextureFramebufferGPUCount ()
static uint32_t	getTextureResourceGPUCount ()
static uint32_t	getTextureExternalGPUCount ()
static Size	getTextureGPUMemSize ()
static Size	getTextureResidentGPUMemSize ()
static Size	getTextureFramebufferGPUMemSize ()
static Size	getTextureResourceGPUMemSize ()
static Size	getTextureExternalGPUMemSize ()
static uint32_t	getTexturePendingGPUTransferCount ()
static Size	getTexturePendingGPUTransferMemSize ()
static Size	getTextureResourcePopulatedGPUMemSize ()
static Size	getTextureResourceIdealGPUMemSize ()

Protected Member Functions
	Context (const Context &context)=delete

Static Protected Member Functions
static void	clearBatches ()
	Deletes all batches in the batch pool. More...

Protected Attributes
std::shared_ptr< Backend >	_backend
FramePointer	_currentFrame
RangeTimerPointer	_frameRangeTimer
StereoState	_stereo
std::mutex	_programsToSyncMutex
std::queue< ProgramsToSync >	_programsToSyncQueue
gpu::Shaders	_syncedPrograms
size_t	_nextProgramToSyncIndex { 0 }
ContextStats	_frameStats

Static Protected Attributes
static CreateBackend	_createBackendCallback = nullptr
static std::once_flag	_initialized
static std::mutex	_batchPoolMutex
static std::list< Batch * >	_batchPool

Detailed Description

DOCTODO

Constructor & Destructor Documentation

Context()

gpu::Context::Context ( const Context &  context )

protecteddelete

Copy constructor, not used.

Parameters

context

Not used.

Member Function Documentation

acquireBatch()

BatchPointer Context::acquireBatch ( const char *  name = nullptr )

static

Acquires batch from a batch pool and sets its name.

If there are no free batches, it creates new one.

Parameters

name	Name to set fot the batch.

Returns

Shared pointer to the batch.

appendFrameBatch()

void Context::appendFrameBatch

(

const BatchPointer &

batch

)

Appends a batch at the end of the current frame.

Parameters

batch

Batch to append.

beginFrame()

void Context::beginFrame	(	const glm::mat4 &	renderView = glm::mat4(),
		const glm::mat4 &	renderPose = glm::mat4()
	)

Creates and sets up new Frame object to which batches of renderer commands will be written.

Parameters

renderView	The view matrix used for rendering the frame, only applicable for HMDs.
renderPose	HMD head pose.

clearBatches()

void Context::clearBatches ( )

staticprotected

Deletes all batches in the batch pool.

Called from the Context destructor. TODO: Should probably move this functionality to Batch. (this comment was here since High Fidelity days, I'm not sure if it still makes sense)

consumeFrameUpdates()

void Context::consumeFrameUpdates

(

const FramePointer &

frame

)

const

Consuming a frame applies any updates queued from the recording thread and applies them to the shadow copy used by the rendering thread.

EVERY frame generated MUST be consumed, regardless of whether the frame is actually executed, or the buffer shadow copies can become unsynced from the recording thread copies.

Consuming a frame is idempotent, as the frame encapsulates the updates and clears them out as it applies them, so calling it more than once on a given frame will have no effect after the first time

This is automatically called by executeFrame, so you only need to call it if you have frames you aren't going to otherwise execute, for instance when a display plugin is being disabled, or in the null display plugin where no rendering actually occurs MUST only be called on the Present thread, which does rendering.

Parameters

frame

Frame for which updates are to be consumed.

createMipGenerationPipeline()

PipelinePointer Context::createMipGenerationPipeline ( const ShaderPointer &  pixelShader )

static

Creates a custom pipeline for generating mipmaps.

Used for SSAO.

Parameters

pixelShader

Pixel shader to use for mipmap generation.

Returns

Shared pointer to the pipeline.

downloadFramebuffer()

void Context::downloadFramebuffer	(	const FramebufferPointer &	srcFramebuffer,
		const Vec4i &	region,
		QImage &	destImage
	)

Writes a region of a given framebuffer to a QImage.

Downloading the Framebuffer is a synchronous action that is not efficient. It s here for convenience to easily capture a snapshot

Parameters

srcFramebuffer	Framebuffer from which to capture the contents.
region	Area to capture. First two coordinates are position of the corner in pixels, and second two are width and height.
destImage	QImage object. Needs to be a correct size and format.

enableStereo()

void Context::enableStereo

(

bool

enable = true

)

Enables stereo for the context.

Called in render_performFrame, where frame rendering commands are recorded.

Parameters

enable

True if stereo rendering should be enabled.

endFrame()

FramePointer Context::endFrame

(

)

Finalizes the currently recorded frame.

After calling this function batches cannot be added to the frame anymore.

Returns

Finished frame. Later frame gets submitted to the display plugin to be rendered on Present thread.

executeBatch() [1/2]

void Context::executeBatch

(

Batch &

batch

)

const

Execute a batch immediately, rather than as part of a frame. MUST only be called on the Present thread, which does rendering.

Parameters

batch

executeBatch() [2/2]

void Context::executeBatch	(	const char *	name,
		std::function< void(Batch &)>	lambda
	)		const

Execute a batch immediately, rather than as part of a frame. MUST only be called on the Present thread, which does rendering.

Parameters

name	Name of the batch.
lambda	Function that adds commands to batch that will be executed.

executeFrame()

void Context::executeFrame

(

const FramePointer &

frame

)

const

Executes a frame, applying any updates contained in the frame batches to the rendering thread shadow copies. Either executeFrame or consumeFrameUpdates MUST be called on every frame generated, IN THE ORDER they were generated.

Parameters

frame

Frame to be executed.

getBackend()

const BackendPointer& gpu::Context::getBackend ( ) const

inline

Returns

Pointer to the Backend object of type specific to currently used graphics API.

getBackendVersion()

const std::string & Context::getBackendVersion

(

)

const

Returns

String describing which graphics API-specific backend is currently in use.

getBufferGPUCount()

uint32_t Context::getBufferGPUCount ( )

static

Returns

Number of buffers on the GPU.

getBufferGPUMemSize()

Context::Size Context::getBufferGPUMemSize ( )

static

Returns

Size of GPU memory used by buffers in bytes.

getFrameStats()

void Context::getFrameStats

(

ContextStats &

stats

)

const

Retrieves most recent frame render statistics such as draw call count.

Same as above but updated at every end of a frame

Parameters

stats

Object to which current statistics will be written.

getFrameTimerBatchAverage()

double Context::getFrameTimerBatchAverage

(

)

const

Returns

Batch frame time in milliseconds.

getFrameTimerGPUAverage()

double Context::getFrameTimerGPUAverage

(

)

const

Returns

GPU frame time in milliseconds.

getFreeGPUMemSize()

Size Context::getFreeGPUMemSize ( )

static

Returns

Free GPU memory in bytes.

getStats()

void Context::getStats

(

ContextStats &

stats

)

const

Retrieves current render statistics such as draw call count.

Parameters

stats

Object to which current statistics will be written.

getStereoProjections()

void Context::getStereoProjections

(

mat4 *

eyeProjections

)

const

Writes current stereo projection matrices to a given mat4 array.

Parameters

eyeProjections

Pointer to the array of matrices. Array needs to have 2 matrices.

getStereoViews()

void Context::getStereoViews

(

mat4 *

eyeViews

)

const

Writes current stereo view matrices to a given mat4 array.

Parameters

eyeViews

Pointer to the array of matrices. Array needs to have 2 matrices.

getTextureExternalGPUCount()

uint32_t Context::getTextureExternalGPUCount ( )

static

Returns

Number of external textures, used for things such as QML and webentities.

getTextureExternalGPUMemSize()

Size Context::getTextureExternalGPUMemSize ( )

static

Returns

Amount of GPU memory used by external textures, used for things such as QML and webentities.

getTextureFramebufferGPUCount()

uint32_t Context::getTextureFramebufferGPUCount ( )

static

Returns

Number of framebuffers on the GPU.

getTextureFramebufferGPUMemSize()

Size Context::getTextureFramebufferGPUMemSize ( )

static

Returns

Amount of GPU memory used by framebuffers, in bytes.

getTextureGPUCount()

uint32_t Context::getTextureGPUCount ( )

static

Returns

Number of textures on the GPU.

getTextureGPUMemSize()

Size Context::getTextureGPUMemSize ( )

static

Returns

Amount of GPU memory used by textures, in bytes.

getTexturePendingGPUTransferCount()

uint32_t Context::getTexturePendingGPUTransferCount ( )

static

TODO: Currently not used.

Returns

getTexturePendingGPUTransferMemSize()

Size Context::getTexturePendingGPUTransferMemSize ( )

static

Returns

Size in bytes of the textures that are currently transferred.

getTextureResidentGPUCount()

uint32_t Context::getTextureResidentGPUCount ( )

static

Returns

Number of textures on the GPU which usage is TextureUsageType::STRICT_RESOURCE.

getTextureResidentGPUMemSize()

Size Context::getTextureResidentGPUMemSize ( )

static

Returns

Amount of GPU memory in bytes used by textures on the GPU which usage is TextureUsageType::STRICT_RESOURCE.

getTextureResourceGPUCount()

uint32_t Context::getTextureResourceGPUCount ( )

static

Returns

Number of resource textures on the GPU. These are regular textures used for things such as models or skyboxes.

getTextureResourceGPUMemSize()

Size Context::getTextureResourceGPUMemSize ( )

static

Returns

Amount of GPU memory used by resource textures on the GPU. These are regular textures used for things such as models or skyboxes.

getTextureResourceIdealGPUMemSize()

Size Context::getTextureResourceIdealGPUMemSize ( )

static

Returns

Total size of textures that are in use currently, including mips that are not currently on GPU.

getTextureResourcePopulatedGPUMemSize()

Size Context::getTextureResourcePopulatedGPUMemSize ( )

static

Returns

Size in bytes of currently populated mips variable allocation textures.

getUsedGPUMemSize()

Size Context::getUsedGPUMemSize ( )

static

Returns

Used GPU memory in bytes.

init()

template<class T >

static void gpu::Context::init ( )

inlinestatic

Creates graphics-API specific Backend object.

This one call must happen before any context is created or used (Shader::MakeProgram) in order to set up the Backend and any singleton data needed.

Template Parameters

T	Type of the backend to create, specific to given graphics API.

isStereo()

bool Context::isStereo

(

)

Returns

true if stereo rendering was enabled with enableStereo.

processProgramsToSync()

void Context::processProgramsToSync

(

)

Loads and compiles shaders.

Called once per frame.

pushProgramsToSync() [1/2]

void Context::pushProgramsToSync	(	const std::vector< gpu::ShaderPointer > &	programs,
		std::function< void()>	callback,
		size_t	rate = 0
	)

Schedule shaders for loading.

Parameters

programs	Pointers to shaders to be loaded and compiled.
callback	Function to call when work is done.
rate	Limits how many shaders can be processed in a single frame.

pushProgramsToSync() [2/2]

void Context::pushProgramsToSync	(	const std::vector< uint32_t > &	programIDs,
		std::function< void()>	callback,
		size_t	rate = 0
	)

Schedule shaders for loading.

Parameters

programIDs	IDs representing shaders to be synchronized. Can be found in ShaderEnums.h file, which is generated at build time.
callback	Function to call when work is done.
rate	Limits how many shaders can be processed in a single frame.

recycle()

void Context::recycle

(

)

const

Handle any pending operations to clean up (recycle / deallocate) resources no longer in use. MUST only be called on the Present thread, which does rendering.

releaseBatch()

void Context::releaseBatch ( Batch *  batch )

static

Clears the batch and adds it batch to the pool.

Parameters

batch

Batch to be released.

setStereoProjections()

void Context::setStereoProjections

(

const mat4

eyeProjections[2]

)

Sets projection matrices for each eye.

Used in render_performFrame before recording the frame rendering commands,

Parameters

eyeProjections

setStereoViews()

void Context::setStereoViews

(

const mat4

eyeViews[2]

)

Sets view matrices for each eye.

DOCTODO: What coordinate system does this use? Used in render_performFrame before recording the frame rendering commands,

Parameters

eyeViews

shutdown()

void Context::shutdown

(

)

@bried Shuts down and deletes graphics backend.

Member Data Documentation

_backend

std::shared_ptr<Backend> gpu::Context::_backend

protected

Instance of Backend class specific to currently selected graphics APT, for example Vulkan or OpenGL.

_batchPool

std::list< Batch * > Context::_batchPool

staticprotected

Pool of batches that can be acquired by renderer and reused for recording.

_batchPoolMutex

std::mutex Context::_batchPoolMutex

staticprotected

Mutex for accessing batch pool.

_createBackendCallback

Context::CreateBackend Context::_createBackendCallback = nullptr

staticprotected

API-specific call that creates rendering backend.

_currentFrame

FramePointer gpu::Context::_currentFrame

protected

Frame currently being recorded. A new Frame object is placed here by beginFrame and the variable is reset by endFrame.

_frameRangeTimer

RangeTimerPointer gpu::Context::_frameRangeTimer

protected

Time it takes for the frame to execute.

_frameStats

ContextStats gpu::Context::_frameStats

mutableprotected

Sampled at the end of every frame, the stats of all the counters.

_initialized

std::once_flag Context::_initialized

staticprotected

Ensures that initialization inside Context::init() is called only once.

_nextProgramToSyncIndex

size_t gpu::Context::_nextProgramToSyncIndex { 0 }

protected

Next shader that will be loaded/compiled.

_programsToSyncMutex

std::mutex gpu::Context::_programsToSyncMutex

protected

Mutex protecting _programsToSyncQueue, must be locked every time it's accessed.

_programsToSyncQueue

std::queue<ProgramsToSync> gpu::Context::_programsToSyncQueue

protected

Queue for loading and compiling shaders. It helps avoid stutter later during the game.

_stereo

StereoState gpu::Context::_stereo

protected

Stereo state is configured before frame recording starts.

_syncedPrograms

gpu::Shaders gpu::Context::_syncedPrograms

protected

Shaders that were already loaded/compiled.

---

The documentation for this class was generated from the following files:

• gpu/src/gpu/Context.h
• gpu/src/gpu/Context.cpp