org.j3d.aviatrix3d
Class Material

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.NodeComponent
          org.j3d.aviatrix3d.Material

All Implemented Interfaces:

java.lang.Comparable, ObjectRenderable, Renderable, TransparentObjectRenderable, TransparentRenderable

public class Material
extends NodeComponent
implements TransparentObjectRenderable

Describes the material properties of an object.

Materials may be either single or double sided for an object. By default, this class sets up for single-sided rendering. All material values are sent to OpenGL as GL_FRONT_AND_BACK for the target unless otherwise specified. Whatever these settings, the values will not be used unless the two-sided lighting value is also enabled on the PolygonAttributes that accompanies this material. Without that turned on, the back-face material values defined here will not be used by OpenGL.

Because the material node is used almost everywhere in scene graphs, and two-sided material handling uses twice the amount of memory, we've made some special rules about using it in order to reduce memory footprint. As the use of separate front and back face colours are relatively rare in use, we don't allocate the internal memory for their storage unless the flag is turned on. This then forces another interaction rule. The memory structures won't be in place unless the flag is turned on, so if you attempted to read or write to them when the flag is turned off, NullPointerExceptions will be generated all over the place. To prevent this, we perform a check before every back-face access to make sure that the flag is currently set, and if not, will issue our own exception IllegalStateException.

The default values for this class mirror the OpenGL defaults:

• ambient color (0.2, 0.2, 0.2)
• emisive color (0.0, 0.0, 0.0)
• diffuse color (0.8, 0.8, 0.8)
• specular color (0, 0, 0)
• shininess 0.2
• transparency 1
• use lighting true
• separated back face colours false
• use colorMaterial false
• colorTarget AMBIENT_AND_DIFFUSE_TARGET
• backColorTarget AMBIENT_AND_DIFFUSE_TARGET

When combining transparency and color material handling, we need to control what gets blended. Sometimes the incoming vertex values have 4 component color, sometimes 3. Sometimes you'd like the material's transparency to override the externally provided color's alpha value, and others not. To deal with this situation, a separate flag is enabled allowing you to control whether the transparency should be treated separately to the color material. If this is set to true, the transparency is set up as a blending factor with the OpenGL blending API - there is no need to make use of a separate BlendAttributes object for this. If you also happen to provide a BlendAttributes instance to the containing appearance, that will override what happens internally to this class.

Internationalisation Resource Names

• wrongColorMaterialTargetMsg: Error message when a non _TARGET constant is used to set the target for the colour material.
• backfaceWriteMsg: Error message when attempting to change a backface field with that ability not enabled
• backfaceReadMsg: Error message when attempting to read a backface field with that ability not enabled
• shininessRangeMsg: Error message when the shininess is not [0,1]
• transparencyRangeMsg: Error message when the transparency is not [0,1]

Version:

$Revision: 1.47 $

Author:

Justin Couch, Alan Hudson

Field Summary

static int	AMBIENT_AND_DIFFUSE_TARGET Set the color material target as the ambient and diffuse light component.
static int	AMBIENT_TARGET Set the color material target as the ambient light component
static int	DIFFUSE_TARGET Set the color material target as the diffuse light component
static int	EMISSIVE_TARGET Set the color material target as the emissive light component
static int	SPECULAR_TARGET Set the color material target as the specular light component

Fields inherited from class org.j3d.aviatrix3d.NodeComponent

lastParent, liveCount, parentList

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Constructor Summary

Material()
Constructs a material with default values.

Material(float[] ambientColor, float[] emissiveColor, float[] diffuseColor, float[] specularColor, float shininess, float transparency)
Create a new material with all the colours specified.

Method Summary

int	compareTo(Material mat) Compares this object with the specified object for order.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
boolean	equals(Material mat) Compares this object with the specified object to check for equivalence.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
void	getAmbientColor(float[] col) Get the current value of the ambient color for the front or combined faces.
void	getBackAmbientColor(float[] col) Get the current value of the ambient color for the back face.
int	getBackColorMaterialTarget() Get the amount of colorTarget for the back face.
void	getBackDiffuseColor(float[] col) Get the current value of the diffuse color for the back face.
void	getBackEmissiveColor(float[] col) Get the current value of the emissive color for the back face.
float	getBackShininess() Get the current shininess value for the back face.
void	getBackSpecularColor(float[] col) Get the current value of the specular color for the back face.
float	getBackTransparency() Get the amount of transparency for the back face.
int	getColorMaterialTarget() Get the current target fr color materials for the front or combined faces.
void	getDiffuseColor(float[] col) Get the current value of the diffuse color of the front and combined faces.
void	getEmissiveColor(float[] col) Get the current value of the emissive color for the front or combined faces.
float	getShininess() Get the current shininess value for the front or combined faces.
void	getSpecularColor(float[] col) Get the current value of the specular color for the front or combined faces.
float	getTransparency() Get the amount of transparency for the front or combined faces.
boolean	hasTransparency() Ask the texture if it has any transparency values.
boolean	isBlendingAvailable() Check to see if the code has detected the lack of the imaging subset.
boolean	isColorMaterialEnabled() Get the current flag defining whether color material lighting is currently enabled or not for this object.
boolean	isLightingEnabled() Get the current flag defining whether lighting is currently enabled or not for this object.
boolean	isSeparateBackfaceEnabled() Get the current state of whether separate back-face colour values are in use.
boolean	isSeparateTransparencyEnabled() Get the current flag defining whether separate transparency and color material lighting is currently enabled or not for this object.
void	postRender(javax.media.opengl.GL gl) Restore all openGL state to the given drawable
void	render(javax.media.opengl.GL gl) Issue ogl commands needed for this component
void	setAmbientColor(float[] col) Set the ambient color to the new value for the front-face and combined values.
void	setBackAmbientColor(float[] col) Set the ambient color to the new value for the back face value.
void	setBackColorMaterialTarget(int target) Set the amount of colorTarget to be used for this material for the back face value.
void	setBackDiffuseColor(float[] col) Set the diffuse color to the new value for the back face value.
void	setBackEmissiveColor(float[] col) Set the emissive color to the new value for the back face value.
void	setBackShininess(float s) Set the shininess factor for the back face value.
void	setBackSpecularColor(float[] col) Set the specular color to the new value for the back face value.
void	setBackTransparency(float transparency) Set the amount of transparency to be used for this material for the back face value.
void	setColorMaterialEnabled(boolean state) Set the flag that enables or disables color material lighting effects on any geometry using this material.
void	setColorMaterialTarget(int target) Set the amount of colorTarget to be used for this material for the front or combined faces.
void	setDiffuseColor(float[] col) Set the diffuse color to the new value for the front and combined faces.
void	setEmissiveColor(float[] col) Set the emissive color to the new value for the front-face and combined values.
void	setLightingEnabled(boolean state) Set the flag that enables or disables lighting on any geometry using this material.
void	setSeparateBackfaceEnabled(boolean state) Set the flag that enables or disables separate material lighting values on any geometry using this material.
void	setSeparateTransparencyEnabled(boolean state) Set the flag that enables or disables separate transparency handling from the color material values.
void	setShininess(float s) Set the shininess factor for the front or combined faces.
void	setSpecularColor(float[] col) Set the specular color to the new value for the front-face and combined values.
void	setTransparency(float transparency) Set the amount of transparency to be used for this material for the front or combined faces.

Methods inherited from class org.j3d.aviatrix3d.NodeComponent

addParent, getParents, numParents, removeParent

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicChild, checkForCyclicParent, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setLive, setUpdateHandler, setUserData

Methods inherited from class java.lang.Object

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

Field Detail

AMBIENT_TARGET

public static final int AMBIENT_TARGET

Set the color material target as the ambient light component

See Also:

Constant Field Values

DIFFUSE_TARGET

public static final int DIFFUSE_TARGET

Set the color material target as the diffuse light component

See Also:

Constant Field Values

SPECULAR_TARGET

public static final int SPECULAR_TARGET

Set the color material target as the specular light component

See Also:

Constant Field Values

EMISSIVE_TARGET

public static final int EMISSIVE_TARGET

Set the color material target as the emissive light component

See Also:

Constant Field Values

AMBIENT_AND_DIFFUSE_TARGET

public static final int AMBIENT_AND_DIFFUSE_TARGET

Set the color material target as the ambient and diffuse light component. This is the default setting if nothing is explicitly set by the user.

See Also:

Constant Field Values

Constructor Detail

Material

public Material()

Constructs a material with default values.

 ambient color = (0.2, 0.2, 0.2)
 emisive color = (0.0, 0.0, 0.0)
 diffuse color = (0.8, 0.8, 0.8)
 specular color = (0, 0, 0)
 shininess = 0.2
 transparency = 1
 

Material

public Material(float[] ambientColor,
                float[] emissiveColor,
                float[] diffuseColor,
                float[] specularColor,
                float shininess,
                float transparency)

Create a new material with all the colours specified.

Parameters:

ambientColor -

emissiveColor -

diffuseColor -

specularColor -

shininess - The shininess factor value

transparency - A transparency value between 0 and 1

Method Detail

hasTransparency

public boolean hasTransparency()

Ask the texture if it has any transparency values. The implementation should determine this from it's internal set of state, such as looking at the texture formats etc to see if they include an alpha channel

Specified by:

hasTransparency in interface TransparentRenderable

Returns:

true if any form of non-opaque rendering is defined

render

public void render(javax.media.opengl.GL gl)

Issue ogl commands needed for this component

Specified by:

render in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

postRender

public void postRender(javax.media.opengl.GL gl)

Restore all openGL state to the given drawable

Specified by:

postRender in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

compareTo

public int compareTo(java.lang.Object o)
              throws java.lang.ClassCastException

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - The object to be compared

Returns:

-1, 0 or 1 depending on order

Throws:

java.lang.ClassCastException - The specified object's type prevents it from being compared to this Object

equals

public boolean equals(java.lang.Object o)

Compare this object for equality to the given object.

Specified by:

equals in interface Renderable

Overrides:

equals in class java.lang.Object

Parameters:

o - The object to be compared

Returns:

True if these represent the same values

setShininess

public void setShininess(float s)
                  throws InvalidWriteTimingException,
                         java.lang.IllegalArgumentException

Set the shininess factor for the front or combined faces. The shininess should be a value between 0 and 1.

Parameters:

s - The shininess factor value

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalArgumentException - The shininess value is outside the range of [0,1]

setBackShininess

public void setBackShininess(float s)
                      throws InvalidWriteTimingException,
                             java.lang.IllegalStateException

Set the shininess factor for the back face value. The shininess should be a value between 0 and 1.

Parameters:

s - The shininess factor value

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getShininess

public float getShininess()

Get the current shininess value for the front or combined faces.

Returns:

a number between 0 and 1

getBackShininess

public float getBackShininess()
                       throws java.lang.IllegalStateException

Get the current shininess value for the back face.

Returns:

a number between 0 and 1

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setDiffuseColor

public void setDiffuseColor(float[] col)
                     throws InvalidWriteTimingException

Set the diffuse color to the new value for the front and combined faces.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

setBackDiffuseColor

public void setBackDiffuseColor(float[] col)
                         throws InvalidWriteTimingException,
                                java.lang.IllegalStateException

Set the diffuse color to the new value for the back face value.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getDiffuseColor

public void getDiffuseColor(float[] col)

Get the current value of the diffuse color of the front and combined faces. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

getBackDiffuseColor

public void getBackDiffuseColor(float[] col)
                         throws java.lang.IllegalStateException

Get the current value of the diffuse color for the back face. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setSpecularColor

public void setSpecularColor(float[] col)
                      throws InvalidWriteTimingException

Set the specular color to the new value for the front-face and combined values.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

setBackSpecularColor

public void setBackSpecularColor(float[] col)
                          throws InvalidWriteTimingException,
                                 java.lang.IllegalStateException

Set the specular color to the new value for the back face value.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getSpecularColor

public void getSpecularColor(float[] col)

Get the current value of the specular color for the front or combined faces. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

getBackSpecularColor

public void getBackSpecularColor(float[] col)
                          throws java.lang.IllegalStateException

Get the current value of the specular color for the back face. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setEmissiveColor

public void setEmissiveColor(float[] col)
                      throws InvalidWriteTimingException

Set the emissive color to the new value for the front-face and combined values.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

setBackEmissiveColor

public void setBackEmissiveColor(float[] col)
                          throws InvalidWriteTimingException,
                                 java.lang.IllegalStateException

Set the emissive color to the new value for the back face value.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getEmissiveColor

public void getEmissiveColor(float[] col)

Get the current value of the emissive color for the front or combined faces. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

getBackEmissiveColor

public void getBackEmissiveColor(float[] col)
                          throws java.lang.IllegalStateException

Get the current value of the emissive color for the back face. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setAmbientColor

public void setAmbientColor(float[] col)
                     throws InvalidWriteTimingException

Set the ambient color to the new value for the front-face and combined values.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

setBackAmbientColor

public void setBackAmbientColor(float[] col)
                         throws InvalidWriteTimingException,
                                java.lang.IllegalStateException

Set the ambient color to the new value for the back face value.

Parameters:

col - The new colour to use

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getAmbientColor

public void getAmbientColor(float[] col)

Get the current value of the ambient color for the front or combined faces. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into.

getBackAmbientColor

public void getBackAmbientColor(float[] col)
                         throws java.lang.IllegalStateException

Get the current value of the ambient color for the back face. The array should be at least length 3 or 4.

Parameters:

col - The array to copy the values into.

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setTransparency

public void setTransparency(float transparency)
                     throws InvalidWriteTimingException

Set the amount of transparency to be used for this material for the front or combined faces. A value of 1 is fully opaque and 0 is totally transparent.

Parameters:

transparency - A value between 0 and 1

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

setBackTransparency

public void setBackTransparency(float transparency)
                         throws InvalidWriteTimingException,
                                java.lang.IllegalStateException

Set the amount of transparency to be used for this material for the back face value. A value of 1 is fully opaque and 0 is totally transparent.

Parameters:

transparency - A value between 0 and 1

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data change callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

getTransparency

public float getTransparency()

Get the amount of transparency for the front or combined faces. A value of 1 is fully opaque and 0 is totally transparent.

Returns:

The current transparency value

getBackTransparency

public float getBackTransparency()
                          throws java.lang.IllegalStateException

Get the amount of transparency for the back face. A value of 1 is fully opaque and 0 is totally transparent.

Returns:

The current transparency value

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setLightingEnabled

public void setLightingEnabled(boolean state)
                        throws InvalidWriteTimingException

Set the flag that enables or disables lighting on any geometry using this material.

Parameters:

state - true if lighting should be used

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

isLightingEnabled

public boolean isLightingEnabled()

Get the current flag defining whether lighting is currently enabled or not for this object.

Returns:

true if lighting is currently enabled for this material

setSeparateTransparencyEnabled

public void setSeparateTransparencyEnabled(boolean state)
                                    throws InvalidWriteTimingException

Set the flag that enables or disables separate transparency handling from the color material values.

Parameters:

state - true if separating transparency from color material

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

isSeparateTransparencyEnabled

public boolean isSeparateTransparencyEnabled()

Get the current flag defining whether separate transparency and color material lighting is currently enabled or not for this object.

Returns:

true if it currently enabled for this material

setColorMaterialEnabled

public void setColorMaterialEnabled(boolean state)
                             throws InvalidWriteTimingException

Set the flag that enables or disables color material lighting effects on any geometry using this material.

Parameters:

state - true if color material should be used

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

isColorMaterialEnabled

public boolean isColorMaterialEnabled()

Get the current flag defining whether color material lighting is currently enabled or not for this object.

Returns:

true if it currently enabled for this material

setColorMaterialTarget

public void setColorMaterialTarget(int target)
                            throws InvalidWriteTimingException,
                                   java.lang.IllegalArgumentException

Set the amount of colorTarget to be used for this material for the front or combined faces.

Parameters:

target - One of the _TARGET constant values

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

java.lang.IllegalArgumentException - The target was not one of the _TARGET values

setBackColorMaterialTarget

public void setBackColorMaterialTarget(int target)
                                throws InvalidWriteTimingException,
                                       java.lang.IllegalStateException,
                                       java.lang.IllegalArgumentException

Set the amount of colorTarget to be used for this material for the back face value.

Parameters:

target - One of the _TARGET constant values

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

java.lang.IllegalStateException - Attempting to write to the value when the separate backface flag is not turned on.

java.lang.IllegalArgumentException - The target was not one of the _TARGET values

getColorMaterialTarget

public int getColorMaterialTarget()

Get the current target fr color materials for the front or combined faces.

Returns:

One of the _TARGET values for the front face

getBackColorMaterialTarget

public int getBackColorMaterialTarget()
                               throws java.lang.IllegalStateException

Get the amount of colorTarget for the back face.

Returns:

One of the _TARGET values for the back face

Throws:

java.lang.IllegalStateException - Attempting to read the value when the separate backface flag is not turned on.

setSeparateBackfaceEnabled

public void setSeparateBackfaceEnabled(boolean state)
                                throws InvalidWriteTimingException

Set the flag that enables or disables separate material lighting values on any geometry using this material. Whether these values are actually used or not is dependent on the accompanying * PolygonAttributes class.

If this is enabling the separate back face values, all the existing front faces are copied into the back face value.

Parameters:

state - true if two sided colours should be used

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener callback method

isSeparateBackfaceEnabled

public boolean isSeparateBackfaceEnabled()

Get the current state of whether separate back-face colour values are in use.

Returns:

true if separate back material values are currently enabled for this material

compareTo

public int compareTo(Material mat)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

mat - The material to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(Material mat)

Compares this object with the specified object to check for equivalence.

Parameters:

mat - The material to be compared

Returns:

true if the objects represent identical values

isBlendingAvailable

public boolean isBlendingAvailable()

Check to see if the code has detected the lack of the imaging subset. This call will always return false until the first time an instance of this class has been rendered. After that time, the real answer is known.

Returns:

true if the blending operations are allowed