diff options
| author | Kevin Rushforth <[email protected]> | 2005-10-26 23:43:42 +0000 |
|---|---|---|
| committer | Kevin Rushforth <[email protected]> | 2005-10-26 23:43:42 +0000 |
| commit | f2b8bc72cac9b037636cae419b57219da7f42886 (patch) | |
| tree | 68676bcfd4a25d5c996d83c9897570c3c2d9b10f /src | |
| parent | 88dba20f8d32240c535341b4e16e9218a715acc7 (diff) | |
1. Added package description.
2. Added introductory material from former specification guide (since that is no longer being maintained).
3. Put copyright notice at bottom of all javadoc pages.
git-svn-id: https://svn.java.net/svn/j3d-core~svn/trunk@450 ba19aa83-45c5-6ac9-afd3-db810772062c
Diffstat (limited to 'src')
15 files changed, 702 insertions, 6 deletions
diff --git a/src/classes/build.xml b/src/classes/build.xml index 1cd3cc1..cb166b3 100644 --- a/src/classes/build.xml +++ b/src/classes/build.xml @@ -192,7 +192,15 @@ </jar> </target> - <target name="docs-jcp"> + <target name="setup-docs"> + <!-- use javadoc.bottom.new once we have the spec license from the JCP PMO --> + <property name="javadoc.bottom.new" + value="<font size="-1">Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to <a href="{@docRoot}/LICENSE-SPEC.html">license terms</a>."/> + <property name="javadoc.bottom" + value="<font size="-1">Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms."/> + </target> + + <target name="docs-jcp" depends="setup-docs"> <!-- Create the build directory structure used by docs --> <mkdir dir="${build}/${platform}/javadocs/docs-jcp"/> @@ -201,6 +209,7 @@ javax.vecmath.*" maxmemory="128m" destdir="${build}/${platform}/javadocs/docs-jcp" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> <sourcepath> <pathelement location="${src}/classes/share"/> @@ -210,13 +219,14 @@ </sourcepath> </javadoc> - <!-- Copy the copyright file --> + <!-- Copy the copyright and license files --> <copy todir="${build}/${platform}/javadocs/docs-jcp"> <fileset dir="${src}/.." includes="COPYRIGHT.txt"/> + <fileset dir="${src}/.." includes="LICENSE-SPEC.html"/> </copy> </target> - <target name="docs-private"> + <target name="docs-private" depends="setup-docs"> <!-- Create the build directory structure used by docs --> <mkdir dir="${build}/${platform}/javadocs/docs-private"/> @@ -241,6 +251,7 @@ maxmemory="128m" private="true" destdir="${build}/${platform}/javadocs/docs-private" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> <sourcepath> <pathelement location="${src}/classes/share"/> @@ -251,13 +262,14 @@ </sourcepath> </javadoc> - <!-- Copy the copyright file --> + <!-- Copy the copyright and license files --> <copy todir="${build}/${platform}/javadocs/docs-private"> <fileset dir="${src}/.." includes="COPYRIGHT.txt"/> + <fileset dir="${src}/.." includes="LICENSE-SPEC.html"/> </copy> </target> - <target name="docs-public"> + <target name="docs-public" depends="setup-docs"> <!-- Create the build directory structure used by docs --> <mkdir dir="${build}/${platform}/javadocs/docs-public"/> @@ -271,6 +283,7 @@ com.sun.j3d.utils.scenegraph.io.state.*" maxmemory="128m" destdir="${build}/${platform}/javadocs/docs-public" + bottom="${javadoc.bottom}" windowtitle="Java 3D ${version}"> <sourcepath> <pathelement location="${src}/classes/share"/> @@ -280,9 +293,10 @@ </sourcepath> </javadoc> - <!-- Copy the copyright file --> + <!-- Copy the copyright and license files --> <copy todir="${build}/${platform}/javadocs/docs-public"> <fileset dir="${src}/.." includes="COPYRIGHT.txt"/> + <fileset dir="${src}/.." includes="LICENSE-SPEC.html"/> </copy> </target> diff --git a/src/classes/share/javax/media/j3d/doc-files/Behaviors.html b/src/classes/share/javax/media/j3d/doc-files/Behaviors.html new file mode 100644 index 0000000..f6c4d00 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Behaviors.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Behaviors and Interpolators</title> +</head> +<body> +<h2>Behaviors and Interpolators</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/Concepts.html b/src/classes/share/javax/media/j3d/doc-files/Concepts.html new file mode 100644 index 0000000..e445240 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Concepts.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Concepts</title> +</head> +<body> +<h2>Java 3D Concepts</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/DAG.gif b/src/classes/share/javax/media/j3d/doc-files/DAG.gif Binary files differnew file mode 100644 index 0000000..8479136 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/DAG.gif diff --git a/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html b/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html new file mode 100644 index 0000000..5e37bd6 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/HelloUniverse.html @@ -0,0 +1,21 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>HelloUniverse</title> +</head> +<body> +<h2>HelloUniverse: A Sample Java +3D Program</h2> +<p>Here are code fragments from a simple program, <code>HelloUniverse.java</code>, +that creates a cube and a RotationInterpolator behavior object that +rotates the cube at a constant rate of pi/2 radians per second. The +HelloUniverse class creates the branch graph +that includes the cube and the RotationInterpolator behavior. It then +adds this branch graph to the Locale object generated by the +SimpleUniverse utility. +</p> +<pre><hr><br>public class HelloUniverse ... {<br> public BranchGroup createSceneGraph() {<br><i> // Create the root of the branch graph<br></i> BranchGroup objRoot = new BranchGroup();<br><br><i> // Create the TransformGroup node and initialize it to the<br> // identity. Enable the TRANSFORM_WRITE capability so that<br> // our behavior code can modify it at run time. Add it to<br> // the root of the subgraph.<br></i> TransformGroup objTrans = new TransformGroup();<br> objTrans.setCapability(<br> TransformGroup.ALLOW_TRANSFORM_WRITE);<br> objRoot.addChild(objTrans);<br><br><i> // Create a simple Shape3D node; add it to the scene graph.<br></i> objTrans.addChild(new ColorCube(0.4));<br><br><i> // Create a new Behavior object that will perform the<br> // desired operation on the specified transform and add<br> // it into the scene graph.<br></i> Transform3D yAxis = new Transform3D();<br> Alpha rotationAlpha = new Alpha(-1, 4000);<br> RotationInterpolator rotator = new RotationInterpolator(<br> rotationAlpha, objTrans, yAxis,<br> 0.0f, (float) Math.PI*2.0f);<br> BoundingSphere bounds =<br> new BoundingSphere(new Point3d(0.0,0.0,0.0), 100.0);<br> rotator.setSchedulingBounds(bounds);<br> objRoot.addChild(rotator);<br><br><i> // Have Java 3D perform optimizations on this scene graph.</i><br> objRoot.compile();<br><br> return objRoot;<br> }<br><br> public HelloUniverse() {<br><i> <set layout of container, construct canvas3d, add canvas3d><br><br> // Create the scene; attach it to the virtual universe<br></i> BranchGroup scene = createSceneGraph();<br> SimpleUniverse u = new SimpleUniverse(canvas3d);<br> u.getViewingPlatform().setNominalViewingTransform();<br> u.addBranchGraph(scene);<br> }<br>}</pre> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/Immediate.html b/src/classes/share/javax/media/j3d/doc-files/Immediate.html new file mode 100644 index 0000000..ab85602 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Immediate.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Immediate-Mode Rendering</title> +</head> +<body> +<h2>Immediate-Mode Rendering</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/Rendering.html b/src/classes/share/javax/media/j3d/doc-files/Rendering.html new file mode 100644 index 0000000..580931a --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/Rendering.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Execution and Rendering Model</title> +</head> +<body> +<h2>Execution and Rendering Model</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html b/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html new file mode 100644 index 0000000..f10b9a1 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/SceneGraphOverview.html @@ -0,0 +1,230 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Scene Graph Overview</title> +</head> +<body> +<h2>Scene Graph Basics</h2> +<p>A scene graph consists of Java 3D +objects, called <em>nodes</em>, +arranged in a tree structure. The user creates one or more scene +subgraphs and attaches them to a virtual universe. The individual +connections between Java 3D nodes always represent a directed +relationship: parent to child. Java 3D restricts scene graphs in one +major way: Scene graphs may not contain cycles. Thus, a Java 3D scene +graph is a directed acyclic graph (DAG). See <a href="#Figure_1">Figure +1</a>. +</p> +<p>Java 3D refines the <a href="../Node.html">Node</a> object class +into two subclasses: <a href="../Group.html">Group</a> +and +<a href="../Leaf.html">Leaf</a> node objects. Group node objects group +together one or more child +nodes. A group node can point to zero or more children but can have +only one parent. The SharedGroup node cannot have any parents (although +it allows sharing portions of a scene graph, as described in "<a + href="SceneGraphSharing.html">Reusing Scene Graphs</a>"). +Leaf node objects contain the actual definitions of shapes (geometry), +lights, fog, sounds, and so forth. A leaf node has no children and only +one parent. The semantics of the various group and leaf nodes are +described in subsequent chapters. </p> +<h2>Scene Graph Structure</h2> +<p>A scene graph organizes and controls the rendering +of its constituent objects. The Java 3D renderer draws a scene graph in +a consistent way that allows for concurrence. The Java 3D renderer can +draw one object independently of other objects. Java 3D can allow such +independence because its scene graphs have a particular form and cannot +share state among branches of a tree. +</p> +<h3>Spatial Separation</h3> +<p>The hierarchy of the scene graph encourages a natural spatial +grouping +on the geometric objects found at the leaves of the graph. Internal +nodes act to group their children together. A group node also defines a +spatial bound that contains all the geometry defined by its +descendants. Spatial grouping allows for efficient implementation of +operations such as proximity detection, collision detection, view +frustum culling, and occlusion culling. +</p> +<p><a name="Figure_1"></a><img style="width: 500px; height: 341px;" + alt="Directed Acyclic Graph" title="Directed Acyclic Graph" + src="DAG.gif"></p> +<p> </p> +<ul> + <font size="-1"><b><i>Figure 1</i> – A Java +3D Scene Graph Is a DAG +(Directed Acyclic Graph)</b></font> +</ul> +<p> </p> +<h3>State Inheritance</h3> +<p>A leaf node's state is defined by the nodes in a direct path between +the scene graph's root and the leaf. Because a leaf's graphics context +relies only on a linear path between the root and that node, the Java +3D renderer can decide to traverse the scene graph in whatever order it +wishes. It can traverse the scene graph from left to right and top to +bottom, in level order from right to left, or even in parallel. The +only exceptions to this rule are spatially bounded attributes such as +lights and fog. +</p> +<p>This characteristic is in marked contrast to many older scene +graph-based APIs (including PHIGS and SGI's Inventor) where, if a node +above or to the left of a node changes the graphics state, the change +affects the graphics state of all nodes below it or to its right. </p> +<p>The most common node object, along the path from the root to the +leaf, +that changes the graphics state is the TransformGroup object. The +TransformGroup object can change the position, orientation, and scale +of the objects below it. </p> +<p>Most graphics state attributes are set by a Shape3D leaf node +through +its constituent Appearance object, thus allowing parallel rendering. +The Shape3D node also has a constituent Geometry object that specifies +its geometry-this permits different shape objects to share common +geometry without sharing material attributes (or vice versa). </p> +<p> </p> +<h3>Rendering</h3> +<p>The Java 3D renderer incorporates all graphics state changes made in +a +direct path from a scene graph root to a leaf object in the drawing of +that leaf object. Java 3D provides this semantic for both retained and +compiled-retained modes. +</p> +<p> </p> +<h2>Scene Graph Objects</h2> +<p>A Java 3D scene graph consists of a collection of Java 3D node +objects +connected in a tree structure. These node objects reference other scene +graph objects called <em>node component objects</em>. +All scene graph node and component objects are subclasses of a common +<a href="../SceneGraphObject.html">SceneGraphObject</a> class. The +SceneGraphObject class is an abstract class +that defines methods that are common among nodes and component objects. +</p> +<p>Scene graph objects are constructed by creating a new instance of +the +desired class and are accessed and manipulated using the object's <code>set</code> +and <code>get</code> +methods. Once a scene graph object is created and connected to other +scene graph objects to form a subgraph, the entire subgraph can be +attached to a virtual universe---via a high-resolution <a + href="../Locale.html">Locale</a> +object-making the object <em>live</em>. Prior to attaching a subgraph +to a virtual +universe, the entire subgraph can be <em>compiled</em> into an +optimized, internal format (see the +<code><a href="../BranchGroup.html#compile%28%29">BranchGroup.compile()</a></code> +method). </p> +<p>An important characteristic of all scene graph objects is that +they can +be accessed or modified only during the creation of a scene graph, +except where explicitly allowed. Access to most <code>set</code> and <code>get</code> +methods of objects that are part of a live or compiled scene graph is +restricted. Such restrictions provide the scene graph compiler with +usage information it can use in optimally compiling or rendering a +scene graph. Each object has a set of capability bits that enable +certain functionality when the object is live or compiled. By default, +all capability bits are disabled (cleared). Only those <code>set</code> +and <code>get</code> +methods corresponding to capability bits that are explicitly enabled +(set) prior to the object being compiled or made live are legal.<br> +</p> +<p> </p> +<h2>Scene Graph Superstructure +Objects</h2> +Java 3D defines two scene graph superstructure objects, +<a href="../VirtualUniverse.html">VirtualUniverse</a> +and <a href="../Locale.html">Locale</a>, which are used to contain +collections of subgraphs that +comprise the scene graph. These objects are described in more detail in +"<a href="VirtualUniverse.html">Scene Graph Superstructure</a>." +<p> </p> +<h3>VirtualUniverse Object</h3> +A <a href="../VirtualUniverse.html">VirtualUniverse</a> object +consists of a list of Locale objects that +contain a collection of scene graph nodes that exist in the universe. +Typically, an application will need only one VirtualUniverse, even for +very large virtual databases. Operations on a VirtualUniverse include +enumerating the Locale objects contained within the universe. See "<a + href="VirtualUniverse.html#VirtualUniverse">Scene Graph +Superstructure: VirtualUniverse Object</a>," for more information. +<p> </p> +<h3>Locale Object</h3> +The <a href="../Locale.html">Locale</a> object acts as a container for +a collection of subgraphs of +the scene graph that are rooted by a BranchGroup node. A Locale also +defines a location within the virtual universe using high-resolution +coordinates (HiResCoord) to specify its position. The HiResCoord serves +as the origin for all scene graph objects contained within the Locale. +<p>A Locale has no parent in the scene graph but is implicitly +attached to +a virtual universe when it is constructed. A Locale may reference an +arbitrary number of BranchGroup nodes but has no explicit children. </p> +<p>The coordinates of all scene graph objects are relative to the +HiResCoord of the Locale in which they are contained. Operations on a +Locale include setting or getting the HiResCoord of the Locale, adding +a subgraph, and removing a subgraph (see "<a + href="VirtualUniverse.html#Locale">Scene Graph Superstructure: Locale +Object</a>," for more information). </p> +<p> </p> +<h2>Scene Graph Viewing Objects</h2> +Java 3D defines five scene graph viewing objects that are not part of +the scene graph per se but serve to define the viewing parameters and +to provide hooks into the physical world. These objects are <a + href="../Canvas3D.html">Canvas3D</a>, +<a href="../Screen3D.html">Screen3D</a>, <a href="../View.html">View</a>, +<a href="../PhysicalBody.html">PhysicalBody</a>, and <a + href="../PhysicalEnvironment.html">PhysicalEnvironment</a>. They are +described in more detail in the "<a href="ViewModel.html">View Model</a>" +document.<br> +<p> </p> +<h3>Canvas3D Object</h3> +The <a href="../Canvas3D.html">Canvas3D</a> object encapsulates all of +the parameters associated with +the window being rendered into. +When a Canvas3D object is attached to a View object, the Java 3D +traverser renders the specified view onto the canvas. Multiple Canvas3D +objects can point to the same View object. +<p> </p> +<h3>Screen3D Object</h3> +The <a href="../Screen3D.html">Screen3D</a> object encapsulates all of +the +parameters associated with the physical screen containing the canvas, +such as the width and height of the screen in pixels, the physical +dimensions of the screen, and various physical calibration values. +<p> </p> +<h3>View Object</h3> +The <a href="../View.html">View</a> object specifies information +needed to render the scene graph. +<a href="#Figure_2">Figure +2</a> shows a View object attached to a simple scene graph for +viewing the scene. +<p>The View object is the central Java 3D object for coordinating all +aspects of viewing. +All viewing parameters in Java 3D are directly contained either within +the View object or within objects pointed to by a View object. Java 3D +supports multiple simultaneously active View objects, each of which can +render to one or more canvases. </p> +<p> </p> +<h3>PhysicalBody Object</h3> +The PhysicalBody object encapsulates all of the +parameters associated with the physical body, such as head position, +right and left eye position, and so forth. +<p> </p> +<h3>PhysicalEnvironment Object</h3> +<p>The PhysicalEnvironment object encapsulates all of the parameters +associated with the physical environment, such as calibration +information for the tracker base for the head or hand tracker.<br> +</p> +<p><a name="Figure_2"></a><br> +</p> +<p><img style="width: 489px; height: 339px;" alt="Viewing a Scene Graph" + title="Viewing a Scene Graph" src="ViewBranch.gif"> +</p> +<p> </p> +<ul> + <font size="-1"><b><i>Figure 2</i> – Viewing a Scene Graph</b></font> +</ul> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html b/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html new file mode 100644 index 0000000..ba707ef --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/SceneGraphSharing.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Reusing Scene Graphs</title> +</head> +<body> +<h2>Reusing Scene Graphs</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif b/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif Binary files differnew file mode 100644 index 0000000..75cc40d --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/ViewBranch.gif diff --git a/src/classes/share/javax/media/j3d/doc-files/ViewModel.html b/src/classes/share/javax/media/j3d/doc-files/ViewModel.html new file mode 100644 index 0000000..b13bd37 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/ViewModel.html @@ -0,0 +1,12 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - View Model</title> +</head> +<body> +<h2>View Model +</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html b/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html new file mode 100644 index 0000000..c4afb99 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/VirtualUniverse.html @@ -0,0 +1,11 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>Java 3D API - Scene Graph Superstructure</title> +</head> +<body> +<h2>Scene Graph Superstructure</h2> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/doc-files/intro.gif b/src/classes/share/javax/media/j3d/doc-files/intro.gif Binary files differnew file mode 100644 index 0000000..503f818 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/intro.gif diff --git a/src/classes/share/javax/media/j3d/doc-files/intro.html b/src/classes/share/javax/media/j3d/doc-files/intro.html new file mode 100644 index 0000000..ee53c66 --- /dev/null +++ b/src/classes/share/javax/media/j3d/doc-files/intro.html @@ -0,0 +1,319 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>The Java 3D API - Introduction</title> +</head> +<body> +<h2>Introduction to the Java 3D API</h2> +<p>The Java 3D API is an application +programming interface used for writing three-dimensional graphics +applications and applets. It gives developers high-level constructs for +creating and manipulating 3D geometry and for constructing the +structures used in rendering that geometry. Application developers can +describe very large virtual worlds using these constructs, which +provide Java 3D with enough information to render these worlds +efficiently. +</p> +<p>Java 3D delivers Java's "write once, run anywhere" +benefit to +developers of 3D graphics applications. Java 3D is part of the +JavaMedia suite of APIs, making it available on a wide range of +platforms. It also integrates well with the Internet because +applications and applets written using the Java 3D API have access to +the entire set of Java classes. +</p> +<p>The Java 3D API draws its ideas from existing +graphics APIs and from +new technologies. Java 3D's low-level graphics constructs synthesize +the best ideas found in low-level APIs such as Direct3D, OpenGL, +QuickDraw3D, and XGL. Similarly, its higher-level constructs synthesize +the best ideas found in several scene graph-based systems. Java 3D +introduces some concepts not commonly considered part of the graphics +environment, such as 3D spatial sound. Java 3D's sound capabilities +help to provide a more immersive experience for the user.<br> +</p> +<p><i>NOTE: Prior to version 1.4, the +Java 3D API was formally specified by a +separate Java 3D API Specification Guide, published separately +from the javadoc. As of version 1.4, +the javadoc-generated API reference is definitive. Relevant portions of +the guide have been included here and supersede any previously +published +information.</i> +</p> +<p> +</p> +<h2>Programming Paradigm</h2> +Java 3D is an object-oriented API. Applications construct individual +graphics elements as separate objects and connect them together into a +treelike structure called a <em>scene graph</em>. The application +manipulates these objects using their predefined accessor, mutator, and +node-linking methods. +<h3>The Scene Graph Programming +Model</h3> +Java 3D's scene graph-based programming model provides a simple and +flexible mechanism for representing and rendering scenes. The scene +graph contains a complete description of the entire scene, or virtual +universe. This includes the geometric data, the attribute information, +and the viewing information needed to render the scene from a +particular point of view. The "<a href="SceneGraphOverview.html">Scene +Graph Basics</a>" document provides more information on the Java 3D +scene graph programming model. +<p>The Java 3D API improves on previous graphics APIs +by eliminating many +of the bookkeeping and programming chores that those APIs impose. Java +3D allows the programmer to think about geometric objects rather than +about triangles-about the scene and its composition rather than about +how to write the rendering code for efficiently displaying the scene. +</p> +<p> +</p> +<h3>Rendering Modes</h3> +Java 3D includes three different rendering modes: immediate mode, +retained mode, and compiled-retained mode (see "<a href="Rendering.html">Execution +and Rendering Model</a>"). +Each successive rendering mode allows Java 3D more freedom in +optimizing an application's execution. Most Java 3D applications will +want to take advantage of the convenience and performance benefits that +the retained and compiled-retained modes provide. +<h4>Immediate Mode</h4> +Immediate mode leaves little room for global +optimization at the scene graph level. Even so, Java 3D has raised the +level of abstraction and accelerates immediate mode rendering on a +per-object basis. An application must provide a Java 3D draw method +with a complete set of points, lines, or triangles, which are then +rendered by the high-speed Java 3D renderer. Of course, the application +can build these lists of points, lines, or triangles in any manner it +chooses. +<h4>Retained Mode</h4> +Retained mode requires an application to construct a scene graph and +specify which elements of that scene graph may change during rendering. +The scene graph describes the objects in the virtual universe, the +arrangement of those objects, and how the application animates those +objects. +<h4>Compiled-Retained Mode</h4> +Compiled-retained mode, like retained mode, requires the application to +construct a scene graph and specify which elements of the scene graph +may change during rendering. Additionally, the application can compile +some or all of the subgraphs that make up a complete scene graph. Java +3D compiles these graphs into an internal format. The compiled +representation of the scene graph may bear little resemblance to the +original tree structure provided by the application, however, it is +functionally equivalent. Compiled-retained mode provides the highest +performance. +<h3>Extensibility</h3> +Most Java 3D classes expose only accessor and mutator methods. Those +methods operate only on that object's internal state, making it +meaningless for an application to override them. Therefore, Java 3D +does not provide the capability to override the behavior of Java 3D +attributes. To make Java 3D work correctly, applications must call "<code>super.setXxxxx</code>" +for any attribute state set method that is overridden. +<p>Applications can extend Java 3D's classes and add +their own methods. +However, they may not override Java 3D's scene graph traversal +semantics because the nodes do not contain explicit traversal and draw +methods. Java 3D's renderer retains those semantics internally. +</p> +<p>Java 3D <em>does</em> provide hooks for mixing +Java 3D-controlled scene graph rendering and user-controlled rendering +using Java 3D's immediate mode constructs (see "<a + href="Immediate.html#Mixed">Mixed-Mode Rendering</a>"). Alternatively, +the application can +stop Java 3D's renderer and do all its drawing in immediate mode (see "<a + href="Immediate.html#PureImmediate">Pure Immediate-Mode Rendering</a>"). +</p> +<p>Behaviors require applications to extend the +Behavior object and to +override its methods with user-written Java code. These extended +objects should contain references to those scene graph objects that +they will manipulate at run time. The "<a href="Behaviors.html">Behaviors +and Interpolators</a>" document describes Java 3D's behavior +model. +</p> +<p> +</p> +<h2>High Performance</h2> +Java 3D's programming model allows the Java 3D API to do the mundane +tasks, such as scene graph traversal, managing attribute state changes, +and so forth, thereby simplifying the application's job. Java 3D does +this without sacrificing performance. At first glance, it might appear +that this approach would create more work for the API; however, it +actually has the opposite effect. Java 3D's higher level of abstraction +changes not only the amount but, more important, also the kind of work +the API must perform. Java 3D does not need to impose the same type of +constraints as do APIs with a lower level of abstraction, thus allowing +Java 3D to introduce optimizations not possible with these lower-level +APIs. +<p>Additionally, leaving the details of rendering to +Java 3D allows it to +tune the rendering to the underlying hardware. For example, relaxing +the strict rendering order imposed by other APIs allows parallel +traversal as well as parallel rendering. Knowing which portions of the +scene graph cannot be modified at run time allows Java 3D to flatten +the tree, pretransform geometry, or represent the geometry in a native +hardware format without the need to keep the original data. +</p> +<p> +</p> +<h3>Layered Implementation</h3> +Besides optimizations at the scene graph level, one of the more +important factors that determines the performance of Java 3D is the +time it takes to render the visible geometry. Java 3D implementations +are layered to take advantage of the native, low-level API that is +available on a given system. In particular, Java 3D implementations +that use Direct3D and OpenGL are available. This means that Java 3D +rendering will be accelerated across the same wide range of systems +that are supported by these lower-level APIs. +<h3>Target Hardware Platforms</h3> +Java 3D is aimed at a wide range of 3D-capable hardware and software +platforms, from low-cost PC game cards and software renderers at the +low end, through midrange workstations, all the way up to very +high-performance specialized 3D image generators. +<p>Java 3D implementations are expected to provide +useful rendering rates +on most modern PCs, especially those with 3D graphics accelerator +cards. On midrange workstations, Java 3D is expected to provide +applications with nearly full-speed hardware performance. +</p> +<p>Finally, Java 3D is designed to scale as the +underlying hardware +platforms increase in speed over time. Tomorrow's 3D PC game +accelerators will support more complex virtual worlds than high-priced +workstations of a few years ago. Java 3D is prepared to meet this +increase in hardware performance. +</p> +<p> +</p> +<h2>Structuring the Java 3D Program</h2> +<p>This section illustrates how a developer might +structure a Java 3D application. The simple application in this example +creates a scene graph that draws an object in the middle of a window +and rotates the object about its center point. +</p> +<h3>Java 3D Application Scene +Graph</h3> +<p>The scene graph for the sample application is shown below. +</p> +<p>The scene graph consists of superstructure +components—a VirtualUniverse +object and a Locale object—and a set of branch graphs. Each branch +graph is a subgraph that is rooted by a BranchGroup node that is +attached to the superstructure. For more information, see "<a + href="SceneGraphOverview.html">Scene Graph Basics</a>." +</p> +<p> +<img style="width: 500px; height: 263px;" alt="Application scene graph" + title="Application scene graph" src="intro.gif"></p> +<p> +</p> +<ul> + <font size="-1"><b><i>Figure 1 – </i>Application Scene Graph</b></font> +</ul> +<p> +A VirtualUniverse object defines a named universe. Java 3D permits the +creation of more than one universe, though the vast majority of +applications will use just one. The VirtualUniverse object provides a +grounding for scene graphs. All Java 3D scene graphs must connect to a +VirtualUniverse object to be displayed. For more information, see "<a + href="VirtualUniverse.html">Scene Graph Superstructure</a>." +</p> +<p>Below the VirtualUniverse object is a Locale object. +The Locale object +defines the origin, in high-resolution coordinates, of its attached +branch graphs. A virtual universe may contain as many Locales as +needed. In this example, a single Locale object is defined with its +origin at (0.0, 0.0, 0.0). +</p> +<p>The scene graph itself starts with the <a href="../BranchGroup.html">BranchGroup</a> +nodes. +A BranchGroup serves as the root of a +subgraph, called a <em>branch graph</em>, of the scene graph. Only +BranchGroup objects can attach to Locale objects. +</p> +<p>In this example there are two branch graphs and, +thus, two BranchGroup +nodes. Attached to the left BranchGroup are two subgraphs. One subgraph +consists of a user-extended Behavior leaf node. The Behavior node +contains Java code for manipulating the transformation matrix +associated with the object's geometry. +</p> +<p>The other subgraph in this BranchGroup consists of a +TransformGroup +node that specifies the position (relative to the Locale), orientation, +and scale of the geometric objects in the virtual universe. A single +child, a Shape3D leaf node, refers to two component objects: a Geometry +object and an Appearance object. The Geometry object describes the +geometric shape of a 3D object (a cube in our simple example). The +Appearance object describes the appearance of the geometry (color, +texture, material reflection characteristics, and so forth). +</p> +<p>The right BranchGroup has a single subgraph that +consists of a +TransformGroup node and a ViewPlatform leaf node. The TransformGroup +specifies the position (relative to the Locale), orientation, and scale +of the ViewPlatform. This transformed ViewPlatform object defines the +end user's view within the virtual universe. +</p> +<p>Finally, the ViewPlatform is referenced by a View +object that specifies +all of the parameters needed to render the scene from the point of view +of the ViewPlatform. Also referenced by the View object are other +objects that contain information, such as the drawing canvas into which +Java 3D renders, the screen that contains the canvas, and information +about the physical environment. +</p> +<p> +</p> +<h3>Recipe for a Java 3D Program</h3> +<p>The following steps are taken by the example program to create the +scene graph elements and link them together. Java 3D will then render +the scene graph and display the graphics in a window on the screen:</p> +<ul> +1. Create a Canvas3D object and add it to the Applet panel. + <p>2. Create a BranchGroup as the root of the scene branch graph.</p> + <p>3. Construct a Shape3D node with a TransformGroup node above it.</p> + <p>4. Attach a RotationInterpolator behavior to the TransformGroup.</p> + <p>5. Call the simple universe utility function to do the following:</p> + <ul> +a. Establish a virtual universe with a single high-resolution Locale +(see "<a href="SceneGraphOverview.html">Scene Graph Basics</a>"). + <p>b. Create the PhysicalBody, PhysicalEnvironment, View, and +ViewPlat-form objects.</p> + <p>c. Create a BranchGroup as the root of the view platform branch +graph.</p> + <p>d. Insert the view platform branch graph into the Locale.</p> + </ul> +6. Insert the scene branch graph into the simple universe's Locale. +</ul> +<p>The Java 3D renderer then starts running in an infinite loop. The +renderer conceptually performs the following operations:</p> +<pre> while(true) {<br> Process input<br> If (request to exit) break<br> Perform Behaviors<br> Traverse the scene graph and render visible objects<br> }<br> Cleanup and exit<br></pre> +<h3>HelloUniverse: A Sample Java +3D Program</h3> +<p><a href="HelloUniverse.html">Click here</a> to see code fragments +from a simple program, <code>HelloUniverse.java</code>, +that creates a cube and a RotationInterpolator behavior object that +rotates the cube at a constant rate of pi/2 radians per second.<br> +</p> +<h2>Other Documents<br> +</h2> +<p>Here are other documents that provide explanatory material, +previously included as part of +the Java 3D API Specification Guide.<br> +</p> +<ul> + <li><a href="Concepts.html">Java 3D Concepts</a></li> + <li><a href="SceneGraphOverview.html">Scene Graph Basics</a></li> + <li><a href="VirtualUniverse.html">Scene Graph Superstructure</a></li> + <li><a href="SceneGraphSharing.html">Reusing Scene Graphs</a></li> + <li><a href="ViewModel.html">View Model</a></li> + <li><a href="Behaviors.html">Behaviors and Interpolators</a></li> + <li><a href="Rendering.html">Execution and Rendering Model</a></li> + <li><a href="Immediate.html">Immediate-Mode Rendering</a></li> +</ul> +<p><br> +</p> +</body> +</html> diff --git a/src/classes/share/javax/media/j3d/package.html b/src/classes/share/javax/media/j3d/package.html new file mode 100644 index 0000000..b8a3e9a --- /dev/null +++ b/src/classes/share/javax/media/j3d/package.html @@ -0,0 +1,34 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta content="text/html; charset=ISO-8859-1" + http-equiv="content-type"> + <title>javax.media.j3d</title> +</head> +<body> +<p>Provides the core set of classes for the +Java 3D<sup><font size="-2">TM</font></sup> API; <a + href="doc-files/intro.html">click here</a> for more information, +including explanatory material that was formerly found in the guide. +</p> +<p>The Java 3D API is an application +programming interface used for writing three-dimensional graphics +applications and applets. It gives developers high-level constructs for +creating and manipulating 3D geometry and for constructing the +structures used in rendering that geometry. Application developers can +describe very large virtual worlds using these constructs, which +provide Java 3D with enough information to render these worlds +efficiently. +</p> +<p><i>NOTE: Prior to version 1.4, the +Java 3D API was formally specified by a +separate Java 3D API Specification Guide, published separately +from the javadoc. As of version 1.4, +the javadoc-generated API reference is definitive. Relevant portions of +the guide have been included <a href="doc-files/intro.html">here</a> +and supersede any previously +published +information.</i> +</p> +</body> +</html> |
