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 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. ============ REQUIREMENTS ============ This version of Java 3D(TM) for Windows 98, Mindows ME and Windows 2000 requires the following: Java 2 (Runtime or SDK) version 1.3 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 7.0 or later, available from Microsoft (http://www.microsoft.com/directx/default.asp). ============ 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-win32-directx-rt.exe Runtime and SDK: java3d-1_2_1-win32-directx-sdk.exe The installers will upgrade your most recently installed Java Runtime Environment and SDK. 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 \jdk1.3, try the following: cd \jdk1.3\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 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/ ================================ 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:/jdk1.3/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 -------------- \bin\J3D.dll \bin\j3daudio.dll \lib\ext\vecmath.jar \lib\ext\j3dcore.jar \lib\ext\j3daudio.jar \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: \j3d-utils-src.jar \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 ===================================================== 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 size Point antialiasing PolygonAttributes backFaceNormalFlip RenderingAttributes ROP_XOR 3D Texture Texture color table 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. 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. Only negative polygon offsets are supported. The limit of this offset corresponds to the depth of the z-buffer. The vertex count is limited to 65535 vertices per primitive. 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. Stereo Support -------------- Java 3D can render in stereo mode on graphics cards that support stereo through Direct3D. To enable stereo for a Java 3D application, use the Java 3D property: j3d.stereo. For example: java -Dj3d.stereo=REQUIRED The valid values for the j3d.stereo property are the same as those for the j3d.fullscreen property given above. 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 NOTE: Direct3D only supports stereo mode for a fullscreen canvas. 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. emulation - use Direct3D software emulation. 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. Vertex Buffer optimization --------------------------- By default, DirectX vertex buffer features are used to increase performance whenever the OpenGL display list feature would be used. If there is a problem with your driver's implementation of vertex buffers, turn off this optimization: -Dj3d.vertexbuffer=false Ignored Java 3D Properties -------------------------- The following Java 3D properties are ignored by the Direct3D implementation: j3d.sharedctx j3d.g2ddrawpixel ============== 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 Direct3D specific Bugs ---------------------- Bugs in the NVidia GForce -------------------------- Make sure you have the latest driver, called "Detonator 3": http://www.nvidia.com/products.nsf/htmlmedia/detonator3.html Line patterns do not work. A solid line is shown. To workaround, use -Dj3d.d3dDevice=Emulation / Reference Texture Border color mode does not work. To workaround, use -Dj3d.d3dDevice=Emulation / Reference The TextureMode "CLAMP" does not work. This bug is introduced in the Detonator 3. It happens when it combine with LINEAR filter mode. You can work around this by using Emulation mode or using FASTEST/BASE_LEVEL_POINT in MagFilter/MinFilter. ModelClip did not work under DirectX8.0, use Eumulation mode to workaround this.