Java 3D API version 1.5 Change Log

Here are the proposed changes for Java 3D version 1.5. 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

Here is the list of proposed changes for the Java 3D 1.5 API:

1. Non-power-of-two textures
2. NIO image buffer support for textures
3. By-reference support for geometry indices
4. Rendering error listeners
   
5. Vecmath accessors/mutators
6. Deprecated API

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

1. Non-power-of-two textures

We propose to add non-power-of-two textures to Java 3D 1.5. Currently, the width, height, and depth of all textures must be an exact power of two. Most graphics cards now support non-power-of-two textures, so we propose to allow this in Java 3D. Since not all graphics drivers support this feature, we will add a new "textureNonPowerOfTwoAvailable" property to Canvas3D.queryProperties that will indicate whether or not non-power-of-two textures are supported. If this property is set to true, then non-power-of-two textures are rendered normally. If this property is set to false, then the graphics driver or card does not support non-power-of-two textures; texture mapping will be disabled if non-power-of-two textures are rendered on a Canvas3D that doesn't support them.

2. NIO image buffer support for textures

We propose to create a new javax.media.j3d.NioImageBuffer class, a wrapper for an image whose DataBuffer is specified via an appropriate subclass of java.nio.Buffer: ByteBuffer or IntBuffer, depending on the type of image. When using IntBuffer, the byte order of the buffer must match the native byte order of the underlying platform.

New public classes:

public class NioImageBuffer extends Object


New constructors and methods:

ImageComponent
New enums:
    public enum ImageClass {
        BUFFERED_IMAGE, RENDERED_IMAGE, NIO_IMAGE_BUFFER
    }

New methods:
    public ImageClass getImageClass()

ImageComponent2D
New constructors:
    public ImageComponent2D(int format,
            NioImageBuffer image,
            boolean byReference, boolean yUp)

New methods:
    public void set(NioImageBuffer image)
    public NioImageBuffer getNioImage()

ImageComponent3D
New constructors:
    public ImageComponent3D(int format, NioImageBuffer[] images,
                            boolean byReference, boolean yUp)

New methods:
    public void set(NioImageBuffer[] images)
    public void set(int index, NioImageBuffer image)
    public NioImageBuffer[] getNioImage()
    public NioImageBuffer getNioImage(int index)


3. By-reference support for geometry indices

We propose to add support for setting the coordinate indices of IndexedGeometryArray objects "by-reference". Currently, the coordinate indices array is set "by-copy" even for by-reference geometry, resulting in excessive memory usage. Though the excess memory usage is temporary, since it happens only at the time of creating an internal copy of the user-specified indices array, nevertheless it can turn out to be of significant concern especially for very large geometries or for dynamically changing geometry. The fact that the graphics drivers have long supported this feature makes the incorporation of this feature attractive, as it entails no special hardware support.

New fields and methods:

GeometryArray
New fields:
    public static final int BY_REFERENCE_INDICES

IndexedGeometryArray
New methods:
    public void setCoordIndicesRef(int coordIndices[])
    public int[] getCoordIndicesRef()


4. Rendering error listener

We propose to add a rendering error class and error listener interface that applications can use to detect rendering errors that are caught by the Java 3D rendering system. The default error listener, if no user-specified error listeners are added, prints out the error message and exits.

The following new classes and interfaces are proposed:

public class RenderingError extends Object
public interface RenderingErrorListener


The following new methods are proposed:

VirtualUniverse
New methods:
    public static void addRenderingErrorListener(RenderingErrorListener listener)
    public static void removeRenderingErrorListener(RenderingErrorListener listener)


5. Vecmath accessors/mutators

We propose to add accessors and mutators to all vecmath classes with publicly accessible fields. This follows the bean pattern, and allows these classes to be read and written by bean-aware tools, for example, the XMLEncoder. The following classes need public accessors and mutators (e.g., setX(), getX(), setY(), and so forth):

Matrix3d
Matrix3f
Matrix4d
Matrix4f
Tuple2d
Tuple2f
Tuple2i
Tuple3b
Tuple3d
Tuple3f
Tuple3i
Tuple4b
Tuple4d
Tuple4f
Tuple4i


6. Deprecated API

We propose to deprecate the following fields and methods relating to the obsolete texture functionality.

Texture2D
Deprecated fields:
    public static final int ALLOW_DETAIL_TEXTURE_READ
    public static final int LINEAR_DETAIL
    public static final int LINEAR_DETAIL_RGB
    public static final int LINEAR_DETAIL_ALPHA
    public static final int DETAIL_ADD
    public static final int DETAIL_MODULATE

Deprecated methods:
    public void setDetailImage(ImageComponent2D detailTexture)
    public ImageComponent2D getDetailImage()
    public void setDetailTextureMode(int mode)
    public int getDetailTextureMode()
    public void setDetailTextureLevel(int level)
    public int getDetailTextureLevel()
    public void setDetailTextureFunc(float[] lod, float[] pts)
    public void setDetailTextureFunc(Point2f[] pts)
    public int getDetailTextureFuncPointsCount()
    public void getDetailTextureFunc(float[] lod, float[] pts)
    public void getDetailTextureFunc(Point2f[] pts)

ImageComponent
Deprecated methods:
    public void setYUp(boolean yUp)


II. Accepted Changes

III. Deferred Changes