| The Java 3D API Specification |
    |
| The Java 3D API Specification |
|
A P P E N D I X  G |
|
The Example Programs |
THIS appendix describes the example programs available for download from the Java 3D web site.
G.1
Before you can compile Java 3D applications or run the example programs, you need to have installed or you need to install the following software on your system:Introduction
- Java 2 SDK version 1.2 or later
- Java 3D API
The
- OpenGL
demo/java3ddirectory contains 37 subdirectories. All but two of these directories (geometryandimages) contain at least one example program. Some directories contain several example programs.
G.2
All of the example programs can be run as standalone applications from a UNIX shell or a DOS window. The syntax shown in this appendix is for UNIX. In DOS windows, you will need to replace "Running the Example Programs /" with "\" and specify the correct drive letter when referring to<jdkhome>(for example, "c:\jdk1.2.2").
Each of the other example programs can be run in a similar manner.
G.2.1
Java 2 applets, including many Java 3D example programs, can be run within a browser using Java Plug-in. Special HTML tags are required to cause Netscape or Internet Explorer to use the correct version of the Java 2 platform via Java Plug-in. All of the Java 3D example programs that can be run as applets include HTML files that have been converted to use Java Plug-in. Refer to the following URL for information on using Java Plug-in 1.2.2 HTML Converter to convert your own applets to run in a browser:Running within a Browser http://java.sun.com/products/plugin/On Windows, the Java Plug-in is automatically installed along with the Java 2 run-time environment. Applets can be run in either Netscape Communicator or Internet Explorer.http://www.sun.com/solaris/netscape/Additional patches may be required (see the website for details).The following page contains links to all of the Java 3D demos that can be run as applets:
<jdkhome>/demo/java3d/index.htmlJust click on the link for a given demo to run that demo within your browser.
G.2.2
To run Java 3D applets withinRunning within Appletviewer appletviewer, open the original, unconverted version of the associated HTML file (not the "_plugin" version). For example,
G.3
Several example programs are included in theProgram Descriptions demo/java3ddirectory. All of the example programs are described here. Code fragments are listed for a few of the example programs.
G.3.1
Directory:AWT_Interaction demo/java3d/AWT_InteractionThe relevant source code fragments from
AWT_Interaction.javafollow:This code creates instance variables for the current angle, the TransformGroup that will be modified, and a button that will trigger the modification. The AWTInteraction class implements ActionListener so that it can receive button press events. The
public class AWTInteraction extends Applet implements ActionListener { TransformGroup objTrans; float angle = 0.0f; Transform3D trans = new Transform3D(); Button rotateB = new Button("Rotate");createSceneGraphmethod (not shown here) creates a root BranchGroup, an object TransformGroup, and a color cube, much as in HelloUniverse.The constructor puts the Rotate button in a panel and adds the AWTInteraction class as an action listener for the button.
public AWTInteraction() { ... Panel p = new Panel(); p.add(rotateB); add("North", p); rotateB.addActionListener(this); ... }The
public void actionPerformed(ActionEvent e) { if (e.getSource() == rotateB) { angle += Math.toRadians(10); trans.rotY(angle); objTrans.setTransform(trans); } }actionPerformedmethod increments theangle, computes a new rotation matrix, and updates the object's TransformGroup. Since this is in an AWT event listener method rather than in a behavior, the transform update is not synchronized with the Java 3D renderer. In particular, if such an event listener method modifies two objects in the Java 3D scene graph, there is no guarantee that the effects of those two updates will be seen in the same frame. Also remember that it is never safe for two threads to modify the same Java 3D object simultaneously. This means that an object that is being updated by a behavior must not be modified by an AWT event listener.
G.3.2
Directory:AlternateAppearance demo/java3d/AlternateAppearance
G.3.3
Directory:Appearance demo/java3d/AppearanceThe above code, extracted from the
int row, col; Appearance[][] app = new Appearance[3][3]; for (row = 0; row < 3; row++) for (col = 0; col < 3; col++) app[row][col] = createAppearance(row * 3 + col); for (int i = 0; i < 3; i++) { double ypos = (double)(i - 1) * 0.6; for (int j = 0; j < 3; j++) { double xpos = (double)(j - 1) * 0.6; objRoot.addChild(createObject(app[i][j], 0.12, xpos, ypos)); } }createSceneGraphmethod, creates a 3 x 3 array of objects, each with its own Appearance, and adds them to the scene graph.
private Appearance createAppearance(int idx) { Appearance app = new Appearance(); // Globally used colorsColor3f black = new Color3f(0.0f, 0.0f, 0.0f); Color3f white = new Color3f(1.0f, 1.0f, 1.0f); switch (idx) { ... case 4: // Set up the texture mapTextureLoader tex = new TextureLoader(texImage, this); app.setTexture(tex.getTexture()); TextureAttributes texAttr = new TextureAttributes(); texAttr.setTextureMode(TextureAttributes.MODULATE); app.setTextureAttributes(texAttr); app.setMaterial(new Material(white, black, white, black, 1.0f)); break;For Appearance number 4, the TextureLoader utility is used to load a JPEG image from a file and create a Texture object. TextureAttributes are set up so that the lit color is blended with the texture map (MODULATE). Finally, a lighting Material object is created with a default color of white.
case 5: // Set up the transparency propertiesTransparencyAttributes ta = new TransparencyAttributes(); ta.setTransparencyMode(ta.BLENDED); ta.setTransparency(0.6f); app.setTransparencyAttributes(ta); // Set up the polygon attributesPolygonAttributes pa = new PolygonAttributes(); pa.setCullFace(pa.CULL_NONE); app.setPolygonAttributes(pa); // Set up the material propertiesColor3f objColor = new Color3f(0.7f, 0.8f, 1.0f); app.setMaterial(new Material(objColor, black, objColor, black, 1.0f)); break; ... return app; }For Appearance number 5, TransparencyAttributes are set up to use blended transparency with the object being 60 percent transparent. Back face culling is disabled in the PolygonAttributes object so that the front and back faces of the transparent object are visible. Finally, a lighting Material object is created with the specified object color.
G.3.4
Directory:AppearanceMixed demo/java3d/AppearanceMixedThe
static class MyCanvas3D extends Canvas3D { private GraphicsContext3D gc; ... private IndexedTriangleArray tri = new IndexedTriangleArray(4, IndexedTriangleArray.COORDINATES | IndexedTriangleArray.NORMALS, 6); private Point3f vert[]; private Vector3f normals[]; public void renderField(int fieldDesc) { computeVert(); computeNormals(); gc.draw(tri); } private void computeVert() { <modify vert[] array> ... tri.setCoordinates(0, vert); } private void computeNormals() { <compute new normals[] based on vert[] values> ... tri.setNormals(0, normals); }renderFieldmethod is called by Java 3D during the rendering loop for each frame. The AppearanceMixed example overrides this Canvas3D method to compute a new set of vertices and normals for the pair of triangles and to draw the triangles to the canvas. ThecomputeVertandcomputeNormalsupdate thevertandnormalsarray and then call the methods to copy these changes to the IndexedTriangleArray object.
public MyCanvas3D(GraphicsConfiguration gcfg) { super(gcfg); ... // Set up the graphics contextgc = getGraphicsContext3D(); // Create the appearance for the triangle fanAppearance app = new Appearance(); ... gc.setAppearance(app); // Set up the global lightsColor3f lColor1 = new Color3f(0.7f, 0.7f, 0.7f); Vector3f lDir1 = new Vector3f(-1.0f, -1.0f, -1.0f); Color3f alColor = new Color3f(0.2f, 0.2f, 0.2f); gc.addLight(new AmbientLight(alColor)); gc.addLight(new DirectionalLight(lColor1, lDir1)); }The constructor for MyCanvas creates a Graphics3D object and initializes its appearance and lights. Note that even though the scene graph also contains light objects, they are not used for immediate mode rendering-lights must be created and added to the graphics context in order for immediate mode geometry to be lit.
G.3.5
Directory:Background demo/java3d/Background
G.3.6
Directory:Billboard demo/java3d/Billboard
Note: Billboard's functionality has largely been superseded by OrientedShape3D.
G.3.7
Directory:ConicWorld demo/java3d/ConicWorldThis directory contains a README file and six demonstration programs:
- The ConicWorld program shows spheres, cylinders, and cones of different resolutions and colors.
- The SimpleCylinder program demonstrates a simple cylinder object. The left mouse button rotates the cylinder, and the middle button zooms.
- The BoxExample program demonstrates a rotating texture-mapped box. The left mouse button rotates the box, and the middle button zooms.
- The FlipCylinder program puts up a textured cylinder that can be rotated and zoomed with the mouse. The left mouse button rotates, the middle button zooms, and the right button translates.
These programs demonstrate the use of the geometry primitives in the
- The TexturedCone and TexturedSphere programs demonstrate the use of texture mapping with the Cone and Sphere primitives, respectively.
com.sun.j3d.utils.geometrypackage.
G.3.8
Directory:FourByFour demo/java3d/FourByFour
G.3.9
Directory:GearTest demo/java3d/GearTest
G.3.10
Directory:GeometryByReference demo/java3d/GeometryByReference
G.3.11
Directory:GeometryCompression demo/java3d/GeometryCompressionjava cgview <.cg file> [object-number]You can use one of the .cg resource files in thedemo/java3d/geometrydirectory. The following example will display a galleon (ship):
java obj2cg <.obj file> [<.obj file> ...] <.cg file>If the .cg file does not exist, it is created. If the file does exist and is a valid .cg resource file, the new object(s) are appended to the objects in the existing file. If it is not a valid .cg file, an exception is thrown.
G.3.12
Directory:HelloUniverse demo/java3d/HelloUniverseThe HelloUniverse program creates a cube and a RotationInterpolator behavior object that rotates the cube at a constant rate of
/2 radians per second. The code for this program is described in Section 1.6.3, "HelloUniverse: A Sample Java 3D Program."
G.3.13
Directory:LOD demo/java3d/LOD
G.3.14
Directory:Lightwave demo/java3d/Lightwavedirectory
will display a red cone moving behind a stationary green ball.
G.3.15
Directory:ModelClip demo/java3d/ModelClip
G.3.16
Directory:Morphing demo/java3d/Morphing
G.3.17
Directory:ObjLoad demo/java3d/ObjLoadThe ObjLoad program loads Wavefront object files. Run the program with the following command:
java ObjLoad [-s] [-n] [-t] [-c degrees] <.obj file>You can use one of the .obj files in the
- where the options are
-sSpin (no user interaction)
-nNo triangulation
-tNo stripification
-cSet crease angle for normal generation (default is 60 without smoothing group info, otherwise 180 within smoothing groups)
demo/java3d/geometrydirectory. The following example will display a galleon (ship):
The relevant source code fragment from
ObjLoad.javafollows:The above code fragment creates an ObjectFile loader with the desired flags and crease angle, loads the specified filename (checking for file and parsing exceptions), and adds the loaded objects to the scene graph. This code fragment could easily be modified to accommodate a variety of loaders.
public BranchGroup createSceneGraph(String args[]) { ... int flags = ObjectFile.RESIZE; ... ObjectFile f = new ObjectFile(flags, (float)(creaseAngle * Math.PI / 180.0)); Scene s = null; try { s = f.load(filename); } catch (FileNotFoundException e) { System.err.println(e); System.exit(1); } catch (ParsingErrorException e) { System.err.println(e); System.exit(1); } catch (IncorrectFormatException e) { System.err.println(e); System.exit(1); } objTrans.addChild(s.getSceneGroup());
G.3.18
Directory:OffScreenCanvas3D demo/java3d/OffScreenCanvas3D
G.3.19
Directory:OrientedShape3D demo/java3d/OrientedShape3D
G.3.20
Directory:PackageInfo demo/java3d/PackageInfo
G.3.21
Directory:PickTest demo/java3d/PickTestThe IntersectInfoBehavior class constructor creates a new PickCanvas object, initializes the PickCanvas with the desired tolerance, and sets the mode to allow geometry intersection information to be retrieved.
PickCanvas pickCanvas; PickResult[] pickResult; public IntersectInfoBehavior(Canvas3D canvas3D, BranchGroup branchGroup, float size) { pickCanvas = new PickCanvas(canvas3D, branchGroup); pickCanvas.setTolerance(5.0f); pickCanvas.setMode(PickCanvas.GEOMETRY_INTERSECT_INFO); ...
public void processStimulus(Enumeration criteria) { ... <check for mouse event>if (eventId == MouseEvent.MOUSE_PRESSED) { int x = ((MouseEvent)event[i]).getX(); int y = ((MouseEvent)event[i]).getY(); pickCanvas.setShapeLocation(x, y); Point3d eyePos = pickCanvas.getStartPosition(); pickResult = pickCanvas.pickAllSorted(); if (pickResult != null) { // Get node infoNode curNode = pickResult[0].getObject(); Geometry curGeom = ((Shape3D)curNode).getGeometry(); GeometryArray curGeomArray = (GeometryArray) curGeom; // Get closest intersection resultsPickIntersection pi = pickResult[0].getClosestIntersection(eyePos); <get specific info from PickIntersection>} } ...The processStimulus method checks for a mouse event and initiates a pick, via the PickCanvas object, at the selected location. It then looks for pick results and extracts the intersection information from the pick result (if any).
G.3.22
Directory:PickText3D demo/java3d/PickText3D
G.3.23
Directory:PlatformGeometry demo/java3d/PlatformGeometry
G.3.24
Directory:PureImmediate demo/java3d/PureImmediateThe relevant source code fragments from
PureImmediate.javafollow:
public class PureImmediate extends Applet implements Runnable { private Canvas3D canvas; private GraphicsContext3D gc = null; private Geometry cube = null; private Transform3D cmt = new Transform3D(); // One rotation (2*PI radians) every 6 secondsprivate Alpha rotAlpha = new Alpha(-1, 6000);The above code creates instance variables for a Canvas3D, the GraphicsContext associated with the canvas, a geometry object for drawing, a Transform3D object for rotation, and an alpha object to allow the rotation to be time-based. The PureImmediate class implements Runnable so that it can be run by a user-created drawing thread.
public void render() { if (gc == null) { // Set up Graphics contextgc = canvas.getGraphicsContext3D(); gc.setAppearance(new Appearance()); // Set up geometrycube = new ColorCube(0.4).getGeometry(); } // Compute angle of rotation based on alpha valuedouble angle = rotAlpha.value() * 2.0*Math.PI; cmt.rotY(angle); // Render the geometry for this framegc.clear(); gc.setModelTransform(cmt); gc.draw(cube); canvas.swap(); } public void run() { while (true) { render(); Thread.yield(); } }Therendermethod renders a single frame. After ensuring that the graphics context is set up and the geometry is created, it computes the new rotation matrix, clears the canvas, draws the cube, and swaps the draw and display buffer. Therunmethod is the entry point for our drawing thread. It calls therendermethod in a loop, yielding control to other threads once per frame.
public PureImmediate() { <set layout of applet, get best graphics config>canvas = new Canvas3D(config); canvas.stopRenderer(); add("Center", canvas); // Create the universe and viewing branchSimpleUniverse u = new SimpleUniverse(canvas); u.getViewingPlatform().setNominalViewingTransform(); // Start a new thread that will continuously rendernew Thread(this).start(); }The constructor creates the 3D canvas, stops the Java 3D renderer, sets up the viewing branch (necessary even in pure immediate mode), and starts up the drawing thread.
G.3.25
Directory:ReadRaster demo/java3d/ReadRaster
G.3.26
Directory:Sound demo/java3d/Sound
G.3.27
Directory:SphereMotion demo/java3d/SphereMotionjava SphereMotion [-dir | -point | -spot]G.3.28
Directory:SplineAnim demo/java3d/SplineAnimThe SplineAnim program demonstrates the use of KBRotPosScaleSplinePathInterpolator (see the description in Table F-10) to do spline animation paths using Kochanek-Bartels splines. A red cone is animated along a spline path specified by five knot points, which are shown as cyan spheres. Use the mouse to manipulate the scene.
G.3.29
Directory:Text2D demo/java3d/Text2DThe Text2DTest program shows three different types of 2D text using the Text2D utility class.
G.3.30
Directory:Text3D demo/java3d/Text3Djava Text3DLoadThe[-f fontname] [-t tesselation] <text>fontnamevariable allows you to specify one of the Java Font names, such as Helvetica, Times Roman, and Courier. Thetesselationvariable specifies how finely to tessellate the font glyphs. Once the text displays, the left mouse button rotates the text, the middle button zooms, and the right button translates.
G.3.31
Directory:TextureByReference demo/java3d/TextureByReference
G.3.32
Directory:TextureTest demo/java3d/TextureTestjava TextureImageThe<image-filename> [-f ImageComponent format]ImageComponent formatvariable allows you to specify the format of the pixel data. If you do not specify an image file, the rotating cube will appear white. You can use one of the image files in thedemo/java3d/imagesdirectory. For example:
will display the rotating cube with an image of earth mapped onto it.
G.3.33
Directory:TickTockCollision demo/java3d/TickTockCollision
G.3.34
Directory:TickTockPicking demo/java3d/TickTockPicking
G.3.35
Directory:VirtualInputDevice demo/java3d/VirtualInputDevice
| The Java 3D API Specification |
|