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.

Material Class

Members

---

int isAlphaTest()

Returns a value indicating if the material has an alpha test option enabled.

Return value

1 if the material has alpha test option enabled; otherwise, 0.

int getBlendDestFunc()

Gets the destination blending function.

Return value

The destination blending function (one of the BLEND_* values described in the State class).

void setBlendFunc(int src, int dest)

Sets the source and destination blending functions.

Arguments

• int src - The source blending function (one of the BLEND_* values described in the State class).
• int dest - The destination blending function (one of the BLEND_* values described in the State class).

int getBlendSrcFunc()

Gets the source blending function.

Return value

The source blending function (one of the BLEND_* values described in the State class).

void setCastShadow(int shadow)

Sets the cast shadow option: a value indicating if an object with the material applied should cast shadows.

Arguments

• int shadow - The cast shadow option.

int getCastShadow()

Gets the cast shadow option: a value indicating if an object with the material applied should cast shadows.

Return value

The cast shadow option.

void setCastWorldShadow(int shadow)

Sets the cast world shadow option: a value indicating if an object with the material applied should cast shadows created by the world light.

Arguments

• int shadow - The cast world shadow option.

int getCastWorldShadow()

Gets the cast world shadow option: a value indicating if an object with the material applied should cast shadows created by the world light.

Return value

The cast world shadow option.

Ptr<Material> getChild(int num)

Returns the child material.

Arguments

• int num - The child material number.

Return value

The child material smart pointer.

Ptr<Material> getCompare()

Returns the compare material smart pointer.

Return value

Compare material smart pointer.

int isDeferred()

Returns a value indicating if the material is rendered in the deferred pass.

Return value

1 if the material is rendered in the deferred pass (non-transparent); otherwise, 0.

void setDepthMask(int mask)

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

Arguments

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

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 isEditable()

Returns a value indicating if the material is editable.

Return value

1 if the material is editable; otherwise, 0.

int isFilter()

Returns a value indicating if the material has a filter texture.

Return value

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

int isForward()

Returns a value indicating if the material is rendered in the forward pass.

Return value

1 if the material is rendered in the forward pass (transparent with blending func); otherwise, 0.

int isHidden()

Returns a value indicating if the material is hidden.

Return value

1 if the material is hidden; otherwise, 0.

void setImageTexture(int num, const Ptr<Texture> & texture)

Sets the given texture smart pointer to the specified image texture.

Arguments

• int num - Texture number.
• const Ptr<Texture> & texture - Texture smart pointer.

Ptr<Texture> getImageTexture(int num)

Gets the image texture smart pointer.

Arguments

• int num - Texture number.

Return value

Texture smart pointer.

void setImageTextureFlags(int id, int flags)

Sets the flags on the image texture.

Arguments

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

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 setImageTextureImage(int id, const Ptr<Image> & image, int dynamic = 0)

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

Arguments

• int id - Texture number.
• const Ptr<Image> & image - Image smart pointer to be 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 image is set successfully; otherwise, 0.

int getImageTextureImage(int id, const Ptr<Image> & image)

Reads the given image texture into an Image smart pointer.

Arguments

• int id - Texture number.
• const Ptr<Image> & image - Image smart pointer into which the texture is read.

Return value

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

void setImageTextureName(int id, const char * name)

Sets the image texture name.

Arguments

• int id - Texture number.
• const char * name - Image texture name.

const char * getImageTextureName(int id)

Gets the image texture name.

Arguments

• int id - Texture number.

Return value

Image texture name.

void setImageTextureProcedural(int num, const Ptr<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.
• const Ptr<Material> & procedural - Procedural material.
• int procedural_num - Procedural texture number.

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 - An integer value, each bit of which is used to set a bit mask.

int getLightMask()

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

Return value

An integer value, each bit of which is used to set a bit mask.

const char * getName()

Returns a material name.

Return value

Material name.

int getNumChildren()

Returns the number of child materials.

Return value

The number of child materials.

int getNumParameters()

Returns the number of material's parameters.

Return value

The number of parameters.

int getNumStates()

Returns the number of material states.

Return value

The number of material states.

int getNumTextures()

Returns the number of material's textures.

Return value

Returns number of textures.

void setOffset(int offset)

Sets the rendering polygon offset for the material.

Arguments

• int offset - The rendering polygon offset.

int getOffset()

Gets the rendering polygon offset.

Return value

The rendering polygon offset.

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 - The rendering order.

int getOrder()

Gets the rendering order.

Return value

Returns rendering order.

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

The owner flag.

void setParameter(int num, const Math::vec4 & arg2)

Sets a material's parameter value.

Arguments

• int num - Parameter number.
• const Math::vec4 & arg2 - Parameter value.

Math::vec4 getParameter(int num)

Gets the material's parameter value.

Arguments

• int num - Parameter number.

Return value

Parameter value.

void setParameterArray(int num, const Vector< Math::vec4 > & values)

Sets values for the given array parameter.

Arguments

• int num - Parameter number.
• const Vector< Math::vec4 > & values - Array of parameter values.

void getParameterArray(int num, Vector< Math::vec4 > & values)

Gets values of the given array parameter.

Arguments

• int num - Parameter number.
• Vector< Math::vec4 > & values - Array of parameter values.

int setParameterExpression(int id, const char * expression)

Sets the expression used as a parameter value.

Arguments

• int id - Parameter number.
• const char * expression - Expression parameter source.

Return value

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

const char * getParameterExpression(int id)

Gets the expression used as the parameter value.

Arguments

• int id - Parameter number.

Return value

Parameter expression, if it exists; otherwise, NULL.

const char * getParameterGroup(int id)

Returns the group of the material parameter.

Arguments

• int id - The ID of the material parameter.

Return value

The group of the material parameter.

int isParameterHidden(int num)

Returns a value indicating if the material's parameter is hidden.

Arguments

• int num - The parameter number.

Return value

1 if the parameter is hidden; otherwise, 0.

const char * getParameterName(int id)

Returns the material's parameter name.

Arguments

• int id - The parameter number.

Return value

Parameter name.

void setParameterSlider(int id, float value)

Sets a slider parameter value.

Arguments

• int id - Parameter number.
• float value - Slider parameter value.

float getParameterSlider(int id)

Gets the slider parameter value.

Arguments

• int id - Parameter number.

Return value

Slider parameter value.

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.

const char * getParameterTitle(int id)

Returns the title of the material parameter.

Arguments

• int id - The ID of the material parameter.

Return value

The title of the material parameter.

const char * getParameterTooltip(int id)

Returns the tooltip of the material parameter.

Arguments

• int id - The ID of the material parameter.

Return value

The tooltip text of the material parameter.

int getParameterType(int num)

Returns the material's parameter type.

Arguments

• int num - The parameter number.

Return value

Parameter type.

Ptr<Material> getParent()

Returns the parent material smart pointer.

Return value

Parent material smart pointer.

int isParent(const char * name)

Returns a value indicating if the material is a parent one.

Arguments

• const char * name - Material name.

Return value

1 if the material is a parent material.

int isProcedural()

Returns a value indicating if the material has a procedural texture.

Return value

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

int setProceduralTextureImage(int num, const Ptr<Image> & image)

Replaces the procedural texture image with an Image smart pointer. Procedural textures are calculated in run-time on GPU, using custom shaders. So, for example, this function can be used to set the initial value for such texture.

Arguments

• int num - Texture number.
• const Ptr<Image> & image - Image smart pointer.

Return value

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

int getProceduralTextureImage(int num, const Ptr<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.
• const Ptr<Image> & image - Image smart pointer.

Return value

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

int isReflection2D()

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

Return value

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

Ptr<Shader> getShader(int pass)

Returns the rendering shader smart pointer for the specified rendering pass and the node type.

Arguments

• int pass - The rendering pass number in range [0;13).

Return value

Shader smart pointer.

Ptr<Shader> getShader(int pass, int node)

Returns the rendering shader smart pointer for the specified rendering pass and the node type.

Arguments

• int pass - The rendering pass number in range [0;13).
• int node - Node type.

Return value

Shader smart pointer.

void setState(int num, int value)

Sets the state value.

Arguments

• int num - State number.
• int value - State value to be set.

void setState(const char * name, int value)

Updates the value of the given state.

Arguments

• const char * name - A name of the target state
• int value - State value.

int getState(int num)

Gets the state value.

Arguments

• int num - State number.

Return value

State value.

int getState(const char * name)

Returns the value of the given state.

Arguments

• const char * name - A name of the target state

Return value

State value.

const char * getStateGroup(int id)

Returns the group of the material state.

Arguments

• int id - The ID of the material state.

Return value

The group of the material state.

int isStateHidden(int id)

Returns a value indicating if the state is hidden.

Arguments

• int id - The state number.

Return value

1 is the state is hidden; otherwise, 0.

const char * getStateName(int num)

Returns the state name.

Arguments

• int num - The state number.

Return value

State name.

const char * getStateSwitchItem(int num, int item)

Returns the switch item name.

Arguments

• int num - State number.
• int item - Item number.

Return value

Switch item name.

int getStateSwitchNumItems(int num)

Returns the number of switch item names.

Arguments

• int num - State number.

Return value

Number of switch item names.

const char * getStateTitle(int id)

Returns the title of the material state.

Arguments

• int id - The ID of the material state.

Return value

The title of the material state.

const char * getStateTooltip(int id)

Returns the tooltip of the material state.

Arguments

• int id - The ID of the material state.

Return value

The tooltip text of the material state.

int getStateType(int num)

Returns the state type.

Arguments

• int num - The state number.

Return value

State type.

const char * getTextureGroup(int id)

Returns the group of the material texture.

Arguments

• int id - The ID of the material texture.

Return value

The group of the material texture.

int isTextureHidden(int id)

Returns a value indicating if the texture is hidden.

Arguments

• int id - The texture number.

Return value

1 is the texture is hidden; otherwise, 0.

const char * getTextureName(int num)

Returns the texture name.

Arguments

• int num - The texture number.

Return value

Texture name.

const char * getTextureTitle(int id)

Returns the title of the material texture.

Arguments

• int id - The ID of the material texture.

Return value

The title of the material texture.

const char * getTextureTooltip(int id)

Returns the tooltip of the material texture.

Arguments

• int id - The ID of the material texture.

Return value

The tooltip text of the material texture.

int getTextureType(int num)

Returns the texture type.

Arguments

• int num - The texture number.

Return value

Texture type, if the texture with the given number exists; otherwise, -1.

void setTransparent(int transparent)

Sets the transparent option: a value indicating if an object with the material applied should be transparent. If the transparent option is set to TRANSPARENT_NONE or TRANSPARENT_DEFERRED, the blending function won't be used.

Arguments

• int transparent - The transparent option (one of the TRANSPARENT_*variables).

int getTransparent()

Gets the transparent option: a value indicating if an object with the material applied should be transparent.

Return value

The transparent option (one of the TRANSPARENT_*variables).

void setTwoSided(int sided)

Sets the two sided option for the material.

Arguments

• int sided - The two sided option.

int getTwoSided()

Gets the two sided option of the material.

Return value

The two sided option.

void setViewportMask(int mask)

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

Arguments

• int mask - An integer value, each bit of which is used to set a bit mask.

int getViewportMask()

Gets the viewport mask: a bit mask for rendering into the viewport.

Return value

An integer value, each bit of which is used to set a bit mask.

int isWater()

Returns a value indicating if the material is rendered in the water pass.

Return value

1 if the material is rendered in the water pass; otherwise, 0.

Ptr<Material> clone(const char * name)

Clones the material.

Arguments

• const char * name - New material name.

Return value

Cloned material smart pointer.

int findParameter(const char * name)

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

Arguments

• const char * name - Parameter name.

Return value

Parameter number.

int findParameter(const char * name, int fast_id)

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

Arguments

• const char * name - Parameter name.
• int fast_id - Parameter's fast identifier (hash of a name).

Return value

Parameter number.

int findState(const char * name, int fast_id)

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

Arguments

• const char * name - State name.
• int fast_id - State's fast identifier (hash of a name).

Return value

State number.

int findState(const char * name)

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

Arguments

• const char * name - State name.

Return value

State number.

int findTexture(const char * name, int fast_id)

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

Arguments

• const char * name - Texture name.
• int fast_id - Texture's fast identifier (hash of a name).

Return value

Texture number.

int findTexture(const char * name)

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

Arguments

• const char * name - Texture name.

Return value

Texture number.

void grab()

Grabs Material (sets the owner flag to 1 for the pointer). The Material should not be handled by the engine after this function is called.

Ptr<Material> inherit(const char * name)

Inherits the material.

Arguments

• const char * name - New material name.

Return value

Inherited material smart pointer.

int loadWorld(const Ptr<Xml> & xml)

Loads material settings from the Xml.

Arguments

• const Ptr<Xml> & xml - Xml smart pointer.

Return value

1 if the material settings are loaded successfully; otherwise, 0.

void release()

Releases Material (sets the owner flag to 0 for the pointer). The Material should be handled by the engine after this function is called.

int restoreState(const Ptr<Stream> & stream, int forced = 0)

Restores material settings from the stream.

Arguments

• const Ptr<Stream> & stream - Stream smart pointer.
• int forced - Forced restoring of material settings.

Return value

1 if the material settings are restored successfully; otherwise, 0.

int saveState(const Ptr<Stream> & stream, int forced = 0)

Saves material settings into the stream.

Arguments

• const Ptr<Stream> & stream - Stream smart pointer.
• int forced - Forced saving of material settings.

Return value

1 if the material settings are saved successfully; otherwise, 0.

int saveWorld(const Ptr<Xml> & xml, int force)

Saves material settings into the Xml.

Arguments

• const Ptr<Xml> & xml - Xml smart pointer.
• int force - Forced saving of material settings.

Return value

1 if the material settings are saved successfully; otherwise, 0.

---

int PARAMETER_ARRAY

Description

Parameter of this type accepts vec4 data type.

int PARAMETER_COLOR

Description

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

int PARAMETER_COMBINER

Description

Parameter of this type allows you to combine some parameter values in one data type.

int PARAMETER_CONSTANT

Description

Parameter of this type accepts only a constant value.

int 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 PARAMETER_SLIDER

Description

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

int STATE_INT

int STATE_SWITCH

Description

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

int STATE_TOGGLE

Description

State of this type allows only two possible values.

int TEXTURE_ALPHA_FADE

int TEXTURE_AUXILIARY

int TEXTURE_CURRENT_DEPTH

int TEXTURE_DECAL_ALBEDO

int TEXTURE_DECAL_DEPTH

int TEXTURE_DECAL_NORMAL

int TEXTURE_DECAL_SHADING

int TEXTURE_DEFERRED_DECAL_MASK

Description

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

int TEXTURE_DEFERRED_DEPTH

Description

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

int TEXTURE_DEFERRED_DIFFUSE

Description

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

int TEXTURE_DEFERRED_LIGHT

Description

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

int TEXTURE_DEFERRED_LIGHT_MAP

Description

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

int TEXTURE_DEFERRED_NORMAL

Description

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

int TEXTURE_DEFERRED_OCCLUSION

Description

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

int TEXTURE_DEFERRED_REFLECTION

int TEXTURE_DEFERRED_SPECULAR

Description

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

int TEXTURE_DEFERRED_VELOCITY

Description

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

int TEXTURE_ENVIRONMENT

Description

A texture of this type stores an environment cube map.

int TEXTURE_FIELD_HEIGHT_ARRAY

int TEXTURE_FIELD_SHORELINE_ARRAY

int TEXTURE_FILTER

Description

A filtering texture.

int TEXTURE_GBUFFER_ALBEDO

int TEXTURE_GBUFFER_LIGHTMAP

int TEXTURE_GBUFFER_MATERIAL_MASK

int TEXTURE_GBUFFER_NORMAL

int TEXTURE_GBUFFER_SHADING

int TEXTURE_GBUFFER_VELOCITY

int TEXTURE_GEODETIC_TOPOLOGY

int TEXTURE_IMAGE

Description

A standard bitmap image.

int TEXTURE_LIGHT_DEPTH

Description

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

int TEXTURE_LIGHT_IMAGE

Description

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

int TEXTURE_LIGHT_NOISE

Description

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

int TEXTURE_LIGHT_VCUBE

Description

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

int TEXTURE_OPACITY_DEPTH

int TEXTURE_OPACITY_SCREEN

int TEXTURE_PROCEDURAL

Description

A procedurally generated texture.

int TEXTURE_REFLECTION_2D

int TEXTURE_REFLECTION_CUBE

int TEXTURE_REFRACTION

int TEXTURE_SCATTERING_GROUND_LUT

int TEXTURE_SCATTERING_SKY_LUT

int TEXTURE_SCREEN_COLOR

int TEXTURE_SCREEN_COLOR_OLD

int TEXTURE_SSAO

int TEXTURE_SSR

int TEXTURE_SSR_DEPTH

int TEXTURE_TRANSPARENT_ENVIRONMENT_PROBE

int TEXTURE_WBUFFER_CONSTANT_ID

int TEXTURE_WBUFFER_DIFFUSE

int TEXTURE_WBUFFER_FOG

int TEXTURE_WBUFFER_NORMAL

int TEXTURE_WBUFFER_WATER

int TEXTURE_WBUFFER_WU_MASK

int TRANSPARENT_ALPHA_TEST

Description

A transparent material which uses alpha test.

int TRANSPARENT_BLEND

Description

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

int 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 TRANSPARENT_NONE

Description

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

int TRANSPARENT_WATER

Description

A transparent material which is rendered in water pass.