Unigine::Material Class

Interface for material manipulation.

To use this class, include the UnigineMaterial.h file.

Unigine::Material Class

Members

---

virtual ~Material ()

Virtual destructor.

virtual void grab () =0

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.

virtual void release () =0

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

virtual int isOwner () const =0

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.

virtual int isHidden () const =0

Returns a value indicating if the material is hidden.

Return value

1 if the material is hidden; otherwise, 0.

virtual int isEditable () const =0

Returns a value indicating if the material is editable.

Return value

1 if the material is editable; otherwise, 0.

virtual int isReflection2D () const =0

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.

virtual int isProcedural () const =0

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

Return value

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

virtual int isFilter () const =0

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

Return value

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

virtual const char * getName () const =0

Returns a material name.

Return value

Material name.

virtual Ptr< Material > getParent () const =0

Returns the parent material smart pointer.

Return value

Parent material smart pointer.

virtual Ptr< Material > getCompare () const =0

Returns the compare material smart pointer.

Return value

Compare material smart pointer.

virtual int getNumChilds () const =0

Returns the number of child materials.

Return value

The number of child materials.

virtual int getNumChildren () const =0

Returns the number of child materials.

Return value

The number of child materials.

virtual Ptr< Material > getChild (int num) const =0

Returns the child material.

Arguments

• int num - The child material number.

Return value

The child material smart pointer.

virtual int isParent (const char * name) const =0

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.

virtual Ptr< Material > clone (const char * name) const =0

Clones the material.

Arguments

• const char * name - New material name.

Return value

Cloned material smart pointer.

virtual Ptr< Material > inherit (const char * name) const =0

Inherits the material.

Arguments

• const char * name - New material name.

Return value

Inherited material smart pointer.

virtual void setBlendFunc (int src, int dest) const =0

Sets the source and destination blending functions.

Arguments

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

virtual int getBlendSrcFunc () const =0

Gets the source blending function.

Return value

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

virtual int getBlendDestFunc () const =0

Gets the destination blending function.

Return value

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

virtual int isOpacity () const =0

Checks if alpha blending is set for the material or if it is opaque.

Return value

1 if the material is opaque; otherwise, 0.

virtual int isForwardTransparent () const =0

Returns a value indicating if the material rendered in the forward rendering pass uses alpha blending.

Return value

1 if alpha blending is used; otherwise, 0.

virtual int isDeferredTransparent () const =0

Returns a value indicating if the material rendered in the deferred rendering pass uses alpha blending.

Return value

1 if alpha blending is used; otherwise, 0.

virtual void setOrder (int order) const =0

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.

virtual int getOrder () const =0

Gets the rendering order.

Return value

Returns rendering order.

virtual void setOffset (int offset) const =0

Sets the rendering polygon offset for the material.

Arguments

• int offset - The rendering polygon offset.

virtual int getOffset () const =0

Gets the rendering polygon offset.

Return value

The rendering polygon offset.

virtual void setLightMask (int mask) const =0

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.

virtual int getLightMask () const =0

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.

virtual void setViewportMask (int mask) const =0

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.

virtual int getViewportMask () const =0

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.

virtual void setAlphaTest (int enable) const =0

Sets the alpha test option: a value indicating if alpha testing is enabled for the material.

Arguments

• int enable - The alpha test option.

virtual int getAlphaTest () const =0

Gets the alpha test option: a value indicating if alpha testing is enabled for the material.

Return value

The alpha test option.

virtual void setTwoSided (int enable) const =0

Sets the two sided option for the material.

Arguments

• int enable - The two sided option.

virtual int getTwoSided () const =0

Gets the two sided option of the material.

Return value

The two sided option.

virtual void setCastShadow (int enable) const =0

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

Arguments

• int enable - The cast shadow option.

virtual int getCastShadow () const =0

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

Return value

The cast shadow option.

virtual void setCastWorldShadow (int enable) const =0

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 enable - The cast world shadow option.

virtual int getCastWorldShadow () const =0

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.

virtual void setTransparent (int enable) const =0

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 enable - The transparent option (one of the TRANSPARENT_* variables).

virtual int getTransparent () const =0

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).

virtual int getNumStates () const =0

Returns the number of material states.

Return value

The number of material states.

virtual const char * getStateName (int num) const =0

Returns the state name.

Arguments

• int num - The state number.

Return value

State name.

virtual int getStateType (int num) const =0

Returns the state type.

Arguments

• int num - The state number.

Return value

State type.

virtual int isStateHidden (int num) const =0

Returns a value indicating if the state is hidden.

Arguments

• int num - The state number.

Return value

1 is the state is hidden; otherwise, 0.

virtual int findState (const char * name) const =0

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

Arguments

• const char * name - State name.

Return value

State number.

virtual int findState (const char * name, int fast_id) const =0

Searches for a state by its name and the fast identifier 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.

virtual void setState (int num, int value) const =0

Sets the state value.

Arguments

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

virtual int getState (int num) const =0

Gets the state value.

Arguments

• int num - State number.

Return value

State value.

virtual int getStateSwitchNumItems (int num) const =0

Returns the number of switch item names.

Arguments

• int num - State number.

Return value

Number of switch item names.

virtual const char * getStateSwitchItem (int num, int item) const =0

Returns the switch item name.

Arguments

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

Return value

Switch item name.

virtual ShaderPtr getShader (int pass, int node) const =0

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.

virtual ShaderPtr getShader (int pass) const =0

Returns the post processing shader smart pointer for the specified rendering pass.

Arguments

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

Return value

Shader smart pointer.

virtual int getNumTextures () const =0

Returns the number of material's textures.

Return value

Returns number of textures.

virtual const char * getTextureName (int num) const =0

Returns the texture name.

Arguments

• int num - The texture number.

Return value

Texture name.

virtual int getTextureType (int num) const =0

Returns the texture type.

Arguments

• int num - The texture number.

Return value

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

virtual int isTextureHidden (int num) const =0

Returns a value indicating if the texture is hidden.

Arguments

• int num - The texture number.

Return value

1 is the texture is hidden; otherwise, 0.

virtual int findTexture (const char * name) const =0

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.

virtual int findTexture (const char * name, int fast_id) const =0

Searches for a texture by its name and fast identifier 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.

virtual void setImageTextureName (int num, const char * name) const =0

Sets the image texture name.

Arguments

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

virtual const char * getImageTextureName (int num) const =0

Gets the image texture name.

Arguments

• int num - Texture number.

Return value

Image texture name.

virtual int setImageTextureImage (int num, const ImagePtr & image, int dynamic) const =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 num - Texture number.
• const ImagePtr & 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.

virtual int getImageTextureImage (int num, const ImagePtr & image) const =0

Reads the given image texture into an Image smart pointer.

Arguments

• int num - Texture number.
• const ImagePtr & image - Image smart pointer into which the texture is read.

Return value

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

virtual void setImageTexture (int num, const TexturePtr & texture) const =0

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

Arguments

• int num - Texture number.
• const TexturePtr & texture - Texture smart pointer.

virtual TexturePtr getImageTexture (int num) const =0

Gets the image texture smart pointer.

Arguments

• int num - Texture number.

Return value

Texture smart pointer.

virtual int setProceduralTextureImage (int num, const ImagePtr & image) const =0

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 ImagePtr & image - Image smart pointer.

Return value

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

virtual int getProceduralTextureImage (int num, const ImagePtr & image) const =0

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 ImagePtr & image - Image smart pointer.

Return value

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

virtual TexturePtr getProceduralTexture (int num) const =0

Gets the procedural texture smart pointer.

Arguments

• int num - Texture number.

Return value

Returns procedural texture smart pointer.

virtual int getNumParameters () const =0

Returns the number of material's parameters.

Return value

The number of parameters.

virtual const char * getParameterName (int num) const =0

Returns the material's parameter name.

Arguments

• int num - The parameter number.

Return value

Parameter name.

virtual int getParameterType (int num) const =0

Returns the material's parameter type.

Arguments

• int num - The parameter number.

Return value

Parameter type.

virtual int isParameterHidden (int num) const =0

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.

virtual int findParameter (const char * name) const =0

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

Arguments

• const char * name - Parameter name.

Return value

Parameter number.

virtual int findParameter (const char * name, int fast_id) const =0

Searches for a parameter by its name and a fast identifier 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.

virtual void setParameter (int num, const vec4 & value) const =0

Sets a material's parameter value.

Arguments

• int num - Parameter number.
• const vec4 & value - Parameter value.

virtual vec4 getParameter (int num) const =0

Gets the material's parameter value.

Arguments

• int num - Parameter number.

Return value

Parameter value.

virtual void setParameterSlider (int num, float value) const =0

Sets a slider parameter value.

Arguments

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

virtual float getParameterSlider (int num) const =0

Gets the slider parameter value.

Arguments

• int num - Parameter number.

Return value

Slider parameter value.

virtual int setParameterExpression (int num, const char * src) const =0

Sets the expression used as a parameter value.

Arguments

• int num - Parameter number.
• const char * src - Expression parameter source.

Return value

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

virtual const char * getParameterExpression (int num) const =0

Gets the expression used as the parameter value.

Arguments

• int num - Parameter number.

Return value

Parameter expression, if it exists; otherwise, NULL.

virtual void setParameterArray (int num, const Vector< vec4 > & values) const =0

Sets values for the given array parameter.

Arguments

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

virtual void getParameterArray (int num, Vector< vec4 > & values) const =0

Gets values of the given array parameter.

Arguments

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

virtual int loadWorld (const XmlPtr & xml) const =0

Loads material settings from the Xml.

Arguments

• const XmlPtr & xml - Xml smart pointer.

Return value

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

virtual int saveWorld (const XmlPtr & xml, int force) const =0

Saves material settings into the Xml.

Arguments

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

Return value

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

virtual int saveState (const StreamPtr & stream, int force) const =0

Saves material settings into the stream.

Arguments

• const StreamPtr & stream - Stream smart pointer.
• int force - Forced saving of material settings.

Return value

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

virtual int restoreState (const StreamPtr & stream, int force) const =0

Restores material settings from the stream.

Arguments

• const StreamPtr & stream - Stream smart pointer.
• int force - Forced restoring of material settings.

Return value

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

---

Unigine::Material::STATE_* Enumeration

Unigine::Material::TEXTURE_* Enumeration

Unigine::Material::PARAMETER_* Enumeration

Unigine::Material::TRANSPARENT_* Enumeration