The Java 3D API Specification

A P P E N D I X G

THIS appendix describes how to install the software on the CD-ROM that came with this book. For descriptions of the program examples on the CD-ROM, see Appendix H, "The Example Programs."

G.1 What's on the CD-ROM

The Java 3D CD-ROM contains the following:

• The Java 2 SDK, Standard Edition, v 1.2.2 for Solaris/SPARC systems (Solaris 2.6 or subsequent compatible version)

• The Java 2 SDK, Standard Edition, v 1.2.2 for Windows (Windows 95, Windows 98, Windows NT, and Windows 2000)

• The Java 3D API Version 1.2, including the com.sun.j3d.* packages, for Solaris/SPARC systems

• The Java 3D API Version 1.2, including the com.sun.j3d.* packages, for Windows systems (OpenGL version)

• Sun OpenGL 1.2.1 for Solaris

• Example programs

• The javadocs and The Java 3D 1.2 API Specification (this book) in a browsable format (both html and Adobe Acrobat)

The Java 3D CD-ROM does not contain OpenGL for Windows, which is required to run Java 3D applications. See Section G.2.1, "Requirements for Windows Systems."

The CD-ROM contains an index.html file with the latest information that may not have made it into this book. This file also has more detailed installation instructions, if you find the need.

The index.html file can be read with any browser. If any information in this appendix contradicts the index.html file, assume that the index.html file is correct.

The CD-ROM also contains the following directories:

doc/	Contains the javadocs, and a browsable copy of this book
programs/	Contains example programs and demos
solaris/	Contains shell scripts for installing the Java 2 SDK, Java 3D, OpenGL, and any necessary patches on Solaris systems
win32/	Contains executable files for installing the Java 2 SDK and Java 3D on Windows systems

G.2 Installing the Software on Windows 95/98/NT Systems

G.2.1 Requirements for Windows Systems

The system on which the contents of the CD-ROM are installed should have

• At least 65 megabytes of free disk space for the Java 2 SDK

• At least 10 megabytes of free disk space for the Java 3D API

This version of Java 3D for Windows 95/98/NT requires OpenGL from Microsoft or a hardware accelerator that supports OpenGL 1.1 (or later). If you do not have OpenGL installed on your system, contact your hardware vendor or download OpenGL from:

http://www.opengl.org/

G.2.2 Installing the Java 2 SDK on Windows Systems

The installation program creates a directory C:\jdk1.2.2 where it puts both the Java 2 SDK and the Java 3D SDK. It also creates a directory C:\Program Files\Javasoft\1.2 where it puts the Java 2 JRE and Java 3D runtime.

To install the Java 2 SDK and Java 3D on a Windows system, follow these steps:

1. If your system does not already have OpenGL installed, install it before installing the CD-ROM (see Section G.2.1, "Requirements for Windows Systems").

2. Insert the CD-ROM in your CD-ROM drive.

3. Install the Java 2 SDK and JRE.

Open the win32 folder on the CD-ROM and execute the jdk1_2_2-001-win.exe file. Follow the instructions the installer program provides.

4. Add the full path of the jdk1.2.2\bin directory to the PATH variable.

Typically, the full path looks something like this:

        C:\jdk1.2.2\bin

5. Check the CLASSPATH variable.

Include "." in your CLASSPATH or ensure that CLASSPATH is not set.

6. Verify that Java is installed by typing the following:

> java -version java version "1.2.2" Classic VM (build JDK-1.2.2-001, native threads, symcjit)

If you do not get the java version "1.2.2" message, verify that the jdk1.2.2/bin directory is in your path in Step 4 above. If you get the above message, proceed to Section G.2.3, "Installing the Java 3D API on Windows Systems."

G.2.3 Installing the Java 3D API on Windows Systems

To install the Java 3D API, follow these steps:

1. Install the Java 3D SDK.

Execute the java3d1_2-win-opengl_sdk.exe file.

2. Install the Java 3D runtime.

Execute the java3d1_2-win-opengl-rt.exe file.

3. Verify that Java 3D is installed by typing the following:

> cd c:\jdk1.2.2\demo\java3d\HelloUniverse > java HelloUniverse

You should see a window with a multi-colored rotating cube.

4. See the README.Java3D-jdk file in the jdk.1.2.2 directory for more information about this release.

G.2.4 Installing the Javadocs on Windows Systems

The javadocs for Java 3D may be installed on your system for ready access. Alternatively, you may choose to save the disk space by not installing the javadocs and read them directly from the CD-ROM whenever needed (see Section G.4, "Accessing the Documentation from the CD-ROM").

You will need at least 10 megabytes of free disk space to install the Java 3D API javadocs.

The javadocs are stored on the CD-ROM in a compressed (zip) format. To install the javadocs on your system:

1. Create a directory on your system where you want to store the javadocs (for example, C:\java3d\doc).

2. Open the win32 folder on the CD-ROM and select the java3d1_2-doc.zip file.

3. Use a zip utility to unzip the javadoc.zip file into the directory you just created.

To read the javadocs, point your browser to the index.html file in the newly-created html directory.

G.3 Installing the Software on Solaris Systems

G.3.1 Requirements for Solaris Systems

The system on which the contents of the CD-ROM are installed should have

• At least 38 megabytes of free disk space for the Java 2 SDK

• At least 7 megabytes of free disk space for the Java 3D API

• At least 32 megabytes of free disk space for Sun OpenGL 1.2.1 for Solaris.

• Sun OpenGL for Solaris/SPARC, version 1.2 (or later). Sun OpenGL 1.2.1 for Solaris is provided on the CD-ROM.

• A frame buffer with OpenGL support, such as Elite3D, Creator3D, or Expert3D.

• The Solaris 2.6 (or later) operating environment with the necessary patches installed (see Section G.3.3, "Installing Patches on Solaris Systems").

G.3.2 Installing Sun OpenGL 1.2.1 for Solaris

If you do not already have at least Sun OpenGL 1.2 for Solaris on your system, install Sun OpenGL 1.2.1 from the CD-ROM as follows:

1. Insert the CD-ROM in your CD-ROM drive.

2. su to root.

3. Run the installation program:

% /cdrom/solaris/opengl/ogl121.sh

4. Exit and restart your window system.

5. Run the ogl_install_check program to verify the installation:

% /usr/openwin/demo/GL/ogl_install_check

G.3.3 Installing Patches on Solaris Systems

Several patches are required to run Java and Java 3D on Solaris. These patches are included on the CD-ROM in the /cdrom/solaris/patches directory. A README file in this directory contains the complete list of patches for Solaris 2.6, Solaris 7, and Solaris 8.

To install the patches for your system, proceed as follows:

1. Insert the CD-ROM in your CD-ROM drive.

2. su to root.

3. Run the following script:

% /cdrom/solaris/patches/install_patches.csh

This script determines the version of Solaris that is running and installs all necessary patches for that version.

4. Reboot your system.

To show the installed patches, type the following:

% showrev -p

If you want to install an individual patch, rather than the entire set of patches, proceed as follows:

1. Insert the CD-ROM in your CD-ROM drive.

2. su to root.

3. Run patchadd with the path to the patch you want to install.

For example:

% patchadd /cdrom/solaris/patches/5.7/105181-17

4. Reboot your system.

G.3.4 Installing the Java 2 SDK on Solaris Systems

---

Note: You must have permission to write files in the directories where you want to install Java and Java 3D. If you do not have this permission, the installation program will run to completion but Java and Java 3D will not be installed.

---

To install the Java 2 SDK on a Solaris system, follow these steps:

1. Change directories to where you wish to install the Java 2 SDK.

For example, to install on /home/myhome:

% cd /home/myhome

2. Run the installation program.

% /cdrom/solaris/Solaris_JDK_1.2.2_05_sparc.bin

This will create a Solaris_JDK_1.2.2_05 directory containing the Java 2 SDK.

3. Update the PATH variable in your startup file.

Put /home/myhome/Solaris_JDK_1.2.2_05/bin in your path ahead of any directory that may contain java, such as /usr/bin.

4. Check the CLASSPATH variable.

Include "." in your CLASSPATH or ensure that CLASSPATH is not set.

5. Verify that Java is installed by typing the following:

% java -version java version "1.2.2" Solaris VM (build Solaris_JDK_1.2.2_05, native threads, sunwjit)

If you do not get the java version "1.2.2" message, verify that you have put the jdk1.2.2/bin directory in your path in Step 3 above. If you do get the above message, proceed to Section G.3.5, "Installing the Java 3D API on Solaris Systems."

G.3.5 Installing the Java 3D API on Solaris Systems

To install the Java 3D API, follow these steps:

1. Change to the jdk1.2.2 directory. For example:

% cd /home/myhome/jdk1_2_2

2. Install the Java 3D API. Type the following:

% /cdrom/solaris/java3d1_2-solsparc.bin

3. Verify that Java 3D is installed by typing the following:

% cd demo/java3d/HelloUniverse % java HelloUniverse

You should see a window with a multi-colored rotating cube.

4. See the README.Java3D-jdk file in the Solaris_JDK_1.2.2_05 directory for more information about this release.

G.3.6 Installing the Javadocs on Solaris Systems

The javadocs for Java 3D may be installed on your system for ready access. Alternatively, you may choose to save the disk space by not installing the javadocs and read them directly from the CD-ROM whenever needed (see Section G.4, "Accessing the Documentation from the CD-ROM").

You will need at least 10 megabytes of free disk space to install the Java 3D API javadocs.

The javadocs are stored on the CD-ROM in a compressed tar format. To install the javadocs on your system:

1. Create a directory where you want to store the javadocs. For example:

% mkdir /home/myhome/java3d/doc

2. Change to the directory you just created. For example:

% cd /home/myhome/java3d/doc

3. Untar the file into the newly created directory:

% zcat /cdrom/solaris/java3d1_2-doc.tar.Z | tar xvf -

To read the javadocs, point your browser to the index.html file in the newly-created html directory.

G.4 Accessing the Documentation from the CD-ROM

The javadoc-generated API documentation and the text of this book are included on the CD-ROM in a browsable (html) format. Additionally, the text of this book is included in a PDF format.

A browsable version of the javadocs are available in the /doc/java3d1_2-doc directory on the CD-ROM. Point your browser to the index.html file in this directory to view the Java 3D API documentation.

A browsable version of The Java 3D API Specification (this book) is available in the /doc/j3dbook directory on the CD-ROM. Point your browser to the index.html file in this directory to view the online version of this book. The text of this book is also available in Adobe Acrobat (PDF) format in the /doc directory as j3dbook.pdf. You can download a copy of the Adobe Acrobat Reader from:

http://www.adobe.com/products/acrobat/readstep.html

---

The Java 3D API Specification

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