This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Landscape Tool
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Material Class

Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

This class is used to create materials, which are assigned to each node (or each surface of the object) and define how they look like. They implement the shaders and control what options, states, parameters of different types and textures are used to render the node during the rendering passes.

The materials are referenced via GUID. Only the manual materials can be referenced via name.

The material name (taken from the file name) specifies how the material will be displayed in Materials Editor (the materials hierarchy, the nodes surface editor).

Namespaces#


Materials can be separated into different namespaces to avoid engine and user materials name collision. Default engine and editor materials have their own namespaces (Unigine and Editor respectively). For example, Unigine::mesh_base or Editor::brush_draw_post.

You can create custom namespaces for your materials. The Material::getNamespaceName() method returns the namespace of a material, if it was assigned to one.

Getting Parameter And Texture Names#

Internal names of the material's textures and parameters are displayed in UnigineEditor tooltips, clicking on the name of the parameter/texture (LMB, once) copies an internal name for it to the clipboard, which allows to easily paste it to the code.

Usage Examples#

Changing Textures#

The first example describes how to inherit a material from a base one, change material's texture and set texture flags for it. We inherit a new material my_mesh_base_0.mat from the mesh_base material, assign it to the default material ball object, change its albedo texture and set the FILTER_POINT flag for it.

Add the following code to the world script file.

Source code (UnigineScript)
// your_world_name.usc

/* .. */

int init() {

	/* .. */
	
	// inherit a new material from the material_ball
	Material m = engine.materials.findManualMaterial("Unigine::mesh_base").inherit("my_mesh_base_0");

	// getting the material_ball object and assigning the material_ball_0 material to it
	ObjectMeshStatic material_ball = node_cast(engine.world.getNodeByName("material_ball"));
	material_ball.setMaterialPath("materials/my_mesh_base_0", "*");

	
	// check if our material is editable and perform modifications
	if (m.isEditable()){
		log.message("Material (%s) is editable.\n", m.getPath());

		// get the number of the albedo texture of the my_mesh_base_0 material
		int num = m.findTexture("albedo");
		// change albedo texture of the material to core/textures/common/checker_d.dds
		Image image = new Image("core/textures/common/checker_d.dds");
		m.setTextureImage(num, image);

		// get current flags, check if point filtering is enabled and display the result in the console
		int flags = m.getTextureSamplerFlags(num);
		log.message("Flags for %s texture (%d):%d \n", m.getTextureName(num), num, flags);
		log.message("FILTER_POINT %s\n", (flags & TEXTURE_FILTER_POINT)? "enabled": "disabled");

		// set the FILTER_POINT flag
		m.setTextureSamplerFlags(num, TEXTURE_FILTER_POINT);

		// get the flags, check if point filtering is enabled and display the result in the console
		int flagsSet = m.getTextureSamplerFlags(num);
		log.message("Flags for %s texture (%d):%d \n", m.getTextureName(num), num, flagsSet);
		log.message("FILTER_POINT %s\n", (flagsSet & TEXTURE_FILTER_POINT) ? "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:

Output
Material (my_mesh_base_0) is editable.
Flags for albedo texture (1):2048000
FILTER_POINT disabled
Flags for albedo texture (1):4096
FILTER_POINT enabled

Changing States and Parameters#

The second example illustrates how to inherit a material from the mesh_base and change two parameters affecting the look of reflections.

Add the following code to the world script file.

Source code (UnigineScript)
// your_world_name.usc

/* .. */

int init() {

	/* .. */
	
	// find the mesh_base material
	Material mesh_base = engine.materials.findManualMaterial("Unigine::mesh_base");
	// inherit a new material from it 
	Material reflector_material = mesh_base.inherit();

	// set metallness and roughness parameters to make the surface look like a mirror
	// by the name of the parameter
	reflector_material.setParameter("metalness", 1.0f);
	// or by its id, which is the same
	reflector_material.setParameter(reflector_material.findParameter("roughness"), 0.0f);

	// save the material asset to planar_reflector.mat file in the data project folder
	reflector_material.createMaterialFile("planar_reflector.mat");
			
	// assign the mesh_base material to the material ball by its path
	ObjectMeshStatic material_ball = node_cast(engine.world.getNodeByName("material_ball"));
	material_ball.setMaterialPath("core/materials/base/objects/mesh/mesh_base.basemat","*");

	// assign new reflective material to the ground object
	ObjectMeshDynamic ground = node_cast(engine.world.getNodeByName("ground"));
	ground.setMaterial(reflector_material, 0);

	
	return 1;
}

/* .. */

Material Class

Members


static Material ( ) #

Constructor. Creates a new material instance.

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 isBrush ( ) #

Returns a value indicating if the material is used for brushes (*.brush or *.basebrush file extension).

Return value

1 if the material is used for brushes; otherwise, 0.

void setBlendDestFunc ( int func ) #

Sets the destination blending function.

Arguments

  • int func - One of the MATERIAL_BLEND_* variables, which specify ways of calculating the blend factor.

int getBlendDestFunc ( ) #

Returns the destination blending function.

Return value

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

void setBlendSrcFunc ( int func ) #

Sets the source blending function.

Arguments

  • int func - One of the MATERIAL_BLEND_* variables, which specify ways of calculating the blend factor.

int getBlendSrcFunc ( ) #

Returns the source blending function.

Return value

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

void setCastShadow ( int shadow ) #

Enables or disables the cast shadow option for an object with the material applied.

Arguments

  • int shadow - 1 to enable casting of shadows, 0 to disable it.

int isCastShadow ( ) #

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

Return value

1 if casting of shadows is enabled; otherwise, 0.

void setCastWorldShadow ( int shadow ) #

Enables or disables casting of shadows from the world light for an object with the material applied.

Arguments

  • int shadow - 1 to enable casting of shadows from the world light, 0 to disable it.

int isCastWorldShadow ( ) #

Returns a value indicating if an object with the material applied casts shadows from the world light.

Return value

1 if casting of shadows from the world light is enabled; otherwise, 0.

Material getChild ( int num ) #

Returns a child material with a given number.

Arguments

  • int num - Child material number.

Return value

Child material.

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

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

Arguments

  • int mask - 1 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.

void setDepthTest ( int test ) #

Enables or disables the depth testing option for the material. This option can be used to render certain objects, that are behind other ones.

Arguments

  • int test - 1 to enable depth testing for the material, 0 to disable it.

int isDepthTest ( ) #

Returns a value indicating if depth testing is enabled for the material. This option can be used to render certain objects, that are behind other ones.

Return value

1 if depth testing is enabled for the material; otherwise, 0.

int isEditable ( ) #

Returns a value indicating if the material can be edited.

Return value

1 if the material is editable; 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 setShadowMask ( int mask ) #

Sets a shadow mask for the material.

For the shadow to be rendered for a light source from an object's surface having this material assigned, this mask must match the following ones (one bit, at least):

The surface with the assigned material lit by a light source casts shadow if the shadow mask of the light source matches the corresponding masks of the surface and its material.

Arguments

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

int getShadowMask ( ) #

Returns a shadow mask of the material.

For the shadow to be rendered for a light source from an object's surface having this material assigned, this mask must match the following ones (one bit, at least):

Return value

Integer value, each bit of which is a mask.

int getNumChildren ( ) #

Returns the number of child materials.

Return value

Number of child materials.

int getNumParameters ( ) #

Returns the number of material's parameters.

Return value

Number of material's parameters.

int getNumStates ( ) #

Returns the number of material's states.

Return value

Number of material's states.

int getNumTextures ( ) #

Returns the number of textures used by the material.

Return value

Number of used textures.

void setOrder ( int order ) #

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

Arguments

  • int order - Rendering order, in the range from -128 to 127.

int getOrder ( ) #

Returns the rendering order of materials.

Return value

Rendering order, in the range from -128 to 127.

void setOverlap ( int overlap ) #

Enables or disables the overlap option for the material. This option enables rendering the material over the final image and can be used for UI elements.

Arguments

  • int overlap - 1 to enable the overlap option for the material, 0 to disable it.

int isOverlap ( ) #

Returns a value indicating if the overlap option is enabled for the material. This option enables rendering the material over the final image and can be used for UI elements.

Return value

1 if the overlap option is enabled for the material; otherwise, 0.

int isParameterExpressionEnabled ( int num ) #

Returns a value indicating if the value of the specified material parameter is represented by an expression in UnigineScript. Values of certain parameters can be calculated by an arbitrary expression, written in UnigineScript. .

Arguments

Return value

1 if the value of the specified material parameter is represented by an expression in UnigineScript; otherwise, 0.

void setParameterExpressionEnabled ( int num, int enabled ) #

Sets a value indicating if the value of the specified material parameter is represented by an expression in UnigineScript. Values of certain parameters can be calculated by an arbitrary expression, written in UnigineScript. .

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • int enabled - 1 to enable setting the values of the specified material parameter by an expression in UnigineScript; 0 - to disable.

int isParameterOverridden ( int num ) #

Returns a value indicating if a given parameter is overridden.

Arguments

Return value

1 if the given parameter is overridden; otherwise, 0.

void setParameter ( int num, Variable arg2 ) #

Sets a material's parameter value.

Arguments

void setParameter ( string name, Variable arg2 ) #

Sets the specified value to the parameter with the given name.

Arguments

Variable getParameter ( string name ) #

Returns a value of the parameter with the given name.

Arguments

Return value

Parameter value.

Variable getParameter ( int num ) #

Returns a value of the parameter with the given number.

Arguments

Return value

Parameter value.

int isParameterInt ( int num ) #

Returns a value indicating if the parameter with the specified number is an integer-type parameter.

Arguments

Return value

0 if the parameter with the specified number is an integer-type parameter; otherwise, 1.

int isParameterFloat ( int num ) #

Returns a value indicating if the parameter with the specified number is a float-type parameter.

Arguments

Return value

0 if the parameter with the specified number is an float-type parameter; otherwise, 1.

int getParameterArraySize ( int num ) #

Returns the number of elements in the array parameter with the specified number.

Arguments

Return value

Number of elements of the specified array parameter.

int isParameterArray ( int num ) #

Returns a value indicating if the parameter with the specified number is an array-type parameter, i.e., one of the following:

Arguments

Return value

1 if the parameter is an array-type parameter; otherwise, 0.

void getParameterArray ( int num ) #

Returns a value of the array parameter (type: PARAMETER_ARRAY_FLOAT4) with the specified number and puts it to the specified buffer array.

Arguments

void setParameterArray ( int num ) #

Sets a value of the array parameter (type: PARAMETER_ARRAY_FLOAT4) with the specified number using the specified array.

Arguments

void setParameterArray ( Variable param, int values ) #

Sets a value of the array parameter (type: PARAMETER_ARRAY_FLOAT4) with the specified number using the specified array.

Arguments

void getParameterArray ( Variable param, int values ) #

Returns a value of the array parameter with the specified number and puts it to the specified buffer array.

Arguments

int setParameterExpression ( int num, string expression ) #

Sets the expression used as a parameter value.

Arguments

Return value

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

string getParameterExpression ( int num ) #

Returns an expression used as a parameter value.

Arguments

Return value

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

string getParameterName ( int num ) #

Returns the name of a given parameter.

Arguments

Return value

Parameter name.

int getParameterType ( int num ) #

Returns the type of a given parameter.

Arguments

Return value

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

Material getParent ( ) #

Returns the parent material.

Return value

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

bool isParent ( ) #

Returns a value indicating if the material with the given GUID is a parent of the current material.

Arguments

    Return value

    true if the material is the parent; otherwise, false.

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

    int checkShaderCache ( int pass, int node_type ) #

    Returns a value indicating if shader combination for the given rendering pass and node type is already in cache.

    Arguments

    • int pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
    • int node_type - Node type.

    Return value

    1 if shader combination for the given rendering pass and node type is already in cache; otherwise, 0.

    int compileShader ( int pass, int node_type ) #

    Compiles shader combination for the given rendering pass and node type.

    Arguments

    • int pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
    • int node_type - Node type.

    Return value

    1 if shader combination for the given rendering pass and node type was compiled successfully; otherwise, 0.

    int isStateInternal ( int num ) #

    Returns a value indicating if a given state is internal.

    Arguments

    • int num - State number.

    Return value

    1 if the given state is internal; otherwise, 0.

    int 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 ( int value ) #

    Sets the value of the given state.

    Arguments

    • int value - State value.

    int getState ( int num ) #

    Returns the state value.

    Arguments

    • int num - State number.

    Return value

    State value.

    int getState ( ) #

    Returns the value of the given state.

    Arguments

      Return value

      State value.

      string getStateName ( int num ) #

      Returns the name of a given state.

      Arguments

      • int num - State number.

      Return value

      State name.

      string getStateSwitchItem ( int num, int item ) #

      Returns the switch item name for a given state.

      Arguments

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

      Return value

      Switch item name or NULL (0), if an error has occurred.

      int getStateSwitchNumItems ( int num ) #

      Returns the number of switch items for a given state.

      Arguments

      • int num - State number.

      Return value

      Number of switch items.

      int getStateType ( int num ) #

      Returns the type of a given state.

      Arguments

      • int num - State number.

      Return value

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

      int isTextureInternal ( int num ) #

      Returns a value indicating if a given texture is internal.

      Arguments

      • int num - Texture number.

      Return value

      1 if the given texture is internal; otherwise, 0.

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

      int isTextureLoaded ( int num ) #

      Returns a value indicating if a given texture is loaded.

      Arguments

      • int num

      Return value

      1 if the given texture is loaded; otherwise, 0.

      string getTextureName ( int num ) #

      Returns the name of a given texture.

      Arguments

      • int num - Texture number.

      Return value

      Texture name.

      int getTextureUnit ( int num ) #

      Returns the number of the unit for a given texture used in shaders.

      Arguments

      • int num - Texture number.

      Return value

      Texture unit number.

      int getTextureSource ( int num ) #

      Returns the source for the texture with the specified number.

      Arguments

      • int num - Texture number.

      Return value

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

      void setTransparent ( int transparent ) #

      Sets a value indicating the transparency type of the material. If the transparent option is set to TRANSPARENT_NONE or TRANSPARENT_DEFERRED, the setBlendSrcFunc() and setBlendDestFunc() blending functions won't be used.

      Arguments

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

      int getTransparent ( ) #

      Returns a value indicating the transparency type of the material.

      Return value

      One of the TRANSPARENT_* variables.

      void setTwoSided ( int sided ) #

      Enables or disables the two sided option for the material.

      Arguments

      • int sided - 1 to make the material two-sided, 0 to make it one-sided.

      int isTwoSided ( ) #

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

      Return value

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

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

      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.

      Material clone ( ) #

      Clones the material. The cloned material will be empty: it will have a GUID but won't be displayed in the materials hierarchy.

      Return value

      Cloned material.

      int findParameter ( string name ) #

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

      Arguments

      Return value

      Parameter number, if it is found; otherwise, -1.

      int findState ( string name ) #

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

      Arguments

      • string name - State name.

      Return value

      State number, if it is found; otherwise, -1.

      int findTexture ( string name ) #

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

      Arguments

      Return value

      Texture number, if it is found; otherwise, -1.

      Material inherit ( ) #

      Inherits the material. The inherited material will be empty: it will have a GUID but won't be displayed in materials hierarchy.

      Return value

      Inherited material.

      int saveState ( Stream stream, int forced = 0 ) #

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

      Saving into the stream requires creating a blob to save into. To restore the saved state the restoreState() method is used:

      Source code (UnigineScript)
      // initialize object
      Material mat = object.getMaterial(0);
      mat.setViewportMask(1); // viewport mask = 1
      	
      // save state
      Blob blob_state = new Blob();
      mat.saveState(blob_state);
      	
      // change something
      mat.setViewportMask(~0);  // now viewport mask = 111111111
      	
      // restore state
      blob_state.seekSet(0);		// returning the carriage to the start of the blob
      mat.restoreState(blob_state);  // restore viewport mask = 1

      Arguments

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

      Return value

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

      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.

      Restoring from the stream requires creating a blob to save into and saving the state using the saveState() method:

      Source code (UnigineScript)
      // initialize object
      Material mat = object.getMaterial(0);
      mat.setViewportMask(1); // viewport mask = 1
      	
      // save state
      Blob blob_state = new Blob();
      mat.saveState(blob_state);
      	
      // change something
      mat.setViewportMask(~0);  // now viewport mask = 111111111
      	
      // restore state
      blob_state.seekSet(0);		// returning the carriage to the start of the blob
      mat.restoreState(blob_state);  // restore viewport mask = 1

      Arguments

      • Stream stream - The stream with saved material data.
      • int forced - Forced restoring of material settings.

      Return value

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

      int 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 overridden value of the given state to the parent one.

      Arguments

      • int num - State number.

      void setTexturePath ( int num ) #

      Sets a new path to the texture with the given number.

      Arguments

      • int num - Texture number.

      void setTexturePath ( ) #

      Sets a new path to the texture with the given name.

      Arguments

        void resetTexture ( int num ) #

        Resets the overridden value of the given texture to the parent one.

        Arguments

        • int num - Texture number.

        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.

        getTexturePath ( ) #

        Returns a path to the texture with the specified name.

        Arguments

          Return value

          A path to the texture.

          int isNodeTypeSupported ( int 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, int 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).
          Notice
          The method isn't available for the manual and base materials.

          Arguments

          • Material material - Material to be set as the parent for this material.
          • int 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.

          int 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 isInternal ( ) #

          Returns a value indicating if the current material is internal.

          Return value

          1 if the material is internal; otherwise, 0.

          int loadXml ( Xml xml ) #

          Loads material settings from the specified Xml source.

          Arguments

          • Xml xml - An Xml node containing material settings.

          Return value

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

          int loadUlon ( UlonNode ulon ) #

          Loads material settings from the specified ULON source.

          Arguments

          • UlonNode ulon - A ULON-node containing material settings.

          Return value

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

          int hasOverrides ( ) #

          Returns a value indicating if the material has at least one overridden property.

          Return value

          1 if the material has at least one overridden property; otherwise, 0.

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

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

          int isManual ( ) #

          Returns a value indicating if the current material is manual.

          Return value

          1 if the material is manual; otherwise, 0.

          int isAutoSave ( ) #

          Returns a value indicating if the material can be saved automatically (automatic material saving is performed, for example, on world's saving). The function will return 0 in the following cases:

          Return value

          1 if the material can be saved automatically; otherwise, 0.

          int isLegacy ( ) #

          Returns a value indicating if the material is a legacy one. A legacy material is a non-ULON base material described in an XML file.

          Return value

          1 if the material is a legacy one; otherwise, 0.

          int isPreviewHidden ( ) #

          Returns a value indicating if preview in the UnigineEditor is disabled for the material. This method is used for custom materials (e.g., landscape terrain brushes).

          Return value

          1 if preview in the UnigineEditor is disabled for the material; otherwise, 0.

          int checkParameterConditions ( int num ) #

          Checks if conditions set for the given parameter are met.

          Arguments

          Return value

          1 if conditions are met; othersiwe, 0.

          int save ( ) #

          Save the material to the current path used for this material.
          Notice
          The method isn't available for the manual and base materials.

          Return value

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

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

          int saveXml ( Xml xml ) #

          Saves the material into the given Xml.
          Notice
          The method isn't available for the manual and base materials.

          Arguments

          • Xml xml - An Xml node.

          Return value

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

          int isBase ( ) #

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

          Return value

          1 if the material is the base one; otherwise, 0.

          int isNodeSupported ( Node node ) #

          Returns a value indicating if the material can be applied to the given node.

          Arguments

          Return value

          1 if the given node is supported; otherwise, 0.

          Material getBaseMaterial ( ) #

          Returns the base material of the current material.

          Return value

          A base material.

          void setTexture ( int num, Texture texture ) #

          Sets the given texture to the texture with the specified number.

          Arguments

          • int num - Texture number.
          • Texture texture - Texture to be set.

          Texture getTexture ( int num ) #

          Returns a texture set for the current material.

          Arguments

          • int num - Texture number.

          Return value

          A texture.

          string getPath ( ) #

          Returns a path to the current material.

          Return value

          Path to the material.

          void resetParameter ( int num ) #

          Resets the overridden value of the given parameter to the parent one.

          Arguments

          int reload ( ) #

          Reloads the material and all its children.

          Return value

          1 if the material is reloaded successfully; 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.

          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.

          TextureCurve getTextureCurve ( int num ) #

          Returns a curve texture instance for the data stored in the specified curve texture (gradient).
          Notice
          Modifications made to the curve shall propagate to the parent and sibling materials. To modify an overridden curve for this material only use the getTextureCurveOverride() method.

          Arguments

          • int num - Texture number.

          Return value

          TextureCurve class instance for the data stored in the gradient texture with the specified number.

          TextureCurve getTextureCurveOverride ( int num ) #

          Returns a new curve texture instance for the data stored in the specified curve texture (gradient) overriding the default one. This method enables you to set individual RGBA curves, adjusting color values of the resulting curve texture (gradient).
          Notice
          Modifications made to the curve shall not propagate to the parent and sibling materials.

          Arguments

          • int num - Texture number.

          Return value

          New TextureCurve class instance overriding the data stored in the specified curve texture (gradient).

          UGUID getGUID ( ) #

          Returns the GUID of the material.

          Return value

          GUID of the material.

          int isEngine ( ) #

          Returns a value indicating if the current material is engine-related (i.e. required for engine operation). Such materials are stored in the core, editor and editor2 folders.

          Return value

          1 if the material is engine-related; otherwise, 0.

          void destroyShaders ( ) #

          Deletes all shaders used for the current material and its children and clears shaders cache.

          void createShaders ( int recursive = 0 ) #

          Creates all shaders for the current material and its children (if specified).

          Arguments

          • int 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.

          int isEmpty ( ) #

          Returns a value indicating if an empty shader is used as a vertex shader in the current material.

          Return value

          1 if an empty vertex shader is used; otherwise, 0.

          int 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 ( int type ) #

          Returns the name of the rendering pass by its number (including custom passes).

          Arguments

          • int type - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).

          Return value

          Rendering pass name if it exists; otherwise NULL.

          int runExpression ( string name, int w, int h, int d = 1 ) #

          Runs the material's expression with the specified name. An expression is a reference to a file containing code in UnigineScript, that can generate various elements used in the material (e.g., textures, texture arrays, unstructured buffers, etc.) or contain other logic. Expressions can be defined in the *.basemat file as follows:
          Source code (ULON)
          Expression name = "expression.usc";

          An example of expression.usc code:

          Source code (UnigineScript)
          // typical most frequently used parameters passed to the expression automatically, when it is called.
          int in_width;
          int in_height;
          int in_depth;
          Material in_material;
          
          // If you need extra parameters, you should set them via Material::setParameter*("param_name", value) before calling Material::runExpression()
          // then you can access them in the expression via in_material.getParameter*("param_name")
          
          // ...
          
          // get a temporary texture
          Texture texture = engine.render.getTemporaryTexture(in_width, in_height);
          
          //get the value of the material parameter named "my_extra_param"
          float my_param = in_material.getParameter("my_extra_param");
          
          // modify the temporary texture using the my_param parameter somehow...
          
          // set the modified texture as albedo texture of the material
          in_material->setTexture("albedo", texture);

          To execute this expression the following code can be used:

          Source code (C++)
          // ...
          // setting the value of extra parameter
          material->setParameterFloat("my_extra_param", 2.5f);
          
          // running the expression 
          material->runExpression("expr_name", 512, 512, 1);
          // ...
          Notice
          Expressions can be executed only for base materials.

          Arguments

          • string name - Expression name. Expression with this name must be defined in the material declaration (*.basemat file).
          • int w - Width, e.g. if a texture or a structured buffer is generated by the expression.
          • int h - Height, e.g. if a texture or a structured buffer is generated by the expression.
          • int d - Depth, e.g. if a 3D Texture, 2D array or a structured buffer is generated by the expression.

          Return value

          1 if the specified expression is executed successfully; otherwise, 0.

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

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

          int getNumUIItems ( ) #

          Returns the number of UI items. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.

          Return value

          Total number of UI items availeble in UnigineEditor for the material.

          int getUIItemDataType ( int item ) #

          Returns the type of data of the specified UI item. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.

          Arguments

          Return value

          UI item data type (parameter, option, state, texture, or group).

          int getUIItemDataID ( int item ) #

          Returns the id of the data type controlled by the specified UI item. UI items represent material parameters, options, states, textures, and groups in UnigineEditor.

          Arguments

          Return value

          UI item data id: one of the STATE_*, PARAMETER_*, OPTION_*, TEXTURE_SOURCE_* pre-defined variables or -1, if an error has occurred.

          int isUIItemHidden ( int item ) #

          Returns a value indicating if the specified UI item is hidden.

          Arguments

          Return value

          1 is the specified UI item is hidden; otherwise, 0.

          string getUIItemTitle ( int item ) #

          Returns the title set for the specified UI item.

          Arguments

          Return value

          Title set for the specified UI item.

          string getUIItemTooltip ( int item ) #

          Returns the text of the tooltip set for the specified UI item.

          Arguments

          Return value

          Text of the tooltip set for the specified UI item.

          int getUIItemWidget ( int item ) #

          Returns the type of the widget for the specified UI item.

          Arguments

          Return value

          UI item widget type.

          int getUIItemParent ( int item ) #

          Returns an index of the parent of the specified UI item. This method is used to get the index of the group to which the specified parameter/state/option/texture belongs.

          Arguments

          Return value

          Global index of the parent UI element in the range from 0 to the total number of UI items for the material.

          int getUIItemNumChildren ( int item ) #

          Returns the number of child items for the group UI item with the specified number.
          Notice
          This method is to be used for UI item groups only (DATA_TYPE_GROUP), other items cannot have children!

          Arguments

          Return value

          Number of child items for the specified group UI item.

          int getUIItemChild ( int item, int num ) #

          Returns the index of a child UI item that belongs to the specified group by the item number within the group.
          Notice
          This method is to be used for UI item groups only (DATA_TYPE_GROUP), other items cannot have children!

          Arguments

          • int item - UI item group index in the range from 0 to the total number of UI items.
          • int num - Number of UI item within the group (in the list of children).

          Return value

          Global index of the child UI element in the range from 0 to the total number of UI items for the material.

          int isUIItemSliderMinExpand ( int item ) #

          Returns a value indicating if the maximum slider value for the specified UI item can be increased.

          Arguments

          Return value

          1 if the maximum value can be increased; otherwise, 0.

          int isUIItemSliderMaxExpand ( int item ) #

          Returns a value indicating if the minimum slider value for the specified UI item can be decreased.

          Arguments

          Return value

          1 if the minimum value can be decreased; otherwise, 0.

          float getUIItemSliderMinValue ( int item ) #

          Returns the minimum allowed value of the slider for the specified UI item.

          Arguments

          Return value

          Minimum value of the slider.

          float getUIItemSliderMaxValue ( int item ) #

          Returns the maximum allowed value of the slider for the specified UI item.

          Arguments

          Return value

          Maximum value of the slider.

          int getUIItemGroupToggleStateID ( int item ) #

          Returns the global index of the state toggle UI element turning the specified group on and off.
          Notice
          This method is to be used for UI item groups only (DATA_TYPE_GROUP)!

          Arguments

          Return value

          Global index of the state toggle UI element in the range from 0 to the total number of UI items for the material.

          int isUIItemGroupCollapsed ( int item ) #

          Returns a value indicating if the specified group of UI items is currently collapsed in the UI of the Unigine Editor.
          Notice
          This method is to be used for UI item groups only (DATA_TYPE_GROUP)!

          Arguments

          Return value

          1 if the specified group of UI items is currently collapsed in the UI; otherwise, 0 (the group is expanded).

          void setOption ( int num, int value ) #

          Sets a new value for the specified option.

          Arguments

          • int num - Option number.
          • int value - New value to be set for the specified option.

          int getOption ( int num ) #

          Returns the current value of the specified option.

          Arguments

          • int num - Option number.

          Return value

          Current value of the specified option.

          int isOptionOverridden ( int num ) #

          Returns a value indicating if a given option is overridden.

          Arguments

          • int num - Option number.

          Return value

          1 if the given option is overridden; otherwise, 0.

          void resetOption ( int num ) #

          Resets the overridden value of the given option to the parent one.

          Arguments

          • int num - Option number.

          int isParent ( Material parent ) #

          Returns a value indicating if the given material is a parent of the current material.

          Arguments

          • Material parent

          Return value

          1 if the material is the parent, otherwise - 0.

          Material clone ( UGUID guid ) #

          Clones the material and assigns the given GUID to it.
          Notice
          A base material cannot be cloned.

          Arguments

          • UGUID guid - Cloned material GUID.

          Return value

          Cloned material.

          Material inherit ( UGUID guid ) #

          Inherits a new material from the current one and assigns the specified GUID to it.

          Arguments

          • UGUID guid - Inhereted material GUID.

          Return value

          Inhereted material.

          string getNamespaceName ( ) #

          Returns the namespace where this material is defined.

          Return value

          Material namespace.

          string getManualName ( ) #

          Returns the name of the manual material.

          Return value

          Manual material name.

          string widgetToString ( int widget ) #

          Returns the name of the widget by its type.

          Arguments

          Return value

          Name of the widget.

          int stringToWidget ( string str ) #

          Returns the widget type by its name.

          Arguments

          • string str - Name of the widget.

          Return value

          Widget type.

          int getTextureSamplerFlags ( int num ) #

          Returns the sampler flags of the texture with the given number.

          Arguments

          • int num - Number of the texture.

          Return value

          Texture sampler flags.

          void setTextureSamplerFlags ( int num, int sampler_flags ) #

          Sets the sampler flags for the texture with the given number.

          Arguments

          • int num - Number of the texture.
          • int sampler_flags - Sampler flags.

          int getTextureFormatFlags ( int num ) #

          Returns the format flags of the texture with the given number.

          Arguments

          • int num - Number of the texture.

          Return value

          Texture format flags.

          int createMaterialFile ( string path ) #

          Creates a file and saves the internal material to it.

          Arguments

          • string path - A path to save the material

          Return value

          The value indicating if the material was successful saved.

          int isReflection2D ( ) #

          Last update: 2022-01-21
          Build: ()