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

#include <OgreHlms.h>

Inheritance diagram for Ogre::Hlms:

Classes
struct	DatablockCustomPieceFile

struct	DatablockEntry

struct	Library

Public Types
enum	CachedCustomPieceFileStatus { CCPFS_Success , CCPFS_OutOfDate , CCPFS_CriticalError }

typedef std::map< int32, DatablockCustomPieceFile >	DatablockCustomPieceFileMap

typedef std::map< IdString, DatablockEntry >	HlmsDatablockMap

typedef vector< Library >::type	LibraryVec

enum	LightGatheringMode { LightGatherForward , LightGatherForwardPlus , LightGatherDeferred , LightGatherNone }

enum	PrecisionMode { PrecisionFull32 , PrecisionMidf16 , PrecisionRelaxed }

Public Member Functions
	Hlms (HlmsTypes type, const String &typeName, Archive dataFolder, ArchiveVec libraryFolders)

virtual	~Hlms ()

void	_addDatablockCustomPieceFile (const String &filename, const String &resourceGroup)
	See HlmsDatablock::setCustomPieceCodeFromMemory & HlmsDatablock::setCustomPieceFile. More...

CachedCustomPieceFileStatus	_addDatablockCustomPieceFile (const String &filename, const String &resourceGroup, const uint64 sourceCodeHash[2])

void	_addDatablockCustomPieceFileFromMemory (const String &filename, const String &sourceCode)

virtual void	_changeRenderSystem (RenderSystem *newRs)

void	_clearShaderCache ()

virtual void	_collectSamplerblocks (set< const HlmsSamplerblock * >::type &outSamplerblocks, const HlmsDatablock *datablock) const

void	_compileShaderFromPreprocessedSource (const RenderableCache &mergedCache, const String source[NumShaderTypes], const uint32 shaderCounter, size_t tid)

int32	_getProperty (size_t tid, IdString key, int32 defaultVal=0) const

virtual void	_loadJson (const rapidjson::Value &jsonValue, const HlmsJson::NamedBlocks &blocks, HlmsDatablock datablock, const String &resourceGroup, HlmsJsonListener listener, const String &additionalTextureExtension) const
	Loads datablock values from a JSON value. More...

void	_notifyManager (HlmsManager *manager)

virtual void	_saveJson (const HlmsDatablock datablock, String &outString, HlmsJsonListener listener, const String &additionalTextureExtension) const

void	_setNumThreads (size_t numThreads)

void	_setProperty (size_t tid, IdString key, int32 value)
	For debugging stuff. I.e. the Command line uses it for testing manually set properties. More...

void	_setShadersGenerated (uint32 shadersGenerated)

void	_setTextureReg (size_t tid, ShaderType shaderType, const char *texName, int32 texUnit)

void	_tagShaderCodeCacheUpToDate ()

virtual void	analyzeBarriers (BarrierSolver &barrierSolver, ResourceTransitionArray &resourceTransitions, Camera *renderingCamera, const bool bCasterPass)

virtual void	calculateHashFor (Renderable *renderable, uint32 &outHash, uint32 &outCasterHash)
	Called by the renderable when either it changes the material, or its properties change (e.g., the mesh's uvs are stripped) More...

void	compileShaderCode (ShaderCodeCache &codeCache, uint32 shaderCounter, size_t tid)
	Compiles input properties and adds it to the shader code cache. More...

void	compileStubEntry (const HlmsCache &passCache, HlmsCache *reservedStubEntry, QueuedRenderable queuedRenderable, uint32 renderableHash, uint32 finalHash, size_t tid)
	Called by ParallelHlmsCompileQueue to finish the job started in getMaterial() More...

HlmsDatablock *	createDatablock (IdString name, const String &refName, const HlmsMacroblock &macroblockRef, const HlmsBlendblock &blendblockRef, const HlmsParamVec &paramVec, bool visibleToManager=true, const String &filename=BLANKSTRING, const String &resourceGroup=BLANKSTRING)
	Creates a unique datablock that can be shared by multiple renderables. More...

void	destroyAllDatablocks ()
	Destroys all datablocks created with createDatablock(). More...

void	destroyDatablock (IdString name)
	Destroys a datablocks given its name. More...

virtual uint32	fillBuffersFor (const HlmsCache *cache, const QueuedRenderable &queuedRenderable, bool casterPass, uint32 lastCacheHash, uint32 lastTextureHash)=0
	Fills the constant buffers. More...

virtual uint32	fillBuffersForV1 (const HlmsCache cache, const QueuedRenderable &queuedRenderable, bool casterPass, uint32 lastCacheHash, CommandBuffer commandBuffer)=0

virtual uint32	fillBuffersForV2 (const HlmsCache cache, const QueuedRenderable &queuedRenderable, bool casterPass, uint32 lastCacheHash, CommandBuffer commandBuffer)=0

virtual void	frameEnded ()
	Called when the frame has fully ended (ALL passes have been executed to all RTTs) More...

uint16	getAreaLightsApproxLimit () const

uint16	getAreaLightsLtcLimit () const

HlmsDatablock *	getDatablock (IdString name) const
	Finds an existing datablock based on its name (. More...

const DatablockCustomPieceFile *	getDatablockCustomPieceData (int32 filenameHashId) const
	Returns all the data we know about filenameHashId. Can be nullptr if not found. More...

const String &	getDatablockCustomPieceFileNameStr (int32 filenameHashId) const

const HlmsDatablockMap &	getDatablockMap () const
	Returns all datablocks owned by this Hlms, including the default one. More...

Archive *	getDataFolder ()

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

bool	getFastShaderBuildHack () const
	Returns true if shaders are being compiled with Fast Shader Build Hack (D3D11 only) More...

void	getFilenameAndResourceGroup (IdString name, String const outFilename, String const outResourceGroup) const
	Returns the filaname & resource group a datablock was created from, and is associated with its hashed name (this was passed as in createDatablock()). More...

HlmsManager *	getHlmsManager () const

HlmsListener *	getListener () const
	Returns the current listener. More...

const HlmsCache *	getMaterial (HlmsCache const lastReturnedValue, const HlmsCache &passCache, const QueuedRenderable &queuedRenderable, bool casterPass, ParallelHlmsCompileQueue parallelQueue)
	Retrieves an HlmsCache filled with the GPU programs to be used by the given renderable. More...

uint32	getMaterialSerial01 (uint32 lastReturnedValue, const HlmsCache &passCache, const size_t passCacheIdx, const QueuedRenderable &queuedRenderable, bool casterPass, ParallelHlmsCompileQueue &parallelQueue)
	This is extremely similar to getMaterial() except it's been designed to be always in parallel and to be used by warm_up passes. More...

uint16	getMaxNonCasterDirectionalLights () const

const String *	getNameStr (IdString name) const
	Returns the string name associated with its hashed name (this was passed as refName in createDatablock()). More...

uint8	getParticleSystemConstSlot () const

uint8	getParticleSystemSlot () const

const LibraryVec &	getPiecesLibrary () const

ArchiveVec	getPiecesLibraryAsArchiveVec () const

PrecisionMode	getPrecisionMode () const
	Returns requested precision mode (i.e., value passed to setPrecisionMode) See getSupportedPrecisionMode. More...

RenderSystem *	getRenderSystem () const

const ShaderCodeCacheVec &	getShaderCodeCache () const

const String &	getShaderProfile () const

IdString	getShaderSyntax () const

bool	getStaticBranchingLights () const

PrecisionMode	getSupportedPrecisionMode () const
	Some GPUs don't support all precision modes. More...

void	getTemplateChecksum (uint64 outHash[2]) const

HlmsTypes	getType () const

IdString	getTypeName () const

const String &	getTypeNameStr () const

bool	isDatablockCustomPieceFileCacheable (int32 filenameHashId) const

bool	isShaderCodeCacheDirty () const
	Users can check this function to tell if HlmsDiskCache needs saving. More...

bool	parseOffline (const String &filename, String &inBuffer, String &outBuffer, size_t tid)
	For standalone parsing. More...

virtual void	postCommandBufferExecution (CommandBuffer *commandBuffer)
	This gets called after executing the command buffer. More...

virtual void	preCommandBufferExecution (CommandBuffer *commandBuffer)
	This gets called right before executing the command buffer. More...

virtual HlmsCache	preparePassHash (const Ogre::CompositorShadowNode shadowNode, bool casterPass, bool dualParaboloid, SceneManager sceneManager)
	Called every frame by the Render Queue to cache the properties needed by this pass. More...

virtual void	reloadFrom (Archive newDataFolder, ArchiveVec libraryFolders=0)
	Destroys all the cached shaders and in the next opportunity will recreate them from the new location. More...

void	saveAllTexturesFromDatablocks (const String &folderPath, set< String >::type &savedTextures, bool saveOitd, bool saveOriginal, HlmsTextureExportListener *listener)

void	setAreaLightForwardSettings (uint16 areaLightsApproxLimit, uint16 areaLightsLtcLimit)
	Area lights use regular Forward. More...

void	setDebugOutputPath (bool enableDebugOutput, bool outputProperties, const String &path=BLANKSTRING)
	Call to output the automatically generated shaders (which are usually made from templates) on the given folder for inspection, analyzing, debugging, etc. More...

void	setListener (HlmsListener *listener)
	Sets a listener to extend an existing Hlms implementation's with custom code, without having to rewrite it or modify the source code directly. More...

void	setMaxNonCasterDirectionalLights (uint16 maxLights)
	Non-caster directional lights are hardcoded into shaders. More...

void	setPrecisionMode (PrecisionMode precisionMode)
	Sets the precision mode of Hlms. More...

virtual void	setStaticBranchingLights (bool staticBranchingLights)
	By default shadow-caster spot and point lights are hardcoded into shaders. More...

Static Public Member Functions
static void	_setHasParticleFX2Plugin (bool bHasPfx2Plugin)

static bool	findParamInVec (const HlmsParamVec &paramVec, IdString key, String &inOut)
	Finds the parameter with key 'key' in the given 'paramVec'. More...

static int32	getProperty (const HlmsPropertyVec &properties, IdString key, int32 defaultVal=0)
	Utility helper, mostly useful to HlmsListener implementations. More...

static bool	hasParticleFX2Plugin ()

static void	setProperty (HlmsPropertyVec &properties, IdString key, int32 value)
	Utility helper, mostly useful to HlmsListener implementations. More...

Static Public Attributes
static constexpr size_t	kNoTid = 0u
	For single-threaded operations. More...

Detailed Description

HLMS stands for "High Level Material System".

The Hlms has multiple caches:

mRenderableCache This cache contains all the properties set to a Renderable class and can be evaluated early, when a Renderable is assigned a datablock i.e. inside Renderable::setDatablock. Contains properties such as whether the material has normal mapping, if the mesh has UV sets, evaluates if the material requires tangents for normal mapping, etc. The main function in charge of filling this cache is Hlms::calculateHashFor

mPassCache This cache contains per-pass information, such as how many lights are in the scene, whether this is a shadow mapping pass, etc. The main function in charge of filling this cache is Hlms::preparePassHash

mShaderCodeCache Contains a cache of unique shaders (from Hlms templates -> actual valid shader code) based on the properties merged from mRenderableCache & mPassCache. However it is possible that two shaders are exactly the same and thus be duplicated, this can happen if two combinations of properties end up producing the exact same code. The Microcode cache (GpuProgramManager::setSaveMicrocodesToCache) can help with that issue.

mShaderCache Contains a cache of the PSOs. The difference between this and mShaderCodeCache is that PSOs require additional information, such as HlmsMacroblock. HlmsBlendblock. For more information of all that is required, see HlmsPso

Member Typedef Documentation

◆ DatablockCustomPieceFileMap

typedef std::map<int32, DatablockCustomPieceFile> Ogre::Hlms::DatablockCustomPieceFileMap

◆ HlmsDatablockMap

typedef std::map<IdString, DatablockEntry> Ogre::Hlms::HlmsDatablockMap

◆ LibraryVec

typedef vector<Library>::type Ogre::Hlms::LibraryVec

Member Enumeration Documentation

◆ CachedCustomPieceFileStatus

enum Ogre::Hlms::CachedCustomPieceFileStatus

Enumerator
CCPFS_Success	Everything ok.
CCPFS_OutOfDate	Recompile the cache from the templates.
CCPFS_CriticalError	The cache contains unrecoverable errors. Do not use the cache.

◆ LightGatheringMode

enum Ogre::Hlms::LightGatheringMode

Enumerator
LightGatherForward
LightGatherForwardPlus
LightGatherDeferred
LightGatherNone

◆ PrecisionMode

enum Ogre::Hlms::PrecisionMode

Enumerator

PrecisionFull32

midf datatype maps to float (i.e., 32-bit) This setting is always supported

PrecisionMidf16

midf datatype maps to float16_t (i.e., forced 16-bit)

        It forces the driver to produce 16-bit code, even if unoptimal
        Great for testing quality downgrades caused by 16-bit support

        - This depends on RSC_SHADER_FLOAT16.
        - If unsupported, we fallback to PrecisionRelaxed (RSC_SHADER_RELAXED_FLOAT)
        - If unsupported, we then fallback to PrecisionFull32

PrecisionRelaxed

midf datatype maps to mediump float / min16float

        The driver is allowed to work in either 16-bit or 32-bit code

        - This depends on RSC_SHADER_RELAXED_FLOAT.
        - If unsupported, we fallback to PrecisionMidf16 (RSC_SHADER_FLOAT16)
        - If unsupported, we then fallback to PrecisionFull32

Constructor & Destructor Documentation

◆ Hlms()

Ogre::Hlms::Hlms	(	HlmsTypes	type,
		const String &	typeName,
		Archive *	dataFolder,
		ArchiveVec *	libraryFolders
	)

Parameters

libraryFolders Path to folders to be processed first for collecting pieces. Will be processed in order. Pointer can be null.

◆ ~Hlms()

virtual Ogre::Hlms::~Hlms ( )

virtual

Member Function Documentation

◆ _addDatablockCustomPieceFile() [1/2]

void Ogre::Hlms::_addDatablockCustomPieceFile	(	const String &	filename,
		const String &	resourceGroup
	)

See HlmsDatablock::setCustomPieceCodeFromMemory & HlmsDatablock::setCustomPieceFile.

Parameters

filename	Name of the file.
resourceGroup	The name of the resource group in which to look for the file.

◆ _addDatablockCustomPieceFile() [2/2]

CachedCustomPieceFileStatus Ogre::Hlms::_addDatablockCustomPieceFile	(	const String &	filename,
		const String &	resourceGroup,
		const uint64	sourceCodeHash[2]
	)

Parameters

filename	See _addDatablockCustomPieceFile() overload. Unlike the other overload, file not found errors are ignored.
resourceGroup	The name of the resource group in which to look for the file.
templateHash	The expected hash of the file. File won't be added if the hash does not match.

Returns: See CachedCustomPieceFileStatus.

◆ _addDatablockCustomPieceFileFromMemory()

void Ogre::Hlms::_addDatablockCustomPieceFileFromMemory	(	const String &	filename,
		const String &	sourceCode
	)

Parameters

filename	Name of the file.
sourceCode	The contents of the file.

◆ _changeRenderSystem()

virtual void Ogre::Hlms::_changeRenderSystem ( RenderSystem * newRs )

virtual

Reimplemented in Ogre::HlmsCompute, Ogre::HlmsUnlit, Ogre::HlmsPbs, and Ogre::HlmsBufferManager.

◆ _clearShaderCache()

void Ogre::Hlms::_clearShaderCache ( )

◆ _collectSamplerblocks()

virtual void Ogre::Hlms::_collectSamplerblocks	(	set< const HlmsSamplerblock * >::type &	outSamplerblocks,
		const HlmsDatablock *	datablock
	)		const

inlinevirtual

Reimplemented in Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ _compileShaderFromPreprocessedSource()

void Ogre::Hlms::_compileShaderFromPreprocessedSource	(	const RenderableCache &	mergedCache,
		const String	source[NumShaderTypes],
		const uint32	shaderCounter,
		size_t	tid
	)

◆ _getProperty()

int32 Ogre::Hlms::_getProperty	(	size_t	tid,
		IdString	key,
		int32	defaultVal = `0`
	)		const

inline

◆ _loadJson()

virtual void Ogre::Hlms::_loadJson	(	const rapidjson::Value &	jsonValue,
		const HlmsJson::NamedBlocks &	blocks,
		HlmsDatablock *	datablock,
		const String &	resourceGroup,
		HlmsJsonListener *	listener,
		const String &	additionalTextureExtension
	)		const

inlinevirtual

Loads datablock values from a JSON value.

See also: HlmsJson.

Parameters

jsonValue	JSON Object containing the definition of this datablock.
blocks	All the loaded Macro-, Blend- & Samplerblocks the JSON has defined and may be referenced by the datablock declaration.
datablock	Datablock to fill the values.

Reimplemented in Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ _notifyManager()

void Ogre::Hlms::_notifyManager ( HlmsManager * manager )

inline

◆ _saveJson()

virtual void Ogre::Hlms::_saveJson	(	const HlmsDatablock *	datablock,
		String &	outString,
		HlmsJsonListener *	listener,
		const String &	additionalTextureExtension
	)		const

inlinevirtual

Reimplemented in Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ _setHasParticleFX2Plugin()

static void Ogre::Hlms::_setHasParticleFX2Plugin ( bool bHasPfx2Plugin )

inlinestatic

◆ _setNumThreads()

void Ogre::Hlms::_setNumThreads ( size_t numThreads )

◆ _setProperty()

void Ogre::Hlms::_setProperty	(	size_t	tid,
		IdString	key,
		int32	value
	)

inline

For debugging stuff. I.e. the Command line uses it for testing manually set properties.

◆ _setShadersGenerated()

void Ogre::Hlms::_setShadersGenerated ( uint32 shadersGenerated )

◆ _setTextureReg()

void Ogre::Hlms::_setTextureReg	(	size_t	tid,
		ShaderType	shaderType,
		const char *	texName,
		int32	texUnit
	)

inline

◆ _tagShaderCodeCacheUpToDate()

void Ogre::Hlms::_tagShaderCodeCacheUpToDate ( )

inline

◆ analyzeBarriers()

virtual void Ogre::Hlms::analyzeBarriers	(	BarrierSolver &	barrierSolver,
		ResourceTransitionArray &	resourceTransitions,
		Camera *	renderingCamera,
		const bool	bCasterPass
	)

virtual

Reimplemented in Ogre::HlmsPbs.

◆ calculateHashFor()

virtual void Ogre::Hlms::calculateHashFor	(	Renderable *	renderable,
		uint32 &	outHash,
		uint32 &	outCasterHash
	)

virtual

Called by the renderable when either it changes the material, or its properties change (e.g., the mesh's uvs are stripped)

Parameters

renderable	The renderable the material will be used on.
outHash	A hash. This hash references property parameters that are already cached.

Reimplemented in Ogre::HlmsLowLevel.

◆ compileShaderCode()

void Ogre::Hlms::compileShaderCode	(	ShaderCodeCache &	codeCache,
		uint32	shaderCounter,
		size_t	tid
	)

Compiles input properties and adds it to the shader code cache.

Parameters

codeCache [in/out] All variables must be filled except for ShaderCodeCache::shaders which is the output

◆ compileStubEntry()

void Ogre::Hlms::compileStubEntry	(	const HlmsCache &	passCache,
		HlmsCache *	reservedStubEntry,
		QueuedRenderable	queuedRenderable,
		uint32	renderableHash,
		uint32	finalHash,
		size_t	tid
	)

Called by ParallelHlmsCompileQueue to finish the job started in getMaterial()

Parameters

passCache	See lastReturnedValue from getMaterial()
reservedStubEntry	The stub cache entry (return value of getMaterial()) to fill.
queuedRenderable	See getMaterial()
renderableHash
finalHash
tid	Thread idx of caller

◆ createDatablock()

HlmsDatablock* Ogre::Hlms::createDatablock	(	IdString	name,
		const String &	refName,
		const HlmsMacroblock &	macroblockRef,
		const HlmsBlendblock &	blendblockRef,
		const HlmsParamVec &	paramVec,
		bool	visibleToManager = `true`,
		const String &	filename = `BLANKSTRING`,
		const String &	resourceGroup = `BLANKSTRING`
	)

Creates a unique datablock that can be shared by multiple renderables.

Remarks: The name of the datablock must be in paramVec["name"] and must be unique Throws if a datablock with the same name paramVec["name"] already exists

Parameters

name	Name of the Datablock, must be unique within all Hlms types, not just this one. 99% you want this to be IdString( refName ); however this is not enforced.
refName	Name of the Datablock. The engine doesn't use this value at all. It is only useful for UI editors which want to enumerate all existing datablocks and display its name to the user.
macroblockRef	see HlmsManager::getMacroblock
blendblockRef	see HlmsManager::getBlendblock
paramVec	Key - String Value list of paramters. MUST BE SORTED.
visibleToManager	When false, HlmsManager::getDatablock won't find this datablock. True by default
filename	Filename in which it was defined, so that this information can be retrieved later by the user if needed. This is only for informational purposes.
resourceGroup	ResourceGroup. See filename param.

Returns: Pointer to created Datablock

◆ destroyAllDatablocks()

void Ogre::Hlms::destroyAllDatablocks ( )

Destroys all datablocks created with createDatablock().

Caller is responsible for ensuring those pointers aren't still in use (i.e. dangling pointers) The default datablock will be recreated.

◆ destroyDatablock()

void Ogre::Hlms::destroyDatablock ( IdString name )

Destroys a datablocks given its name.

Caller is responsible for ensuring those pointers aren't still in use (i.e. dangling pointers)

Remarks: Throws if no datablock with the given name exists.

◆ fillBuffersFor()

virtual uint32 Ogre::Hlms::fillBuffersFor	(	const HlmsCache *	cache,
		const QueuedRenderable &	queuedRenderable,
		bool	casterPass,
		uint32	lastCacheHash,
		uint32	lastTextureHash
	)

pure virtual

Fills the constant buffers.

Gets executed right before drawing the mesh.

Parameters

cache	Current cache of Shaders to be used.
queuedRenderable	The Renderable-MovableObject pair about to be rendered.
casterPass	Whether this is a shadow mapping caster pass.
lastCacheHash	The hash of the cache of shaders that was the used by the previous renderable.
lastTextureHash	Last Texture Hash, used to let the Hlms know whether the textures should be changed again

Returns: New Texture hash (may be equal or different to lastTextureHash).

Implemented in Ogre::HlmsLowLevel, Ogre::HlmsCompute, Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ fillBuffersForV1()

virtual uint32 Ogre::Hlms::fillBuffersForV1	(	const HlmsCache *	cache,
		const QueuedRenderable &	queuedRenderable,
		bool	casterPass,
		uint32	lastCacheHash,
		CommandBuffer *	commandBuffer
	)

pure virtual

Implemented in Ogre::HlmsLowLevel, Ogre::HlmsCompute, Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ fillBuffersForV2()

virtual uint32 Ogre::Hlms::fillBuffersForV2	(	const HlmsCache *	cache,
		const QueuedRenderable &	queuedRenderable,
		bool	casterPass,
		uint32	lastCacheHash,
		CommandBuffer *	commandBuffer
	)

pure virtual

Implemented in Ogre::HlmsLowLevel, Ogre::HlmsCompute, Ogre::HlmsUnlit, and Ogre::HlmsPbs.

◆ findParamInVec()

static bool Ogre::Hlms::findParamInVec	(	const HlmsParamVec &	paramVec,
		IdString	key,
		String &	inOut
	)

static

Finds the parameter with key 'key' in the given 'paramVec'.

If found, outputs the value to 'inOut', otherwise leaves 'inOut' as is.

Returns: True if the key was found (inOut was modified), false otherwise

Remarks: Assumes paramVec is sorted by key.

◆ frameEnded()

virtual void Ogre::Hlms::frameEnded ( )

inlinevirtual

Called when the frame has fully ended (ALL passes have been executed to all RTTs)

Reimplemented in Ogre::HlmsUnlit, Ogre::HlmsPbs, and Ogre::HlmsBufferManager.

◆ getAreaLightsApproxLimit()

uint16 Ogre::Hlms::getAreaLightsApproxLimit ( ) const

inline

◆ getAreaLightsLtcLimit()

uint16 Ogre::Hlms::getAreaLightsLtcLimit ( ) const

inline

◆ getDatablock()

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

Finds an existing datablock based on its name (.

See also: createDatablock)

Returns: The datablock associated with that name. Null pointer if not found. Doesn't throw.

◆ getDatablockCustomPieceData()

const DatablockCustomPieceFile* Ogre::Hlms::getDatablockCustomPieceData ( int32 filenameHashId ) const

Returns all the data we know about filenameHashId. Can be nullptr if not found.

◆ getDatablockCustomPieceFileNameStr()

const String& Ogre::Hlms::getDatablockCustomPieceFileNameStr ( int32 filenameHashId ) const

◆ getDatablockMap()

const HlmsDatablockMap& Ogre::Hlms::getDatablockMap ( ) const

inline

Returns all datablocks owned by this Hlms, including the default one.

◆ getDataFolder()

Archive* Ogre::Hlms::getDataFolder ( )

inline

◆ getDefaultDatablock()

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

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

◆ getFastShaderBuildHack()

bool Ogre::Hlms::getFastShaderBuildHack ( ) const

Returns true if shaders are being compiled with Fast Shader Build Hack (D3D11 only)

◆ getFilenameAndResourceGroup()

void Ogre::Hlms::getFilenameAndResourceGroup	(	IdString	name,
		String const **	outFilename,
		String const **	outResourceGroup
	)		const

Returns the filaname & resource group a datablock was created from, and is associated with its hashed name (this was passed as in createDatablock()).

Returns null ptr if not found. Note that it may also be a valid pointer but contain an empty string. The reason this String doesn't live in HlmsDatablock is to prevent cache trashing (datablocks are hot iterated every frame, and the filename & resource groups are rarely ever used).

: Usage:
String const *filename;

String const *resourceGroup;

datablock->getFilenameAndResourceGroup( &filename, &resourceGroup );

if( filename && resourceGroup && !filename->empty() && !resourceGroup->empty() )

{

//Valid filename & resource group.

}

Ogre::String
_StringBase String
Definition: OgreCommon.h:40

◆ getHlmsManager()

HlmsManager* Ogre::Hlms::getHlmsManager ( ) const

inline

◆ getListener()

HlmsListener* Ogre::Hlms::getListener ( ) const

Returns the current listener.

See also: setListener();

Remarks: If the default listener is being used (that does nothing) then null is returned.

◆ getMaterial()

const HlmsCache* Ogre::Hlms::getMaterial	(	HlmsCache const *	lastReturnedValue,
		const HlmsCache &	passCache,
		const QueuedRenderable &	queuedRenderable,
		bool	casterPass,
		ParallelHlmsCompileQueue *	parallelQueue
	)

Retrieves an HlmsCache filled with the GPU programs to be used by the given renderable.

If the shaders have already been created (i.e. whether for this renderable, or another one) it gets them from a cache. Otherwise we create it. It assumes that renderable->setHlms( this, parameters ) has already called.

Parameters

lastReturnedValue	The last value returned by getMaterial.
passCache	The cache returned by preparePassHash().
renderable	The renderable the caller wants us to give the shaders.
movableObject	The MovableObject owner of the renderable (we need it to know if renderable should cast shadows)
casterPass	True if this pass is the shadow mapping caster pass, false otherwise
parallelQueue	If non-null, the returned pointer will be a stub pointer; and caller is expected to call compileStubEntry() from a worker thread.

Returns: Structure containing all necessary shaders

◆ getMaterialSerial01()

uint32 Ogre::Hlms::getMaterialSerial01	(	uint32	lastReturnedValue,
		const HlmsCache &	passCache,
		const size_t	passCacheIdx,
		const QueuedRenderable &	queuedRenderable,
		bool	casterPass,
		ParallelHlmsCompileQueue &	parallelQueue
	)

This is extremely similar to getMaterial() except it's been designed to be always in parallel and to be used by warm_up passes.

The main difference is that getMaterial() starts firing shaders for parallel compilation as soon as they are seen, while this function accumulates as much as possible (even crossing multiple warm_up passes if they are in Collect mode) and then fire everything at once.

This can result in greater throughput.

Parameters

lastReturnedValue	Hash of the last value we've returned.
passCache	See getMaterial()
passCacheIdx	We can't send a permanent reference of passCache to parallelQueue, because the passCache won't survive that long. So we send instead and index that parallelQueue will later use to send the right pass cache to compileStubEntry()
queuedRenderable	See getMaterial()
casterPass	See getMaterial()
parallelQueue	[in/out] Queue to push our work to

Returns: The hash the shader will end up with. Caller must track whether we've already returned this value.

◆ getMaxNonCasterDirectionalLights()

uint16 Ogre::Hlms::getMaxNonCasterDirectionalLights ( ) const

inline

◆ getNameStr()

const String* Ogre::Hlms::getNameStr ( IdString name ) const

Returns the string name associated with its hashed name (this was passed as refName in createDatablock()).

Returns null ptr if not found. The reason this String doesn't live in HlmsDatablock is to prevent cache trashing (datablocks are hot iterated every frame, and the full name is rarely ever used)

◆ getParticleSystemConstSlot()

uint8 Ogre::Hlms::getParticleSystemConstSlot ( ) const

inline

◆ getParticleSystemSlot()

uint8 Ogre::Hlms::getParticleSystemSlot ( ) const

inline

◆ getPiecesLibrary()

const LibraryVec& Ogre::Hlms::getPiecesLibrary ( ) const

inline

◆ getPiecesLibraryAsArchiveVec()

ArchiveVec Ogre::Hlms::getPiecesLibraryAsArchiveVec ( ) const

◆ getPrecisionMode()

PrecisionMode Ogre::Hlms::getPrecisionMode ( ) const

Returns requested precision mode (i.e., value passed to setPrecisionMode) See getSupportedPrecisionMode.

◆ getProperty()

static int32 Ogre::Hlms::getProperty	(	const HlmsPropertyVec &	properties,
		IdString	key,
		int32	defaultVal = `0`
	)

static

Utility helper, mostly useful to HlmsListener implementations.

◆ getRenderSystem()

RenderSystem* Ogre::Hlms::getRenderSystem ( ) const

inline

◆ getShaderCodeCache()

const ShaderCodeCacheVec& Ogre::Hlms::getShaderCodeCache ( ) const

inline

◆ getShaderProfile()

const String& Ogre::Hlms::getShaderProfile ( ) const

inline

◆ getShaderSyntax()

IdString Ogre::Hlms::getShaderSyntax ( ) const

inline

◆ getStaticBranchingLights()

bool Ogre::Hlms::getStaticBranchingLights ( ) const

inline

◆ getSupportedPrecisionMode()

PrecisionMode Ogre::Hlms::getSupportedPrecisionMode ( ) const

Some GPUs don't support all precision modes.

Therefore this will returns the actually used precision mode after checking HW support

◆ getTemplateChecksum()

void Ogre::Hlms::getTemplateChecksum ( uint64 outHash[2] ) const

◆ getType()

HlmsTypes Ogre::Hlms::getType ( ) const

inline

◆ getTypeName()

IdString Ogre::Hlms::getTypeName ( ) const

inline

◆ getTypeNameStr()

const String& Ogre::Hlms::getTypeNameStr ( ) const

inline

◆ hasParticleFX2Plugin()

static bool Ogre::Hlms::hasParticleFX2Plugin ( )

inlinestatic

◆ isDatablockCustomPieceFileCacheable()

bool Ogre::Hlms::isDatablockCustomPieceFileCacheable ( int32 filenameHashId ) const

◆ isShaderCodeCacheDirty()

bool Ogre::Hlms::isShaderCodeCacheDirty ( ) const

inline

Users can check this function to tell if HlmsDiskCache needs saving.

If this value returns false, then HlmsDiskCache doesn't need saving.

◆ parseOffline()

bool Ogre::Hlms::parseOffline	(	const String &	filename,
		String &	inBuffer,
		String &	outBuffer,
		size_t	tid
	)

For standalone parsing.

◆ postCommandBufferExecution()

virtual void Ogre::Hlms::postCommandBufferExecution ( CommandBuffer * commandBuffer )

inlinevirtual

This gets called after executing the command buffer.

Reimplemented in Ogre::HlmsPbs, and Ogre::HlmsBufferManager.

◆ preCommandBufferExecution()

virtual void Ogre::Hlms::preCommandBufferExecution ( CommandBuffer * commandBuffer )

inlinevirtual

This gets called right before executing the command buffer.

Reimplemented in Ogre::HlmsBufferManager.

◆ preparePassHash()

virtual HlmsCache Ogre::Hlms::preparePassHash	(	const Ogre::CompositorShadowNode *	shadowNode,
		bool	casterPass,
		bool	dualParaboloid,
		SceneManager *	sceneManager
	)

virtual

Called every frame by the Render Queue to cache the properties needed by this pass.

i.e. Number of PSSM splits, number of shadow casting lights, etc

Parameters

shadowNode The shadow node currently in effect. Can be null.

Returns: A hash and cached property parameters. Unlike calculateHashFor(), the cache must be kept by the caller and not by us (because it may change every frame and is one for the whole pass, but Mesh' properties usually stay consistent through its lifetime but may differ per mesh)

Reimplemented in Ogre::HlmsLowLevel, Ogre::HlmsUnlit, Ogre::HlmsPbs, and Ogre::HlmsBufferManager.

◆ reloadFrom()

virtual void Ogre::Hlms::reloadFrom	(	Archive *	newDataFolder,
		ArchiveVec *	libraryFolders = `0`
	)

virtual

Destroys all the cached shaders and in the next opportunity will recreate them from the new location.

This is very useful for fast iteration and real-time editing of Hlms shader templates.

Remarks: Calling with null pointer is possible and will only invalidate existing shaders but you should provide a valid pointer before we start generating the first shader (or else crash).

: Existing datablock materials won't be reloaded from files, so their properties won't change (i.e. changed from blue to red), but the shaders will.

Parameters

libraryFolders When null pointer, the library folders paths won't be changed at all (but still will be reloaded). When non-null pointer, the library folders will be overwriten. Pass an empty container if you want to stop using libraries.

Reimplemented in Ogre::HlmsCompute.

◆ saveAllTexturesFromDatablocks()

void Ogre::Hlms::saveAllTexturesFromDatablocks	(	const String &	folderPath,
		set< String >::type &	savedTextures,
		bool	saveOitd,
		bool	saveOriginal,
		HlmsTextureExportListener *	listener
	)

◆ setAreaLightForwardSettings()

void Ogre::Hlms::setAreaLightForwardSettings	(	uint16	areaLightsApproxLimit,
		uint16	areaLightsLtcLimit
	)

Area lights use regular Forward.

Parameters

areaLightsApproxLimit

Maximum number of area approx lights that will be considered by the shader. Default value is 1. Use 0 to disable area lights.

Note: There is little to no performance impact for setting this value higher than you need. e.g. If you set areaLightsApproxLimit = 4, but you only have 2 area lights on scene, you'll pay the price of 2 area lights (but the RAM price of 4).

Beware of setting this value too high (e.g. 65535) as the amount of memory space is limited (we cannot exceed 64kb, including unrelated data to lighting, but required to the pass)

areaLightsLtcLimit Same as areaLightsApproxLimit, but for LTC lights

◆ setDebugOutputPath()

void Ogre::Hlms::setDebugOutputPath	(	bool	enableDebugOutput,
		bool	outputProperties,
		const String &	path = `BLANKSTRING`
	)

Call to output the automatically generated shaders (which are usually made from templates) on the given folder for inspection, analyzing, debugging, etc.

Remarks: The shader will be dumped when it is generated, not when this function gets called. You should call this function at start up

Parameters

enableDebugOutput	Whether to enable or disable dumping the shaders into a folder
outputProperties	Whether to dump properties and pieces at the beginning of the shader file. This is very useful for determining what caused Ogre to compile a new variation. Note that this setting may not always produce valid shader code in the dumped files (but it we'll still produce valid shader code while at runtime) If you want to compile the dumped file and it is invalid, just strip this info.
path	Path location on where to dump it. Should end with slash for proper concatenation (i.e. C:/path/ instead of C:/path; or /home/user/ instead of /home/user)

◆ setListener()

void Ogre::Hlms::setListener ( HlmsListener * listener )

Sets a listener to extend an existing Hlms implementation's with custom code, without having to rewrite it or modify the source code directly.

Remarks: Other alternatives for extending an existing implementation is to derive from the class and override particular virtual functions. For performance reasons, listeners are never called on a per-object basis. Consult the section "Customizing an existing implementation" from the manual in the Docs/2.0 folder.

Parameters

listener Listener pointer. Use null to disable.

◆ setMaxNonCasterDirectionalLights()

void Ogre::Hlms::setMaxNonCasterDirectionalLights ( uint16 maxLights )

Non-caster directional lights are hardcoded into shaders.

This means that if you have 6 directional lights and then you add a 7th one, a whole new set of shaders will be created.

This setting allows you to tremendously reduce the amount of shader permutations by forcing Ogre to switching to static branching with an upper limit to the max number of non-shadow-casting directional lights.

There is no such switch for shadow-casting directional/point/spot lights because of technical limitations at the GPU level (cannot index shadow map textures in DX11, nor samplers in any known GPU).

See also: setAreaLightForwardSettings

Parameters

maxLights

Maximum number of non-caster directional lights. 0 to allow unlimited number of lights, at the cost of shader recompilations when directional lights are added or removed.

Default value is 0.

Note: There is little to no performance impact for setting this value higher than you need. e.g. If you set maxLights = 4, but you only have 2 non-caster dir. lights on scene, you'll pay the price of 2 lights (but the RAM price of 4).

Beware of setting this value too high (e.g. 65535) as the amount of memory space is limited (we cannot exceed 64kb, including unrelated data to lighting, but required to the pass)

◆ setPrecisionMode()

void Ogre::Hlms::setPrecisionMode ( PrecisionMode precisionMode )

Sets the precision mode of Hlms.

See PrecisionMode Note: This call may invalidate the shader cache! Call as early as possible.

◆ setProperty()

static void Ogre::Hlms::setProperty	(	HlmsPropertyVec &	properties,
		IdString	key,
		int32	value
	)

static

Utility helper, mostly useful to HlmsListener implementations.

◆ setStaticBranchingLights()

virtual void Ogre::Hlms::setStaticBranchingLights ( bool staticBranchingLights )

virtual

By default shadow-caster spot and point lights are hardcoded into shaders.

This means that if you have 8 spot/point lights and then you add a 9th one, a whole new set of shaders will be created. Even more if you have a combination of 3 spot and 5 point lights and the combination has changed to 4 spot and 4 point lights then you'll get the next set of shaders

This setting allows you to tremendously reduce the amount of shader permutations by forcing Ogre to switching to static branching with an upper limit to the max number of shadow-casting spot or point lights.

See Hlms::setAreaLightForwardSettings

Remarks: All point and spot lights must share the same hlms_shadowmap atlas

This is mostly an D3D11 / HLSL SM 5.0 restriction (https://github.com/OGRECave/ogre-next/pull/255) but it may also help with performance in other APIs.

If multiple atlas support is needed, using Texture2DArrays may be a good solution, although it is currently untested and may need additional fixes to get it working

Parameters

staticBranchingLights True to evalute number of lights in the shader using static branching (less shader variants). False to recompile the shader more often (more variants, but better optimized shaders).

Reimplemented in Ogre::HlmsPbs.

Member Data Documentation

◆ kNoTid

constexpr size_t Ogre::Hlms::kNoTid = 0u

staticconstexpr

For single-threaded operations.

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

OgreHlms.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ DatablockCustomPieceFileMap

◆ HlmsDatablockMap

◆ LibraryVec

Member Enumeration Documentation

◆ CachedCustomPieceFileStatus

◆ LightGatheringMode

◆ PrecisionMode

Constructor & Destructor Documentation

◆ Hlms()

◆ ~Hlms()

Member Function Documentation

◆ _addDatablockCustomPieceFile() [1/2]

◆ _addDatablockCustomPieceFile() [2/2]

◆ _addDatablockCustomPieceFileFromMemory()

◆ _changeRenderSystem()

◆ _clearShaderCache()

◆ _collectSamplerblocks()

◆ _compileShaderFromPreprocessedSource()

◆ _getProperty()

◆ _loadJson()

◆ _notifyManager()

◆ _saveJson()

◆ _setHasParticleFX2Plugin()

◆ _setNumThreads()

◆ _setProperty()

◆ _setShadersGenerated()

◆ _setTextureReg()

◆ _tagShaderCodeCacheUpToDate()

◆ analyzeBarriers()

◆ calculateHashFor()

◆ compileShaderCode()

◆ compileStubEntry()

◆ createDatablock()

◆ destroyAllDatablocks()

◆ destroyDatablock()

◆ fillBuffersFor()

◆ fillBuffersForV1()

◆ fillBuffersForV2()

◆ findParamInVec()

◆ frameEnded()

◆ getAreaLightsApproxLimit()

◆ getAreaLightsLtcLimit()

◆ getDatablock()

◆ getDatablockCustomPieceData()

◆ getDatablockCustomPieceFileNameStr()

◆ getDatablockMap()

◆ getDataFolder()

◆ getDefaultDatablock()

◆ getFastShaderBuildHack()

◆ getFilenameAndResourceGroup()

◆ getHlmsManager()

◆ getListener()

◆ getMaterial()

◆ getMaterialSerial01()

◆ getMaxNonCasterDirectionalLights()

◆ getNameStr()

◆ getParticleSystemConstSlot()

◆ getParticleSystemSlot()

◆ getPiecesLibrary()

◆ getPiecesLibraryAsArchiveVec()

◆ getPrecisionMode()

◆ getProperty()

◆ getRenderSystem()

◆ getShaderCodeCache()

◆ getShaderProfile()

◆ getShaderSyntax()

◆ getStaticBranchingLights()

◆ getSupportedPrecisionMode()

◆ getTemplateChecksum()

◆ getType()

◆ getTypeName()

◆ getTypeNameStr()

◆ hasParticleFX2Plugin()