The Java 3D API Specification Contents Previous Next Index


A P P E N D I X F

The Utility Packages




THIS appendix summarizes the Java 3D utilities packages.

F.1 The Utility Packages

The com.sun.j3d.* packages provide aids to assist the application programmer in setting up a user environment and getting a Java 3D application up and running as quickly as possible. The utilities packages contain classes that are not part of the formal Java 3D API specification. Since these packages are not part of the API specification, they are subject to change and will evolve over time.

The most useful of these packages are

F.2 Package Overview

The Java 3D utilities packages are all in the com.sun.j3d hierarchy. Table F-1 lists the utilities packages.

Table F-1 Utilities Packages
Package Name Description
audioengines Useful only to people writing audio device drivers.
audioengines.javasound Defines an audio output device that accesses JavaSound's sound mixer functionality.
loaders Used in the construction of file loaders.
loaders.lw3d Implements a loader for Lightwave 3D scene files.
loaders.objectfile Implements a loader for Wavefront object files.
utils.applet Enables creating Java applets that can also run as stand-alone applications.
utils.behaviors.interpolators Enhances the Interpolator class with the TCB (Kochanek-Bartels) spline interpolation.
utils.behaviors.keyboard Useful for controlling the scene graph behavior from the keyboard.
utils.behaviors.mouse Useful for controlling scene graph behavior with the mouse, specifically, object rotation, translation, and zoom.
utils.compression Useful for geometry compression.
utils.geometry Includes geometry utilities, such as stripification, normal generation, tessellation, and primitive construction.
utils.image Useful for loading Java 3D texture objects.
utils.picking Useful for defining picking operations and retrieving information about the picked object.
utils.picking.behaviors Combines picking with mouse-based rotation, translation, and zoom behaviors.
utils.universe Useful for setting up a user environment to get a Java 3D program up and running quickly and easily.

F.3 audioengines Package

The com.sun.j3d.audioengines package is useful only to people writing audio device drivers. Java 3D application developers are not expected to use the classes in this package.

Table F-2 lists the classes in the com.sun.j3d.audioengines package.

Table F-2 audioengines Classes
Class Description
AudioEngine Extends: Object Implements: AudioDevice Encapsulates basic information about the AudioDevice, such as the playback type (headphones, monaural speakers, or stereo speakers) and the listener's distance from the speakers.
AudioEngine3D Extends: AudioEngine Implements: AudioDevice3D Defines an audio output device that generates sound "image" from high-level sound parameters passed to it while the scene graph is active.
AuralParameters Extends: Object Defines a set of fields that correspond to AuralAttribute fields.
Sample Extends: Object Defines the data and methods associated with a sound sample played through the AudioDevice.

F.4 audioengines.javasound Package

The com.sun.j3d.audioengines.javasound package contains a single public class that implements a JavaSound-based audio device. Most programs should let the SimpleUniverse (or Viewer) class in the universe package construct the audio device.

Table F-3 lists the class in the com.sun.j3d.audioengines.javasound package.

Table F-3 audioengines.javasound Package
Class Description
JavaSoundMixer Extends: AudioEngine3D Defines an audio output device that accesses JavaSound's sound mixer functionality.

F.5 loaders Package

The com.sun.j3d.loaders package contains two interfaces, Loader and Scene, that can be used to implement a variety of Java 3D loaders in a standard manner. Base classes that implement these interfaces are also included as a convenience.

F.5.1 Interfaces

Table F-4 lists the interfaces in the com.sun.j3d.loaders package.

Table F-4 loaders Package Interfaces
Interface Description
Loader Used to specify the location and elements of a file format to load. The interface is used to give loaders of various file formats a common public interface.
Scene A set of methods used to extract Java 3D scene graph information from a file loader utility. The interface is used to give loaders of various file formats a common public interface.

F.5.2 Classes

Table F-5 lists the classes in the com.sun.j3d.loaders package.

Table F-5 loaders Package Classes
Class Description
LoaderBase Extends: Object Implements: Loader Abstract base class that can be used as a starting point for a Loader. A specific file loader could extend this class and implement the load methods.
SceneBase Extends: Object Implements: Scene Responsible for both the storage and retrieval of data from the Scene. Most loaders will not need to extend this class.

F.5.3 Exceptions

Table F-6 lists the exceptions in the com.sun.j3d.loaders package.

Table F-6 loaders Package Exceptions
Exception Description
IncorrectFormatException Extends: RuntimeException Indicates that a file of an incorrect type was passed to a loader.
ParsingErrorException Extends: RuntimeException Indicates that the loader encountered a problem parsing the specified file.

F.6 loaders.lw3d Package

The com.sun.j3d.loaders.lw3d package provides a file loader that allows applications to load Lightwave 3D scene files.

Table F-7 lists the class in the com.sun.j3d.loaders.lw3d package.

Table F-7 loaders.lw3d Package
Class Description
Lw3dLoader Extends: loaders.lw3d.TextfileParser Implements: Loader Allows users to load Lightwave 3D scene files.

F.7 loaders.objectfile Package

The com.sun.j3d.loaders.objectfile package provides a file loader that allows applications to load Wavefront object files.

Table F-8 lists the class in the com.sun.j3d.loaders.objectfile package.

Table F-8 loaders.objectfile Package
Class Description
ObjectFile Extends: Object Implements: Loader Implements the Loader interface for the Wavefront .obj file format, a standard 3D object file format created for use with Wavefront's Advanced Visualizer and available for purchase from Viewpoint DataLabs, as well as other 3D model companies.

F.8 utils.applet Package

The com.sun.j3d.utils.applet package includes a single class, MainFrame, that enables the creation of Java applets that can also run as standalone applications. The MainFrame class was developed by Jef Poskanzer of Acme Labs <jef@acme.com>.

Table F-9 lists the class in the com.sun.j3d.applet package.

Table F-9 utils.applet Package
Class Description
MainFrame Extends: Frame Implements: java.lang.Runnable, java.applet.AppletStub, java.applet.AppletContext Allows a Java applet to run as an application.

F.9 utils.behaviors.interpolators Package

The com.sun.j3d.utils.behaviors.interpolators package provides spline-based interpolators using KCB (Kochanek-Bartels) splines (also known as the TCB or Tension-Continuity-Bias spline). Applications can use these interpolators to implement key-frame animation sequences.

Table F-10 lists the classes in the com.sun.j3d.utils.behaviors.interpolators package.

Table F-10 utils.behaviors.interpolators Package
Class Description
KBCubicSplineCurve Extends: Object A container class that holds a number of cubic spline segments.
KBCubicSplineSegment Extends: Object Creates the representation of a KCB (Kochanek-Bartels) spline.
KBKeyFrame Extends: Object Represents a Key Frame that can be used for Kochanek-Bartels spline interpolation.
KBRotPosScaleSplinePathInterpolator Extends: KBSplinePathInterpolator Defines a behavior that varies the rotational, translational, and scale components of its target TransformGroup by using the Kochanek-Bartels cubic spline interpolation to interpolate among a series of key frames (using the value generated by the specified Alpha object). The interpolated position, orientation, and scale are used to generate a transform in the local coordinate system of this interpolator.
KBSplinePathInterpolator Extends: Interpolator Defines the base class for all KCB (Kochanek-Bartels) Spline Path Interpolators.

F.10 utils.behaviors.keyboard Package

The com.sun.j3d.utils.behaviors.keyboard package contains classes that take keyboard events and turns them into transform changes that are suitable for use in modifying the ViewPlatform's transformation matrix for navigation.

Table F-11 lists the classes in the com.sun.j3d.utils.behaviors.keyboard package.

Table F-11 utils.behaviors.keyboard Package
Class Description
KeyNavigator Extends: Object Accumulates AWT key events (key press and key release) and computes a new transform based on the accumulated events and elapsed time.
KeyNavigatorBehavior Extends: Behavior A simple behavior that invokes the KeyNavigator to modify the view platform transform.

F.11 utils.behaviors.mouse Package

The com.sun.j3d.utils.behaviors.mouse package contains classes that use mouse events to modify object or viewing transformations. Subclasses exist to perform rotation, translation, and zoom operations.

F.11.1 Interfaces

Table F-12 lists the interface in the com.sun.j3d.utils.behaviors.mouse package.

Table F-12 utils.behaviors.mouse Package Interface
Interface Description
MouseBehaviorCallback Allows a class to be notified when the transform is changed by one of the MouseBehaviors. The class that is interested in transform changes implements this interface, and the object created with that class is registered with the desired subclass of MouseBehavior using the setupCallback method. When the transform changes, the registered object's transformChanged method is invoked.

F.11.2 Classes

Table F-13 lists the classes in the com.sun.j3d.utils.behaviors.mouse package.

Table F-13 utils.behaviors.mouse Package Classes
Class Description
MouseBehavior Extends: Behavior The base class for all mouse manipulators (MouseRotate, MouseZoom, and MouseTranslate).
MouseRotate Extends: MouseBehavior A Java 3D behavior object that lets users control the rotation of an object via a mouse.
MouseTranslate Extends: MouseBehavior A Java 3D behavior object that lets users control the translation (x, y) of an object via a mouse drag motion with the third mouse button (alt-click on PC).
MouseZoom Extends: MouseBehavior A Java 3D behavior object that lets users control the z axis translation of an object via a mouse drag motion with the second mouse button.

F.12 utils.compression Package

The com.sun.j3d.utils.compression package includes classes for compressing geometry and for reading and writing compressed geometry resource files.

Table F-14 lists the classes in the com.sun.j3d.utils.compression package.

Table F-14 utils.compression Package
Class Description
CompressedGeometryFile Extends: Object Provides methods to read and write compressed geometry resource files. These files usually end with the .cg extension and support sequential as well as random access to multiple compressed geometry objects.
CompressionStream Extends: Object Used as input to a geometry compressor. It collects elements such as vertices, normals, colors, mesh references, and quantization parameters in an ordered stream. This stream is then traversed during the compression process and used to build the compressed output buffer.
GeometryCompressor Extends: Object Takes a stream of geometric elements and quantization parameters (the CompressionStream object) and compresses it into a stream of commands as defined in Appendix B, "3D Geometry Compression." The resulting data may be output in the form of a CompressedGeometry node component or appended to a CompressedGeometryFile.

F.13 utils.geometry Package

The com.sun.j3d.utils.geometry package contains geometry utilities, such as stripification, normal generation, tessellation (polygon triangulation), and primitive construction. The GeometryInfo class provides a common data storage format for the stripification, normal generation, and tessellation classes.

Table F-15 lists the classes in the com.sun.utils.geometry package.

Table F-15 utils.geometry Package
Class Description
Box Extends: Primitive A geometry primitive created with a given length, width, and height.
ColorCube Extends: Shape3D A simple color-per-vertex cube with a different color for each face.
Cone Extends: Primitive A geometry primitive defined with a radius and a height. It is a capped cone centered at the origin with its central axis aligned along the y-axis.
Cylinder Extends: Primitive A geometry primitive defined with a radius and a height. It is a capped cylinder centered at the origin with its central axis aligned along the y-axis.
GeometryInfo Extends: Object The object where you put your geometry if you want to use the Java 3D utility packages. Once you have your data in the GeometryInfo object, you can send it to any (or all) of several utilities to have operations performed on it, such as generating normals or turning it into long strips for more efficient rendering. Geometry is loaded just as it is in the Java 3D Geometry-Array object, but there are fewer options for getting data into the object. GeometryInfo itself contains some simple utilities, such as calculating indices for nonindexed data ("indexifying") and getting rid of unused data in your indexed geometry information ("compacting").
NormalGenerator Extends: Object Calculates and fills the normals of a GeometryInfo object. The normals are computed based on an analysis of the indexed coordinate information.
Primitive Extends: Group The base class for all Java 3D primitives.
Sphere Extends: Primitive A geometry primitive created with a given radius and resolution. It is centered at the origin.
Stripifier Extends: Object Changes the primitive of the GeometryInfo object to triangle strips. The strips are made by analyzing the triangles in the original data and connecting them together.
Text2D Extends: Shape3D Creates a texture-mapped rectangle that displays the text string supplied by the user, given the appearance parameters also supplied by the user.
Triangulator Extends: Object Turns arbitrary polygons into triangles so they can be rendered by Java 3D. Polygons can be concave or nonplanar,and can contain holes (see GeometryInfo).

F.14 utils.image Package

The com.sun.j3d.utils.image package contains a single class, TextureLoader, that is used to load a Java 3D texture object from a file. It will automatically scale the image to a power of two and, optionally, compute mipmaps.

Table F-16 lists the class in the com.sun.j3d.utils.image package.

Table F-16 utils.image Package
Class Description
TextureLoader Extends: Object Used for loading a texture from an Image or BufferedImage. Methods are provided to retrieve the Texture object and the associated ImageComponent object or a scaled version of the ImageComponent object. The default format is RGBA. Other legal formats are: RGBA, RGBA4, RGB5_A1, RGB, RGB4, RGB5, R3_G3_B2, LUM8_ALPHA8, LUM4_ALPHA4, LUMINANCE, and ALPHA.

F.15 utils.picking Package

The com.sun.j3d.utils.picking package includes classes that construct a pick shape from a 2D mouse location, initiate a picking operation, and retrieve information about the picked object(s).

Table F-17 lists the classes in the com.sun.j3d.utils.picking package.

Table F-17 utils.picking Package
Class Description
PickCanvas Extends: PickTool Simplifies picking using mouse events from a canvas. This class allows picking using canvas x,y locations by generating the appropriate pick shape.
PickIntersection Extends: Object Holds information about an intersection of a PickShape with a Node as part of a PickResult. Information about the intersected geometry, intersected primitive, intersection point, and closest vertex can be inquired.
PickResult Extends: Object Stores information about a pick hit. Detailed information about the pick and each intersection of the PickShape with the picked Node can be inquired.
PickTool Extends: Object The base class for picking operations. The picking methods will return a PickResult object for each object picked, which can then be queried to obtain more detailed information about the specific objects that were picked.

F.16 utils.picking.behaviors Package

The com.sun.j3d.utils.picking.behaviors package combines picking with mouse-based rotation, translation, and zoom behaviors. Once an object is picked, that object can be manipulated with the mouse.

F.16.1 Interfaces

Table F-18 lists the interface in the com.sun.j3d.utils.picking.behaviors package.

Table F-18 utils.picking.behaviors Package Interfaces
Interface Description
PickingCallback Allows a class to be notified when a picked object is moved. The class that is interested in object movement implements this interface, and the object created with that class is registered with the desired subclass of PickMouseBehavior using the setupCallback method. When the picked object moves, the registered object's transformChanged method is invoked.

F.16.2 Classes

Table F-19 lists the classes in the com.sun.j3d.utils.picking.behaviors package.

Table F-19 utils.picking.behaviors Package Classes
Class Description
PickMouseBehavior Extends: Behavior Base class that allows users to add picking and mouse manipulation to the scene graph.
PickRotateBehavior Extends: PickMouseBehavior A mouse behavior that allows users to pick and drag scene graph objects.
PickTranslateBehavior Extends: PickMouseBehavior A mouse behavior that allows users to pick and translate scene graph objects.
PickZoomBehavior Extends: PickMouseBehavior A mouse behavior that allows users to pick and zoom scene graph objects.

F.17 utils.universe Package

The com.sun.j3d.universe package is useful for setting up a user environment to quickly and easily get a Java 3D program up and running. Specifically, this class creates a Locale, a single ViewingPlatform (with its associated ViewPlatform), and a Viewer object (with its associated View, PhysicalBody, PhysicalEnvironment, and AudioDevice). For many applications, the SimpleUniverse class will provide all of the necessary functionality.

Table F-20 lists the classes in the com.sun.j3d.utils.universe package.

Table F-20 utils.universe Package
Class Description
MultiTransformGroup Extends: Object A convenience class that effectively creates a series of TransformGroup nodes connected one to another hierarchically.
PlatformGeometry Extends: BranchGroup Holds any geometry that should be associated with the ViewingPlatform object.
SimpleUniverse Extends: VirtualUniverse Sets up a minimal user environment to get a Java 3D program up and running quickly and easily. This utility class creates all the necessary objects on the "view" side of the scene graph. Specifically, this class creates a locale-a single ViewingPlatform, and a Viewer object (both with their default values). Many basic Java 3D applications will find that SimpleUniverse provides all necessary functionality needed by their applications.
Viewer Extends: Object Holds all the information that describes the physical and virtual "presence" in the Java 3D universe.
ViewerAvatar Extends: BranchGroup Holds geometry that should be associated with the View's avatar.
ViewingPlatform Extends: BranchGroup Used to set up the "view" side of a Java 3D scene graph. The ViewingPlatform object contains a MultiTransformGroup node to allow for a series of transforms to be linked together. To this structure the ViewPlatform is added as well as any geometry to associate with this view platform.



   The Java 3D API Specification Contents Previous Next Index


Copyright © 2000, Sun Microsystems, Inc. All rights reserved.