Ogre::HlmsComputeJob Class Reference

#include <OgreHlmsComputeJob.h>

Inheritance diagram for Ogre::HlmsComputeJob:

Public Types
enum	ThreadGroupsBasedOn { ThreadGroupsBasedOnNothing , ThreadGroupsBasedOnTexture , ThreadGroupsBasedOnUav }

Public Member Functions
	HlmsComputeJob (IdString name, Hlms *creator, const String &sourceFilename, const StringVector &includedPieceFiles)
virtual	~HlmsComputeJob ()
void	_calculateNumThreadGroupsBasedOnSetting ()
	INTERNAL USE.
ShaderParams *	_getShaderParams (IdString key)
	Gets a shader parameter with the given key.
void	_setSamplerblock (uint8 slotIdx, const HlmsSamplerblock *refParams)
	Sets a samplerblock directly.
void	_setUavBuffer (uint8 slotIdx, UavBufferPacked *uavBuffer, ResourceAccess::ResourceAccess access, size_t offset=0, size_t sizeBytes=0)
	Sets an UAV buffer at the given slot ID.
void	_setUavTexture (uint8 slotIdx, TexturePtr &texture, int32 textureArrayIndex, ResourceAccess::ResourceAccess access, int32 mipmapLevel, PixelFormat pixelFormat)
	Sets an UAV texture.
void	_updateAutoProperties (void)
HlmsComputeJob *	clone (const String &cloneName)
void	cloneTo (HlmsComputeJob *dstJob)
void	createShaderParams (IdString key)
	Creates a set of shader paramters with a given key, e.g.
Hlms *	getCreator (void) const
IdString	getName (void) const
size_t	getNumTexUnits (void) const
const uint32 *	getNumThreadGroups (void) const
uint32	getNumThreadGroupsX (void) const
uint32	getNumThreadGroupsY (void) const
uint32	getNumThreadGroupsZ (void) const
size_t	getNumUavUnits (void) const
int32	getProperty (IdString key, int32 defaultVal=0) const
ShaderParams &	getShaderParams (IdString key)
	Gets a shader parameter with the given key.
const TexturePtr &	getTexture (uint8 slotIdx) const
const uint32 *	getThreadsPerGroup (void) const
uint32	getThreadsPerGroupX (void) const
uint32	getThreadsPerGroupY (void) const
uint32	getThreadsPerGroupZ (void) const
UavBufferPacked *	getUavBuffer (uint8 slotIdx) const
const TexturePtr &	getUavTexture (uint8 slotIdx) const
void	operator delete (void *ptr)
void	operator delete (void *ptr, const char *, int, const char *)
void	operator delete (void *ptr, void *)
void	operator delete[] (void *ptr)
void	operator delete[] (void *ptr, const char *, int, const char *)
void *	operator new (size_t sz)
void *	operator new (size_t sz, const char *file, int line, const char *func)
	operator new, with debug line info
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz)
void *	operator new[] (size_t sz, const char *file, int line, const char *func)
	array operator new, with debug line info
void	removePiece (IdString pieceName)
	Removes an existing piece.
void	removeTexUnit (uint8 slotIdx)
	Destroys a given texture unit, displacing all the higher tex units.
void	removeUavUnit (uint8 slotIdx)
	Destroys a given texture unit, displacing all the higher tex units.
void	setConstBuffer (uint8 slotIdx, ConstBufferPacked *constBuffer)
	Sets a const/uniform bufferat the given slot ID.
void	setInformHlmsOfTextureData (bool bInformHlms)
	The Hlms has the ability to pass data to the shader source code via its syntax system to add hardcoded values.
void	setNumTexUnits (uint8 numSlots)
	Creates 'numSlots' number of slots before they can be set.
void	setNumThreadGroups (uint32 numThreadGroupsX, uint32 numThreadGroupsY, uint32 numThreadGroupsZ)
	Sets the number of groups of threads to dispatch.
void	setNumThreadGroupsBasedOn (ThreadGroupsBasedOn source, uint8 texSlot, uint8 divisorX, uint8 divisorY, uint8 divisorZ)
	Instead of calling setNumThreadGroups, Ogre can automatically deduce them based on the Texture resolution and the threads per group.
void	setNumUavUnits (uint8 numSlots)
	Creates 'numSlots' number of slots before they can be set.
void	setPiece (IdString pieceName, const String &pieceContent)
	Defines a piece, i.e.
void	setProperty (IdString key, int32 value)
	Sets an arbitrary property to pass to the shader.
void	setSamplerblock (uint8 slotIdx, const HlmsSamplerblock &refParams)
	Sets a samplerblock based on reference parameters.
void	setTexBuffer (uint8 slotIdx, TexBufferPacked *texBuffer, size_t offset=0, size_t sizeBytes=0)
	Sets a texture buffer at the given slot ID.
void	setTexture (uint8 slotIdx, TexturePtr &texture, const HlmsSamplerblock *refParams=0)
	Sets a texture buffer at the given slot ID.
void	setThreadsPerGroup (uint32 threadsPerGroupX, uint32 threadsPerGroupY, uint32 threadsPerGroupZ)
	Sets the number of threads per group.

Friends
class	HlmsCompute

Member Enumeration Documentation

ThreadGroupsBasedOn

enum Ogre::HlmsComputeJob::ThreadGroupsBasedOn

Enumerator
ThreadGroupsBasedOnNothing	Disabled. (obey setNumThreadGroups)
ThreadGroupsBasedOnTexture	Based the number of thread groups on a texture. See setNumThreadGroupsBasedOn.
ThreadGroupsBasedOnUav	Based the number of thread groups on a UAV. See setNumThreadGroupsBasedOn.

Constructor & Destructor Documentation

HlmsComputeJob()

Ogre::HlmsComputeJob::HlmsComputeJob	(	IdString	name,
		Hlms *	creator,
		const String &	sourceFilename,
		const StringVector &	includedPieceFiles
	)

~HlmsComputeJob()

virtual Ogre::HlmsComputeJob::~HlmsComputeJob ( )

virtual

Member Function Documentation

_calculateNumThreadGroupsBasedOnSetting()

void Ogre::HlmsComputeJob::_calculateNumThreadGroupsBasedOnSetting

(

)

INTERNAL USE.

Calculates the number of thread groups as specified in setNumThreadGroupsBasedOn, overriding setNumThreadGroups.

_getShaderParams()

ShaderParams * Ogre::HlmsComputeJob::_getShaderParams

(

IdString

key

)

Gets a shader parameter with the given key.

e.g. "default" "glsl" "hlsl". Returns null if doesn't exist. See createShaderParams

_setSamplerblock()

void Ogre::HlmsComputeJob::_setSamplerblock	(	uint8	slotIdx,
		const HlmsSamplerblock *	refParams
	)

Sets a samplerblock directly.

For internal use / advanced users.

Parameters

slotIdx	See setNumTexUnits.
refParams	Direct samplerblock. Reference count is assumed to already have been increased. We won't increase it ourselves.
params	The sampler block to use as reference.

_setUavBuffer()

void Ogre::HlmsComputeJob::_setUavBuffer	(	uint8	slotIdx,
		UavBufferPacked *	uavBuffer,
		ResourceAccess::ResourceAccess	access,
		size_t	offset = 0,
		size_t	sizeBytes = 0
	)

Sets an UAV buffer at the given slot ID.

Remarks

UAV slots are shared with setUavTexture. Calling this function will remove the settings from previous setUavTexture calls to the same slot index.

May trigger a recompilation if setInformHlmsOfTextureData is enabled.

Be very careful when calling this directly. The Compositor needs to evaluate memory barriers and resource transitions. Leaving inconsistent memory barriers can result in hazards/race conditions in some APIs. If in doubt, change the CompositorPassComputeDef instead.

Parameters

slotIdx	See setNumUavUnits. The slot index to bind this UAV buffer.
access	Access. Should match what the shader expects. Needed by Ogre to resolve memory barrier dependencies.
uavBuffer	UAV buffer to bind.
offset	0-based offset. It is possible to bind a region of the buffer. Offset needs to be aligned. You can query the RS capabilities for the alignment, however 256 bytes is the maximum allowed alignment per the OpenGL specification, making it a safe bet to hardcode.
sizeBytes	Size in bytes to bind the tex buffer. When zero, binds from offset until the end of the buffer.

_setUavTexture()

void Ogre::HlmsComputeJob::_setUavTexture	(	uint8	slotIdx,
		TexturePtr &	texture,
		int32	textureArrayIndex,
		ResourceAccess::ResourceAccess	access,
		int32	mipmapLevel,
		PixelFormat	pixelFormat
	)

Sets an UAV texture.

Remarks

UAV buffer slots are shared with setUavTexture's. Calling this function will remove the settings from previous setUavBuffer calls to the same slot index.

May trigger a recompilation if setInformHlmsOfTextureData is enabled.

Be very careful when calling this directly. The Compositor needs to evaluate memory barriers and resource transitions. Leaving inconsistent memory barriers can result in hazards/race conditions in some APIs. If in doubt, change the CompositorPassComputeDef instead.

Parameters

slot	See setNumUavUnits.
texture
textureArrayIndex
access
mipmapLevel
pixelFormat

_updateAutoProperties()

void Ogre::HlmsComputeJob::_updateAutoProperties

(

void

)

clone()

HlmsComputeJob * Ogre::HlmsComputeJob::clone

(

const String &

cloneName

)

cloneTo()

void Ogre::HlmsComputeJob::cloneTo

(

HlmsComputeJob *

dstJob

)

createShaderParams()

void Ogre::HlmsComputeJob::createShaderParams

(

IdString

key

)

Creates a set of shader paramters with a given key, e.g.

"default" "glsl" "hlsl". Does nothing if parameters already exist.

getCreator()

Hlms * Ogre::HlmsComputeJob::getCreator ( void  ) const

inline

getName()

IdString Ogre::HlmsComputeJob::getName ( void  ) const

inline

getNumTexUnits()

size_t Ogre::HlmsComputeJob::getNumTexUnits ( void  ) const

inline

getNumThreadGroups()

const uint32 * Ogre::HlmsComputeJob::getNumThreadGroups ( void  ) const

inline

getNumThreadGroupsX()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsX ( void  ) const

inline

getNumThreadGroupsY()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsY ( void  ) const

inline

getNumThreadGroupsZ()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsZ ( void  ) const

inline

getNumUavUnits()

size_t Ogre::HlmsComputeJob::getNumUavUnits ( void  ) const

inline

getProperty()

int32 Ogre::HlmsComputeJob::getProperty	(	IdString	key,
		int32	defaultVal = 0
	)		const

getShaderParams()

ShaderParams & Ogre::HlmsComputeJob::getShaderParams

(

IdString

key

)

Gets a shader parameter with the given key.

e.g. "default" "glsl" "hlsl". Creates if does not exist.

getTexture()

const TexturePtr & Ogre::HlmsComputeJob::getTexture

(

uint8

slotIdx

)

const

getThreadsPerGroup()

const uint32 * Ogre::HlmsComputeJob::getThreadsPerGroup ( void  ) const

inline

getThreadsPerGroupX()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupX ( void  ) const

inline

getThreadsPerGroupY()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupY ( void  ) const

inline

getThreadsPerGroupZ()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupZ ( void  ) const

inline

getUavBuffer()

UavBufferPacked * Ogre::HlmsComputeJob::getUavBuffer

(

uint8

slotIdx

)

const

getUavTexture()

const TexturePtr & Ogre::HlmsComputeJob::getUavTexture

(

uint8

slotIdx

)

const

operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr )

inlineinherited

operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr, const char *  , int  , const char *    )

inlineinherited

operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr, void *    )

inlineinherited

operator delete[]() [1/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr )

inlineinherited

operator delete[]() [2/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr, const char *  , int  , const char *    )

inlineinherited

operator new() [1/3]

template<class Alloc >

void * Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz )

inlineinherited

operator new() [2/3]

template<class Alloc >

void * Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz, const char *  file, int  line, const char *  func  )

inlineinherited

operator new, with debug line info

operator new() [3/3]

template<class Alloc >

void * Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz, void *  ptr  )

inlineinherited

placement operator new

operator new[]() [1/2]

template<class Alloc >

void * Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz )

inlineinherited

operator new[]() [2/2]

template<class Alloc >

void * Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz, const char *  file, int  line, const char *  func  )

inlineinherited

array operator new, with debug line info

removePiece()

void Ogre::HlmsComputeJob::removePiece

(

IdString

pieceName

)

Removes an existing piece.

See setPiece. Does nothing if the piece didn't exist.

removeTexUnit()

void Ogre::HlmsComputeJob::removeTexUnit

(

uint8

slotIdx

)

Destroys a given texture unit, displacing all the higher tex units.

removeUavUnit()

void Ogre::HlmsComputeJob::removeUavUnit

(

uint8

slotIdx

)

Destroys a given texture unit, displacing all the higher tex units.

setConstBuffer()

void Ogre::HlmsComputeJob::setConstBuffer	(	uint8	slotIdx,
		ConstBufferPacked *	constBuffer
	)

Sets a const/uniform bufferat the given slot ID.

Parameters

slotIdx	Slot to bind to. It's independent from the texture & UAV ones.
constBuffer	Const buffer to bind.

setInformHlmsOfTextureData()

void Ogre::HlmsComputeJob::setInformHlmsOfTextureData

(

bool

bInformHlms

)

The Hlms has the ability to pass data to the shader source code via its syntax system to add hardcoded values.

For example, you may want to unroll a loop based on the width of a texture for maximum performance.

Enabling this feature informs the Hlms to reparse the shader on any change to bound textures that could trigger a recompilation. If you don't need it, keep this feature disabled to prevent unnecessary recompilations.

Parameters

bInformHlms

True to enable this feature, false to disable.

setNumTexUnits()

void Ogre::HlmsComputeJob::setNumTexUnits

(

uint8

numSlots

)

Creates 'numSlots' number of slots before they can be set.

setNumThreadGroups()

void Ogre::HlmsComputeJob::setNumThreadGroups	(	uint32	numThreadGroupsX,
		uint32	numThreadGroupsY,
		uint32	numThreadGroupsZ
	)

Sets the number of groups of threads to dispatch.

Note the actual value may be changed by the shader template using the @pset() function. These values are passed to the template as: num_thread_groups_x num_thread_groups_y num_thread_groups_z

Remarks

As an example, it's typical to do: numThreadGroupsX = ceil( threadsPerGroupX / image.width ); numThreadGroupsY = ceil( threadsPerGroupY / image.height );

May trigger a recompilation if the value changes, regardless of what setInformHlmsOfTextureData says. There may be API / HW limitations on the max values for each dimension.

setNumThreadGroupsBasedOn()

void Ogre::HlmsComputeJob::setNumThreadGroupsBasedOn	(	ThreadGroupsBasedOn	source,
		uint8	texSlot,
		uint8	divisorX,
		uint8	divisorY,
		uint8	divisorZ
	)

Instead of calling setNumThreadGroups, Ogre can automatically deduce them based on the Texture resolution and the threads per group.

It is calculated as follows: scaledWidth = (textureWidth + divisorX - 1u) / divisorX; numThreadGroupsX = (scaledWidth + threadsPerGroupX - 1u) / threadsPerGroupX;

Remarks

Unless disabled, this will overwrite your setNumThreadGroups based on the texture bound at the time the job is dispatched.

If no texture/uav is bound at the given slot (or no such slot exists), we will log a warning.

Parameters

source	What to use as source for the calculations. See ThreadGroupsBasedOn
texSlot	Index of the texture/uav unit.
divisorX	divisorY divisorZ Often compute shaders operate on multiple pixels, thus you need less thread groups. For example if you operate on blocks of 2x2, then you want divisorX = 2 and divisorY = 2.

setNumUavUnits()

void Ogre::HlmsComputeJob::setNumUavUnits

(

uint8

numSlots

)

Creates 'numSlots' number of slots before they can be set.

setPiece()

void Ogre::HlmsComputeJob::setPiece	(	IdString	pieceName,
		const String &	pieceContent
	)

Defines a piece, i.e.

the same as doing @piece( pieceName )pieceContent@end If the piece doesn't exist, it gets created. If the piece already exists, it gets overwritten.

Remarks

Because we need to efficiently track changes (to know when to recompile, when we can reuse a cached shader, etc), we store a property of the same name as pieceName with the hash of the piece's content as value. e.g. doing setPiece( pieceName, pieceContent ) implies calling setProperty( pieceName, hash( pieceContent ). Hence you should NOT manipulate mPieces directly, otherwise we won't see changes performed to it, or use shaders from a cache we shouldn't use.

Parameters

pieceName	Name of the piece.
pieceContent	The contents of the piece.

setProperty()

void Ogre::HlmsComputeJob::setProperty	(	IdString	key,
		int32	value
	)

Sets an arbitrary property to pass to the shader.

Remarks

Will trigger a recompilation if the value changes, regardless of what setInformHlmsOfTextureData says.

Parameters

key	Name of the property
value	Value to set

setSamplerblock()

void Ogre::HlmsComputeJob::setSamplerblock	(	uint8	slotIdx,
		const HlmsSamplerblock &	refParams
	)

Sets a samplerblock based on reference parameters.

Parameters

slotIdx	See setNumTexUnits.
refParams	We'll create (or retrieve an existing) samplerblock based on the input parameters.

setTexBuffer()

void Ogre::HlmsComputeJob::setTexBuffer	(	uint8	slotIdx,
		TexBufferPacked *	texBuffer,
		size_t	offset = 0,
		size_t	sizeBytes = 0
	)

Sets a texture buffer at the given slot ID.

Remarks

Texture buffer slots are shared with setTexture's. Calling this function will remove the settings from previous setTexture calls to the same slot index.

May trigger a recompilation if setInformHlmsOfTextureData is enabled.

Setting a RenderTarget that could be used for writing is dangerous in explicit APIs (DX12, Vulkan). Use the CompositorPassComputeDef

Parameters

slotIdx	See setNumTexUnits. The slot index to bind this texture buffer In OpenGL, a few cards support between to 16-18 texture units, while most cards support up to 32
texBuffer	Texture buffer to bind.
offset	0-based offset. It is possible to bind a region of the buffer. Offset needs to be aligned. You can query the RS capabilities for the alignment, however 256 bytes is the maximum allowed alignment per the OpenGL specification, making it a safe bet to hardcode.
sizeBytes	Size in bytes to bind the tex buffer. When zero, binds from offset until the end of the buffer.

setTexture()

void Ogre::HlmsComputeJob::setTexture	(	uint8	slotIdx,
		TexturePtr &	texture,
		const HlmsSamplerblock *	refParams = 0
	)

Sets a texture buffer at the given slot ID.

Remarks

Texture slots are shared with setTexBuffer's. Calling this function will remove the settings from previous setTexBuffer calls to the same slot index.

UAVs and Textures share the same slots in OpenGL, but don't in D3D11. For best compatibility, assume they're shared and put the UAVs in the first slots.

May trigger a recompilation if setInformHlmsOfTextureData is enabled.

Parameters

slotIdx	See setNumTexUnits. The slot index to bind this texture In OpenGL, some cards support up to 16-18 texture units, while most cards support up to 32
texBuffer	Texture buffer to bind.
texture	Texture to bind.
samplerblock	Optional. We'll create (or retrieve an existing) samplerblock based on the input parameters. When null, we leave the previously set samplerblock (if a texture is being set, and if no samplerblock was set, we'll create a default one)

setThreadsPerGroup()

void Ogre::HlmsComputeJob::setThreadsPerGroup	(	uint32	threadsPerGroupX,
		uint32	threadsPerGroupY,
		uint32	threadsPerGroupZ
	)

Sets the number of threads per group.

Note the actual value may be changed by the shader template using the @pset() function. These values are passed to the template as: threads_per_group_x threads_per_group_y threads_per_group_z

Remarks

May trigger a recompilation if the value changes, regardless of what setInformHlmsOfTextureData says. There may be API / HW limitations on the max values for each dimension.

Friends And Related Symbol Documentation

HlmsCompute

friend class HlmsCompute

friend

---

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

• OgreHlmsComputeJob.h