JMSL Chart Guide: Java 3D

JMSL Chart
Programmer's Guide

Java 3D

Java 3D

The JMSL Chart 3D package is built on top of Java 3D. For most purposes, using the Chart 3D package does not require knowledge of Java 3D.

A JMSL chart can be saved as an image file in two ways: either using the Java ImageIO class or the Java Advanced Imaging (JAI) API.

Using the Chart 3D with Swing

Swing components are lightweight, but the canvas used to render Java 3D is a heavyweight component. Generally, lightweight components cannot be drawn on top of heavyweight components

To allow Swing menu items to appear on top of the canvas, use

JPopupMenu.setDefaultLightWeightPopupEnabled(false);

To allow Swing Tooltips, use

JPopupMenu.setDefaultLightWeightPopupEnabled(false); ToolTipManager.sharedInstance().setLightWeightPopupEnabled(false);

Video Card Drivers

Java 3D is implemented on top of OpenGL. In Windows, there is also an option to use Direct3D. Both of these APIs use the video card hardware to accelerate performance. The interface between OpenGL/Direct3D and the video card hardware is the video card driver.

Problems with the video card drivers can cause problems with Java 3D and therefore with the Chart 3D package. If there is a problem, check with the hardware manufacturer for a driver update. It may also be possible to work around problems by setting certain system properties.

System Properties

Java system properties can be set on the command line using the syntax

-Dname=value

They can also be set using methods in the System class.

There are many system properties which can be set to control Java 3D. The following table lists some of the most important settings.

For more details, see http://java3d.j3d.org/implementation/properties.html.

Property

Values

Definition

j3d.rend ogl | d3d Windows-only. Specifies which underlying rendering API should be used (thus allowing both Direct3D and OpenGL native DLLs to be installed on a singe machine.
Default: ogl

j3d.deviceSampleTime An integer The sample time in milliseconds for non-blocking input devices.
Default: 5

j3d.threadLimit An integer Controls how many threads may run in parallel regardless of how many cpu's the system has. Setting it to "1" will make the system act like a traditional OpenGL render loop.
Default: number of CPUs plus one.

j3d.disableXinerama true | false Solaris only. Allows major performance boost when using dual screen environments with the X11 Xinerama extension enabled. To disable this feature you need JDK1.4. Detailed information in the release notes. Default: false.

j3d.displaylist true | false OpenGL only. Enable use of display lists, an OpenGL performance enhancing feature. False to disable for debugging.
Default: true

j3d.g2ddrawpixel true | false If true, use glDrawPixel to flush the graphics2D to the screen. If false, use texture mapping to flush the graphics2D to the screen. glDrawPixel is not accelerated on some older Windows video cards.
Default: true

j3d.sharedctx true | false Shared contexts are used in OpenGL for DisplayLists and Texture Objects to improve performance. However some drivers have bugs causing weird rendering artifacts. This can be used to disable their use to see if this is the problem.
Default: true for Solaris and false for Windows

j3d.debug true | false Prints out startup and running information. Useful for finding out information about the underlying hardware setup.
Default: false

j3d.vertexbuffer true | false Use of vertex buffers, a D3D performance enhancing feature equivalent to OpenGL display lists. Some drivers have implementation problems so it might be worth turning this off if there are crashes. Default: true

sun.java2d.d3d true | false Windows only. Disable use of Direct3D by Java.
Default: true

sun.java2d.ddoffscreen true | false Windows only. Disable use of DirectDraw and Direct3D by Java for off screen images, such as the Swing back buffer.
Default: true

sun.java2d.noddraw true | false Windows only. Completely disable use of DirectDraw and Direct3D by Java. This avoids any problems associated with use of these APIs and their respective drivers.
Default: false

Property	Values	Definition
j3d.rend	ogl \| d3d	Windows-only. Specifies which underlying rendering API should be used (thus allowing both Direct3D and OpenGL native DLLs to be installed on a singe machine. Default: ogl
j3d.deviceSampleTime	An integer	The sample time in milliseconds for non-blocking input devices. Default: 5
j3d.threadLimit	An integer	Controls how many threads may run in parallel regardless of how many cpu's the system has. Setting it to "1" will make the system act like a traditional OpenGL render loop. Default: number of CPUs plus one.
j3d.disableXinerama	true \| false	Solaris only. Allows major performance boost when using dual screen environments with the X11 Xinerama extension enabled. To disable this feature you need JDK1.4. Detailed information in the release notes. Default: false.
j3d.displaylist	true \| false	OpenGL only. Enable use of display lists, an OpenGL performance enhancing feature. False to disable for debugging. Default: true
j3d.g2ddrawpixel	true \| false	If true, use glDrawPixel to flush the graphics2D to the screen. If false, use texture mapping to flush the graphics2D to the screen. glDrawPixel is not accelerated on some older Windows video cards. Default: true
j3d.sharedctx	true \| false	Shared contexts are used in OpenGL for DisplayLists and Texture Objects to improve performance. However some drivers have bugs causing weird rendering artifacts. This can be used to disable their use to see if this is the problem. Default: true for Solaris and false for Windows
j3d.debug	true \| false	Prints out startup and running information. Useful for finding out information about the underlying hardware setup. Default: false
j3d.vertexbuffer	true \| false	Use of vertex buffers, a D3D performance enhancing feature equivalent to OpenGL display lists. Some drivers have implementation problems so it might be worth turning this off if there are crashes. Default: true
sun.java2d.d3d	true \| false	Windows only. Disable use of Direct3D by Java. Default: true
sun.java2d.ddoffscreen	true \| false	Windows only. Disable use of DirectDraw and Direct3D by Java for off screen images, such as the Swing back buffer. Default: true
sun.java2d.noddraw	true \| false	Windows only. Completely disable use of DirectDraw and Direct3D by Java. This avoids any problems associated with use of these APIs and their respective drivers. Default: false