Client API. The Codename One framework your app is built on: this runs on the device, not in a backend.

public final class Material

Object
Material

A declarative description of how a surface should be shaded. The 3D engine is responsible for translating a material into a platform shader (GLSL on OpenGL ES and WebGL, Metal Shading Language on iOS); applications never write shader source. A material combines a lighting model (Type), a base color, an optional texture and pipeline RenderState.

Nested types

enum Material.Type The built in lighting model used to shade a surface.

Fields

public static final int MAX_JOINTS = 64 The most joints setSkinning takes.

Constructors

`public Material()`	Creates an unlit white material.
`public Material(Material.Type type)`	Creates a material of the supplied type.

Methods

`public` `Material.Type getType()`	Returns the lighting model.
`public` `Material setType(Material.Type type)`	Sets the lighting model.
`public int getColor()`	Returns the base color as a packed ARGB integer.
`public` `Material setColor(int argb)`	Sets the base color as a packed ARGB integer (0xAARRGGBB).
`public` `Texture getTexture()`	Returns the diffuse texture, or null when the material is untextured.
`public` `Material setTexture(Texture texture)`	Sets the diffuse texture.
`public float getShininess()`	Returns the Phong specular exponent.
`public` `Material setShininess(float shininess)`	Sets the Phong specular exponent (used only by `Type.PHONG`).
`public` `RenderState getRenderState()`	Returns the pipeline render state.
`public` `Material setRenderState(RenderState renderState)`	Sets the pipeline render state.
`public float getMetallic()`	Returns how metallic a `Type.PBR` surface is, from 0 (a dielectric such as paint, plastic or wood) to 1 (bare metal).
`public` `Material setMetallic(float metallic)`	Sets how metallic a `Type.PBR` surface is.
`public float getRoughness()`	Returns how rough a `Type.PBR` surface is, from 0 (mirror) to 1 (chalk).
`public` `Material setRoughness(float roughness)`	Sets how rough a `Type.PBR` surface is.
`public int getEmissive()`	Returns the light the surface gives off by itself, as RGB in an ARGB int; black for none.
`public` `Material setEmissive(int argb)`	Sets the light the surface gives off by itself: a lamp, a screen, wet paint catching the sun.
`public boolean isReceiveShadows()`	Returns true if the surface is darkened by shadows the light casts.
`public` `Material setReceiveShadows(boolean receiveShadows)`	Sets whether the surface is darkened by the light’s shadows.
`public boolean isCastShadows()`	Returns true if geometry drawn with this material casts a shadow.
`public` `Material setCastShadows(boolean castShadows)`	Sets whether geometry drawn with this material casts a shadow.
`public boolean isLit()`	Returns true if this material is lit by the directional light.
`public` `String getShaderKey()`	Returns a stable string identifying the shader variant required by this material.
`public` `Material setSkinning(float[] rows, int count)`	Skins the meshes drawn with this material on the GPU.
`public float[] getJointRows()`	Returns the joint rows `setSkinning` gave, or null.
`public int getJointCount()`	Returns the number of joints `setSkinning` gave, 0 without skinning.
`public boolean isSkinned()`	True if the material skins its meshes on the GPU.
`public boolean isFogged()`	Returns false when the environment’s fog skips this material.
`public` `Material setFogged(boolean fogged)`	Sets whether the environment’s fog applies to this material.
`public` `ShaderMaterial getShader()`	Returns the custom shading attached to this material.
`public` `Material setShader(ShaderMaterial shader)`	Attaches custom shading: graphs that replace inputs of the shader the material’s type selects.
`public` `Material setNormalMap(Texture map, float strength)`	Sets a tangent space normal map, sampled with the primary texture coordinate.
`public` `Texture getNormalMap()`	Returns the normal map.
`public` `Material setDetailNormal(Texture map, float scale, float scrollU, float scrollV, float strength)`	Sets a tiling detail normal map, layered over the normal map, that can scroll with time: ripples on water, grain on stone.
`public` `Texture getDetailNormal()`	Returns the detail normal map.
`public` `Material setMetallicRoughnessMap(Texture map)`	Sets a glTF style metallic-roughness map: roughness in green and metallic in blue, each multiplying the material’s own factor.
`public` `Texture getMetallicRoughnessMap()`	Returns the metallic-roughness map.
`public` `Material setOcclusionMap(Texture map, float strength)`	Sets an ambient occlusion map, read from its red channel, that darkens creases and contact areas.
`public` `Texture getOcclusionMap()`	Returns the occlusion map.
`public` `Material setEmissiveMap(Texture map)`	Sets an emissive map, multiplied by the emissive colour (or by white when that is black): windows lit at night, glowing runes.
`public` `Texture getEmissiveMap()`	Returns the emissive map.
`public` `ShaderMaterial getEffectiveShader()`	Returns the shading backends draw this material with: the attached `ShaderMaterial` combined with the graphs the texture maps on this material need.

Inherited methods

From Object

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

Field details

MAX_JOINTS

public static final int MAX_JOINTS = 64

The most joints setSkinning takes. A rig of more is skinned on the CPU by com.codename1.gaming.AnimatedModel.

Constructor details

Material

public Material()

Creates an unlit white material.

Material

public Material(Material.Type type)

Creates a material of the supplied type.

Parameters

type Material.Type: the lighting model

Method details

getType

public Material.Type getType()

Returns the lighting model.

setType

public Material setType(Material.Type type)

Sets the lighting model.

Parameters

type Material.Type: the lighting model

Returns

this material for chaining

getColor

public int getColor()

Returns the base color as a packed ARGB integer.

setColor

public Material setColor(int argb)

Sets the base color as a packed ARGB integer (0xAARRGGBB).

Parameters

argb int: the packed ARGB color

Returns

this material for chaining

getTexture

public Texture getTexture()

Returns the diffuse texture, or null when the material is untextured.

setTexture

public Material setTexture(Texture texture)

Sets the diffuse texture. Pass null for an untextured material.

Parameters

texture Texture: the diffuse texture or null

Returns

this material for chaining

getShininess

public float getShininess()

Returns the Phong specular exponent.

setShininess

public Material setShininess(float shininess)

Sets the Phong specular exponent (used only by Type.PHONG).

Parameters

shininess float: the specular exponent

Returns

this material for chaining

getRenderState

public RenderState getRenderState()

Returns the pipeline render state.

setRenderState

public Material setRenderState(RenderState renderState)

Sets the pipeline render state.

Parameters

renderState RenderState: the render state

Returns

this material for chaining

getMetallic

public float getMetallic()

Returns how metallic a Type.PBR surface is, from 0 (a dielectric such as paint, plastic or wood) to 1 (bare metal).

setMetallic

public Material setMetallic(float metallic)

Sets how metallic a Type.PBR surface is.

Parameters

metallic float: 0 for a dielectric, 1 for metal

Returns

this material for chaining

getRoughness

public float getRoughness()

Returns how rough a Type.PBR surface is, from 0 (mirror) to 1 (chalk).

setRoughness

public Material setRoughness(float roughness)

Sets how rough a Type.PBR surface is. Rough surfaces spread their highlight wide and dim; smooth ones make it small and bright.

Parameters

roughness float: 0 for a mirror, 1 for fully diffuse

Returns

this material for chaining

getEmissive

public int getEmissive()

Returns the light the surface gives off by itself, as RGB in an ARGB int; black for none.

setEmissive

public Material setEmissive(int argb)

Sets the light the surface gives off by itself: a lamp, a screen, wet paint catching the sun. Emissive colour is added after lighting and is what a bloom post effect picks up. Used by Type.PBR, Type.LAMBERT and Type.PHONG.

Parameters

argb int: the emitted colour; black for none

Returns

this material for chaining

isReceiveShadows

public boolean isReceiveShadows()

Returns true if the surface is darkened by shadows the light casts.

setReceiveShadows

public Material setReceiveShadows(boolean receiveShadows)

Sets whether the surface is darkened by the light’s shadows. A ground plane receives them; a particle or a muzzle flash should not.

Parameters

receiveShadows boolean: true to receive shadows

Returns

this material for chaining

isCastShadows

public boolean isCastShadows()

Returns true if geometry drawn with this material casts a shadow.

setCastShadows

public Material setCastShadows(boolean castShadows)

Sets whether geometry drawn with this material casts a shadow. Transparent and unlit effects normally should not.

Parameters

castShadows boolean: true to cast shadows

Returns

this material for chaining

isLit

public boolean isLit()

Returns true if this material is lit by the directional light.

getShaderKey

public String getShaderKey()

Returns a stable string identifying the shader variant required by this material. Backends use it together with the mesh VertexFormat to cache generated and compiled shader programs. The key intentionally depends only on properties that change the generated source, not on values such as the color which are passed as uniforms.

Returns

a shader variant cache key

setSkinning

public Material setSkinning(float[] rows, int count)

Skins the meshes drawn with this material on the GPU. Each joint is three rows of its 4x4 matrix (the fourth is always 0, 0, 0, 1), so joint j is rows[j * 12 .. j * 12 + 11]: the first row’s four values, then the second’s, then the third’s. A mesh in VertexFormat.SKINNED moves each vertex by its four joints blended by their weights; a mesh without joints draws as it is. The array is read at every draw, so an animation updates it in place. Use it only where GraphicsDevice.isGpuSkinning says the device can.

Parameters

rows float[]: the joint rows, at least count * 12 floats, or null to stop skinning
count int: the number of joints, at most MAX_JOINTS

Returns

this material

getJointRows

public float[] getJointRows()

Returns the joint rows setSkinning gave, or null.

Returns

the rows, shared and not copied

getJointCount

public int getJointCount()

Returns the number of joints setSkinning gave, 0 without skinning.

Returns

the joint count

isSkinned

public boolean isSkinned()

True if the material skins its meshes on the GPU.

Returns

true after setSkinning with joints

isFogged

public boolean isFogged()

Returns false when the environment’s fog skips this material.

Returns

true when fogged, the default

setFogged

public Material setFogged(boolean fogged)

Sets whether the environment’s fog applies to this material. Turn it off for sky domes and distant backdrops that already paint their own haze, which fog would wash out to a flat colour.

Parameters

fogged boolean: false to draw without fog

Returns

this material

getShader

public ShaderMaterial getShader()

Returns the custom shading attached to this material.

Returns

the shader, or null for the engine’s own

setShader

public Material setShader(ShaderMaterial shader)

Attaches custom shading: graphs that replace inputs of the shader the material’s type selects. The library in com.codename1.gpu.shaders builds ready made ones.

Parameters

shader ShaderMaterial: the shader, or null for the engine’s own

Returns

this material

setNormalMap

public Material setNormalMap(Texture map, float strength)

Sets a tangent space normal map, sampled with the primary texture coordinate. The tangent frame comes from the surface normal (see ShaderNode.perturbNormal), so a mesh needs no tangents. Lit types only.

Parameters

map Texture: the normal map, or null for none
strength float: 1 for the map as authored

Returns

this material

getNormalMap

public Texture getNormalMap()

Returns the normal map.

Returns

the map, or null

setDetailNormal

public Material setDetailNormal(Texture map, float scale, float scrollU, float scrollV, float strength)

Sets a tiling detail normal map, layered over the normal map, that can scroll with time: ripples on water, grain on stone.

Parameters

map Texture: a tileable normal map, or null for none
scale float: how many times it repeats per unit of texture coordinate
scrollU float: texture coordinate units per second along u
scrollV float: texture coordinate units per second along v
strength float: 1 for the map as authored

Returns

this material

getDetailNormal

public Texture getDetailNormal()

Returns the detail normal map.

Returns

the map, or null

setMetallicRoughnessMap

public Material setMetallicRoughnessMap(Texture map)

Sets a glTF style metallic-roughness map: roughness in green and metallic in blue, each multiplying the material’s own factor. PBR only.

Parameters

map Texture: the map, or null for none

Returns

this material

getMetallicRoughnessMap

public Texture getMetallicRoughnessMap()

Returns the metallic-roughness map.

Returns

the map, or null

setOcclusionMap

public Material setOcclusionMap(Texture map, float strength)

Sets an ambient occlusion map, read from its red channel, that darkens creases and contact areas.

Parameters

map Texture: the map, or null for none
strength float: 0 for no effect, 1 for the full map

Returns

this material

getOcclusionMap

public Texture getOcclusionMap()

Returns the occlusion map.

Returns

the map, or null

setEmissiveMap

public Material setEmissiveMap(Texture map)

Sets an emissive map, multiplied by the emissive colour (or by white when that is black): windows lit at night, glowing runes.

Parameters

map Texture: the map, or null for none

Returns

this material

getEmissiveMap

public Texture getEmissiveMap()

Returns the emissive map.

Returns

the map, or null

getEffectiveShader

public ShaderMaterial getEffectiveShader()

Returns the shading backends draw this material with: the attached ShaderMaterial combined with the graphs the texture maps on this material need. A hook the attached shader sets wins over a map. For backends; applications use getShader.

Returns

the shader to draw with, or null for the engine’s own