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 concepts of a path and a name of the material should be distinguished:
- The path specifies where the material is stored on the disk. The path includes a material file name.
- The name specifies how the material will be displayed in Materials Editor (the materials hierarchy, the nodes surface editor). The name can also be used to reference material from 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 named material_ball_0 from the material_ball material, assign it to the default material ball object, change its albedo texture and set the FILTER_POINT flag for it.
Add the following code to the AppWorldLogic.cs file.
// AppWorldLogic.cs
/* .. */
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
/* .. */
public override int init()
{
// inherit a new material from the material_ball
Material m = Materials.get().findMaterial("material_ball").inherit("material_ball_0");
// getting the material_ball object and assigning the material_ball_0 material to it
ObjectMeshStatic material_ball = ObjectMeshStatic.cast(Editor.get().getNodeByName("material_ball"));
material_ball.setMaterial("material_ball_0", "*");
// get the number of the albedo texture of the material_ball_0 material
int num = m.findTexture("albedo");
// check if our material is editable and perform modifications
if (m.isEditable() == 1)
{
Log.message("Material ({0}) is editable.\n", m.getName());
// 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.getTextureFlags(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.setTextureFlags(num, Texture.FILTER_POINT);
// get the flags, check if point filtering is enabled and display the result in the console
int flagsSet = m.getTextureFlags(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");
}
return 1;
}
/* .. */
}
}
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:
Material (material_ball_0) is editable.
Flags for albedo texture (1):2048000
FILTER_POINT disabled
Flags for albedo texture (1):4096
FILTER_POINT enabled
Changing States and Parameters#
The second example illustrates how to inherit a material from the mesh_base, enable the planar reflection state and change two parameters affecting the look of dynamic reflections.
Add the following code to the AppWorldLogic.cs file.
// AppWorldLogic.cs
/* .. */
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
/* .. */
public override int init()
{
// find the mesh_base material
Material mesh_base = Materials.get().findMaterial("mesh_base");
// inherit a new material from it
Material reflector_material = mesh_base.inherit("planar_reflector", "unigine_project/materials/planar_reflector.mat");
// enable planar reflections for the mirror material
reflector_material.setState("planar_reflection", 1);
// set metallness and roughness parameters to make the surface look like a mirror
reflector_material.setParameterSlider(reflector_material.findParameter("metalness"), 1.0f);
reflector_material.setParameterSlider(reflector_material.findParameter("roughness"), 0.0f);
// assign the mesh_base material to the material ball
ObjectMeshStatic material_ball = ObjectMeshStatic.cast(Editor.get().getNodeByName("material_ball"));
material_ball.setMaterial("mesh_base","*");
// assign new mirror material to the ground object
ObjectMeshDynamic ground = ObjectMeshDynamic.cast(Editor.get().getNodeByName("ground"));
ground.setRotation(new quat(90.0f, 90.0f, 0.0f));
ground.setMaterial("planar_reflector", 0);
// enable planar reflections rendering using the corresponding console command (render_reflection_dynamic)
Unigine.Console.get().run("render_reflection_dynamic 1");
return 1;
}
/* .. */
}
}
Material Class
Properties
bool IsEmpty#
bool IsEngine#
bool IsAutoSave#
- The canSave() function returns 0 for the material.
- The material is non-editable.
- The path isn't specified for the material.
bool IsManual#
bool IsInternal#
bool IsReflection2D#
bool IsProcedural#
bool IsBrush#
bool IsBase#
bool IsHidden#
bool IsFilter#
bool IsEditable#
int ViewportMask#
int TwoSided#
bool IsAlphaTest#
bool IsForward#
bool IsDeferred#
bool IsWater#
int Transparent#
int NumTextures#
int NumStates#
int NumParameters#
UGUID FileGUID#
string Path#
UGUID GUID#
string Name#
int NumChildren#
Material BaseMaterial#
Material Parent#
int Order#
int Offset#
int Overlap#
int DepthTest#
int DepthMask#
int ShadowMask#
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
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
int CastWorldShadow#
int CastShadow#
Members
static Material ( ) #
Constructor. Creates a new material instance.int GetBlendDestFunc ( ) #
Returns the destination blending function.Return value
The destination blending function (one of the BLEND_* variables).void SetBlendFunc ( int src, int dest ) #
Sets the source and destination blending functions.Arguments
- int src - Blend mode (one of the MATERIAL_BLEND_* variables) for the source color.
- int dest - Blend mode (one of the MATERIAL_BLEND_* variables) for the destination color.
int GetBlendSrcFunc ( ) #
Returns the source blending function.Return value
The source blending function (one of the BLEND_*values described in the State class).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.void SetImageTextureProcedural ( int num, Material procedural, int procedural_num ) #
Assigns the procedural texture of the given procedural material to the specified texture of the current material.Arguments
- int num - Number of the texture, to which the procedural texture will be assigned.
- Material procedural - Procedural material.
- int procedural_num - Procedural texture number.
int IsOwner ( ) #
Returns the owner flag. If the pointer is the owner, on its deletion the material also will be deleted. Use grab() and release() functions to change ownership.Return value
Owner flag.bool IsParameterExpression ( 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
1 if the value of the specified material parameter is represented by an expression in UnigineScript; otherwise, 0.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
1 if the given parameter is overridden; otherwise, 0.void SetParameter ( int num, vec4 arg2 ) #
Sets a material's parameter value.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4 arg2 - Parameter value.
void SetParameter ( string name, vec4 arg2 ) #
Sets the specified value to the parameter with the given name.Arguments
- string name - Parameter name.
- vec4 arg2 - Parameter value to set.
vec4 GetParameter ( string name ) #
Returns a value of the parameter with the given name.Arguments
- string name - Parameter name.
Return value
Parameter value.vec4 GetParameter ( int num ) #
Returns a value of the parameter with the given number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Parameter value.void SetParameterArray ( int num, vec4[] values ) #
Sets the values for a given array parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4[] values - Array of parameter values.
void GetParameterArray ( int num, vec4[] values ) #
Returns the values of a given array parameter (the values are written into the specified array).Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- vec4[] values - Array of parameter values.
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 GetParameterGroup ( int num ) #
Returns the group of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
The group of the material parameter.bool IsParameterHidden ( int num ) #
Returns a value indicating if a given parameter is hidden.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the parameter is hidden; otherwise, 0.int SetParameterMask ( int num, int mask ) #
Sets a mask for a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- int mask - Integer value, each bit of which is a mask.
Return value
1 if the mask is set successfully; otherwise, 0.int GetParameterMask ( int num ) #
Returns the mask for a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Integer value, each bit of which is a mask.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.void SetParameterSlider ( string name, float value ) #
Sets the value of a given slider parameter by its name.Arguments
- string name - Name of the target slider parameter.
- float value - Slider parameter value.
void SetParameterSlider ( int num, float value ) #
Sets the value of a given slider parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- float value - Slider parameter value.
float GetParameterSlider ( int num ) #
Returns the current value of a given slider parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Slider parameter value.int GetParameterSliderMaxExpand ( int num ) #
Returns a value indicating if the maximum value of a given parameter can be increased.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the maximum value can be changed; otherwise, 0.float GetParameterSliderMaxValue ( int num ) #
Returns the maximum allowed value of a slider parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Maximum value.int GetParameterSliderMinExpand ( int num ) #
Returns a value indicating if the minimum value of a given parameter can be decreased.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the minimum value can be changed; otherwise, 0.float GetParameterSliderMinValue ( int num ) #
Returns the minimum allowed value of a slider parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Minimum value.string GetParameterTitle ( int num ) #
Returns the title of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Material parameter title.string GetParameterTooltip ( int num ) #
Returns the tooltip of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
The tooltip text of the material parameter.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 MATERIAL_PARAMETER_* pre-defined variables or -1, if an error occurred.int GetParameterWidgetIndex ( int num ) #
Returns the index of the widget used to display the specified material parameter in UI.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Index of the widget used for the specified material parameter.string GetParameterWidget ( int num ) #
Returns the name of the widget used to display the specified material parameter in UI.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Widget name for the specified material parameter.bool IsParent ( string name ) #
Returns a value indicating if the material with the given name is a parent of the current material.Arguments
- string name - Material name.
Return value
1 if the material is the parent, otherwise - 0.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
1 if the material is the parent; otherwise, 0.void SetProceduralTexture ( int num, Texture texture ) #
Replaces a procedural texture having the specified number with the specified Texture. Procedural textures are calculated at run-time on GPU, using custom shaders. For example, this function allows to set the initial value for such texture.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- Texture texture - Texture to be set.
int SetProceduralTextureImage ( int num, Image image ) #
Replaces a given procedural texture with an Image instance. Procedural textures are calculated at run-time on GPU, using custom shaders. For example, this function allows to set the initial value for such texture.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- Image image - An image to set.
Return value
1 if the texture is replaced successfully; otherwise, 0.int GetProceduralTextureImage ( int num, Image image ) #
Reads the given procedural texture into an Image smart pointer. Procedural textures are calculated in run-time on GPU, using custom shaders. So, for example, this function enables to read the value of such texture at any moment.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- Image image - Image into which texture is read.
Return value
1 if the texture is read successfully; otherwise, 0.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 smart pointer for the specified rendering pass and the node type.Arguments
- Render.PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
Return value
Shader smart pointer.Shader FetchShader ( Render.PASS pass, Node.TYPE node_type ) #
Returns the rendering shader smart pointer for the specified rendering pass and the 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 smart pointer.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 GetStateGroup ( int num ) #
Returns the group of the material state.Arguments
- int num - State number.
Return value
The group of the material state.bool IsStateHidden ( int num ) #
Returns a value indicating if a given state is hidden.Arguments
- int num - State number.
Return value
1 is the state is hidden; otherwise, 0.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 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.string GetStateTitle ( int num ) #
Returns the title of the material state.Arguments
- int num - State number.
Return value
The title of the material state.string GetStateTooltip ( int num ) #
Returns the tooltip of the material state.Arguments
- int num - State number.
Return value
The tooltip text of the material state.int GetStateWidgetIndex ( int num ) #
Returns the index of the widget used to display the specified material state in UI.Arguments
- int num - State number in the range from 0 to the total number of states.
Return value
Index of the widget used for the specified material state.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.string GetTextureGroup ( int num ) #
Returns the group of the material texture.Arguments
- int num - State number.
Return value
The group of the material texture.bool IsTextureHidden ( int num ) #
Returns a value indicating if the texture is hidden.Arguments
- int num - Texture number.
Return value
1 if the texture is hidden; otherwise, 0.bool IsTextureOverridden ( int num ) #
Returns a value indicating if a given texture is overridden.Arguments
- int num - Texture number.
Return value
1 if the given texture is overridden; otherwise, 0.string GetTextureName ( int num ) #
Returns the name of a given texture.Arguments
- int num - Texture number.
Return value
Texture name.string GetTextureTitle ( int num ) #
Returns the title of the material texture.Arguments
- int num - Texture number.
Return value
Title of the material texture.string GetTextureTooltip ( int num ) #
Returns the tooltip of the material texture.Arguments
- int num - Texture number.
Return value
Tooltip text of the material texture.int GetTextureWidgetIndex ( int num ) #
Returns the index of the widget used to display the specified material texture in UI.Arguments
- int num - Texture number in the range from 0 to the total number of textures.
Return value
Index of the widget used for the specified material texture.int GetTextureType ( int num ) #
Returns the type of a given texture.Arguments
- int num - Texture number.
Return value
One of the TEXTURE_* pre-defined variables or -1, if an error occurred.Material Clone ( string name ) #
Clones the material and assigns the given name to it.Arguments
- string name - Cloned material name.
Return value
Cloned material.Material Clone ( string name, string path, UGUID guid ) #
Clones the material and assigns the given name, GUID and path to the cloned material. The cloned material will be saved to the specified path on saveMaterials() call. This method may be used, for example, to create a material missed during project's migration.Arguments
- string name - CLoned material name.
- string path - Path to the cloned material.
- UGUID guid - Cloned material GUID.
Return value
The cloned material.Material Clone ( string name, string path ) #
Clones the material and assigns the given name and path to the cloned material. The cloned material will be saved to the specified path on saveMaterials() call.Arguments
- string name - Cloned material name.
- string path - Path to save the cloned material
Return value
Cloned material.Material Clone ( ) #
Clones the material. The cloned material will be empty: it won't have a name, path, textures and won't be displayed in the materials hierarchy.Return value
Cloned material.int FetchParameter ( string name, int fast_id ) #
Searches for a parameter by a given name among all parameters of the material.Arguments
- string name - Parameter name.
- int fast_id - Parameter number in users auxiliary parameters cache. The value must be in the range [0; 128]
Return value
Parameter number, if it is found; otherwise, -1.int FetchState ( string name, int fast_id ) #
Searches for a state by a given name among all states of the current material.Arguments
- string name - State name.
- int fast_id - State number in users auxiliary states cache. The value must be in the range [0; 128]
Return value
State number, if it is found; otherwise, -1.int FetchTexture ( string name, int fast_id ) #
Searches for a texture by a given name among all textures used by the current material.Arguments
- string name - Texture name.
- int fast_id - Texture number in users auxiliary textures cache. The value must be in the range [0; 128]
Return value
Texture number, if it is found; otherwise, -1.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 texture used by the current material.Arguments
- string name - Texture name.
Return value
Texture number, if it is found; otherwise, -1.void Grab ( ) #
Grabs Material (sets the owner flag to 1). The Material should not be handled by the engine after this function is called.Material Inherit ( string name ) #
Inherits a material from the current one and assigns the specified name to it.Arguments
- string name - Inherited material name.
Return value
Inherited material.Material Inherit ( string name, string path ) #
Inherits a material from the current one and assigns the specified name and path to it. The inherited material will be saved to the specified path on saveMaterials() call.Arguments
- string name - Inherited material name.
- string path - Path to the inherited material.
Return value
Inherited material.Material Inherit ( string name, string path, UGUID guid ) #
Inherits a material from the current one and assigns the specified name, GUID and path to it. The inherited material will be saved to the specified path on saveMaterials() call.Arguments
- string name - Inherited material name.
- string path - Path to the inherited material.
- UGUID guid - Inherited material GUID.
Return value
Inherited material.Material Inherit ( ) #
Inherits the material. The inherited material will be empty: it won't have a name, path, texture and won't be displayed in materials hierarchy.Return value
Inherited material.void Release ( ) #
Releases Material (sets the owner flag to 0). The Material should be handled by the engine after this function is called.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.Arguments
- Stream stream - The stream with saved material data.
- bool forced - Forced restoring of material settings.
Return value
1 if the material settings are restored successfully; otherwise, 0.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.Arguments
- Stream stream - The stream to save material state data.
- bool forced - Forced saving of material settings.
Return value
1 if the material settings are saved successfully; otherwise, 0.bool CanRenderNode ( ) #
Returns a value indicating if the marial can be rendered for at least one type of nodes.Return value
1 if the material is rendered for at least one type of nodes; otherwise, 0.void ResetState ( int num ) #
Resets the overriden 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 overriden 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
1 if the node type is supported; otherwise, 0.int 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
1 if the material's parent is changed; otherwise, 0.bool CheckTextureConditions ( int num ) #
Checks if conditions set for the given texture are met.Arguments
- int num - Texture number.
Return value
1 if conditions are met; otherwise, 0.int GetTextureFlags ( int num ) #
Returns the flags set on the given texture.Arguments
- int num - Texture number.
Return value
Texture flags bit mask.void ReloadShaders ( ) #
Reloads shaders of the current material.int LoadXml ( Xml xml ) #
Loads material settings from the Xml.Arguments
- Xml xml - An Xml node containing material settings.
Return value
1 if the material settings are loaded successfully; otherwise, 0.bool HasOverrides ( ) #
Returns a value indicating if the material has at least one overriden property.Return value
1 if the material has at least one overriden property; otherwise, 0.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
1 if the material can be saved; otherwise, 0.bool CheckStateConditions ( int num ) #
Checks if conditions set for the given state are met.Arguments
- int num - State number.
Return value
1 if conditions are met; otherwise, 0.bool CheckParameterConditions ( int num ) #
Checks if conditions set for the given parameter are met.Arguments
- int num - Parameter name.
Return value
1 if conditions are met; othersiwe, 0.bool Save ( ) #
Save the material to the current path used for this material.Return value
1 if the material is saved successfully; otherwise, 0.bool Save ( string path ) #
Save the material to the specified path.Arguments
- string path - A path to save the material
Return value
1 if the material is saved successfully; otherwise, 0.bool Load ( ) #
Loads the material from the file specified by the setPath() function. The function can be used to load materials created during application execution or stored outside the data directory.Return value
1 if the material is loaded successfully; otherwise, 0.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
1 if the material is loaded successfully; otherwise, 0.bool SaveXml ( Xml xml ) #
Saves the material into the given Xml.Arguments
- Xml xml - An Xml node.
Return value
1 if the material is saved successfully; otherwise, 0.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
1 if the given node is supported; otherwise, 0.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.void SetTextureFlags ( int num, int flags ) #
Sets the specified texture flags to the given texture.Arguments
- int num - Texture number.
- int flags - Texture flags bit mask.
void SetTexture ( int num, Texture texture ) #
Sets the given texture to the texture with the specified number.Arguments
- int num - Texture number.
- Texture texture - A 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 overriden 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
1 if the material is reloaded 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.void DestroyShaders ( ) #
Deletes all shaders used for the current material and its children and clears shaders cache.void CreateShaders ( bool recursive = 0 ) #
Creates all shaders for the current material and its children (if specified).Arguments
- bool recursive - 1 to create shaders for child materials of the current material; otherwise, 0.
void DestroyTextures ( ) #
Deletes all textures used by the current material and its children.void ReloadShader ( long num ) #
Reloads the shader with the given number.Arguments
- long num - Shader number.
void UpdateShadersHash ( ) #
Updates fast identifiers of shaders (hashes of names) of the material. The function is available only for base materials.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:<!--...-->
<expression name="expr_name" path="expression.usc"/>
An example of expression.usc code:
// 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.getFloatParameter("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:
// ...
// setting the value of extra parameter
material->setParameterFloat("my_extra_param", 2.5f);
// running the expression
material->runExpression("expr_name, 512, 512, 1);
// ...
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
0 if the specified pass was not found; otherwise, 1.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.
void SetParent ( Material parent ) #
Arguments
- Material parent