OGRE-Next: Ogre::HlmsComputeJob Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
Ogre::HlmsComputeJob Class Reference
Component » Material

`#include <OgreHlmsComputeJob.h>`

Inheritance diagram for Ogre::HlmsComputeJob:
[legend]

## Public Types
enum | ThreadGroupsBasedOn { ThreadGroupsBasedOnNothing , ThreadGroupsBasedOnTexture , ThreadGroupsBasedOnUav }
Public Types inherited from Ogre::TextureGpuListener
enum | Reason { Unknown , FromStorageToSysRam , FromSysRamToStorage , GainedResidency , LostResidency , PoolTextureSlotChanged , ResidentToSysRamSync , MetadataCacheOutOfDate , ExceptionThrown , FsaaSettingAlteredByApi , ReadyForRendering , Deleted }

## Public Member Functions
| HlmsComputeJob (IdString name, Hlms *creator, const String &sourceFilename, const StringVector &includedPieceFiles)
| ~HlmsComputeJob () override
void | _calculateNumThreadGroupsBasedOnSetting ()
| INTERNAL USE.
uint8 | _getRawGlTexSlotStart () const
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, const DescriptorSetUav::BufferSlot &newSlot)
| Sets an UAV buffer at the given slot ID.
void | _setUavTexture (uint8 slotIdx, const DescriptorSetUav::TextureSlot &texSlot)
| Sets an UAV texture.
void | _updateAutoProperties ()
void | analyzeBarriers (ResourceTransitionArray &resourceTransitions, bool clearBarriers=true)
| Checks every regular texture and every UAV (texture and buffers) bound and resolves transitions.
void | clearTexBuffers ()
| Sets all texture buffers to nullptr.
void | clearUavBuffers ()
| Sets all UAV buffers to nullptr.
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 () const
uint8 | getGlTexSlotStart () const
IdString | getName () const
String | getNameStr () const
size_t | getNumSamplerUnits () const
| See setNumSamplerUnits.
size_t | getNumTexUnits () const
const uint32 * | getNumThreadGroups () const
uint32 | getNumThreadGroupsX () const
uint32 | getNumThreadGroupsY () const
uint32 | getNumThreadGroupsZ () const
size_t | getNumUavUnits () const
int32 | getProperty (IdString key, int32 defaultVal=0) const
ShaderParams & | getShaderParams (IdString key)
| Gets a shader parameter with the given key.
TextureGpu * | getTexture (uint8 slotIdx) const
const uint32 * | getThreadsPerGroup () const
uint32 | getThreadsPerGroupX () const
uint32 | getThreadsPerGroupY () const
uint32 | getThreadsPerGroupZ () const
UavBufferPacked * | getUavBuffer (uint8 slotIdx) const
TextureGpu * | getUavTexture (uint8 slotIdx) const
void | notifyTextureChanged (TextureGpu *texture, TextureGpuListener::Reason reason, void *extraData) override
| Called when a TextureGpu changed in a way that affects how it is displayed:
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 | setGlTexSlotStart (uint8 texSlotStart)
| By default HlmsComputeJob::setTexture and HlmsComputeJob::setTexBuffer are in range [0; getNumTexUnits)
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 | setNumSamplerUnits (uint8 numSlots)
| This value is overriden by setNumTexUnits to be compatible with OpenGL.
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, const DescriptorSetTexture2::BufferSlot &newSlot)
| Sets a texture buffer at the given slot ID.
void | setTexture (uint8 slotIdx, const DescriptorSetTexture2::TextureSlot &newSlot, const HlmsSamplerblock *refParams=0, bool bSetSampler=true)
| Sets a texture buffer at the given slot ID.
void | setThreadsPerGroup (uint32 threadsPerGroupX, uint32 threadsPerGroupY, uint32 threadsPerGroupZ)
| Sets the number of threads per group.
void | setupRootLayout (RootLayout &rootLayout)
Public Member Functions inherited from Ogre::TextureGpuListener
virtual | ~TextureGpuListener ()
virtual bool | shouldStayLoaded (TextureGpu *texture)
| Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

## 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 )

Referenced by clone(), and cloneTo().

## ◆ ~HlmsComputeJob()

Ogre::HlmsComputeJob::~HlmsComputeJob | ( |  | ) |
| override

## Member Function Documentation

## ◆ _calculateNumThreadGroupsBasedOnSetting()

void Ogre::HlmsComputeJob::_calculateNumThreadGroupsBasedOnSetting | ( |  | ) |

INTERNAL USE.

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

## ◆ _getRawGlTexSlotStart()

uint8 Ogre::HlmsComputeJob::_getRawGlTexSlotStart | ( |  | ) | const

## ◆ _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.

Must be in range [0; getNumTexUnits) regardless of what getTexSlotStart is

Parameters

  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,
|  | 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

  slotIdx | See 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

  slot | See setNumUavUnits.

## ◆ _updateAutoProperties()

void Ogre::HlmsComputeJob::_updateAutoProperties | ( |  | ) |

## ◆ analyzeBarriers()

void Ogre::HlmsComputeJob::analyzeBarriers | ( | ResourceTransitionArray & | resourceTransitions,
|  | bool | clearBarriers = true )

Checks every regular texture and every UAV (texture and buffers) bound and resolves transitions.

Parameters

  resourceTransitions |

## ◆ clearTexBuffers()

void Ogre::HlmsComputeJob::clearTexBuffers | ( |  | ) |

Sets all texture buffers to nullptr.

## ◆ clearUavBuffers()

void Ogre::HlmsComputeJob::clearUavBuffers | ( |  | ) |

Sets all UAV buffers to nullptr.

## ◆ clone()

HlmsComputeJob * Ogre::HlmsComputeJob::clone | ( | const String & | cloneName | ) |

References HlmsComputeJob().

## ◆ cloneTo()

void Ogre::HlmsComputeJob::cloneTo | ( | HlmsComputeJob * | dstJob | ) |

References HlmsComputeJob().

## ◆ 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 | ( |  | ) | const
| inline

## ◆ getGlTexSlotStart()

uint8 Ogre::HlmsComputeJob::getGlTexSlotStart | ( |  | ) | const

## ◆ getName()

IdString Ogre::HlmsComputeJob::getName | ( |  | ) | const
| inline

## ◆ getNameStr()

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

## ◆ getNumSamplerUnits()

size_t Ogre::HlmsComputeJob::getNumSamplerUnits | ( |  | ) | const
| inline

See setNumSamplerUnits.

## ◆ getNumTexUnits()

size_t Ogre::HlmsComputeJob::getNumTexUnits | ( |  | ) | const
| inline

## ◆ getNumThreadGroups()

const uint32 * Ogre::HlmsComputeJob::getNumThreadGroups | ( |  | ) | const
| inline

## ◆ getNumThreadGroupsX()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsX | ( |  | ) | const
| inline

## ◆ getNumThreadGroupsY()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsY | ( |  | ) | const
| inline

## ◆ getNumThreadGroupsZ()

uint32 Ogre::HlmsComputeJob::getNumThreadGroupsZ | ( |  | ) | const
| inline

## ◆ getNumUavUnits()

size_t Ogre::HlmsComputeJob::getNumUavUnits | ( |  | ) | 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 | ( |  | ) | const
| inline

## ◆ getThreadsPerGroupX()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupX | ( |  | ) | const
| inline

## ◆ getThreadsPerGroupY()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupY | ( |  | ) | const
| inline

## ◆ getThreadsPerGroupZ()

uint32 Ogre::HlmsComputeJob::getThreadsPerGroupZ | ( |  | ) | const
| inline

## ◆ getUavBuffer()

UavBufferPacked * Ogre::HlmsComputeJob::getUavBuffer | ( | uint8 | slotIdx | ) | const

## ◆ getUavTexture()

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

## ◆ notifyTextureChanged()

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

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.

## ◆ 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.

## ◆ setGlTexSlotStart()

void Ogre::HlmsComputeJob::setGlTexSlotStart | ( | uint8 | texSlotStart | ) |

By default HlmsComputeJob::setTexture and HlmsComputeJob::setTexBuffer are in range [0; getNumTexUnits)

However this allows you to offset the range to [texSlotStart; texSlotStart + getNumTexUnits)

This is useful when ReadOnlyBuffers are bound via setTexBuffers, because in OpenGL these will map to uav buffer slots, thus overlapping/conflicting with UAVs

Parameters

  texSlotStart | The offset at which the textures/texbuffers should start being bound

## ◆ 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.

## ◆ setNumSamplerUnits()

void Ogre::HlmsComputeJob::setNumSamplerUnits | ( | uint8 | numSlots | ) |

This value is overriden by setNumTexUnits to be compatible with OpenGL.

However you can later override this behavior to minimize the number of samplers by shrinking (or enlarging?) the sampler units.

This is an advanced function. Don't use it unless you're careful not to assume 1 tex unit = 1 sampler unit

## ◆ 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.

Must be in range [0; getNumTexUnits) regardless of what getTexSlotStart is

Parameters

  refParams | We'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

  ReadOnlyBufferPacked can be bound using this function. But please note in certain APIs these type of buffers may end up being bound to UAV slots already taken by _setUav* functions.

See HlmsComputeJob::setTexSlotStart to workaround that

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

Must be in range [0; getNumTexUnits) regardless of what getTexSlotStart is

Parameters

  newSlot |

## ◆ setTexture()

void Ogre::HlmsComputeJob::setTexture | ( | uint8 | slotIdx,
|  | const DescriptorSetTexture2::TextureSlot & | newSlot,
|  | const HlmsSamplerblock * | refParams = 0,
|  | bool | bSetSampler = true )

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

Must be in range [0; getNumTexUnits) regardless of what getTexSlotStart is

Parameters

  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)
  bSetSampler | If true, samplerblock will behave as described. When false and samplerblock is nullptr, we won't touch the samplerblock. Only use this with APIs that have separate texturse & sampler (e.g. everyone except GL)

## ◆ 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.

## ◆ setupRootLayout()

void Ogre::HlmsComputeJob::setupRootLayout | ( | RootLayout & | rootLayout | ) |

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

- OgreHlmsComputeJob.h