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 Linux/OpenGL This file contains important information for users of Java 3D(TM). The first four sections (Requirements, Installation, Shared Contexts, and Running Java 3D(TM) in a Browser) are of interest to all Java 3D(TM) users. The rest of this file applies only to developers of Java 3D(TM) applications. ** It is recommended that any previous version of Java 3D(TM) be ** uninstalled before installing this version. ============ REQUIREMENTS ============ This version of Java 3D(TM) for Linux requires the following: Java 2 Runtime or SDK version 1.3.1 or later from Blackdown (http://www.blackdown.org/) or Sun Microsystems (http://java.sun.com/j2se/). XFree86 3.3.6 with Mesa 3.1 or later or XFree86 4.0.3 or later with XFree86's Mesa library and DRI or XFree86 4.0.3 with NVidia drivers 1.0-2313 or later or XFree86 4.0.3 with an official (ie. not XFree86's) Mesa library (http://www.mesa3d.org/) if you can't or don't want to use DRI Note that XFree86 4 with XFree86's Mesa library without DRI is not supported at this time! Most likely the XServer will crash when you close Java3D application with that setup. ============ INSTALLATION ============ You must have permission to write files in your Java(TM) Runtime Environment and/or SDK directories. If you do not have this permission, the installer will run to completion but Java 3D(TM) will not be installed. Make sure you are running Java(TM) from your local machine and that you are the same user who installed Java. Java3D 1.2.1_03-FCS SDK: ------------------------ Change your working directory to the the top level directory of the J2SDK you wish to install Java 3D(TM) into. Then run java3d-sdk-1.2.1_03-fcs-linux-.bin to extract E.g.: cd /usr/lib/j2sdk1.3.1 /bin/sh ~/java3d-sdk-1.2.1_03-fcs-linux-i386.bin After installation, you may remove the archive. The Java 3D(TM) SDK includes several demo programs that can verify correct installation. Assuming your Java 2 SDK is installed at /usr/lib/j2sdk1.3.1, try the following: cd /usr/lib/j2sdk1.3.1/demo/java3d/HelloUniverse java HelloUniverse Java3D 1.2.1_03-FCS Runtime Environment: ---------------------------------------- Change your working directory to the the top level directory of the J2RE you wish to install Java 3D(TM) into. Then run java3d-re-1.2.1_03-fcs-linux-.bin to extract E.g.: cd /usr/lib/j2sdk1.3.1 /bin/sh ~/java3d-re-1.2.1_03-fcs-linux-i386.bin After installation, you may remove the archive. Packages for Debian: -------------------- Select one of the Blackdown mirrors (http://www.blackdown.org/java-linux/mirrors.html) and add a line of the form deb ftp:////debian non-free to /etc/apt/source.list. should be potato or woody. E.g., if you want to use the woody tree on ftp.tux.org you would use deb ftp://ftp.tux.org/java/debian woody non-free Then install java3d-sdk or java3d-re using the standard Debian tools. No further setup is required. Java 3D(TM) consists of four jar files and two shared libraries. You do not need to include the jar files in your CLASSPATH, nor do you need to include the shared libraries in your PATH/LD_LIBRARY_PATH. You should include "." in your CLASSPATH or ensure that CLASSPATH is not set. Java 3D documentation and tutorials are available from the Java 3D(TM) Home Page: http://java.sun.com/products/java-media/3D/ =============== SHARED CONTEXTS =============== This version of Java 3D by default uses shared contexts in OpenGL for Display Lists and Texture Objects. For single canvas applications, there will be no change in behavior. For multiple canvas applications, memory requirements will decrease by using this property. Some video cards (e.g. from NVidia) have problems using shared contexts. If you are experiencing no rendering, crashes, deadlocks with System.exit(), or no textures being displayed when shared contexts are enabled, this is the most likely problem. To disable the use of shared contexts either set the j3d.sharedctx property to false, for example: java -Dj3d.sharedctx=false MyProgram or set the environment variable J3D_USE_SHARED_CONTEXT to FALSE. ================= Background Images ================= Some older PC video cards (such as the Riva TNT) render background images very slowly. If you are experiencing slow rendering of background images, you can set the j3d.g2ddrawpixel property to false. This may yield better performance for you card. Example: java -Dj3d.g2ddrawpixel=false MyProgram ================================ RUNNING JAVA 3D(TM) IN A BROWSER ================================ You can run Java 3D(TM) programs in your browser. Java 2(TM) from Blackdown or Sun includes the Java Plug-In (JPI) to upgrade the Java(TM) in the browser to Java 2(TM). To verify proper installation, point your browser to file:///usr/lib/j2sdk1.3.1/demo/java3d/index.html To create a web page with Java 3D, you need to use special HTML code to force the browser to use the JPI VM. Refer to the following URL for information on using Java Plug-In "HTML Converter" and running applets using Java Plug-in: http://java.sun.com/products/plugin/ ==================================================== DISTRIBUTING Java 3D(TM) WITH YOUR JAVA(TM) PROGRAMS ==================================================== Sun Microsystems allows vendors to distribute the Java 3D(TM) Runtime environment with their Java programs, provided they follow the terms of the Java 3D(TM) Binary Code License and Supplemental License Terms agreement. This document uses the term "vendors" to refer to licensees, developers, and independent software vendors (ISVs) who license and distribute Java 3D(TM) with their Java programs. REQUIRED vs. OPTIONAL FILES --------------------------- Vendors must follow the terms of the Java 3D(TM) Evaluation License agreement, which includes these terms: - Don't arbitrarily subset Java 3D(TM). You may, however, omit those files that have been designated below as "optional". - Include in your product's license the provisions called out in the Java 3D(TM) Evaluation License. BUNDLING Java 3D(TM) -------------------- Java 3D(TM) comes with its own installer that makes it suitable for downloading by end users. Java(TM) application developers have the option of not bundling Java 3D(TM) with their software. Instead, they can direct end-users to download and install the Java 3D(TM) software themselves. Required Files -------------- When bundling Java 3D(TM) with your application, the following files must be included: /lib//J3D.so /lib//j3daudio.so /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 ============== KNOWN PROBLEMS ============== To get the very latest list of known Java 3D bugs, look on the Java Bug Parade (http://developer.java.sun.com/developer/bugParade/index.html) Documentation Bugs ------------------ 4161432 Transform3D transform definitions are imprecise with respect to mirror transform 4259353 documentation for com.sun.j3d.utils.geometry.Box is confusing 4303052 Quaternion documentation is inadequate 4303053 javadoc for DistanceLOD with multiple switch nodes needs improvement 4303054 Lighting equations should be updated to reflect color override 4303055 Docs should specify effect on clipped portion of ImageComponent 4303056 Docs should specify thread-safety behavior of Java 3D methods 4303062 Need to specify which attributes are passed by reference versus by value 4307547 Need to doc. : scene graph needs to have at least a Canvas3D to keep j3d working 4312421 Need to document texture by reference 4391487 Transform3D CONGRUENT definition is not clear 4421320 Can't update live geometry or texture image from Canvas3D callback Examples -------- 4312044 java Viewer reflects only Lightwave objects with depth Installation Bugs ----------------- 4370320 InstallAnywhere failed to display text selection under JTG 1.2.1 and JTG 1.2.2 4370346 Sometimes InstallAnywhere not able to remove Java 3D jar files during uninstall Core Graphics and Vecmath ------------------------- 4154445 PathInterpolator's setKnot method does not validate inputs 4160172 Access to some aggregate data is not MT-safe 4179923 ReadRaster does not clip to screen correctly 4181340 Updating the view cache could be a problem if other canvas running on same view 4181344 Java 3D cannot handle more than 64 lights 4181349 Need to add Transform to SceneGrphPath hashCode 4181417 Need to add an internal epsilonEquals method for bounds objects 4186182 sceneAntialiasing setting of PREFERRED is ignored 4189092 HEAD_PREDICTOR and HAND_PREDICTOR policies not implemented 4191172 Text3D rendering problems 4193466 GMatrix SVD does not work correctly for some cases. 4246325 AWT Event once enable, will not disable when behavior remove 4259345 Text3D does not correct convert geometry of Japanese-text 4260818 java3d should support stereo graphics automatically 4269784 vecmath.GMatrix.LUD inefficient 4296708 Cannot detach BranchGroup from TransformGroup, despite proper capabilities 4299480 readRaster() and waitForOffScreenRendering() will not work if threadLimit=1 4313678 Java3D disables invalid lights 4319780 RFE: java3d scene graph objects are not serializable 4331677 setWindowResizePolicy(View.VIRTUAL_WORLD) doesn't work 4335245 Raster type RASTER_COLOR_DEPTH did not work as expect 4340607 Node and NodeComponent's set* methods not synchronized with set/clearLive 4348562 GMatrix SVD method incorrect output and throws ArrayIndexOutOfBoundsException 4348609 Poor rendering of textures on NT with 16 bit color 4351050 APIs issue : Shape3D and Morph's intersect method. 4351579 APIs issue : Shape3D intersect method -- multiple geometry support 4355332 Require Thread safe removeChild in BranchGroup 4357843 Picking doesn't handle OrientedShape3D's orientation when doing intersect test. 4359609 MediaContainer does nto report errors 4359764 Java3D does not support > 32 canvas 4363761 getImagePlateToVworld not synchronized with View< 4363899 APIs issue : OrientedShape3D's intersect method needs view info. 4366060 ObjectFile.load() throws IndexOutOfBoundsException 4366511 Full scene antialiasing slow under OpenGL 4368961 Locale.addBranchGraph doesn't check for already live branch graph 4370378 ImageComponentByReferenceTest raster image disappeared after window maximized 4371535 when PickTool cursor's update is enabled, the camera/view no longer updates 4373686 Using scrollbar on Applets not working under Win32 4374220 setPickTolerance doesn't seems to have effect when doing parallel proj. picking. 4377979 Transform3D classify is too slow and is called unnecessarily 4386903 DistanceLOD API inconsistant 4391492 Rotation matrix of Transform3D constructor not extract 4395292 Transform3D consume lots of memory 4396453 Bounding polytope should check for NaN bounds 4396990 StackOverflowError in PIckResult.toString() 4400608 java.lang.ArrayIndexOutOfBoundsException in examples/PickTest/PickTest 4401274 background color affect geometry color when scene antialiasing is used 4401323 Transparency value ignored for RGBA rasters 4408505 memory leak in immediate mode texture when texture keep changing 4409793 ImageComponent and Transform not updated synchronously 4412868 Alpha setMode() did not handle increasing/decreasingAlphaDuration correctly 4416025 MediaContained.setURLString() doesn't throw SoundException if URL is bad 4416995 Text2D.setString(String) restores filter setting default values 4416996 setVisible(false) affecting objects that did not have attribute set 4416999 Differences in rendering between retained and immediate modes w/same Appearance 4417459 GMatrix SVD incorrect 4419187 Texture2D ignored if not enabled when made live 4419189 Sound node ignores Switch value 4420303 D3D: object may disappear when canvases share scenegraph move between monitors 4420305 sound/animation sometimes disrupted by menus 4421860 PickTest : PickCylinder unable to pick point/line when pick mode set to GEOMETRY 4422273 In a multiple views setup, object may not be visible to all canvases, at startup Sound ----- 4138605 using any non-javasound java sound causes severe performance hit 4164181 Sound performance on native threads is bad 4187092 Filtering causes loud, sweeping resonance to be added to most sounds 4187093 Cross-talk cancellation for sound playback in not implemented 4419189 Sound node ignores Switch value 4419938 ConstructPoints, MixedMode Sound problems 4315018 Garbage sound in TestFilter 4360462 Sound nodes referencing InputStream MediaContainer not fully functional 4360463 Doppler calculated results in less than expected frequency variation 4374943 SoundScheduler hangs under windows 4404165 Sound attributes did not check illegalSharing correctly Utility Bugs ------------ 4173647 Cannot share Sphere objects of same size between immediate and retained mode 4217567 NormalsGenerator only checks the cosine for smoothing 4252349 First viewport may jump when using KeyNavigatorBehavior 4259533 getTexture() throws NullPointerException when using proxies 4308592 texture loader does not scale non-power-of-2 RGBA textures properly 4327643 RFE: LW3Dloader needs to be able to load 'other' image file formats 4331669 setRectangleScaleFactor will not change text size unless setString called 4336679 In examples/PickTest program, a pick miss can happen on morph object. 4343427 Loader interface has no facility to monitor progress of Load Operation 4347998 PickTool pickGeomAllSorted did not compute closest distance for PickConeRay 4367699 Lightwave Loader throws NullPointerException when loading data from a Stream 4372387 TextureLoader throws SecurityException 4372722 ObjectFile loader hangs when loader .jpg file 4374631 CompressedGeometryFile can't be used by applets with default security 4374633 CompressionStream should provide a method for getting original bounds 4375265 ViewingPlatform Behavior support far too restrictive. API needs updating 4376368 Adding KeyNavigatorBehavior will keep cpu busy 4386880 TextureLoader should use imageio loaders 4391167 Triangulator unable to handle some polygons with holes. 4391507 MouseBehavior did not handle setEnable() correctly to remove buffer events 4394017 debug message not remove in utility Numerics Linux-specific Bugs ------------------- none