OGRE: Ogre::PsoCacheHelper Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Classes | Public Member Functions | List of all members
Ogre::PsoCacheHelper Class Reference
Core » Resources

Utility class to cache PSOs. More...

`#include <OgrePsoCacheHelper.h>`

Inheritance diagram for Ogre::PsoCacheHelper:
[legend]

## Public Member Functions
| PsoCacheHelper (RenderSystem *renderSystem)
| ~PsoCacheHelper ()
void | clearState (void)
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...
HlmsPso * | getPso (void)
| Returns an HlmsPso you can set via renderSystem->_setPipelineStateObject based on all past calls to setRenderTarget + setVertexFormat + setMacroblock + etc. More...
uint32 | getRenderableHash (void)
| 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 | ( | void |  | ) |

## ◆ getPso() [1/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.

## ◆ getPso() [2/2]

HlmsPso* Ogre::PsoCacheHelper::getPso | ( | void |  | ) |

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.

## ◆ getRenderableHash()

uint32 Ogre::PsoCacheHelper::getRenderableHash | ( | void |  | ) |

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