Material

class nvisii.material(*args, **kwargs)

The “Material” component describes the surface properties of an entity. This material follows a physically based workflow, more specifically the Blender principled shader, and is very similar to the Disney material model.

property thisown

The membership flag

static create(*args, **kwargs)

Constructs a material with the given name.

Return type

Material

Returns

a reference to a material component

Parameters

• name (string) – A unique name for this material.

• base_color (vec3, optional) – The diffuse or metal surface color.

• roughness (float, optional) – Microfacet roughness of the surface for diffuse and specular reflection.

• metallic (float, optional) – Blends between a non-metallic and metallic material model.

• specular (float, optional) – The amount of dielectric specular reflection.

• specular_tint (float, optional) – Tints the facing specular reflection using the base color, while glancing reflection remains white.

• transmission (float, optional) – Controls how much the surface looks like glass. Note, metallic takes precedence.

• transmission_roughness (float, optional) – The roughness of the interior surface used for transmitted light.

• ior (float, optional) – Index of refraction used for transmission events.

• alpha (float, optional) – The transparency of the surface, independent of transmission.

• subsurface_radius (vec3, optional) – Average distance that light scatters below the surface

• subsurface_color (vec3, optional) – The subsurface scattering base color.

• subsurface (float, optional) – Mix between diffuse and subsurface scattering.

• anisotropic (float, optional) – The amount of anisotropy for specular reflection.

• anisotropic_rotation (float, optional) – The angle of anisotropy.

• sheen (float, optional) – Amount of soft velvet like reflection near edges, for simulating materials such as cloth.

• sheen_tint (float, optional) – Mix between white and using base color for sheen reflection.

• clearcoat (float, optional) – Extra white specular layer on top of others.

• clearcoat_roughness (float, optional) – Microfacet surface roughness of clearcoat specular.

static get(name)

Gets a material by name

Return type

Material

Returns

a material who’s primary name key matches name

Parameters

name (string) – A unique name used to lookup this material.

static get_count()

Return type

int

Returns

the number of allocated materials

get_name()

Return type

string

Returns

the name of this component

static get_name_to_id_map()

Return type

std::map< std::string,uint32_t,std::less< std::string >,std::allocator< std::pair< std::string const,uint32_t > > >

Returns

A map whose key is a material name and whose value is the ID for that material

static remove(name)

Parameters

name (string) – The name of the material to remove

static initialize_factory(max_components)

Allocates the tables used to store all material components

is_initialized()

Return type

boolean

Returns

True the current material is a valid, initialized material, and False if the material was cleared or removed.

static clear_all()

Clears any existing material components.

static are_any_dirty()

Return type

boolean

Returns

True if any the material has been modified since the previous frame, and False otherwise

to_string()

Returns a json string representation of the current component

set_base_color(color)

The diffuse or metal surface color. Ignored if a base color texture is set.

Parameters

color (vec3) – a red, green, blue color intensity vector, usually between 0 and 1

set_base_color_texture(texture)

The diffuse or metal surface color. Texture is expected to be RGB. Overrides any existing constant base color.

Parameters

texture (Texture) – An RGB texture component whose values range between 0 and 1. Alpha channel is ignored.

clear_base_color_texture()

Disconnects the base color texture, reverting back to any existing constant base color

get_base_color()

The diffuse or metal surface color. Ignored if a base color texture is set.

Return type

vec3

Returns

the color intensity vector

set_subsurface(subsurface)

Mix between diffuse and subsurface scattering.

Parameters

subsurface (float) – Rather than being a simple mix between Diffuse and Subsurface Scattering, this value controls a multiplier for the Subsurface Radius.

set_subsurface_texture(texture, channel=0)

Mix between diffuse and subsurface scattering. Overrides any existing constant subsurface

Parameters

• texture (Texture) – A grayscale texture component containing subsurface radius multipliers.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_subsurface_texture()

Disconnects the subsurface texture, reverting back to any existing constant subsurface

get_subsurface()

Mix between diffuse and subsurface scattering.

Return type

float

Returns

the current subsurface radius multiplier.

set_subsurface_radius(subsurfaceRadius)

Average distance that light scatters below the surface. Higher radius gives a softer appearance, as light bleeds into shadows and through the object. The scattering distance is specified separately for the RGB channels, to render materials such as skin where red light scatters deeper.

Parameters

subsurface_radius – control the subsurface radius. The X, Y and Z values of this vector are mapped to the R, G and B radius values, respectively.

set_subsurface_radius_texture(texture)

Average distance that light scatters below the surface. Higher radius gives a softer appearance, as light bleeds into shadows and through the object. Overrides any existing constant subsurface radius

Parameters

texture (Texture) – An RGB texture component controlling the subsurface radius in x, y, and z. Alpha channel is ignored.

clear_subsurface_radius_texture()

Disconnects the subsurface radius texture, reverting back to any existing constant subsurface radius

get_subsurface_radius()

Average distance that light scatters below the surface. Higher radius gives a softer appearance, as light bleeds into shadows and through the object.

Return type

vec3

Returns

The subsurface scattering distance is specified separately for the RGB channels.

set_subsurface_color(color)

The subsurface scattering base color.

Parameters

color (vec3) – the color intensity vector, usually between 0 and 1

set_subsurface_color_texture(texture)

The subsurface scattering base color. Overrides any existing constant subsurface color

Parameters

texture (Texture) – An RGB texture whose values range between 0 and 1. Alpha channel is ignored.

clear_subsurface_color_texture()

Disconnects the subsurface color texture, reverting back to any existing constant subsurface color

set_metallic(metallic)

Blends between a non-metallic and metallic material model.

Parameters

metallic (float) – A value of 1.0 gives a fully specular reflection tinted with the base color, without diffuse reflection or transmission. At 0.0 the material consists of a diffuse or transmissive base layer, with a specular reflection layer on top.

set_metallic_texture(texture, channel=0)

Blends between a non-metallic and metallic material model. Overrides any existing constant metallic

Parameters

• texture (Texture) – A grayscale texture, where texel values of 1 give a fully specular reflection tinted with the base color, without diffuse reflection or transmission. When texel values equal 0.0 the material consists of a diffuse or transmissive base layer, with a specular reflection layer on top.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_metallic_texture()

Disconnects the metallic texture, reverting back to any existing constant metallic

get_metallic()

Blends between a non-metallic and metallic material model.

Return type

float

Returns

the current metallic value.

set_specular(specular)

The amount of dielectric specular reflection.

Parameters

specular (float) – Specifies facing (along normal) reflectivity in the most common 0 - 8% range. Since materials with reflectivity above 8% do exist, the field allows values above 1.

set_specular_texture(texture, channel=0)

The amount of dielectric specular reflection. Overrides any existing constant specular

Parameters

• texture (Texture) – A grayscale texture containing dielectric specular reflection values.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_specular_texture()

Disconnects the specular texture, reverting back to any existing constant specular

get_specular()

The amount of dielectric specular reflection.

Return type

float

Returns

the current dielectric specular reflection value.

set_specular_tint(specularTint)

Tints the facing specular reflection using the base color, while glancing reflection remains white. Normal dielectrics have colorless reflection, so this parameter is not technically physically correct and is provided for faking the appearance of materials with complex surface structure.

Parameters

specular_tint – a value between 0 and 1, enabling/disabling specular tint

set_specular_tint_texture(texture, channel=0)

Tints the facing specular reflection using the base color, while glancing reflection remains white. Overrides any existing constant specular tint

Parameters

• texture (Texture) – A grayscale texture containing specular tint values, between 0 and 1.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_specular_tint_texture()

Disconnects the specular tint texture, reverting back to any existing constant specular tint

get_specular_tint()

Tints the facing specular reflection using the base color, while glancing reflection remains white.

Return type

float

Returns

the current specular tint value, between 0 and 1

set_roughness(roughness)

Microfacet roughness of the surface for diffuse and specular reflection.

Parameters

roughness (float) – Specifies the surface microfacet roughness value, between 0 and 1

set_roughness_texture(texture, channel=0)

Microfacet roughness of the surface for diffuse and specular reflection. Overrides any existing constant roughness

Parameters

• texture (Texture) – A grayscale texture containing microfacet roughness values, between 0 and 1.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_roughness_texture()

Disconnects the roughness texture, reverting back to any existing constant roughness

get_roughness()

Microfacet roughness of the surface for diffuse and specular reflection.

Return type

float

Returns

the current surface microfacet roughness value, between 0 and 1

set_alpha(a)

The transparency of the surface, independent of transmission.

Parameters

a (float) – Controls the transparency of the surface, with 1.0 being fully opaque.

set_alpha_texture(texture, channel=0)

The transparency of the surface, independent of transmission. Overrides any existing constant alpha

Parameters

• texture (Texture) – A grayscale texture containing surface transparency values, with 1.0 being fully opaque and 0.0 being fully transparent.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_alpha_texture()

Disconnects the alpha texture, reverting back to any existing constant alpha

get_alpha()

The transparency of the surface, independent of transmission.

Return type

float

Returns

the current surface transparency, with 1.0 being fully opaque and 0.0 being fully transparent.

set_anisotropic(anisotropic)

The amount of anisotropy for specular reflection.

Parameters

anistropic – The amount of anisotropy for specular reflection. Higher values give elongated highlights along the tangent direction; negative values give highlights shaped perpendicular to the tangent direction.

set_anisotropic_texture(texture, channel=0)

The amount of anisotropy for specular reflection. Overrides any existing constant anisotropy

Parameters

• texture (Texture) – A grayscale texture containing amounts of anisotropy for specular reflection. G, B, and A channels are ignored.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_anisotropic_texture()

Disconnects the anisotropic texture, reverting back to any existing constant anisotropy

get_anisotropic()

The amount of anisotropy for specular reflection.

Return type

float

Returns

The current amount of anisotropy for specular reflection.

set_anisotropic_rotation(anisotropicRotation)

The angle of anisotropy. :param anisotropic_rotation: Rotates the angle of anisotropy, with 1.0 going full circle.

set_anisotropic_rotation_texture(texture, channel=0)

The angle of anisotropy. Overrides any existing constant anisotropic rotation

Parameters

• texture (Texture) – A grayscale texture containing the angle of anisotropy, between 0 and 1.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_anisotropic_rotation_texture()

Disconnects the anisotropic rotation texture, reverting back to any existing constant anisotropic rotation

get_anisotropic_rotation()

The angle of anisotropy.

Return type

float

Returns

the current the angle of anisotropy, between 0 and 1.

set_sheen(sheen)

Amount of soft velvet like reflection near edges, for simulating materials such as cloth.

Parameters

sheen (float) – controls the amount of sheen, between 0 and 1

set_sheen_texture(texture, channel=0)

Amount of soft velvet like reflection near edges, for simulating materials such as cloth. Overrides any existing constant sheen

Parameters

• texture (Texture) – A grayscale texture containing amounts of sheen, between 0 and 1.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_sheen_texture()

Disconnects the sheen texture, reverting back to any existing constant sheen

get_sheen()

Amount of soft velvet like reflection near edges, for simulating materials such as cloth.

Return type

float

Returns

the current sheen amount, between 0 and 1

set_sheen_tint(sheenTint)

Mix between white and using base color for sheen reflection.

Parameters

sheen_tint – controls the mix between white and base color for sheen reflection.

set_sheen_tint_texture(texture, channel=0)

Mix between white and using base color for sheen reflection. Overrides any existing constant sheen tint

Parameters

• texture (Texture) – A grayscale texture containing values used to mix between white and base color for sheen reflection.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_sheen_tint_texture()

Disconnects the sheen tint texture, reverting back to any existing constant sheen tint

get_sheen_tint()

Mix between white and using base color for sheen reflection.

Return type

float

Returns

the current value used to mix between white and base color for sheen reflection.

set_clearcoat(clearcoat)

Extra white specular layer on top of others. This is useful for materials like car paint and the like.

Parameters

clearcoat (float) – controls the influence of clear coat, between 0 and 1

set_clearcoat_texture(texture, channel=0)

Extra white specular layer on top of others. Overrides any existing constant clearcoat

Parameters

• texture (Texture) – A grayscale texture controlling the influence of clear coat, between 0 and 1.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_clearcoat_texture()

Disconnects the clearcoat texture, reverting back to any existing constant clearcoat

get_clearcoat()

Extra white specular layer on top of others. This is useful for materials like car paint and the like.

Return type

float

Returns

the current clear coat influence

set_clearcoat_roughness(clearcoatRoughness)

Microfacet surface roughness of clearcoat specular.

Parameters

clearcoat_roughness – the roughness of the microfacet distribution influencing the clearcoat, between 0 and 1

set_clearcoat_roughness_texture(texture, channel=0)

Microfacet surface roughness of clearcoat specular. Overrides any existing constant clearcoat roughness

Parameters

• texture (Texture) – the roughness of the microfacet distribution influencing the clearcoat, between 0 and 1

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_clearcoat_roughness_texture()

Disconnects the clearcoat roughness texture, reverting back to any existing constant clearcoat roughness

get_clearcoat_roughness()

Microfacet surface roughness of clearcoat specular.

Return type

float

Returns

the current clearcoat microfacet roughness value, between 0 and 1

set_ior(ior)

Index of refraction used for transmission events.

Parameters

ior (float) – the index of refraction. A value of 1 results in no refraction. For reference, the IOR of water is roughly 1.33, and for glass is roughly 1.57.

set_ior_texture(texture, channel=0)

Index of refraction used for transmission events. Overrides any existing constant ior.

Parameters

• texture (Texture) – the index of refraction. A value of 1 results in no refraction. For reference, the IOR of water is roughly 1.33, and for glass is roughly 1.57.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_ior_texture()

Disconnects the ior texture, reverting back to any existing constant ior

get_ior()

Index of refraction used for transmission events.

Return type

float

Returns

the current index of refraction.

set_transmission(transmission)

Controls how much the surface looks like glass. Note, metallic takes precedence.

Parameters

transmission (float) – Mixes between a fully opaque surface at zero to fully glass like transmissions at one.

set_transmission_texture(texture, channel=0)

Controls how much the surface looks like glass. Note, metallic takes precedence. Overrides any existing constant transmission.

Parameters

• texture (Texture) – A grayscale texture containing the specular transmission of the surface.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_transmission_texture()

Disconnects the transmission texture, reverting back to any existing constant transmission

get_transmission()

Controls how much the surface looks like glass. Note, metallic takes precedence.

Return type

float

Returns

the current specular transmission of the surface.

set_transmission_roughness(transmissionRoughness)

The roughness of the interior surface used for transmitted light.

Parameters

transmission_roughness – Controls the roughness value used for transmitted light.

set_transmission_roughness_texture(texture, channel=0)

The roughness of the interior surface used for transmitted light. Overrides any existing constant transmission roughness

Parameters

• texture (Texture) – Controls the roughness value used for transmitted light.

• channel (int, optional) – A value between 0 and 3 indicating the channel to use for this parameter.

clear_transmission_roughness_texture()

Disconnects the TransmissionRoughness texture, reverting back to any existing constant TransmissionRoughness

get_transmission_roughness()

The roughness of the interior surface used for transmitted light.

Return type

float

Returns

the current roughness value used for transmitted light.

set_normal_map_texture(texture)

A normal map texture used to displace surface normals. Note that we expect R=X+, G=Y+, and B=Z+ (Matches Blender / OpenGL). Textures imported as “.dds” are an exception, and use R=X+, G=Y-, and B=Z+ (Matches DirectX style)

Parameters

texture (Texture) – A texture containing a surface normal displacement between 0 and 1. A channel is ignored.

clear_normal_map_texture()

Disconnects the normal map texture