Unigine.Material Class
This class is used to create materials, which are assigned to each node (or each surface of the object) and define how they look like. They implement the shaders and control what options, states, parameters of different types and textures are used to render the node during the rendering passes.
The materials are referenced via GUID. Only the manual materials can be referenced via name.
The material name (taken from the file name) specifies how the material will be displayed in Materials Editor (the materials hierarchy, the nodes surface editor).
Namespaces#
Materials can be separated into different namespaces to avoid engine and user materials name collision. Default engine and editor materials have their own namespaces (Unigine and Editor respectively). For example, Unigine::mesh_base or
Editor::brush_draw_post.
You can create custom namespaces for your materials. The Material::getNamespaceName() method returns the namespace of a material, if it was assigned to one.
Getting Parameter And Texture Names#
Internal names of the material's textures and parameters are displayed in UnigineEditor tooltips, clicking on the name of the parameter/texture (LMB, once) copies an internal name for it to the clipboard, which allows to easily paste it to the code.
Usage Examples#
Changing Textures#
The first example describes how to inherit a material from a base one, change material's texture and set texture flags for it. We inherit a new material my_mesh_base_0.mat from the mesh_base material, assign it to the default material ball object, change its albedo texture and set the FILTER_POINT flag for it.
Create a new MaterialCustomizer component and add the following code to the MaterialCustomizer.cs file.
Source code (C#)
// MaterialCustomizer.cs
using System;
using System.Collections;
using System.Collections.Generic;
using Unigine;
[Component(PropertyGuid = "some_generated_guid")]
public class MaterialCustomizer : Component
{
// material to be inherited from mesh_base and customized
private Material m;
private void Init()
{
// finding the mesh_base material from the Unigine namespace
Material mesh_base = Materials.FindManualMaterial("Unigine::mesh_base");
if(mesh_base){
// inherit a new material from the mesh_base
m = mesh_base.Inherit();
// get the number of the albedo texture of the inherited material
int num = m.FindTexture("albedo");
// check if our material is editable and perform modifications
if (m.IsEditable)
{
Log.Message("Material ({0}) is editable.\n", m.Path);
// change albedo texture of the material to core/textures/common/checker_d.dds
Image image = new Image("core/textures/common/checker_d.dds");
m.SetTextureImage(num, image);
// get current flags, check if point filtering is enabled and display the result in the console
int flags = m.GetTextureSamplerFlags(num);
Log.Message("Flags for {0} texture ({1}):{2} \n", m.GetTextureName(num), num, flags);
Log.Message("FILTER_POINT {0}\n", (flags & Texture.FILTER_POINT) != 0 ? "enabled" : "disabled");
// set the FILTER_POINT flag
m.SetTextureSamplerFlags(num, Texture.FILTER_POINT);
// get the flags, check if point filtering is enabled and display the result in the console
int flagsSet = m.GetTextureSamplerFlags(num);
Log.Message("Flags for {0} texture ({1}):{2} \n", m.GetTextureName(num), num, flagsSet);
Log.Message("FILTER_POINT {0}\n", (flagsSet & Texture.FILTER_POINT) != 0 ? "enabled" : "disabled");
}
// saving the material asset to the specified path if it doesn't exist yet
if (!Materials.FindMaterialByPath("materials/my_mesh_base_0.mat"))
m.CreateMaterialFile("materials/my_mesh_base_0.mat");
// assigning the my_mesh_base_0 material to the node if it is an object
if(node.IsObject)
(node as Unigine.Object).SetMaterialPath("materials/my_mesh_base_0.mat", "*");
else
Log.Message("The node is not an object.\n");
}
}
private void Update()
{
// write here code to be called before updating each render frame
}
private void Shutdown()
{
// write here code to be called before updating each render frame
m.DeleteLater();
}
}Assign this component to the template_buildings node of the default project template? save the world and click the Play button.
As a result you'll see that albedo texture of the material ball object has changed and the following result is displayed in the console:
Output
Material (my_mesh_base_0) is editable.
Flags for albedo texture (1):2048000
FILTER_POINT disabled
Flags for albedo texture (1):4096
FILTER_POINT enabledChanging States and Parameters#
The second example illustrates how to inherit a material from the mesh_base and change two parameters affecting the look of reflections.
Add the following code to the AppWorldLogic.cs file.
Source code (C#)
// AppWorldLogic.cs
/* .. */
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
/* .. */
public override bool Init()
{
// finding the mesh_base material
Material mesh_base = Materials.FindManualMaterial("Unigine::mesh_base");
// inherit a new material from it
Material reflector_material = mesh_base.Inherit();
// set metallness and roughness parameters to make the surface look like a mirror
// by the name of the parameter
reflector_material.SetParameterFloat("metalness", 1.0f);
// or by its id, which is the same
reflector_material.SetParameterFloat(reflector_material.FindParameter("roughness"), 0.0f);
// save the material asset to planar_reflector.mat file in the data project folder
reflector_material.CreateMaterialFile("planar_reflector.mat");
// assign the mesh_base material to the template_buildings by its path
ObjectMeshStatic material_ball = (World.GetNodeByName("template_buildings") as ObjectMeshStatic);
material_ball.SetMaterialPath("core/materials/base/objects/mesh/mesh_base.basemat", "*");
// assign new reflecting material to the ground object
ObjectMeshDynamic ground = (World.GetNodeByName("ground_plane") as ObjectMeshDynamic);
ground.SetMaterial(reflector_material, "*");
return true;
}
/* .. */
}
}Material Class
Enums
WIDGET#
| Name | Description |
|---|---|
| EDIT_INT = 0 | Text widget enabling you to set an integer value. |
| EDIT_INT2 = 1 | Text widget enabling you to set 2 integer values. |
| EDIT_INT3 = 2 | Text widget enabling you to set 3 integer values. |
| EDIT_INT4 = 3 | Text widget enabling you to set 4 integer values. |
| EDIT_FLOAT = 4 | Text widget enabling you to set a float or integer value. |
| EDIT_FLOAT2 = 5 | Text widget enabling you to set 2 float or integer values. |
| EDIT_FLOAT3 = 6 | Text widget enabling you to set 3 float or integer values. |
| EDIT_FLOAT4 = 7 | Text widget enabling you to set 4 float or integer values. |
| TOGGLE = 8 | Button widget allowing you to enable or disable a certain state. |
| COMBOBOX = 9 | ComboBox widget enabling you to select a texture out of available ones. |
| TEXTURE_ASSET = 10 | Texture asset widget enabling you to specify a texture. |
| TEXTURE_RAMP = 11 | Ramp asset widget enabling you to specify and adjust a 2D Ramp via the dedicated Curve Editor. |
| ACCORDION = 12 | Accordion widget enabling you to expand or collapse a set of widgets it contains. |
| SLIDER = 13 | Slider widget enabling you to specify and adjust a float or integer value. |
| COLOR = 14 | Color widget enabling you to specify a color via a color picker dialog. |
| UV = 15 | UV texture asset widget enabling you to specify a UV texture. |
| MASK24 = 16 | 24-bit mask widget. |
| MASK32 = 17 | 32-bit mask widget. |
DATA_TYPE#
Properties
bool IsEmpty#
The A value indicating if an empty shader is used as a vertex shader in the current material.
bool IsFileEngine#
The value indicating if the material is a core Engine or UnigineEditor material (i.e. required for Engine/Editor operation). Such materials are stored in the core, editor and editor2 folders/packages.
Notice
It is not recommended to delete files of non-core materials (e.g., created by plugins or otherwise) at run-time, as this may affect materials caching and result in a crash.
bool IsAutoSave#
The A value indicating if the material can be saved automatically (automatic material saving is performed, for example, on world's saving). The function will return 0 in the following cases:
- The canSave() function returns 0 for the material.
- The material is non-editable.
- The material GUID is not a valid one.
bool IsManual#
The A value indicating if the current material is manual.
bool IsInternal#
The A value indicating if the current material is internal.
bool IsReflection2D#
The A value indicating if the material has a 2d reflection texture.
bool IsBrush#
The A value indicating if the material is used for brushes (*.brush or *.basebrush file extension).
bool IsBase#
The A value indicating if the material is the base one.
bool IsHidden#
The A value indicating if the material is hidden.
bool IsEditable#
The A value indicating if the material can be edited.
int ViewportMask#
The current bit mask for rendering into the viewport. the material is rendered, if its mask matches the player's one.
bool TwoSided#
The A value indicating if the material is two-sided.
bool IsAlphaTest#
The A value indicating if the material has an alpha test option enabled.
bool IsForward#
The A value indicating if the material is rendered in the forward pass.
bool IsDeferred#
The A value indicating if the material is rendered in the deferred pass.
bool IsWater#
The A value indicating if the material is rendered in the water pass.
int Transparent#
The A value indicating the transparency type of the material.
int NumTextures#
The number of textures used by the material.
int NumStates#
The number of material's states.
int NumParameters#
The number of material's parameters.
string Path#
The A path to the current material.
UGUID GUID#
The GUID of the material.
int NumChildren#
The number of child materials.
Material BaseMaterial#
The base material of the current material.
int Order#
The rendering order of materials.
bool Overlap#
The A value indicating if the overlap option is enabled for the material. this option enables rendering the material over the final image and can be used for ui elements.
bool DepthTest#
The A value indicating if depth testing is enabled for the material. this option can be used to render certain objects, that are behind other ones.
int DepthMask#
The A value indicating if the material uses a depth mask.
int ShadowMask#
The A shadow mask of the material.
For the shadow to be rendered for a light source from an object's surface having this material assigned, this mask must match the following ones (one bit, at least):
- Shadow mask of the light source
- Shadow mask of the surface of the object having this material assigned
bool CastWorldShadow#
The Value indicating if an object with the material applied casts shadows from the world light.
bool CastShadow#
The Value indicating if an object with the material applied casts shadows.
bool IsPreviewHidden#
The true if preview in the UnigineEditor is disabled for the material; otherwise, false.
bool IsLegacy#
The true if the material is a legacy one; otherwise, false.
int BlendSrcFunc#
The source blending function.
int BlendDestFunc#
The destination blending function.
Material Parent#
The parent material.
int NumUIItems#
The number of UI items. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.
string ManualName#
The Manual material name.
string NamespaceName#
The Material namespace.
Members
Material ( ) #
Constructor. Creates a new material instance.Material GetChild ( int num ) #
Returns a child material with a given number.Arguments
- int num - Child material number.
Return value
The child material smart pointer.bool IsParameterExpressionEnabled ( int num ) #
Returns a value indicating if the value of the specified material parameter is represented by an expression in UnigineScript. Values of certain parameters can be calculated by an arbitrary expression, written in UnigineScript. .Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the value of the specified material parameter is represented by an expression in UnigineScript; otherwise, false.void SetParameterExpressionEnabled ( int num, bool enabled ) #
Sets a value indicating if the value of the specified material parameter is represented by an expression in UnigineScript. Values of certain parameters can be calculated by an arbitrary expression, written in UnigineScript. .Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- bool enabled - true to enable setting the values of the specified material parameter by an expression in UnigineScript; false - to disable.
bool IsParameterOverridden ( int num ) #
Returns a value indicating if a given parameter is overridden.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the given parameter is overridden; otherwise, false.bool IsParameterInt ( int num ) #
Returns a value indicating if the parameter with the specified number is an integer-type parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the parameter with the specified number is an integer-type parameter; otherwise, false.bool IsParameterFloat ( int num ) #
Returns a value indicating if the parameter with the specified number is a float-type parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the parameter with the specified number is an float-type parameter; otherwise, false.float GetParameterFloat ( string name ) #
Returns a value of a float parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Float parameter value.vec2 GetParameterFloat2 ( string name ) #
Returns a value of a FLOAT2 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as a vec2 vector.vec3 GetParameterFloat3 ( string name ) #
Returns a value of a FLOAT3 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as a vec3 vector.vec4 GetParameterFloat4 ( string name ) #
Returns a value of a FLOAT4 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as a vec4 vector.int GetParameterInt ( string name ) #
Returns a value of an integer parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Integer parameter value.ivec2 GetParameterInt2 ( string name ) #
Returns a value of a INT2 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as an ivec2 vector.ivec3 GetParameterInt3 ( string name ) #
Returns a value of a INT3 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as an ivec3 vector.ivec4 GetParameterInt4 ( string name ) #
Returns a value of a INT4 parameter with the specified name.Arguments
- string name - Parameter name.
Return value
Parameter value as an ivec4 vector.int GetParameterArraySize ( int num ) #
Returns the number of elements in the array parameter with the specified number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Number of elements of the specified array parameter.bool IsParameterArray ( int num ) #
Returns a value indicating if the parameter with the specified number is an array-type parameter, i.e., one of the following:- PARAMETER_ARRAY_FLOAT
- PARAMETER_ARRAY_FLOAT2
- PARAMETER_ARRAY_FLOAT4
- PARAMETER_ARRAY_INT
- PARAMETER_ARRAY_INT2
- PARAMETER_ARRAY_INT4
Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the parameter is an array-type parameter; otherwise, false.void GetParameterArray ( int num, float[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_FLOAT) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- float[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, float[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_FLOAT) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- float[] values - Array of values to be set.
void GetParameterArray ( int num, vec2[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_FLOAT2) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec2[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, vec2[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_FLOAT2) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec2[] values - Array of values to be set.
void GetParameterArray ( int num, vec4[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_FLOAT4) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, vec4[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_FLOAT4) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4[] values - Array of values to be set.
void GetParameterArray ( int num, int[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_INT) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- int[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, int[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_INT) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- int[] values - Array of values to be set.
void GetParameterArray ( int num, ivec2[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_INT2) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec2[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, ivec2[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_INT2) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec2[] values - Array of values to be set.
void GetParameterArray ( int num, ivec4[] values ) #
Returns a value of the array parameter (type: PARAMETER_ARRAY_INT4) with the specified number and puts it to the specified buffer array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec4[] values - Buffer array to store parameter values.
void SetParameterArray ( int num, ivec4[] values ) #
Sets a value of the array parameter (type: PARAMETER_ARRAY_INT4) with the specified number using the specified array.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec4[] values - Array of values to be set.
int SetParameterExpression ( int num, string expression ) #
Sets the expression used as a parameter value.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- string expression - New expression.
Return value
1 if the expression is set successfully; otherwise, 0.string GetParameterExpression ( int num ) #
Returns an expression used as a parameter value.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Parameter expression, if it exists; otherwise, NULL (0).string GetParameterName ( int num ) #
Returns the name of a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Parameter name.void SetParameterFloat ( int num, float value ) #
Sets the value of a given float parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- float value - Parameter value to be set.
void SetParameterFloat ( string name, float value ) #
Sets the value of a given float parameter by its name.Arguments
- string name - Name of the target float parameter.
- float value - Parameter value to be set.
float GetParameterFloat ( int num ) #
Returns the current value of a given float parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterFloat2 ( int num, vec2 value ) #
Sets the value of a given float2 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec2 value - Parameter value to be set.
void SetParameterFloat2 ( string name, vec2 value ) #
Sets the value of a given float2 parameter by its name.Arguments
- string name - Name of the target float2 parameter.
- vec2 value - Parameter value to be set.
vec2 GetParameterFloat2 ( int num ) #
Returns the current value of a given float2 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterFloat3 ( int num, vec3 value ) #
Sets the value of a given float3 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec3 value - Parameter value to be set.
void SetParameterFloat3 ( string name, vec3 value ) #
Sets the value of a given float3 parameter by its name.Arguments
- string name - Name of the target float3 parameter.
- vec3 value - Parameter value to be set.
vec3 GetParameterFloat3 ( int num ) #
Returns the current value of a given float3 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterFloat4 ( int num, vec4 value ) #
Sets the value of a given float4 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4 value - Parameter value to be set.
void SetParameterFloat4 ( string name, vec4 value ) #
Sets the value of a given float4 parameter by its name.Arguments
- string name - Name of the target float4 parameter.
- vec4 value - Parameter value to be set.
vec4 GetParameterFloat4 ( int num ) #
Returns the current value of a given float4 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterInt ( int num, int value ) #
Sets the value of a given int parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- int value - Parameter value to be set.
void SetParameterInt ( string name, int value ) #
Sets the value of a given int parameter by its name.Arguments
- string name - Name of the target int parameter.
- int value - Parameter value to be set.
int GetParameterInt ( int num ) #
Returns the current value of a given int parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterInt2 ( int num, ivec2 value ) #
Sets the value of a given int2 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec2 value - Parameter value to be set.
void SetParameterInt2 ( string name, ivec2 value ) #
Sets the value of a given int2 parameter by its name.Arguments
- string name - Name of the target int2 parameter.
- ivec2 value - Parameter value to be set.
ivec2 GetParameterInt2 ( int num ) #
Returns the current value of a given int2 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterInt3 ( int num, ivec3 value ) #
Sets the value of a given int3 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec3 value - Parameter value to be set.
void SetParameterInt3 ( string name, ivec3 value ) #
Sets the value of a given int3 parameter by its name.Arguments
- string name - Name of the target int3 parameter.
- ivec3 value - Parameter value to be set.
ivec3 GetParameterInt3 ( int num ) #
Returns the current value of a given int3 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void SetParameterInt4 ( int num, ivec4 value ) #
Sets the value of a given int4 parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- ivec4 value - Parameter value to be set.
void SetParameterInt4 ( string name, ivec4 value ) #
Sets the value of a given int4 parameter by its name.Arguments
- string name - Name of the target int4 parameter.
- ivec4 value - Parameter value to be set.
ivec4 GetParameterInt4 ( int num ) #
Returns the current value of a given int4 parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.int GetParameterType ( int num ) #
Returns the type of a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
One of the PARAMETER_* pre-defined variables or -1, if an error has occurred.bool IsParent ( UGUID guid ) #
Returns a value indicating if the material with the given GUID is a parent of the current material.Arguments
- UGUID guid - Material GUID.
Return value
true if the material is the parent; otherwise, false.bool CheckShaderCache ( ) #
Returns a value indicating if shader combination for current material states and options is already in cache.Return value
1 if shader combination for current material states and options is already in cache; otherwise, 0.bool CheckShaderCache ( Render.PASS pass, Node.TYPE node_type ) #
Returns a value indicating if shader combination for the given rendering pass and node type is already in cache.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node.TYPE node_type - Node type.
Return value
1 if shader combination for the given rendering pass and node type is already in cache; otherwise, 0.bool CompileShader ( Render.PASS pass, Node.TYPE node_type ) #
Compiles shader combination for the given rendering pass and node type.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node.TYPE node_type - Node type.
Return value
1 if shader combination for the given rendering pass and node type was compiled successfully; otherwise, 0.Shader FetchShader ( Render.PASS pass ) #
Returns the rendering shader for the specified rendering pass.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
Return value
Shader for the specified rendering pass.Shader FetchShader ( Render.PASS pass, Node.TYPE node_type ) #
Returns the rendering shader for the specified rendering pass and node type.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node.TYPE node_type - Node type.
Return value
Shader for the specified rendering pass and node type.Shader FetchShader ( string pass_name ) #
Returns the rendering shader for the specified rendering pass.Arguments
- string pass_name - Rendering pass name. One of the following:
- wireframe
- visualizer_solid
- deferred
- auxiliary
- emission
- reflection
- refraction
- transparent_blur
- ambient
- light_voxel_probe
- light_environment_probe
- light_omni
- light_proj
- light_world
- shadow
- depth_pre_pass
- post
- object_post
Return value
Shader for the specified rendering pass.Shader FetchShader ( string pass_name, int node ) #
Returns the rendering shader for the specified rendering pass and node type.Arguments
- string pass_name - Rendering pass name. One of the following:
- wireframe
- visualizer_solid
- deferred
- auxiliary
- emission
- reflection
- refraction
- transparent_blur
- ambient
- light_voxel_probe
- light_environment_probe
- light_omni
- light_proj
- light_world
- shadow
- depth_pre_pass
- post
- object_post
- int node - Node type.
Return value
Shader for the specified rendering pass and node type.bool IsStateInternal ( int num ) #
Returns a value indicating if a given state is internal.Arguments
- int num - State number.
Return value
true if the given state is internal; otherwise, false.bool IsStateOverridden ( int num ) #
Returns a value indicating if a given state is overridden.Arguments
- int num - State number.
Return value
1 if the given state is overridden; otherwise, 0.void SetState ( int num, int value ) #
Sets the state value.Arguments
- int num - State number.
- int value - State value to be set.
void SetState ( string name, int value ) #
Sets the value of the given state.Arguments
- string name - State name.
- int value - State value.
int GetState ( int num ) #
Returns the state value.Arguments
- int num - State number.
Return value
State value.int GetState ( string name ) #
Returns the value of the given state.Arguments
- string name - State name.
Return value
State value.string GetStateName ( int num ) #
Returns the name of a given state.Arguments
- int num - State number.
Return value
State name.string GetStateSwitchItem ( int num, int item ) #
Returns the switch item name for a given state.Arguments
- int num - State number.
- int item - Item number.
Return value
Switch item name or NULL (0), if an error has occurred.int GetStateSwitchNumItems ( int num ) #
Returns the number of switch items for a given state.Arguments
- int num - State number.
Return value
Number of switch items.int GetStateType ( int num ) #
Returns the type of a given state.Arguments
- int num - State number.
Return value
One of the MATERIAL_STATE_* pre-defined variables or -1, if an error occurred.bool IsTextureInternal ( int num ) #
Returns a value indicating if a given texture is internal.Arguments
- int num - Texture number.
Return value
true if the given texture is internal; otherwise, false.bool IsTextureOverridden ( int num ) #
Returns a value indicating if a given texture is overridden.Arguments
- int num - Texture number.
Return value
true if the given texture is overridden; otherwise, false.bool IsTextureLoaded ( int num ) #
Returns a value indicating if a given texture is loaded.Arguments
- int num
Return value
true if the given texture is loaded; otherwise, false.string GetTextureName ( int num ) #
Returns the name of a given texture.Arguments
- int num - Texture number.
Return value
Texture name.int GetTextureUnit ( int num ) #
Returns the number of the unit for a given texture used in shaders.Arguments
- int num - Texture number.
Return value
Texture unit number.int GetTextureSource ( int num ) #
Returns the source for the texture with the specified number.Arguments
- int num - Texture number.
Return value
One of the TEXTURE_SOURCE_* pre-defined variables or -1, if an error occurred.Texture GetTexture ( string name ) #
Returns the texture used in the material by its name.Arguments
- string name - Name of the desired texture (e.g., albedo, emission, etc.).
Return value
Texture used with the requested name.int FindParameter ( string name ) #
Searches for a parameter by a given name among all parameters of the current material.Arguments
- string name - Parameter name.
Return value
Parameter number, if it is found; otherwise, -1.int FindState ( string name ) #
Searches for a state by a given name among all states of the current material.Arguments
- string name - State name.
Return value
State number, if it is found; otherwise, -1.int FindTexture ( string name ) #
Searches for a texture by a given name among all textures used by the current material.Arguments
- string name - Texture name.
Return value
Texture number, if it is found; otherwise, -1.bool SaveState ( Stream stream, bool forced = 0 ) #
Saves the settings of a given material (all of its options, states and parameters) into a binary stream.Saving into the stream requires creating a blob to save into. To restore the saved state the RestoreState() method is used:
Source code (C#)
// initialize object
Material mat = obj.GetMaterial(0);
mat.ViewportMask = 1; // viewport mask = 1
// save state
Blob blob_state = new Blob();
mat.SaveState(blob_state, true);
// change the state
mat.ViewportMask = ~0; // now viewport mask = 111111111
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
mat.RestoreState(blob_state, true); // restore viewport mask = 1Arguments
- Stream stream - The stream to save material state data.
- bool forced - Forced saving of material settings.
Return value
true if the material settings are saved successfully; otherwise, true.bool RestoreState ( Stream stream, bool forced = 0 ) #
Restores the state of a given material (all of its options, states and parameters) from a binary stream.Restoring from the stream requires creating a blob to save into and saving the state using the SaveState() method:
Source code (C#)
// initialize object
Material mat = obj.GetMaterial(0);
mat.ViewportMask = 1; // viewport mask = 1
// save state
Blob blob_state = new Blob();
mat.SaveState(blob_state, true);
// change the state
mat.ViewportMask = ~0; // now viewport mask = 111111111
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
mat.RestoreState(blob_state, true); // restore viewport mask = 1Arguments
- Stream stream - The stream with saved material data.
- bool forced - Forced restoring of material settings.
Return value
true if the material settings are restored successfully; otherwise, false.bool CanRenderNode ( ) #
Returns a value indicating if the marial can be rendered for at least one type of nodes.Return value
true if the material is rendered for at least one type of nodes; otherwise, false.void ResetState ( int num ) #
Resets the overridden value of the given state to the parent one.Arguments
- int num - State number.
void SetTexturePath ( int num, string path ) #
Sets a new path to the texture with the given number.Arguments
- int num - Texture number.
- string path - A path to the texture or NULL to clear the path.
void SetTexturePath ( string name, string path ) #
Sets a new path to the texture with the given name.Arguments
- string name - Texture name.
- string path - A path to the texture or NULL to clear the path.
void ResetTexture ( int num ) #
Resets the overridden value of the given texture to the parent one.Arguments
- int num - Texture number.
string GetTexturePath ( int num ) #
Returns a path to the texture with the specified number.Arguments
- int num - Texture number.
Return value
A path to the texture.string GetTexturePath ( string name ) #
Returns a path to the texture with the specified name.Arguments
- string name - Texture name.
Return value
A path to the texture.bool IsNodeTypeSupported ( Node.TYPE type ) #
Returns a value indicating if the given type of nodes is supported by the material.Arguments
Return value
true if the node type is supported; otherwise, false.bool SetParent ( Material material, bool save_all_values = 1 ) #
Sets the given material as the parent for this material and saves the material's properties values (if the corresponding flag is set).Arguments
- Material material - Material to be set as the parent for this material.
- bool save_all_values - Flag indicating if the material's properties will be saved after reparenting.
Return value
true if the material's parent is changed; otherwise, false.bool CheckTextureConditions ( int num ) #
Checks if conditions set for the given texture are met.Arguments
- int num - Texture number.
Return value
true if conditions are met; otherwise, false.bool LoadXml ( Xml xml ) #
Loads material settings from the specified Xml source.Arguments
- Xml xml - An Xml node containing material settings.
Return value
true if the material settings are loaded successfully; otherwise, false.bool LoadUlon ( UlonNode ulon ) #
Loads material settings from the specified ULON source.Arguments
- UlonNode ulon - A ULON-node containing material settings.
Return value
true if the material settings are loaded successfully; otherwise, false.bool HasOverrides ( ) #
Returns a value indicating if the material has at least one overridden property.Return value
true if the material has at least one overridden property; otherwise, false.bool CanSave ( ) #
Returns a value indicating if the material can be saved. For example, this function will return 0 for a base or manual material.Return value
true if the material can be saved; otherwise, false.bool CheckStateConditions ( int num ) #
Checks if conditions set for the given state are met.Arguments
- int num - State number.
Return value
true if conditions are met; otherwise, false.bool CheckParameterConditions ( int num ) #
Checks if conditions set for the given parameter are met.Arguments
- int num - Parameter name.
Return value
true if conditions are met; othersiwe, false.bool Save ( ) #
Save the material to the current path used for this material.Return value
true if the material is saved successfully; otherwise, false.bool Load ( string path ) #
Loads a material from the given file. 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 file.
Return value
true if the material is loaded successfully; otherwise, false.bool SaveXml ( Xml xml ) #
Saves the material into the given Xml.Arguments
- Xml xml - An Xml node.
Return value
true if the material is saved successfully; otherwise, false.bool IsNodeSupported ( Node node ) #
Returns a value indicating if the material can be applied to the given node.Arguments
- Node node - A node.
Return value
true if the given node is supported; otherwise, false.void SetTexture ( int num, Texture texture ) #
Sets the given texture to the texture with the specified number.Arguments
- int num - Texture number.
- Texture texture - Texture to be set.
void SetTexture ( string name, Texture texture ) #
Sets the given texture to the texture with the specified name.Arguments
- string name - Texture name (one of the textures used by the material, e.g.: albedo).
- Texture texture - Texture to be set.
Texture GetTexture ( int num ) #
Returns a texture set for the current material.Arguments
- int num - Texture number.
Return value
A texture.void ResetParameter ( int num ) #
Resets the overridden value of the given parameter to the parent one.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
bool Reload ( ) #
Reloads the material and all its children.Return value
true if the material is reloaded successfully; otherwise, false.int SetTextureImage ( int num, Image image ) #
Set a given image to a given texture.Arguments
- int num - Texture number.
- Image image - An image to set.
Return value
1 if the image is set successfully; otherwise, 0.int GetTextureImage ( int num, Image image ) #
Reads a given texture into a given image.Arguments
- int num - Texture number.
- Image image - An image.
Return value
1 if the texture is read successfully; otherwise, 0.TextureRamp GetTextureRamp ( int num ) #
Returns a ramp texture instance for the data stored in the specified ramp texture (gradient).Notice
Modifications made to the ramp shall propagate to the parent and sibling materials. To modify an overridden ramp for this material only use the getTextureRampOverride() method.
Arguments
- int num - Texture number.
Return value
TextureRamp class instance for the data stored in the gradient texture with the specified number.TextureRamp GetTextureRampOverride ( int num ) #
Returns a new ramp texture instance for the data stored in the specified ramp texture (gradient) overriding the default one. This method enables you to set individual RGBA curves, adjusting color values of the resulting ramp texture (gradient).Notice
Modifications made to the ramp shall not propagate to the parent and sibling materials.
Arguments
- int num - Texture number.
Return value
New TextureRamp class instance overriding the data stored in the specified ramp texture (gradient).void CreateShaders ( bool recursive = 0 ) #
Creates all shaders for the current material and its children (if specified).Arguments
- bool recursive - true to create shaders for child materials of the current material; otherwise, false.
void DestroyTextures ( ) #
Deletes all textures used by the current material and its children.Render.PASS GetRenderPass ( string pass_name ) #
Returns the type of the rendering pass by its name (including custom passes).Arguments
- string pass_name - Name of the rendering pass.
Return value
Rendering pass number in the range from 0 to 18 + custom_passes_number, if it exists; otherwise -1.string GetRenderPassName ( Render.PASS type ) #
Returns the name of the rendering pass by its number (including custom passes).Arguments
- Render.PASS type - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
Return value
Rendering pass name if it exists; otherwise NULL.bool RunExpression ( string name, int w, int h, int d = 1 ) #
Runs the material's expression with the specified name. An expression is a reference to a file containing code in UnigineScript, that can generate various elements used in the material (e.g., textures, texture arrays, unstructured buffers, etc.) or contain other logic. Expressions can be defined in the *.basemat file as follows:Source code (ULON)
Expression name = "expression.usc";An example of expression.usc code:
Source code (UnigineScript)
// typical most frequently used parameters passed to the expression automatically, when it is called.
int in_width;
int in_height;
int in_depth;
Material in_material;
// If you need extra parameters, you should set them via Material::setParameter*("param_name", value) before calling Material::runExpression()
// then you can access them in the expression via in_material.getParameter*("param_name")
// ...
// get a temporary texture
Texture texture = engine.render.getTemporaryTexture(in_width, in_height);
//get the value of the material parameter named "my_extra_param"
float my_param = in_material.getParameter("my_extra_param");
// modify the temporary texture using the my_param parameter somehow...
// set the modified texture as albedo texture of the material
in_material->setTexture("albedo", texture);To execute this expression the following code can be used:
Source code (C++)
// ...
// setting the value of extra parameter
material->setParameterFloat("my_extra_param", 2.5f);
// running the expression
material->runExpression("expr_name", 512, 512, 1);
// ...Notice
Expressions can be executed only for base materials.
Arguments
- string name - Expression name. Expression with this name must be defined in the material declaration (*.basemat file).
- int w - Width, e.g. if a texture or a structured buffer is generated by the expression.
- int h - Height, e.g. if a texture or a structured buffer is generated by the expression.
- int d - Depth, e.g. if a 3D Texture, 2D array or a structured buffer is generated by the expression.
Return value
1 if the specified expression is executed successfully; otherwise, 0.bool RenderScreen ( string pass_name ) #
Renders the screen-space material. The material must have a shader for the specified pass associated with it.Arguments
- string pass_name - Name of the rendering pass.
Return value
0 if the specified pass was not found; otherwise, 1.void RenderScreen ( Render.PASS pass ) #
Renders the screen-space material. The material must have a shader for the specified pass associated with it.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
bool RenderCompute ( string pass_name, int group_threads_x = 1, int group_threads_y = 1, int group_threads_z = 1 ) #
Renders the material using a compute shader. The material must have a compute shader for the specified pass associated with it.Arguments
- string pass_name - Name of the rendering pass.
- int group_threads_x - Local X work-group size of the compute shader.
- int group_threads_y - Local Y work-group size of the compute shader.
- int group_threads_z - Local Z work-group size of the compute shader.
Return value
true if the specified pass was not found; otherwise, false.void RenderCompute ( Render.PASS pass, int group_threads_x = 1, int group_threads_y = 1, int group_threads_z = 1 ) #
Renders the material using a compute shader. The material must have a compute shader for the specified pass associated with it.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- int group_threads_x - Local X work-group size of the compute shader.
- int group_threads_y - Local Y work-group size of the compute shader.
- int group_threads_z - Local Z work-group size of the compute shader.
Material.DATA_TYPE GetUIItemDataType ( int item ) #
Returns the type of data of the specified UI item. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
UI item data type (parameter, option, state, texture, or group).int GetUIItemDataID ( int item ) #
Returns the id of the data type controlled by the specified UI item. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
UI item data id: one of the STATE_*, PARAMETER_*, OPTION_*, TEXTURE_SOURCE_* pre-defined variables or -1, if an error has occurred.bool IsUIItemHidden ( int item ) #
Returns a value indicating if the specified UI item is hidden.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
true is the specified UI item is hidden; otherwise, false.string GetUIItemTitle ( int item ) #
Returns the title set for the specified UI item.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Title set for the specified UI item.string GetUIItemTooltip ( int item ) #
Returns the text of the tooltip set for the specified UI item.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Text of the tooltip set for the specified UI item.Material.WIDGET GetUIItemWidget ( int item ) #
Returns the type of the widget for the specified UI item.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
UI item widget type.int GetUIItemParent ( int item ) #
Returns an index of the parent of the specified UI item. This method is used to get the index of the group to which the specified parameter/state/option/texture belongs.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Global index of the parent UI element in the range from 0 to the total number of UI items for the material.int GetUIItemNumChildren ( int item ) #
Returns the number of child items for the group UI item with the specified number.Notice
This method is to be used for UI item groups only (DATA_TYPE_GROUP), other items cannot have children!
Arguments
- int item - UI item group index in the range from 0 to the total number of UI items.
Return value
Number of child items for the specified group UI item.int GetUIItemChild ( int item, int num ) #
Returns the index of a child UI item that belongs to the specified group by the item number within the group.Notice
This method is to be used for UI item groups only (DATA_TYPE_GROUP), other items cannot have children!
Arguments
- int item - UI item group index in the range from 0 to the total number of UI items.
- int num - Number of UI item within the group (in the list of children).
Return value
Global index of the child UI element in the range from 0 to the total number of UI items for the material.bool IsUIItemSliderMinExpand ( int item ) #
Returns a value indicating if the maximum slider value for the specified UI item can be increased.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
true if the maximum value can be increased; otherwise, false.bool IsUIItemSliderMaxExpand ( int item ) #
Returns a value indicating if the minimum slider value for the specified UI item can be decreased.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
true if the minimum value can be decreased; otherwise, false.float GetUIItemSliderMinValue ( int item ) #
Returns the minimum allowed value of the slider for the specified UI item.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Minimum value of the slider.float GetUIItemSliderMaxValue ( int item ) #
Returns the maximum allowed value of the slider for the specified UI item.Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Maximum value of the slider.int GetUIItemGroupToggleStateID ( int item ) #
Returns the global index of the state toggle UI element turning the specified group on and off.Notice
This method is to be used for UI item groups only (DATA_TYPE_GROUP)!
Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
Global index of the state toggle UI element in the range from 0 to the total number of UI items for the material.bool IsUIItemGroupCollapsed ( int item ) #
Returns a value indicating if the specified group of UI items is currently collapsed in the UI of the Unigine Editor.Notice
This method is to be used for UI item groups only (DATA_TYPE_GROUP)!
Arguments
- int item - UI item index in the range from 0 to the total number of UI items.
Return value
true if the specified group of UI items is currently collapsed in the UI; otherwise, false (the group is expanded).void SetOption ( int num, int value ) #
Sets a new value for the specified option.Arguments
- int num - Option number.
- int value - New value to be set for the specified option.
int GetOption ( int num ) #
Returns the current value of the specified option.Arguments
- int num - Option number.
Return value
Current value of the specified option.bool IsOptionOverridden ( int num ) #
Returns a value indicating if a given option is overridden.Arguments
- int num - Option number.
Return value
true if the given option is overridden; otherwise, false.void ResetOption ( int num ) #
Resets the overridden value of the given option to the parent one.Arguments
- int num - Option number.
bool IsParent ( Material parent ) #
Returns a value indicating if the given material is a parent of the current material.Arguments
- Material parent - Material instance.
Return value
true if the material is the parent, otherwise - false.Material Clone ( ) #
Clones the material. The cloned material will be empty: it will have a GUID but won't be displayed in the materials hierarchy.Return value
Cloned material.Material Clone ( UGUID guid ) #
Clones the material and assigns the given GUID to it.Notice
A base material cannot be cloned.
Arguments
- UGUID guid - Cloned material GUID.
Return value
Cloned material.Material Inherit ( ) #
Inherits the material. The inherited material will be empty: it will have a GUID but won't be displayed in materials hierarchy.Return value
Inherited material.Material Inherit ( UGUID guid ) #
Inherits a new material from the current one and assigns the specified GUID to it.Arguments
- UGUID guid - Inhereted material GUID.
Return value
Inhereted material.string GetNamespaceName ( ) #
Returns the namespace where this material is defined.Return value
Material namespace.string GetManualName ( ) #
Returns the name of the manual material.Return value
Manual material name.string WidgetToString ( Material.WIDGET widget ) #
Returns the name of the widget by its type.Arguments
- Material.WIDGET widget - Widget type.
Return value
Name of the widget.Material.WIDGET StringToWidget ( string str ) #
Returns the widget type by its name.Arguments
- string str - Name of the widget.
Return value
Widget type.int GetTextureSamplerFlags ( int num ) #
Returns the sampler flags of the texture with the given number.Arguments
- int num - Number of the texture.
Return value
Texture sampler flags.void SetTextureSamplerFlags ( int num, int sampler_flags ) #
Sets the sampler flags for the texture with the given number.Arguments
- int num - Number of the texture.
- int sampler_flags - Sampler flags.
int GetTextureFormatFlags ( int num ) #
Returns the format flags of the texture with the given number.Arguments
- int num - Number of the texture.
Return value
Texture format flags.bool CreateMaterialFile ( string path ) #
Creates a file and saves the internal material to it.Arguments
- string path - A path to save the material
Return value
The value indicating if the material was successful saved.bool IsReflection2D ( ) #
Last update:
2022-12-14
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)