Java 3D(TM) 1.2.1_01

----------------------------------------------------------------------
CHANGES 
-----------------------------------------------------------------------
This CHANGES section summarizes the changes between the FCS version of
Java 3D and this patch version, Java 3D 1.2.1_01.

----------------------------------------------------------------------
BUGS FIXED IN PATCH Java 3D 1.2.1_01
-----------------------------------------------------------------------
  4411851 OrientedShape3D fail to add under SharedGroup when mode =
          ROTATE_ABOUT_POINT
  4426898 D3D: crash when transparency of RGBA Raster change
  4427335 Severe performance regression in 1.2.1 during attach/detach from
          TransformGroup
  4430127 Performance : enable polygon offset can cause big performance hit on
          ifb and afb
  4430366 Transform3D invert() is numerically unstable when matrix is congruent
  4430638 Congruent classification is numerically unstable
  4430912 ConcurrentModificationException throws from RenderBin freeResource()
  4431812 OGL: crash intermittently when multiple texture used and Canvas
          active/deactive
-----------------------------------------------------------------------


README file for Linux/OpenGL

This file contains important information for users of Java 3D(TM).
The first four sections (Requirements, Installation, Shared 
Contexts, 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 Runtime or SDK version 1.3.0 or later from Blackdown
  (http://www.blackdown.org/) or Sun Microsystems
  (http://java.sun.com/j2se/).

  XFree86 3.3.6 with Mesa 3.1 or later
    or
  XFree86 4.0.3 or later with XFree86's Mesa library and DRI
    or
  XFree86 4.0.3 with NVidia drivers 1.0-1251 or later
    or
  XFree86 4.0.3 with an official (ie. not XFree86's) Mesa library
  (http://www.mesa3d.org/) if you can't or don't want to use DRI

  Note that XFree86 4 with XFree86's Mesa library without DRI is not 
  supported at this time!  Most likely the XServer will crash when you
  close Java3D application with that setup.


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

You must have permission to write files in your Java(TM) Runtime
Environment and/or SDK directories.  If you do not have this
permission, the installer will run to completion but Java 3D(TM)
will not be installed.  Make sure you are running Java(TM) from
your local machine and that you are the same user who installed
Java.

Java3D 1.2.1_01-FCS SDK:
------------------------
Change your working directory to the the top level directory of 
the J2SDK you wish to install Java 3D(TM) into.
Then extract java3d-1.2.1_01-fcs-linux-<ARCH>-sdk.tar.bz2 with bzip2
and tar.
E.g.:
        cd /usr/lib/j2sdk1.3.0
        bzip2 -dc ~/java3d-1.2.1_01-fcs-linux-i386-sdk.tar.bz2 | tar xvf -

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/lib/js2dk1.3, try the following:

        cd /usr/lib/j2sdk1.3/demo/java3d/HelloUniverse
        java HelloUniverse

Java3D 1.2.1_01-FCS Runtime Environment:
----------------------------------------
Change your working directory to the the top level directory of 
the J2RE you wish to install Java 3D(TM) into.
Then extract java3d-1.2.1_01-fcs-linux-<ARCH>-re.tar.bz2 with bzip2
and tar.
E.g.:
        cd /usr/lib/j2sdk1.3.0
        bzip2 -dc ~/java3d-1.2.1_01-fcs-linux-i386-re.tar.bz2 | tar xvf -

After installation, you may remove the tar ball.


Packages for Debian:
--------------------

Select one of the Blackdown mirrors
(http://www.blackdown.org/java-linux/mirrors.html) and add a line of
the form

      deb ftp://<mirror>/<path to java dir>/debian <dist> non-free

to /etc/apt/source.list. <dist> should be potato or woody.
E.g., if you want to use the woody tree on ftp.tux.org you would use
      
      deb ftp://ftp.tux.org/java/debian woody non-free

Then install java3d-sdk or java3d-re using the standard Debian tools.
No further setup is required.



Java 3D(TM) consists of four jar files and two shared libraries.  You
do not need to include the jar files in your CLASSPATH, nor do you
need to include the shared libraries in your PATH/LD_LIBRARY_PATH.
You should include "." in your CLASSPATH or ensure that CLASSPATH is
not set.

Java 3D 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 by default uses 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.  

Some video cards (e.g. from NVidia) have problems using shared
contexts.  If you are experiencing no rendering, crashes, deadlocks
with System.exit(), or no textures being displayed when shared
contexts are enabled, this is the most likely problem.
To disable the use of shared contexts either set the j3d.sharedctx
property to false, for example:

    java -Dj3d.sharedctx=false MyProgram

or set the environment variable J3D_USE_SHARED_CONTEXT to FALSE.

=================
Background Images
=================

Some older PC video cards (such as the Riva TNT) render background images very
slowly.  If you are experiencing slow rendering of background images,
you can set the j3d.g2ddrawpixel property to false.  This may yield better
performance for you card.  Example:

	java -Dj3d.g2ddrawpixel=false MyProgram


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

You can run Java 3D(TM) programs in your browser.  Java 2(TM) from
Blackdown or Sun includes the Java Plug-In (JPI) to upgrade the
Java(TM) in the browser to Java 2(TM).  To verify proper installation,
point your browser to file:///usr/lib/j2sdk1.3/demo/java3d/index.html

To create a web page with Java 3D, you need to use special HTML
code to force the browser to use the JPI VM.  Refer to the
following URL for information on using Java Plug-In "HTML
Converter" and running applets using Java Plug-in:

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

====================================================
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) Binary Code License and Supplemental License Terms
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:

        <J2REDIR>/lib/<ARCH>/J3D.so
        <J2REDIR>/lib/<ARCH>/j3daudio.so
        <J2REDIR>/lib/ext/vecmath.jar
        <J2REDIR>/lib/ext/j3dcore.jar
        <J2REDIR>/lib/ext/j3daudio.jar
        <J2REDIR>/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:

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


=========================
CHANGES SINCE 1.2.1 Beta2
=========================

All exmaple programs use the new OrbitBehaviors utilities.

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

Documentation
-------------
4401875 Lack of doc on how weights function on indexed geometry for morph
4404334 setValidVertexCount and setInitial*Index are ignored for
        IndexedGeometryArray
4415312 GeometryInfo documentation is unclear


Core Graphics and Vecmath
-------------------------
4368961 Locale.addBranchGraph doesn't check for already live branch graph
4373686 D3D: Using scrollbar on Applets not working under Win32
4374220 setPickTolerance doesn't seems to have effect when doing parallel
        proj. picking
4394017 debug message not removed in utility Numerics
4396990 StackOverflowError in PickResult.toString()
4398616 Visibility query incorrect for multiple views
4399760 Multiple views config. might not show all visible objects in every view
4401274 background color affect geometry color when scene antialiasing is used
4401315 Immediate Mode texture did not render correctly if shared in 
        same appearance	
4401323 Transparency value ignored for RGBA rasters
4402940 SingularMatrixException when zooming
4402941 D3D: Fog did not work for some graphics card
4403359 Repeatly add/remove View branchgraph may throws NullPointerException
4403360 D3D: window resize may fail if there is not enough hardware memory
4403361 D3D: need a way to use other display driver
4403575 Picking may throw NullPointerException while branchgroup is detach
4403640 BoundingPolytope computeVertex() throws ArrayIndexOutOfBoundsException
4403691 View stopTime did not take into account swapping time
4403769 D3D: Immediate mode Texture disappear if canvas move from one monitor
        to another
4403770 D3D: Crash when using VX720 Nvidia RIVA 128 card in 32 bit mode
4404159 NodeComponentRetained getInImmCtx() return false if same appearance
        is set
4404169 Canvas did not update immediately when switching light
4404333 userlist managerment in NodeComponents is not MT safe
4404972 Text3D fail to undergo Transformation when view change after setString
4405593 Morph with indexed geometry array should ignore validVertexCount
4406373 D3D: viewport did not set correctly inside Browser after it move
4407031 Exception during Behavior execution
4407427 .compile throws an ArrayIndexOutOfBounds exception
4408377 setting light influencing bounding leaf doesn't work
4408900 D3D: Texture coordinate problem 
4408909 Intermittent crash
4408985 D3D: lighting change when view rotate
4409248 BranchGroups in scene graph not drawn until a parent TransformGroup
        changes
4409948 D3D: sometimes show nothing when canvas resize
4410530 D3D: scene Antialiasing fail to enable the second time
4410403 NullPointerException throw when OrderedGroup is used and view unregister
4412402 RenderBin throws NullPointerException in vrml player when
        switching model
4413538 DeadLock when setting LinearFog distance
4413855 OGL: hardware acceleration is not used for some graphics card
4414525 BoundingPolytope fail to recompute after setPlanes() if original
        bounds is empty
4415633 When using JAI TextureLoader does not handle transparent images
4416226 Can't add Switch to SharedGroups under certain scene graph arrangement
4417916 Performance regression in some benchmark programs since 1.2.1beta2
4417978 D3D: nothing show when ortho projection is use
4417981 D3D: nothing show when toggle to fullscreen using the latest nvidia
        5.12 driver
4418139 PureImmediate throws "exception in native code outside the VM"
4418472 ClassCasatException when appearance changed on a OrientedShape3D
4418473 .compile throws Exception when picking Shape3D with null geometry
4418748 D3D: multiple screen did not work
4419279 D3D: Intermittent crash in Haze demo when repeatly reload and resize
        frame
4419555 Collision detection for geometry is not accurate
4421284 Lines are not rendered when they are zoomed out and then in
4422288 View not updated for Head track environment
4424030 Geometry sometimes disappear when under Switch node
4424723 D3D: MultiTexture with texture transform did not work


Sound
-----
4412398 JavaSoundMixer throws IndexOutOfBoundsException when switching
        models in VRML


Utilities
---------
4367699 Lightwave Loader throws NullPointerException when loading data from
        a Stream
4404871 Orbit Behavior and VPMouseBehavior need API cleanup
4406445 OrbitBehavior transforms need to be integrated when behavior is changed
4406451 Need to disable old ViewPlatformBehavior when a new one is set
4408796 missing primitives


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

All example programs now use the OrbitBehavior utilites.

=======================
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
        - Triangle stripifier
        - Geometry compression utilities
        - Spline-based path interpolators
        - Wavefront .obj loader
        - 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

Some framebuffers only have one Z buffer and share this between the left
and right eyes.  If you are experiencing problems using stereo try the
following property:

java -Dj3d.stereo=PREFERRED -Dj3d.sharedstereozbuffer=true MyProgram


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

To get the very latest list of known Java 3D bugs, look on the Java
Bug Parade (http://developer.java.sun.com/developer/bugParade/index.html)

Documentation Bugs
------------------
4161432 Transform3D transform definitions are imprecise with respect to
    mirror transform
4259353 documentation for com.sun.j3d.utils.geometry.Box is confusing
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
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
4312421 Need to document texture by reference
4391487 Transform3D CONGRUENT definition is not clear
4421320 Can't update live geometry or texture image from Canvas3D callback

Examples
--------
4312044 java Viewer reflects only Lightwave objects with depth

Installation Bugs
-----------------
4370320 InstallAnywhere failed to display text selection under JTG 1.2.1
    and JTG 1.2.2
4370346 Sometimes InstallAnywhere not able to remove Java 3D jar files
    during uninstall

Core Graphics and Vecmath
-------------------------
4154445 PathInterpolator's setKnot method does not validate inputs
4160172 Access to some aggregate data is not MT-safe
4179923 ReadRaster does not clip to screen correctly
4181340 Updating the view cache could be a problem if other canvas
    running on same view
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
4186182 sceneAntialiasing setting of PREFERRED is ignored
4189092 HEAD_PREDICTOR and HAND_PREDICTOR policies not implemented
4191172 Text3D rendering problems
4193466 GMatrix SVD does not work correctly for some cases.
4246325 AWT Event once enable, will not disable when behavior remove
4259345 Text3D does not correct convert geometry of Japanese-text
4260818 java3d should support stereo graphics automatically
4269784 vecmath.GMatrix.LUD inefficient
4296708 Cannot detach BranchGroup from TransformGroup, despite proper
    capabilities
4299480 readRaster() and waitForOffScreenRendering() will not work if
    threadLimit=1
4313678 Java3D disables invalid lights
4319780 RFE: java3d scene graph objects are not serializable
4331677 setWindowResizePolicy(View.VIRTUAL_WORLD) doesn't work
4335245 Raster type RASTER_COLOR_DEPTH did not work as expect
4340607 Node and NodeComponent's set* methods not synchronized with
    set/clearLive
4348562 GMatrix SVD method incorrect output and throws
    ArrayIndexOutOfBoundsException
4348609 Poor rendering of textures on NT with 16 bit color
4351050 APIs issue : Shape3D and Morph's intersect method.
4351579 APIs issue : Shape3D intersect method -- multiple geometry
    support
4355332 Require Thread safe removeChild in BranchGroup
4357843 Picking doesn't handle OrientedShape3D's orientation when doing
    intersect test.
4359609 MediaContainer does nto report errors
4359764 Java3D does not support > 32 canvas
4363761 getImagePlateToVworld not synchronized with View<
4363899 APIs issue : OrientedShape3D's intersect method needs view
    info.
4366060 ObjectFile.load() throws IndexOutOfBoundsException
4366511 Full scene antialiasing slow under OpenGL
4368961 Locale.addBranchGraph doesn't check for already live branch
    graph
4370378 ImageComponentByReferenceTest raster image disappeared after
    window maximized
4371535 when PickTool cursor's update is enabled, the camera/view no
    longer updates
4373686 Using scrollbar on Applets not working under Win32
4374220 setPickTolerance doesn't seems to have effect when doing
    parallel proj. picking.
4377979 Transform3D classify is too slow and is called unnecessarily
4386903 DistanceLOD API inconsistant
4391492 Rotation matrix of Transform3D constructor not extract
4395292 Transform3D consume lots of memory
4396453 Bounding polytope should check for NaN bounds
4396990 StackOverflowError in PIckResult.toString()
4400608 java.lang.ArrayIndexOutOfBoundsException in examples/PickTest/PickTest
4401274 background color affect geometry color when scene antialiasing
    is used
4401323 Transparency value ignored for RGBA rasters
4408505 memory leak in immediate mode texture when texture keep changing
4409793 ImageComponent and Transform not updated synchronously
4412868 Alpha setMode() did not handle increasing/decreasingAlphaDuration
    correctly
4416025 MediaContained.setURLString() doesn't throw SoundException if URL is
    bad
4416995 Text2D.setString(String) restores filter setting default values
4416996 setVisible(false) affecting objects that did not have attribute set
4416999 Differences in rendering between retained and immediate modes w/same
    Appearance
4417459 GMatrix SVD incorrect
4419187 Texture2D ignored if not enabled when made live
4419189 Sound node ignores Switch value
4420303 D3D: object may disappear when canvases share scenegraph move between
    monitors
4420305 sound/animation sometimes disrupted by menus
4421860 PickTest : PickCylinder unable to pick point/line when pick mode set
    to GEOMETRY
4422273 In a multiple views setup, object may not be visible to all canvases,
    at startup


Sound
-----
4138605 using any non-javasound java sound causes severe performance
    hit
4164181 Sound performance on native threads is bad
4187092 Filtering causes loud, sweeping resonance to be added to most
    sounds
4187093 Cross-talk cancellation for sound playback in not implemented
4419189 Sound node ignores Switch value
4419938 ConstructPoints, MixedMode Sound problems
4315018 Garbage sound in TestFilter
4360462 Sound nodes referencing InputStream MediaContainer not fully
    functional
4360463 Doppler calculated results in less than expected frequency
    variation
4374943 SoundScheduler hangs under windows
4404165 Sound attributes did not check illegalSharing correctly

Utility Bugs
------------
4173647 Cannot share Sphere objects of same size between immediate and
    retained mode
4217567 NormalsGenerator only checks the cosine for smoothing
4252349 First viewport may jump when using KeyNavigatorBehavior
4259533 getTexture() throws NullPointerException when using proxies
4308592 texture loader does not scale non-power-of-2 RGBA textures
    properly
4327643 RFE: LW3Dloader needs to be able to load 'other' image file
    formats
4331669 setRectangleScaleFactor will not change text size unless setString
    called
4336679 In examples/PickTest program, a pick miss can happen on morph
    object.
4343427 Loader interface has no facility to monitor progress of Load
    Operation
4347998 PickTool pickGeomAllSorted did not compute closest distance for
    PickConeRay
4367699 Lightwave Loader throws NullPointerException when loading data
    from a Stream
4372387 TextureLoader throws SecurityException
4372722 ObjectFile loader hangs when loader .jpg file
4374631 CompressedGeometryFile can't be used by applets with default
    security
4374633 CompressionStream should provide a method for getting original
    bounds
4375265 ViewingPlatform Behavior support far too restrictive. API needs
    updating
4376368 Adding KeyNavigatorBehavior will keep cpu busy
4386880 TextureLoader should use imageio loaders
4391167 Triangulator unable to handle some polygons with holes.
4391507 MouseBehavior did not handle setEnable() correctly to remove
    buffer events
4394017 debug message not remove in utility Numerics


Linux-specific Bugs
-------------------
* Offscreen rendering does not work with NVidia drivers


