org.j3d.aviatrix3d
Class ShaderProgram

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

All Implemented Interfaces:

java.lang.Comparable, DeletableRenderable, ObjectRenderable, Renderable, ShaderComponentRenderable, ShaderSourceRenderable

public class ShaderProgram
extends NodeComponent
implements DeletableRenderable, ShaderSourceRenderable, ShaderComponentRenderable

Representation of a complete GLSLang shader program.

The behaviour of this object mirrors that of the OpenGL specification. To create a program, you have to collect a number of objects, have them compiled, then assemble and link the objects into a single application. In addition, any runtime structural changes to the program will not take effect until the next time that the program is (re)linked.

A program is separate from the arguments that can be passed to it. This class represents the raw shader program that can be called upon to do some processing work. Vertex attribute values are set through the calls in the VertexGeometry class. Uniform values are defined by the accompanying ShaderArguments class. This allows a single instance of this program to be created, yet used in different parts of the scene graph with different settings (eg a marble shader that has different colour combos).

Version:

$Revision: 2.23 $

Author:

Justin Couch

Field Summary

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

Fields inherited from interface org.j3d.aviatrix3d.rendering.ShaderComponentRenderable

FRAGMENT_SHADER, GEOMETRY_SHADER, PROGRAM_SHADER, VERTEX_SHADER

Constructor Summary

ShaderProgram()
Constructs a Shader program with nothing set.

Method Summary

void	addShaderObject(ShaderObject obj) Add a shader object to this program.
void	bindAttributeName(java.lang.String name, int index) Bind the given attribute name to a specific index.
void	cleanup(javax.media.opengl.GL gl) Cleanup the object now for the given GL context.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
int	compareTo(ShaderProgram sh) Compares this object with the specified object for order.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
boolean	equals(ShaderProgram sh) 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.
int	getComponentType() Get the type of component this state represents.
java.lang.String	getLastInfoLog() Get the last fetched information log from this shader.
int	getNumShaderObjects() Get the number of currently registered shader objects.
int	getProgramId(javax.media.opengl.GL gl) Fetch the ID handle for this program for the given context.
void	getShaderObjects(ShaderObject[] objects) Get the current shader objects.
void	initialize(javax.media.opengl.GL gl) Link this shader now.
boolean	isLinkConfirmed() Check to see the current state of whether compilation should be confirmed.
boolean	isValid(javax.media.opengl.GL gl) Check to see if this is linked for the given GL context.
void	link() Request that the shader link at the next available oppourtunity.
void	postRender(javax.media.opengl.GL gl) Restore all openGL state to the given drawable
void	reinitialize(javax.media.opengl.GL gl) Re-initialise this shader because the underlying GL context has changed.
void	removeShaderObject(ShaderObject obj) Remove the shader object from this program.
void	render(javax.media.opengl.GL gl) Issue ogl commands needed for this component
void	requestInfoLog() Request that the shader fetch the last run log of this program.
void	requestLinkConfirmation(boolean enable) Have the class confirm whether or not the source successfully compiled.
protected void	setLive(boolean state) Notification that this object is live now.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.

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, setUserData

Methods inherited from class java.lang.Object

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

Constructor Detail

ShaderProgram

public ShaderProgram()

Constructs a Shader program with nothing set.

Method Detail

getComponentType

public int getComponentType()

Get the type of component this state represents.

Specified by:

getComponentType in interface ShaderComponentRenderable

Returns:

One of the _SHADER constants

isValid

public boolean isValid(javax.media.opengl.GL gl)

Check to see if this is linked for the given GL context. This tests to see if a valid program ID has already been assigned, indicating that at least an internal link(gl) call has been made.

Specified by:

isValid in interface ShaderComponentRenderable

Parameters:

gl - The GL context to test for linkage against

Returns:

true if there is a valid ID to work with

getProgramId

public int getProgramId(javax.media.opengl.GL gl)

Fetch the ID handle for this program for the given context.

Specified by:

getProgramId in interface ShaderComponentRenderable

Parameters:

gl - The GL context to get the ID for

Returns:

The ID value or 0 if none

reinitialize

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

Re-initialise this shader because the underlying GL context has changed. This should also reinitialise any resources that it is dependent on.

Specified by:

reinitialize in interface ShaderComponentRenderable

Parameters:

gl - The GL context to reinitialise with

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

initialize

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

Link this shader now. If any uncompiled shader objects are found, they are automatically compiled and added to the list to be linked in. Old objects that used to be attached to the program object are detached, new objects attached, attribute names are bound, and finally everything is linked.

Specified by:

initialize in interface ShaderSourceRenderable

Parameters:

gl - The GL context to use to compile the code 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

cleanup

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

Cleanup the object now for the given GL context.

Specified by:

cleanup in interface DeletableRenderable

Parameters:

gl - The gl context to draw with

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

setLive

protected void setLive(boolean state)

Notification that this object is live now. Overridden to make sure that the live state of the nodes represents the same state as the parent scene graph.

Overrides:

setLive in class SceneGraphObject

Parameters:

state - true if this should be marked as live now

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

addShaderObject

public void addShaderObject(ShaderObject obj)
                     throws InvalidWriteTimingException

Add a shader object to this program. If the shader object is already registered, the request is ignored. The object does not need to be initialised or compiled at this point.

Parameters:

obj - The object instance to add

Throws:

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

removeShaderObject

public void removeShaderObject(ShaderObject obj)
                        throws InvalidWriteTimingException

Remove the shader object from this program. If ths shader object is not already registered the request is ignored.

Parameters:

obj - The object instance to remove

Throws:

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

getNumShaderObjects

public int getNumShaderObjects()

Get the number of currently registered shader objects.

Returns:

A value >= 0

getShaderObjects

public void getShaderObjects(ShaderObject[] objects)

Get the current shader objects. The array must be at least getNumShaderObjects() in length.

Parameters:

objects - An array to copy values into

link

public void link()
          throws InvalidWriteTimingException

Request that the shader link at the next available oppourtunity. If any of the used ShaderObjects have not yet been compiled, they will be compiled just before linking.

Throws:

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

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

bindAttributeName

public void bindAttributeName(java.lang.String name,
                              int index)
                       throws InvalidWriteTimingException

Bind the given attribute name to a specific index. This index can then be used in the setAttributes() methods of VertexGeometry. Note that, in accordance with the rules of OpenGL, this binding will not take place until the next link() call.

Parameters:

name - The attribute name to bind the index to

index - The index value for the attrib name to correspond to the vertex attribute values

Throws:

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

requestLinkConfirmation

public void requestLinkConfirmation(boolean enable)
                             throws InvalidWriteTimingException

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

Throws:

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

isLinkConfirmed

public boolean isLinkConfirmed()

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

Returns:

true if the confirmation needs to take place

compareTo

public int compareTo(ShaderProgram sh)

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:

sh - The program instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(ShaderProgram sh)

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

Parameters:

sh - The program instance to be compared

Returns:

true if the objects represent identical values