

==============================================================================
Java 3D(TM) 1.1.3
==============================================================================

This is the 1.1.3 version of Java 3D(TM).

------------------------------------------------------------------------------
DISTRIBUTING Java 3D(TM) WITH YOUR JAVA(TM) PROGRAMS
------------------------------------------------------------------------------

Sun Microsystems allows vendors to distribute the Java 3D Runtime
environment with their Java programs, provided they follow the terms
of the Java 3D Binary Code License agreement.

This document uses the term "vendors" to refer to licensees,
developers, and independent software vendors (ISVs) who license and
distribute Java 3D with their Java programs.

------------------------------------------------------------------------------
REQUIRED vs. OPTIONAL FILES
------------------------------------------------------------------------------

Vendors must follow the terms of the Java 3D Binary Code License agreement,
which includes these terms:

 - Don't arbitrarily subset Java 3D. You may, however, omit those files
   that have been designated below as "optional".

 - Include in your product's license the provisions called out
   in the Java 3D Binary Code License.


==============================================================================
           BUNDLING AND RUNNING JAVA 3D
==============================================================================

------------------------------------------------------------------------------
BUNDLING JAVA 3D
------------------------------------------------------------------------------

The release of Java 3D for Win32 comes with its own installer that
makes it suitable for downloading by end users. Java application
developers have the option of not bundling Java 3D with their software.
Instead, they can direct end-users to download and install the Java 3D
software themselves.

Solaris versions of Java 3D do not have an installer. Software
developers should bundle Java 3D and an installer with their software.

Required Files
--------------

The following files are required.



	<installdir>/jre/lib/$(ARCH)/libJ3D.so
	<installdir>/jre/lib/$(ARCH)/libj3daudio.so

	<installdir>/jre/lib/ext/vecmath.jar
	<installdir>/jre/lib/ext/j3dcore.jar
	<installdir>/jre/lib/ext/j3daudio.jar
	<installdir>/jre/lib/ext/j3dutils.jar


If an application developer bundles Java 3D with their application,
all required files must be included.


Optional Files
--------------

Files in the following directories and files are optional:


	<installdir>/demo/java3d
	<installdir>/j3d-utils-src.jar


An application developer may include these with their Java 3D application,
but is not required to do so.


==============================================================================
Requirements
==============================================================================

This version of Java 3D for Linux requires the following:
    - Recent version of Mesa (the release was built with version 3.1), 
      typically available from your Linux distribution
    - Java2 SDK 1.2.2-RC4 for Linux.  This can be obtained from
      http://www.blackdown.org
      Sun's Java2 SDK 1.2.2 FCS for Linux should work too but is not
      supported by Blackdown.

==============================================================================
Installation
==============================================================================

To install the Java 3D Runtime environment:

        cd $installdir		    # see note below
        tar xvIf java3d1_1_3- 1 -sdk.tar.bz2

where $installdir is the directory where JDK1.2.2 was extracted.

Once the release has been extracted, you may want to run one of the example
programs.

	cd $installdir/jdk1.2.2/demo/java3d/test_program
	java test_program

	Where test_program is the program you wish to run
	(e.g., HelloUniverse).


==============================================================================
Running Java 3D in a Browser
==============================================================================



If you want to run applets in a browser, you need to also download and
install the Java Plug-in. The Java Plug-In is installed into
$(HOME)/.netscape/java by default.  If you install the Runtime version
of Java3D into the Plug-In, you can then run applets that have a
modified HTML page.  Refer to the following URLs for information on
using the Java Plug-in 1.2.2 HTML Converter and running applets using
Java Plug-in:

        http://www.blackdown.org/java-linux/jdk1.2-status/plugin-status.html
        http://java.sun.com/products/plugin/index.html

NOTE: There is a bug in Java Plug-In that prevents standard extension
classes, such as Java 3D, from being loaded.  Java Plug-In currently
looks only in the lib directory of lib and fails to look in the
lib/ext directory.  The solution is to copy the following four Java 3D
jar files from lib/ext to lib:

	j3daudio.jar
	j3dcore.jar
	j3dutils.jar
	vecmath.jar

(The problem will be fixed in the next Java Plug-In for Linux release).



==============================================================================
Changes since 1.1.2
==============================================================================
    Memory Release
        Some work was done to help ensure that Java 3D releases memory
        when a branch graph is detached from the scene graph.  In some
        cases you may need to detach the View from the scene graph
        to release the memory. 

    Bugs Fixed:
        - Line/polytope intersection fails for line longer than 1.0
        - NullPointerException when de-iconifying application
        - Setting Texture reference from user thread can cause deadlock.
        - Alpha setTriggerTime() fail to set stopTime
        - AccessControlException when a visible Canvas3D is added to a View
        - software decompressor produces bad colors from mesh references
        - Can't restart RotPosScaleTCBSplinePathInterpolator
        - Quaternion interpolation causes bad rotations
        - In segmentAndQuad, the return value of dist[0] is a ratio, 
          not a distance.
        - fog scoping methods throw CapabilityNotSetException even it is set
        - RotationInterpolator created with null Alpha cannot be restarted
        - Lightwave TestParse can't load SpaceFighters


==============================================================================
Utilities:
==============================================================================

This release includes utilities for Java 3D.  These utilities are still
being defined and under development.  Much of the source for these utilities
is also provided.  The API for these utilities may change in future releases.

NOTE:  The Javadocs for all utilities are available from the Java 3D
Implementation Download Web Page:
http://java.sun.com/products/java-media/3D/download.html.  At the bottom
of the page there is a section titled: "Download the Java 3D 1.1.3
Implementation Documentation".

The following utilities are provided in this release:

        - Java Sound Audio Device
	- Some predefined Mouse based behaviors
	- Picking utilities including predefined picking behaviors
	- Geometry creation classes for Box, Cone, Cylinder, and Sphere
	- A Text2D utility
	- A Universe Builder - SimpleUniverse
	- An Image Loading utility
	- A Normal Generator utility
	- A Polygon Triangulator utility
	- Preliminary triangle stripifier
	- Spline-based path interpolators
	- Preliminary Wavefront .obj loader
	- Preliminary Lightwave 3D File Loader
	- A utility to generate compressed geometry for use with Java 3D's
          CompressedGeometry node.

==============================================================================
Known Problems
==============================================================================


Core Bugs (j3d and vecmath)
      - ReadRaster does not clip to screen correctly
      - MediaContainer node cloned improperly
      - SwitchValueInterpolator needs to handle firstChild > lastChild index
      - Compiles of nested BranchGroups consumes more memory than single
        root compile
      - Back clip distance in Clip node not scaled correctly
      - SceneAntialiasing setting of PREFERRED is ignored
      - Geometry Collision does not implement points/surface, line/line, or
        line/point
      - Java 3D cannot handle more than 64 lights
      - Cached eye position not set in compatibility mode
      - Cached transforms not set in compatibility mode
      - Region of Influence/Scope changes to Light/Fog doesn't effect
        static objects
      -	Shape3D memory not freed when unassigned if associated
	appearance object is live
      - Java 3D classes and threads are not cleaned up and cannot be unloaded
      - After switch from Mixed mode to normal mode,
	IllegalSharingException thrown
      - Non-Congruent matrix above view platform will kill the traverser thread
      -	Illegal rendering state exceptions kill Traverser thread
      - Billboard node not synchronized with view platform changes
      - getBounds returns null for non-live scene graphs
      - wakeupOn fails to register a condition when called with the same
        reference twice
      - Collision does implicit conversions of bounds types
      - PathInterpolator's setKnot method does not validate inputs
      - Sound performance on native threads is bad
      -	Not all physical coexistence center policies are implemented
      -	HMD mode not yet implemented
      -	SceneGraphCycleException checking needs to be turned on.
      -	Occasional spikes in Doppler calculation causes wild
	exaggerated pitch shifting
      -	Filtering causes loud, sweeping resonance to be added to most
	sounds
      -	Cross-talk cancellation for sound playback in not implemented
      -	setReverbDelay(null) of AuralAttributes return incorrect value
      -	HEAD_PREDICTOR and HAND_PREDICTOR policies not implemented
      -	Geometry-based picking is not supported for CompressedGeometry.
      -	Geometry collision not supported for compressed geometry
      -	Multiple sample channels are not always synchronized when
	started
      -	GMatrix SVD does not work correctly for some cases.
      -	Java3D does unneeded redraws for window events
      -	Loading HTML page or Java 3D applet while sound is playing
	may cause exception
      - Extrusion contures for Font3D don't produce smooth normals
      - Multiple views of a Switch node incorrect
      - Multiple repaints per scene graph change
      - ImageComponent2D with no image set causes segmentation fault
      - ViewPlatforms do not work correctly under Switch nodes

Utility Bugs
      - ObjectFile Loader material properties support needs to be expanded
      - FourByFour generates SecurityException when trying to write out
	the high score file


Windows-specific Bugs
      -	Bug in Symantec JIT causes the GearBox example to render
	incorrectly.
      -	Symantec JIT issues warning when running FourByFour example
      - PureImmediate mode does not work after paint() event on Win95 with ogl



