Java 3D(TM) 1.2.1_03

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

----------------------------------------------------------------------
BUGS FIXED IN PATCH Java 3D 1.2.1_03
----------------------------------------------------------------------

  4489206 Java3D throws exception when scoping is used under a sharedGroup

----------------------------------------------------------------------
BUGS FIXED IN PATCH Java 3D 1.2.1_02 (as well as patch 1.2.1_03)
----------------------------------------------------------------------
  4451441 Resource cleanup is not in the same Renderer thread
  4457123 freeContext called by Renderer doesn't free resources on Windows
          opengl version
  4457394 NullPointerException when unregister View if Shape3D is not add
          in OG
  4458891 MasterControl throw NullPointerException sometimes when exit
          from applet
  4460081 Transform3D freelist cache is not MT safe
  4461310 Object may disappear in Billboard/OrientedShape3D due to
          numerical problem
  4465145 setFog(null) in immediate mode causes NullPointerException
  4467858 GeometryArrayRetained getDlistTimeStamp() throws
          ArrayIndexOutOfBoundsException
  4468945 Texture coordinate did not work in PureImmediate mode
  4469621 Missing doPrivileged
  4471996 Memory leak cause Java3D crash/OutOfMemory when running for
          long time
  4472252 OrientedShape3D not rendered
  4472407 TextureLoader doesn't optimize loading when YUP/ByReference is used
  4472423 Alt App behaves incorrectly when the bg with altapp is
          attached/detached
  4473661 Crash in Canvas3D.swapBuffers() sometimes when canvas remove
  4474415 PureImmediate offscreen rendering may not render properly
----------------------------------------------------------------------
BUGS FIXED IN PATCH Java 3D 1.2.1_01 (as well as patch 1.2.1_03)
-----------------------------------------------------------------------
  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 Solaris/SPARC/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 Solaris/SPARC requires the following:

  Java 2 Runtime or SDK version 1.2.2 or later from Sun Microsystems.
  (http://java.sun.com/j2se/)

  Frame Buffer with OpenGL support (Expert3D, Elite3D, Creator3D,
  PGX).

  Solaris 2.6 or later.

  OpenGL 1.2.1 for Solaris patch 10 or later.
  To find your current version, use `pkginfo -l SUNWglrt`
  OpenGL for Solaris can be obtained at 
  http://www.sun.com/solaris/opengl

  PATCHES

  There are no patches required for Solaris 8.  However, Java 2
  version 1.3 does require patches.  These patches must be installed
  before trying to install Java 3D.  These patches must be installed in
  order for the Java 3D installer to run properly.


  Solaris 7 requires the Kernel Update patch (106541-06 or later)
  which fixes a bug on multi-processor systems that can lock up
  the window system when running a Java 3D program with more than
  one active window.  Also, Java 2 version 1.3 requires patches.
  These patches must be installed in order for the Java 3D installer
  to run properly.


  Use `showrev -p` to list installed patches.  Patches can be
  downloaded for free from http://sunsolve.sun.com/.

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

To install Java 3D(TM), execute the Java 3D(TM) GUI Installer
program from any directory:

   Runtime only:      java3d-1_2_1-solsparc-rt.bin
   Runtime and SDK:   java3d-1_2_1-solsparc-sdk.bin

After accepting the license agreement and viewing this file,
you will be asked to select which Java(TM) VM to upgrade
with Java 3D(TM).  JVMs from your PATH will be listed, or 
you may choose a different one by selecting its 'java'
executable.

After installation, you may remove the executable GUI installer.

The Java 3D(TM) SDK includes several demo programs that can
verify correct installation.  Assuming your Java 2 SDK is installed
at ~/j2sdk1.3.0_01, try the following:

        cd ~/j2sdk1.3.0_01/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 64 megabytes, add the following
	      command line options to java or appletviewer:
                  java: -mx64m
                  appletviewer: -J-mx64m

Make sure you have the SUNWi1of package (optional fonts) installed by
running `pkginfo SUNWi1of`.  If not present, you may see error messages
like this:

    Font specified in font.properties not found
    [-b&h-lucida sans typewriter-bold-r-normal-sans-*-%d-*-*-m-*-iso8859-1]
    ...

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


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

Java 3D programs can be run in Netscape Communicator on Solaris 
with the Java(TM) Plug-IN (JPI) installed:

  Solaris 8 includes Netscape and the JPI.

  For Solaris 7 users, Netscape Communicator may be downloaded
  for free from http://www.sun.com/solaris/netscape.  Patches
  may be required (see the website for details).

  Netscape Communicator 6.0 automatically includes the JPI.

  Java 1.3 and higher include the JPI.  The Control Panel
  will be at $JAVAHOME/jre/ControlPanel.html.

  If you are using Solaris 7, Java 1.2.2, and Netscape 4.51, 4.7,
  or 4.74, you need to download and install the JPI from 
  http://www.sun.com/solaris/netscape/jpis.  NOTE: requires
  membership to the JDC.  More patches may be required
  (see the website for details).  If you install it in
  the default location (/opt/NSCPcom) the control panel
  will be at file:/opt/NSCPcom/j2pi/ControlPanel.html.

You need to set the NPX_PLUGIN_PATH environment variable
to the directory containing the JPI.  For example, you you
are using the JPI from Java 1.3 installed in ~/j2sdk1.3.0_01,
do 'setenv NPX_PLUGIN_PATH ~/j2sdk1.3.0_01/jre/plugin/sparc'
before starting Netscape.  The default is /opt/NSCPcom.

JDK 1.3.1 and higher have different plugin directories for
Netscape 4.x vs. 6.0.  For Netscape 4.x you need:
  'setenv NPX_PLUGIN_PATH ~/j2sdk1_3_1/jre/plugin/sparc/ns4'
while for 6.0: 
  'setenv NPX_PLUGIN_PATH ~/j2sdk1_3_1/jre/plugin/sparc/ns600'

There is a bug in the Solaris JPI 1.2.2 that keeps it
from finding Java extensions in the lib/ext/ directory
where they are kept.  If you are not using JPI 1.3, 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 ..

To verify proper installation, point your browser to
file:/home/myhome/j2sdk1.3.0_01/demo/java3d/index.html

If it seems like Java 3D isn't installed, make sure the JPI
is using the JVM you've upgraded with Java 3D(TM).  Run the
JPI Control Panel and click on the "Advanced" tab to change
the JVM associated with the JPI.  Under "Java Run Time
Environment" choose "Other..." and Enter the path to your
JVM in the 'Path:' box (for example,
/home/myhome/j2sdk1.3.0_01/jre).  Press "Apply."  (Note:
choose the directory above the 'bin' directory.)

NOTE: Many Java 3D(TM) programs will require a larger heap size
than the default 16M in the JPI.  In the Control Panel
"Java Run Time Parameters" put "mx64m" for 64M of heap memory.

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 (Solaris):

        <JREDIR>/lib/sparc/J3D.so
        <JREDIR>/lib/sparc/j3daudio.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.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


Solaris-specific Bugs
---------------------
none

