org.j3d.aviatrix3d
Class ShaderObject

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.ShaderObject

All Implemented Interfaces:

java.lang.Comparable, Renderable, ShaderSourceRenderable

public class ShaderObject
extends SceneGraphObject
implements ShaderSourceRenderable

Representation of a single Shader Object code that will form the final shader program.

Version:

$Revision: 1.17 $

Author:

Justin Couch

Field Summary

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Constructor Summary

ShaderObject(boolean isVertexShader)
Constructs a Shader Object of the specific kind.

Method Summary

void	clearSourceStrings() Clear the source string so that it is no longer needed.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
int	compareTo(ShaderObject so) Compares this object with the specified object for order.
void	compile() Mark this code as needing compilation at the next available oppourtunity.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
boolean	equals(ShaderObject so) Compares this object with the specified object to check for equivalence.
void	fetchLogInfo(javax.media.opengl.GL gl) The user requested log information about the shader object, so now is the time to fetch it.
java.lang.String	getLastInfoLog() Get the last fetched information log from this shader.
protected int	getShaderId(javax.media.opengl.GL gl) Request the object_id for this shader object so that it can be linked with the containing program.
java.lang.String[]	getSourceStrings() Get the currently set source strings.
void	initialize(javax.media.opengl.GL gl) Internal method to have the containing ShaderProgram request a compile of this object, if available.
boolean	isCompilationConfirmed(boolean enable) Check to see the current state of whether compilation should be confirmed.
boolean	isCompiled() Deprecated. Should not be called any more by client code.
protected boolean	isCompiled(javax.media.opengl.GL gl) Query the current compilation state for this code under the given GL context.
boolean	isVertexShader() Query to find out whether this is a fragment or vertex shader object encapsulation.
void	markForDeletion() Not implemented yet.
void	requestCompilationConfirmation(boolean enable) Have the class confirm whether or not the source successfully compiled.
void	requestInfoLog() Request that the shader fetch the last run log of this program.
void	setSourceStrings(java.lang.String[] str, int numValid) Set the program string that is to be registered by this shader.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

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

Methods inherited from class java.lang.Object

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

Constructor Detail

ShaderObject

public ShaderObject(boolean isVertexShader)

Constructs a Shader Object of the specific kind. Shader objects must be one of fragment or vertex. A value of true for the argument will set this object to be a vertex shader. A value of false, will make it a fragment shader.

Method Detail

setUpdateHandler

protected void setUpdateHandler(NodeUpdateHandler handler)

Set the scenegraph update handler for this node. It will notify all its children of the value. A null value will clear the current handler.

Overrides:

setUpdateHandler in class SceneGraphObject

Parameters:

handler - The instance to use as a handler

initialize

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

Internal method to have the containing ShaderProgram request a compile of this object, if available. If the code has already been compiled, do nothing.

Specified by:

initialize in interface ShaderSourceRenderable

Parameters:

gl - The gl context to draw with

fetchLogInfo

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

The user requested log information about the shader object, so now is the time to fetch it.

Specified by:

fetchLogInfo in interface ShaderSourceRenderable

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 objec 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

isVertexShader

public boolean isVertexShader()

Query to find out whether this is a fragment or vertex shader object encapsulation.

Returns:

true if this is a vertex shader, false for fragment

setSourceStrings

public void setSourceStrings(java.lang.String[] str,
                             int numValid)
                      throws InvalidWriteTimingException

Set the program string that is to be registered by this shader. Setting a value of null will be ignored, unless the object has not yet been compiled. A copy of the arrays is made.

Setting a new set of source strings does not automatically imply that the code should be recompiled at the next available oppourtunity. To force a recompilation (and thus any downstream effects like linking) you will also need to call the compile() method as well, after calling this one.

Parameters:

str - The new program string(s) to be registered or null

numValid - The number of valid strings to use from the array

Throws:

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

getSourceStrings

public java.lang.String[] getSourceStrings()

Get the currently set source strings. If none is set, or it has been cleared already, return null. This returns the reference to the internal array, so don't modify anything in the array.

Returns:

The current string or null

clearSourceStrings

public void clearSourceStrings()

Clear the source string so that it is no longer needed. Once the source has been compiled by OpenGL (by calling glCompileShader), the string is no longer needed by the application level code. It can be safely removed with no harmful effects to the application.

Throws:

InvalidWriteTimingException - An attempt was made to clear outside of the NodeUpdateListener data changed callback method

compile

public void compile()

Mark this code as needing compilation at the next available oppourtunity. This will queue the shader up to be compiled at the next frame render cycle.

requestInfoLog

public void requestInfoLog()
                    throws InvalidWriteTimingException

Request that the shader fetch the last run log of this program. This will queue up a request for the next frame, which will find the log string. The result of this will be found in the getLastInfoLog() method. If this object is not part of a live scene graph, the request is ignored.

Throws:

InvalidWriteTimingException - An attempt was made to request this outside of the updateSceneGraph() call

getLastInfoLog

public java.lang.String getLastInfoLog()

Get the last fetched information log from this shader. If the log has not yet been fetched then null is returned.

Returns:

The last info log string or null

isCompiled

public boolean isCompiled()

Deprecated. Should not be called any more by client code.

Query the current compilation state. An object is compiled if the current source string has undergone the OpenGL compilation process and was successful. It is not compiled if the previous string was compiled and then a new set of source strings has been set since and the code has been marked as needing compilation.

Returns:

true if the code is compiled and no changes

isCompiled

protected boolean isCompiled(javax.media.opengl.GL gl)

Query the current compilation state for this code under the given GL context. An object is compiled if the current source string has undergone the OpenGL compilation process and was successful. It is not compiled if the previous string was compiled and then a new set of source strings has been set since and the code has been marked as needing compilation.

Parameters:

gl - The GL context to check compilation on

Returns:

true if the code is compiled and no changes

markForDeletion

public void markForDeletion()

Not implemented yet.

requestCompilationConfirmation

public void requestCompilationConfirmation(boolean enable)

Have the class confirm whether or not the source successfully compiled. The standard OpenGL calls are non-blocking when a compile takes place. It is not known whether the compile has succeeded until some indeterminant time later. That is the normal process this class takes. If the end user wants to first comfirm that the compile succeeds before returning to executing the rest of the render loop, then set this flag. In doing so, expect performance penalties for the frame that does the work of compiling this. Individually, this may not be significant, but with a number of objects to compile and shader programs to link in a single frame could cause a large pause.

Parameters:

enable - true if the code should confirm compilation succeeds

isCompilationConfirmed

public boolean isCompilationConfirmed(boolean enable)

Check to see the current state of whether compilation should be confirmed.

Returns:

true if the confirmation needs to take place

getShaderId

protected int getShaderId(javax.media.opengl.GL gl)

Request the object_id for this shader object so that it can be linked with the containing program.

Parameters:

gl - The GL context to used for the caller

Returns:

The object_id of the compiled source or 0 if not compiled yet

compareTo

public int compareTo(ShaderObject so)

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:

so - The object instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(ShaderObject so)

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

Parameters:

so - The object instance to be compared

Returns:

true if the objects represent identical values