OGRE-Next  3.0.0
Object-Oriented Graphics Rendering Engine
Ogre::Hlms Class Referenceabstract

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

#include <OgreHlms.h>

+ Inheritance diagram for Ogre::Hlms:

Classes

struct  DatablockEntry
 
struct  Library
 

Public Types

typedef std::map< IdString, DatablockEntryHlmsDatablockMap
 
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 ()
 
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])
 
int32 _getProperty (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 _setProperty (IdString key, int32 value)
 For debugging stuff. I.e. the Command line uses it for testing manually set properties. More...
 
void _setTextureReg (ShaderType shaderType, const char *texName, int32 texUnit)
 
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. More...
 
void compileShaderCode (ShaderCodeCache &codeCache)
 Compiles input properties and adds it to the shader code cache. More...
 
HlmsDatablockcreateDatablock (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
 
HlmsDatablockgetDatablock (IdString name) const
 Finds an existing datablock based on its name (. More...
 
const HlmsDatablockMapgetDatablockMap () const
 Returns all datablocks owned by this Hlms, including the default one. More...
 
ArchivegetDataFolder ()
 
HlmsDatablockgetDefaultDatablock () 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...
 
HlmsManagergetHlmsManager () const
 
HlmsListenergetListener () const
 Returns the current listener. More...
 
const HlmsCachegetMaterial (HlmsCache const *lastReturnedValue, const HlmsCache &passCache, const QueuedRenderable &queuedRenderable, bool casterPass)
 Retrieves an HlmsCache filled with the GPU programs to be used by the given renderable. More...
 
uint16 getMaxNonCasterDirectionalLights () const
 
const StringgetNameStr (IdString name) const
 Returns the string name associated with its hashed name (this was passed as refName in createDatablock()). More...
 
const LibraryVecgetPiecesLibrary () const
 
ArchiveVec getPiecesLibraryAsArchiveVec () const
 
PrecisionMode getPrecisionMode () const
 Returns requested precision mode (i.e. More...
 
RenderSystemgetRenderSystem () const
 
const ShaderCodeCacheVec & getShaderCodeCache () const
 
const StringgetShaderProfile () 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 StringgetTypeNameStr () const
 
bool parseOffline (const String &filename, String &inBuffer, String &outBuffer)
 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 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 void setProperty (HlmsPropertyVec &properties, IdString key, int32 value)
 Utility helper, mostly useful to HlmsListener implementations. 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

◆ HlmsDatablockMap

◆ LibraryVec

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

Member Enumeration Documentation

◆ LightGatheringMode

Enumerator
LightGatherForward 
LightGatherForwardPlus 
LightGatherDeferred 
LightGatherNone 

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

◆ _changeRenderSystem()

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

Reimplemented in Ogre::HlmsCompute.

◆ _clearShaderCache()

void Ogre::Hlms::_clearShaderCache ( )

◆ _collectSamplerblocks()

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

◆ _compileShaderFromPreprocessedSource()

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

◆ _getProperty()

int32 Ogre::Hlms::_getProperty ( 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
jsonValueJSON Object containing the definition of this datablock.
blocksAll the loaded Macro-, Blend- & Samplerblocks the JSON has defined and may be referenced by the datablock declaration.
datablockDatablock to fill the values.

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

◆ _setProperty()

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

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

◆ _setTextureReg()

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

◆ analyzeBarriers()

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

◆ 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' uvs are stripped)

Parameters
renderableThe renderable the material will be used on.
movableObjectThe MovableObject the material will be used on (usually the parent of renderable)
outHashA hash. This hash references property parameters that are already cached.

Reimplemented in Ogre::HlmsLowLevel.

◆ compileShaderCode()

void Ogre::Hlms::compileShaderCode ( ShaderCodeCache &  codeCache)

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

◆ 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
nameName 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.
refNameName 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 also
HlmsManager::getMacroblock
Parameters
blendblockRef
See also
HlmsManager::getBlendblock
Parameters
paramVecKey - String Value list of paramters. MUST BE SORTED.
visibleToManagerWhen false, HlmsManager::getDatablock won't find this datablock. True by default
filenameFilename in which it was defined, so that this information can be retrieved later by the user if needed. This is only for informational purposes.
resourceGroupResourceGroup. 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
cacheCurrent cache of Shaders to be used.
queuedRenderableThe Renderable-MovableObject pair about to be rendered.
casterPassWhether this is a shadow mapping caster pass.
lastCacheHashThe hash of the cache of shaders that was the used by the previous renderable.
lastTextureHashLast 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, and Ogre::HlmsCompute.

◆ fillBuffersForV1()

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

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

◆ fillBuffersForV2()

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

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

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

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

◆ 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. }

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

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
lastReturnedValueThe last value returned by getMaterial.
passCacheThe cache returned by preparePassHash().
renderableThe renderable the caller wants us to give the shaders.
movableObjectThe MovableObject owner of the renderable (we need it to know if renderable should cast shadows)
casterPassTrue if this pass is the shadow mapping caster pass, false otherwise
Returns
Structure containing all necessary shaders

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

◆ 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

◆ parseOffline()

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

For standalone parsing.

◆ postCommandBufferExecution()

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

This gets called after executing the command buffer.

◆ preCommandBufferExecution()

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

This gets called right before executing the command buffer.

◆ 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
shadowNodeThe 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.

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

Parameters
areaLightsLtcLimitSame 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
enableDebugOutputWhether to enable or disable dumping the shaders into a folder
outputPropertiesWhether 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.
pathPath 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
listenerListener 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
maxLightsMaximum 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
maxShadowMapLightsMaximum number of shadow-caster spot and point lights. 0 to allow unlimited number of lights, at the cost of shader recompilations when spot or point lights are added or removed or their combination are changed.

Default value is 0.


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