An hlms datablock contains individual information about a specific material. More...

#include <OgreHlmsDatablock.h>

Inheritance diagram for Ogre::HlmsDatablock:

Public Member Functions
	HlmsDatablock (IdString name, Hlms creator, const HlmsMacroblock macroblock, const HlmsBlendblock *blendblock, const HlmsParamVec &params)

virtual	~HlmsDatablock ()

void	_linkRenderable (Renderable *renderable)

void	_unlinkRenderable (Renderable *renderable)

virtual void	calculateHash ()
	Calculates the hashes needed for sorting by the RenderQueue (i.e. mTextureHash) More...

HlmsDatablock *	clone (String name) const
	Creates a copy of this datablock with the same settings, but a different name. More...

bool	getAlphaHashing () const

CompareFunction	getAlphaTest () const

bool	getAlphaTestShadowCasterOnly () const

float	getAlphaTestThreshold () const

const HlmsBlendblock *	getBlendblock (bool casterBlock=false) const

Hlms *	getCreator () const

int32	getCustomPieceFileIdHash (ShaderType shaderType) const
	Returns the internal ID generated by setCustomPieceFile() and setCustomPieceCodeFromMemory(). More...

const String &	getCustomPieceFileStr (ShaderType shaderType) const
	Returns the filename argument set to setCustomPieceFile() and setCustomPieceCodeFromMemory(). More...

virtual ColourValue	getDiffuseColour () const
	Returns the closest match for a diffuse colour, if applicable by the actual implementation. More...

virtual TextureGpu *	getDiffuseTexture () const
	Returns the closest match for a diffuse texture, if applicable by the actual implementation. More...

virtual ColourValue	getEmissiveColour () const
	Returns the closest match for a emissive colour, if applicable by the actual implementation. More...

virtual TextureGpu *	getEmissiveTexture () const
	Returns the closest match for a emissive texture, if applicable by the actual implementation. More...

void	getFilenameAndResourceGroup (String const outFilename, String const outResourceGroup) const

const vector< Renderable * >::type &	getLinkedRenderables () const

const HlmsMacroblock *	getMacroblock (bool casterBlock=false) const

IdString	getName () const

const String *	getNameStr () const

virtual bool	hasCustomShadowMacroblock () const

virtual void	preload ()
	Tells datablock to start loading all of its textures (if not loaded already) and any other resource it may need. More...

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

void	setAlphaHashing (bool bAlphaHashing)
	Uses a trick to mimic true Order Independent Transparency alpha blending. More...

virtual void	setAlphaTest (CompareFunction compareFunction, bool shadowCasterOnly=false, bool useAlphaFromTextures=true)
	Sets the alpha test to the given compare function. More...

virtual void	setAlphaTestThreshold (float threshold)
	Alpha test's threshold. More...

void	setBlendblock (const HlmsBlendblock &blendblock, bool casterBlock=false, bool overrideCasterBlock=true)
	Sets a new blendblock that matches the same parameter as the input. More...

void	setBlendblock (const HlmsBlendblock *blendblock, bool casterBlock=false, bool overrideCasterBlock=true)
	Sets the blendblock from the given pointer that was already retrieved from the HlmsManager. More...

void	setCustomPieceCodeFromMemory (const String &filename, const String &shaderCode, ShaderType shaderType)
	Same as setCustomPieceFile() but sources the code from memory instead of from disk. More...

void	setCustomPieceFile (const String &filename, const String &resourceGroup, ShaderType shaderType)
	Sets the filename of a piece file to be parsed from disk. More...

void	setMacroblock (const HlmsMacroblock &macroblock, bool casterBlock=false, bool overrideCasterBlock=true)
	Sets a new macroblock that matches the same parameter as the input. More...

void	setMacroblock (const HlmsMacroblock *macroblock, bool casterBlock=false, bool overrideCasterBlock=true)
	Sets the macroblock from the given pointer that was already retrieved from the HlmsManager. More...

Static Public Member Functions
static const char *	getCmpString (CompareFunction compareFunction)

Public Attributes
bool	mAllowTextureResidencyChange
	When false, we won't try to have Textures become resident. More...

uint16	mMacroblockHash [2]

float	mShadowConstantBias

uint32	mTextureHash

uint8	mType

Detailed Description

An hlms datablock contains individual information about a specific material.

It consists of:

A const pointer to an HlmsMacroblock we do not own and may be shared by other datablocks.
A const pointer to an HlmsBlendblock we do not own and may be shared by other datablocks.
The original properties from which this datablock was constructed.
This type may be derived to contain additional information.

Derived types can cache information present in mOriginalProperties as strings, like diffuse colour values, etc.

A datablock is the internal representation of the surface parameters (depth settings, textures to be used, diffuse colour, specular colour, etc). The notion of a datablock is the closest you'll get to a "material"

Remarks: Macro- & Blendblocks are immutable, hence const pointers. Trying to const cast these pointers in order to modify them may work on certain RenderSystems (i.e. GLES2) but will seriously break on other RenderSystems (i.e. D3D11).

: If you need to change a macroblock, create a new one (HlmsManager keeps them cached if already created) and change the entire pointer.

: Each datablock has a pair of macroblocks and blendblocks. One of is for the regular passes, the other is for shadow mapping passes, since in some cases you don't want them to be the same. As for blendblocks, with transparent objects you may want to turn off alpha blending, but enable alpha testing instead.

Constructor & Destructor Documentation

◆ HlmsDatablock()

Ogre::HlmsDatablock::HlmsDatablock	(	IdString	name,
		Hlms *	creator,
		const HlmsMacroblock *	macroblock,
		const HlmsBlendblock *	blendblock,
		const HlmsParamVec &	params
	)

◆ ~HlmsDatablock()

virtual Ogre::HlmsDatablock::~HlmsDatablock ( )

virtual

Member Function Documentation

◆ _linkRenderable()

void Ogre::HlmsDatablock::_linkRenderable ( Renderable * renderable )

◆ _unlinkRenderable()

void Ogre::HlmsDatablock::_unlinkRenderable ( Renderable * renderable )

◆ calculateHash()

virtual void Ogre::HlmsDatablock::calculateHash ( )

inlinevirtual

Calculates the hashes needed for sorting by the RenderQueue (i.e. mTextureHash)

◆ clone()

HlmsDatablock* Ogre::HlmsDatablock::clone ( String name ) const

Creates a copy of this datablock with the same settings, but a different name.

Parameters

name	Name of the cloned datablock.

◆ getAlphaHashing()

bool Ogre::HlmsDatablock::getAlphaHashing ( ) const

inline

◆ getAlphaTest()

CompareFunction Ogre::HlmsDatablock::getAlphaTest ( ) const

◆ getAlphaTestShadowCasterOnly()

bool Ogre::HlmsDatablock::getAlphaTestShadowCasterOnly ( ) const

◆ getAlphaTestThreshold()

float Ogre::HlmsDatablock::getAlphaTestThreshold ( ) const

inline

◆ getBlendblock()

const HlmsBlendblock* Ogre::HlmsDatablock::getBlendblock ( bool casterBlock = false ) const

inline

◆ getCmpString()

static const char* Ogre::HlmsDatablock::getCmpString ( CompareFunction compareFunction )

static

◆ getCreator()

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

inline

◆ getCustomPieceFileIdHash()

int32 Ogre::HlmsDatablock::getCustomPieceFileIdHash ( ShaderType shaderType ) const

Returns the internal ID generated by setCustomPieceFile() and setCustomPieceCodeFromMemory().

All calls with the same filename share the same ID. This ID is a deterministic hash. Returns 0 if unset.

◆ getCustomPieceFileStr()

const String& Ogre::HlmsDatablock::getCustomPieceFileStr ( ShaderType shaderType ) const

Returns the filename argument set to setCustomPieceFile() and setCustomPieceCodeFromMemory().

◆ getDiffuseColour()

virtual ColourValue Ogre::HlmsDatablock::getDiffuseColour ( ) const

virtual

Returns the closest match for a diffuse colour, if applicable by the actual implementation.

Note that Unlit implementation returns 0 as diffuse, since it's considered emissive instead due to being bright even in the absence lights.

◆ getDiffuseTexture()

virtual TextureGpu* Ogre::HlmsDatablock::getDiffuseTexture ( ) const

virtual

Returns the closest match for a diffuse texture, if applicable by the actual implementation.

See HlmsDatablock::getDiffuseColour

◆ getEmissiveColour()

virtual ColourValue Ogre::HlmsDatablock::getEmissiveColour ( ) const

virtual

Returns the closest match for a emissive colour, if applicable by the actual implementation.

See HlmsDatablock::getDiffuseColour

◆ getEmissiveTexture()

virtual TextureGpu* Ogre::HlmsDatablock::getEmissiveTexture ( ) const

virtual

Returns the closest match for a emissive texture, if applicable by the actual implementation.

See HlmsDatablock::getDiffuseColour

◆ getFilenameAndResourceGroup()

void Ogre::HlmsDatablock::getFilenameAndResourceGroup	(	String const **	outFilename,
		String const **	outResourceGroup
	)		const

See also: Hlms::getFilenameAndResourceGroup. This operation is NOT fast. Might return null (if the datablock was removed from the Hlms but somehow is still alive)

: 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

◆ getLinkedRenderables()

const vector<Renderable *>::type& Ogre::HlmsDatablock::getLinkedRenderables ( ) const

inline

◆ getMacroblock()

const HlmsMacroblock* Ogre::HlmsDatablock::getMacroblock ( bool casterBlock = false ) const

inline

◆ getName()

IdString Ogre::HlmsDatablock::getName ( ) const

inline

◆ getNameStr()

const String* Ogre::HlmsDatablock::getNameStr ( ) const

See also: Hlms::getNameStr. This operation is NOT fast. Might return null (if the datablock was removed from the Hlms but somehow is still alive)

◆ hasCustomShadowMacroblock()

virtual bool Ogre::HlmsDatablock::hasCustomShadowMacroblock ( ) const

virtual

◆ preload()

virtual void Ogre::HlmsDatablock::preload ( )

virtual

Tells datablock to start loading all of its textures (if not loaded already) and any other resource it may need.

Useful to cut loading times by anticipating what the user will do.

Do not call this function aggressively (e.g. for lots of material every frame)

Reimplemented in Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

◆ saveTextures()

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

virtual

Remarks: It's possible to set both saveOitd & saveOriginal to true, but will likely double storage requirements (2x as many textures). Setting both to true is useful for troubleshooting obscure Ogre bugs.

Parameters

folderPath	Folder where to dump the textures.
savedTextures	[in/out] Set of texture names. Textures whose name is already in the set won't be saved again. Textures that were saved will be inserted into the set.
saveOitd	When true, we will download the texture from GPU and save it in OITD format. OITD is faster to load as it's stored in Ogre's native format it understands, but it cannot be opened by traditional image editors; also OITD is not backwards compatible with older versions of Ogre.
saveOriginal	When true, we will attempt to read the raw filestream of the original texture and save it (i.e. copy the original png/dds/etc file).

Reimplemented in Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

◆ setAlphaHashing()

void Ogre::HlmsDatablock::setAlphaHashing ( bool bAlphaHashing )

Uses a trick to mimic true Order Independent Transparency alpha blending.

The advantage of this method is that it is compatible with depth buffer writes and is order independent.

Calling this function triggers a HlmsDatablock::flushRenderables

Remarks: For best results:

// Disable alpha test (default).

datablock->setAlphaTest( CMPF_ALWAYS_PASS );

// Do NOT enable alpha blending in the HlmsBlendblock (default).

HlmsBlendblock blendblock;

blendblock.setBlendType( SBT_REPLACE );

// Recommended: Enable A2C when using MSAA.

blendblock.mAlphaToCoverage = Ogre::HlmsBlendblock::A2cEnabledMsaaOnly;

datablock->setBlendblock( blendblock );

datablock->setAlphaHashing( true );

Ogre::CMPF_ALWAYS_PASS
@ CMPF_ALWAYS_PASS
Definition: OgreCommon.h:152

Ogre::SBT_REPLACE
@ SBT_REPLACE
The default blend mode where source replaces destination.
Definition: OgreBlendMode.h:221

Ogre::HlmsBlendblock::A2cEnabledMsaaOnly
@ A2cEnabledMsaaOnly
Alpha to Coverage is enabled only if RenderTarget uses MSAA.
Definition: OgreHlmsDatablock.h:179

Parameters

bAlphaHashing True to enable alpha hashing.

◆ setAlphaTest()

virtual void Ogre::HlmsDatablock::setAlphaTest	(	CompareFunction	compareFunction,
		bool	shadowCasterOnly = `false`,
		bool	useAlphaFromTextures = `true`
	)

virtual

Sets the alpha test to the given compare function.

CMPF_ALWAYS_PASS means disabled.

See also: mAlphaTestThreshold. Calling this function triggers a HlmsDatablock::flushRenderables

Remarks: It is to the derived implementation to actually implement the alpha test.

Parameters

compareFunction	Compare function to use. Default is CMPF_ALWAYS_PASS, which means disabled. Note: CMPF_ALWAYS_FAIL is not supported. Set a negative threshold to workaround this issue.
shadowCasterOnly	When true, only the caster should use alpha testing. Useful if you want alpha blending (i.e. transparency) while rendering normally, but want semi-transparent shadows.
useAlphaFromTextures	Whether you want the diffuse texture's alpha to influence the alpha test Most likely you want this to be true, unless you're customizing the shader and have special use for alpha testing

◆ setAlphaTestThreshold()

virtual void Ogre::HlmsDatablock::setAlphaTestThreshold ( float threshold )

virtual

Alpha test's threshold.

See also: setAlphaTest

Parameters

threshold Value typically in the range [0; 1)

Reimplemented in Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

◆ setBlendblock() [1/2]

void Ogre::HlmsDatablock::setBlendblock	(	const HlmsBlendblock &	blendblock,
		bool	casterBlock = `false`,
		bool	overrideCasterBlock = `true`
	)

Sets a new blendblock that matches the same parameter as the input.

Decreases the reference count of the previous mBlendblock. Runs an O(N) search to get the right block. Calling this function triggers a HlmsDatablock::flushRenderables

Parameters

blendblock	see HlmsManager::getBlendblock
casterBlock	True to directly set the blendblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant.
overrideCasterBlock	If true and casterBlock = false, the caster block will also be set to the input value.

◆ setBlendblock() [2/2]

void Ogre::HlmsDatablock::setBlendblock	(	const HlmsBlendblock *	blendblock,
		bool	casterBlock = `false`,
		bool	overrideCasterBlock = `true`
	)

Sets the blendblock from the given pointer that was already retrieved from the HlmsManager.

Unlike the other overload, this operation is O(1). Calling this function triggers a HlmsDatablock::flushRenderables

Parameters

blendblock	A valid block. The reference count is increased inside this function.
casterBlock	True to directly set the blendblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant.
overrideCasterBlock	If true and casterBlock = false, the caster block will also be set to the input value.

◆ setCustomPieceCodeFromMemory()

void Ogre::HlmsDatablock::setCustomPieceCodeFromMemory	(	const String &	filename,
		const String &	shaderCode,
		ShaderType	shaderType
	)

Same as setCustomPieceFile() but sources the code from memory instead of from disk.

Calling this function triggers HlmsDatablock::flushRenderables.

Remarks: HlmsDiskCache cannot cache shaders generated from memory as it cannot guarantee the cache isn't out of date.

Parameters

filename	"Filename" to identify it. It must be unique. Empty to disable. If the filename has already been previously provided, the contents must be an exact match.
shaderCode	Shader source code.
shaderType	Shader stage to be used.

◆ setCustomPieceFile()

void Ogre::HlmsDatablock::setCustomPieceFile	(	const String &	filename,
		const String &	resourceGroup,
		ShaderType	shaderType
	)

Sets the filename of a piece file to be parsed from disk.

First, before all other files.

Calling this function triggers HlmsDatablock::flushRenderables.

Remarks: HlmsDiskCache can cache shaders generated with setCustomPieceFile().

Parameters

filename	Filename of the piece file. Must be unique. Empty to disable. If the filename has already been previously provided, the contents must be an exact match.
resourceGroup
shaderType	Shader stage to be used.

◆ setMacroblock() [1/2]

void Ogre::HlmsDatablock::setMacroblock	(	const HlmsMacroblock &	macroblock,
		bool	casterBlock = `false`,
		bool	overrideCasterBlock = `true`
	)

Sets a new macroblock that matches the same parameter as the input.

Decreases the reference count of the previously set one. Runs an O(N) search to get the right block. Calling this function triggers a HlmsDatablock::flushRenderables

Parameters

macroblock	see HlmsManager::getMacroblock
casterBlock	True to directly set the macroblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant.
overrideCasterBlock	If true and casterBlock = false, the caster block will also be set to the input value.

◆ setMacroblock() [2/2]

void Ogre::HlmsDatablock::setMacroblock	(	const HlmsMacroblock *	macroblock,
		bool	casterBlock = `false`,
		bool	overrideCasterBlock = `true`
	)

Sets the macroblock from the given pointer that was already retrieved from the HlmsManager.

Unlike the other overload, this operation is O(1). Calling this function triggers a HlmsDatablock::flushRenderables

Parameters

macroblock	A valid block. The reference count is increased inside this function.
casterBlock	True to directly set the macroblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant.
overrideCasterBlock	If true and casterBlock = false, the caster block will also be set to the input value.

Member Data Documentation

◆ mAllowTextureResidencyChange

bool Ogre::HlmsDatablock::mAllowTextureResidencyChange

When false, we won't try to have Textures become resident.

◆ mMacroblockHash

uint16 Ogre::HlmsDatablock::mMacroblockHash[2]

◆ mShadowConstantBias

float Ogre::HlmsDatablock::mShadowConstantBias

◆ mTextureHash

uint32 Ogre::HlmsDatablock::mTextureHash

◆ mType

uint8 Ogre::HlmsDatablock::mType

See also: HlmsTypes

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

OgreHlmsDatablock.h

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ HlmsDatablock()

◆ ~HlmsDatablock()

Member Function Documentation

◆ _linkRenderable()

◆ _unlinkRenderable()

◆ calculateHash()

◆ clone()

◆ getAlphaHashing()

◆ getAlphaTest()

◆ getAlphaTestShadowCasterOnly()

◆ getAlphaTestThreshold()

◆ getBlendblock()

◆ getCmpString()

◆ getCreator()

◆ getCustomPieceFileIdHash()

◆ getCustomPieceFileStr()

◆ getDiffuseColour()

◆ getDiffuseTexture()

◆ getEmissiveColour()

◆ getEmissiveTexture()

◆ getFilenameAndResourceGroup()

◆ getLinkedRenderables()

◆ getMacroblock()

◆ getName()

◆ getNameStr()

◆ hasCustomShadowMacroblock()

◆ preload()

◆ saveTextures()

◆ setAlphaHashing()

◆ setAlphaTest()

◆ setAlphaTestThreshold()

◆ setBlendblock() [1/2]

◆ setBlendblock() [2/2]

◆ setCustomPieceCodeFromMemory()

◆ setCustomPieceFile()

◆ setMacroblock() [1/2]

◆ setMacroblock() [2/2]

Member Data Documentation

◆ mAllowTextureResidencyChange

◆ mMacroblockHash

◆ mShadowConstantBias

◆ mTextureHash

◆ mType