OGRE-Next  3.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::HlmsListener Class Reference

Listener that can be hooked to an Hlms implementation for extending it with custom code. More...

#include <OgreHlmsListener.h>

Public Member Functions

virtual uint16 getNumExtraPassTextures (const HlmsPropertyVec &properties, bool casterPass) const
 If hlmsTypeChanged is going to be binding extra textures, override this function to tell us how many textures you will use, so that we don't use those slots. More...
 
virtual uint32 getPassBufferSize (const CompositorShadowNode *shadowNode, bool casterPass, bool dualParaboloid, SceneManager *sceneManager) const
 Listeners should return the number of extra bytes they wish to allocate for storing additional data in the pass buffer. More...
 
virtual void hlmsTypeChanged (bool casterPass, CommandBuffer *commandBuffer, const HlmsDatablock *datablock, size_t texUnit)
 Called when the last Renderable processed was of a different Hlms type, thus we need to rebind certain buffers (like the pass buffer). More...
 
virtual float * preparePassBuffer (const CompositorShadowNode *shadowNode, bool casterPass, bool dualParaboloid, SceneManager *sceneManager, float *passBufferPtr)
 Write additional data in the pass buffer. More...
 
virtual void preparePassHash (const CompositorShadowNode *shadowNode, bool casterPass, bool dualParaboloid, SceneManager *sceneManager, Hlms *hlms)
 Called right before creating the pass cache, to allow the listener to add/remove properties. More...
 
virtual void propertiesMergedPreGenerationStep (Hlms *hlms, const HlmsCache &passCache, const HlmsPropertyVec &renderableCacheProperties, const PiecesMap renderableCachePieces[NumShaderTypes], const HlmsPropertyVec &properties, const QueuedRenderable &queuedRenderable)
 Similar to HlmsListener::shaderCacheEntryCreated, but it gets called before creating any shader. More...
 
virtual void setupRootLayout (RootLayout &rootLayout, const HlmsPropertyVec &properties) const
 Called right before compiling. More...
 
virtual void shaderCacheEntryCreated (const String &shaderProfile, const HlmsCache *hlmsCacheEntry, const HlmsCache &passCache, const HlmsPropertyVec &properties, const QueuedRenderable &queuedRenderable)
 Called after the shader was created/compiled, and right before bindGpuProgramParameters (relevant information for OpenGL programs). More...
 

Detailed Description

Listener that can be hooked to an Hlms implementation for extending it with custom code.

See "8.6.5 Customizing an existing implementation" of the 2.x manual on the different approaches to customizing Hlms implementations.

Remarks
For performance reasons, the listener interface does not allow you to add customizations that work per Renderable, as that loop is performance sensitive. The only listener callback that works inside Hlms::fillBuffersFor is hlmsTypeChanged which only gets evaluated when the previous Renderable used a different Hlms implementation; which is rare, and since we sort the RenderQueue, it often branch predicts well.

Member Function Documentation

◆ getNumExtraPassTextures()

virtual uint16 Ogre::HlmsListener::getNumExtraPassTextures ( const HlmsPropertyVec properties,
bool  casterPass 
) const
inlinevirtual

If hlmsTypeChanged is going to be binding extra textures, override this function to tell us how many textures you will use, so that we don't use those slots.

Remarks
Given the same set of properties, the function must always return the same value. Otherwise caching (i.e. HlmsDiskCache) won't work correctly

◆ getPassBufferSize()

virtual uint32 Ogre::HlmsListener::getPassBufferSize ( const CompositorShadowNode shadowNode,
bool  casterPass,
bool  dualParaboloid,
SceneManager sceneManager 
) const
inlinevirtual

Listeners should return the number of extra bytes they wish to allocate for storing additional data in the pass buffer.

The actual data will be provided by a preparePassBuffer() override.

Returns
Number of bytes of additional pass buffer data to allocate. Must be a multiple of 16.

◆ hlmsTypeChanged()

virtual void Ogre::HlmsListener::hlmsTypeChanged ( bool  casterPass,
CommandBuffer commandBuffer,
const HlmsDatablock datablock,
size_t  texUnit 
)
inlinevirtual

Called when the last Renderable processed was of a different Hlms type, thus we need to rebind certain buffers (like the pass buffer).

You can use this moment to bind your own buffers.

◆ preparePassBuffer()

virtual float* Ogre::HlmsListener::preparePassBuffer ( const CompositorShadowNode shadowNode,
bool  casterPass,
bool  dualParaboloid,
SceneManager sceneManager,
float *  passBufferPtr 
)
inlinevirtual

Write additional data in the pass buffer.

Users can write to passBufferPtr. Implementations must ensure they make the buffer big enough via getPassBufferSize(). The passBufferPtr is already aligned to 16 bytes.

Returns
Pointer past the end of added data, aligned to 16 bytes. The difference between the result pointer and the input passBufferPtr must equal the value that you returned from getPassBufferSize().

◆ preparePassHash()

virtual void Ogre::HlmsListener::preparePassHash ( const CompositorShadowNode shadowNode,
bool  casterPass,
bool  dualParaboloid,
SceneManager sceneManager,
Hlms hlms 
)
inlinevirtual

Called right before creating the pass cache, to allow the listener to add/remove properties.

Remarks
For the rest of the parameters,
See also
Hlms::preparePassHash
Parameters
hlmsCaller Hlms; from which you can alter the properties using Hlms::setProperty

◆ propertiesMergedPreGenerationStep()

virtual void Ogre::HlmsListener::propertiesMergedPreGenerationStep ( Hlms hlms,
const HlmsCache passCache,
const HlmsPropertyVec renderableCacheProperties,
const PiecesMap  renderableCachePieces[NumShaderTypes],
const HlmsPropertyVec properties,
const QueuedRenderable queuedRenderable 
)
inlinevirtual

Similar to HlmsListener::shaderCacheEntryCreated, but it gets called before creating any shader.

The main difference is that there is no hlmsCacheEntry (because it hasn't been generated yet) and the properties are before they are transformed by the templates

propertiesMergedPreGenerationStep

Parameters
hlmsPointer to caller. WARNING: Note that any modified property WON'T BE CACHED. If you set a property based on external information, it will break caches.

You can only set new properties that are derived from existing properties e.g. c = a + b, which means caching a and b will always result in c being the same value

Parameters
passCacheProperties used by this pass
renderableCachePropertiesProperties assigned to the renderable
renderableCachePiecesPieces that can be inserted, belonging to the renderable. The PiecesMap pointer cannot be null
propertiesCombined properties of both renderableCacheProperties & passCache.setProperties
queuedRenderable

◆ setupRootLayout()

virtual void Ogre::HlmsListener::setupRootLayout ( RootLayout rootLayout,
const HlmsPropertyVec properties 
) const
inlinevirtual

Called right before compiling.

If customizations require additional resources slots (e.g. more textures) then this function should modify the root layout accordingly

To allow caches to work, the rootLayout must only be generated from values in 'properties' (or via constant modifications) otherwise there is no guarantee a cached version can recreate the same state.

This is why the function is marked const.

Parameters
rootLayoutAn already-filled rootLayout derived classes can modify
propertiesThe current contents of Hlms::mSetProperties

◆ shaderCacheEntryCreated()

virtual void Ogre::HlmsListener::shaderCacheEntryCreated ( const String shaderProfile,
const HlmsCache hlmsCacheEntry,
const HlmsCache passCache,
const HlmsPropertyVec properties,
const QueuedRenderable queuedRenderable 
)
inlinevirtual

Called after the shader was created/compiled, and right before bindGpuProgramParameters (relevant information for OpenGL programs).

Parameters
shaderProfile
See also
Hlms::mShaderProfile
Parameters
hlmsCacheEntryThe created shader.
passCache
See also
Hlms::createShaderCacheEntry
Parameters
propertiesThe current contents of Hlms::mSetProperties
queuedRenderable
See also
Hlms::createShaderCacheEntry

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