Java 3D API Specification
Java 3D API Specification
C H A P T E R 3 |
|
Scene Graph Superstructure |
Java 3D's superstructure consists of one or more VirtualUniverse objects, each of which contains a set of one or more high-resolution Locale objects. The Locale objects, in turn, contain collections of subgraphs that comprise the scene graph.
3.1
The Virtual Universe
Java 3D defines the concept of a virtual universe as a three-dimensional space with an associated set of objects. Virtual universes serve as the largest unit of aggregate representation, and can also be thought of as databases. Virtual universes can be very large, both in physical space units and in contents. Indeed, in most cases a single virtual universe will serve an application's entire needs.
Virtual universes are separate entities in that no node object may exist in more than one virtual universe at any one time. Likewise, the objects in one virtual universe are not visible in, nor do they interact with objects in, any other virtual universe.
To support large virtual universes, Java 3D introduces the concept of locales that have high-resolution coordinates as an origin. Think of high-resolution coordinates as "tie-downs" that precisely anchor the locations of objects specified using less-precise floating point coordinates that are within the range of influence of the high-resolution coordinates.
Figure 3-1
The Virtual Universe
A locale, with its associated high-resolution coordinates, serves as the next level of representation down from a virtual universe. For example, all virtual universes contain one or more high-resolution coordinate locales, and all other objects are attached to a locale. High-resolution coordinates act as an upper level translation-only transform node. For example, the coordinates of all objects attached to a particular locale are all relative to the location of that locale's high-resolution coordinate.
While a virtual universe is similar to the traditional computer graphics concept of a scene graph, a given virtual universe can become so large that it is often better to think of a scene graph as the descendent of a high-resolution coordinate locale.
3.2
To construct a three-dimensional scene, the programmer must execute a Java 3D program. The Java 3D application must first create a virtual universe and attach at least one locale to it. Then the desired scene graph is constructed, starting with a BranchGroup node and also including at least one ViewPlatform object, and is attached to the locale. Finally, a View object is constructed that references the ViewPlatform object (see Section 1.7, "Structuring the Java 3D Program"). As soon as a scene graph containing a VIewPlatform is attached to the VirtualUniverse, Java 3D's rendering loop is engaged, and the scene will appear on the drawing canvas(es) associated with the View object.
3.3
Java 3D is a run-time API (application programmers interface), not a file format. As an API, Java 3D provides no direct mechanism for loading or storing a virtual universe. Constructing a scene graph involves the execution of a Java 3D program. However, loaders to convert a number of standard 3D file formats to or from Java 3D virtual universes are expected to be generally available.
3.4
By default, Java 3D coordinate systems are right handed, with the orientation semantics that +Y is the local gravitational up, +X is horizontal to the right, and +Z is directly toward the viewer.
By default, Java 3D coordinate systems are in units of meters.
3.5
Double precision floating point, single precision floating point, or even fixed-point representations of three-dimensional coordinates are sufficient to represent and display rich 3D scenes. Unfortunately, scenes are not worlds, let alone universes. If one ventures even a hundred miles away from the (0.0, 0.0, 0.0) origin using only single-precision floating-point coordinates, representable points become quite quantized, to at very best a third of an inch (and much more coarsely than that in practice).
To "shrink" down to a small size (say the size of an IC transistor), even very near (0.0, 0.0, 0.0) the same problem arises.
If a large contiguous virtual universe is to be supported, some form of higher-resolution addressing is required. Thus the choice of 256-bit positional components for "high resolution" positions.
3.5.1
A Java 3D high-resolution coordinate consists of three 256-bit fixed-point numbers, one each for x, y, and z. The fixed point is at bit 128 and the value 1.0 is defined to be exactly one meter. This coordinate system is sufficient to describe a universe in excess of several hundred billion light years across, yet still define objects smaller than a proton (down to below the planck length). Table 3-1 shows how many bits are needed above or below the fixed point to represent the range of interesting physical dimensions.
A 256-bit fixed-point number also has the advantage of being able to directly represent nearly any reasonable single-precision floating point value exactly.
High-resolution coordinates in Java 3D are only used to embed more traditional floating point coordinate systems within a much higher resolution substrate. In this way a visually seamless virtual universe of any conceivable size or scale can be created, without worry about numerical accuracy.
3.5.2
Within a given virtual world coordinate system, positions are expressed by three floating point numbers. The virtual world coordinate scale is in meters, but this can be affected by scale changes in the object hierarchy.
3.5.3
High-resolution coordinates are represented as signed, two's-complement fixed point numbers consisting of 256 bits. Although Java 3D keeps the internal representation of high-resolution coordinates opaque, users specify such coordinates using eight-element integer arrays. Java 3D treats the integer found at index 0 as containing the most-significant bits and those found at index 7 as containing the least-significant bits of the high-resolution coordinate. The binary point is located at bit position 128 or between the integers at index 3 and 4. A high-resolution coordinate of 1.0 is 1 meter.
The semantics of how file loaders deal with high-resolution coordinates is up to the individual file loader, as Java 3D does not directly define any file loading semantics. However, some general advice can be given (note that this advice is not officially part of the Java 3D specification).
For "small" virtual universes (order of hundreds of meters across in relative scale), a single high-resolution coordinate at location (0.0, 0.0, 0.0) as the root node (below the virtual universe object) is sufficient; a loader can automatically construct this node during the loading process, and the high-resolution coordinate does not need any direct representation in the external file.
For larger virtual universes, it is expected that they will usually be constructed like computer directory hierarchies, e.g. a "root" virtual universe containing mostly external file references to embedded virtual universes. In this case, the file reference object (user-specific data hung off a Java 3D group or hi-res node) defines the location for the data to be read into the current virtual universe.
When reading the file, its contents should be parented to the file object node, and thus inherit the high-resolution coordinate of the file object as the new relative virtual universe origin of the embedded scene graph. If this scene graph itself contains high-resolution coordinates, it will need to be offset (translated) by the amount in the file object's high-resolution coordinate, and then added to the larger virtual universe as new high-resolution coordinates, with their contents hung off below them. Once again, the above is not part of the official Java 3D specification, but some more details on the care and use of high-resolution coordinates in external file formats will probably be available as a Java 3D application note.
Note for authoring tools directly supporting high-resolution coordinate: authoring tools should create additional high-resolution coordinates as a user creates new geometry "sufficiently" far away (or of different scale) from existing high-resolution coordinates.
Semantics of "widely" moving objects. Most fixed and near-fixed objects stay attached to the same high-resolution coordinate. Objects that make wide changes in position or scale may need to be periodically re-parented to more appropriate high-resolution coordinates. If no appropriate high-resolution coordinate exists, the application may need to create a new one.
Semantics of viewing. The view platform object and the associated nodes in its hierarchy are very often widely moving objects. Applications will typically attach the view platform to the most appropriate high-resolution locale. For display, all objects will first have their positions translated by the difference between the location of their high-resolution locale, and the view platform's high-resolution locale. (In the common case of the locales being the same, no translation is necessary.)
3.6
3.6.1
The VirtualUniverse object consists of a set of Locale objects.
Constructors
The VirtualUniverse object has the following constructors.
public VirtualUniverse()This constructs a new VirtualUniverse object. This VirtualUniverse can then be used to create Locale objects.
Methods
The VirtualUniverse object has the following methods.
public Locale getLocale(int index)Returns the locale specified by the index.
public int numLocales()Returns the number of locales.
3.6.2
The Locale object consists of a high-resolution coordinate and a set of subgraphs, rooted by BranchGroup node objects.
Constructors
The Locale object has the following constructors.
public Locale(VirtualUniverse universe) public Locale(VirtualUniverse universe, int[] x, int[] y, int[] z) public Locale(VirtualUniverse universe, HiResCoord hiRes)These three constructors create a new high-resolution Locale object in the specified VirtualUniverse. The first form constructs a Locale object located at (0.0, 0.0, 0.0). The other two forms construct a Locale object using the specified high-resolution coordinate. In the second form, the parameters
x,y, andzare arrays of eight 32-bit integers that specify the high-resolution coordinate.Methods
public VirtualUniverse getVirtualUniverse()This method retrieves the virtual universe within which this Locale object is contained.
public void setHiRes(int[] x, int[] y, int[] z) public void setHiRes(HiResCoord hiRes) public void getHiRes(HiResCoord hiRes)These methods set or get the high-resolution coordinate of this Locale.
public void addBranchGraph(BranchGroup branchGroup) public void removeBranchGraph(BranchGroup branchGroup) public void replaceBranchGraph(BranchGroup oldGroup, BranchGroup newGroup) public int numBranchGraphs() public Enumeration getAllBranchGraphs()The first three methods add, remove, and replace a branch graph in this Locale. Adding a branch graph has the effect of making the branch graph "live." The fourth method retrieves the number of branch graphs in this Locale. The last method retrieves an Enumeration object of all branch graphs.
3.6.3
A high-resolution coordinate consists of three two's-complement fixed-point numbers. Each high-resolution number consists of 256 total bits with a binary point at bit 128. Java 3D uses integer arrays of length eight to define or extract a single 256-bit coordinate value. Java 3D interprets the integer at index zero as the 32 most-significant bits and the integer at index 7 as the 32 least-significant bits.
Constructors
The HiResCoord object has the following constructors.
public HiResCoord(int[] x, int[] y, int[] z) public HiResCoord(HiResCoord hc) public HiResCoord()The first constructor generates the high-resolution coordinate from three integer arrays of length eight. The integer arrays specify the coordinate values corresponding with their name. The second constructor creates a new high-resolution coordinate by cloning the high resolution coordinate
hc. The third constructor creates a new high-resolution coordinate with value (0.0, 0.0, 0.0).Methods
public void setHiResCoord(int[] x, int[] y, int[] z) public void setHiResCoord(HiResCoord hiRes) public void setHiResCoordX(int[] x) public void setHiResCoordY(int[] y) public void setHiResCoordZ(int[] z)These five methods modify the value of high-resolution coordinate
this. The first method resets all three coordinate values with the values specified by the three integer arrays. The second method sets the value ofthisto that of high-resolution coordinatehiRes. The third, fourth, and fifth methods reset the corresponding coordinate ofthis.public void getHiResCoord(int[] x, int[] y, int[] z) public void getHiResCoord(HiResCoord hc) public void getHiResCoordX(int[] x) public void getHiResCoordY(int[] y) public void getHiResCoordZ(int[] z)These five methods retrieve the value of the high-resolution coordinate
this. The first method retrieves the high-resolution coordinate's value and places that value into the three integer arrays specified. All three arrays must have length greater than or equal to eight. The second method updates the value of the high-resolution coordinatehcto match the value ofthis. The third, fourth, and fifth methods retrieve the coordinate value that corresponds to their name and update the integer array specified, which must be of length eight or greater.public void add(HiResCoord h1, HiResCoord h2) public void sub(HiResCoord h1, HiResCoord h2)These two methods perform arithmetic operations on high-resolution coordinates. The first method adds
h1toh2and stores the result inthis. The second method subtractsh2fromh1and stores the result inthis.public void scale(int scale, HiResCoord h1) public void scale(int scale)These methods scale a high resolution coordinate. The first method scales
h1by the scalar valuescaleand places the scaled coordinate intothis. The second method scalesthisby the scalar value scale and places the scaled coordinate back intothis.public void negate(HiResCoord h1) public void negate()These two methods negate a high resolution coordinate. The first method negates
h1and stores the result inthis. The second method negatesthisand stores its negated value back intothis.public void difference(HiResCoord h1, Vector3d v)This method subtracts
h1fromthisand stores the resulting difference vector in the double-precision floating-point vectorv. Note that although the individual high-resolution coordinates cannot be represented accurately by double precision numbers, this difference vector between them can be accurately represented by doubles for many practical purposes, such as viewing.public boolean equals(HiResCoord h1)This method performs an arithmetic comparison between
thisandh1. It returns a true if the two high-resolution coordinates are equal, otherwise it returns a false.public double distance(HiResCoord h1)This method computes the linear distance between high-resolution coordinates
thisandh1, and returns this value expressed as a double. Note that although the individual high-resolution coordinates cannot be represented accurately by double precision numbers, this distance between them can be accurately represented by a double for many practical purposes.
Java 3D API Specification
Copyright © 1997, Sun Microsystems, Inc. All rights reserved.