Java 3D(TM) 1.3.1 Beta 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.1 or later from Blackdown (http://www.blackdown.org/) or Sun Microsystems (http://java.sun.com/j2se/). * glibc-2.2.5 or later * XFree86 4.1 or later with XFree86's Mesa library and DRI or the NVidia driver 1.0.4191 or later or the ATI Fire GL2/3/4 drivers X4.1.0-1.9.16 or later (In order to get hardware acceleration withe Fire GL2/3/4 driver you have to set LD_PRELOAD=/usr/lib/libGL.so before starting Java 3D applications. E.g. "LD_PRELOAD=/usr/lib/libGL.so java HelloUniverse" According to ATI this problem is fixed in the 1.9.19 driver.) 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.1 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-beta 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-beta-linux-.bin to extract (tar and bzip2 must be installed to do this) E.g.: cd /usr/lib/j2sdk1.4.1 /bin/bash ~/java3d-sdk-1.3.1-beta-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/js2dk1.3.1, try the following: cd /usr/lib/j2sdk1.4.1/demo/java3d/HelloUniverse java HelloUniverse Java3D 1.3.1-beta 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-beta-linux-.bin to extract (tar and bzip2 must be installed to do this) E.g.: cd /usr/lib/j2re1.4.1 /bin/bash ~/java3d-re-1.3.1-beta-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 main 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 main Then install java3d-sdk-beta or java3d-re-beta using the standard Debian tools. No further setup is required. 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 =========================== 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.1/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 ========== Documentation ------------- 4693320 Javadoc missing for TCBKeyFrame, CubicSplineSegment, and CubicSplineCurve Core Graphics and Vecmath ------------------------- 4191172 Text3D rendering problems 4259345 Text3D does not correct convert geometry of Japanese-text 4266866 Text3D handles badly the 2-byte international characters. 4466779 NullPointerException using MoveTo when BG not in scenegraph 4476109 OGL: DecalGroup afffect render of other primitive under windows 4513029 J3dI18N: Error using IndexedGeometryArray.getInitialIndexIndex 4516966 Font extrusion for 3D text can generate NaN 4656945 jtest.other.Examples.AddRemoveCanvas2 sometimes throws ArrayIndexOutOfBoundsExce 4661470 Memory not released by Java 3D applets 4683493 CompressGeometry should render as transparency for polygon line antialias mode 4687389 View isBehaviorSchedulerRunning() may always return true 4688070 Memory not immediately reclaim when branchgroup remove 4702086 D3D: crash when fallback to software mode also fail 4707919 D3D: crash when QuadArray vertex count > 43690 4708566 setxxxRefxxx() throws ArrayIndexOutOfBounds for valid IndexedGeometryArray 4709318 OGL: Fail to destroy displayList in case of multiple canvases when canvas remove 4711657 Trouble with Link/SharedGroup at set live - in both memory and setup time. 4713671 Problem with Transparency sorting on Switch group. 4716435 Possible deadlock in TimerThread when removeAllLocates() is invoked 4717253 D3D: May crash in buildGA when texture is not used under JDK1.3.1 4718725 OrientedShape3DRenderMethod throws NullPointerException in j3dfly 4719308 Deadlock in PureImmediate mode if AWT Thread invoke cv.swap() before 1st paint 4721635 1.3 RenderingAttibutes setVisible not honored 4722648 Non-uniform scale causes lighting errors 4730225 ViewPlatform setActivationRadius not honor before scenegraph make live 4730461 Incorrect capabilityNotSetException message output for Node.getCollidable 4732333 View setMinimumFrameCycleTime() did not response until last cycle complete setM 4732956 Raster z value set incorrectly when setDstOffset() or CLIP_IMAGE mode is used 4732965 Raster CLIP_IMAGE mode cause flickering when part of it is clipped 4733554 OrientedShape3D scale not work when set before live 4733572 Raster setDstOffset() cause geometry to jump momentarily whenever setGeometry() 4735143 IndexedLineStripArray missing after compile if Shape3D merge 4737066 Incorrect initialTexCoordIndex when using setTexCoordRef2f/3f 4742827 destroyContext() may not invoke under Solaris when sharedCtx = false 4743398 Geometries disappear after changing TransparencyAttributes4742720 Memory leak when non-byRef ImageComponent is used for Raster 4747248 DecalGroup should treat as OrderedGroup if stencil buffer not support 4748837 Memory leak when new texture is set in Appearance 4749885 setxxxRefxxx() did not check index limit correctly for IndexedGeometryArray 4752616 NullPointerException when vertexFormat not specified in byRef but array is set 4760882 Picking does not return proper result 4774337 Bounds do not recompute when setting Coordinates in a not live GeometryArray 4777750 PickShape BoundingPolytope fail to compute intersection correctly 4777781 Deadlock when getBestConfiguration() is invoked from Behavior thread 4784249 readRaster crash if imageComponent size pass in is smaller than Raster size 4792484 Intersect fails for cylinder and cone rays and triangle or quad geometries Sound ----- 4786990 ConeSound setDistanceGain() fail to set backGain 4783790 MediaContainer fail to handle inputstream 4786979 audioengines.Sample.clear() throws NullPointerException intermittently 4787011 MoveAppBoundingLeaf examples may throw NoSuchElementException when program exit 4787253 Sound setEnable(false) not work Utilities --------- 4676082 possible NullPointerException in ViewPlatformAWTBehavior 4692475 saveChildren() return is ignored 4712222 PickRay computation is not numerically stable 4721663 Incorrect RuntimeException message for PickResult when PickPoint is used 4725633 ConfiguredUniverse needs to instantiate AWT InputDevice implementations 4730414 Text2D setString() throws Texture illegal size Exception 4730897 CompressedGeometryState throws NullPointerException if header lowerBound is null 4735222 GeometryCompressor fails with consecutive nearly-equal positions 4778482 ConfiguredUniverse only reads local config files 4791840 Universe cleanup() causes NullPointerException ============== 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 ------------------------- 4712205 Window panels disappear when BranchGroup.compile() is used. 4714426 compile() removes null child eventhough ALLOW_CHILDREN_READ is set. 4762021 Transform3D setScale() fail to return negative scale in some case 4792478 ArrayIndexOutOfBoundsException with two ViewSpecificGroups with Lights 4774228 Wrong quaternion result at Quat4*.set(Matrix3*) with some matrices 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 4676808 View class needs getTrackerBaseToVworld() 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 4707462 Canvas3D needs a getImagePlateToViewPlatform method 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 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 4789101 J3D.dll is accessing jniGetObjectClass inside the critical region 4790016 PickObject generatePickRay return wrong PickShape if View compatibility enable 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 ------------ 4690609 GeometryArray: cannot directly access data in BY_REFERENCE mode 4702800 HelloUniverseConfig throws IllegalArgumentException 4780878 ConfiguredUniverse needs a way to access multiple behaviors 4791847 NullPointerException in ConfiguredUniverse.getNamedSensors, getNamedBehaviors 4717595 SceneGraph IO bug in J3DFly 4718786 Incorrect coefficients in CubicSplineSegment computeCommonCoefficients() 4783638 WakeupOnAWTEvent does not support MouseWheelEvent Linux-specific Bugs ------------------- none