#if 0 /* * $RCSfile$ * * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved. * * Use is subject to license terms. * * $Revision$ * $Date$ * $State$ */ #endif ======================================================================== ======================================================================== NOTE: THIS FILE REFERS TO THE 1.3.1 BINARY RELEASE OF THE JAVA 3D API AND, AS SUCH, IS OUT OF DATE. IT NEEDS TO BE UPDATED FOR the 1.3.2 RELEASE. ======================================================================== ======================================================================== Java 3D(TM) 1.3.1 #if defined(WIN32OGL) 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. #elif defined(SOLARIS) 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 ** removed before installing this version. #else README file for Win32/DirectX 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. #endif ============ REQUIREMENTS ============ #if defined(SOLARIS) This version of Java 3D(TM) for Solaris/SPARC requires the following: Java 2 Runtime or SDK version 1.4 or later from Sun Microsystems. (http://java.sun.com/j2se/) Frame Buffer with OpenGL support (XVR-500, XVR-1000, XVR1200, XVR-4000, Expert3D, Elite3D, Creator3D, and PGX). Solaris 7 or later. OpenGL 1.2.2 for Solaris or later. Depending on type of frame buffer, a higher OpenGL version might be needed, such as XVR-1000 requires OpenGL 1.2.3. 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 versions 1.4 and 1.4.1 do require patches. These patches must be installed before trying to install Java 3D. 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 versions 1.4 and 1.4.1 require patches. These patches must be installed before trying to install Java 3D. Use `showrev -p` to list installed patches. Patches can be downloaded for free from http://sunsolve.sun.com/. #elif defined(WIN32OGL) 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.4 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. #elif defined(WIN32D3D) This version of Java 3D(TM) for Windows 98, Mindows ME and Windows 2000 requires the following: Java 2 (Runtime or SDK) version 1.4 or later from Sun Microsystems (http://java.sun.com/jdk/). This includes the Java Plug-In (JPI) to update Java(TM) in your browser. DirectX 8.0 or later, available from Microsoft (http://www.microsoft.com/directx/default.asp). #endif ============ 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. #if defined(SOLARIS) To install Java 3D(TM), execute the appropriate self-extracting shell script. Runtime only: java3d-1_3_1-solaris-sparc-rt.bin Runtime and SDK: java3d-1_3_1-solaris-sparc-sdk.bin 64 bit Runtime: java3d-1_3_1-solaris-sparcv9.bin For the two runtime versions, execute the script in the destination jre directories. Note: The 64 bit runtime only contains the nessesary 64 bit components. Install it in the jre directory after installing the regular runtime files. For the runtime and sdk bundle, execute the script in the destination sdk directory. The Java 3D(TM) SDK includes several demo programs that can verify correct installation. Assuming your Java 2 SDK is installed at /usr/j2se, try the following: cd /usr/j2se/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] ... #elif defined(WIN32OGL) 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\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 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/ #elif defined(WIN32D3D) To install Java 3D(TM), execute the InstallShield binaries. Runtime only: java3d-1_3_1-windows-i586-directx-rt.exe Runtime and SDK: java3d-1_3_1-windows-i586-directx-sdk.exe The installers will 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\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 meg, add the following command line options to java or appletviewer: java: -mx64m appletviewer: -J-mx64m #endif 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/ #if defined(WIN32OGL) || defined(SOLARIS) =============== 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 #endif #if defined(WIN32OGL) 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 #endif ====================== 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.compiledVertexArray, 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.compiledVertexArray, 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 ================================ #if defined(WIN32OGL) || defined(WIN32D3D) 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. #elif defined(SOLARIS) 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.4.1 installed in /usr/j2se, do 'setenv NPX_PLUGIN_PATH /usr/j2se/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 /usr/j2se/jre/plugin/sparc/ns4' while for 6.0: 'setenv NPX_PLUGIN_PATH /usr/j2se/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:///usr/j2se/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, /usr/j2se/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. #endif 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 -------------- #if defined(SOLARIS) When bundling Java 3D(TM) with your application, the following files must be included (Solaris): /lib/sparc/libJ3D.so /lib/sparc/libj3daudio.so /lib/sparc/libJ3DUtils.so /lib/ext/vecmath.jar /lib/ext/j3dcore.jar /lib/ext/j3daudio.jar /lib/ext/j3dutils.jar #elif defined(WIN32OGL) || defined(WIN32D3D) \bin\J3D.dll \bin\j3daudio.dll \bin\J3DUtils.dll \lib\ext\vecmath.jar \lib\ext\j3dcore.jar \lib\ext\j3daudio.jar \lib\ext\j3dutils.jar #endif Optional Files -------------- An application developer may include these files and directories with their Java 3D(TM) application, but is not required to do so: #if defined(SOLARIS) /j3d-utils-src.jar /demo/java3d #elif defined(WIN32OGL) || defined(WIN32D3D) \j3d-utils-src.jar \demo\java3d #endif ======================== 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 #if defined(SOLARIS) ========================================================= Support for disabling X11 Xinerama mode in Solaris OpenGL ========================================================= Solaris OpenGL is well optimized in general for single-threaded applications running in the Xinerama virtual screen environment, but there are two situations in which significant degradations in graphics performance may be experienced by multi-threaded OpenGL clients such as Java 3D applications. The first is when using GeometryByReference, which is implemented through the use of OpenGL vertex arrays. This is essentially treated as immediate mode data by Solaris OpenGL, which in multi-threaded mode incurs the expense of copying data for multiple graphics pipelines even when a single window on a single screen is being used. The second is for applications using multiple Canvas3D objects. The X11 Xinerama extension internally creates separate graphics resources on each physical screen for each window created on the virtual screen. This causes significant overhead for multi-threaded Solaris OpenGL clients. Java 3D provides a new property in this release, j3d.disableXinerama, which when set to true will disable the use of Xinerama features by Solaris OpenGL. This increases performance in the two situations up to 75%, equivalent to that of running in a non-Xinerama environment. The drawback of setting this property is that when moving a Canvas3D from one physical screen to another the graphics rendering will be clipped to the physical limits of the original screen on which it was created. The property is primarily intended to benefit fullscreen applications using multiple physical screens or fullscreen applications using GeometryByReference. To use it, specify the property value on the command line: java -Dj3d.disableXinerama=true Disabling Xinerama requires both JDK 1.4 or later and Solaris OpenGL 1.2.2 or later. Solaris 7 and 8 must be upgraded to the patch level required by JDK 1.4. #endif #if defined(WIN32D3D) ===================================================== Information on the Direct3D Implementation of Java 3D ===================================================== Unsupported Features -------------------- The following features are currently unsupported in the Direct3D implementation of Java 3D: Line width Line antialiasing Point antialiasing PolygonAttributes backFaceNormalFlip RenderingAttributes ROP_XOR Stereo Texture features not support: Texture color table Base/Maximum Level Max/Minimum LOD LOD offset Detail Texture Sharpen Texture Function Filter4 Function Boundary width Boundary mode CLAMP_TO_EDGE & CLAMP_TO_BOUNDARY (will fall back to CLAMP) Texture blend color when multiple pass is used to simulate multiTexture. Limited Support --------------- FullScreen antialiasing is supported only if the device returns D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT in its raster capabilities list. (OpenGL supports fullscreen antialiasing if an accumulation buffer exists.) TransparencyAttributes.TransparencyMode values FASTEST, NICEST and SCREEN_DOOR are the same as BLENDED under D3D. DepthComponent in certain display mode when stencil buffer is selected (use for DecalGroup) since depth Buffer Component Read/write can't coexist with Stencil buffer in DirectX8.0. OffScreen rendering with width/height > current desktop size Texture coordinates outside the range [0,1] when boundaryModeS and boundaryModeT are set to CLAMP will not use the Texture Boundary' color unless BASE_LEVEL_LINEAR filtering is turned on. If the driver did not expose D3DPTADDRESSCAPS_BORDER capability bit (viathe directX SDK utility Caps Viewer). Then it didn't support Texture Border color mode. Default color as in Clamp mode will be used in this case. Most driver currently available need to workaround using reference mode (-Dj3d.d3dDevice=Reference). if the driver did not expose D3DPMISCCAPS_LINEPATTERNREP capability bit then it didn't support line patterns. A solid line will be shown in this case. Most driver currently available need to workaround using reference mode. Only negative polygon offsets are supported. The limit of this offset corresponds to the depth of the z-buffer. Float anisotripic filter degree did not support. They will round off to integer value and pass down to the DirectX library. Texture environment combiner : COMBINE_REPLACE - Support if driver expose TextureOpCaps D3DTOP_SELECTARG1. Only combine scale 1 is support. COMBINE_MODULATE - Support if driver expose TextureOpCaps D3DTOP_MODULATE, D3DTOP_MODULATE2X, D3DTOP_MODULATE4X for scale 1, 2 & 4 respectively. COMBINE_ADD - Support if driver expose TextureOpCaps D3DTOP_ADD, only combine scale 1 is support COMBINE_ADD_SIGNED - Support if driver expose TextureOpCaps D3DTOP_ADDSIGNED, D3DTOP_ADDSIGNED2X for scale 1 & 2 respectively. Combine scale 4 will fall back to 2. COMBINE_SUBTRACT - Support if driver expose TextureOpCaps D3DTOP_SUBTRACT. Only combine scale 1 is support. COMBINE_INTERPOLATE - Support if driver expose TextureOpCaps D3DTOP_LERP. Only combine scale 1 is support. COMBINE_DOT3 - Support if driver expose TextureOpCaps D3DTOP_DOTPRODUCT3 Only combine scale 1 is support. Rendering Different between OGL & D3D -------------------------------------- - SpotLight formula is different, OGL will normally have a bigger bright spot. - TexCoordGeneration Sphere Map formula is different, OGL will normally has texture map that zoom closer than D3D. - Specular hightlight in Texture mapping mode may different. If OGL driver support separate specular color, then resulting specular highlight in texture are the same. Otherwise D3D verson will have a brighter and more obviously specular highlight compare with OGL. Fullscreen Support ------------------------ The Direct3D implementation of Java 3D can be run in fullscreen mode. To start an application in fullscreen mode, use the property j3d.fullscreen. The values for j3d.fullscreen are: REQUIRED - A fullscreen canvas is required. If not available, do not start up the application. PREFERRED - A fullscreen canvas is desired for this invocation of the Java 3D application. If a fullscreen canvas cannot be created, a windowed canvas is acceptable. UNNECESSARY - States that a fullscreen canvas is not necessary for this application. Create a windowed application (this is the same behavior as not setting this property). Example: java -Dj3d.fullscreen=REQUIRED HelloUniverse Further, an application can be toggled between fullscreen and windowed mode by use of the keyboard combination. When using JDK1.4 fullscreen API with Java3D DirectX version, it is necessary to set the following property : -Dsun.java2d.noddraw=true Direct3D Driver Selection ------------------------- When there is more then one device associated with a monitor, by default, Java 3D uses the first driver found on a given display. This order can be found by using the -Dj3d.debug=true property during Java startup. In order to use a 3D only graphics card such as Voodoo1/2 A new property has been added -Dj3d.d3ddriver=idx where idx is the driver order number (starting with 1) found using the debug property above. This will force Java 3D to use the driver specified by the user (this may fail if the driver is not compatible with the display). For a typical setup with a 3D only card attached to a single monitor system, use idx=2. This will automatically toggle to fullscreen hardware acceleration mode. Direct3D Device Selection ------------------------- In order to aid in development and debugging, Java 3D has added a property to allow the D3DDevice to use for rendering to be selected. The property, j3d.d3ddevice can have the following values: tnlhardware - select a device that supports transform and lighting in hardware, if present. If no such device is present, a dialog box is displayed to alert the user and the application will exit. hardware - select a Direct3D device that performs hardware rasterization, if present. If no such device is present, a dialog box is displayed to alert the user and the application will exit. reference - use the Direct3D reference pipeline (only available if the Direct3D SDK is installed). By default Java 3D first tries to select a TnLhardaware device, if that fails a Hardware device, if that also fails then finally Java 3D selects an Emulation device. Ignored Java 3D Properties -------------------------- The following Java 3D properties are ignored by the Direct3D implementation: j3d.sharedctx j3d.stereo j3d.sharedstereozbuffer j3d.g2ddrawpixel j3d.usecombiners j3d.disableSeparateSpecular j3d.backgroundtexture j3d.disableXinerama #endif =================================================== 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 #if defined(SOLARIS) Solaris-specific Bugs --------------------- none #elif defined(WIN32OGL) Windows/OGL-specific Bugs --------------------- none #elif defined(WIN32D3D) Direct3D specific Bugs ---------------------- Problem in the NVidia GForce ----------------------------- Make sure you have the latest driver from http://www.nvidia.com/ ModelClip did not work under DirectX8.0 debug build, use Eumulation mode to workaround this. #endif