OGRE  2.3
Object-Oriented Graphics Rendering Engine
Ogre::HlmsDatablock Class Reference

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...
 
HlmsDatablockclone (String name) const
 Creates a copy of this datablock with the same settings, but a different name. More...
 
CompareFunction getAlphaTest (void) const
 
bool getAlphaTestShadowCasterOnly (void) const
 
float getAlphaTestThreshold (void) const
 
const HlmsBlendblockgetBlendblock (bool casterBlock=false) const
 
HlmsgetCreator (void) const
 
virtual ColourValue getDiffuseColour (void) const
 Returns the closest match for a diffuse colour, if applicable by the actual implementation. More...
 
virtual TextureGpugetDiffuseTexture (void) const
 Returns the closest match for a diffuse texture, if applicable by the actual implementation. More...
 
virtual ColourValue getEmissiveColour (void) const
 Returns the closest match for a emissive colour, if applicable by the actual implementation. More...
 
virtual TextureGpugetEmissiveTexture (void) 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 (void) const
 
const HlmsMacroblockgetMacroblock (bool casterBlock=false) const
 
IdString getName (void) const
 
const StringgetNameStr (void) const
 
virtual bool hasCustomShadowMacroblock (void) const
 
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 More...
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
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 More...
 
virtual void saveTextures (const String &folderPath, set< String >::type &savedTextures, bool saveOitd, bool saveOriginal, HlmsTextureExportListener *listener)
 
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)
 Sets a new blendblock that matches the same parameter as the input. More...
 
void setBlendblock (const HlmsBlendblock *blendblock, bool casterBlock=false)
 Sets the blendblock from the given pointer that was already retrieved from the HlmsManager. More...
 
void setMacroblock (const HlmsMacroblock &macroblock, bool casterBlock=false)
 Sets a new macroblock that matches the same parameter as the input. More...
 
void setMacroblock (const HlmsMacroblock *macroblock, bool casterBlock=false)
 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
 

Friends

class RenderQueue
 

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 often you don't want them to be the same. Shadow mapping often wants to reverse culling (
See also
HlmsManager::setShadowMappingUseBackFaces) or use some depth bias. 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)

Reimplemented in Ogre::HlmsUnlitMobileDatablock, and Ogre::HlmsPbsMobileDatablock.

◆ clone()

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

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

Parameters
nameName of the cloned datablock.

◆ getAlphaTest()

CompareFunction Ogre::HlmsDatablock::getAlphaTest ( void  ) const

◆ getAlphaTestShadowCasterOnly()

bool Ogre::HlmsDatablock::getAlphaTestShadowCasterOnly ( void  ) const

◆ getAlphaTestThreshold()

float Ogre::HlmsDatablock::getAlphaTestThreshold ( void  ) 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 ( void  ) const
inline

◆ getDiffuseColour()

virtual ColourValue Ogre::HlmsDatablock::getDiffuseColour ( void  ) 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 ( void  ) 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 ( void  ) 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 ( void  ) 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 operations 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. }

◆ getLinkedRenderables()

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

◆ getMacroblock()

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

◆ getName()

IdString Ogre::HlmsDatablock::getName ( void  ) const
inline

◆ getNameStr()

const String* Ogre::HlmsDatablock::getNameStr ( void  ) const
See also
Hlms::getNameStr. This operations 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 ( void  ) const
virtual

◆ 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

◆ 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
folderPathFolder 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.
saveOitdWhen 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.
saveOriginalWhen 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.

◆ 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
compareFunctionCompare 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.
shadowCasterOnlyWhen 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.
useAlphaFromTexturesWhether 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
thresholdValue typically in the range [0; 1)

Reimplemented in Ogre::HlmsPbsMobileDatablock.

◆ setBlendblock() [1/2]

void Ogre::HlmsDatablock::setBlendblock ( const HlmsBlendblock blendblock,
bool  casterBlock = false 
)

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
casterBlockTrue to directly set the blendblock to be used during the shadow mapping's caster pass. Note that when false, it will reset the caster block to the same as the regular one.

◆ setBlendblock() [2/2]

void Ogre::HlmsDatablock::setBlendblock ( const HlmsBlendblock blendblock,
bool  casterBlock = false 
)

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
blendblockA valid block. The reference count is increased inside this function.
casterBlockTrue to directly set the blendblock to be used during the shadow mapping's caster pass. Note that when false, it will reset the caster block to the same as the regular one.

◆ setMacroblock() [1/2]

void Ogre::HlmsDatablock::setMacroblock ( const HlmsMacroblock macroblock,
bool  casterBlock = false 
)

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
casterBlockTrue to directly set the macroblock to be used during the shadow mapping's caster pass. Note that when false, it will automatically reset the caster's block according to HlmsManager::setShadowMappingUseBackFaces setting.

◆ setMacroblock() [2/2]

void Ogre::HlmsDatablock::setMacroblock ( const HlmsMacroblock macroblock,
bool  casterBlock = false 
)

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
macroblockA valid block. The reference count is increased inside this function.
casterBlockTrue to directly set the macroblock to be used during the shadow mapping's caster pass. Note that when false, it will automatically reset the caster's block according to HlmsManager::setShadowMappingUseBackFaces setting.

Friends And Related Function Documentation

◆ RenderQueue

friend class RenderQueue
friend

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

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