Java 3D(TM) 1.2

README file for Linux/OpenGL

===========================
IMPORTANT INSTALLATION NOTE
===========================

This file contains important information for users of Java 3D(TM).
The first three sections (Requirements, Installation, and Running
Java 3D(TM) in a Browser) are of interest to all Java 3D(TM) users.
The rest of this file applies only to developers of Java 3D(TM)
applications.

** It is recommended that any previous version of Java 3D(TM) be
** uninstalled before installing this version.

============
REQUIREMENTS
============


This version of Java 3D(TM) for Linux requires the following:

        Java 2 SDK version 1.2.2-FCS or later from Blackdown Java-Linux
        (http://www.blackdown.org) if you want to use the J3D1.2 SDK
        or Java 2 Runtime environment version 1.2.2-FCS or later from 
        Blackdown Java-Linux (http://www.blackdown.org) if you want to 
        use the J3D1.2 Runtime Environment.
        It is recommended that you use a native threads VM (classic VM 
        with native threads or the HotSpot(TM) VM).  This release has 
        been certified for use with the Blackdown Java-Linux Java2 SDK
        version 1.2.2-FCS (native threads and the sunwjit compiler),  
        Java 2 SDK version 1.3.0 (with HotSpot(TM)) from Sun/Blackdown 
        works but has not been certified at this point.

        Mesa 3.2 (http://www.mesa3d.org) or another OpenGL(TM)
        implementation.
        For drivers with hardware acceleration see
        http://www.mesa3d.org/#Systems



============
INSTALLATION
============


Java3D 1.2 SDK:
---------------
Change your working directory to the the top level directory of 
the JDK you wish to install Java 3D(TM) into.
Then extract java3d1_2-FCS-linux-<ARCH>-sdk.tar.bz2 with 'tar xvfI'.
E.g.:
        cd /usr/local/jdk1.2.2
        tar xvfI ~/java3d1_2-FCS-linux-i386-sdk.tar.bz2

After installation, you may remove the tar ball.

The Java 3D(TM) SDK includes several demo programs that can
verify correct installation.  Assuming your Java 2 SDK is installed
at /usr/local/jdk1.2.2, try the following:

        cd /usr/local/jdk1.2.2/demo/java3d/HelloUniverse
        java HelloUniverse

        Note: Many more demos are available under the demo/java3d/
              directory.  Some of the demos require a maximum memory
              pool larger than the default in java.  To increase the
              maximum memory pool to 128 meg, add the following command
              line options to java or appletviewer:
                  java: -mx128m
                  appletviewer: -J-mx128m

Java3D 1.2 Runtime Environment:
-------------------------------
Change your working directory to the the top level directory of 
the JRE you wish to install Java 3D(TM) into.
Then extract java3d1_2-FCS-linux-<ARCH>-re.tar.bz2 with 'tar xvfI'.
E.g.:
        cd /usr/local/jre1.2.2
        tar xvfI ~/java3d1_2-FCS-linux-i386-re.tar.bz2

After installation, you may remove the tar ball.


You do not need to include the J3D jar files in your CLASSPATH,
nor do you need to include the J3D shared libraries in your PATH.
You should include "." in your CLASSPATH or ensure that CLASSPATH
is not set.

Java 3D(TM) documentation and tutorials are available from the Java 3D(TM)
Home Page: http://java.sun.com/products/java-media/3D/


===============
SHARED CONTEXTS
===============

This version of Java 3D is able to use shared contexts in OpenGL for Display
Lists and Texture Objects.  For single canvas applications, there will be no
change in behavior.  For multiple canvas applications, memory requirements
will decrease by using this property.  To enable the use of shared contexts
set the j3d.sharedctx property to true, for example:

    java -Dj3d.sharedctx=true MyProgram

Some video cards, such as the Riva TNT & TNT2, have problems using shared
contexts.  If you are experiencing no rendering, crashes, or no textures
being displayed, when shared contexts are enabled this is the most likely
problem.

================================
RUNNING JAVA 3D(TM) IN A BROWSER
================================


You can run Java 3D(TM) programs in Netscape Communicator.  
After installing Netscape Communicator you then
install the Java(TM) Plug-IN (JPI) to add Java 2(TM).
Then follow the instructions here to install Java 3D(TM).

Netscape Communicator may be downloaded for free from
http://www.netscape.com.  Netscape version 4.51 or higher is required.

The JPI is available from 
http://www.blackdown.org/java-linux/jdk1.2-status/plugin-status.html
JPI 1.2.2 or higher is required.

By default, the JPI is installed in $(HOME)/.netscape/java.  If 
another directory is used, it must be specified with the 
NPX_PLUGIN_PATH environment variable.

The JPI comes with its own JVM, but we need it to use the JVM
you've upgraded with Java 3D(TM).  Run the Java Plug-In Control
Panel by pointing Netscape at the ControlPanel applet page or by
starting the ControlPanel script in the JPI's main directory.
Click on the 'Advanced' tab and under "Java Run Time Environment"
choose "Other..."  Enter the path to your JVM in the 'Path:' box
(for example, /usr/local/jdk1.2.2/jre).  Press "Apply."

There is a bug in the Linux and Solaris versions of the JPI 1.2.2 
that keeps it from finding Java extensions in the lib/ext/ directory
where they are kept.  To work around the problem, you need to
copy the four .jar files from the lib/ext/ directory to the
lib/ directory as follows:

    cd $SDKHOME/jre/lib/ext
    cp j3daudio.jar ..
    cp j3dcore.jar ..
    cp j3dutils.jar ..
    cp vecmath.jar ..

Java Plug-In will be built into Linux Netscape 6.0, so this
separate installation process will no longer be necessary.

Special HTML code is required to get Netscape to use the JPI
VM.  Refer to the following URL for information on using
Java Plug-In 1.2.2 HTML Converter and running applets using
Java Plug-in:

        http://java.sun.com/products/plugin/

All example programs that can be run as applets now have an html file 
with "_plugin" in their name that has been converted to use Java 
Plug-In. Use any of these programs to test your installation of Java 3D
in your browser.

NOTE: Many Java 3D(TM) programs will require a larger heap size
than the default in the JPI.  Run the Java Plug-In Control
Panel by pointing Netscape at the ControlPanel applet page or by
starting the ControlPanel script in the JPI's main directory.
In Java Run Time Parameters put "mx100m" for 100M of heap memory.


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

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

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

REQUIRED vs. OPTIONAL FILES
---------------------------
Vendors must follow the terms of the Java 3D(TM) Evaluation License
agreement, which includes these terms:

 - Don't arbitrarily subset Java 3D(TM). 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(TM) Evaluation License.

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

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


When bundling Java 3D(TM) with your application, the following files
must be included (Linux):

        <JREDIR>/lib/<ARCH>/libJ3D.so
        <JREDIR>/lib/<ARCH>/libj3daudio.so
        <JREDIR>/lib/ext/vecmath.jar
        <JREDIR>/lib/ext/j3dcore.jar
        <JREDIR>/lib/ext/j3daudio.jar
        <JREDIR>/lib/ext/j3dutils.jar


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

An application developer may include these files and directories
with their Java 3D(TM) application, but is not required to do so:


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



========================
CHANGES SINCE 1.2 Beta 2
========================

==========
BUGS FIXED
==========

4152507 Non-Congruent matrix above view platform will kill the traverser thread
4189141 Geometry-based picking is not supported for CompressGeometry.
4189608 for certain cases, PointSound clone[Node,Tree] method not working
4248505 ViewPlatforms do not work correctly under Switch nodes
4259292 ImageComponent2D with no image set causes segmentation fault
4259332 Multiple views of a Switch node incorrect
4259343 bug in loader routine private void setBaseUrlFromUrl
4267310 Extrusion contours for Font3D don't produce smooth normals
4280130 Shape with lighting enabled and no normals should throw exception
4303050 GeometryArray: set Color/Texture should throw exception if wrong
        dimension
4305949 Scene antialiasing produces significant rendering artifacts
4309039 setting texture object on >= 2 objects repeatedly generates
        OutOfMemoryError
4309811 Memory leak when textures are removed
4315063 TickTockPicking fail to pick and highlight shape color
4310690 PickIntersection.getPointCoordinates() return wrong result
4310717 PickResult.toString() stack overflow
4311548 Memory Leaks with AlternateAppearance
4312393 SimpleTextureApp gets nullpointer exception, from TextureLoader
       in utils
4313347 Synchronizing interpolator and view transformgroup
4313908 Memory leak when adding/removing scene graphs
4314108 Picking utility can't handle shape with multiple geometries properly
4315015 Text3DLoad throw NullPointerException
4315031 MixedImmediate hangs under windows98
4315307 NullPointerException throws at getApplicationBackground
4315326 One spotlight is missing in tutorial SpotLightApp
4315329 tutorial BoundaryColorApp shows different images on
        windows/Solaris (AFB/FFB)
4315335 TextureLoader throws NullPointerException when observer is null
4316842 Ends of cylinders contain 2x as many triangles as needed
4317059 Background application bounds did not transform as expected
4317467 NullPointerException at TransformGroupRetained.setTransform()
4318997 Vecmath Serialization is NOT compatible with Java3D 1.1.x
4319878 ClippedOffScreenCanvas3DTest fail to print cube in certain
	clipping cases
4322069 ClassCast & pointer Exception in Morph during detach and
	setGeometryArray
4322165 ambiguous default values for ConeSound angular attenuation
4322661 TextureByReference demo no longer animates
4322725 Changes to AlternateAppearance ignored when no Shape3D is enabled
4322817 java.lang.IllegalStateException: GeometryArray: must be in COLOR_3 mode
4323280 RotPosScaleTCBSplinePathInterpolator fail to clone KeyFrames and Alpha
4324801 MultiTextureTest throws NullPointerException when texture change
4325005 Environment mapping (i.e. TexCoordGeneration.SPHERE_MAP) not work
4325643 Switching from multi to single texture sometimes does not work
4325789 AppearanceTest throws NullPointerException under windows
4325847 Background Image did not remove when branch detach
4326650 BackgroundGeometry got cull away sometimes when using
        VertexArrayRenderMethod
4327020 NullPointerException when texture unit state is disable
4327715 Bad flickering in PureImmediate Mode
4327776 SharedAlternateTargetTest throws NullPointerException in Behavior
        callback
4328222 PickAny(Locale ) did not check for isPickable flag
4328331 J3DGraphics2D drawing buffer is not cleared
4328765 MasterControl sometimes throws NullPointerException when
        SimpleGeometry startup
4328844 performance regression on input events processing
4329542 Nested Shared group throws ArrayIndexOutOfBoundsException
4329546 Exception in texture when image of a different size is
        setImage() after setLive
4329571 lights removed from a scene still light the scene
4329636 IndexOutOfBoundsException throw when share object pick
4329682 ModelClipImm did not work
4329812 WakeupOnTransformChange and AWT Event processing order not in correct
4329873 JVM Segmentation fault if depth Component not set in Raster
4329942 Texture setImage(s) unclear on how to set a new image of a
        different size
4330199 Link.setSharedGroup() throws array index exception
4330210 Debug statement printed when using ordered group
4331122 hardware decompression is disabled on Solaris
4331694 can't pick LineStripArray or IndexedLineStripArray
4332218 OrderedGroup.setChild throws IndexOutOfBoundsException
4333197 quitting PureImmediate demo causes IndexOutOfBoundsExc on Win and
        SIGSEGV on Solaris
4333543 ConicWorld/TexturedCone would not load as an applet

============
NEW FEATURES
============

All example program now have example.html and example_plugin.html for
use with the plugin feature available with most web browsers.  In addition,
an html page, demo/java3d/index.html now contains links to all demo programs
that can be run as applets.

=======================
Constructing a Canvas3D
=======================

Many Java 3D programs pass null to the Canvas3D constructor.  By doing
this, Java 3D will select a default GraphicsConfiguration that is
appropriate for Java 3D.  However, this is a bad practice, and can lead
to errors when applications try to run in alternate environments, such as
stereo viewing.  Java 3D will now print out a warning if the Canvas3D
constructor is passed in a null argument for the GraphicsConfiguration.

=========
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.

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
        - Geometry compression utilities
        - Spline-based path interpolators
        - Preliminary Wavefront .obj loader
        - Preliminary Lightwave 3D File Loader

===================================
Enabling Stereo with SimpleUniverse
===================================

The SimpleUniverse utility does not, by default, request a
GraphicsConfiguration that is capable of Stereo rendering.  To enable this,
you need to set a property when running your application.  Here is an
example.

java -Dj3d.stereo=PREFERRED MyProgram

==============
KNOWN PROBLEMS
==============

Documentation Bugs
------------------
4181456 make Sensor.setSensorReadCount MT-safe
4199091 Raster object uses the alpha value inside the image to perform
        blend operation
4284971 Specify that wakeup criteria should not be shared
4284973 Billboard and OrientedShape3D must specify that +Z axis is illegal
4284976 Specify that getProjection is illegal in non-compatibility mode
4284977 Clarify effect of capability bits in retained mode
4303052 Quaternion documentation is inadequate
4303053 javadoc for DistanceLOD with multiple switch nodes needs improvement
4303054 Lighting equations should be updated to reflect color override
4303055 Docs should specify effect on clipped portion of ImageComponent
4303056 Docs should specify thread-safety behavior of Java 3D methods
4303058 Docs should indicate when boundary color is used
4303060 Docs should be more clear on interaction of old/new texture state
        methods
4303062 Need to specify which attributes are passed by reference versus by
        value
4307547 Need to doc. : scene graph needs to have at least a Canvas3D to
        keep j3d working
4307552 Spec. need to be clearer on the issue of sync. between sg. update
        and picking.
4259353 documentation for com.sun.j3d.utils.geometry.Box is confusing

Core Bugs (j3d and vecmath)
---------------------------
4181344 Java 3D cannot handle more than 64 lights
4181349 Need to add Transform to SceneGrphPath hashCode
4181417 Need to add an internal epsilonEquals method for bounds objects
4181456 make Sensor.setSensorReadCount MT-safe
4182781 Shape3D memory not freed when unassigned if associated
        appearance object isalive
4182859 Back clip distance in Clip node not scaled correctly
4186182 sceneAntialiasing setting of PREFERRED is ignored
4186219 Geometry Collision does not implement points/surface, line/line, or
        line/point
4187092 Filtering causes loud, sweeping resonance to be added to most sounds
4187093 Cross-talk cancellation for sound playback in not implemented
4189092 HEAD_PREDICTOR ansd HAND_PREDICTOR policies not implemented
4190692 Multiple sample channels are not always synchronized when started
4191172 Text3D rendering problems
4193466 GMatrix SVD does not work correctly for some cases.
4212805 ReadRaster test program has race condition
4246325 AWT Event once enable, will not disable when behavior remove
4250253 GeometryInfo leaks memory in some cases (with Appearance?)
4259345 Text3D does not correct convert geometry of Japanese-text
4259533 getTexture() throws NullPointerException when using proxies
4260818 java3d should support stereo graphics automatically
4269784 vecmath.GMatrix.LUD inefficient
4269923 LOD's slow
4269929 lighting bounds problem
4271363 CloneTree display garbled in AccelGalaxy card RealImage 2100
4299480 readRaster() and waitForOffScreenRendering() will not work if
        threadLimit=1
4308591 Text3D objects bounding box not accurate enough
4308592 texture loader does not scale non-power-of-2 RGBA textures properly
4308599 transparent BufferedImages not working
4308601 using KeyEvents and Swing requires clicking on the window with
        the mouse
4308605 cloned object's setAppearance method produces no effect
4309037 setWorldURL in the Loader.java is setup wrong (fix included)
4309059 background geometry appears very close to the camera vs 1.1.3
4310109 share context not use when createContext() in GraphicsContext3D
4310958 wrong bounds may be used in region of influence operations
4312044 java Viewer reflects only Lightwave objects with depth
4313678 Java3D disables invalid lights
4315018 Garbage sound in TestFilter
4315058 VolRend display white cube when Axis Volume is 3D
4316844 Documentation of Java 3D colors should specify gamma assumptions
4319780 RFE: java3d scene graph objects are not serializable
4325851 Hardware MultiTexture not support even though
        numActiveTexture <= supported num
4326571 Need URL method for Lightwave objects in applets
4327643 RFE: LW3Dloader needs to be able to load 'other' image file formats
4328532 Textures for the bottom of cones and cylinders are upside-down
4331434 adding object to itself does not generate an exception
4331646 rendering differences between WIN32 and Solaris platforms
4331669 setRectangleScaleFactor will not change text size unless setString
        called
4331677 setWindowResizePolicy(View.VIRTUAL_WORLD) doesn't work1<
4332793 View transform & object transform not synchronized in a single behavior
4334767 examples/MoveAppBoundingLeaf sometimes produces no sound
4335205 WakeupOnCollision fail if arming Node is TransformGroup which
        undergo transform
4335245 Raster type RASTER_COLOR_DEPTH did not work as expect

Utility Bugs
------------
4217567 NormalsGenerator only checks the cosine for smoothing
4250253 GeometryInfo leaks memory in some cases (with Appearance?)
4252349 First viewport may jump when using KeyNavigatorBehavior