
Java 3D(TM) 1.3.1

README file for Win32/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 WindowsNT 4.0,
Windows 98, Windows ME and Windows 2000 requires the following:

        Java 2 (Runtime or SDK) version 1.3.1 or later from Sun
	Microsystems (http://java.sun.com/jdk/).  This includes
	the Java Plug-In (JPI) to update Java(TM) in your browser.

        OpenGL 1.1 or later, available from Microsoft or from
        your graphics card manufacturer (see below).

        NT 4.0 only: Service Pack 3 or later.

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

   Runtime only:      java3d-1_3_1-windows-i586-opengl-rt.exe
   Runtime and SDK:   java3d-1_3_1-windows-i586-opengl-sdk.exe

The installers upgrade your most recently installed Java Runtime
Environment and SDK.  

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

        cd \j2sdk1.4.1\demo\java3d\HelloUniverse
        java HelloUniverse

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

If, after installation, you get the following error message while
running a Java 3D program:

  java.lang.UnsatisfiedLinkError: no J3D in shared library path

it is most likely because OpenGL and/or the OpenGL GLU utilities are
not installed on the machine.

For information on OpenGL and how to get it, see the OpenGL web page at
http://www.opengl.org/

Java 3D(TM) consists of four jar files and three 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.  By default, this property is set
to false. 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.

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

The background image can be rendered in two modes: raster and texture. In windows,
the default mode is texture and in Solaris, the default one is raster.
The property j3d.backgroundtexture can be used to control which mode to use.
If you are experiencing slow rendering of background images,
you can change j3d.backgroundtexture property. For example, to enable
texture mode if your have hardware support for texture rendering, 

	java -Dj3d.backgroundtexture=true MyProgram 

======================
Compiled Vertex Array
======================

Compiled Vertex Array extension is used in IndexedGeometryArray
when it's USE_COORD_INDEX_ONLY flag is set and it is not in display list mode.
You may disable the use of this extension by setting the new property,
j3d.compliedVertexArray, to false.

Compiled Vertex Array extension is used extensively, on SUN XVR-4000, for
all GeometryArray type when display list mode is not used.
You may disable the use of this extension by setting the new property,
j3d.compliedVertexArray, to false.

===========================
Multisampling Antialiasing
===========================

By default, full scene antialiasing is disabled if a
multisampling pixel format (or visual) is chosen.
To honor a display drivers multisample antialiasing
setting (e.g. force scene antialiasing), set the 
implicitAntialiasing property to true. 
This causes Java3D to ignore its own scene antialias
settings, letting the driver implicitly implement the 
feature. 

      java -Dj3d.implicitAntialiasing=true MyProgram 

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

You can run Java 3D(TM) programs in your browser.  Java 2(TM)
from 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:/j2sdk1.4.1/demo/java3d/index.html

If you are getting permission exceptions while running the Java 3D
demo programs in your browser, it may be because of bug 4416056.

First, upgrade your Java SDK to the latest release.  The bug may
have been fixed by the time you read this.

To work around the problem, the path to your JRE must not 
contain spaces.  By default, it does ("c:\Program Files\JavaSoft\. . .").
The Java SDK installer automatically installs the JRE in 
c:\Program Files\JavaSoft, so you must run the installers in
this order:
  Java SDK installer
  Java JRE installer (choose a directory with no spaces)
  Java 3D SDK installer (will default to the correct directories)

NOTE: Many Java 3D(TM) programs will require a larger heap size
than the default 16M in the JPI.  Run the Java Plug-In Control
Panel from Start/Programs (JPI 1.2.2) or Start/Settings/Control 
Panel (JPI 1.3) and in "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
--------------

        <JREDIR>\bin\J3D.dll
        <JREDIR>\bin\j3daudio.dll
        <JREDIR>\bin\J3DUtils.dll
        <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.3
========================

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

  A set of new methods is added to the Viewer, a utility class, to 
  support dynamic video resize, specificially targeted for SUN  
  framebuffer : XVR-4000.
  Dynamic video resize is a new feature in Java 3D 1.3.1.   
  This feature provides a means for doing swap synchronous resizing
  of the area that is to be magnified (or passed through) to the
  output video resolution. This functionality allows an application
  to draw into a smaller viewport in the framebuffer in order to reduce
  the time spent doing pixel fill. The reduced size viewport is then 
  magnified up to the video output resolution using the SUN_video_resize
  extension. This extension is only implemented in XVR-4000 and later
  hardware with back end video out resizing capability.
 

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

====================================
Multipass Texture support limitation
====================================
If an application has setup more texture unit states than the graphics 
hardware can support, COMBINE mode will not be supported and Java 3D will 
fallback to the REPLACE mode.

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

        - Some predefined Mouse based behaviors
        - Picking utilities including predefined picking behaviors
        - Geometry creation classes for Box, Cone, Cylinder, and Sphere
        - A Text2D utility
        - Universe Builders - SimpleUniverse and ConfiguredUniverse
        - 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
        - A scenegraph io utility
        - A high resolution interval timer
   
===================================
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

===================================================
Information on Java 3D Audio Device Implementations
===================================================

Java 3D sound is rendered via the use of a specific implementation
of the AudioDevice3D interface.   This release includes two AudioDevice3DL2
implementations: HeadspaceMixer and JavaSoundMixer.  Both of these
implementations are included in the j3daudio.jar.

Please read README.release in program examples Sound directory for details
regarding the feature and format limitations of each of these implementations
and for examples of these use.

=============================================
HeadspaceMixer AudioDevice3DL2 Implememtation
=============================================

 The HeadspaceMixer implementation is part of the Sun Java 3D
 com.sun.j3d.audioengines.headspace package.  This implementation
 uses a version of the Headspace Audio Engine licensed from Beatnik
 which does all rendering in software and pipes the stereo audio image
 to the platform's audio device.

 The implemention that was called JavaSoundMixer in previous Sun
 releases of Java 3D has been renamed to HeadspaceMixer.
 It was renamed in anticipation of the release of a new AudioDevice
 implementation that uses the JavaSound API which will be called
 JavaSoundMixer (described below).

 The HeadspaceMixer audio device will be created and initialized when the
 utility SimpleUniverse.Viewer.createAudioDevice() method is called.
 If your application uses this utility, no change will be required to
 use the recommended HeadspaceMixer implementation.

 If your application explicitly used the older JavaSoundMixer audio device
 implemention from the package com.sun.j3d.audioengines.javasound, you should
 change the reference to JavaSoundMixer, at least for this release,
 to HeadspaceMixer:

     import com.sun.j3d.audioengines.headspace.HeadspaceMixer;
             :
     HeadspaceMixer mixer = new HeadspaceMixer(physicalEnvironment);

 Most of the Java 3D Audio features have been implemented but there are
 a few exceptions.  Additionally, some Java 3D Audio features are only
 only partially implemented.  Please read the README.release document in
 programs/examples/Sound for more information.

 Note that the HeadspaceMixer is not supported in the 64 bit Solaris 
 version of Java 3D.

=============================================
JavaSoundMixer AudioDevice3DL2 Implememtation
=============================================
 
  The JavaSoundMixer implementation is part of the Sun Java 3D
  com.sun.j3d.audioengines.javasound package.  This implementation uses
  the Java Sound API.  All low-level access to the platforms audio device
  are dependent on the Java Sound mixer implementation(s) installed on
  the machine you're running on.
 
  The JavaSoundMixer Java 3D audio device implementation uses Java Sound
  SourceDataLine streams for non-cached data and Java Sound Clips for
  cached data.  Support for specific sound cards, the exact input formats
  that can be passed as data to Java 3D MediaContainers, and which feature
  are rendered in software verses accelleration hardware is dependent on
  the Java Sound implementation installed on your machine.
  There is guarenteed to be at least one Java Sound mixer implementation
  available with all J2SE releases (such as Sun's JDK 1.3 and above).
  Please read the README.release document in programs/examples/Sound.

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

Core Graphics and Vecmath
-------------------------
4685686 Apps Particles sometimes throws ArrayOfBoundsException at GeometryArrayRetained
4794994 Memory leak when SharedGroup removed 
4792478 ArrayIndexOutOfBoundsException with two ViewSpecificGroups with Lights
4793926 Incorrect collison report when geometry close to each other 
4794382 NullPointerException if SharedGroup not set in Link under SwitchGroup 
4798443 RenderBin findOrderedCollection throws IndexOutOfBoundsException 
4800640 D3D: Garbage line appear in TexCubeMap negative & postive Y surface
4805797 View setLocalEyeLightingEnable() does not work
4807209 View setMinimumFrameCycleTime() fail to free CPU time for other applications
4809037 OGL: glLockArrayEXT() should invoke after vertex pointer defined
4826575 J3D fail to run on JDK1.5
4829457 Missing object when lighting change in SDSC ExHenge
4829458 Texture stage fail to disable in accelerated mode for multiTexture apps
4836232 TextureUnitState setTextureAttributes() & setTexCoordGeneration() may not work
4838311 D3D: TextureAttributes in texture stage need to reset for multitexture
4839757 OGL: Incorrect rescale normal extension use for non-uniform scale
4840952 TransformGroupRetained throws NullPointerException if sharedGroup link set null
4843212 AWTEvent disable if canvas remove from panel and add back later after SG Live
4843221 GraphicsContext3D flush(true) hangs for non-visible Canvas3D
4846822 NullPointerException in MasterControl addFreeImageUpdateInfo

Utilities
---------

4331669 setRectangleScaleFactor will not change text size unless setString called (doc?)
4780878 ConfiguredUniverse needs a way to access multiple behaviors
4801176 Sphere Texture map reverse when GENERATE_NORMALS_INWARD is used
4803241 EdgeTable & Edge.java use by NormalGenerator missing in java3d-utils-src.jar
4822946 Picking throws NullPointerException for BoundingBox/Sphere/Polytope PickShape 
4822988 SceneGraphIO throws NullPointerException when Morph Node is read
4827900 TransformInterpolatorState source missing in j3d-utils-src.jar
4830842 Triangulator fails for polygons with holes in YZ or XZ plane

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

4303056  Docs should specify thread-safety behavior of Java 3D methods
4350033  JFTC: possible conflict between implementation and spec on PolygonOffset
4391492  Rotation matrix of Transform3D constructor not extract
4514880  results of changing geometry and texture are not well documented
4632391  Typo in doc j3d_tutorial_ch2.pdf
4698350  Spec. did not mention alpha component for Texture Mode REPLACE, MODULATE clearly

Core Graphics and Vecmath
-------------------------

4509357  example program - raster image incorrect until mouse moved into window
4512179  Undeterminable behavior caussed by Appearance.setTexture
4516005  AddRemoveCanvas2 fail to show cube intermittently
4518080  Light scoping sometimes not working for compiled geometry
4529297  TCK: Group.removeAllChildren() inconsistent with expected behavior
4667088  sas applications gets VerifyError running with 64-bit JVM
4669211  SharedGroup.getLinks().length is always zero for non-live Link node.
4674146  Background texture fail to render for RenderedImage and byref ImageComponent2D
4674843  ImageComponent3D byReference always make an internal copy
4676035  Off screen rendering has off-center view
4676483  Geometry by Reference change alpha color component of user data
4680305  Detaches of SharedGroups from user threads is not Mt-Safe
4681750  Texture3D throws ArrayIndexOutOfBoundsException when scaleImage
4681863  OGL: OffScreen canvas ignore GraphicsConfigTemplate under windows
4684405  j3d holds a reference to user's bounds (via setBounds()) for use in getBounds().
4684807  NullPointerException in NodeComponent during setAppearance()
4686527  Deadlock between MasterControl and user thread when using ByRef updateData()
4697155  ByRef USE_COORD_INDEX_ONLY geometry not yet implement for optimizeForSpace=false
4701430  Infrequent NPE at RenderBin.java:544
4705053  OrientedPtTest example program displays frame lag
4712205  Window panels disappear when BranchGroup.compile() is used.
4714426  compile() removes null child eventhough ALLOW_CHILDREN_READ is set.
4720938  IndexedGeometry shouldn't consider vertex not reference by index in computeBound
4736484  Big alpha value in byRefColor render geometry even though transparency = 1.0
4740086  Picking cause lots of GC in PickShape intersect() routine
4751162  View TRANSPARENCY_SORT_GEOMETRY throws NullPointerException when viewpoint move
4751283  Transform3D.normalize() and Matrix4d.get(Matrix3d) permute matrix columns
4753957  Morph only consider first GeometryArray when compute bounds
4762021  Transform3D setScale() fail to return negative scale in some case
4762753  Precision problem of OrientedShape3D.ROTATE_ABOUT_POINT if far away from origin
4768237  RuntimeException in pickIntersection.getPointNormal()
4768353  JBrawl does not run smoothly with > 2 cpus
4774341  Locale need a wait between changing HiRes and adding branch graph
4782718  NPE if boundingLeaf in SchedulingBoundLeaf not attach to scenegraph
4783638  WakeupOnAWTEvent does not support MouseWheelEvent
4789101  J3D.dll is accessing jniGetObjectClass inside the critical region
4790016  PickObject generatePickRay return wrong PickShape if View compatibility enable
4794998  hashKey output TROUBLE message when OutOfMemory
4828096  Morph doesn't work correctly with Java3D 1.3
4828098  Morph doesn't use its weights, when it was cloned with cloneTree()

Sound
-----

4634751  BackgroundSound fails to activates with the view intersects it's bounds.
4680280  JavaSoundMixer play sound only once
4760772  BackgroundSounds not looping with HeadspaceMixer mixer

Utility Bugs
------------

4717595  SceneGraph IO bug in J3DFly
4718786  Incorrect coefficients in CubicSplineSegment computeCommonCoefficients()
4805076  Transform3D.get(Matrix3f ) occasionally returns incorrect values

Windows/OGL-specific Bugs
---------------------
none

