com.jme3.material

Class Material

java.lang.Object

com.jme3.material.Material

All Implemented Interfaces:

CloneableSmartAsset, Savable, java.lang.Cloneable

public class Material
extends java.lang.Object
implements CloneableSmartAsset, java.lang.Cloneable, Savable

Material describes the rendering style for a given Geometry.

A material is essentially a list of parameters, those parameters map to uniforms which are defined in a shader. Setting the parameters can modify the behavior of a shader.

Field Summary

Fields

Modifier and Type	Field and Description
static int	SAVABLE_VERSION

Constructor Summary

Constructors

Constructor and Description
Material() Do not use this constructor.
Material(AssetManager contentMan, java.lang.String defName)
Material(MaterialDef def)

Method Summary

Modifier and Type	Method and Description
void	clearParam(java.lang.String name) Clear a parameter from this material.
Material	clone() Clones this material.
boolean	contentEquals(java.lang.Object otherObj) Compares two materials and returns true if they are equal.
int	contentHashCode() Works like Object.hashCode() except it may change together with the material as the material is mutable by definition.
Technique	getActiveTechnique() Returns the currently active technique.
RenderState	getAdditionalRenderState() Acquire the additional render state to apply for this material.
java.lang.String	getAssetName() Returns the asset key name of the asset from which this material was loaded.
AssetKey	getKey() Returns the asset key that is used to track this asset for garbage collection.
MaterialDef	getMaterialDef() Get the material definition (j3md file info) that this material is implementing.
java.lang.String	getName()
MatParam	getParam(java.lang.String name) Returns the parameter set on this material with the given name, returns null if the parameter is not set.
java.util.Collection<MatParam>	getParams() Returns a collection of all parameters set on this material.
ListMap<java.lang.String,MatParam>	getParamsMap() Returns the ListMap of all parameters set on this material.
<T> T	getParamValue(java.lang.String name) Returns the current parameter's value.
int	getSortId() Returns the sorting ID or sorting index for this material.
MatParamTexture	getTextureParam(java.lang.String name) Returns the texture parameter set on this material with the given name, returns null if the parameter is not set.
boolean	isReceivesShadows() Check if the material should receive shadows or not.
boolean	isTransparent() Check if the transparent value marker is set on this material.
void	preload(RenderManager renderManager, Geometry geometry) Preloads this material for the given render manager.
void	read(JmeImporter im)
void	render(Geometry geometry, LightList lights, RenderManager renderManager) Called by RenderManager to render the geometry by using this material.
void	render(Geometry geom, RenderManager rm) Called by RenderManager to render the geometry by using this material.
void	selectTechnique(java.lang.String name, RenderManager renderManager) Select the technique to use for rendering this material.
void	setBoolean(java.lang.String name, boolean value) Pass a boolean to the material shader.
void	setColor(java.lang.String name, ColorRGBA value) Pass a Color to the material shader.
void	setFloat(java.lang.String name, float value) Pass a float to the material shader.
void	setFloat(java.lang.String name, java.lang.Float value) Pass a float to the material shader.
void	setInt(java.lang.String name, int value) Pass an int to the material shader.
void	setKey(AssetKey key) Set by the AssetManager to track this asset.
void	setMatrix4(java.lang.String name, Matrix4f value) Pass a Matrix4f to the material shader.
void	setName(java.lang.String name) This method sets the name of the material.
void	setParam(java.lang.String name, VarType type, java.lang.Object value) Pass a parameter to the material shader.
void	setReceivesShadows(boolean receivesShadows) Set if the material should receive shadows or not.
void	setShaderStorageBufferObject(java.lang.String name, BufferObject value) Pass a shader storage buffer object to the material shader.
void	setTexture(java.lang.String name, Texture value) Pass a texture to the material shader.
void	setTextureParam(java.lang.String name, VarType type, Texture value) Set a texture parameter.
void	setTransparent(boolean transparent) Set the transparent value marker.
void	setUniformBufferObject(java.lang.String name, BufferObject value) Pass an uniform buffer object to the material shader.
void	setVector2(java.lang.String name, Vector2f value) Pass a Vector2f to the material shader.
void	setVector3(java.lang.String name, Vector3f value) Pass a Vector3f to the material shader.
void	setVector4(java.lang.String name, Vector4f value) Pass a Vector4f to the material shader.
java.lang.String	toString()
void	write(JmeExporter ex)

Methods inherited from class java.lang.Object

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

Field Detail

SAVABLE_VERSION

public static final int SAVABLE_VERSION

See Also:

Constant Field Values

Constructor Detail

Material

public Material(MaterialDef def)

Material

public Material(AssetManager contentMan,
                java.lang.String defName)

Material

public Material()

Do not use this constructor. Serialization purposes only.

Method Detail

getAssetName

public java.lang.String getAssetName()

Returns the asset key name of the asset from which this material was loaded.

This value will be null unless this material was loaded from a .j3m file.

Returns:

Asset key name of the j3m file

getName

public java.lang.String getName()

Returns:

the name of the material (not the same as the asset name), the returned value can be null

setName

public void setName(java.lang.String name)

This method sets the name of the material. The name is not the same as the asset name. It can be null and there is no guarantee of its uniqueness.

Parameters:

name - the name of the material

setKey

public void setKey(AssetKey key)

Description copied from interface: CloneableSmartAsset

Set by the AssetManager to track this asset. Only clones of the asset has this set, the original copy that was loaded has this key set to null so that only the clones are tracked for garbage collection.

Specified by:

setKey in interface CloneableSmartAsset

Parameters:

key - The AssetKey to set

getKey

public AssetKey getKey()

Description copied from interface: CloneableSmartAsset

Returns the asset key that is used to track this asset for garbage collection.

Specified by:

getKey in interface CloneableSmartAsset

Returns:

the asset key that is used to track this asset for garbage collection.

getSortId

public int getSortId()

Returns the sorting ID or sorting index for this material.

The sorting ID is used internally by the system to sort rendering of geometries. It sorted to reduce shader switches, if the shaders are equal, then it is sorted by textures.

Returns:

The sorting ID used for sorting geometries for rendering.

clone

public Material clone()

Clones this material. The result is returned.

Specified by:

clone in interface CloneableSmartAsset

Overrides:

clone in class java.lang.Object

Returns:

A clone of this asset. The cloned asset cannot reference equal this asset.

contentEquals

public boolean contentEquals(java.lang.Object otherObj)

Compares two materials and returns true if they are equal. This methods compare definition, parameters, additional render states. Since materials are mutable objects, implementing equals() properly is not possible, hence the name contentEquals().

Parameters:

otherObj - the material to compare to this material

Returns:

true if the materials are equal.

contentHashCode

public int contentHashCode()

Works like Object.hashCode() except it may change together with the material as the material is mutable by definition.

Returns:

value for use in hashing

getActiveTechnique

public Technique getActiveTechnique()

Returns the currently active technique.

The technique is selected automatically by the RenderManager based on system capabilities. Users may select their own technique by using selectTechnique(java.lang.String, com.jme3.renderer.RenderManager).

Returns:

the currently active technique.

See Also:

selectTechnique(java.lang.String, com.jme3.renderer.RenderManager)

isTransparent

public boolean isTransparent()

Check if the transparent value marker is set on this material.

Returns:

True if the transparent value marker is set on this material.

See Also:

setTransparent(boolean)

setTransparent

public void setTransparent(boolean transparent)

Set the transparent value marker.

This value is merely a marker, by itself it does nothing. Generally model loaders will use this marker to indicate further up that the material is transparent and therefore any geometries using it should be put into the transparent bucket.

Parameters:

transparent - the transparent value marker.

isReceivesShadows

public boolean isReceivesShadows()

Check if the material should receive shadows or not.

Returns:

True if the material should receive shadows.

See Also:

setReceivesShadows(boolean)

setReceivesShadows

public void setReceivesShadows(boolean receivesShadows)

Set if the material should receive shadows or not.

This value is merely a marker, by itself it does nothing. Generally model loaders will use this marker to indicate the material should receive shadows and therefore any geometries using it should have RenderQueue.ShadowMode.Receive set on them.

Parameters:

receivesShadows - if the material should receive shadows or not.

getAdditionalRenderState

public RenderState getAdditionalRenderState()

Acquire the additional render state to apply for this material.

The first call to this method will create an additional render state which can be modified by the user to apply any render states in addition to the ones used by the renderer. Only render states which are modified in the additional render state will be applied.

Returns:

The additional render state.

getMaterialDef

public MaterialDef getMaterialDef()

Get the material definition (j3md file info) that this material is implementing.

Returns:

the material definition this material implements.

getParam

public MatParam getParam(java.lang.String name)

Returns the parameter set on this material with the given name, returns null if the parameter is not set.

Parameters:

name - The parameter name to look up.

Returns:

The MatParam if set, or null if not set.

getParamValue

public <T> T getParamValue(java.lang.String name)

Returns the current parameter's value.

Type Parameters:

T - the expected type of the parameter value

Parameters:

name - the parameter name to look up.

Returns:

current value or null if the parameter wasn't set.

getTextureParam

public MatParamTexture getTextureParam(java.lang.String name)

Returns the texture parameter set on this material with the given name, returns null if the parameter is not set.

Parameters:

name - The parameter name to look up.

Returns:

The MatParamTexture if set, or null if not set.

getParams

public java.util.Collection<MatParam> getParams()

Returns a collection of all parameters set on this material.

Returns:

a collection of all parameters set on this material.

See Also:

setParam(java.lang.String, com.jme3.shader.VarType, java.lang.Object)

getParamsMap

public ListMap<java.lang.String,MatParam> getParamsMap()

Returns the ListMap of all parameters set on this material.

Returns:

a ListMap of all parameters set on this material.

See Also:

setParam(java.lang.String, com.jme3.shader.VarType, java.lang.Object)

setParam

public void setParam(java.lang.String name,
                     VarType type,
                     java.lang.Object value)

Pass a parameter to the material shader.

Parameters:

name - the name of the parameter defined in the material definition (j3md)

type - the type of the parameter VarType

value - the value of the parameter

clearParam

public void clearParam(java.lang.String name)

Clear a parameter from this material. The parameter must exist

Parameters:

name - the name of the parameter to clear

setTextureParam

public void setTextureParam(java.lang.String name,
                            VarType type,
                            Texture value)

Set a texture parameter.

Parameters:

name - The name of the parameter

type - The variable type VarType

value - The texture value of the parameter.

Throws:

java.lang.IllegalArgumentException - is value is null

setTexture

public void setTexture(java.lang.String name,
                       Texture value)

Pass a texture to the material shader.

Parameters:

name - the name of the texture defined in the material definition (j3md) (for example Texture for Lighting.j3md)

value - the Texture object previously loaded by the asset manager

setMatrix4

public void setMatrix4(java.lang.String name,
                       Matrix4f value)

Pass a Matrix4f to the material shader.

Parameters:

name - the name of the matrix defined in the material definition (j3md)

value - the Matrix4f object

setBoolean

public void setBoolean(java.lang.String name,
                       boolean value)

Pass a boolean to the material shader.

Parameters:

name - the name of the boolean defined in the material definition (j3md)

value - the boolean value

setFloat

public void setFloat(java.lang.String name,
                     float value)

Pass a float to the material shader.

Parameters:

name - the name of the float defined in the material definition (j3md)

value - the float value

setFloat

public void setFloat(java.lang.String name,
                     java.lang.Float value)

Pass a float to the material shader. This version avoids auto-boxing if the value is already a Float.

Parameters:

name - the name of the float defined in the material definition (j3md)

value - the float value

setInt

public void setInt(java.lang.String name,
                   int value)

Pass an int to the material shader.

Parameters:

name - the name of the int defined in the material definition (j3md)

value - the int value

setColor

public void setColor(java.lang.String name,
                     ColorRGBA value)

Pass a Color to the material shader.

Parameters:

name - the name of the color defined in the material definition (j3md)

value - the ColorRGBA value

setUniformBufferObject

public void setUniformBufferObject(java.lang.String name,
                                   BufferObject value)

Pass an uniform buffer object to the material shader.

Parameters:

name - the name of the buffer object defined in the material definition (j3md).

value - the buffer object.

setShaderStorageBufferObject

public void setShaderStorageBufferObject(java.lang.String name,
                                         BufferObject value)

Pass a shader storage buffer object to the material shader.

Parameters:

name - the name of the buffer object defined in the material definition (j3md).

value - the buffer object.

setVector2

public void setVector2(java.lang.String name,
                       Vector2f value)

Pass a Vector2f to the material shader.

Parameters:

name - the name of the Vector2f defined in the material definition (j3md)

value - the Vector2f value

setVector3

public void setVector3(java.lang.String name,
                       Vector3f value)

Pass a Vector3f to the material shader.

Parameters:

name - the name of the Vector3f defined in the material definition (j3md)

value - the Vector3f value

setVector4

public void setVector4(java.lang.String name,
                       Vector4f value)

Pass a Vector4f to the material shader.

Parameters:

name - the name of the Vector4f defined in the material definition (j3md)

value - the Vector4f value

selectTechnique

public void selectTechnique(java.lang.String name,
                            RenderManager renderManager)

Select the technique to use for rendering this material.

Any candidate technique for selection (either default or named) must be verified to be compatible with the system, for that, the renderManager is queried for capabilities.

Parameters:

name - The name of the technique to select, pass TechniqueDef.DEFAULT_TECHNIQUE_NAME to select one of the default techniques.

renderManager - The render manager to query for capabilities.

Throws:

java.lang.IllegalArgumentException - If no technique exists with the given name.

java.lang.UnsupportedOperationException - If no candidate technique supports the system capabilities.

preload

public void preload(RenderManager renderManager,
                    Geometry geometry)

Preloads this material for the given render manager.

Preloading the material can ensure that when the material is first used for rendering, there won't be any delay since the material has been already been setup for rendering.

Parameters:

renderManager - The render manager to preload for

geometry - to determine the applicable parameter overrides, if any

render

public void render(Geometry geometry,
                   LightList lights,
                   RenderManager renderManager)

Called by RenderManager to render the geometry by using this material.

The material is rendered as follows:

• Determine which technique to use to render the material - either what the user selected via Material.selectTechnique(), or the first default technique that the renderer supports (based on the technique's requested rendering capabilities)
  • If the technique has been changed since the last frame, then it is notified via Technique.makeCurrent(). If the technique wants to use a shader to render the model, it should load it at this part - the shader should have all the proper defines as declared in the technique definition, including those that are bound to material parameters. The technique can re-use the shader from the last frame if no changes to the defines occurred.
• Set the RenderState to use for rendering. The render states are applied in this order (later RenderStates override earlier RenderStates):
  1. Technique Definition's RenderState - i.e. specific RenderState that is required for the shader.
  2. Material Instance Additional RenderState - i.e. ad-hoc RenderState set per model
  3. RenderManager's Forced RenderState - i.e. RenderState requested by a SceneProcessor or post-processing filter.
• If the technique uses a shader, then the uniforms of the shader must be updated.
  • Uniforms bound to material parameters are updated based on the current material parameter values.
  • Uniforms bound to world parameters are updated from the RenderManager. Internally UniformBindingManager is used for this task.
  • Uniforms bound to textures will cause the texture to be uploaded as necessary. The uniform is set to the texture unit where the texture is bound.
• If the technique uses a shader, the model is then rendered according to the lighting mode specified on the technique definition.
  • single pass light mode fills the shader's light uniform arrays with the first 4 lights and renders the model once.
  • multi pass light mode light mode renders the model multiple times, for the first light it is rendered opaque, on subsequent lights it is rendered with alpha-additive blending and depth writing disabled.
• For techniques that do not use shaders, fixed function OpenGL is used to render the model (see GLRenderer interface):
  • OpenGL state that is bound to material parameters is updated.
  • The texture set on the material is uploaded and bound. Currently only 1 texture is supported for fixed function techniques.
  • If the technique uses lighting, then OpenGL lighting state is updated based on the light list on the geometry, otherwise OpenGL lighting is disabled.
  • The mesh is uploaded and rendered.

Parameters:

geometry - The geometry to render

lights - Presorted and filtered light list to use for rendering

renderManager - The render manager requesting the rendering

render

public void render(Geometry geom,
                   RenderManager rm)

Called by RenderManager to render the geometry by using this material. Note that this version of the render method does not perform light filtering.

Parameters:

geom - The geometry to render

rm - The render manager requesting the rendering

write

public void write(JmeExporter ex)
           throws java.io.IOException

Specified by:

write in interface Savable

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

read

public void read(JmeImporter im)
          throws java.io.IOException

Specified by:

read in interface Savable

Throws:

java.io.IOException