Class Material

java.lang.Object
com.codename1.gpu.Material
public final class Material extends Object
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.

  • Field Details

    • MAX_JOINTS

      public static final int MAX_JOINTS
      The most joints setSkinning takes. A rig of more is skinned on the CPU by com.codename1.gaming.AnimatedModel.
      See Also:

  • 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: the joint rows, at least count * 12 floats, or null to stop skinning

      • count: 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: 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: 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: the normal map, or null for none

      • strength: 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: a tileable normal map, or null for none

      • scale: how many times it repeats per unit of texture coordinate

      • scrollU: texture coordinate units per second along u

      • scrollV: texture coordinate units per second along v

      • strength: 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: 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: the map, or null for none

      • strength: 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: 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