org.j3d.aviatrix3d
Class ShaderArguments

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

All Implemented Interfaces:

java.lang.Comparable, ComponentRenderable, Renderable

public class ShaderArguments
extends NodeComponent
implements ComponentRenderable

Representation of a set of arguments (uniform variables) that can be passed to a shader program.

Arguments are separate from the program so that the same program can be used amongst a number of primitives, but with different setup information if needed.

If changing the value of an existing argument, no consistency checks are made on whether the old type and new type match.

The external data passed to the ComponentRenderable calls shall be an Integer instance that represents the GL program identifier generated for the shader program this instance is working with.

Internationalisation Resource Names

• invalidDataSizeMsg: Error message when the user tries to set a uniform data size that is not 1, 2, 3 or 4.
• invalidMatrixSizeMsg: Error message when the user tries to set a uniform matrix size that is not 2, 3 or 4.
• invalidCountMsg: Error message when the user tries to set a uniform matrix size that is not 2, 3 or 4.
• notIntMsg: Error message when trying set a float to an int type
• notFloatMsg: Error message when trying set an int to an float type

Version:

$Revision: 1.19 $

Author:

Justin Couch

Field Summary

static int	FLOAT_UNIFORM_TYPE The uniform data type is a float array
static int	INT_UNIFORM_TYPE The uniform data type is an int array
static int	MATRIX_UNIFORM_TYPE The uniform data type is a matrix array
static int	SAMPLER_UNIFORM_TYPE The uniform data type is an int array

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

ShaderArguments()
Constructs a Shader with default values.

Method Summary

int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
int	compareTo(ShaderArguments 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(ShaderArguments sh) Compares this object with the specified object to check for equivalence.
void	getUniform(java.lang.String name, float[] data) Get the value of a uniform using a float array.
void	getUniform(java.lang.String name, int[] data) Get the value of a uniform using an int array.
int	getUniformCount(java.lang.String name) Get the number of items declared for a uniform value.
int	getUniformSize(java.lang.String name) Get the data vector size for the given uniform name.
int	getUniformType(java.lang.String name) Get the data type of this uniform.
void	postRender(javax.media.opengl.GL gl, java.lang.Object programId)
void	removeUniform(java.lang.String name) Remove the given uniform name from the settable argument list.
void	render(javax.media.opengl.GL gl, java.lang.Object programId) Assign the uniform values to the shader now.
void	setUniform(java.lang.String name, int size, float[] data, int count) Set the value of an float array uniform variable.
void	setUniform(java.lang.String name, int size, int[] data, int count) Set the value of an int array uniform variable.
void	setUniformMatrix(java.lang.String name, int size, float[] data, int count, boolean columnMajor) Set the value of an matrix uniform variable.
void	setUniformSampler(java.lang.String name, int textureUnitId) Convenience method to set the uniform name as a sampler for the given texture unit number.

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

INT_UNIFORM_TYPE

public static final int INT_UNIFORM_TYPE

The uniform data type is an int array

See Also:

Constant Field Values

FLOAT_UNIFORM_TYPE

public static final int FLOAT_UNIFORM_TYPE

The uniform data type is a float array

See Also:

Constant Field Values

MATRIX_UNIFORM_TYPE

public static final int MATRIX_UNIFORM_TYPE

The uniform data type is a matrix array

See Also:

Constant Field Values

SAMPLER_UNIFORM_TYPE

public static final int SAMPLER_UNIFORM_TYPE

The uniform data type is an int array

See Also:

Constant Field Values

Constructor Detail

ShaderArguments

public ShaderArguments()

Constructs a Shader with default values.

Method Detail

render

public void render(javax.media.opengl.GL gl,
                   java.lang.Object programId)

Assign the uniform values to the shader now.

Specified by:

render in interface ComponentRenderable

Parameters:

gl - The GL context to write the values through

programId - the ID of the program to make GL calls with

postRender

public void postRender(javax.media.opengl.GL gl,
                       java.lang.Object programId)

Specified by:

postRender in interface ComponentRenderable

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

setUniform

public void setUniform(java.lang.String name,
                       int size,
                       float[] data,
                       int count)
                throws InvalidWriteTimingException

Set the value of an float array uniform variable. This value will be set the next time the shader is used. The array of provided data should be at least as long as the size given.

Parameters:

name - The name of the uniform to be set

size - A value of 1, 2, 3 or 4 depending on how many items

data - The value(s) to be set

count - The number of the values to set

Throws:

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

setUniform

public void setUniform(java.lang.String name,
                       int size,
                       int[] data,
                       int count)
                throws InvalidWriteTimingException

Set the value of an int array uniform variable. This value will be set the next time the shader is used. The array of provided data should be at least as long as the size given.

Parameters:

name - The name of the uniform to be set

size - A value of 1, 2, 3 or 4 depending on how many items

data - The value(s) to be set

count - The number of the values to set

Throws:

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

setUniformMatrix

public void setUniformMatrix(java.lang.String name,
                             int size,
                             float[] data,
                             int count,
                             boolean columnMajor)
                      throws InvalidWriteTimingException

Set the value of an matrix uniform variable. This value will be set the next time the shader is used. The array of provided data should must be at least the size squared. The matrix values may be presented in either column or row-major order in the array with the boolean flag used to indicate which order to use when talking to OpenGL.

Parameters:

name - The name of the uniform to be set

size - A value of 2, 3 or 4 depending on the matrix size (eg 2x2)

data - The value(s) to be set

count - The number of the values to set

Throws:

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

setUniformSampler

public void setUniformSampler(java.lang.String name,
                              int textureUnitId)
                       throws InvalidWriteTimingException

Convenience method to set the uniform name as a sampler for the given texture unit number.

Parameters:

name - The name of the uniform to be set

textureUnitId - The ID of the texture unit to assign to the sampler

Throws:

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

getUniformType

public int getUniformType(java.lang.String name)

Get the data type of this uniform. Returns the basic data type - int, float, matrix or sampler. Use in combination with the other getter methods to work out the real data size for any data fetching.

If the uniform name provided has not been set yet, this will return -1.

Parameters:

name - The name of the uniform to fetch the size of

Returns:

One of the _UNIFORM_TYPE values or -1

getUniformSize

public int getUniformSize(java.lang.String name)

Get the data vector size for the given uniform name. For all the methods that need a size parameter, this will return the value set there. If the uniform name is used on a sampler (texture ID), this will always return 1. If the uniform represents a matrix type, then this still return 2, 3 or 4. Use the getUniformType(String) method to determine the underlying data type this represents.

If the uniform name provided has not been set yet, this will return -1.

Parameters:

name - The name of the uniform to fetch the size of

Returns:

A value of 1, 2, 3 or 4 depending on how many items, or -1

getUniformCount

public int getUniformCount(java.lang.String name)

Get the number of items declared for a uniform value. This returns the number of elements in the array. For samplers, this always returns 1.

Parameters:

name - The name of the uniform to be set

Returns:

A value greater than or equal to zero

getUniform

public void getUniform(java.lang.String name,
                       float[] data)
                throws InvalidDataTypeException

Get the value of a uniform using a float array. Can be used to fetch either the matrix types or float[] values. Type conversions for the integer or sampler types are not performed and if requested an exception will be generated. To work out if this type is a float-based type, use getUniformType(String).

The provided array must be big enough to contain all of the data. The length of the array must at least be:

int size = getUniformSize(name) * getUniformCount(name) * (getUniformType(name) == MATRIX_UNIFORM_TYPE ? getUniformSize(name) : 1);

If the uniform name is not known, nothing happens.

Parameters:

name - The name of the uniform to be set

data - An array to copy values to

Throws:

InvalidDataTypeException - Attempt to fetch an int type

java.lang.ArrayIndexOutOfBoundsException - The provided array is too short

getUniform

public void getUniform(java.lang.String name,
                       int[] data)
                throws InvalidDataTypeException

Get the value of a uniform using an int array. Can be used to fetch either the int[] types or sampler values. Type conversions for the float or matrix types are not performed and if requested an exception will be generated. To work out if this type is a int-based type, use getUniformType(String).

The provided array must be big enough to contain all of the data. The length of the array must at least be:

int size = getUniformSize(name) * getUniformCount(name);

If the uniform name is not known, nothing happens.

Parameters:

name - The name of the uniform to be set

data - An array to copy values to

Throws:

InvalidDataTypeException - Attempt to fetch an int type

java.lang.ArrayIndexOutOfBoundsException - The provided array is too short

removeUniform

public void removeUniform(java.lang.String name)
                   throws InvalidWriteTimingException

Remove the given uniform name from the settable argument list. If the name isn't previously set, it silently ignores the request.

Parameters:

name - The name of the uniform variable to be removed.

Throws:

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

compareTo

public int compareTo(ShaderArguments 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 argument instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(ShaderArguments sh)

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

Parameters:

sh - The shader instance to be compared

Returns:

true if the objects represent identical values