Java 3D 1.4 Shaders

From 8ad266e192dd129a035492098d18c83c93c79a22 Mon Sep 17 00:00:00 2001 From: Kevin Rushforth Date: Fri, 25 Mar 2005 21:42:54 +0000 Subject: Reorganized 1.4 feature list git-svn-id: https://svn.java.net/svn/j3d-core~svn/trunk@174 ba19aa83-45c5-6ac9-afd3-db810772062c --- www/j3d1_4/shaders.html | 290 ++++++++++++++++++------------------------------ 1 file changed, 110 insertions(+), 180 deletions(-) (limited to 'www/j3d1_4/shaders.html') diff --git a/www/j3d1_4/shaders.html b/www/j3d1_4/shaders.html index fadfde0..380b742 100644 --- a/www/j3d1_4/shaders.html +++ b/www/j3d1_4/shaders.html @@ -2,187 +2,117 @@ - Java 3D 1.4 Shaders + http-equiv="content-type"> + Java 3D 1.4: Programmable Shaders -

Shaders in Java 3D^TM 1.4

Introduction and pointer to discussion forum

- -

Here is the latest rough first draft of what we are thinking in -terms of programmable shader support in Java 3D^TM for 1.4. We plan to formalize 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. +

Java 3D^TM 1.4: +Programmable Shaders

This is the latest draft of the proposed Java 3D^TM +1.4 API changes for programmable shaders.

We have created a thread on the Java 3D discussion forum for discussing Java 3D Programmable Shaders. Feel free to + href="http://www.javadesktop.org/forums/thread.jspa?threadID=5056" + target="_blank">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 GLSL shader classes:

public class GLSLShaderProgram extends ShaderProgram
-    method: {add/remove/get}Shader(GLSLShader) // set of shader objs
-    method: {add/remove}ErrorListener(GLSLErrorListener)
-    method: validate(Canvas3D) ???
-
-public abstract class GLSLShader extends Shader
-    public class GLSLVertexShader extends GLSLShader
-	method: set/getShaderSource(String)
-	method: validate(Canvas3D) ???
-    public class GLSLFragmentShader extends GLSLShader
-	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) ???
-

New ShaderAppearance class:

public class ShaderAppearance extends Appearance
-    method: set/getShaderProgram(ShaderProgram)
-    method: set/getShaderAttributeSet(ShaderAttributeSet)
-

Abstract shader base classes:

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

Concrete GLSL shader classes:

public class GLSLShaderProgram extends ShaderProgram
    method: {add/remove/get}Shader(GLSLShader) // set of shader objs
    method: {add/remove}ErrorListener(GLSLErrorListener)
    method: validate(Canvas3D) ???

public abstract class GLSLShader extends Shader
    public class GLSLVertexShader extends GLSLShader
	method: set/getShaderSource(String)
	method: validate(Canvas3D) ???
    public class GLSLFragmentShader extends GLSLShader
	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) ???

New ShaderAppearance class:

public class ShaderAppearance extends Appearance
    method: set/getShaderProgram(ShaderProgram)
    method: set/getShaderAttributeSet(ShaderAttributeSet)

New ShaderAttributeSet class:

public class ShaderAttributeSet extends NodeComponent
    method: put/get(ShaderAttribute)
    ...

New ShaderAttributeSet class:

public class ShaderAttributeSet extends NodeComponent
-    method: put/get(ShaderAttribute)
-    ...
-

Click on the following link for a current look at the javadoc-generated + href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/index.html">javadoc-generated API definitions for the proposed 1.4 API.

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 GLSL vertex and fragment shader source code from text files
-vertexShaderSource = StringIO.readFully(vertexShaderFile);
-fragmentShaderSource = StringIO.readFully(fragmentShaderSource);
-
-// Create GLSL vertex and fragment shader objects using the given source code
-GLSLVertexShader vertexShader = new GLSLVertexShader(vertexShaderSource);
-GLSLFragmentShader fragmentShader = new GLSLFragmentShader(fragmentShaderSource);
-
-// Create the GLSL shader program object and attach the vertex and
-// fragment shader objects; add an error listener
-GLSLShaderProgram shaderProgram = new GLSLShaderProgram();
-shaderProgram.setVertexShader(vertexShader);
-shaderProgram.setFragmentShader(fragmentShader);
-shaderProgram.addErrorListener(myGLSLErrorListener);
-
-// Use GLSL shader program object in appearance
-shaderAppearance.setShaderProgram(shaderProgram);
-

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

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

// Create GLSL vertex and fragment shader objects using the given source code
GLSLVertexShader vertexShader = new GLSLVertexShader(vertexShaderSource);
GLSLFragmentShader fragmentShader = new GLSLFragmentShader(fragmentShaderSource);

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

// Use GLSL shader program object in appearance
shaderAppearance.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.

Uniform parameters (attributes) are those parameters whose +
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.
-
- +
We have created a new ShaderAttributeSet for allowing applications to specify uniform shader attributes. There are two ways in which values can be specified for uniform attributes: explicitly, by providing a -value; and implicitly, by defining a binding between a Java 3D system +value; and implicitly, by defining a binding between a Java 3D system attribute and a uniform attribute. This functionality is provided by two subclasses of ShaderAttribute: ShaderAttributeObject, which is used to specify explicitly defined attributes; and ShaderAttributeBinding, which is used to specify implicitly defined, automatically tracked attributes. See the javadoc for the new ShaderAttributeSet + href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttributeSet.html">ShaderAttributeSet and ShaderAttribute + href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttribute.html">ShaderAttribute classes for more details.
-
- -Issues
- -
- Should j3dAttrName be specified as a type-safe enum or object +
  + Issues
  +
  - Should j3dAttrName be specified as a type-safe enum or object instead of a String? -
  - How do we handle passing arrays to the shader, especially for +
    +
  - How do we handle passing arrays to the shader, especially for system parameters such as lights? One possibility is: - -
    +
    Alternatively, an object with a string or type-safe enum, a state (scalar, array element, subarray, or entire array), and indices (as needed). -
  - -
  -Automatic variables
  - +
  +
+
+ Automatic variables
Depending on the shading language (and profile) being used, several Java 3D state attributes are automatically made available to the shader program as pre-defined uniform attributes. The application @@ -190,65 +120,65 @@ doesn't need to do anything to pass these attributes in to the shader program. The implementation of each shader language (e.g., Cg, GLSL) defines its own mapping from Java 3D attribute to uniform variable name.
-
- +
A partial list of Java 3D attributes that are mapped to shader -attributes follows: -

Java 3D +attributes follows: +
+ + + + - + - + - - - - - - - - - - - - - - - - - -

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

-
-

Varying parameters are those parameters that are specified +

ModelViewProjection
+

glstate.matrix.mvp
+

gl_ModelViewProjectionMatrix
+

Light[n] pos
+

glstate.light[n].position +

gl_LightSource[n].position +

...
+

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.

Page last updated — +

Page last updated — $Date$ - -

-- cgit v1.2.3