Unigine::Material Class
| Header: | #include <UnigineMaterial.h> |
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 concepts of a path and a name of the material should be distinguished:
- The path specifies where the material is stored on the disk. The path includes a material file name.
- The name specifies how the material will be displayed in Materials Editor (the materials hierarchy, the nodes surface editor). The name can also be used to reference material from 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 named material_ball_0 from the material_ball 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 AppWorldLogic.cpp file.
Source code (C++)
// AppWorldLogic.cpp
#include "AppWorldLogic.h"
#include <UnigineMaterials.h>
#include <UnigineObjects.h>
#include <UnigineWorld.h>
using namespace Unigine;
/* .. */
int AppWorldLogic::init()
{
// inherit a new material from the material_ball
MaterialPtr m = Materials::findMaterial("material_ball")->inherit("material_ball_0");
// getting the material_ball object and assigning the material_ball_0 material to it
ObjectMeshStaticPtr material_ball = checked_ptr_cast<ObjectMeshStatic>(World::getNodeByName("material_ball"));
material_ball->setMaterial("material_ball_0", "*");
// get the number of the albedo texture of the material_ball_0 material
int num = m->findTexture("albedo");
// check if our material is editable and perform modifications
if (m->isEditable()){
Log::message("Material (%s) is editable.\n", m->getName());
// change albedo texture of the material to core/textures/common/checker_d.dds
ImagePtr image = Image::create("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->getTextureFlags(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->setTextureFlags(num, Texture::FILTER_POINT);
// get the flags, check if point filtering is enabled and display the result in the console
int flagsSet = m->getTextureFlags(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 (material_ball_0) is editable.
Flags for albedo texture (1):2048000
FILTER_POINT disabled
Flags for albedo texture (1):4096
FILTER_POINT enabledChanging States and Parameters#
The second example illustrates how to inherit a material from the mesh_base, enable the planar reflection state and change two parameters affecting the look of dynamic reflections.
Add the following code to the AppWorldLogic.cpp file.
Source code (C++)
// AppWorldLogic.cpp
#include "AppWorldLogic.h"
#include <UnigineMaterials.h>
#include <UnigineWorld.h>
#include <UnigineRender.h>
using namespace Unigine;
/* .. */
int AppWorldLogic::init() {
// find the mesh_base material
MaterialPtr mesh_base = Materials::findMaterial("mesh_base");
// inherit a new material from it and assign the path to asset to be created on save() call:
// planar_reflector.mat in the data project folder
MaterialPtr reflector_material = mesh_base->inherit("planar_reflector", "planar_reflector.mat");
// enable planar reflections for the mirror material
reflector_material->setState("planar_reflection", 1);
// set metallness and roughness parameters to make the surface look like a mirror
// by the name of the parameter
reflector_material->setParameterFloat("metalness", 1.0f);
// or by its id, which is the same
reflector_material->setParameterFloat(reflector_material->findParameter("roughness"), 0.0f);
// save the material asset to the path specified earlier
reflector_material->save();
// assign the mesh_base material to the material ball by its name
ObjectMeshStaticPtr material_ball = checked_ptr_cast<ObjectMeshStatic>(World::getNodeByName("material_ball"));
material_ball->setMaterial("mesh_base","*");
// assign new mirror material to the ground object
ObjectMeshDynamicPtr ground = checked_ptr_cast<ObjectMeshDynamic>(World::getNodeByName("ground"));
ground->setMaterial(reflector_material, "*");
// enable planar reflections rendering using the corresponding method of the Render class
Render::setReflectionDynamic(true);
return 1;
}
/* .. */Material Class
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.int getBlendDestFunc ( ) const#
Returns the destination blending function.Return value
Destination blending function (one of the BLEND_* variables).void setBlendFunc ( int src, int dest ) #
Sets the source and destination blending functions.Arguments
- int src - Source blending function (one of the BLEND_* values described in the RenderState class).
- int dest - Destination blending function (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 ( 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 getCastShadow ( ) 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 ( 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 getCastWorldShadow ( ) 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 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 ( ) const#
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 getDepthTest ( ) 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 isFilter ( ) const#
Returns a value indicating if the material has filter texture.Return value
1 if the material has a filter texture; 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
1 if the material is hidden; otherwise, 0.void setImageTextureProcedural ( int num, const Ptr<Material> & procedural, int procedural_num ) #
Assigns the procedural texture of the given procedural material to the specified texture of the current material.Arguments
- int num - Number of the texture, to which the procedural texture will be assigned.
- const Ptr<Material> & procedural - Procedural material.
- int procedural_num - Procedural texture number.
void 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):
- Shadow mask of the light source
- Shadow mask of the surface of the object having this material assigned
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):
- Shadow mask of the light source
- Shadow mask of the surface of the object having this material assigned
Return value
Integer value, each bit of which is a mask.const char * getName ( ) const#
Returns the current material name.Return value
Material name.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 ( 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 getOverlap ( ) 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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the given parameter is overridden; otherwise, 0.bool isParameterInt ( int num ) const#
Returns a value indicating if the parameter with the specified number is an integer-type parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the parameter with the specified number is an float-type parameter; otherwise, false.int getParameterMinExpand ( int num ) const#
Returns a value indicating if the minimum value of the parameter with the specified number can be decreased.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the minimum value can be changed; otherwise, 0.int getParameterMaxExpand ( int num ) const#
Returns a value indicating if the maximum value of the parameter with the specified number can be increased.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the maximum value can be changed; otherwise, 0.float getParameterMinValue ( int num ) const#
Returns the minimum allowed value for the parameter with the specified number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Minimum parameter value.float getParameterMaxValue ( int num ) const#
Returns the maximum allowed value for the parameter with the specified number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Maximum parameter value.float getParameterFloat ( const char * name ) const#
Returns a value of a float parameter with the specified name.Arguments
- const char * name - Parameter name.
Return value
Float parameter value.Math::vec2 getParameterFloat2 ( const char * name ) const#
Returns a value of a FLOAT2 parameter with the specified name.Arguments
- const char * name - Parameter name.
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
- const char * name - Parameter name.
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
- const char * name - Parameter name.
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
- const char * name - Parameter name.
Return value
Integer parameter value.Math::ivec2 getParameterInt2 ( const char * name ) const#
Returns a value of a INT2 parameter with the specified name.Arguments
- const char * name - Parameter name.
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
- const char * name - Parameter name.
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
- const char * name - Parameter name.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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:- PARAMETER_ARRAY_FLOAT
- PARAMETER_ARRAY_FLOAT2
- PARAMETER_ARRAY_FLOAT4
- PARAMETER_ARRAY_INT
- PARAMETER_ARRAY_INT2
- PARAMETER_ARRAY_INT4
Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
true if the parameter is an array-type parameter; otherwise, false.void getParameterArray ( int num, Vector< float > & 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 > & values - Buffer array to store parameter values.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< float > & values - Array of values to be set.
void getParameterArray ( int num, Vector< Math::vec2 > & 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 > & values - Buffer array to store parameter values.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< Math::vec2 > & values - Array of values to be set.
void getParameterArray ( int num, Vector< Math::vec4 > & 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 > & values - Buffer array to store parameter values.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< Math::vec4 > & values - Array of values to be set.
void getParameterArray ( int num, Vector< int > & 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 > & values - Buffer array to store parameter values.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< int > & values - Array of values to be set.
void getParameterArray ( int num, Vector< Math::ivec2 > & 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 > & values - Buffer array to store parameter values.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< Math::ivec2 > & values - Array of values to be set.
void getParameterArray ( int num, Vector< Math::ivec4 > & 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 > & values - Buffer array to store parameter values.
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 num - Parameter number in the range from 0 to the total number of parameters.
- const Vector< Math::ivec4 > & values - Array of values to be set.
int setParameterExpression ( int num, const char * expression ) #
Sets the expression used as a parameter value.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- const char * expression - New expression.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Parameter expression, if it exists; otherwise, NULL (0).const char * getParameterGroup ( int num ) const#
Returns the group of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
The group of the material parameter.bool isParameterHidden ( int num ) const#
Returns a value indicating if a given parameter is hidden.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
1 if the parameter is hidden; otherwise, 0.const char * getParameterName ( int num ) const#
Returns the name of a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Parameter name.void setParameterFloat ( int num, float value ) #
Sets the value of a given float parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- float value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::vec2 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::vec3 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::vec4 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.void setParameterInt ( int num, int value ) #
Sets the value of a given int parameter by its number.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
- int value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::ivec2 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::ivec3 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
- const Math::ivec4 & value - Parameter value to be set.
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
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Current parameter value.const char * getParameterTitle ( int num ) const#
Returns the title of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Material parameter title.const char * getParameterTooltip ( int num ) const#
Returns the tooltip of the material parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
The tooltip text of the material parameter.int getParameterType ( int num ) const#
Returns the type of a given parameter.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
One of the PARAMETER_* pre-defined variables or -1, if an error has occurred.int getParameterWidgetIndex ( int num ) const#
Returns the index of the widget used to display the specified material parameter in UI.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Index of the widget used for the specified material parameter.const char * getParameterWidget ( int num ) const#
Returns the name of the widget used to display the specified material parameter in UI.Arguments
- int num - Parameter number in the range from 0 to the total number of parameters.
Return value
Widget name for the specified material parameter.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 char * name ) const#
Returns a value indicating if the material with the given name is a parent of the current material.Arguments
- const char * name - Material name.
Return value
1 if the material is the parent, otherwise - 0.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
1 if the material is the parent; otherwise, 0.bool isProcedural ( ) const#
Returns a value indicating if the material has procedural texture.Return value
1 if the material has a procedural texture; otherwise, 0.void setProceduralTexture ( int num, const Ptr<Texture> & texture ) #
Replaces a procedural texture having the specified number with the specified Texture. Procedural textures are calculated at run-time on GPU, using custom shaders. For example, this function allows to set the initial value for such texture.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- const Ptr<Texture> & texture - Texture to be set.
int setProceduralTextureImage ( int num, const Ptr<Image> & image ) #
Replaces a given procedural texture with an Image instance. Procedural textures are calculated at run-time on GPU, using custom shaders. For example, this function allows to set the initial value for such texture.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- const Ptr<Image> & image - An image to set.
Return value
1 if the texture is replaced successfully; otherwise, 0.int getProceduralTextureImage ( int num, const Ptr<Image> & image ) #
Reads the given procedural texture into an Image smart pointer. Procedural textures are calculated in run-time on GPU, using custom shaders. So, for example, this function enables to read the value of such texture at any moment.Arguments
- int num - Texture number. In materials, such texture should be declared with type="procedural" attribute.
- const Ptr<Image> & image - Image into which texture is read.
Return value
1 if the texture is read successfully; otherwise, 0.bool isReflection2D ( ) const#
Returns a value indicating if the material has a 2d reflection texture.Return value
1 if the material has a 2d reflection texture; otherwise, 0.bool checkShaderCache ( ) const#
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.bool checkShaderCache ( 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
- Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node::TYPE node_type - Node type.
Return value
1 if shader combination for the given rendering pass and node type is already in cache; otherwise, 0.bool compileShader ( Render::PASS pass, Node::TYPE node_type ) #
Compiles shader combination for the given rendering pass and node type.Arguments
- Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node::TYPE node_type - Node type.
Return value
1 if shader combination for the given rendering pass and node type was compiled successfully; otherwise, 0.Ptr<Shader> fetchShader ( Render::PASS pass ) #
Returns the rendering shader for the specified rendering pass.Arguments
- Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
Return value
Shader for the specified rendering pass.Ptr<Shader> fetchShader ( Render::PASS pass, Node::TYPE node_type ) #
Returns the rendering shader for the specified rendering pass and node type.Arguments
- Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
- Node::TYPE node_type - Node type.
Return value
Shader for the specified rendering pass and node type.Ptr<Shader> fetchShader ( const char * pass_name ) #
Returns the rendering shader for the specified rendering pass.Arguments
- const char * pass_name - 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.Ptr<Shader> fetchShader ( const char * pass_name, int node ) #
Returns the rendering shader for the specified rendering pass and node type.Arguments
- const char * pass_name - 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.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 * getStateGroup ( int num ) const#
Returns the group of the material state.Arguments
- int num - State number.
Return value
The group of the material state.bool isStateHidden ( int num ) const#
Returns a value indicating if a given state is hidden.Arguments
- int num - State number.
Return value
1 is the state is hidden; otherwise, 0.const char * getStateName ( int num ) const#
Returns the name of a given state.Arguments
- int num - State number.
Return value
State name.const char * getStateSwitchGroup ( int num ) const#
Returns the switch group name for a given state.Arguments
- int num - State number.
Return value
State switch group 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.const char * getStateTitle ( int num ) const#
Returns the title of the material state.Arguments
- int num - State number.
Return value
The title of the material state.const char * getStateTooltip ( int num ) const#
Returns the tooltip of the material state.Arguments
- int num - State number.
Return value
The tooltip text of the material state.int getStateWidgetIndex ( int num ) const#
Returns the index of the widget used to display the specified material state in UI.Arguments
- int num - State number in the range from 0 to the total number of states.
Return value
Index of the widget used for the specified material state.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.const char * getTextureGroup ( int num ) const#
Returns the group of the material texture.Arguments
- int num - State number.
Return value
The group of the material texture.bool isTextureHidden ( int num ) const#
Returns a value indicating if the texture is hidden.Arguments
- int num - Texture number.
Return value
true if the given texture is hidden; otherwise, false.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.const char * getTextureTitle ( int num ) const#
Returns the title of the material texture.Arguments
- int num - Texture number.
Return value
Title of the material texture.const char * getTextureTooltip ( int num ) const#
Returns the tooltip of the material texture.Arguments
- int num - Texture number.
Return value
Tooltip text of the material texture.int getTextureWidgetIndex ( int num ) const#
Returns the index of the widget used to display the specified material texture in UI.Arguments
- int num - Texture number in the range from 0 to the total number of textures.
Return value
Index of the widget used for the specified material texture.int getTextureType ( int num ) const#
Returns the type of a given texture.Arguments
- int num - Texture number.
Return value
One of the TEXTURE_* 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 blending function 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 ( 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 getTwoSided ( ) const#
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 ( ) 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.Ptr<Material> clone ( const char * name ) #
Clones the material and assigns the given name to it.Notice
A base material cannot be cloned.
Arguments
- const char * name - Cloned material name.
Return value
Cloned material.Ptr<Material> clone ( const char * name, const char * path, const UGUID & guid ) #
Clones the material and assigns the given name, GUID and path to the cloned material. The cloned material will be saved to the specified path on saveMaterials() call. This method may be used, for example, to create a material missed during project's migration.Notice
A base material cannot be cloned.
Arguments
- const char * name - CLoned material name.
- const char * path - Path to the cloned material.
- const UGUID & guid - Cloned material GUID.
Return value
The cloned material.Ptr<Material> clone ( const char * name, const char * path ) #
Clones the material and assigns the given name and path to the cloned material. The cloned material will be saved to the specified path on saveMaterials() call.Notice
A base material cannot be cloned.
Arguments
- const char * name - Cloned material name.
- const char * path - Path to save the cloned material
Return value
Cloned material.Ptr<Material> clone ( ) #
Clones the material. The cloned material will be empty: it won't have a name, path, textures and won't be displayed in the materials hierarchy.Return value
Cloned material.int fetchParameter ( const char * name, int fast_id ) #
Searches for a parameter by a given name among all parameters of the material.Arguments
- const char * name - Parameter name.
- int fast_id - Parameter number in users auxiliary parameters cache. The value must be in the range [0; 512]
Return value
Parameter number, if it is found; otherwise, -1.int fetchState ( const char * name, int fast_id ) #
Searches for a state by a given name among all states of the current material.Arguments
- const char * name - State name.
- int fast_id - State number in users auxiliary states cache. The value must be in the range [0; 512]
Return value
State number, if it is found; otherwise, -1.int fetchTexture ( const char * name, int fast_id ) #
Searches for a texture by a given name among all textures used by the current material.Arguments
- const char * name - Texture name.
- int fast_id - Texture number in users auxiliary textures cache. The value must be in the range [0; 512]
Return value
Texture number, if it is found; otherwise, -1.int findParameter ( const char * name ) const#
Searches for a parameter by a given name among all parameters of the current material.Arguments
- const char * name - Parameter name.
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
- const char * name - Texture name.
Return value
Texture number, if it is found; otherwise, -1.Ptr<Material> inherit ( const char * name ) #
Inherits a material from the current one and assigns the specified name to it.Arguments
- const char * name - Inherited material name.
Return value
Inherited material.Ptr<Material> inherit ( const char * name, const char * path ) #
Inherits a material from the current one and assigns the specified name and path to it. The inherited material will be saved to the specified path on saveMaterials() call.Arguments
- const char * name - Inherited material name.
- const char * path - Path to the inherited material.
Return value
Inherited material.Ptr<Material> inherit ( const char * name, const char * path, const UGUID & guid ) #
Inherits a material from the current one and assigns the specified name, GUID and path to it. The inherited material will be saved to the specified path on saveMaterials() call.Arguments
- const char * name - Inherited material name.
- const char * path - Path to the inherited material.
- const UGUID & guid - Inherited material GUID.
Return value
Inherited material.Ptr<Material> inherit ( ) #
Inherits the material. The inherited material will be empty: it won't have a name, path, texture and won't be displayed in materials hierarchy.Return value
Inherited material.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 = 1Arguments
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 = 1Arguments
- 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 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, 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 setName ( const char * name ) #
Sets a given name for the current material.Arguments
- const char * name - Material name.
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
- const char * name - Texture name.
Return value
A path to the texture.void setPath ( const char * path ) #
Sets a new path for the material.Arguments
- const char * path - New path to the material file.
void setFileGUID ( const UGUID & fileguid ) #
Sets a new GUID for the material file.Arguments
UGUID getFileGUID ( ) const#
Returns the current GUID of the material file.Return value
GUID of the material file.bool isNodeTypeSupported ( Node::TYPE type ) const#
Returns a value indicating if the given type of nodes is supported by the material.Arguments
- Node::TYPE type - Node type: one of the OBJECT_* or DECAL_* variables.
Return value
1 if the node type is supported; otherwise, 0.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).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
1 if the material's parent is changed; otherwise, 0.bool checkTextureConditions ( int num ) const#
Checks if conditions set for the given texture are met.Arguments
- int num - Texture number.
Return value
1 if conditions are met; otherwise, 0.bool isInternal ( ) const#
Returns a value indicating if the current material is internal.Return value
1 if the material is internal; otherwise, 0.int getTextureFlags ( int num ) const#
Returns the flags set on the given texture.Arguments
- int num - Texture number.
Return value
Texture flags bit mask.int loadXml ( const Ptr<Xml> & xml ) #
Loads material settings from the Xml.Arguments
Return value
1 if the material settings are loaded successfully; otherwise, 0.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 to the path specified via setPath() (automatic material saving is performed, for example, on world's saving). The function will return 0 in the following cases:- The canSave() function returns 0 for the material.
- The material is non-editable.
- The path isn't specified for the material.
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 isOptionsHidden ( ) const#
Returns a value indicating if Common material options (such as Transparency Preset, Material Mask, etc.) are not available for the material. This method is used for custom materials (e.g., landscape terrain brushes).Return value
true if Common material options are not available for the material; 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
- int num - Parameter name.
Return value
1 if conditions are met; othersiwe, 0.bool save ( ) #
Save the material to the current path used for this material.Return value
1 if the material is saved successfully; otherwise, 0.bool save ( const char * path ) #
Save the material to the specified path.Arguments
- const char * path - A path to save the material
Return value
1 if the material is saved successfully; otherwise, 0.bool load ( ) #
Loads the material from the file specified by the setPath() function. The function can be used to load materials created during application execution or stored outside the data directory.Return value
1 if the material is loaded successfully; otherwise, 0.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
1 if the material is loaded successfully; otherwise, 0.bool saveXml ( const Ptr<Xml> & xml ) const#
Saves the material into the given Xml.Arguments
Return value
1 if the material is saved successfully; otherwise, 0.bool isBase ( ) const#
Returns a value indicating if the material is the base one.Return value
1 if the material is the base one; otherwise, 0.bool isNodeSupported ( const Ptr<Node> & node ) const#
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.Ptr<Material> getBaseMaterial ( ) const#
Returns the base material of the current material.Return value
A base material.void setTextureFlags ( int num, int flags ) #
Sets the specified texture flags to the given texture.Arguments
- int num - Texture number.
- int flags - Texture flags bit mask.
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
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 ) const#
Returns a texture set for the current material.Arguments
- int num - Texture number.
Return value
A texture.const char * getPath ( ) const#
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 num - Parameter number in the range from 0 to the total number of parameters.
bool reload ( ) #
Reloads the material and all its children.Return value
1 if the material is reloaded successfully; otherwise, 0.int setTextureImage ( int num, const Ptr<Image> & image ) #
Set a given image to a given texture.Arguments
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
Return value
1 if the texture is read successfully; otherwise, 0.Ptr<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.Ptr<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 ( ) const#
Returns the GUID of the material.Return value
GUID of the material.bool isEngine ( ) const#
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
true if the material is engine-related; otherwise, false.void destroyShaders ( ) #
Deletes all shaders used for the current material and its children and clears shaders cache.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
- Render::PASS type - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
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 (XML)
<!--...-->
<expression name="expr_name" path="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
- Render::PASS pass - Rendering pass number in range [0;NUM_PASSES) (one of the PASS_* variables).
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.
const char * getOptionTitle ( int option ) const#
Returns the title of the specified material option.Arguments
- int option - Material option: one of the OPTION_* values.
Return value
Material option title.const char * getOptionTooltip ( int option ) const#
Returns the tooltip of the specified material option.Arguments
- int option - Material option: one of the OPTION_* values.
Return value
Tooltip text of the material's option.const char * getOptionGroup ( int option ) const#
Returns the group to which the specified material option belongs.Arguments
- int option - Material option: one of the OPTION_* values.
Return value
The group of the material option.int getOptionWidgetIndex ( int option ) const#
Returns the index of the widget used to display the specified material option in UI.Arguments
- int option - Material option: one of the OPTION_* values.
Return value
Index of the widget used for the specified material option.bool isOptionHidden ( int option ) const#
Returns a value indicating if the specified material option is hidden.Arguments
- int option - Material option: one of the OPTION_* values.
Return value
1 if the option is hidden; otherwise, 0.Last update:
2021-04-17
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)