OGRE  2.2.4
Object-Oriented Graphics Rendering Engine
Ogre::HlmsComputeJob Class Reference

#include <OgreHlmsComputeJob.h>

+ Inheritance diagram for Ogre::HlmsComputeJob:

Public Types

enum  Reason {
  Unknown, FromStorageToSysRam, FromSysRamToStorage, GainedResidency,
  LostResidency, PoolTextureSlotChanged, ResidentToSysRamSync, MetadataCacheOutOfDate,
  ExceptionThrown, FsaaSettingAlteredByApi, ReadyForRendering, Deleted
}
 
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. More...
 
ShaderParams_getShaderParams (IdString key)
 Gets a shader parameter with the given key. More...
 
void _setSamplerblock (uint8 slotIdx, const HlmsSamplerblock *refParams)
 Sets a samplerblock directly. More...
 
void _setUavBuffer (uint8 slotIdx, const DescriptorSetUav::BufferSlot &newSlot)
 Sets an UAV buffer at the given slot ID. More...
 
void _setUavTexture (uint8 slotIdx, const DescriptorSetUav::TextureSlot &texSlot)
 Sets an UAV texture. More...
 
void _updateAutoProperties (void)
 
void clearTexBuffers (void)
 Sets all texture buffers to nullptr. More...
 
void clearUavBuffers (void)
 Sets all UAV buffers to nullptr. More...
 
HlmsComputeJobclone (const String &cloneName)
 
void cloneTo (HlmsComputeJob *dstJob)
 
void createShaderParams (IdString key)
 Creates a set of shader paramters with a given key, e.g. More...
 
HlmsgetCreator (void) const
 
IdString getName (void) const
 
String getNameStr (void) const
 
size_t getNumTexUnits (void) const
 
const uint32getNumThreadGroups (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
 
ShaderParamsgetShaderParams (IdString key)
 Gets a shader parameter with the given key. More...
 
TextureGpugetTexture (uint8 slotIdx) const
 
const uint32getThreadsPerGroup (void) const
 
uint32 getThreadsPerGroupX (void) const
 
uint32 getThreadsPerGroupY (void) const
 
uint32 getThreadsPerGroupZ (void) const
 
UavBufferPackedgetUavBuffer (uint8 slotIdx) const
 
TextureGpugetUavTexture (uint8 slotIdx) const
 
virtual void notifyTextureChanged (TextureGpu *texture, TextureGpuListener::Reason reason, void *extraData)
 Called when a TextureGpu changed in a way that affects how it is displayed: More...
 
void operator delete (void *ptr)
 
void operator delete (void *ptr, void *)
 
void operator delete (void *ptr, const char *, int, const char *)
 
void operator delete[] (void *ptr)
 
void operator delete[] (void *ptr, const char *, int, const char *)
 
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info More...
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
void * operator new[] (size_t sz)
 
void removePiece (IdString pieceName)
 Removes an existing piece. More...
 
void removeTexUnit (uint8 slotIdx)
 Destroys a given texture unit, displacing all the higher tex units. More...
 
void removeUavUnit (uint8 slotIdx)
 Destroys a given texture unit, displacing all the higher tex units. More...
 
void setConstBuffer (uint8 slotIdx, ConstBufferPacked *constBuffer)
 Sets a const/uniform bufferat the given slot ID. More...
 
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. More...
 
void setNumTexUnits (uint8 numSlots)
 Creates 'numSlots' number of slots before they can be set. More...
 
void setNumThreadGroups (uint32 numThreadGroupsX, uint32 numThreadGroupsY, uint32 numThreadGroupsZ)
 Sets the number of groups of threads to dispatch. More...
 
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. More...
 
void setNumUavUnits (uint8 numSlots)
 Creates 'numSlots' number of slots before they can be set. More...
 
void setPiece (IdString pieceName, const String &pieceContent)
 Defines a piece, i.e. More...
 
void setProperty (IdString key, int32 value)
 Sets an arbitrary property to pass to the shader. More...
 
void setSamplerblock (uint8 slotIdx, const HlmsSamplerblock &refParams)
 Sets a samplerblock based on reference parameters. More...
 
void setTexBuffer (uint8 slotIdx, const DescriptorSetTexture2::BufferSlot &newSlot)
 Sets a texture buffer at the given slot ID. More...
 
void setTexture (uint8 slotIdx, const DescriptorSetTexture2::TextureSlot &newSlot, const HlmsSamplerblock *refParams=0)
 Sets a texture buffer at the given slot ID. More...
 
void setThreadsPerGroup (uint32 threadsPerGroupX, uint32 threadsPerGroupY, uint32 threadsPerGroupZ)
 Sets the number of threads per group. More...
 
virtual bool shouldStayLoaded (TextureGpu *texture)
 Return true if this TextureGpu should likely stay loaded or else graphical changes could occur. More...
 

Friends

class HlmsCompute
 

Member Enumeration Documentation

◆ Reason

Enumerator
Unknown 
FromStorageToSysRam 

OnStorage -> OnSystemRam.

FromSysRamToStorage 

OnSystemRam -> OnStorage.

GainedResidency 

OnStorage -> Resident OnSystemRam -> Resident See ReadyForRendering.

LostResidency 

Resident -> OnStorage Resident -> OnSystemRam.

PoolTextureSlotChanged 
ResidentToSysRamSync 

Only called while TextureGpu is still Resident, and strategy is AlwaysKeepSystemRamCopy.

This listener happens when something was done to the TextureGpu that modifies its contents in the GPU, and were thus forced to sync those values back to SystemRam. This listener calls tells that sync is over.

MetadataCacheOutOfDate 

The Metadata cache was out of date and we had to do a ping-pong.

Expect this to be followed by at least LostResidency and GainedResidency calls

This is very important, because if you were expecting certain sequence of calls (e.g. you were expecting a LostResidency soon to arrive), expect that to be changed.

See TextureGpuManager for details about the metadata cache.

ExceptionThrown 

Called when the worker thread caught an exception.

This exception has already been logged, and the texture resumed loading normally with a white 2x2 RGBA8 fallback.

This listener will get called from the main thread.

The texture may still have pending residency transitions (e.g. it may still be loading the 2x2 fallback)

Cast Exception e = reinterpret_cast<Exception>( extraData ); to know more info

FsaaSettingAlteredByApi 

Requested FSAA (MSAA / CSAA / EQAA / etc) is not supported by the API, and thus the setting had to be downgraded.

Note this may happen on device lost, and a new GPU became in use; thus it's possible for a TextureGpu to initially support certain FSAA but later change.

ReadyForRendering 

This Reason is called when TextureGpu::notifyDataIsReady is called.

This normally means worker thread is done loading texture from file and uploading it to GPU; and can now be used for rendering. It does NOT mean that Ogre has finished issueing rendering commands to a RenderTexture and is now ready to be presented to the monitor.

Deleted 

◆ 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
slotIdxSee setNumTexUnits.
refParamsDirect samplerblock. Reference count is assumed to already have been increased. We won't increase it ourselves.
paramsThe sampler block to use as reference.

◆ _setUavBuffer()

void Ogre::HlmsComputeJob::_setUavBuffer ( uint8  slotIdx,
const DescriptorSetUav::BufferSlot newSlot 
)

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
slotIdxSee setNumUavUnits. The slot index to bind this UAV buffer.
newSlot

◆ _setUavTexture()

void Ogre::HlmsComputeJob::_setUavTexture ( uint8  slotIdx,
const DescriptorSetUav::TextureSlot texSlot 
)

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
slotSee setNumUavUnits.

◆ _updateAutoProperties()

void Ogre::HlmsComputeJob::_updateAutoProperties ( void  )

◆ clearTexBuffers()

void Ogre::HlmsComputeJob::clearTexBuffers ( void  )

Sets all texture buffers to nullptr.

◆ clearUavBuffers()

void Ogre::HlmsComputeJob::clearUavBuffers ( void  )

Sets all UAV buffers to nullptr.

◆ 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

◆ getNameStr()

String Ogre::HlmsComputeJob::getNameStr ( void  ) const

◆ 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()

TextureGpu* 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()

TextureGpu* Ogre::HlmsComputeJob::getUavTexture ( uint8  slotIdx) const

◆ notifyTextureChanged()

virtual void Ogre::HlmsComputeJob::notifyTextureChanged ( TextureGpu texture,
TextureGpuListener::Reason  reason,
void *  extraData 
)
virtual

Called when a TextureGpu changed in a way that affects how it is displayed:

  1. TextureGpu::notifyDataIsReady got called (texture is ready to be displayed)
  2. Texture changed residency status.
  3. Texture is being deleted. It won't be a valid pointer after this call.

Implements Ogre::TextureGpuListener.

◆ 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,
void *   
)
inlineinherited

◆ operator delete() [3/3]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
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,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

operator new, with debug line info

◆ operator new() [2/3]

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

◆ 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,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

array operator new, with debug line info

◆ operator new[]() [2/2]

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

◆ 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
slotIdxSlot to bind to. It's independent from the texture & UAV ones.
constBufferConst 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
bInformHlmsTrue 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 () 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
sourceWhat to use as source for the calculations. See ThreadGroupsBasedOn
texSlotIndex of the texture/uav unit.
divisorXdivisorY 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 ( pieceName )pieceContent 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
pieceNameName of the piece.
pieceContentThe 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
keyName of the property
valueValue to set

◆ setSamplerblock()

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

Sets a samplerblock based on reference parameters.

Parameters
slotIdxSee setNumTexUnits.
refParamsWe'll create (or retrieve an existing) samplerblock based on the input parameters.

◆ setTexBuffer()

void Ogre::HlmsComputeJob::setTexBuffer ( uint8  slotIdx,
const DescriptorSetTexture2::BufferSlot newSlot 
)

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
slotIdxSee 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
newSlot

◆ setTexture()

void Ogre::HlmsComputeJob::setTexture ( uint8  slotIdx,
const DescriptorSetTexture2::TextureSlot newSlot,
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
slotIdxSee 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
samplerblockOptional. 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 () 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.

◆ shouldStayLoaded()

virtual bool Ogre::TextureGpuListener::shouldStayLoaded ( TextureGpu texture)
inlinevirtualinherited

Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

Return false if it is certainly safe to unload.

Reimplemented in Ogre::VctLighting, and Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

Friends And Related Function Documentation

◆ HlmsCompute

friend class HlmsCompute
friend

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