The Java 3D API Specification |

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

> - `utils.universe` - contains the SimpleUniverse class, which defines a minimal user environment that includes all of the necessary objects on the "view" side of the scene graph. See Section F.17, "utils.universe Package," for a description of this package.

> - `utils.geometry` - contains geometry utilities, such as stripification, normal generation, tessellation, and primitive construction. See Section F.13, "utils.geometry Package," for a description of this package.

> - `utils.picking` - contains the PickIntersection, PickTool, PickCanvas, and PickResult classes, which simplify the construction of picking routines. See Section F.15, "utils.picking Package," for a description of this package.

> - `loaders` - contains the Loader and Scene interfaces, which can be used to implement a variety of Java 3D loaders in a standard manner. See Section F.5, "loaders Package," for a description of this package.

> ## 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 |

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