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:

Non-power-of-two textures
NIO image buffer support for textures
By-reference support for geometry indices
Rendering error listeners
Vecmath accessors/mutators
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)