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

HLMS stands for "High Level Material System". More...

#include <OgreHlmsManager.h>

+ Inheritance diagram for Ogre::HlmsManager:

Public Types

typedef vector< uint16 >::type BlockIdxVec
 
typedef std::map< IdString, HlmsDatablock * > HlmsDatablockMap
 
typedef map< String, String >::type ResourceToTexExtensionMap
 

Public Member Functions

 HlmsManager ()
 
 ~HlmsManager () override
 
void _changeRenderSystem (RenderSystem *newRs)
 
void _datablockAdded (HlmsDatablock *datablock)
 Internal function used by Hlms types to tell us a datablock has been created so that we can return it when the user calls getDatablock(). More...
 
void _datablockDestroyed (IdString name)
 Internal function to inform us that the datablock with the input name has been destroyed. More...
 
const BlockIdxVec_getActiveBlocksIndices (const HlmsBasicBlock &blockType) const
 Gets the indices of active blocks. More...
 
const HlmsBlendblock_getBlendblock (uint16 idx) const
 Gets a blendblock based on its index. More...
 
BasicBlock const *const * _getBlocks (const HlmsBasicBlock &blockType) const
 Gets all blocks of a given type. More...
 
uint16 _getInputLayoutId (const VertexElement2VecVec &vertexElements, OperationType opType)
 Always returns a unique ID for the given vertexElement / OperationType combination, necessary by Hlms to generate a unique PSO. More...
 
const HlmsMacroblock_getMacroblock (uint16 idx) const
 Gets a macroblock based on its index. More...
 
const HlmsSamplerblock_getSamplerblock (uint16 idx) const
 Gets a samplerblock based on its index. More...
 
void addReference (const BasicBlock *block)
 Increments the reference count for the block, despite being const. More...
 
void destroyBlendblock (const HlmsBlendblock *Blendblock)
 
void destroyDescriptorSetSampler (const DescriptorSetSampler *descSet)
 
void destroyDescriptorSetTexture (const DescriptorSetTexture *descSet)
 
void destroyDescriptorSetTexture2 (const DescriptorSetTexture2 *descSet)
 
void destroyDescriptorSetUav (const DescriptorSetUav *descSet)
 
void destroyMacroblock (const HlmsMacroblock *macroblock)
 Destroys a macroblock created by HlmsManager::getMacroblock. More...
 
void destroySamplerblock (const HlmsSamplerblock *Samplerblock)
 
const HlmsBlendblockgetBlendblock (const HlmsBlendblock &baseParams)
 See HlmsManager::getMacroblock. More...
 
HlmsComputegetComputeHlms ()
 
HlmsDatablockgetDatablock (IdString name) const
 Retrieves an exisiting datablock (i.e. More...
 
HlmsDatablockgetDatablockNoDefault (IdString name) const
 See getDatablock(). More...
 
const HlmsDatablockMapgetDatablocks () const
 Returns all registered datablocks. More...
 
HlmsDatablockgetDefaultDatablock () const
 Datablock to use when another datablock failed or none was specified. More...
 
const DescriptorSetSamplergetDescriptorSetSampler (const DescriptorSetSampler &baseParams)
 
const DescriptorSetTexturegetDescriptorSetTexture (const DescriptorSetTexture &baseParams)
 
const DescriptorSetTexture2getDescriptorSetTexture2 (const DescriptorSetTexture2 &baseParams)
 
const DescriptorSetUavgetDescriptorSetUav (const DescriptorSetUav &baseParams)
 
HlmsgetHlms (HlmsTypes type)
 Returns a registered HLMS based on type. May be null. More...
 
HlmsgetHlms (IdString name)
 Returns a registered HLMS based on name. May be null. More...
 
Real getLoadingOrder () const override
 Gets the relative loading order of scripts of this type. More...
 
const HlmsMacroblockgetMacroblock (const HlmsMacroblock &baseParams)
 Creates a macroblock that matches the same parameter as the input. More...
 
HlmsDatablockgetMaterial (IdString name) const
 Alias function. More...
 
RenderSystemgetRenderSystem () const
 
const HlmsSamplerblockgetSamplerblock (HlmsSamplerblock baseParams)
 See getMacroblock(). More...
 
const StringVectorgetScriptPatterns () const override
 Gets the file patterns which should be used to find scripts for this class. More...
 
void loadMaterials (const String &filename, const String &groupName, HlmsJsonListener *listener, const String &additionalTextureExtension)
 Opens a file containing a JSON string to load all Hlms materials from. More...
 
void parseScript (DataStreamPtr &stream, const String &groupName) override
 Parse a script file. More...
 
void registerComputeHlms (HlmsCompute *provider)
 
void registerHlms (Hlms *provider, bool deleteOnExit=true)
 Registers an HLMS provider. More...
 
void saveMaterial (const HlmsDatablock *datablock, const String &filename, HlmsJsonListener *listener, const String &additionalTextureExtension)
 Saves a specific Hlms material at the given file location. More...
 
void saveMaterials (HlmsTypes hlmsType, const String &filename, HlmsJsonListener *listener, const String &additionalTextureExtension, bool sortByName=false)
 Saves all materials of the registered Hlms at the given file location. More...
 
void unregisterComputeHlms ()
 
void unregisterHlms (HlmsTypes type)
 Unregisters an HLMS provider of the given type. More...
 
void useDefaultDatablockFrom (HlmsTypes type)
 
- Public Member Functions inherited from Ogre::ScriptLoader
virtual ~ScriptLoader ()
 

Public Attributes

ResourceToTexExtensionMap mAdditionalTextureExtensionsPerGroup
 
HlmsJsonListenermJsonListener
 

Detailed Description

HLMS stands for "High Level Material System".

HlmsMacroblock & HlmsBlendblock pointers are never recycled when their reference counts reach 0. This allows us to better cache PSOs instead of destroying them every time materials are destroyed.

A user can only create up to OGRE_HLMS_MAX_LIFETIME_MACROBLOCKS & OGRE_HLMS_MAX_LIFETIME_BLENDBLOCKS. If for some reason you need more, increase these values (they're macros) and recompile Ogre

Member Typedef Documentation

◆ BlockIdxVec

typedef vector<uint16>::type Ogre::HlmsManager::BlockIdxVec

◆ HlmsDatablockMap

◆ ResourceToTexExtensionMap

Constructor & Destructor Documentation

◆ HlmsManager()

Ogre::HlmsManager::HlmsManager ( )

◆ ~HlmsManager()

Ogre::HlmsManager::~HlmsManager ( )
override

Member Function Documentation

◆ _changeRenderSystem()

void Ogre::HlmsManager::_changeRenderSystem ( RenderSystem newRs)

◆ _datablockAdded()

void Ogre::HlmsManager::_datablockAdded ( HlmsDatablock datablock)

Internal function used by Hlms types to tell us a datablock has been created so that we can return it when the user calls getDatablock().

Remarks
Throws if a datablock with the same name has already been registered. Don't call this function directly unless you know what you're doing.

◆ _datablockDestroyed()

void Ogre::HlmsManager::_datablockDestroyed ( IdString  name)

Internal function to inform us that the datablock with the input name has been destroyed.

◆ _getActiveBlocksIndices()

const BlockIdxVec& Ogre::HlmsManager::_getActiveBlocksIndices ( const HlmsBasicBlock blockType) const

Gets the indices of active blocks.

See also
HlmsManager::_getBlocks

◆ _getBlendblock()

const HlmsBlendblock* Ogre::HlmsManager::_getBlendblock ( uint16  idx) const

Gets a blendblock based on its index.

See also
_getActiveBlocksIndices to get how which indices are active.
_getBlocks to retrieve all types of block in a generic way.

◆ _getBlocks()

BasicBlock const* const* Ogre::HlmsManager::_getBlocks ( const HlmsBasicBlock blockType) const

Gets all blocks of a given type.

This is an advanced function useful in retrieving all the Macroblocks, all the Blendblocks, and all the Samplerblocks currently in use. Example: Get all macroblocks: const BlockIdxVec &activeMacroblockIdx = mgr->_getActiveBlocksIndices( BLOCK_MACRO ); BasicBlock const * const macroblocks = mgr->_getBlocks( BLOCK_MACRO ); BlockIdxVec::const_iterator itor = activeMacroblockIdx.begin(); BlockIdxVec::const_iterator end = activeMacroblockIdx.end(); while( itor != end ) { const HlmsMacroblock *macroblock = static_cast<const HlmsMacroblock>( macroblocks[*itor] ); ++itor; }

◆ _getInputLayoutId()

uint16 Ogre::HlmsManager::_getInputLayoutId ( const VertexElement2VecVec vertexElements,
OperationType  opType 
)

Always returns a unique ID for the given vertexElement / OperationType combination, necessary by Hlms to generate a unique PSO.

We store the OperationType in the last 6 bits because of v1 reasons, since v1::VertexDeclaration does not store OperationType, thus it cannot cache beforehand, and calling this function from Hlms::calculateHashForV1 would make material asignment to SubEntity more expensive than it is.

That means there 10 bits left for vertexElements, and that's how many different vertex elements you can create (1024).

See also
v1::VertexDeclaration::_getInputLayoutId
Parameters
vertexElements
opType
Returns
The returned value is deterministic, however it depends on the order in which _getInputLayoutId is called.

◆ _getMacroblock()

const HlmsMacroblock* Ogre::HlmsManager::_getMacroblock ( uint16  idx) const

Gets a macroblock based on its index.

See also
_getActiveBlocksIndices to get how which indices are active.
_getBlocks to retrieve all types of block in a generic way.

◆ _getSamplerblock()

const HlmsSamplerblock* Ogre::HlmsManager::_getSamplerblock ( uint16  idx) const

Gets a samplerblock based on its index.

See also
_getActiveBlocksIndices to get how which indices are active.
_getBlocks to retrieve all types of block in a generic way.

◆ addReference()

void Ogre::HlmsManager::addReference ( const BasicBlock block)

Increments the reference count for the block, despite being const.

◆ destroyBlendblock()

void Ogre::HlmsManager::destroyBlendblock ( const HlmsBlendblock Blendblock)

◆ destroyDescriptorSetSampler()

void Ogre::HlmsManager::destroyDescriptorSetSampler ( const DescriptorSetSampler descSet)

◆ destroyDescriptorSetTexture()

void Ogre::HlmsManager::destroyDescriptorSetTexture ( const DescriptorSetTexture descSet)

◆ destroyDescriptorSetTexture2()

void Ogre::HlmsManager::destroyDescriptorSetTexture2 ( const DescriptorSetTexture2 descSet)

◆ destroyDescriptorSetUav()

void Ogre::HlmsManager::destroyDescriptorSetUav ( const DescriptorSetUav descSet)

◆ destroyMacroblock()

void Ogre::HlmsManager::destroyMacroblock ( const HlmsMacroblock macroblock)

Destroys a macroblock created by HlmsManager::getMacroblock.

Blocks are manually reference counted and calling this function will decrease the count.

The internal object (BasicBlock::mRsData) will actually be destroyed when the count reaches 0; however the actual pointer is never deallocated throghout the lifetime of HlmsManager, it is only deactivated.

This guarantees caches of HlmsPso that once a Macroblock is created, its pointer always valid.

When count reaches 0, it will perform an O(N) search but N <= OGRE_HLMS_NUM_MACROBLOCKS

◆ destroySamplerblock()

void Ogre::HlmsManager::destroySamplerblock ( const HlmsSamplerblock Samplerblock)

◆ getBlendblock()

const HlmsBlendblock* Ogre::HlmsManager::getBlendblock ( const HlmsBlendblock baseParams)

See HlmsManager::getMacroblock.

This is the same for blend states The block's reference count will be increased. Use destroyBlendblock to decrease it.

◆ getComputeHlms()

HlmsCompute* Ogre::HlmsManager::getComputeHlms ( )
inline

◆ getDatablock()

HlmsDatablock* Ogre::HlmsManager::getDatablock ( IdString  name) const

Retrieves an exisiting datablock (i.e.

material) based on its name, regardless of which HLMS type it belongs to.

Remarks
If the datablock was created with the flag visibleByManager = false; you can't retrieve it using this function. If that's the case, get the appropiate Hlms using getHlms() and then call Hlms::getDatablock on it
If the material/datablock with that name wasn't found, returns a default one (note that Hlms::getDatablock doesn't do this!!!)
Parameters
nameUnique name of the datablock. Datablock names are unique within the same Hlms type. If two types create a datablock with the same name and both attempt to make it globally visible to this manager, we will throw on creation.
Returns
Pointer to the datablock

◆ getDatablockNoDefault()

HlmsDatablock* Ogre::HlmsManager::getDatablockNoDefault ( IdString  name) const

See getDatablock().

Exactly the same, but returns null pointer if it wasn't found, instead of going fallback to default.

◆ getDatablocks()

const HlmsDatablockMap& Ogre::HlmsManager::getDatablocks ( ) const
inline

Returns all registered datablocks.

See also
getDatablock,
_datablockAdded,
_datablockDestroyed

◆ getDefaultDatablock()

HlmsDatablock* Ogre::HlmsManager::getDefaultDatablock ( ) const

Datablock to use when another datablock failed or none was specified.

◆ getDescriptorSetSampler()

const DescriptorSetSampler* Ogre::HlmsManager::getDescriptorSetSampler ( const DescriptorSetSampler baseParams)

◆ getDescriptorSetTexture()

const DescriptorSetTexture* Ogre::HlmsManager::getDescriptorSetTexture ( const DescriptorSetTexture baseParams)

◆ getDescriptorSetTexture2()

const DescriptorSetTexture2* Ogre::HlmsManager::getDescriptorSetTexture2 ( const DescriptorSetTexture2 baseParams)

◆ getDescriptorSetUav()

const DescriptorSetUav* Ogre::HlmsManager::getDescriptorSetUav ( const DescriptorSetUav baseParams)

◆ getHlms() [1/2]

Hlms* Ogre::HlmsManager::getHlms ( HlmsTypes  type)
inline

Returns a registered HLMS based on type. May be null.

◆ getHlms() [2/2]

Hlms* Ogre::HlmsManager::getHlms ( IdString  name)

Returns a registered HLMS based on name. May be null.

◆ getLoadingOrder()

Real Ogre::HlmsManager::getLoadingOrder ( ) const
overridevirtual

Gets the relative loading order of scripts of this type.

Remarks
There are dependencies between some kinds of scripts, and to enforce this all implementors of this interface must define a loading order.
Returns
A value representing the relative loading order of these scripts compared to other script users, where higher values load later.

Implements Ogre::ScriptLoader.

◆ getMacroblock()

const HlmsMacroblock* Ogre::HlmsManager::getMacroblock ( const HlmsMacroblock baseParams)

Creates a macroblock that matches the same parameter as the input.

If it already exists, returns the existing one.

Macroblocks must be destroyed with destroyMacroblock. Don't try to delete the pointer directly.

Calling this function will increase the reference count of the block. Make sure to call destroyMacroblock after you're done using it; which will decrease the reference count (it won't be actually destroyed until the reference is 0).

Up to 32 different macroblocks are supported at the same time.

VERY IMPORTANT:

You can only create up to OGRE_HLMS_MAX_LIFETIME_MACROBLOCKS different macroblocks throghout the entire lifetime of HlmsManager, EVEN if you call destroyMacroblock on them, as we need to ensure caches of HlmsPso remain valid.

Parameters
baseParamsA macroblock reference to base the parameters. This reference may live on the stack, on the heap, etc; it's RS-specific data does not have to be filled. e.g. this is fine: HlmsMacroblock myRef; myRef.mDepthCheck = false; HlmsMacroblock *finalBlock = manager->getMacroblock( myRef ); myRef.mRsData == finalBlock.mRsData not necessarily true
Returns
Created or cached datablock with same parameters as baseParams

◆ getMaterial()

HlmsDatablock* Ogre::HlmsManager::getMaterial ( IdString  name) const
inline

Alias function.

See getDatablock(), as many beginners will probably think of the word "Material" first. Datablock is a more technical (and accurate) name of what it does (it's a block.. of data). Prefer calling getDatablock directly.

◆ getRenderSystem()

RenderSystem* Ogre::HlmsManager::getRenderSystem ( ) const
inline

◆ getSamplerblock()

const HlmsSamplerblock* Ogre::HlmsManager::getSamplerblock ( HlmsSamplerblock  baseParams)

See getMacroblock().

This is the same for Sampler states

Remarks
The block's reference count will be increased. Use destroySamplerblock to decrease it. The input is a hard copy because it may be modified if invalid parameters are detected (i.e. specifying anisotropic level higher than 1, but no anisotropic filter) A warning on the log will be generated in such cases.

◆ getScriptPatterns()

const StringVector& Ogre::HlmsManager::getScriptPatterns ( ) const
inlineoverridevirtual

Gets the file patterns which should be used to find scripts for this class.

Remarks
This method is called when a resource group is loaded if you use ResourceGroupManager::_registerScriptLoader.
Returns
A list of file patterns, in the order they should be searched in.

Implements Ogre::ScriptLoader.

◆ loadMaterials()

void Ogre::HlmsManager::loadMaterials ( const String filename,
const String groupName,
HlmsJsonListener listener,
const String additionalTextureExtension 
)

Opens a file containing a JSON string to load all Hlms materials from.

Remarks
You can do: HlmsJson hlmsJson( this ); const char *string = ...; hlmsJson.loadMaterials( "Filename for debug purposes", string ); To load materials from an arbitrary JSON string. See HlmsJson::loadMaterials
Parameters
filename
groupName

◆ parseScript()

void Ogre::HlmsManager::parseScript ( DataStreamPtr stream,
const String groupName 
)
overridevirtual

Parse a script file.

Parameters
streamWeak reference to a data stream which is the source of the script
groupNameThe name of a resource group which should be used if any resources are created during the parse of this script.

Implements Ogre::ScriptLoader.

◆ registerComputeHlms()

void Ogre::HlmsManager::registerComputeHlms ( HlmsCompute provider)

◆ registerHlms()

void Ogre::HlmsManager::registerHlms ( Hlms provider,
bool  deleteOnExit = true 
)

Registers an HLMS provider.

The type is retrieved from the provider. Two providers of the same type cannot be registered at the same time (

See also
HlmsTypes) and will throw an exception.
Parameters
providerThe HLMS provider being registered.
deleteOnExitTrue if we should delete the pointer using OGRE_DELETE when the provider is unregistered or when this manager is destroyed. Otherwise it's caller's responsability to free the pointer.

◆ saveMaterial()

void Ogre::HlmsManager::saveMaterial ( const HlmsDatablock datablock,
const String filename,
HlmsJsonListener listener,
const String additionalTextureExtension 
)

Saves a specific Hlms material at the given file location.

Parameters
datablockDatablock/Material to save
filenameValid file path.

◆ saveMaterials()

void Ogre::HlmsManager::saveMaterials ( HlmsTypes  hlmsType,
const String filename,
HlmsJsonListener listener,
const String additionalTextureExtension,
bool  sortByName = false 
)

Saves all materials of the registered Hlms at the given file location.

Parameters
hlmsTypeHlms type. The type must be registered, otherwise it may crash.
filenameValid file path.
sortByNameUse true if output JSON should have materials sorted alphabetically by name (case sensitive).

◆ unregisterComputeHlms()

void Ogre::HlmsManager::unregisterComputeHlms ( )

◆ unregisterHlms()

void Ogre::HlmsManager::unregisterHlms ( HlmsTypes  type)

Unregisters an HLMS provider of the given type.

Does nothing if no provider was registered. See registerHlms() for details.

◆ useDefaultDatablockFrom()

void Ogre::HlmsManager::useDefaultDatablockFrom ( HlmsTypes  type)
inline

Member Data Documentation

◆ mAdditionalTextureExtensionsPerGroup

ResourceToTexExtensionMap Ogre::HlmsManager::mAdditionalTextureExtensionsPerGroup

◆ mJsonListener

HlmsJsonListener* Ogre::HlmsManager::mJsonListener

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