Java 3D(TM) 1.3.1 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.4.2 or later from Blackdown (http://www.blackdown.org/) * XFree86 4.2 or later with XFree86's Mesa library and DRI or the NVidia driver 1.0.4499 or later or 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.x 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.3.1 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.3.1-linux-amd64.bin to extract (tar and bzip2 must be installed to do this) E.g.: cd /usr/lib/j2sdk1.4.2 /bin/bash ~/java3d-sdk-1.3.1-linux-amd64.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/js2dk1.3.1, try the following: cd /usr/lib/j2sdk1.4.2/demo/java3d/HelloUniverse java HelloUniverse Java3D 1.3.1 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.3.1-linux-amd64.bin to extract (tar and bzip2 must be installed to do this) E.g.: cd /usr/lib/j2re1.4.2 /bin/bash ~/java3d-re-1.3.1-linux-amd64.bin After installation, you may remove the archive. 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 and Linux, 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 Blackdown and 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.4.2/demo/java3d/index.html ==================================================== 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//libJ3D.so /lib//libj3daudio.so /lib//libJ3DUtils.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.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 Linux-specific Bugs ------------------- none