 |
Home | Changes | Index | Search | Go
Welcome to the Java 3D Knowledge Base Wiki page for Application Developers. All Java 3D Community Members are welcome to contribute to this Wiki! Please read Java3DWikiInfo before making any changes to this page.
Table of Contents
Programming Tips
A behavior outline on byRef / byCopy scene graph update related to geometry and texture
J3D Scene Graph Update Study -- Tables on texture and geometry update.
Releasing Canvas3D?, View, and VirtualUniverse objects
Many applications use and dispose of multiple Canvas3D?, View, and VirtualUniverse objects.
See https://java3d.dev.java.net/issues/show_bug.cgi?id=134 for one issue that was filed on this.
Here is a recipe for cleaning this up so that Java 3D will not hold onto the memory or other (native)
resources.
If you want to dispose of a VIrtualUniverse and its associated Locale(s) / scene graphs, Canvas3D?(s), and View(s), you can do one of two things:
- Call SimpleUniverse.cleanup() if the VirtualUniverse is an instance of SimpleUniverse.
- Do the following set of operations (which is basically what SimpleUniverse.cleanup() does) in the order listed:
- Set the off-screen buffer to null for each off-screen Canvas3D? -- canvas3d.setOffScreenBuffer(null)
- Remove all Canvas3Ds? (both on-screen and off-screen) from the View -- view.removeAllCanvas3Ds()
- Attach a null ViewPlatform to the View -- view.attachViewPlatform(null);
- Remove all Locales from the VirtualUniverse -- universe.removeAllLocales()
Java 3D hangs with Swing - How to fix
On Windows systems, Swing trys to use DirectDraw to accelerate 2D operations. But some video drivers fails to have this Swing feature working properly with Java 3D, with application hanging or crashing. In order to get your Java 3D running you can disable Swing usage of DirectX, by using one or more of the following system properties:
- -Dsun.java2d.d3d=false
- -Dsun.java2d.ddoffscreen=false
- -Dsun.java2d.noddraw=true
Example of usage:
c:\java -Dsun.java2d.d3d=false MyApp3D
See http://java.sun.com/j2se/1.5.0/docs/guide/2d/flags.html#win for more information about 2D properties.
Also there are more tips and workarounds about Java 3D with Swing available at J3D?.org http://java3d.j3d.org/faq/index.html
Display Lists in Java 3D
This section describes the use of OpenGL display lists for both the
native ogl pipeline and the JOGL pipeline. In general, display lists
are used for GeometryArray objects whenever possible. If any of the
following conditions are true, display lists will not be used:
- Geometry is writable AND optimizeForSpace==true [a]
- Geometry has per-vertex colors AND alpha is editable [b]
- Cg shaders are used AND geometry has vertex attributes (varying shader params)
- Geometry is by-reference AND optimizeForSpace==true [c]
- NIO Buffers are used
- IndexedGeometryArray and geometry is by-reference
[a] - This is not the intended behavior. Writable geometry should be display listed if it is infrequently writable, regardless of the optimizeForSpace flag
[b] - Alpha is considered editable if the appearance is writable, the alternate appearance override is enabled, or any of the following appearance attributes are writable:
RenderingAttributes, TransparencyAttributes, or TextureAttributes.
[c] - Note that optimizeForSpace is currently true by default, we are considering changing the default to false in Java 3D 1.5.0.
Here is a table illustrating this for the different geometry formats:
| | By-copy | By-ref Java Arrays | By-ref NIO Buffer |
|---|
| Non-indexed GeometryArray | YES | YES | NO |
|---|
| IndexedGeometryArray? | YES | NO | NO |
|---|
Java 3D System Properties
Here are the Java system properties recognized by Java 3D. These can be specified on the "java" command line with the "-D" option. For example:
java -Dj3d.rend=d3d MyApp
Standard Properties
The following properties are not officially supported, but are very unlikely to change:
| Property | Type | Default | Description |
|---|
| j3d.rend | String | ogl | Renderer to use: ogl (native OpenGL), jogl, or d3d (Direct3D) |
| j3d.shadingLanguage | String | GLSL | Shading language to use: GLSL or Cg |
Experimental Properties
The following properties are unsupported, and are subject to change or removal:
| Property | Type | Default | Description |
|---|
| j3d.adjustClockSkew | boolean | false | If set to true, adjust internal timer for clock skew between nanoTime and currentTimeMillis |
| j3d.allowSoleUser | boolean | false | If set to true, allow the sole-user optimization; otherwise, sole-user is disabled |
| j3d.backgroundtexture | boolean | true | If set to true, use texture mapping for background image; otherwise, use glDrawPixels |
| j3d.cacheAutoComputeBounds | boolean | false | If set to true, cache AutoCompute Bounds to accelerate getBounds method |
| j3d.compiledVertexArray | boolean | true | If set to true, enable compiled vertex arrays |
| j3d.debug | boolean | false | If set to true, enable debugging |
| j3d.deviceSampleTime | integer | 5 | Sampling period (msec) for non-blocking input devices |
| j3d.disablecompile | String | <null> | If defined, BranchGroup.compile is disabled |
| j3d.disableSeparateSpecular | String | <null> | If defined, separate specular color is disabled |
| j3d.disableXinerama | String | <null> | If defined, Xinerama is disabled on Solaris |
| j3d.displaylist | boolean | true | If set to true, display lists are used in many cases; otherwise, display lists are disabled |
| j3d.docompaction | boolean | true | If set to true, enable RenderBin compaction |
| j3d.forceNormalized | boolean | false | If set to true, force glNormalize |
| j3d.forceReleaseView | boolean | false | If set to true, force a ReleaseView operation after Canvas3D dispose |
| j3d.g2ddrawpixel | boolean | false | If set to true, use glDrawPixels for Graphics2D; otherwise, use texture mapping |
| j3d.implicitAntialiasing | boolean | false | If set to true, enable implicit antialiasing |
| j3d.optimizeForSpace | boolean | true | If set to true, optimize by-ref geometry for space; otherwise, optimize for rendering speed |
| j3d.releaseBoundingBoxMemory | boolean | false | If set to true, release temporary resources each time a BoundingBox is transformed |
| j3d.renderLock | boolean | false | If set to true, do all rendering while holding the AWT lock |
| j3d.sharedctx | boolean | false | If set to true, use GL shared contexts for textures and display lists |
| j3d.sharedstereozbuffer | boolean | true | If set to true, assume a shared Z buffer for both eyes in stereo mode |
| j3d.simulatedMultiTexture | boolean | false | If set to true, allow simulated multi-texture when number of texture units exceeded |
| j3d.sortShape3DBounds | boolean | false | If set to true, enable user-specified Shape3D bounds for transparency sorting |
| j3d.textureEnforcePowerOfTwo | boolean | false | If set to true, enforce power-of-two size restriction on textures even if the driver supports NPOT texture |
| j3d.threadLimit | integer | numProcessors+1 | Number of active, concurrect threads scheduled by MasterControl |
| j3d.transparentOffScreen | boolean | false | If set to true, enable transparent OffScreen |
| j3d.useBoxForGroupBounds | boolean | false | If set to true, use BoundingBox (instead of sphere) for group bounds |
| j3d.usecombiners | boolean | false | If set to true, enable NV_register_combiners (if available) |
| j3d.usePbuffer | boolean | true | If set to true, use PBuffer for Off-screen Canvas3Ds |
| j3d.viewFrustumCulling | boolean | true | If set to true, enable view frustum culling in the renderer |
The following properties are exclusive to Direct 3D pipeline. They are also unsupported, and are subject to change or removal:
| Property | Type | Default | Description |
|---|
| j3d.d3ddevice | String | "TnLhardware" | Choose D3D? Device. Possible values are "reference" , "hardware" and "TnLhardware". Device "reference" is a software renderer and requires MS DirectX SDK installed |
| j3d.d3ddriver | integer | 1 | For multiscreen enviroments only. Value is the id of target screen, and values can be 1 , 2, 3, etc. Default is 1 (default screen). |
| j3d.d3dFPUPreserv | boolean | true | Uses D3DCREATE_FPU_PRESERV when creating d3d devices. The default true value follows Swing D3D? pipeline policy . If set to false D3D? will set FPU to use float precision instead double precision, and mask fpu exceptions. It´s safer to leave it as default value. |
| j3d.d3dVertexProcess | String | "hardware" | Force device vertex processing mode. Possible values are "hardware", "mixed" and "software". Default mode is a smart fallback choose. |
| j3d.fullscreen | String | "unnecessary" | Full Screen mode. Possible values are "required" and "preferred", Default is "unnecessary" |
| j3d.useNvPerfHUD | boolean | false | Used for profilling and debugging on D3D? pipeline. This option also overrides vertex processing mode to "hardware". Requires NVidia video card and NVidia's NvPerfKit , a set of several tools including a Instrumented Driver and NvPerfHUD profiler. Check NvPerfKit docs about details. A bat file to start-up your Java3D application is highly recommended. |
| j3d.vertexbufferlimit | integer | 65536 | Max vertex count used on vertex buffer. If geometry vertex count is greater than vertexbufferlimit, then geometry is splitted in smaller geometries. Values must be => 6, default is 65,535 (2^16 -1). Due video driver bugs, some old systems fails to use vertexbufferlimit greater than default value. |
Logging in Java 3D
We added a logging framework to Java 3D 1.5.1 that can be used to get more information or hints about Java 3D execution.
Setting up a IDE for Java3D Development
The basic steps for setting up an IDE for Java3D development are :
- Download all required Java3D files from https://java3d.dev.java.net/binary-builds.html ;
- Install Java3D in your JDK;
- In your IDE create a library for Java3D, including j3dcore.jar, j3dutils.jar and vecmath.jar;
If you are going to test your application outside your IDE, you must install Java3D in your default JRE.
Go to https://java3d.dev.java.net/binary-builds.html and download :
- Java3D installer zip file : java3d-1_5_x-PLATFORM.zip ; (replace platform by your OS)
- (Optional) download Java3D source code zip file : java3d-1_5_x-src.zip and vecmath-1_5_x-src.zip
- (Optional) download API javadocs java3d-1_5_x-api-docs.zip
- (Optional) download Java3D examples j3d-examples-1_5_1-src.zip .
Run Java3D installer, unzipping it in your JDK/JRE folder. This must be the same JDK used by your NetBeans.
After unzip, make sure you have the following files at /JDK/JRE/lib folder : j3dcore.jar, j3dutils.jar and vecmath.jar .
Also, check if your /JDK/JRE/bin folder has the following DLLs : j3dcore-ogl.dll, j3dcore-d3d.dll, j3dcore-ogl-chk.dll and j3dcore-ogl-cg.dll .
On Linux 32, the binaries are placed at /JDK/JRE/lib/i386 folder, and they have different names : libj3dcore-ogl.so and libj3dcore-ogl-cg.so .
To easy library management, create a folder, as C:\Java3DLibs, and put there all downloaded files.
Unzip the Java3D installer in this folder, to have the jar files available for NetBeans' Library Manager, to be configured as described below..
Run your NetBeans, go to menu Tools and choose Libraries.
In the opened Library Manager window, click "New Library ..." button, in the left botton.
Give a name for this library, as Java3D, let the combo box as "Class Libraries" and press "OK" button;
Back on Library Manager, you should have your new Java3D library selected on right hand panel, and at left side "Classpath" tab.
On "Classpath" tab, click on "Add JAR/Folder..." button.
Navigate to C:\Java3DLibs folder, and ctrl select j3dcore.jar, j3dutils.jar and vecmath.jar.
Optionally, back to Library Manager window and select "Sources" tab, press "Add JAR/Folder...", navigate to C:\Java3DLibs and select the java3d-1_5_x-src.zip and vecmath-1_5_x-src.zip .
Optionally , you can do the same for "Javadoc" folder, selecting the Java3D-1_5_x-api-docs.zip
Press "OK" on Library Manager. You have finished the Java3D library creation.
Now when you create a project using Java3D, mouse right click on project name, go to Properties, choose Libraries, press "Add Library" button and select Java3D library.
Eclipse IDE
Eclipse only requires a JRE to run. If you are using JDK , below steps are about JDK/jre folder.
Download and Install
Go to https://java3d.dev.java.net/binary-builds.html and download :
- Java3D installer zip file : java3d-1_5_x-PLATFORM.zip ; (replace platform by your OS)
- (Optional) download Java3D source code zip file : java3d-1_5_x-src.zip and vecmath-1_5_x-src.zip
- (Optional) download API javadocs java3d-1_5_x-api-docs.zip
- (Optional) download Java3D examples j3d-examples-1_5_1-src.zip .
Run Java3D installer, unzipping it in your JRE folder. This must be the same JRE used by your project.
Check it in your project, at Project / Property / Java Build Path / Libraries tab / JRE System Library .
After unzip the installer, make sure you have the following files at your JRE/lib folder : j3dcore.jar, j3dutils.jar and vecmath.jar .
Also, check if your JRE/bin folder has the following DLLs : j3dcore-ogl.dll, j3dcore-d3d.dll, j3dcore-ogl-chk.dll and j3dcore-ogl-cg.dll .
On Linux 32, the binaries are placed at /JDK/JRE/lib/i386 folder, and they have different names : libj3dcore-ogl.so and libj3dcore-ogl-cg.so .
To easy library management, create a folder, as C:\Java3DLibs, and put there all downloaded files.
Unzip the Java3D installer in this folder, to have the jar files available for Eclipse Libraries, to be configured as described below.
Create Java3D Library :
Run your Eclipse, go to menu Project , Properties, Java Build Path, Libraries tab .
Press "Add Library..." button
Choose "User Library" and press Next, the "User Libraries" button again...
In the User Libraries frame, press "New..."
Name it as Java3D
Press "add JARS...", navigate to C:\Java3DLibs folder, and add the following files : j3dcore.jar, j3dutils.jar and vecmath.jar .
Optional : after above step, click on Source node and press "Edit..." . Point it to your downloaded zipped source code.
Do the same for the Javadoc node.
Press "OK" on User Libraries window. You justfinished the Java3D library creation.
New Eclipse projects using Java3D
Now when you create a project using Java3D, mouse right click on project name, go to Properties, Java Build Path, choose Libraries tab, press "Add Library", then choose "User Libraries" and select Java3D library.
Profilling OpenGL? and DirectX? D3D? HW resources on Java3D applications
It´s possible to profile the hardware resources used by OpenGL? or Direct3D? on Java3D applications running on Windows platform with NVidia video cards.
Go to http://developer.nvidia.com/object/nvperfkit_home.html and download NVidia's NVPerfKit?.
NVPerf Kit is composed by several tools for profilling 3D applications:
- NVPerfHUD?
- PerfSDK?
- GLExpert
- gDEBugger
- PIX for Windows plugin
NVidia has detailed infprmation about software and hardware requirements
Java3D's D3D? pipeline supports low level profilling , when enabled by JVM options -Dj3d.rend=d3d -Dj3d.useNvPerfHUD=true
The Java3D OpenGL? pipeline can be profiled using GLExpert and gDEBbuger.
IMPORTANT
Use a batch file to launch your Java3D application. Just create a plain text file named run.bat with following statement:
REM Profile D3D? pipeline
java -Dj3d.rend=d3d -Dj3d.useNvPerfHUD=true My3DApplication?
or
REM Profile OpenGL? pipeline
java -Dj3d.rend=ogl My3DApplication?
Replace "My3DApplication" by the name of your main class.
FINISH THIS TOPIC
More Topics
This is a placeholder for other topics
|