This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Basics
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
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
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Animations-Related Classes
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
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::Material Class

Header: #include <UnigineMaterial.h>

This class is used to create materials that are assigned to each node (or each surface of the object) and define what the nodes look like. Materials implement the shaders and control what options, states, parameters 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) defines how the material is displayed in Materials Editor (the materials hierarchy, the nodes surface editor).

Namespaces#


Materials can be separated into different namespaces to avoid the engine and the 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 has been assigned to any.

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 the material 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 SAMPLER_FILTER_POINT flag for it.

Add the following code to the AppWorldLogic.cpp file.

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineMaterials.h>
#include <UnigineWorld.h>

using namespace Unigine;

/* .. */

int AppWorldLogic::init()
{

	// pointer to material to be inherited from mesh_base and customized
	MaterialPtr m;

	// finding the mesh_base material
	MaterialPtr mesh_base_mat = Materials::findManualMaterial("Unigine::mesh_base");
	if (mesh_base_mat) {
		// inheriting a new material from the mesh_base
		m = mesh_base_mat->inherit();

		// check if our material is editable and perform modifications
		if (m->isEditable()) {
			Log::message("Material (%s) is editable.\n", m->getFilePath());

			// get the number of the albedo texture of the material
			int num = m->findTexture("albedo");

			// change albedo texture of the material to core/textures/common/checker_d.texture
			m->setTexturePath(num, "core/textures/common/checker_d.texture");

			// 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("SAMPLER_FILTER_POINT %s\n", (flags & Texture::SAMPLER_FILTER_POINT) ? "enabled" : "disabled");

			// set the SAMPLER_FILTER_POINT flag
			m->setTextureSamplerFlags(num, Texture::SAMPLER_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("SAMPLER_FILTER_POINT %s\n", (flagsSet & Texture::SAMPLER_FILTER_POINT) ? "enabled" : "disabled");
		}

		// saving the material asset to the specified path 
		if (!Materials::findMaterialByPath("materials/my_mesh_base_0.mat"))
			m->createMaterialFile("materials/my_mesh_base_0.mat");

		// getting the material_ball object and assigning the material_ball_0 material to it
		if (ObjectMeshStaticPtr material_ball = checked_ptr_cast<ObjectMeshStatic>(World::getNodeByName("material_ball")))
			material_ball->setMaterialFilePath("materials/my_mesh_base_0.mat", "*");
	}

	return 1;
}

As a result you'll see that the albedo texture of the material ball object has changed and the following text is displayed in the console:

Output
Material (guid://4dfec30f491f753f6e89094db6d3d695e89f9d6f) is editable.
Flags for albedo texture (1):524288000
FILTER_POINT disabled
Flags for albedo texture (1):1048576
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 AppWorldLogic.cpp file.

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineMaterials.h>
#include <UnigineWorld.h>

using namespace Unigine;

/* .. */

int AppWorldLogic::init()
{

	// find the mesh_base material
	MaterialPtr mesh_base = Materials::findManualMaterial("Unigine::mesh_base");
	// inherit a new material from it and assign the path to asset to be created on save() call:
	MaterialPtr reflector_material = mesh_base->inherit();

	// set the metallness and the roughness parameter to make the surface look like a mirror
	// by the name of the parameter
	reflector_material->setParameterFloat("metalness", 1.0f);
	// or by its index number (either of these two approaches can be used to achieve the same result)
	reflector_material->setParameterFloat(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 new mirror material to the ground object
	ObjectMeshDynamicPtr ground = checked_ptr_cast<ObjectMeshDynamic>(World::getNodeByName("ground"));
	ground->setMaterial(reflector_material, "*");

	return 1;
}

Material Class

Enums

WIDGET#

NameDescription
WIDGET_EDIT_INT = 0Text widget enabling you to set an integer value.
WIDGET_EDIT_INT2 = 1Text widget enabling you to set 2 integer values.
WIDGET_EDIT_INT3 = 2Text widget enabling you to set 3 integer values.
WIDGET_EDIT_INT4 = 3Text widget enabling you to set 4 integer values.
WIDGET_EDIT_FLOAT = 4Text widget enabling you to set a float or integer value.
WIDGET_EDIT_FLOAT2 = 5Text widget enabling you to set 2 float or integer values.
WIDGET_EDIT_FLOAT3 = 6Text widget enabling you to set 3 float or integer values.
WIDGET_EDIT_FLOAT4 = 7Text widget enabling you to set 4 float or integer values.
WIDGET_TOGGLE = 8Button widget allowing you to enable or disable a certain state.
WIDGET_COMBOBOX = 9ComboBox widget enabling you to select a texture out of available ones.
WIDGET_TEXTURE_ASSET = 10Texture asset widget enabling you to specify a texture.
WIDGET_TEXTURE_RAMP = 11Ramp asset widget enabling you to specify and adjust a 2D Ramp via the dedicated Curve Editor.
WIDGET_ACCORDION = 12Accordion widget enabling you to expand or collapse a set of widgets it contains.
WIDGET_SLIDER = 13Slider widget enabling you to specify and adjust a float or integer value.
WIDGET_COLOR = 14Color widget enabling you to specify a color via a color picker dialog.
WIDGET_UV = 15UV texture asset widget enabling you to specify a UV texture.
WIDGET_MASK24 = 1624-bit mask widget.
WIDGET_MASK32 = 1732-bit mask widget.

DATA_TYPE#

NameDescription
DATA_TYPE_OPTION = 0Material option.
DATA_TYPE_STATE = 1Material state. States are flags that are used for a shader corresponding to the material. States define a set of textures and parameters of the material.
DATA_TYPE_PARAMETER = 2Material parameter.
DATA_TYPE_TEXTURE = 3Material texture.
DATA_TYPE_GROUP = 4Material group.

Members


static MaterialPtr create ( ) #

Constructor. Creates a new material instance.

bool isAlphaTest ( ) const#

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.

bool isBrush ( ) const#

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 - Destination blending function to be set (one of the BLEND_* variables).

int getBlendDestFunc ( ) const#

Returns the destination blending function.

Return value

Destination blending function (one of the BLEND_* variables).

void setBlendSrcFunc ( int func ) #

Sets the source blending function.

Arguments

  • int func - Source blending function to be set (one of the BLEND_*values described in the RenderState class).

int getBlendSrcFunc ( ) const#

Returns the source blending function.

Return value

Source blending function (one of the BLEND_*values described in the RenderState class).

void setCastShadow ( bool shadow ) #

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

Arguments

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

bool isCastShadow ( ) const#

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 ( bool shadow ) #

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

Arguments

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

bool isCastWorldShadow ( ) const#

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.

Ptr<Material> getChild ( int num ) const#

Returns a child material with a given number.

Arguments

  • int num - Child material number.

Return value

The child material smart pointer.

bool isDeferred ( ) const#

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 setDepthTest ( bool 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

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

bool isDepthTest ( ) const#

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.

bool isEditable ( ) const#

Returns a value indicating if the material can be edited.

Return value

1 if the material is editable; otherwise, 0.

bool isForward ( ) const#

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.

bool isHidden ( ) const#

Returns a value indicating if the material is hidden.

Return value

true if the material is hidden; otherwise, false.

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

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

Returns the number of child materials.

Return value

Number of child materials.

int getNumParameters ( ) const#

Returns the number of material's parameters.

Return value

Number of material's parameters.

int getNumStates ( ) const#

Returns the number of material's states.

Return value

Number of material's states.

int getNumTextures ( ) const#

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

Returns the rendering order of materials.

Return value

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

void setOverlap ( bool 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

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

bool isOverlap ( ) const#

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.

bool isParameterExpressionEnabled ( int num ) const#

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

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

void setParameterExpressionEnabled ( int num, bool 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.
  • bool enabled - true to enable setting the values of the specified material parameter by an expression in UnigineScript; false - to disable.

bool isParameterOverridden ( int num ) const#

Returns a value indicating if a given parameter is overridden.

Arguments

Return value

true if the given parameter is overridden; otherwise, false.

bool isParameterInt ( int num ) const#

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

Arguments

Return value

true if the parameter with the specified number is an integer-type parameter; otherwise, false.

bool isParameterFloat ( int num ) const#

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

Arguments

Return value

true if the parameter with the specified number is an float-type parameter; otherwise, false.

float getParameterFloat ( const char * name ) const#

Returns a value of a float parameter with the specified name.

Arguments

Return value

Float parameter value.

Math::vec2 getParameterFloat2 ( const char * name ) const#

Returns a value of a FLOAT2 parameter with the specified name.

Arguments

Return value

Parameter value as a vec2 vector.

Math::vec3 getParameterFloat3 ( const char * name ) const#

Returns a value of a FLOAT3 parameter with the specified name.

Arguments

Return value

Parameter value as a vec3 vector.

Math::vec4 getParameterFloat4 ( const char * name ) const#

Returns a value of a FLOAT4 parameter with the specified name.

Arguments

Return value

Parameter value as a vec4 vector.

int getParameterInt ( const char * name ) const#

Returns a value of an integer parameter with the specified name.

Arguments

Return value

Integer parameter value.

Math::ivec2 getParameterInt2 ( const char * name ) const#

Returns a value of a INT2 parameter with the specified name.

Arguments

Return value

Parameter value as an ivec2 vector.

Math::ivec3 getParameterInt3 ( const char * name ) const#

Returns a value of a INT3 parameter with the specified name.

Arguments

Return value

Parameter value as an ivec3 vector.

Math::ivec4 getParameterInt4 ( const char * name ) const#

Returns a value of a INT4 parameter with the specified name.

Arguments

Return value

Parameter value as an ivec4 vector.

int getParameterArraySize ( int num ) const#

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

Arguments

Return value

Number of elements of the specified array parameter.

bool isParameterArray ( int num ) const#

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

true if the parameter is an array-type parameter; otherwise, false.

void getParameterArray ( int num, Vector<float> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector<float> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

void setParameterArray ( int num, const Vector<float> & values ) #

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

Arguments

void getParameterArray ( int num, Vector< Math::vec2> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector< Math::vec2> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

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

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

Arguments

void getParameterArray ( int num, Vector< Math::vec4> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector< Math::vec4> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

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

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

Arguments

void getParameterArray ( int num, Vector<int> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector<int> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

void setParameterArray ( int num, const Vector<int> & values ) #

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

Arguments

void getParameterArray ( int num, Vector< Math::ivec2> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector< Math::ivec2> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

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

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

Arguments

void getParameterArray ( int num, Vector< Math::ivec4> & OUT_values ) const#

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

Arguments

  • int num - Parameter number in the range from 0 to the total number of parameters.
  • Vector< Math::ivec4> & OUT_values - Buffer array to store parameter values.
    Notice
    This output buffer is to be filled by the Engine as a result of executing the method.

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

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

Arguments

int setParameterExpression ( int num, const char * expression ) #

Sets the expression used as a parameter value.

Arguments

Return value

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

const char * getParameterExpression ( int num ) const#

Returns an expression used as a parameter value.

Arguments

Return value

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

const char * getParameterName ( int num ) const#

Returns the name of a given parameter.

Arguments

Return value

Parameter name.

void setParameterFloat ( int num, float value ) #

Sets the value of a given float parameter by its number.

Arguments

void setParameterFloat ( const char * name, float value ) #

Sets the value of a given float parameter by its name.

Arguments

  • const char * name - Name of the target float parameter.
  • float value - Parameter value to be set.

float getParameterFloat ( int num ) const#

Returns the current value of a given float parameter.

Arguments

Return value

Current parameter value.

void setParameterFloat2 ( int num, const Math::vec2 & value ) #

Sets the value of a given float2 parameter by its number.

Arguments

void setParameterFloat2 ( const char * name, const Math::vec2 & value ) #

Sets the value of a given float2 parameter by its name.

Arguments

  • const char * name - Name of the target float2 parameter.
  • const Math::vec2 & value - Parameter value to be set.

Math::vec2 getParameterFloat2 ( int num ) const#

Returns the current value of a given float2 parameter.

Arguments

Return value

Current parameter value.

void setParameterFloat3 ( int num, const Math::vec3 & value ) #

Sets the value of a given float3 parameter by its number.

Arguments

void setParameterFloat3 ( const char * name, const Math::vec3 & value ) #

Sets the value of a given float3 parameter by its name.

Arguments

  • const char * name - Name of the target float3 parameter.
  • const Math::vec3 & value - Parameter value to be set.

Math::vec3 getParameterFloat3 ( int num ) const#

Returns the current value of a given float3 parameter.

Arguments

Return value

Current parameter value.

void setParameterFloat4 ( int num, const Math::vec4 & value ) #

Sets the value of a given float4 parameter by its number.

Arguments

void setParameterFloat4 ( const char * name, const Math::vec4 & value ) #

Sets the value of a given float4 parameter by its name.

Arguments

  • const char * name - Name of the target float4 parameter.
  • const Math::vec4 & value - Parameter value to be set.

Math::vec4 getParameterFloat4 ( int num ) const#

Returns the current value of a given float4 parameter.

Arguments

Return value

Current parameter value.

void setParameterInt ( int num, int value ) #

Sets the value of a given int parameter by its number.

Arguments

void setParameterInt ( const char * name, int value ) #

Sets the value of a given int parameter by its name.

Arguments

  • const char * name - Name of the target int parameter.
  • int value - Parameter value to be set.

int getParameterInt ( int num ) const#

Returns the current value of a given int parameter.

Arguments

Return value

Current parameter value.

void setParameterInt2 ( int num, const Math::ivec2 & value ) #

Sets the value of a given int2 parameter by its number.

Arguments

void setParameterInt2 ( const char * name, const Math::ivec2 & value ) #

Sets the value of a given int2 parameter by its name.

Arguments

  • const char * name - Name of the target int2 parameter.
  • const Math::ivec2 & value - Parameter value to be set.

Math::ivec2 getParameterInt2 ( int num ) const#

Returns the current value of a given int2 parameter.

Arguments

Return value

Current parameter value.

void setParameterInt3 ( int num, const Math::ivec3 & value ) #

Sets the value of a given int3 parameter by its number.

Arguments

void setParameterInt3 ( const char * name, const Math::ivec3 & value ) #

Sets the value of a given int3 parameter by its name.

Arguments

  • const char * name - Name of the target int3 parameter.
  • const Math::ivec3 & value - Parameter value to be set.

Math::ivec3 getParameterInt3 ( int num ) const#

Returns the current value of a given int3 parameter.

Arguments

Return value

Current parameter value.

void setParameterInt4 ( int num, const Math::ivec4 & value ) #

Sets the value of a given int4 parameter by its number.

Arguments

void setParameterInt4 ( const char * name, const Math::ivec4 & value ) #

Sets the value of a given int4 parameter by its name.

Arguments

  • const char * name - Name of the target int4 parameter.
  • const Math::ivec4 & value - Parameter value to be set.

Math::ivec4 getParameterInt4 ( int num ) const#

Returns the current value of a given int4 parameter.

Arguments

Return value

Current parameter value.

int getParameterType ( int num ) const#

Returns the type of a given parameter.

Arguments

Return value

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

Ptr<Material> getParent ( ) const#

Returns the parent material.

Return value

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

bool isParent ( const UGUID & guid ) const#

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

Arguments

  • const UGUID & guid - Material GUID.

Return value

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

bool isStateInternal ( int num ) const#

Returns a value indicating if a given state is internal.

Arguments

  • int num - State number.

Return value

true if the given state is internal; otherwise, false.

bool isStateOverridden ( int num ) const#

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 ( const char * name, int value ) #

Sets the value of the given state.

Arguments

  • const char * name - State name.
  • int value - State value.

int getState ( int num ) const#

Returns the state value.

Arguments

  • int num - State number.

Return value

State value.

int getState ( const char * name ) const#

Returns the value of the given state.

Arguments

  • const char * name - State name.

Return value

State value.

const char * getStateName ( int num ) const#

Returns the name of a given state.

Arguments

  • int num - State number.

Return value

State name.

const char * getStateSwitchItem ( int num, int item ) const#

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

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

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.

bool isTextureInternal ( int num ) const#

Returns a value indicating if a given texture is internal.

Arguments

  • int num - Texture number.

Return value

true if the given texture is internal; otherwise, false.

bool isTextureOverridden ( int num ) const#

Returns a value indicating if a given texture is overridden.

Arguments

  • int num - Texture number.

Return value

true if the given texture is overridden; otherwise, false.

bool isTextureLoaded ( int num ) const#

Returns a value indicating if a given texture is loaded.

Arguments

  • int num

Return value

true if the given texture is loaded; otherwise, false.

const char * getTextureName ( int num ) const#

Returns the name of a given texture.

Arguments

  • int num - Texture number.

Return value

Texture name.

int getTextureUnit ( int num ) const#

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

Arguments

  • int num - Texture number.

Return value

Texture unit number.

bool isTextureEditable ( int num ) const#

Returns a value indicating if the texture with the specified number is editable (can be modified).

Arguments

  • int num - Texture number.

Return value

true if the texture with the specified number is editable; otherwise, false (the texture is read-only).

int getTextureSource ( int num ) const#

Returns the source for the texture with the specified number.

Arguments

  • int num - Texture number.

Return value

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

Ptr<Texture> getTexture ( const char * name ) #

Returns the texture used in the material by its name.

Arguments

  • const char * name - Name of the desired texture (e.g., albedo, emission, etc.).

Return value

Texture used with the requested name.

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

Returns a value indicating the transparency type of the material.

Return value

One of the TRANSPARENT_* variables.

void setTwoSided ( bool sided ) #

Enables or disables the two sided option for the material.

Arguments

  • bool sided - true to make the material two-sided, false to make it one-sided.

bool isTwoSided ( ) const#

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

Return value

true if the material is two-sided; otherwise, false.

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

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.

bool isWater ( ) const#

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.

int findParameter ( const char * name ) const#

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 ( const char * name ) const#

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

Arguments

  • const char * name - State name.

Return value

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

int findTexture ( const char * name ) const#

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.

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

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 (C++)
// initialize object
MaterialPtr mat = object->getMaterial(0);
mat->setViewportMask(1); // viewport mask = 1
	
// save state
BlobPtr blob_state = Blob::create();
mat->saveState(blob_state, true);
	
// 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, true);  // restore viewport mask = 1

Arguments

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

Return value

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

bool restoreState ( const Ptr<Stream> & stream, bool 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 (C++)
// initialize object
MaterialPtr mat = object->getMaterial(0);
mat->setViewportMask(1); // viewport mask = 1
	
// save state
BlobPtr blob_state = Blob::create();
mat->saveState(blob_state, true);
	
// 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, true);  // restore viewport mask = 1

Arguments

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

Return value

true if the material settings are restored successfully; otherwise, false.

bool canRenderNode ( ) const#

Returns a value indicating if the material can be rendered for at least one type of nodes.

Return value

true if the material is rendered for at least one type of nodes; otherwise, false.

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, const char * path ) #

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

Arguments

  • int num - Texture number.
  • const char * path - A path to the texture or NULL to clear the path.

void setTexturePath ( const char * name, const char * path ) #

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

Arguments

  • const char * name - Texture name.
  • const char * path - A path to the texture or NULL to clear the path.

void resetTexture ( int num ) #

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

Arguments

  • int num - Texture number.

const char * getTexturePath ( int num ) const#

Returns a path to the texture with the specified number.

Arguments

  • int num - Texture number.

Return value

A path to the texture.

const char * getTexturePath ( const char * name ) const#

Returns a path to the texture with the specified name.

Arguments

Return value

A path to the texture.

bool isNodeTypeSupported ( Node::TYPE type ) const#

Returns a value indicating if the given type of nodes is supported by the material.

Arguments

Return value

true if the node type is supported; otherwise, false.

bool setParent ( const Ptr<Material> & material, bool save_all_values = 1 ) #

Sets the given material as the parent for this material and saves the material's properties values (if the corresponding flag is set).
Notice
The method isn't available for the manual and base materials.

Arguments

  • const Ptr<Material> & material - Material to be set as the parent for this material.
  • bool save_all_values - Flag indicating if the material's properties will be saved after reparenting.

Return value

true if the material's parent is changed; otherwise, false.

bool checkTextureConditions ( int num ) const#

Checks if conditions set for the given texture are met.

Arguments

  • int num - Texture number.

Return value

true if conditions are met; otherwise, false.

bool isInternal ( ) const#

Returns a value indicating if the current material is internal.

Return value

true if the material is internal; otherwise, false.

int loadXml ( const Ptr<Xml> & xml ) #

Loads material settings from the specified Xml source.

Arguments

  • const Ptr<Xml> & xml - An Xml node containing material settings.

Return value

true if the material settings are loaded successfully; otherwise, false.

bool loadUlon ( const Ptr<UlonNode> & ulon ) #

Loads material settings from the specified ULON source.

Arguments

  • const Ptr<UlonNode> & ulon - A ULON-node containing material settings.

Return value

true if the material settings are loaded successfully; otherwise, false.

bool hasOverrides ( ) const#

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

Return value

true if the material has at least one overridden property; otherwise, false.

bool canSave ( ) const#

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

true if the material can be saved; otherwise, false.

bool checkStateConditions ( int num ) const#

Checks if conditions set for the given state are met.

Arguments

  • int num - State number.

Return value

true if conditions are met; otherwise, false.

bool isManual ( ) const#

Returns a value indicating if the current material is manual.

Return value

true if the material is manual; otherwise, false.

bool isAutoSave ( ) const#

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

true if the material can be saved automatically; otherwise, false.

bool isLegacy ( ) const#

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

true if the material is a legacy one; otherwise, false.

bool isPreviewHidden ( ) const#

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

true if preview in the UnigineEditor is disabled for the material; otherwise, false.

bool checkParameterConditions ( int num ) const#

Checks if conditions set for the given parameter are met.

Arguments

Return value

true if conditions are met; othersiwe, false.

bool 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

true if the material is saved successfully; otherwise, false.

bool load ( const char * 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

  • const char * path - A path to the material file.

Return value

true if the material is loaded successfully; otherwise, false.

bool saveXml ( const Ptr<Xml> & xml ) const#

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

Arguments

  • const Ptr<Xml> & xml - An Xml node.

Return value

true if the material is saved successfully; otherwise, false.

bool isBase ( ) const#

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

Return value

true if the material is the base one; otherwise, false.

bool isNodeSupported ( const Ptr<Node> & node ) const#

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

Arguments

Return value

true if the given node is supported; otherwise, false.

Ptr<Material> getBaseMaterial ( ) const#

Returns the base material of the current material.

Return value

A base material.

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

Sets the given texture to the texture with the specified number.
Notice
This method only sets a pointer to the texture, so mind the scope of the source texture pointer.

Arguments

  • int num - Texture number.
  • const Ptr<Texture> & texture - Texture to be set.

void setTexture ( const char * name, const Ptr<Texture> & texture ) #

Sets the given texture to the texture with the specified name.
Notice
This method only sets a pointer to the texture, so mind the scope of the source texture pointer.

Arguments

  • const char * name - Texture name (one of the textures used by the material, e.g.: albedo).
  • const Ptr<Texture> & texture - Texture to be set.

Ptr<Texture> getTexture ( int num ) #

Returns a texture set for the current material.

Arguments

  • int num - Texture number.

Return value

A texture.

const char * getFilePath ( ) const#

Returns a path to the current material file.

Return value

Path to the material.

UGUID getFileGUID ( ) const#

Returns a GUID of the current material file.

Return value

GUID of the current material file.

void resetParameter ( int num ) #

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

Arguments

bool reload ( ) #

Reloads the material and all its children.

Return value

true if the material is reloaded successfully; otherwise, false.

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

Set a given image to a given texture.

Arguments

  • int num - Texture number.
  • const Ptr<Image> & image - An image to set.

Return value

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

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

Reads a given texture into a given image.

Arguments

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

Return value

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

Ptr<TextureRamp> getTextureRamp ( int num ) #

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

Arguments

  • int num - Texture number.

Return value

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

Ptr<TextureRamp> getTextureRampOverride ( int num ) #

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

Arguments

  • int num - Texture number.

Return value

New TextureRamp class instance overriding the data stored in the specified ramp texture (gradient).

UGUID getGUID ( ) const#

Returns the GUID of the material.

Return value

GUID of the material.

bool isFileEngine ( ) const#

Returns a value indicating if the material is a core Engine or UnigineEditor material (i.e. required for Engine/Editor operation). Such materials are stored in the core, editor and editor2 folders/packages.
Notice
It is not recommended to delete files of non-core materials (e.g., created by plugins or otherwise) at run-time, as this may affect materials caching and result in a crash.

Return value

true if the material is a core Engine or UnigineEditor material; otherwise, false.

void createShaders ( bool recursive = 0 ) #

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

Arguments

  • bool recursive - true to create shaders for child materials of the current material; otherwise, false.

void destroyTextures ( ) #

Deletes all textures used by the current material and its children.

bool isEmpty ( ) const#

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

Return value

true if an empty vertex shader is used; otherwise, false.

Render::PASS getRenderPass ( const char * pass_name ) const#

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

Arguments

  • const char * 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.

const char * getRenderPassName ( Render::PASS type ) const#

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

Arguments

Return value

Rendering pass name if it exists; otherwise nullptr.

bool runExpression ( const char * 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

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

Return value

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

bool renderScreen ( const char * pass_name ) #

Renders the screen-space material. The material must have a shader for the specified pass associated with it.

Arguments

  • const char * pass_name - Name of the rendering pass.

Return value

0 if the specified pass was not found; otherwise, 1.

void renderScreen ( Render::PASS pass ) #

Renders the screen-space material. The material must have a shader for the specified pass associated with it.

Arguments

bool renderCompute ( const char * 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

  • const char * 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

true if the specified pass was not found; otherwise, false.

void renderCompute ( Render::PASS pass, int group_threads_x = 1, int group_threads_y = 1, int group_threads_z = 1 ) #

Renders the material using a compute shader. The material must have a compute shader for the specified pass associated with it.

Arguments

  • Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
  • int group_threads_x - Local X work-group size of the compute shader.
  • int group_threads_y - Local Y work-group size of the compute shader.
  • int group_threads_z - Local Z work-group size of the compute shader.

int getNumUIItems ( ) const#

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.

Material::DATA_TYPE getUIItemDataType ( int item ) const#

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

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.

bool isUIItemHidden ( int item ) const#

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

Arguments

Return value

true is the specified UI item is hidden; otherwise, false.

const char * getUIItemTitle ( int item ) const#

Returns the title set for the specified UI item.

Arguments

Return value

Title set for the specified UI item.

const char * getUIItemTooltip ( int item ) const#

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.

Material::WIDGET getUIItemWidget ( int item ) const#

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

Arguments

Return value

UI item widget type.

int getUIItemParent ( int item ) const#

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

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

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.

bool isUIItemSliderMinExpand ( int item ) const#

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

Arguments

Return value

true if the maximum value can be increased; otherwise, false.

bool isUIItemSliderMaxExpand ( int item ) const#

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

Arguments

Return value

true if the minimum value can be decreased; otherwise, false.

float getUIItemSliderMinValue ( int item ) const#

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

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

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.

bool isUIItemGroupCollapsed ( int item ) const#

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

true if the specified group of UI items is currently collapsed in the UI; otherwise, false (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 ) const#

Returns the current value of the specified option.

Arguments

  • int num - Option number.

Return value

Current value of the specified option.

bool isOptionOverridden ( int num ) const#

Returns a value indicating if a given option is overridden.

Arguments

  • int num - Option number.

Return value

true if the given option is overridden; otherwise, false.

void resetOption ( int num ) #

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

Arguments

  • int num - Option number.

bool isParent ( const Ptr<Material> & parent ) const#

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

Arguments

  • const Ptr<Material> & parent - Material smart pointer.

Return value

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

Ptr<Material> clone ( ) const#

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.

Ptr<Material> clone ( const UGUID & guid ) const#

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

Arguments

  • const UGUID & guid - Cloned material GUID.

Return value

Cloned material.

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

Ptr<Material> inherit ( const UGUID & guid ) #

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

Arguments

  • const UGUID & guid - Inhereted material GUID.

Return value

Inhereted material.

const char * getNamespaceName ( ) const#

Returns the namespace where this material is defined.

Return value

Material namespace.

const char * getManualName ( ) const#

Returns the name of the manual material.

Return value

Manual material name.

const char * widgetToString ( Material::WIDGET widget ) #

Returns the name of the widget by its type.

Arguments

Return value

Name of the widget.

Material::WIDGET stringToWidget ( const char * str ) #

Returns the widget type by its name.

Arguments

  • const char * str - Name of the widget.

Return value

Widget type.

int getTextureSamplerFlags ( int num ) const#

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

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

Arguments

  • int num - Number of the texture.

Return value

Texture format flags.

bool createMaterialFile ( const char * path ) #

Creates a file and saves the internal material to it.

Arguments

  • const char * path - A path to save the material

Return value

The value indicating if the material was successful saved.

bool isReflection2D ( ) const#

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

Return value

true if the material has a 2d reflection texture; otherwise, false.

Ptr<Shader> getShaderAsync ( Render::PASS pass, int node ) #

Returns the rendering shader for the specified rendering pass and node type:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will initiate its asynchronous compilation in another thread and return the successfully compiled shader.
    Notice
    The function will keep returning nullptr until the shader is compiled.
Notice
To compile the shader asynchronously, enable the asynchronous compilation mode. Otherwise, the function will work the same as getShaderForce().

Arguments

Return value

Shader for the specified rendering pass and node type, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderAsync ( Render::PASS pass ) #

Returns the rendering shader for the specified rendering pass:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will initiate its asynchronous compilation in another thread and return the successfully compiled shader.
    Notice
    The function will keep returning nullptr until the shader is compiled.
Notice
To compile the shader asynchronously, enable the asynchronous compilation mode. Otherwise, the function will work the same as getShaderForce().

Arguments

Return value

Shader for the specified rendering pass, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderAsync ( const char * pass, int node ) #

Returns the rendering shader for the specified rendering pass and node type:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will initiate its asynchronous compilation in another thread and return the successfully compiled shader.
    Notice
    The function will keep returning nullptr until the shader is compiled.
Notice
To compile the shader asynchronously, enable the asynchronous compilation mode. Otherwise, the function will work the same as getShaderForce().

Arguments

  • const char * pass - Rendering pass name. One of the following:
    • wireframe
    • visualizer_solid
    • deferred
    • auxiliary
    • emission
    • reflection
    • refraction
    • transparent_blur
    • ambient
    • light_voxel_probe
    • light_environment_probe
    • light_omni
    • light_proj
    • light_world
    • shadow
    • depth_pre_pass
    • post
    • object_post
  • int node - Node type.

Return value

Shader for the specified rendering pass and node type, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderAsync ( const char * pass ) #

Returns the rendering shader for the specified rendering pass:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will initiate its asynchronous compilation in another thread and return the successfully compiled shader.
    Notice
    The function will keep returning nullptr until the shader is compiled.
Notice
To compile the shader asynchronously, enable the asynchronous compilation mode. Otherwise, the function will work the same as getShaderForce().

Arguments

  • const char * pass - Rendering pass name. One of the following:
    • wireframe
    • visualizer_solid
    • deferred
    • auxiliary
    • emission
    • reflection
    • refraction
    • transparent_blur
    • ambient
    • light_voxel_probe
    • light_environment_probe
    • light_omni
    • light_proj
    • light_world
    • shadow
    • depth_pre_pass
    • post
    • object_post

Return value

Shader for the specified rendering pass, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderForce ( Render::PASS pass, int node ) #

Returns the rendering shader for the specified rendering pass and node type:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will immediately compile and return it.
Notice
The function causes a spike because it compiles the shader in the current thread.

Arguments

Return value

Shader for the specified rendering pass and node type, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderForce ( Render::PASS pass ) #

Returns the rendering shader for the specified rendering pass:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will immediately compile and return it.
Notice
The function causes a spike because it compiles the shader in the current thread.

Arguments

Return value

Shader for the specified rendering pass, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderForce ( const char * pass, int node ) #

Returns the rendering shader for the specified rendering pass and node type:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will immediately compile and return it.
Notice
The function causes a spike because it compiles the shader in the current thread.

Arguments

  • const char * pass - Rendering pass name. One of the following:
    • wireframe
    • visualizer_solid
    • deferred
    • auxiliary
    • emission
    • reflection
    • refraction
    • transparent_blur
    • ambient
    • light_voxel_probe
    • light_environment_probe
    • light_omni
    • light_proj
    • light_world
    • shadow
    • depth_pre_pass
    • post
    • object_post
  • int node - Node type.

Return value

Shader for the specified rendering pass and node type, if compiled successfully. Otherwise, nullptr.

Ptr<Shader> getShaderForce ( const char * pass ) #

Returns the rendering shader for the specified rendering pass:
  • If the shader has been compiled previously, the function will return it immediately.
  • If the shader hasn't been compiled yet, the function will immediately compile and return it.
Notice
The function causes a spike because it compiles the shader in the current thread.

Arguments

  • const char * pass - Rendering pass name. One of the following:
    • wireframe
    • visualizer_solid
    • deferred
    • auxiliary
    • emission
    • reflection
    • refraction
    • transparent_blur
    • ambient
    • light_voxel_probe
    • light_environment_probe
    • light_omni
    • light_proj
    • light_world
    • shadow
    • depth_pre_pass
    • post
    • object_post

Return value

Shader for the specified rendering pass, if compiled successfully. Otherwise, nullptr.

void setTextureStreamingDensityMultiplier ( int num, float streaming_density_multiplier ) #

Sets a multiplier adjusting the distance at which the texture mipmaps are rendered.

Arguments

  • int num - Number of the texture.
  • float streaming_density_multiplier - Multiplier applied to the texture mipmaps rendering distance.

float getTextureStreamingDensityMultiplier ( int num ) const#

Returns the current adjusting the distance at which the texture mipmaps are rendered.

Arguments

  • int num - Number of the texture.

Return value

Multiplier applied to the texture mipmaps rendering distance.

bool needCreateShaderCache ( ) const#

Returns a value indicating if shader cache needs to be created for current material states and options.

Return value

true if shader cache is required for current material states and options; or false, if shader combination for current material states and options is already in cache.

bool needCreateShaderCache ( Render::PASS pass, Node::TYPE node_type ) const#

Returns a value indicating if shader combination needs to be created for the given rendering pass and node type.

Arguments

Return value

true if shader cache needs to be created for the given rendering pass and node type; or false, if shader combination for the given rendering pass and node type is already in cache.

bool shaderCacheExist ( Render::PASS pass, Node::TYPE node_type ) const#

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

Arguments

Return value

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

void createShaderForce ( Render::PASS pass, Node::TYPE node_type ) #

Compiles shader combination for the given rendering pass and node type. Shaders are compiled immediately, which may cause spikes, therefore this method is recommended only for critical cases, where createShaderAsync doesn't ensure a satisfying result.

Arguments

void createShaderAsync ( Render::PASS pass, Node::TYPE node_type ) #

Compiles shader combination for the given rendering pass and node type. Shaders are compiled asynchronously, which ensures smooth performance without spikes and is suitable for most cases. For the shaders that requre to be compiled immediately, use createShaderForce.

Arguments

void createRenderMaterials ( ) #

Creates render materials (internal materials required for rendering). For example, you can create all necessary render materials during initialization to avoid spikes that may occur later.

void createShaderCache ( bool recursive = false ) #

Compiles all shaders for the current material and its children (if any).

Arguments

  • bool recursive - true to compile shaders for child materials; otherwise, false.

void createShadersFromCache ( bool recursive = false ) #

Compiles all shaders available in shader cache for the current material and its children (if any).

Arguments

  • bool recursive - true to compile shaders for child materials; otherwise, false.
Last update: 2024-12-13
Build: ()