Shaders in Java 3D^TM 1.4

Introduction and pointer to discussion forum

If you wandered over here looking for a completed draft programmable shading specification for Java 3D^TM 1.4 that you can review, you are in the wrong place; or more accurately, the right place at the wrong time. Come back in about 2 months and things should be in state where you can review a fairly complete draft specification. If, on the other hand, you'd like to help us define and evolve the programmable shading API in Java 3D 1.4, please read on.

This is a very rough first draft of what we are thinking in terms of programmable shader support in Java 3D 1.4. As we mentioned at JavaOne, we plan to do the 1.4 API specification under the auspices of the Java Community Process (JCP). However, we very much want to involve the larger community in API discussions for programmable shaders, so please join in the discussion.

We have created a thread on the Java 3D discussion forum for discussing Java 3D Programmable Shaders. Feel free to post your comments on our ideas, or post some ideas of your own.

Class Hierarchy for Shader Objects

The proposed class hierarchy for programmable shaders in Java 3D is:

• Abstract shader base classes:

public abstract class ShaderProgram extends NodeComponent
public abstract class Shader extends NodeComponent

• Concrete GL2 shader classes:

public class GL2ShaderProgram extends ShaderProgram
    method: {add/remove/get}Shader(GL2Shader) // set of shader objs
    method: {add/remove}ErrorListener(GL2ErrorListener)
    method: validate(Canvas3D) ???

public abstract class GL2Shader extends Shader
    public class GL2VertexShader extends GL2Shader
	method: set/getShaderSource(String)
	method: validate(Canvas3D) ???
    public class GL2FragmentShader extends GL2Shader
	method: set/getShaderSource(String)
	method: validate(Canvas3D) ???

• Concrete Cg shader classes:

public class CgShaderProgram extends ShaderProgram
    method: {set/get}VertexShader(CgVertexShader)
    method: {set/get}FragmentShader(CgFramentShader)
    method: {add/remove}ErrorListener(CgErrorListener)
    method: validate(Canvas3D) ???

public abstract class CgShader extends Shader
    public class CgVertexShader extends CgShader
	method: set/getShaderSource(String)
	method: validate(Canvas3D) ???
    public class CgFragmentShader extends CgShader
	method: set/getShaderSource(String)
	method: validate(Canvas3D) ???

• Changes to existing Appearance class (or maybe create new ShaderAppearance subclass):

public class Appearance extends NodeComponent
    ...
    method: set/getShaderProgram(ShaderProgram)

Click on the following link for a preliminary look at the javadoc-generated API definitions for the newly proposed classes. Note that this is only the javadoc for the new classes. We know that there are lots of broken links for the existing classes.

Example Usage

This is an example code excerpt showing how one might use the new programmable shader API in a Java 3D program.

String vertexShaderFile = "my-vertex-shader-file-name";
String fragmentShaderFile = "my-fragment-shader-file-name";
String vertexShaderSource;
String fragmentShaderSource;

// Read CG vertex and fragment shader source code from text files
vertexShaderSource = TextFileUtils.readFully(vertexShaderFile);
fragmentShaderSource = TextFileUtils.readFully(fragmentShaderSource);

// Create CG vertex and fragment shader objects using the given source code
CgVertexShader vertexShader = new CgVertexShader(vertexShaderSource);
CgFragmentShader fragmentShader = new CgFragmentShader(fragmentShaderSource);

// Create the CG shader program object and attach the vertex and
// fragment shader objects; add an error listener
CgShaderProgram shaderProgram = new CgShaderProgram();
shaderProgram.setVertexShader(vertexShader);
shaderProgram.setFragmentShader(fragmentShader);
shaderProgram.addErrorListener(myCgErrorListener);

// Use CG shader program object in appearance
appearance.setShaderProgram(shaderProgram);

Shader Parameters

Programmable shaders define two types of parameters: uniform and varying. As the names imply, uniform parameters are constant (within a primitive), while varying parameters can vary on per-vertex or per-fragment basis.

1. Uniform parameters (attributes) are those parameters whose value is constant during the rendering of a primitive. Their values may change from primitive to primitive, but are constant for each vertex (for vertex shaders) or fragment (for fragment shaders) of a single primitive. Examples of uniform parameters include a transformation matrix, a texture map, lights, lookup tables, etc. Several Java 3D state attributes are automatically available to the shader program as pre-defined uniform parameters. The application doesn't need to do anything to pass these parameters in to the shader program. The implementation of each shader language (e.g., Cg, GL2) defines its own mapping from Java 3D attribute to uniform variable name.
   
   We need additional API to allow applications to pass in uniform parameters that do not correspond to a pre-defined Java 3D attribute...
   TODO: Finish this...
   
   A partial list of Java 3D attributes that are mapped to shader attributes follows:



Java 3D Attribute	Cg shader variable	GL2 shader variable
ModelViewProjection	glstate.matrix.mvp	gl_ModelViewProjectionMatrix
Light[n] pos	glstate.light[n].position	gl_LightSource[n].position
...	...	...



2. Varying parameters are those parameters that are specified as per-vertex attributes. They are are interpolated across a primitive similarly to colors and texture coordinates in the fixed function pipeline.
   
   We need additional API to allow applications to pass in per-vertex varying parameters...
   TODO: Finish this...
   

TODO: more info here.