sh::Factory Class Reference

The main interface class. More...

#include <Factory.hpp>

Public Member Functions
	Factory (Platform *platform)
MaterialInstance *	createMaterialInstance (const std::string &name, const std::string &parentInstance="")
void	destroyMaterialInstance (const std::string &name)
void	setShadersEnabled (bool enabled)
	Use this to enable or disable shaders on-the-fly.
void	setShaderDebugOutputEnabled (bool enabled)
	write generated shaders to current directory, useful for debugging
void	setGlobalSetting (const std::string &name, const std::string &value)
void	setSharedParameter (const std::string &name, PropertyValuePtr value)
Language	getCurrentLanguage ()
void	setCurrentLanguage (Language lang)
	Switch between different shader languages (cg, glsl, hlsl)
MaterialInstance *	getMaterialInstance (const std::string &name)
	Get a MaterialInstance by name.
void	createConfiguration (const std::string &name)
	Create a configuration, which can then be altered by using Factory::getConfiguration.
void	registerLodConfiguration (int index, PropertySetGet configuration)
void	setTextureAlias (const std::string &alias, const std::string &realName)
std::string	retrieveTextureAlias (const std::string &name)
	Retrieve the real texture name for a texture alias (the real name is set by the user)
void	setMaterialListener (MaterialListener *listener)
	Attach a listener for material created events.
void	loadAllFiles ()
	Call this after you have set up basic stuff, like the shader language.
void	setWriteSourceCache (bool write)
void	setReadSourceCache (bool read)
void	setWriteMicrocodeCache (bool write)
void	setReadMicrocodeCache (bool read)
void	listMaterials (std::vector< std::string > &out)
void	listGlobalSettings (std::map< std::string, std::string > &out)
	Lists current name & value of all global settings.
void	listConfigurationNames (std::vector< std::string > &out)
	Lists configuration names.
void	listConfigurationSettings (const std::string &name, std::map< std::string, std::string > &out)
	Lists current name & value of settings for a given configuration.
void	listShaderSets (std::vector< std::string > &out)
	Lists shader sets.
bool	reloadShaders ()
void	doMonitorShaderFiles ()
void	unloadUnreferencedMaterials ()
void	destroyConfiguration (const std::string &name)
void	notifyConfigurationChanged ()
void	saveAll ()
std::string	getErrorLog ()
void	_ensureMaterial (const std::string &name, const std::string &configuration)
Configuration *	getConfiguration (const std::string &name)
bool	getWriteMicrocodeCache ()

Static Public Member Functions
static Factory &	getInstance ()
	Return instance of this class.
static Factory *	getInstancePtr ()

Friends
class	Platform
class	MaterialInstance
class	ShaderInstance
class	ShaderSet
class	TextureUnitState

Detailed Description

The main interface class.

Constructor & Destructor Documentation

Factory()

sh::Factory::Factory

(

Platform *

platform

)

Note

Ownership of platform is transferred to this class, so you don't have to delete it.

Member Function Documentation

_ensureMaterial()

void sh::Factory::_ensureMaterial	(	const std::string &	name,
		const std::string &	configuration
	)

Make sure a material technique is loaded.
You will probably never have to use this.

createMaterialInstance()

MaterialInstance* sh::Factory::createMaterialInstance	(	const std::string &	name,
		const std::string &	parentInstance = ""
	)

Create a MaterialInstance, optionally copying all properties from parentInstance

Parameters

name	name of the new instance
name	of the parent (optional)

Returns

newly created instance

destroyMaterialInstance()

void sh::Factory::destroyMaterialInstance

(

const std::string &

name

)

Note

It is safe to call this if the instance does not exist

doMonitorShaderFiles()

void sh::Factory::doMonitorShaderFiles

(

)

Calls reloadShaders() if shader files have been modified since the last reload.

Note

This only works if microcode caching is disabled, as there is currently no way to remove the cache through the Ogre API. Luckily, this is already fixed in Ogre 1.9.

getErrorLog()

std::string sh::Factory::getErrorLog

(

)

Returns the error log as a string, then clears it. Note: Errors are also written to the standard error output, or thrown if they are fatal.

listMaterials()

void sh::Factory::listMaterials

(

std::vector< std::string > &

out

)

Lists all materials currently registered with the factory. Whether they are loaded or not does not matter.

registerLodConfiguration()

void sh::Factory::registerLodConfiguration	(	int	index,
		PropertySetGet	configuration
	)

Register a lod configuration, which can then be used by setting up lod distance values for the material
0 refers to highest lod, so use 1 or higher as index parameter

reloadShaders()

bool sh::Factory::reloadShaders

(

)

Note

This only works if microcode caching is disabled, as there is currently no way to remove the cache through the Ogre API. Luckily, this is already fixed in Ogre 1.9.

saveAll()

void sh::Factory::saveAll

(

)

Saves all materials and configurations, by default to the file they were loaded from. If you wish to save them elsewhere, use setSourceFile first.

setGlobalSetting()

void sh::Factory::setGlobalSetting	(	const std::string &	name,
		const std::string &	value
	)

Use this to manage user settings.
Global settings can be retrieved in shaders through a macro.
When a global setting is changed, the shaders that depend on them are recompiled automatically.

setReadMicrocodeCache()

void sh::Factory::setReadMicrocodeCache ( bool  read )

inline

Controls reading of shader microcode from the cache folder. Microcode is machine independent and loads very fast compared to regular compilation. Note that the availability of this feature depends on the Platform.

Note

The default is off (no cache reading)

setReadSourceCache()

void sh::Factory::setReadSourceCache ( bool  read )

inline

Controls reading of generated shader sources from the cache folder

Note

The default is off (no cache reading)

Even if microcode caching is enabled, generating (or caching) the source is still required due to the macros.

setSharedParameter()

void sh::Factory::setSharedParameter	(	const std::string &	name,
		PropertyValuePtr	value
	)

Adjusts the given shared parameter.
Internally, this will change all uniform parameters of this name marked with the macro @shSharedParameter

Parameters

name	of the shared parameter
value	of the parameter, use sh::makeProperty to construct this value

setTextureAlias()

void sh::Factory::setTextureAlias	(	const std::string &	alias,
		const std::string &	realName
	)

Set an alias name for a texture, the real name can then be retrieved with the "texture_alias" property in a texture unit - this is useful if you don't know the name of your texture beforehand.
Example:

• In the material definition: texture_alias ReflectionMap
  
• At runtime: factory->setTextureAlias("ReflectionMap", "rtt_654654");
  You can call factory->setTextureAlias as many times as you want, and if the material was already created, its texture will be updated!

setWriteMicrocodeCache()

void sh::Factory::setWriteMicrocodeCache ( bool  write )

inline

Controls writing the microcode of the generated shaders to the cache folder. Microcode is machine independent and loads very fast compared to regular compilation. Note that the availability of this feature depends on the Platform.

Note

The default is off (no cache writing)

setWriteSourceCache()

void sh::Factory::setWriteSourceCache ( bool  write )

inline

Controls writing of generated shader source code to the cache folder, so that the (rather expensive) preprocessing step can be skipped on the next run. See Factory::setReadSourceCache

Note

The default is off (no cache writing)

unloadUnreferencedMaterials()

void sh::Factory::unloadUnreferencedMaterials

(

)

Unloads all materials that are currently not referenced. This will not unload the textures themselves, but it will let go of the SharedPtr's to the textures, so that you may unload them if you so desire.
A good time to call this would be after a new level has been loaded, but just calling it occasionally after a period of time should work just fine too.

---

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

• Factory.hpp