Java 3D API version 1.4 Change Log

Here are the proposed changes for Java 3D version 1.4. These proposed changes are a results of discussion and collaboration with the Java 3D community on java.net (see https://java3d.dev.java.net). They are already part of daily and periodic stable builds available on java.net.

I. Proposed Changes

II. Accepted Changes

Here is the list of accepted changes for the Java 3D 1.4 API:

1. Programmable shader support
2. Default values for read capability bits
3. Picking
4. Stencil
5. Rendering attributes
6. Other minor features
7. Deprecated API
   

For a complete description of these changes, please see the proposed API specification (javadoc) for the 1.4 version of the Java 3D API.

1. Programmable shader support

We propose to add programmable shader support to Java 3D 1.4. This is the primary new feature of this release.

The following new classes and interfaces are added in the javax.media.j3d package:

public class ShaderAppearance extends Appearance
public class ShaderAttributeSet extends NodeComponent
public abstract class ShaderAttribute extends NodeComponent
public class ShaderAttributeBinding extends ShaderAttribute
public abstract class ShaderAttributeObject extends ShaderAttribute
public class ShaderAttributeValue extends ShaderAttributeObject
public class ShaderAttributeArray extends ShaderAttributeObject
public abstract class Shader extends NodeComponent
public class SourceCodeShader extends Shader
public abstract class ShaderProgram extends NodeComponent
public class CgShaderProgram extends ShaderProgram
public class GLSLShaderProgram extends ShaderProgram
public class ShaderError extends Object
public interface ShaderErrorListener



The following new classes are added in the javax.vecmath package:

public abstract class Tuple2i implements Serializable, Cloneable
public class Point2i extends Tuple2i


The following new fields, constructors, and methods are added to existing classes:

Canvas3D
New method:
    public boolean isShadingLanguageSupported(int shadingLanguage)

VirtualUniverse
New methods:
    public void addShaderErrorListener(ShaderErrorListener listener)
    public void removeShaderErrorListener(ShaderErrorListener listener)

GeometryArray
New fields:
    public static final int ALLOW_VERTEX_ATTR_READ
    public static final int ALLOW_VERTEX_ATTR_WRITE
    public static final int VERTEX_ATTRIBUTES

New constructor:
    public GeometryArray(... int vertexAttrCount, int[] vertexAttrSizes)

New methods:
    public int getVertexAttrCount()
    public void getVertexAttrSizes(int[] vertexAttrSizes)
    public void setVertexAttr(int vertexAttrNum, int index, float[] vertexAttr)
    public void setVertexAttr(int vertexAttrNum, int index, Point2f vertexAttr)
    public void setVertexAttr(int vertexAttrNum, int index, Point3f vertexAttr)
    public void setVertexAttr(int vertexAttrNum, int index, Point4f vertexAttr)
    public void setVertexAttrs(int vertexAttrNum, int index, float[] vertexAttrs)
    public void setVertexAttrs(int vertexAttrNum, int index, Point2f[] vertexAttrs)
    public void setVertexAttrs(int vertexAttrNum, int index, Point3f[] vertexAttrs)
    public void setVertexAttrs(int vertexAttrNum, int index, Point4f[] vertexAttrs)
    public void setVertexAttrs(int vertexAttrNum, int index,
                               float[] vertexAttrs, int start, int length)
    public void setVertexAttrs(int vertexAttrNum, int index,
                               Point2f[] vertexAttrs, int start, int length)
    public void setVertexAttrs(int vertexAttrNum, int index,
                               Point3f[] vertexAttrs, int start, int length)
    public void setVertexAttrs(int vertexAttrNum, int index,
                               Point4f[] vertexAttrs, int start, int length)
    public void getVertexAttr(int vertexAttrNum, int index, float[] vertexAttr)
    public void getVertexAttr(int vertexAttrNum, int index, Point2f vertexAttr)
    public void getVertexAttr(int vertexAttrNum, int index, Point3f vertexAttr)
    public void getVertexAttr(int vertexAttrNum, int index, Point4f vertexAttr)
    public void getVertexAttrs(int vertexAttrNum, int index, float[] vertexAttrs)
    public void getVertexAttrs(int vertexAttrNum, int index, Point2f[] vertexAttrs)
    public void getVertexAttrs(int vertexAttrNum, int index, Point3f[] vertexAttrs)
    public void getVertexAttrs(int vertexAttrNum, int index, Point4f[] vertexAttrs)
    public void setInitialVertexAttrIndex(int vertexAttrNum, int initialVertexAttrIndex)
    public int getInitialVertexAttrIndex(int vertexAttrNum)
    public void setVertexAttrRefBuffer(int vertexAttrNum, J3DBuffer vertexAttrs)
    public J3DBuffer getVertexAttrRefBuffer(int vertexAttrNum)
    public void setVertexAttrRefFloat(int vertexAttrNum, float[] vertexAttrs)
    public float[] getVertexAttrRefFloat(int vertexAttrNum)

IndexedGeometryArray
New fields:
    public static final int ALLOW_VERTEX_ATTR_INDEX_READ
    public static final int ALLOW_VERTEX_ATTR_INDEX_WRITE

New constructor:
    public IndexedGeometryArray(... int vertexAttrCount, int[] vertexAttrSizes ...)

New methods:
    public void setInitialVertexAttrIndex(int vertexAttrNum, int initialVertexAttrIndex)
    public void setVertexAttrIndex(int vertexAttrNum, int index, int vertexAttrIndex)
    public void setVertexAttrIndices(int vertexAttrNum, int index, int[] vertexAttrIndices)
    public int getVertexAttrIndex(int vertexAttrNum, int index)
    public void getVertexAttrIndices(int vertexAttrNum, int index, int[] vertexAttrIndices)



The following new constructors are added to existing GeometryArray subclasses:

PointArray
public PointArray(... int vertexAttrCount, int[] vertexAttrSizes)

LineArray
public LineArray(... int vertexAttrCount, int[] vertexAttrSizes)


TriangleArray
public TriangleArray(... int vertexAttrCount, int[] vertexAttrSizes)


QuadArray
public QuadArray(... int vertexAttrCount, int[] vertexAttrSizes)


GeometryStripArray
public GeometryStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


LineStripArray
public LineStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


TriangleStripArray
public TriangleStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


TriangleFanArray
public TriangleFanArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedPointArray
public IndexedPointArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedLineArray
public IndexedLineArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedTriangleArray
public IndexedTriangleArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedQuadArray
public IndexedQuadArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedGeometryStripArray
public IndexedGeometryStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedLineStripArray
public IndexedLineStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedTriangleStripArray
public IndexedTriangleStripArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


IndexedTriangleFanArray
public IndexedTriangleFanArray(... int vertexAttrCount, int[] vertexAttrSizes ...)


2. Default values for read capability bits

Capability bits control whether data in a Java 3D scene graph object may be read or written when it is part of a live or compiled subgraph. We propose to change the default value for all read capability bits to true, meaning that all attributes may be read by default (the default value for all write capability bits will remain false, meaning that no attributes may be written by default). Note that read capability bits are defined as those capability bits of the form ALLOW_*_READ, plus the ALLOW_INTERSECT capability bit.

3. Picking

We propose to add a new PickInfo class (with an inner class to hold intersection information), and new core picking methods that return objects of this new class type.

New Classes:

public class PickInfo extends Object
public class PickInfo.IntersectionInfo extends Object


New methods:

Locale
public PickInfo[] pickAll( int mode, int flags, PickShape pickShape )
public PickInfo[] pickAllSorted( int mode, int flags, PickShape pickShape )
public PickInfo pickClosest( int mode, int flags, PickShape pickShape )
public PickInfo pickAny( int mode, int flags, PickShape pickShape )


BranchGroup
public PickInfo[] pickAll( int mode, int flags, PickShape pickShape )
public PickInfo[] pickAllSorted( int mode, int flags, PickShape pickShape )
public PickInfo pickClosest( int mode, int flags, PickShape pickShape )
public PickInfo pickAny( int mode, int flags, PickShape pickShape )

4. Stencil

We propose new stencil functionality. Here are the proposed new fields and methods:

RenderingAttributes
New fields:
    public static final int ALLOW_STENCIL_ATTRIBUTES_READ
    public static final int ALLOW_STENCIL_ATTRIBUTES_WRITE
    public static final int STENCIL_KEEP
    public static final int STENCIL_ZERO
    public static final int STENCIL_REPLACE
    public static final int STENCIL_INCR
    public static final int STENCIL_DECR
    public static final int STENCIL_INVERT

New methods:
    public void setStencilEnable(boolean enable)
    public boolean getStencilEnable()
    public void setStencilOp(int failOp, int zFailOp, int zPassOp)
    public void setStencilOp(int[] stencilOps)
    public void getStencilOp(int[] stencilOps)
    public void setStencilFunction(int function, int refValue, int compareMask)
    public void setStencilFunction(int[] params)
    public void getStencilFunction(int[] params)
    public void setStencilWriteMask(int mask)
    public int getStencilWriteMask()

GraphicsConfigTemplate3D
New methods:
    public void setStencilSize(int value)
    public int getStencilSize()


5. Rendering attributes

We propose to add new rendering attributes/modes to enable applications to specify the depth test function, additional raster operations, and additional blending modes. The new fields and methods are as follows:

RenderingAttributes
New fields:
    public static final int ALLOW_DEPTH_TEST_FUNCTION_READ
    public static final int ALLOW_DEPTH_TEST_FUNCTION_WRITE
    public static final int ROP_CLEAR
    public static final int ROP_AND
    public static final int ROP_AND_REVERSE
    public static final int ROP_AND_INVERTED
    public static final int ROP_NOOP
    public static final int ROP_OR
    public static final int ROP_NOR
    public static final int ROP_EQUIV
    public static final int ROP_INVERT
    public static final int ROP_OR_REVERSE
    public static final int ROP_COPY_INVERTED
    public static final int ROP_OR_INVERTED
    public static final int ROP_NAND
    public static final int ROP_SET

New methods:
    public void setDepthTestFunction(int function)
    public int getDepthTestFunction()

TransparencyAttributes
New fields:
    public static final int BLEND_DST_COLOR
    public static final int BLEND_ONE_MINUS_DST_COLOR
    public static final int BLEND_SRC_COLOR
    public static final int BLEND_ONE_MINUS_SRC_COLOR


6. Other minor features

We propose to add the following new features: a name for all scene graph objects; the ability to get the Locale or parent from a live or compiled scene graph, a scene graph structure change listener, and a method to get the tessellated glyph geometry for a character in a 3D font.

The following new class has been added:

public interface GraphStructureChangeListener


The new fields and methods are as follows:

VirtualUniverse
New methods:
    public void addGraphStructureChangeListener(GraphStructureChangeListener listener)
    public void removeGraphStructureChangeListener(GraphStructureChangeListener listener)


SceneGraphObject
New methods:
    public void setName(String name)
    public String getName()


Node
New fields:
    public static final int ALLOW_PARENT_READ
    public static final int ALLOW_LOCALE_READ

New methods:
    public Locale getLocale()


Font3D
New methods:
    public GeometryArray getGlyphGeometry(char c)


7. Deprecated API

We propose to deprecate the following classes:

CompressedGeometry
CompressedGeometryHeader
PickPoint
Morph


We propose to deprecate the following fields and methods:

Sensor
Deprecated fields:
    public static final int PREDICT_NONE
    public static final int PREDICT_NEXT_FRAME_TIME
    public static final int NO_PREDICTOR
    public static final int HEAD_PREDICTOR
    public static final int HAND_PREDICTOR

Deprecated methods:
    public void setPredictor(int predictor)
    public int getPredictor()
    public void setPredictionPolicy(int policy)
    public int getPredictionPolicy()
    public void getRead(Transform3D read, long deltaT)


III. Deferred Changes