Package com.google.android.filament

Class Material

java.lang.Object

com.google.android.filament.Material

public class Material
extends java.lang.Object

A Filament Material defines the visual appearance of an object. Materials function as a templates from which MaterialInstances can be spawned. Use Material.Builder to construct a Material object.

See Also:

Filament Materials Guide

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Material.BlendingMode	Supported blending modes
static class	Material.Builder
static class	Material.CullingMode	Face culling Mode
static class	Material.Interpolation	Attribute interpolation types in the fragment shader
static class	Material.Parameter
static class	Material.RefractionMode	Supported refraction modes
static class	Material.RefractionType	Supported refraction types
static class	Material.Shading	Supported shading models
static class	Material.VertexDomain	Supported types of vertex domains

Constructor Summary

Constructors

Constructor	Description
Material(long nativeMaterial)

Method Summary

Modifier and Type	Method	Description
MaterialInstance	createInstance()	Creates a new instance of this material.
MaterialInstance	createInstance(java.lang.String name)	Creates a new instance of this material with a specified name.
Material.BlendingMode	getBlendingMode()	Returns the blending mode of this material.
Material.CullingMode	getCullingMode()	Returns the default culling mode of this material.
MaterialInstance	getDefaultInstance()	Returns the material's default instance.
Material.Interpolation	getInterpolation()	Returns the interpolation mode of this material.
float	getMaskThreshold()	Returns the alpha mask threshold used when the blending mode is set to masked.
java.lang.String	getName()	Returns the name of this material.
long	getNativeObject()
int	getParameterCount()	Returns the number of parameters declared by this material.
java.util.List<Material.Parameter>	getParameters()	Returns a list of Parameter objects representing this material's parameters.
Material.RefractionMode	getRefractionMode()	Returns the refraction mode of this material.
Material.RefractionType	getRefractionType()	Returns the refraction type of this material.
java.util.Set<VertexBuffer.VertexAttribute>	getRequiredAttributes()	Returns a set of VertexBuffer.VertexAttributes that are required by this material.
Material.Shading	getShading()	Returns the shading model of this material.
float	getSpecularAntiAliasingThreshold()	Returns the clamping threshold for specular-antialiasing.
float	getSpecularAntiAliasingVariance()	Returns the screen-space variance for specular-antialiasing.
Material.VertexDomain	getVertexDomain()	Returns the vertex domain of this material.
boolean	hasParameter(java.lang.String name)	Indicates whether a parameter of the given name exists on this material.
boolean	isColorWriteEnabled()	Indicates whether instances of this material will, by default, write to the color buffer.
boolean	isDepthCullingEnabled()	Indicates whether instances of this material will, by default, use depth testing.
boolean	isDepthWriteEnabled()	Indicates whether instances of this material will, by default, write to the depth buffer.
boolean	isDoubleSided()	Indicates whether this material is double-sided.
void	setDefaultParameter(java.lang.String name, boolean x)	Sets the value of a bool parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, boolean x, boolean y)	Sets the value of a bool2 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, boolean x, boolean y, boolean z)	Sets the value of a bool3 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, boolean x, boolean y, boolean z, boolean w)	Sets the value of a bool4 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, float x)	Sets the value of a float parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, float x, float y)	Sets the value of a float2 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, float x, float y, float z)	Sets the value of a float3 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, float x, float y, float z, float w)	Sets the value of a float4 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, int x)	Sets the value of an int parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, int x, int y)	Sets the value of an int2 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, int x, int y, int z)	Sets the value of a int3 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, int x, int y, int z, int w)	Sets the value of a int4 parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, Colors.RgbaType type, float r, float g, float b, float a)	Sets the color of the given parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, Colors.RgbType type, float r, float g, float b)	Sets the color of the given parameter on this material's default instance.
void	setDefaultParameter(java.lang.String name, MaterialInstance.BooleanElement type, boolean[] v, int offset, int count)	Set a bool parameter array by name.
void	setDefaultParameter(java.lang.String name, MaterialInstance.FloatElement type, float[] v, int offset, int count)	Set a float parameter array by name.
void	setDefaultParameter(java.lang.String name, MaterialInstance.IntElement type, int[] v, int offset, int count)	Set an int parameter array by name.
void	setDefaultParameter(java.lang.String name, Texture texture, TextureSampler sampler)	Sets a texture and sampler parameter on this material's default instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Material

public Material(long nativeMaterial)

Method Detail

createInstance

@NonNull
public MaterialInstance createInstance()

Creates a new instance of this material. Material instances should be freed using Engine.destroyMaterialInstance(MaterialInstance).

Returns:

the new instance

createInstance

@NonNull
public MaterialInstance createInstance(@NonNull
                                       java.lang.String name)

Creates a new instance of this material with a specified name. Material instances should be freed using Engine.destroyMaterialInstance(MaterialInstance).

Parameters:

name - arbitrary label to associate with the given material instance

Returns:

the new instance

getDefaultInstance

@NonNull
public MaterialInstance getDefaultInstance()

Returns the material's default instance.

getName

public java.lang.String getName()

Returns the name of this material. The material name is used for debugging purposes.

See Also:

General: name

getShading

public Material.Shading getShading()

Returns the shading model of this material.

See Also:

Material Models

getInterpolation

public Material.Interpolation getInterpolation()

Returns the interpolation mode of this material. This affects how variables are interpolated.

See Also:

Vertex and attributes: interpolation

getBlendingMode

public Material.BlendingMode getBlendingMode()

Returns the blending mode of this material.

See Also:

Blending and transparency: blending

getRefractionMode

public Material.RefractionMode getRefractionMode()

Returns the refraction mode of this material.

See Also:

Blending and transparency: refraction

getRefractionType

public Material.RefractionType getRefractionType()

Returns the refraction type of this material.

See Also:

Blending and transparency: refractionType

getVertexDomain

public Material.VertexDomain getVertexDomain()

Returns the vertex domain of this material.

See Also:

Vertex and attributes: vertexDomain

getCullingMode

public Material.CullingMode getCullingMode()

Returns the default culling mode of this material.

See Also:

Rasterization: culling

isColorWriteEnabled

public boolean isColorWriteEnabled()

Indicates whether instances of this material will, by default, write to the color buffer.

See Also:

Rasterization: colorWrite

isDepthWriteEnabled

public boolean isDepthWriteEnabled()

Indicates whether instances of this material will, by default, write to the depth buffer.

See Also:

Rasterization: depthWrite

isDepthCullingEnabled

public boolean isDepthCullingEnabled()

Indicates whether instances of this material will, by default, use depth testing.

See Also:

Rasterization: depthCulling

isDoubleSided

public boolean isDoubleSided()

Indicates whether this material is double-sided.

See Also:

Rasterization: doubleSided

getMaskThreshold

public float getMaskThreshold()

Returns the alpha mask threshold used when the blending mode is set to masked.

See Also:

Blending and transparency: maskThreshold

getSpecularAntiAliasingVariance

public float getSpecularAntiAliasingVariance()

Returns the screen-space variance for specular-antialiasing. This value is between 0 and 1.

See Also:

Anti-aliasing: specularAntiAliasingVariance

getSpecularAntiAliasingThreshold

public float getSpecularAntiAliasingThreshold()

Returns the clamping threshold for specular-antialiasing. This value is between 0 and 1.

See Also:

Anti-aliasing: specularAntiAliasingThreshold

getRequiredAttributes

public java.util.Set<VertexBuffer.VertexAttribute> getRequiredAttributes()

Returns a set of VertexBuffer.VertexAttributes that are required by this material.

See Also:

Vertex and attributes: requires

getParameterCount

public int getParameterCount()

Returns the number of parameters declared by this material. The returned value can be 0.

See Also:

General: parameters

getParameters

public java.util.List<Material.Parameter> getParameters()

Returns a list of Parameter objects representing this material's parameters. The list may be empty if the material has no declared parameters.

See Also:

General: parameters

hasParameter

public boolean hasParameter(@NonNull
                            java.lang.String name)

Indicates whether a parameter of the given name exists on this material.

See Also:

General: parameters

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                boolean x)

Sets the value of a bool parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the material parameter

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                float x)

Sets the value of a float parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the material parameter

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                int x)

Sets the value of an int parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the material parameter

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                boolean x,
                                boolean y)

Sets the value of a bool2 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                float x,
                                float y)

Sets the value of a float2 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                int x,
                                int y)

Sets the value of an int2 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                boolean x,
                                boolean y,
                                boolean z)

Sets the value of a bool3 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                float x,
                                float y,
                                float z)

Sets the value of a float3 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                int x,
                                int y,
                                int z)

Sets the value of a int3 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                boolean x,
                                boolean y,
                                boolean z,
                                boolean w)

Sets the value of a bool4 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

w - the value of the fourth component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                float x,
                                float y,
                                float z,
                                float w)

Sets the value of a float4 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

w - the value of the fourth component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                int x,
                                int y,
                                int z,
                                int w)

Sets the value of a int4 parameter on this material's default instance.

Parameters:

name - the name of the material parameter

x - the value of the first component

y - the value of the second component

z - the value of the third component

w - the value of the fourth component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                MaterialInstance.BooleanElement type,
                                @NonNull @Size(min=1L)
                                boolean[] v,
                                @IntRange(from=0L)
                                int offset,
                                @IntRange(from=1L)
                                int count)

Set a bool parameter array by name.

Parameters:

name - name of the parameter array as defined by this Material

type - the number of components for each individual parameter

v - array of values to set to the named parameter array

offset - the number of elements in v to skip

count - the number of elements in the parameter array to set

For example, to set a parameter array of 4 bool4s:

     boolean[] a = new boolean[4 * 4];
     material.setDefaultParameter("param", MaterialInstance.BooleanElement.BOOL4, a, 0, 4);
 

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                MaterialInstance.IntElement type,
                                @NonNull @Size(min=1L)
                                int[] v,
                                @IntRange(from=0L)
                                int offset,
                                @IntRange(from=1L)
                                int count)

Set an int parameter array by name.

Parameters:

name - name of the parameter array as defined by this Material

type - the number of components for each individual parameter

v - array of values to set to the named parameter array

offset - the number of elements in v to skip

count - the number of elements in the parameter array to set

For example, to set a parameter array of 4 int4s:

     int[] a = new int[4 * 4];
     material.setDefaultParameter("param", MaterialInstance.IntElement.INT4, a, 0, 4);
 

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                MaterialInstance.FloatElement type,
                                @NonNull @Size(min=1L)
                                float[] v,
                                @IntRange(from=0L)
                                int offset,
                                @IntRange(from=1L)
                                int count)

Set a float parameter array by name.

Parameters:

name - name of the parameter array as defined by this Material

type - the number of components for each individual parameter

v - array of values to set to the named parameter array

offset - the number of elements in v to skip

count - the number of elements in the parameter array to set

For example, to set a parameter array of 4 float4s:

     float[] a = new float[4 * 4];
     material.setDefaultParameter("param", MaterialInstance.FloatElement.FLOAT4, a, 0, 4);
 

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                Colors.RgbType type,
                                float r,
                                float g,
                                float b)

Sets the color of the given parameter on this material's default instance.

Parameters:

name - the name of the material color parameter

type - whether the color is specified in the linear or sRGB space

r - red component

g - green component

b - blue component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                Colors.RgbaType type,
                                float r,
                                float g,
                                float b,
                                float a)

Sets the color of the given parameter on this material's default instance.

Parameters:

name - the name of the material color parameter

type - whether the color is specified in the linear or sRGB space

r - red component

g - green component

b - blue component

a - alpha component

See Also:

getDefaultInstance()

setDefaultParameter

public void setDefaultParameter(@NonNull
                                java.lang.String name,
                                @NonNull
                                Texture texture,
                                @NonNull
                                TextureSampler sampler)

Sets a texture and sampler parameter on this material's default instance.

Parameters:

name - The name of the material texture parameter

texture - The texture to set as parameter

sampler - The sampler to be used with this texture

See Also:

getDefaultInstance()

getNativeObject

public long getNativeObject()