Java 3D(TM) 1.2 README file for Linux/OpenGL =========================== IMPORTANT INSTALLATION NOTE =========================== 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 Linux requires the following: Java 2 SDK version 1.2.2-FCS or later from Blackdown Java-Linux (http://www.blackdown.org) if you want to use the J3D1.2 SDK or Java 2 Runtime environment version 1.2.2-FCS or later from Blackdown Java-Linux (http://www.blackdown.org) if you want to use the J3D1.2 Runtime Environment. It is recommended that you use a native threads VM (classic VM with native threads or the HotSpot(TM) VM). This release has been certified for use with the Blackdown Java-Linux Java2 SDK version 1.2.2-FCS (native threads and the sunwjit compiler), Java 2 SDK version 1.3.0 (with HotSpot(TM)) from Sun/Blackdown works but has not been certified at this point. Mesa 3.2 (http://www.mesa3d.org) or another OpenGL(TM) implementation. For drivers with hardware acceleration see http://www.mesa3d.org/#Systems ============ INSTALLATION ============ Java3D 1.2 SDK: --------------- Change your working directory to the the top level directory of the JDK you wish to install Java 3D(TM) into. Then extract java3d1_2-FCS-linux--sdk.tar.bz2 with 'tar xvfI'. E.g.: cd /usr/local/jdk1.2.2 tar xvfI ~/java3d1_2-FCS-linux-i386-sdk.tar.bz2 After installation, you may remove the tar ball. The Java 3D(TM) SDK includes several demo programs that can verify correct installation. Assuming your Java 2 SDK is installed at /usr/local/jdk1.2.2, try the following: cd /usr/local/jdk1.2.2/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 128 meg, add the following command line options to java or appletviewer: java: -mx128m appletviewer: -J-mx128m Java3D 1.2 Runtime Environment: ------------------------------- Change your working directory to the the top level directory of the JRE you wish to install Java 3D(TM) into. Then extract java3d1_2-FCS-linux--re.tar.bz2 with 'tar xvfI'. E.g.: cd /usr/local/jre1.2.2 tar xvfI ~/java3d1_2-FCS-linux-i386-re.tar.bz2 After installation, you may remove the tar ball. You do not need to include the J3D jar files in your CLASSPATH, nor do you need to include the J3D shared libraries in your PATH. You should include "." in your CLASSPATH or ensure that CLASSPATH is not set. Java 3D(TM) 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. 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. ================================ RUNNING JAVA 3D(TM) IN A BROWSER ================================ You can run Java 3D(TM) programs in Netscape Communicator. After installing Netscape Communicator you then install the Java(TM) Plug-IN (JPI) to add Java 2(TM). Then follow the instructions here to install Java 3D(TM). Netscape Communicator may be downloaded for free from http://www.netscape.com. Netscape version 4.51 or higher is required. The JPI is available from http://www.blackdown.org/java-linux/jdk1.2-status/plugin-status.html JPI 1.2.2 or higher is required. By default, the JPI is installed in $(HOME)/.netscape/java. If another directory is used, it must be specified with the NPX_PLUGIN_PATH environment variable. The JPI comes with its own JVM, but we need it to use the JVM you've upgraded with Java 3D(TM). Run the Java Plug-In Control Panel by pointing Netscape at the ControlPanel applet page or by starting the ControlPanel script in the JPI's main directory. Click on the 'Advanced' tab and under "Java Run Time Environment" choose "Other..." Enter the path to your JVM in the 'Path:' box (for example, /usr/local/jdk1.2.2/jre). Press "Apply." There is a bug in the Linux and Solaris versions of the JPI 1.2.2 that keeps it from finding Java extensions in the lib/ext/ directory where they are kept. To work around the problem, you need to copy the four .jar files from the lib/ext/ directory to the lib/ directory as follows: cd $SDKHOME/jre/lib/ext cp j3daudio.jar .. cp j3dcore.jar .. cp j3dutils.jar .. cp vecmath.jar .. Java Plug-In will be built into Linux Netscape 6.0, so this separate installation process will no longer be necessary. Special HTML code is required to get Netscape to use the JPI VM. Refer to the following URL for information on using Java Plug-In 1.2.2 HTML Converter and running applets using Java Plug-in: http://java.sun.com/products/plugin/ All example programs that can be run as applets now have an html file with "_plugin" in their name that has been converted to use Java Plug-In. Use any of these programs to test your installation of Java 3D in your browser. NOTE: Many Java 3D(TM) programs will require a larger heap size than the default in the JPI. Run the Java Plug-In Control Panel by pointing Netscape at the ControlPanel applet page or by starting the ControlPanel script in the JPI's main directory. In Java Run Time Parameters put "mx100m" for 100M of heap memory. ==================================================== 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) Evaluation License 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 (Linux): /lib//libJ3D.so /lib//libj3daudio.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 Beta 2 ======================== ========== BUGS FIXED ========== 4152507 Non-Congruent matrix above view platform will kill the traverser thread 4189141 Geometry-based picking is not supported for CompressGeometry. 4189608 for certain cases, PointSound clone[Node,Tree] method not working 4248505 ViewPlatforms do not work correctly under Switch nodes 4259292 ImageComponent2D with no image set causes segmentation fault 4259332 Multiple views of a Switch node incorrect 4259343 bug in loader routine private void setBaseUrlFromUrl 4267310 Extrusion contours for Font3D don't produce smooth normals 4280130 Shape with lighting enabled and no normals should throw exception 4303050 GeometryArray: set Color/Texture should throw exception if wrong dimension 4305949 Scene antialiasing produces significant rendering artifacts 4309039 setting texture object on >= 2 objects repeatedly generates OutOfMemoryError 4309811 Memory leak when textures are removed 4315063 TickTockPicking fail to pick and highlight shape color 4310690 PickIntersection.getPointCoordinates() return wrong result 4310717 PickResult.toString() stack overflow 4311548 Memory Leaks with AlternateAppearance 4312393 SimpleTextureApp gets nullpointer exception, from TextureLoader in utils 4313347 Synchronizing interpolator and view transformgroup 4313908 Memory leak when adding/removing scene graphs 4314108 Picking utility can't handle shape with multiple geometries properly 4315015 Text3DLoad throw NullPointerException 4315031 MixedImmediate hangs under windows98 4315307 NullPointerException throws at getApplicationBackground 4315326 One spotlight is missing in tutorial SpotLightApp 4315329 tutorial BoundaryColorApp shows different images on windows/Solaris (AFB/FFB) 4315335 TextureLoader throws NullPointerException when observer is null 4316842 Ends of cylinders contain 2x as many triangles as needed 4317059 Background application bounds did not transform as expected 4317467 NullPointerException at TransformGroupRetained.setTransform() 4318997 Vecmath Serialization is NOT compatible with Java3D 1.1.x 4319878 ClippedOffScreenCanvas3DTest fail to print cube in certain clipping cases 4322069 ClassCast & pointer Exception in Morph during detach and setGeometryArray 4322165 ambiguous default values for ConeSound angular attenuation 4322661 TextureByReference demo no longer animates 4322725 Changes to AlternateAppearance ignored when no Shape3D is enabled 4322817 java.lang.IllegalStateException: GeometryArray: must be in COLOR_3 mode 4323280 RotPosScaleTCBSplinePathInterpolator fail to clone KeyFrames and Alpha 4324801 MultiTextureTest throws NullPointerException when texture change 4325005 Environment mapping (i.e. TexCoordGeneration.SPHERE_MAP) not work 4325643 Switching from multi to single texture sometimes does not work 4325789 AppearanceTest throws NullPointerException under windows 4325847 Background Image did not remove when branch detach 4326650 BackgroundGeometry got cull away sometimes when using VertexArrayRenderMethod 4327020 NullPointerException when texture unit state is disable 4327715 Bad flickering in PureImmediate Mode 4327776 SharedAlternateTargetTest throws NullPointerException in Behavior callback 4328222 PickAny(Locale ) did not check for isPickable flag 4328331 J3DGraphics2D drawing buffer is not cleared 4328765 MasterControl sometimes throws NullPointerException when SimpleGeometry startup 4328844 performance regression on input events processing 4329542 Nested Shared group throws ArrayIndexOutOfBoundsException 4329546 Exception in texture when image of a different size is setImage() after setLive 4329571 lights removed from a scene still light the scene 4329636 IndexOutOfBoundsException throw when share object pick 4329682 ModelClipImm did not work 4329812 WakeupOnTransformChange and AWT Event processing order not in correct 4329873 JVM Segmentation fault if depth Component not set in Raster 4329942 Texture setImage(s) unclear on how to set a new image of a different size 4330199 Link.setSharedGroup() throws array index exception 4330210 Debug statement printed when using ordered group 4331122 hardware decompression is disabled on Solaris 4331694 can't pick LineStripArray or IndexedLineStripArray 4332218 OrderedGroup.setChild throws IndexOutOfBoundsException 4333197 quitting PureImmediate demo causes IndexOutOfBoundsExc on Win and SIGSEGV on Solaris 4333543 ConicWorld/TexturedCone would not load as an applet ============ NEW FEATURES ============ All example program now have example.html and example_plugin.html for use with the plugin feature available with most web browsers. In addition, an html page, demo/java3d/index.html now contains links to all demo programs that can be run as applets. ======================= 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 - Preliminary triangle stripifier - Geometry compression utilities - Spline-based path interpolators - Preliminary Wavefront .obj loader - Preliminary 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 ============== KNOWN PROBLEMS ============== Documentation Bugs ------------------ 4181456 make Sensor.setSensorReadCount MT-safe 4199091 Raster object uses the alpha value inside the image to perform blend operation 4284971 Specify that wakeup criteria should not be shared 4284973 Billboard and OrientedShape3D must specify that +Z axis is illegal 4284976 Specify that getProjection is illegal in non-compatibility mode 4284977 Clarify effect of capability bits in retained mode 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 4303058 Docs should indicate when boundary color is used 4303060 Docs should be more clear on interaction of old/new texture state 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 4307552 Spec. need to be clearer on the issue of sync. between sg. update and picking. 4259353 documentation for com.sun.j3d.utils.geometry.Box is confusing Core Bugs (j3d and vecmath) --------------------------- 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 4181456 make Sensor.setSensorReadCount MT-safe 4182781 Shape3D memory not freed when unassigned if associated appearance object isalive 4182859 Back clip distance in Clip node not scaled correctly 4186182 sceneAntialiasing setting of PREFERRED is ignored 4186219 Geometry Collision does not implement points/surface, line/line, or line/point 4187092 Filtering causes loud, sweeping resonance to be added to most sounds 4187093 Cross-talk cancellation for sound playback in not implemented 4189092 HEAD_PREDICTOR ansd HAND_PREDICTOR policies not implemented 4190692 Multiple sample channels are not always synchronized when started 4191172 Text3D rendering problems 4193466 GMatrix SVD does not work correctly for some cases. 4212805 ReadRaster test program has race condition 4246325 AWT Event once enable, will not disable when behavior remove 4250253 GeometryInfo leaks memory in some cases (with Appearance?) 4259345 Text3D does not correct convert geometry of Japanese-text 4259533 getTexture() throws NullPointerException when using proxies 4260818 java3d should support stereo graphics automatically 4269784 vecmath.GMatrix.LUD inefficient 4269923 LOD's slow 4269929 lighting bounds problem 4271363 CloneTree display garbled in AccelGalaxy card RealImage 2100 4299480 readRaster() and waitForOffScreenRendering() will not work if threadLimit=1 4308591 Text3D objects bounding box not accurate enough 4308592 texture loader does not scale non-power-of-2 RGBA textures properly 4308599 transparent BufferedImages not working 4308601 using KeyEvents and Swing requires clicking on the window with the mouse 4308605 cloned object's setAppearance method produces no effect 4309037 setWorldURL in the Loader.java is setup wrong (fix included) 4309059 background geometry appears very close to the camera vs 1.1.3 4310109 share context not use when createContext() in GraphicsContext3D 4310958 wrong bounds may be used in region of influence operations 4312044 java Viewer reflects only Lightwave objects with depth 4313678 Java3D disables invalid lights 4315018 Garbage sound in TestFilter 4315058 VolRend display white cube when Axis Volume is 3D 4316844 Documentation of Java 3D colors should specify gamma assumptions 4319780 RFE: java3d scene graph objects are not serializable 4325851 Hardware MultiTexture not support even though numActiveTexture <= supported num 4326571 Need URL method for Lightwave objects in applets 4327643 RFE: LW3Dloader needs to be able to load 'other' image file formats 4328532 Textures for the bottom of cones and cylinders are upside-down 4331434 adding object to itself does not generate an exception 4331646 rendering differences between WIN32 and Solaris platforms 4331669 setRectangleScaleFactor will not change text size unless setString called 4331677 setWindowResizePolicy(View.VIRTUAL_WORLD) doesn't work1< 4332793 View transform & object transform not synchronized in a single behavior 4334767 examples/MoveAppBoundingLeaf sometimes produces no sound 4335205 WakeupOnCollision fail if arming Node is TransformGroup which undergo transform 4335245 Raster type RASTER_COLOR_DEPTH did not work as expect Utility Bugs ------------ 4217567 NormalsGenerator only checks the cosine for smoothing 4250253 GeometryInfo leaks memory in some cases (with Appearance?) 4252349 First viewport may jump when using KeyNavigatorBehavior