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 HlmsBlendblock *	getBlendblock (const HlmsBlendblock &baseParams)
	See HlmsManager::getMacroblock. More...

HlmsCompute *	getComputeHlms ()

HlmsDatablock *	getDatablock (IdString name) const
	Retrieves an exisiting datablock (i.e. More...

HlmsDatablock *	getDatablockNoDefault (IdString name) const
	See getDatablock(). More...

const HlmsDatablockMap &	getDatablocks () const
	Returns all registered datablocks. More...

HlmsDatablock *	getDefaultDatablock () const
	Datablock to use when another datablock failed or none was specified. More...

const DescriptorSetSampler *	getDescriptorSetSampler (const DescriptorSetSampler &baseParams)

const DescriptorSetTexture *	getDescriptorSetTexture (const DescriptorSetTexture &baseParams)

const DescriptorSetTexture2 *	getDescriptorSetTexture2 (const DescriptorSetTexture2 &baseParams)

const DescriptorSetUav *	getDescriptorSetUav (const DescriptorSetUav &baseParams)

Hlms *	getHlms (HlmsTypes type)
	Returns a registered HLMS based on type. May be null. More...

Hlms *	getHlms (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 HlmsMacroblock *	getMacroblock (const HlmsMacroblock &baseParams)
	Creates a macroblock that matches the same parameter as the input. More...

HlmsDatablock *	getMaterial (IdString name) const
	Alias function. More...

RenderSystem *	getRenderSystem () const

const HlmsSamplerblock *	getSamplerblock (HlmsSamplerblock baseParams)
	See getMacroblock(). More...

const StringVector &	getScriptPatterns () 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

HlmsJsonListener *	mJsonListener

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

typedef std::map<IdString, HlmsDatablock *> Ogre::HlmsManager::HlmsDatablockMap

◆ ResourceToTexExtensionMap

typedef map<String, String>::type Ogre::HlmsManager::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 )

See also: destroyMacroblock

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

See also: destroyMacroblock

◆ 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

name	Unique 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

baseParams A 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

stream	Weak reference to a data stream which is the source of the script
groupName	The 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

provider	The HLMS provider being registered.
deleteOnExit	True 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

datablock	Datablock/Material to save
filename	Valid 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

hlmsType	Hlms type. The type must be registered, otherwise it may crash.
filename	Valid file path.
sortByName	Use 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:

OgreHlmsManager.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ BlockIdxVec

◆ HlmsDatablockMap

◆ ResourceToTexExtensionMap

Constructor & Destructor Documentation

◆ HlmsManager()

◆ ~HlmsManager()

Member Function Documentation

◆ _changeRenderSystem()

◆ _datablockAdded()

◆ _datablockDestroyed()

◆ _getActiveBlocksIndices()

◆ _getBlendblock()

◆ _getBlocks()

◆ _getInputLayoutId()

◆ _getMacroblock()

◆ _getSamplerblock()

◆ addReference()

◆ destroyBlendblock()

◆ destroyDescriptorSetSampler()

◆ destroyDescriptorSetTexture()

◆ destroyDescriptorSetTexture2()

◆ destroyDescriptorSetUav()

◆ destroyMacroblock()

◆ destroySamplerblock()

◆ getBlendblock()

◆ getComputeHlms()

◆ getDatablock()

◆ getDatablockNoDefault()

◆ getDatablocks()

◆ getDefaultDatablock()

◆ getDescriptorSetSampler()

◆ getDescriptorSetTexture()

◆ getDescriptorSetTexture2()

◆ getDescriptorSetUav()

◆ getHlms() [1/2]

◆ getHlms() [2/2]

◆ getLoadingOrder()

◆ getMacroblock()

◆ getMaterial()

◆ getRenderSystem()

◆ getSamplerblock()

◆ getScriptPatterns()

◆ loadMaterials()

◆ parseScript()

◆ registerComputeHlms()

◆ registerHlms()

◆ saveMaterial()

◆ saveMaterials()

◆ unregisterComputeHlms()

◆ unregisterHlms()

◆ useDefaultDatablockFrom()

Member Data Documentation

◆ mAdditionalTextureExtensionsPerGroup

◆ mJsonListener