Most visited

Recently visited

Material

public class Material
extends Object

java.lang.Object
   ↳ com.viro.core.Material


Materials are the set of shading attributes that define the appearance of a geometry's surfaces when rendered. Each Geometry in a scene can be assigned one or more materials. All UI elements, and most basic 3D models, utilize only one material. Complex 3D objects, represented by Object3D, typically have multiple materials, one for each defined mesh surface in the 3D object.

Whereas a Geometry defines the structure of a 3D Object, Material defines the appearance of each surface. The final color of each pixel on a surface is determined by both the Material attributes and the parameters of each Light in the Scene.

For an extended discussion on Material properties, refer to the Lighting and Materials Guide.

Summary

Nested classes

enum Material.BlendMode

BlendMode determines how a pixel's color, as it is being rendered, interacts with the color of the pixel already in the framebuffer. 

enum Material.CullMode

CullMode determines whether we render front faces, back faces, or both. 

enum Material.LightingModel

LightingModel defines a formula for combining a material’s diffuse, specular, and other properties with the Lights in the Scene, and the point of view, to create the color of each rendered pixel. 

class Material.MaterialBuilder

Builder for creating Material objects. 

enum Material.ShadowMode

ShadowMode defines in what form a Material receives shadows. 

enum Material.TransparencyMode

TransparencyMode determines how the opacity of pixels is computed. 

Public constructors

Material()

Construct a new Material.

Public methods

static Material.MaterialBuilder builder()

Builder for creating Material objects.

void dispose()

Release native resources associated with this Material.

Texture getAmbientOcclusionMap()

Get the ambient occlusion Texture used by this Material.

Material.BlendMode getBlendMode()

Get the Material.BlendMode used by this Material.

float getBloomThreshold()

Get the bloom threshold, the brightness at which this Material will begin to bloom.

int getChromaKeyFilteringColor()

Returns the chroma key filtering color.

Material.CullMode getCullMode()

Get the Material.CullMode used by this Material.

int getDiffuseColor()

Get the diffuse Color used by this Material, which defines its base color.

Texture getDiffuseTexture()

Get the diffuse Texture used by this Material, which defines its base color.

Material.LightingModel getLightingModel()

Get the Material.LightingModel used by this Material.

float getMetalness()

Set a uniform metalness value to use for this Material.

Texture getMetalnessMap()

Get the metalness Texture used by this Material.

String getName()

Get the (non-unique) name that can be optionally used to represent this Material.

Texture getNormalMap()

Get the normap map Texture used by this Material.

boolean getReadsFromDepthBuffer()

Return true if this Material reads from the depth buffer.

float getRoughness()

Set a uniform roughness value to use for this Material.

Texture getRoughnessMap()

Set the roughness Texture to use for this Material.

Material.ShadowMode getShadowMode()

Get the Material.ShadowMode used by this Material, which defines how surfaces using this material render shadows.

float getShininess()

Get the shininess value, which defines the sharpness of specular highlights.

Texture getSpecularTexture()

Get the specular Texture used by this Material.

Material.TransparencyMode getTransparencyMode()

Get the Material.TransparencyMode to use for Material.

boolean getWritesToDepthBuffer()

Return true if this Material writes to the depth buffer.

boolean isChromaKeyFilteringEnabled()

Returns true if chroma key filtering is enabled.

void setAmbientOcclusionMap(Texture ambientOcclusionMap)

Set the ambient occlusion Texture to use for this Material.

void setBlendMode(Material.BlendMode blendMode)

Set the Material.BlendMode to use for this Material.

void setBloomThreshold(float bloomThreshold)

Set the brightness value at which this Material will begin to bloom.

void setChromaKeyFilteringColor(int color)

Set the color to remove from all surfaces rendering with this material, via chroma key filtering.

void setChromaKeyFilteringEnabled(boolean enabled)

Enable chroma key filtering for this material.

void setCullMode(Material.CullMode cullMode)

Set the Material.CullMode to use for this Material.

void setDiffuseColor(int color)

Set the diffuse Color to use for this Material.

void setDiffuseTexture(Texture texture)

Set the diffuse Texture to use for this Material.

void setLightingModel(Material.LightingModel lightingModel)

Set the Material.LightingModel to use for this Material.

void setMetalness(float metalness)

Set a uniform metalness value to use for this Material.

void setMetalnessMap(Texture metalnessMap)

Set the metalness Texture to use for this Material.

void setName(String name)

Sets a (non-unique) name to represent this Material object.

void setNormalMap(Texture normalMap)

Set the normal map Texture to use for this Material.

void setReadsFromDepthBuffer(boolean readsFromDepthBuffer)

Set whether this Material reads from the depth buffer.

void setRoughness(float roughness)

Set a uniform roughness value to use for this Material.

void setRoughnessMap(Texture roughnessMap)

Set the roughness Texture to use for this Material.

void setShadowMode(Material.ShadowMode shadowMode)

Set the Material.ShadowMode for this Material, which defines how surfaces using this Material render shadows.

void setShininess(float shininess)

Set the sharpness of specular highlights.

void setSpecularTexture(Texture texture)

Set the specular Texture to use with this Material.

void setTransparencyMode(Material.TransparencyMode transparencyMode)

Set the Material.TransparencyMode to use for this Material.

void setWritesToDepthBuffer(boolean writesToDepthBuffer)

Set whether this Material writes to the depth buffer.

Public constructors

Material

Material ()

Construct a new Material. The material defaults to a flat white color with a constant lighting model.

Public methods

builder

Material.MaterialBuilder builder ()

Builder for creating Material objects.

Returns
Material.MaterialBuilder

dispose

void dispose ()

Release native resources associated with this Material.

getAmbientOcclusionMap

Texture getAmbientOcclusionMap ()

Get the ambient occlusion Texture used by this Material. The ambient occlusion map approximates how exposed the surface is to ambient lighting, at each texel.

This property is only used under PHYSICALLY_BASED lighting.

Returns
Texture ambientOcclusionMap The ambient occlusion map used by this Material. Null if no ambient occlusion map is installed.

getBlendMode

Material.BlendMode getBlendMode ()

Get the Material.BlendMode used by this Material. See Material.BlendMode for more details.

Returns
Material.BlendMode The BlendMode used by this Material.

getBloomThreshold

float getBloomThreshold ()

Get the bloom threshold, the brightness at which this Material will begin to bloom. See setBloomThreshold(float) for more details.

Returns
float The bloom threshold.

getChromaKeyFilteringColor

int getChromaKeyFilteringColor ()

Returns the chroma key filtering color. Hues within an epsilon range about this color are removed (made transparent) when chroma key filtering is enabled.

Returns
int The chroma key filtering color.

getCullMode

Material.CullMode getCullMode ()

Get the Material.CullMode used by this Material. See Material.CullMode for more details.

Returns
Material.CullMode The CullMode used by this Material.

getDiffuseColor

int getDiffuseColor ()

Get the diffuse Color used by this Material, which defines its base color. See setDiffuseColor(int) for more details.

Returns
int The diffuse

getDiffuseTexture

Texture getDiffuseTexture ()

Get the diffuse Texture used by this Material, which defines its base color. See setDiffuseTexture(Texture) for more details.

Returns
Texture The diffuse Texture used by this Material.

getLightingModel

Material.LightingModel getLightingModel ()

Get the Material.LightingModel used by this Material. See Material.LightingModel for more details.

Returns
Material.LightingModel The LightingModel used by this Material.

getMetalness

float getMetalness ()

Set a uniform metalness value to use for this Material. Metalness defines how "metallic" the surface is at each pixel, which influences the degree to which light reflects off the surface, the sharpness of the reflections, and more.

This property is only used under PHYSICALLY_BASED lighting. If a metalness map is set (by setMetalnessMap(Texture), then this value is ignored, and the values derived from the metalness map are used instead.

Returns
float metalness The uniform metalness value used by this Material.

getMetalnessMap

Texture getMetalnessMap ()

Get the metalness Texture used by this Material. The metalness map defines how "metallic" the surface is at each texel, which influences the degree to which light reflects off the surface, the sharpness of the reflections, and more.

This property is only used under PHYSICALLY_BASED lighting.

Returns
Texture The metalness map used by this Material. Null if no metalness map is installed.

getName

String getName ()

Get the (non-unique) name that can be optionally used to represent this Material. Material names are either set by setName(String), or they are automatically set when loading OBJ or FBX files. Null if no name is set.

Returns
String name The string value representing the name used by this Material.

getNormalMap

Texture getNormalMap ()

Get the normap map Texture used by this Material. The normal map defines a normal vector for each point on the surface.

Returns
Texture The normal map Texture used by this material.

getReadsFromDepthBuffer

boolean getReadsFromDepthBuffer ()

Return true if this Material reads from the depth buffer. See setReadsFromDepthBuffer(boolean) for discussion.

Returns
boolean True if reading is enabled.

getRoughness

float getRoughness ()

Set a uniform roughness value to use for this Material. Roughness defines the roughness of the surface's microfacets, at each pixel. The rougher a surface is (roughness approaching 1.0), the more light sill scatter along completely different directions, resulting in larger and more muted specular reflections. Smoother surfaces (roughness approaching 0.0), meanwhile, exhibit a sharper specular reflection as light rays are more likely to reflect in a uniform direction.

This property is only used under PHYSICALLY_BASED lighting. If a roughness map is set (by setRoughnessMap(Texture), then this value is ignored, and the values derived from the roughness map are used instead.

Returns
float The uniform roughness value used by this Material.

getRoughnessMap

Texture getRoughnessMap ()

Set the roughness Texture to use for this Material. The roughness map defines the roughness of the surface's microfacets at each texel. The rougher a surface is (roughness approaching 1.0), the more light sill scatter along completely different directions, resulting in larger and more muted specular reflections. Smoother surfaces (roughness approaching 0.0), meanwhile, exhibit a sharper specular reflection as light rays are more likely to reflect in a uniform direction.

This property is only used under PHYSICALLY_BASED lighting.

Returns
Texture The roughness map used by this Material. Null if no roughness map is used.

getShadowMode

Material.ShadowMode getShadowMode ()

Get the Material.ShadowMode used by this Material, which defines how surfaces using this material render shadows. See Material.ShadowMode for details.

Returns
Material.ShadowMode The Material.ShadowMode used by this Material.

getShininess

float getShininess ()

Get the shininess value, which defines the sharpness of specular highlights.

Returns
float The shininess value.

getSpecularTexture

Texture getSpecularTexture ()

Get the specular Texture used by this Material. The specular Texture defines the amount of light that is reflected by the Material toward the user. See setSpecularTexture(Texture) for more details.

Returns
Texture The specular Texture used by this Material.

getTransparencyMode

Material.TransparencyMode getTransparencyMode ()

Get the Material.TransparencyMode to use for Material. See Material.TransparencyMode for more details.

Returns
Material.TransparencyMode The TransparencyMode used by this Material.

getWritesToDepthBuffer

boolean getWritesToDepthBuffer ()

Return true if this Material writes to the depth buffer. See setWritesToDepthBuffer(boolean) for discussion.

Returns
boolean True if writing is enabled.

isChromaKeyFilteringEnabled

boolean isChromaKeyFilteringEnabled ()

Returns true if chroma key filtering is enabled.

Returns
boolean True if chroma key filtering is enabled.

setAmbientOcclusionMap

void setAmbientOcclusionMap (Texture ambientOcclusionMap)

Set the ambient occlusion Texture to use for this Material. The ambient occlusion map approximates how exposed the surface is to ambient lighting, at each texel. This has no effect on direct lights (it does not result in clear shadows) but it darkens enclosed and sheltered areas. These textures are typically authored using modeling tools along with roughness and metalness.

This property is only used under PHYSICALLY_BASED lighting.

Parameters
ambientOcclusionMap Texture: The ambient occlusion map to use for this Material.

setBlendMode

void setBlendMode (Material.BlendMode blendMode)

Set the Material.BlendMode to use for this Material. BlendMode determines how a pixel's color, as it is being rendered, interacts with the color of the pixel already in the framebuffer.

Parameters
blendMode Material.BlendMode: The BlendMode to use for this Material.

setBloomThreshold

void setBloomThreshold (float bloomThreshold)

Set the brightness value at which this Material will begin to bloom.

Bloom is an effect that makes surfaces appear to glow by applying a Gaussian blur and additive blend.

This value specifies at what 'brightness' the pixels of the surfaces using this material should start to bloom. Brightness is effectively the magnitude of the final color of a pixel (modified for the human eye: specifically it is the dot product of the final color with (0.2126, 0.7152, 0.0722)).

For example, if this property is set to 0.0, then all surfaces using this material will bloom. If this property is set to 1.0, then only those pixels of the surface whose brightness exceeds 1.0 (after lights are applied) will bloom.

Default is -1.0, which disables bloom.

Parameters
bloomThreshold float: The bloom threshold value to set. Set to less than zero to disable bloom entirely.

setChromaKeyFilteringColor

void setChromaKeyFilteringColor (int color)

Set the color to remove from all surfaces rendering with this material, via chroma key filtering. Chroma key filtering enables partially transparent ("alpha") videos. When chroma key filtering is enabled, all colors within an epsilon range this color will be removed (made transparent). This technique is useful when rendering "green screen" or "blue screen" videos, as is commonly seen in newscasting and motion pictures. To enable chroma key filtering, you must also call setChromaKeyFilteringEnabled(boolean).

Parameters
color int: The Color to use for the filtering.

setChromaKeyFilteringEnabled

void setChromaKeyFilteringEnabled (boolean enabled)

Enable chroma key filtering for this material. Chroma key filtering enables partially transparent ("alpha") videos. When chroma key filtering is enabled, all colors within an epsilon range about the chroma key filtering color will be removed (made transparent). This technique is useful when rendering "green screen" or "blue screen" videos, as is commonly seen in newscasting and motion pictures. To set the color to be removed, use setChromaKeyFilteringColor(int).

Parameters
enabled boolean: True to enable chroma key filtering.

setCullMode

void setCullMode (Material.CullMode cullMode)

Set the Material.CullMode to use for this Material. CullMode determines whether we render front faces, back faces, or both.

Parameters
cullMode Material.CullMode: The CullMode to use for this Material.

setDiffuseColor

void setDiffuseColor (int color)

Set the diffuse Color to use for this Material. The diffuse color, if specified, defines the "base" color of the surfaces using this Material. More specifically, the diffuse color defines for each pixel the light that is reflected from the surface, independent of point of view.

If a diffuse Texture is also defined, it will be modulated (multiplied) by this color.

Defaults to white.

Parameters
color int: The diffuse Color to use for this Material.

setDiffuseTexture

void setDiffuseTexture (Texture texture)

Set the diffuse Texture to use for this Material. The diffuse texture, if specified, defines the "base" color of the surfaces using this Material. More specifically, the diffuse Texture defines for each pixel the light that is reflected from the surface, independent of point of view.

The color from the diffuse Texture will be modulated (multiplied) by the diffuse color.

Parameters
texture Texture: The diffuse Texture to use for this Material.

setLightingModel

void setLightingModel (Material.LightingModel lightingModel)

Set the Material.LightingModel to use for this Material. LightingModel defines a formula for combining a material’s diffuse, specular, and other properties with the Lights in the Scene, and the point of view, to create the color of each rendered pixel.

Defaults to CONSTANT.

Parameters
lightingModel Material.LightingModel: The LightingModel to use for this Material.

setMetalness

void setMetalness (float metalness)

Set a uniform metalness value to use for this Material. Metalness defines how "metallic" the surface is at each pixel, which influences the degree to which light reflects off the surface, the sharpness of the reflections, and more.

This property is only used under PHYSICALLY_BASED lighting. If a metalness map is set (by setMetalnessMap(Texture), then this value is ignored, and the values derived from the metalness map are used instead.

Parameters
metalness float: The uniform metalness value to use for this Material.

setMetalnessMap

void setMetalnessMap (Texture metalnessMap)

Set the metalness Texture to use for this Material. The metalness map defines how "metallic" the surface is at each texel, which influences the degree to which light reflects off the surface, the sharpness of the reflections, and more.

This property is only used under PHYSICALLY_BASED lighting.

Parameters
metalnessMap Texture: The metalness map to use for this Material.

setName

void setName (String name)

Sets a (non-unique) name to represent this Material object. Names may be automatically set when loaded from OBJ or FBX files.

Parameters
name String

setNormalMap

void setNormalMap (Texture normalMap)

Set the normal map Texture to use for this Material. Normal maps define the orientation of the surface used by this Material for each pixel, thus enabling the fine-grained responses to light that are necessary to simulate rough surfaces.

For each pixel of the normal map, the RGB colors are interpreted by the renderer as XYZ components of a surface normal vector.

Parameters
normalMap Texture: The normal map to use for this Material.

setReadsFromDepthBuffer

void setReadsFromDepthBuffer (boolean readsFromDepthBuffer)

Set whether this Material reads from the depth buffer. Viro tracks the depth of each object in the scene with a depth buffer. This way the renderer can determine which surfaces occlude others from the point of view of the user.

Set this to true to read from the depth buffer. By doing so, the surface first checks if any other surface is closer to the user: if so, the surface will not appear (it is occluded).

Set to false for advanced usage only. Defaults to true.

Parameters
readsFromDepthBuffer boolean: True to read from the depth buffer.

setRoughness

void setRoughness (float roughness)

Set a uniform roughness value to use for this Material. Roughness defines the roughness of the surface's microfacets, at each pixel. The rougher a surface is (roughness approaching 1.0), the more light sill scatter along completely different directions, resulting in larger and more muted specular reflections. Smoother surfaces (roughness approaching 0.0), meanwhile, exhibit a sharper specular reflection as light rays are more likely to reflect in a uniform direction.

This property is only used under PHYSICALLY_BASED lighting. If a roughness map is set (by setRoughnessMap(Texture), then this value is ignored, and the values derived from the roughness map are used instead.

Parameters
roughness float: The uniform roughness value to use for this Material.

setRoughnessMap

void setRoughnessMap (Texture roughnessMap)

Set the roughness Texture to use for this Material. The roughness map defines the roughness of the surface's microfacets at each texel. The rougher a surface is (roughness approaching 1.0), the more light sill scatter along completely different directions, resulting in larger and more muted specular reflections. Smoother surfaces (roughness approaching 0.0), meanwhile, exhibit a sharper specular reflection as light rays are more likely to reflect in a uniform direction.

This property is only used under PHYSICALLY_BASED lighting.

Parameters
roughnessMap Texture: The roughness map to use for this Material.

setShadowMode

void setShadowMode (Material.ShadowMode shadowMode)

Set the Material.ShadowMode for this Material, which defines how surfaces using this Material render shadows. See Material.ShadowMode for details. The default value is NORMAL.

Parameters
shadowMode Material.ShadowMode: The Material.ShadowMode to use for this Material.

setShininess

void setShininess (float shininess)

Set the sharpness of specular highlights. This only applies if this Material has a specular texture. See Material.LightingModel for the specifics of how the shininess value is applied.

Defaults to 2.0.

This property is ignored if the Material is using PHYSICALLY_BASED.

Parameters
shininess float: The shininess value.

setSpecularTexture

void setSpecularTexture (Texture texture)

Set the specular Texture to use with this Material. The specular Texture defines the amount of light that is reflected by the Material toward the user, resulting in a bright, shiny highlight. Specular effects are point of view dependent, and only have an effect when using the Blinn or Phong lighting models. See Material.LightingModel for more details on how the specular highlights are computed.

This property is ignored if the Material is using PHYSICALLY_BASED.

Parameters
texture Texture: The specular Texture to use for this Material.

setTransparencyMode

void setTransparencyMode (Material.TransparencyMode transparencyMode)

Set the Material.TransparencyMode to use for this Material. TransparencyMode determines how the opacity of pixels is computed.

Parameters
transparencyMode Material.TransparencyMode: The TransparencyMode used by this material.

setWritesToDepthBuffer

void setWritesToDepthBuffer (boolean writesToDepthBuffer)

Set whether this Material writes to the depth buffer. Viro tracks the depth of each object in the scene with a depth buffer. This way the renderer can determine which surfaces occlude others from the point of view of the user.

Set this to true to write the depth buffer. By doing so, any surfaces that *read* from the depth buffer will only appear if they are at a shallower depth than this material (e.g. if they are closer to the user). Defaults to true.

Set to false for advanced usage only. Defaults to true.

Parameters
writesToDepthBuffer boolean: True to write to the depth buffer.

Hooray!