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.

Material Class

Members

---

Material clone (string name)

Clones the material.

Arguments

• string name - New material name.

Return value

Cloned material.

int findParameter (string name)

Searches for a parameter by a name among all parameters of the current material.

Arguments

• string name - Name of the parameter.

Return value

ID number of the parameter, if it is found; otherwise, -1.

int findParameter (string name, int fast_id)

Searches for a parameter by a name and a fast identifier among all parameters of the current material.

Arguments

• string name - Name of the parameter.
• int fast_id - Parameter's fast identifier (hash of a name).

Return value

ID number of the parameter, if it is found.

int findState (string name)

Searches for a state by a name among all states of the current material.

Arguments

• string name - Name of the state.

Return value

ID number of the state, if it is found; otherwise, -1.

int findState (string name, int fast_id)

Searches for a state by a name and a fast identifier among all states of the current material.

Arguments

• string name - Name of the state.
• int fast_id - State's fast identifier (hash of a name).

Return value

ID number of the state, if it is found.

int findTexture (string name)

Searches for a texture by a name among all texture used by the current material.

Arguments

• string name - Name of the texture.

Return value

ID number of the texture, if it is found.

int findTexture (string name, int fast_id)

Searches for a texture by a name and fast identifier among all texture used by the current material.

Arguments

• string name - Name of the texture.
• int fast_id - Texture's fast identifier (hash of a name).

Return value

ID number of the texture, if it is found; otherwise, -1.

int getAlphaTest ()

Returns a value indicating if alpha testing is enabled for the material.

Return value

Positive number if alpha testing is enabled; otherwise, 0.

int getBlendDestFunc ()

Returns a blend mode used to scale the destination color.

Return value

One of the MATERIAL_BLEND_* variables, which specify ways of calculating the blend factor.

int getBlendSrcFunc ()

Returns a blend mode used to scale the source color.

Return value

One of the MATERIAL_BLEND_* variables, which specify ways of calculating the blend factor.

int getCastShadow ()

Returns a value indicating if an object with the material applied should cast shadows.

Return value

Positive number if shadows should be cast; otherwise, 0.

int getCastWorldShadow ()

Returns a value indicating if an object with the material applied should cast shadows created by the world light.

Return value

Positive number if shadows should be cast; otherwise, 0.

Material getChild (int id)

Returns a child material with a given number.

Arguments

• int id - ID number of the target child material.

Return value

Child material.

Material getCompare ()

Returns the parent material, whose parameters have been changed.

Return value

Parent material.

int getDepthMask ()

Returns a value indicating if the material uses a depth mask.

Return value

Positive number if the depth mask is used; otherwise, 0.

int getImageTextureFlags (int id)

Returns the flags set on the image texture.

Arguments

• int id - ID number of the target texture.

Return value

A flags mask.

int getImageTextureImage (int id, Image image)

Reads a given texture into an Image instance.

Arguments

• int id - ID number of the target texture.
• Image image - Image into which texture is read.

Return value

1 if the texture is read successfully; otherwise, 0.

string getImageTextureName (int id)

Returns the name of a given image texture.

Arguments

• int id - ID number of the target texture.

Return value

Texture name or NULL (0), if an error occurs.

int getLightBlending ()

Returns a value indicating if the Light Blending option is enabled for the material.

Return value

1 if the Light Blending option is enabled; otherwise, 0.

int getLightMask ()

Returns a light mask of the material. The material is illuminated by a light source, if they both have corresponding masks.

Return value

Integer, each bit of which is a mask.

string getName ()

Returns the material name.

Return value

Name of the material.

int getNumChildren ()

Returns the number of children of the material.

Return value

Number of children materials.

int getNumChilds ()

Returns the number of children of the material.

Return value

Number of children materials.

int getNumParameters ()

Returns the number of material parameters.

Return value

Number of material parameters.

int getNumStates ()

Returns the number of material states.

Return value

Number of material states.

int getNumTextures ()

Returns the number of textures used by the material.

Return value

Number of used textures.

int getOffset ()

Returns the polygon offset used for the material.

Return value

Offset in levels.

int getOrder ()

Returns the rendering order of materials (the priority of the material rendering inside the group).

Return value

Rendering order.

void getParameterArray (int id, int values = [])

Returns the values of a given array parameter.

Arguments

• int id - ID number of the target parameter.
• int values - ID of the returned vec4 array.

string getParameterExpression (int id)

Returns an expression used as a parameter value.

Arguments

• int id - ID number of the target parameter.

Return value

Parameter expression, if exists; otherwise, NULL (0).

string getParameterName (int id)

Returns the name of a given parameter.

Arguments

• int id - ID number of the target parameter.

Return value

Name of the parameter.

int getParameterSliderLog10 (int id)

Returns a value indicating if a given parameter uses a logarithmic scale (with the base ten).

Arguments

• int id - ID number of the target parameter.

Return value

Positive number if the parameter uses a logarithmic scale; otherwise, 0.

int getParameterSliderMaxExpand (int id)

Returns a value indicating if the maximum value of a given parameter can be increased.

Arguments

• int id - ID number of the target parameter.

Return value

Positive number if the maximum value can be changed; otherwise, 0.

float getParameterSliderMaxValue (int id)

Returns the maximum allowed value of a slider parameter.

Arguments

• int id - ID number of the target parameter.

Return value

Maximum value.

int getParameterSliderMinExpand (int id)

Returns a value indicating if the minimum value of a given parameter can be decreased.

Arguments

• int id - ID number of the target parameter.

Return value

Positive number if the minimum value can be changed; otherwise, 0.

float getParameterSliderMinValue (int id)

Returns the minimum allowed value of a slider parameter.

Arguments

• int id - ID number of the target parameter.

Return value

Minimum value.

float getParameterSlider (int id)

Returns the current value of a given slider parameter.

Arguments

• int id - ID number of the target slider parameter.

Return value

Current value.

int getParameterType (int id)

Returns the type of a given parameter.

Arguments

• int id - ID number of the target parameter.

Return value

One of the MATERIAL_PARAMETER_* pre-defined variables or -1, if an error occurred.

vec4 getParameter (variable variable)

Returns the value of a given parameter.

Arguments

• variable variable - Parameter to be updated. It can either be:
  • int - ID number of the target parameter.
  • string - name of the target parameter.

Return value

Parameter value.

Material getParent ()

Returns the parent material.

Return value

Parent material or NULL (0), if the current material has no parent.

int getPostRefraction ()

Returns a value indicating if a surface with this material is rendered after the refraction pass or before it.

Return value

Positive number if the surfaces are rendered after the refraction pass; otherwise, 0.

int getPostScattering ()

Returns a value indicating if a surface with this material is rendered after the scattering pass or before it.

Return value

Positive number if the surfaces are rendered after the scattering pass; otherwise, 0.

int getProceduralTextureImage (int id, Image image)

Reads a given procedural texture into an Image instance. Procedural textures are calculated in run-time on GPU, using custom shaders. For example, this function allows to read the value of such texture at any moment.

Arguments

• int id - Number of the target texture. 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.

string getStateName (int id)

Returns the name of a given state.

Arguments

• int id - ID number of the target state.

Return value

Name of the state.

string getStateSwitchItem (int state, int item)

Returns a string value for a switch item of a given state.

Arguments

• int state - ID number of the target state.
• int item - ID number of the target item.

Return value

Value of the item or NULL (0), if an error occurred.

int getStateSwitchNumItems (int id)

Returns the number of switch items of a given state.

Arguments

• int id - ID number of the target state.

Return value

Number of switch items.

int getStateType (int id)

Returns the type of a given state.

Arguments

• int id - ID number of the target state.

Return value

One of the MATERIAL_STATE_* pre-defined variables or -1, if an error occurred.

int getState (variable variable)

Returns the value of the given state.

Arguments

• variable variable - State to be updated. It can either be:
  • int - ID number of the target state.
  • string - name of the target state.

Return value

State value.

string getTextureName (int id)

Returns the name of a given texture.

Arguments

• int id - ID number of the target texture.

Return value

Name of the texture.

int getTextureType (int id)

Returns the type of a given texture.

Arguments

• int id - ID number of the target texture.

Return value

One of the MATERIAL_TEXTURE_* pre-defined variables or -1, if an error occurred.

int getTransparent ()

Returns a value indicating the transparency type of the material.

Return value

0 if the material is MATERIAL_TRANSPARENT_NONE, 1 if the material is MATERIAL_TRANSPARENT_BLEND, 2 if the material is MATERIAL_TRANSPARENT_DEFERRED.

int getTwoSided ()

Returns a value indicating if the material is two-sided.

Return value

Positive number if the material is two-sided; otherwise, 0.

int getViewportMask ()

Returns the current bit mask for rendering into the viewport. The material is rendered, if its mask matches the player's one.

Return value

Integer, each bit of which is a mask.

Material inherit (string name)

Creates a new material with a specified name and sets the current material as its parent.

Arguments

• string name - New material name.

Return value

Inherited material.

int isEditable ()

Returns a value indicating if the material can be edited.

Return value

1 if the material is editable; otherwise, 0.

int isFilter ()

Returns a value indicating if the material has filter texture.

Return value

Returns 1 if the material has filter texture; otherwise, 0.

int isHidden ()

Returns a value indicating if the material is hidden.

Return value

1 if the material is hidden; otherwise, 0.

int isParameterHidden (int id)

Returns a value indicating if a given parameter is hidden.

Arguments

• int id - ID number of the target parameter.

Return value

1 if the parameter is hidden; otherwise, 0.

int isParent (string name)

Returns a value indicating if the material is parent.

Arguments

• string name - Name of the material.

Return value

1 if the material is parent, otherwise - 0.

int isProcedural ()

Returns a value indicating if the material has procedural texture.

Return value

Returns 1 if the material has procedural texture; otherwise, 0.

int isReflection2D ()

Returns a value indicating if the material has 2d reflection texture.

Return value

Returns 1 if the material has 2d reflection texture; otherwise, 0.

int isStateHidden (int id)

Returns a value indicating if a given state is hidden.

Arguments

• int id - ID number of the target state.

Return value

1 if the state is hidden; otherwise, 0.

int isTextureHidden (int id)

Returns a value indicating if a given texture is hidden.

Arguments

• int id - ID number of the target texture.

Return value

1 if the texture is hidden; otherwise, 0.

int restoreState (Stream stream, int 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.
• int forced - Forced restoring of material settings.

Return value

1 if the material state is restored successfully; otherwise, 0.

int saveState (Stream stream, int forced = 0)

Saves the state of the given material (all of its options, states and parameters) into a binary stream.

Arguments

• Stream stream - The stream to save material state data.
• int forced - Forced saving of material settings.

Return value

1 if the material state is saved successfully; otherwise, 0.

void setAlphaTest (int mode)

Updates a value indicating if alpha testing is enabled for the material.

Arguments

• int mode - Positive number to enable alpha testing, 0 to disable.

void setBlendFunc (int source, int destination)

Sets blend modes for the source and destination colors.

Arguments

• int source - Blend mode (one of the MATERIAL_BLEND_* variables) for the source color.
• int destination - Blend mode (one of the MATERIAL_BLEND_* variables) for the destination color.

void setCastShadow (int mode)

Updates a value indicating if an object with the material applied should cast shadows.

Arguments

• int mode - Positive number to cast shadows, 0 not to cast.

void setCastWorldShadow (int mode)

Updates a value indicating if an object with the material applied should cast shadows created by the world light.

Arguments

• int mode - Positive number to cast shadows, 0 not to cast.

void setDepthMask (int mode)

Updates a value indicating if the material uses a depth mask.

Arguments

• int mode - Positive number to use the depth mask, 0 not to use.

void setImageTextureFlags (int num, int flags)

Sets the flags on the image texture.

Arguments

• int num - ID number of the target texture.
• int flags - A flags mask.

int setImageTextureImage (int id, Image image, int dynamic = 0)

Replaces a given texture with an Image instance. If you need to reset a texture of the inherited material instance, set dynamic flag to 1.

Arguments

• int id - ID number of the target texture.
• Image image - New texture to set.
• int dynamic - Dynamic texture flag.
  • If set to 0, changing a texture of the inherited material instance will also affect the base material. If the device is lost and the renderer resets its context, a texture will be reset to a default one instead of the specified image.
  • If set to 1, an image will be successfully set only for the current material instance.

Return value

1 if the texture is replaced successfully; otherwise, 0.

void setImageTextureName (int id, string name)

Updates the name of a given image texture.

Arguments

• int id - ID number of the target texture.
• string name - New name of the texture or NULL (0) to clear the name.

void setImageTextureProcedural (int num, Material procedural, int procedural_num)

Assigns the procedural texture to the specified image texture.

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.

void setLightBlending (int mode)

Updates a value indicating if the Light Blending option is enabled for the material. This option changes the current material blending mode, so it will be rendered during light rendering passes.

Arguments

• int mode - 1 to enable the Light Blending option, 0 to disable it.

void setLightMask (int mask)

Sets a light mask for the material. The material is illuminated by a light source, if they both have corresponding masks.

Arguments

• int mask - Integer, each bit of which is a mask.

void setOffset (int offset)

Updates the polygon offset of the material. Polygon offset is useful to prevent a Z-fighting effect.

Arguments

• int offset - Material offset in levels. Available values: 0 - 1024 (powers of 2).

void setOrder (int order)

Updates the rendering order of material. The higher the rendering order, the lower the rendering priority (the material with the -8 order will be rendered first).

Arguments

• int order - New rendering order ID.

void setParameterArray (int id, int values = [])

Updates the values of a given array parameter.

Arguments

• int id - ID number of the target parameter.
• int values - ID of the vec4 array.

int setParameterExpression (int id, string expression)

Updates the expression used as a parameter value.

Arguments

• int id - ID number of the target parameter.
• string expression - New expression.

Return value

1 if the expression is updated successfully; otherwise, 0.

void setParameterSlider (int id, float value)

Updates the value of a given slider parameter.

Arguments

• int id - ID number of the target slider parameter.
• float value - New value of the parameter.

void setParameter (variable variable, vec4 value)

Updates the value of a given parameter.

Arguments

• variable variable - Parameter to be updated. It can either be:
  • int - ID number of the target parameter.
  • string - name of the target parameter.
• vec4 value - New value of the parameter.

void setPostRefraction (int enable)

Updates a value indicating if a surface with this material should be rendered after the refraction pass.

Arguments

• int enable - Positive number to render the surfaces after the refraction pass; otherwise, 0.

void setPostScattering (int enable)

Updates a value indicating if a surface with this material should be rendered after the scattering pass or before it.

Arguments

• int enable - Positive number to render the surfaces after the scattering pass; otherwise, 0.

int setProceduralTextureImage (int id, Image image)

Replaces a given procedural texture with an Image instance. Procedural textures are calculated in run-time on GPU, using custom shaders. For example, this function allows to set the initial value for such texture.

Arguments

• int id - ID number of the target texture. In materials, such texture should be declared with type="procedural" attribute.
• Image image - New texture to set.

Return value

1 if the texture is replaced successfully; otherwise, 0.

void setState (variable variable, int value)

Updates the value of the given state.

Arguments

• variable variable - State to be updated. It can either be:
  • int - ID number of the target state.
  • string - name of the target state.
• int value - New value of the state.

void setTransparent (int transparent)

Sets a value indicating the transparency type of the material.

Arguments

• int transparent - A value indicating if the material is transparent.
  • 0 if the material is MATERIAL_TRANSPARENT_NONE
  • 1 if the material is MATERIAL_TRANSPARENT_BLEND
  • 2 if the material is MATERIAL_TRANSPARENT_DEFERRED

void setTwoSided (int mode)

Makes the material one- or two-sided.

Arguments

• int mode - Positive number to make the material two-sided, 0 to make it one-sided.

void setViewportMask (int mask)

Sets a bit mask for rendering into the viewport. The material is rendered, if its mask matches the player's one.

Arguments

• int mask - Integer, each bit of which is a mask.

---

int MATERIAL_ANISOTROPY

Description

An anisotropy effect is applied to the material.

int MATERIAL_BLEND_DEST_ALPHA

Description

Components of each material color are multiplied by bA .

int MATERIAL_BLEND_DEST_COLOR

Description

Components of each material color are multiplied by these factors (per component): (bR, bG, bB, bA) .

int MATERIAL_BLEND_NONE

Description

No blending is used.

int MATERIAL_BLEND_ONE

Description

Components of each material color are multiplied by one.

int MATERIAL_BLEND_ONE_MINUS_DEST_ALPHA

Description

Components of each material color are multiplied by 1- bA .

int MATERIAL_BLEND_ONE_MINUS_DEST_COLOR

Description

Components of each material color are multiplied by these factors (per component): (1 - bR, 1 - bG, 1 - bB, 1 - bA) .

int MATERIAL_BLEND_ONE_MINUS_SRC1_ALPHA

Description

Option for dual-source color blending (used by light scattering). Components of each material color are multiplied by 1- mA of the second color output form a pixel shader.

int MATERIAL_BLEND_ONE_MINUS_SRC1_COLOR

Description

Option for dual-source color blending (used by light scattering). Components of each material color are multiplied by the second color output form a pixel shader: (1 - mR, 1 - mG, 1 - mB, 1 - mA).

int MATERIAL_BLEND_ONE_MINUS_SRC_ALPHA

Description

Components of each material color are multiplied by 1- mA .

int MATERIAL_BLEND_ONE_MINUS_SRC_COLOR

Description

Components of each material color are multiplied by these factors (per component): (1 - mR, 1 - mG, 1 - mB, 1 - mA) .

int MATERIAL_BLEND_SRC1_ALPHA

Description

Option for dual-source color blending (used by light scattering). Components of each material color are multiplied by mA of the second color output form a pixel shader.

int MATERIAL_BLEND_SRC1_COLOR

Description

Option for dual-source color blending (used by light scattering). Components of each material color are multiplied by the second color output form a pixel shader: (mR, mG, mB, mA).

int MATERIAL_BLEND_SRC_ALPHA

Description

Components of each material color are multiplied by mA .

int MATERIAL_BLEND_SRC_COLOR

Description

Components of each material color are multiplied by these factors (per component): (mR, mG, mB, mA) .

int MATERIAL_BLEND_ZERO

Description

Components of each material color are multiplied by zero.

int MATERIAL_PARAMETER_ARRAY

Description

Parameter of this type accepts vec4 data type.

int MATERIAL_PARAMETER_AUX

Description

Parameter of the auxiliary type.

int MATERIAL_PARAMETER_COLOR

Description

Parameter of this type requires a color value—a quad of floats corresponding to RGBA color components.

int MATERIAL_PARAMETER_CONSTANT

Description

Parameter of this type accepts only a constant value.

int MATERIAL_PARAMETER_EXPRESSION

Description

Parameter of this type accepts expressions, which may include any operators, functions, and constants from the UnigineScript core library plus additional variable time and functions random() and noise().

int MATERIAL_PARAMETER_SLIDER

Description

Parameter of this type accepts values only from a continuous range of allowed values.

int MATERIAL_STATE_AUX

Description

State of the auxiliary type.

int MATERIAL_STATE_SWITCH

Description

State of this type allows specifying a set of more than two possible values.

int MATERIAL_STATE_TOGGLE

Description

State of this type allows only two possible values.

int MATERIAL_TEXTURE_AUX

Description

Texture of the auxiliary type.

int MATERIAL_TEXTURE_DEFERRED_DEPTH

Description

A texture of this type uses a deferred buffer to store depth values.

int MATERIAL_TEXTURE_DEFERRED_DIFFUSE

Description

A texture of this type uses a deferred buffer to store diffuse values.

int MATERIAL_TEXTURE_DEFERRED_LIGHT

Description

A texture of this type uses a deferred buffer to store light values.

int MATERIAL_TEXTURE_DEFERRED_NORMAL

Description

A texture of this type uses a deferred buffer to store normal values.

int MATERIAL_TEXTURE_DEFERRED_SPECULAR

Description

A texture of this type uses a deferred buffer to store specular values.

int MATERIAL_TEXTURE_DEFERRED_VELOCITY

Description

A texture of this type uses a deferred buffer to store velocity values.

int MATERIAL_TEXTURE_ENVIRONMENT

Description

A texture of this type stores an environment cube map.

int MATERIAL_TEXTURE_FILTER

Description

A filtering texture.

int MATERIAL_TEXTURE_IMAGE

Description

A standard bitmap image.

int MATERIAL_TEXTURE_LIGHT_DEPTH

Description

A texture of this type stores depth values (used to render shadows).

int MATERIAL_TEXTURE_LIGHT_IMAGE

Description

A texture of this type stores the light values provided by projected light sources.

int MATERIAL_TEXTURE_LIGHT_NOISE

Description

A texture of this type stores 3D noise values (used to render soft shadows).

int MATERIAL_TEXTURE_LIGHT_VCUBE

Description

Texture of this type is used to map coordinates of the special 2D depth texture to cube map coordinates.

int MATERIAL_TEXTURE_PROCEDURAL

Description

A procedurally generated texture.

int MATERIAL_TRANSPARENT_BLEND

Description

A transparent material which is rendered in forward pass, uses blend func.

int MATERIAL_TRANSPARENT_DEFERRED

Description

A transparent material which is rendered in deferred pass upon the deferred geometry into the g-buffer with alpha blend, doesn't use blend func.

int MATERIAL_TRANSPARENT_NONE

Description

An opaque material (non-transparent), doesn't use blend func.

int MATERIAL_WRAP_CLAMP_X

Description

A texture is clamped by the specified value on the X axis.

int MATERIAL_WRAP_CLAMP_Y

Description

A texture is clamped by the specified value on the Y axis.

int MATERIAL_WRAP_CLAMP_Z

Description

A texture is clamped by the specified value on the Z axis.