com.jme3.material
Class Material

java.lang.Object
  extended by 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
static int SAVABLE_VERSION
           
 
Constructor Summary
Material()
          Do not use this constructor.
Material(AssetManager contentMan, java.lang.String defName)
           
Material(MaterialDef def)
           
 
Method Summary
 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.
 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 rm)
          Preloads this material for the given render manager.
 void read(JmeImporter im)
           
 void render(Geometry geom, RenderManager rm)
          Called by RenderManager to render the geometry by using this material.
protected  void renderMultipassLighting(Shader shader, Geometry g, RenderManager rm)
           
 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 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 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 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.
protected  void updateLightListUniforms(Shader shader, Geometry g, int numLights)
          Uploads the lights in the light list as two uniform arrays.

*
 void write(JmeExporter ex)
           
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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 uniqness.

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.


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 the 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.

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)

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

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

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

updateLightListUniforms

protected void updateLightListUniforms(Shader shader,
                                       Geometry g,
                                       int numLights)
Uploads the lights in the light list as two uniform arrays.

*

uniform vec4 g_LightColor[numLights];
// g_LightColor.rgb is the diffuse/specular color of the light.
// g_Lightcolor.a is the type of light, 0 = Directional, 1 = Point,
// 2 = Spot.

uniform vec4 g_LightPosition[numLights];
// g_LightPosition.xyz is the position of the light (for point lights)
// or the direction of the light (for directional lights).
// g_LightPosition.w is the inverse radius (1/r) of the light (for attenuation)


renderMultipassLighting

protected void renderMultipassLighting(Shader shader,
                                       Geometry g,
                                       RenderManager rm)

selectTechnique

public void selectTechnique(java.lang.String name,
                            RenderManager renderManager)
Select the technique to use for rendering this material.

If name is "Default", then one of the default techniques on the material will be selected. Otherwise, the named technique will be found in the material definition.

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 "Default" to select one of the default techniques.
renderManager - The render manager to query for capabilities.
Throws:
java.lang.IllegalArgumentException - If "Default" is passed and no default techniques are available on the material definition, or if a name is passed but there's no technique by that name.
java.lang.UnsupportedOperationException - If no candidate technique supports the system capabilities.

preload

public void preload(RenderManager rm)
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:
rm - The render manager to preload for

render

public void render(Geometry geom,
                   RenderManager rm)
Called by RenderManager to render the geometry by using this material.

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

read

public void read(JmeImporter im)
          throws java.io.IOException
Specified by:
read in interface Savable
Throws:
java.io.IOException