Ogre::PsoCacheHelper Class Reference

Utility class to cache PSOs. More...

#include <OgrePsoCacheHelper.h>

Inheritance diagram for Ogre::PsoCacheHelper:

Public Member Functions
	PsoCacheHelper (RenderSystem *renderSystem)
	~PsoCacheHelper ()
void	clearState ()
HlmsPso *	getPso ()
	Returns an HlmsPso you can set via renderSystem->_setPipelineStateObject based on all past calls to setRenderTarget + setVertexFormat + setMacroblock + etc. More...
HlmsPso *	getPso (uint32 renderableHash, bool renderableCacheAlreadySet=false)
	Returns an HlmsPso you can set via renderSystem->_setPipelineStateObject based on the input hash calculated via getRenderableHash. More...
uint32	getRenderableHash ()
	Returns a hash value you can cache into a Renderable (or whatever you're rendering). More...
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 More...
void *	operator new (size_t sz, void *ptr)
	placement operator new More...
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 More...
void	setBlendblock (const HlmsBlendblock *blendblock)
	Calls to this function cannot be skipped unless you have a renderableHash. More...
void	setMacroblock (const HlmsMacroblock *macroblock)
	Calls to this function cannot be skipped unless you have a renderableHash. More...
void	setPixelShader (GpuProgramPtr &shader)
	Calls to this function can be skipped if it's valid to not have a shader set at this stage, or if you have a renderableHash. More...
void	setRenderTarget (const RenderPassDescriptor *renderPassDesc)
	You must call this function every frame, and every time the RenderTarget changes. More...
void	setVertexFormat (const VertexElement2VecVec &vertexElements, OperationType operationType, bool enablePrimitiveRestart)
	This function can be skipped if no vertex buffer is used (e.g. More...
void	setVertexShader (GpuProgramPtr &shader)
	Calls to this function can be skipped if it's valid to not have a shader set at this stage, or if you have a renderableHash. More...

Detailed Description

Utility class to cache PSOs.

Useful for porting v1 libraries (eg. Gorilla) that render in "immediate mode" style and weren't build with PSOs in mind. Ideally a PSO would be created ahead of time and its pointer stored alongside the renderable you need to render.

Almost all functions already do redundant state checking unless explicitly stated, thus there is no need for you to do it yourself.

Usage (example) "OK": PsoCacheHelper psoCache( renderSystem ); //Save this variable (i.e. per class)

void render() { psoCache.clearState(); psoCache.setRenderTarget( renderTarget ); for( int i=0; i<numMaterials; ++i ) { psoCache.setMacroblock( material[i].macroblock ); psoCache.setBlendblock( material[i].blendblock ); psoCache.setVertexShader( material[i].vertexShader ); psoCache.setPixelShader( material[i].pixelShader ); for( int j=0; j<numThingsToRenderPerMaterial; ++j ) { v1::RenderOperation renderOp = renderables[j].renderOp; Consider caching 'vertexElements' somewhere as convertToV2 involves allocations VertexElement2VecVec vertexElements = renderOp.vertexData-> vertexDeclaration->convertToV2(); psoCache.setVertexFormat( vertexElements, renderOp.operationType, enablePrimitiveRestart );

HlmsPso *pso = psoCache.getPso(); renderSystem->_setPipelineStateObject( pso ); } } }

Usage "MUCH better": PsoCacheHelper psoCache( renderSystem ); //Save this variable (i.e. per class)

Outside rendering, just ONCE at loading time or when the material changes (or the vertex layout changes): psoCache.clearState(); psoCache.setMacroblock( material[i].macroblock ); psoCache.setBlendblock( material[i].blendblock ); psoCache.setVertexShader( material[i].vertexShader ); psoCache.setPixelShader( material[i].pixelShader ); for( int j=0; j<numThingsToRenderPerMaterial; ++j ) { v1::RenderOperation renderOp = renderables[j].renderOp; Consider caching 'vertexElements' somewhere as convertToV2 involves allocations VertexElement2VecVec vertexElements = renderOp.vertexData-> vertexDeclaration->convertToV2(); psoCache.setVertexFormat( vertexElements, renderOp.operationType, enablePrimitiveRestart );

renderables[j].customSavedValue = psoCache.getRenderableHash(); }

During render: void render() { psoCache.clearState(); setRenderTarget still needs to be called. psoCache.setRenderTarget( renderTarget ); for( int i=0; i<numMaterials; ++i ) { for( int j=0; j<numThingsToRenderPerMaterial; ++j ) { HlmsPso *pso = psoCache.getPso( renderables[j].customSavedValue ); renderSystem->_setPipelineStateObject( pso ); } } }

Constructor & Destructor Documentation

PsoCacheHelper()

Ogre::PsoCacheHelper::PsoCacheHelper

(

RenderSystem *

renderSystem

)

~PsoCacheHelper()

Ogre::PsoCacheHelper::~PsoCacheHelper

(

)

Member Function Documentation

clearState()

void Ogre::PsoCacheHelper::clearState

(

)

getPso() [1/2]

HlmsPso* Ogre::PsoCacheHelper::getPso

(

)

Returns an HlmsPso you can set via renderSystem->_setPipelineStateObject based on all past calls to setRenderTarget + setVertexFormat + setMacroblock + etc.

Use this version if for architecture reasons (i.e. legacy code, time constraints) you can't store the hash at loading time into the Renderable for later reuse.

Returns

The HlmsPso to use. Do NOT persistently store this pointer. It may be invalidated if the next getPso call needs to create a new PSO.

getPso() [2/2]

HlmsPso* Ogre::PsoCacheHelper::getPso	(	uint32	renderableHash,
		bool	renderableCacheAlreadySet = false
	)

Returns an HlmsPso you can set via renderSystem->_setPipelineStateObject based on the input hash calculated via getRenderableHash.

Remarks

Don't call getRenderableHash for every object every frame and then this function. That's inefficient. If you can't save the hash at loading time / when materials are set, just call the other getPso overload directly.

Parameters

renderableHash	The hash obtained from getRenderableHash which you should've saved in the Renderable.
renderableCacheAlreadySet	Internal parameter. Leave the default. Used by the other getPso overload to tell there is no need to perform a linear O(N) search in mRenderableCache because mCurrentState is up to date (this search only happens if the PSO hadn't been already cached).

Returns

The HlmsPso to use. Do NOT persistently store this pointer. It may be invalidated if the next getPso call needs to create a new PSO.

getRenderableHash()

uint32 Ogre::PsoCacheHelper::getRenderableHash

(

)

Returns a hash value you can cache into a Renderable (or whatever you're rendering).

This hash will contain VertexFormat, Macroblock, Blendblock information and shaders set, but nothing that is part of the pass (RenderTargets attached, RTT formats, stencil parameters, etc). You would later insert this value to getPso( renderableHash ); See examples in the class description.

Remarks

The hash is deterministic, but depends on the order in which they're created. The hash is immune to collisions (unless you overflow 2^RenderableBits).

Do NOT call this function every frame per object. The goal is that you only call this function when the object is being loaded (i.e. once) or when the object has changed (e.g. new material, vertex definition information was changed).

If you can't perform this optimization, just set every state for every object every frame (like in the first example) and call getPso.

Returns

The hash containing all the information.

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

setBlendblock()

void Ogre::PsoCacheHelper::setBlendblock

(

const HlmsBlendblock *

blendblock

)

Calls to this function cannot be skipped unless you have a renderableHash.

setMacroblock()

void Ogre::PsoCacheHelper::setMacroblock

(

const HlmsMacroblock *

macroblock

)

Calls to this function cannot be skipped unless you have a renderableHash.

setPixelShader()

void Ogre::PsoCacheHelper::setPixelShader

(

GpuProgramPtr &

shader

)

Calls to this function can be skipped if it's valid to not have a shader set at this stage, or if you have a renderableHash.

setRenderTarget()

void Ogre::PsoCacheHelper::setRenderTarget

(

const RenderPassDescriptor *

renderPassDesc

)

You must call this function every frame, and every time the RenderTarget changes.

Remarks

Warning: This function will not check for redundant state changes (there's a lot that could've changed: stencil settings, depth buffer, etc)

This function is a PASS state changing function, and its information is not part of getRenderableHash.

setVertexFormat()

void Ogre::PsoCacheHelper::setVertexFormat	(	const VertexElement2VecVec &	vertexElements,
		OperationType	operationType,
		bool	enablePrimitiveRestart
	)

This function can be skipped if no vertex buffer is used (e.g.

you use gl_VertexID or other trickery) or if you have a renderableHash.

setVertexShader()

void Ogre::PsoCacheHelper::setVertexShader

(

GpuProgramPtr &

shader

)

Calls to this function can be skipped if it's valid to not have a shader set at this stage, or if you have a renderableHash.

---

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

• OgrePsoCacheHelper.h