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

virtual	~HlmsManager ()

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.

void	_datablockDestroyed (IdString name)
	Internal function to inform us that the datablock with the input name has been destroyed.

const BlockIdxVec &	_getActiveBlocksIndices (const HlmsBasicBlock &blockType) const
	Gets the indices of active blocks.

const HlmsBlendblock *	_getBlendblock (uint16 idx) const
	Gets a blendblock based on its index.

BasicBlock const const	_getBlocks (const HlmsBasicBlock &blockType) const
	Gets all blocks of a given type.

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.

const HlmsMacroblock *	_getMacroblock (uint16 idx) const
	Gets a macroblock based on its index.

const HlmsSamplerblock *	_getSamplerblock (uint16 idx) const
	Gets a samplerblock based on its index.

void	addReference (const BasicBlock *block)
	Increments the reference count for the block, despite being const.

void	destroyBlendblock (const HlmsBlendblock *Blendblock)

void	destroyMacroblock (const HlmsMacroblock *macroblock)
	Destroys a macroblock created by HlmsManager::getMacroblock.

void	destroySamplerblock (const HlmsSamplerblock *Samplerblock)
	@See destroyMacroblock

const HlmsBlendblock *	getBlendblock (const HlmsBlendblock &baseParams)
	See HlmsManager::getMacroblock.

HlmsCompute *	getComputeHlms (void)

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

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

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

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

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

Hlms *	getHlms (IdString name)
	Returns a registered HLMS based on name. May be null.

virtual Real	getLoadingOrder (void) const
	Gets the relative loading order of scripts of this type.

const HlmsMacroblock *	getMacroblock (const HlmsMacroblock &baseParams)
	Creates a macroblock that matches the same parameter as the input.

HlmsDatablock *	getMaterial (IdString name) const
	Alias function.

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

virtual const StringVector &	getScriptPatterns (void) const
	Gets the file patterns which should be used to find scripts for this class.

bool	getShadowMappingUseBackFaces (void)

HlmsTextureManager *	getTextureManager (void) const

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.

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

void *	operator new (size_t sz, void *ptr)
	placement operator new

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

virtual void	parseScript (DataStreamPtr &stream, const String &groupName)
	Parse a script file.

void	registerComputeHlms (HlmsCompute *provider)

void	registerHlms (Hlms *provider, bool deleteOnExit=true)
	Registers an HLMS provider.

void	saveMaterial (const HlmsDatablock datablock, const String &filename, HlmsJsonListener listener, const String &additionalTextureExtension)
	Saves a specific Hlms material at the given file location.

void	saveMaterials (HlmsTypes hlmsType, const String &filename, HlmsJsonListener *listener, const String &additionalTextureExtension)
	Saves all materials of the registered Hlms at the given file location.

void	setShadowMappingUseBackFaces (bool useBackFaces)
	Sets whether or not shadow casters should be rendered into shadow textures using their back faces rather than their front faces.

void	unregisterComputeHlms (void)

void	unregisterHlms (HlmsTypes type)
	Unregisters an HLMS provider of the given type.

void	useDefaultDatablockFrom (HlmsTypes type)

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

virtual Ogre::HlmsManager::~HlmsManager ( )

virtual

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

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

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 @HlmsgetDatablock 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 ( void ) const

inline

Returns all registered datablocks.

See also: getDatablock,; _datablockAdded,; _datablockDestroyed

◆ getDefaultDatablock()

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

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

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

virtual Real Ogre::HlmsManager::getLoadingOrder ( void ) const

virtual

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.

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

virtual const StringVector & Ogre::HlmsManager::getScriptPatterns ( void ) const

inlinevirtual

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.

◆ getShadowMappingUseBackFaces()

bool Ogre::HlmsManager::getShadowMappingUseBackFaces ( void )

inline

◆ getTextureManager()

HlmsTextureManager * Ogre::HlmsManager::getTextureManager ( void ) const

inline

◆ 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

◆ 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

◆ parseScript()

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

virtual

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
	)

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.

◆ setShadowMappingUseBackFaces()

void Ogre::HlmsManager::setShadowMappingUseBackFaces ( bool useBackFaces )

Sets whether or not shadow casters should be rendered into shadow textures using their back faces rather than their front faces.

Remarks: Rendering back faces rather than front faces into a shadow texture can help minimise depth comparison issues, if you're using depth shadowmapping. You will probably still need some biasing but you won't need as much. For solid objects the result is the same anyway, if you have objects with holes you may want to turn this option off. The default is to enable this option.

◆ unregisterComputeHlms()

void Ogre::HlmsManager::unregisterComputeHlms ( void )

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

◆ destroyMacroblock()

◆ destroySamplerblock()

◆ getBlendblock()

◆ getComputeHlms()

◆ getDatablock()

◆ getDatablockNoDefault()

◆ getDatablocks()

◆ getDefaultDatablock()

◆ getHlms() [1/2]

◆ getHlms() [2/2]

◆ getLoadingOrder()

◆ getMacroblock()

◆ getMaterial()

◆ getSamplerblock()

◆ getScriptPatterns()

◆ getShadowMappingUseBackFaces()

◆ getTextureManager()

◆ loadMaterials()

◆ operator delete() [1/3]

◆ operator delete() [2/3]

◆ operator delete() [3/3]

◆ operator delete[]() [1/2]

◆ operator delete[]() [2/2]

◆ operator new() [1/3]

◆ operator new() [2/3]

◆ operator new() [3/3]

◆ operator new[]() [1/2]

◆ operator new[]() [2/2]

◆ parseScript()

◆ registerComputeHlms()

◆ registerHlms()

◆ saveMaterial()

◆ saveMaterials()

◆ setShadowMappingUseBackFaces()

◆ unregisterComputeHlms()

◆ unregisterHlms()

◆ useDefaultDatablockFrom()

Member Data Documentation

◆ mAdditionalTextureExtensionsPerGroup

◆ mJsonListener