engine.materials Functions
Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.
Interface for managing loaded materials via the code.
All materials existing in the project are preloaded at Engine initialization depending on the materials preload mode specified by the materials_preload console command (enabled by default) and saved on world's saving or on calling the materials_save console command.
See Also#
- C++ API sample located in the folder <UnigineSDK>/source/samples/Api/Systems/Materials
Materials Class
Members
void setPrecompileAllShaders ( int shaders ) #
Sets a new value indicating if shader precompilation is enabled.
Arguments
- int shaders - The shader precompilation
int isPrecompileAllShaders() const#
Returns the current value indicating if shader precompilation is enabled.
Return value
Current shader precompilationint getNumMaterials() const#
Returns the current number of materials loaded for the current project.
Return value
Current number of materials.static getEventEndReload() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.static getEventBeginReload() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.bool isShadersCompiling() const#
Returns the current
Return value
true if is enabled; otherwise false.Material engine.materials.loadMaterial ( string path ) #
Loads a material stored by the given path. The function can be used to load materials created during application execution or stored outside the data directory.Arguments
- string path - A path to the material (including its name).
Return value
A loaded material.int engine.materials.isMaterialGUID ( UGUID guid ) #
Returns a value indicating if a material with the specified GUID exists.Arguments
Return value
1 if the material with the specified GUID exists; otherwise, 0.Material engine.materials.getMaterial ( int num ) #
Returns the material by its number.Arguments
- int num - Material number.
Return value
A material.Material engine.materials.findManualMaterial ( string name ) #
Searches for a manual material by the given name.Arguments
- string name - A manual material name.
Return value
A manual material instance.Material engine.materials.findMaterialByGUID ( UGUID guid ) #
Searches for a material with the given GUID.Arguments
Return value
A material instance.Material engine.materials.findMaterialByFileGUID ( UGUID guid ) #
Searches for a material with the given GUID of a material file.Arguments
Return value
A material instance.Material engine.materials.findMaterialByPath ( string path ) #
Searches for a material stored by the specified path.Arguments
- string path - A loading path of the material (including a material's name).
Return value
A material instance.void engine.materials.setCachedMaterial ( Material mat ) #
Sets the material to be modified in runtime. This method is used together with setCachedState and getCachedMaterial() to change the material state in runtime without the necessity to recalculate the materials every frame and recompile the shaders. Using these methods is highly recommended if the material states are changed almost every frame or several times per frame.Let's review an example use case that can make use of these methods. Assume that you have a performance-consuming material and you want to reduce its quality when it's rendered in reflections. The following pseudo code demonstrates the approach to using these methods:
Source code
MaterialPtr get_effect_material(bool quality)
{
Materials::setCachedMaterial(my_effect);
Materials::setCachedState("quality", quality);
return Material::getCachedMaterial();
}
// switching quality of material depending on where it's rendered
void event()
{
bool quality = true;
if (Renderer::isReflection())
quality = false;
MaterialPtr mat = get_effect_material(quality);
}Arguments
- Material mat - The material to be modified in runtime.
Material engine.materials.getCachedMaterial ( ) #
Returns the material modified in runtime. This method is used together with setCachedMaterial() and setCachedState to change the material state in runtime without the necessity to recalculate the materials every frame and recompile the shaders. Using these methods is highly recommended if the material states are changed almost every frame or several times per frame.Let's review an example use case that can make use of these methods. Assume that you have a performance-consuming material and you want to reduce its quality when it's rendered in reflections. The following pseudo code demonstrates the approach to using these methods:
Source code
MaterialPtr get_effect_material(bool quality)
{
Materials::setCachedMaterial(my_effect);
Materials::setCachedState("quality", quality);
return Material::getCachedMaterial();
}
// switching quality of material depending on where it's rendered
void event()
{
bool quality = true;
if (Renderer::isReflection())
quality = false;
MaterialPtr mat = get_effect_material(quality);
}Return value
The material modified in runtime.void engine.materials.setCachedState ( string name, int value ) #
Sets the target state for the material to modify it in runtime. This method is used together with setCachedMaterial() and getCachedMaterial() to change the material state in runtime without the necessity to recalculate the materials every frame and recompile the shaders. Using these methods is highly recommended if the material states are changed almost every frame or several times per frame.Let's review an example use case that can make use of these methods. Assume that you have a performance-consuming material and you want to reduce its quality when it's rendered in reflections. The following pseudo code demonstrates the approach to using these methods:
Source code
MaterialPtr get_effect_material(bool quality)
{
Materials::setCachedMaterial(my_effect);
Materials::setCachedState("quality", quality);
return Material::getCachedMaterial();
}
// switching quality of material depending on where it's rendered
void event()
{
bool quality = true;
if (Renderer::isReflection())
quality = false;
MaterialPtr mat = get_effect_material(quality);
}Arguments
- string name - The name of the state to be changed.
- int value - The target state value.
int engine.materials.removeMaterial ( UGUID guid, int remove_file = 0, int remove_children = 1 ) #
Deletes a material. If the remove_file flag is enabled, the material file will be deleted as well. If the flag is disabled, the deleted material will be loaded again on the next application start-up. If the remove_children flag is enabled, all the children of the material will be deleted as well.Arguments
- UGUID guid - GUID of the material to be removed.
- int remove_file - Flag indicating if the material file will be deleted.
- int remove_children - Flag indicating if all the children of the material will be also deleted.
Return value
1 if the material is deleted successfully; otherwise, 0.int engine.materials.replaceMaterial ( Material material, Material new_material ) #
Replaces the material with the given one.Arguments
Return value
1 if the material is replaced successfully; otherwise, 0.int engine.materials.saveMaterials ( ) #
Saves changes made for all loaded materials.Return value
1 if materials are saved successfully; otherwise, 0.void engine.materials.reloadMaterials ( ) #
Reloads all loaded materials.void engine.materials.destroyShaders ( ) #
Deletes all shaders used for the loaded materials.void engine.materials.destroyTextures ( ) #
Deletes all textures used by the loaded materials.void engine.materials.createShaders ( ) #
Creates all shaders for all loaded materials.void engine.materials.createRenderMaterials ( ) #
Creates render materials (internal materials required for rendering). For example, you can create all necessary render materials during initialization to avoid spikes that may occur later.void engine.materials.createShaderCache ( ) #
Creates shader cache for all loaded materials.void engine.materials.createShadersFromCache ( ) #
Compiles the shaders available in the shader cache.int engine.materials.isShadersCompiling ( ) #
Returns a value indicating if asynchronous compilation is being performed.Return value
1 if asynchronous compilation is being performed; otherwise, 0.void engine.materials.flushShadersCompiling ( ) #
Force-compiles all shaders that are queued for the asynchronous compilation.The information on this page is valid for UNIGINE 2.20 SDK.
Last update:
2025-03-04
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)