FXCanvas3D
API Specification 2.0

FXCanvas3D enables JavaFX™ to draw the Virtual Universe.

See:
Description

Packages

com.interactivemesh.j3d.community.gui

GUI components which Java 3D renders into.

FXCanvas3D enables JavaFX™ to draw the Virtual Universe.

This API is a derived work of the Java 3D™ utility class JCanvas3D and includes the Java™ class FXCanvas3D and the Java interface FXCanvas3DRepainter.

The following two objectives determine the current approach of the FXCanvas3D API:

• Java 3D renders off-screen into a lightweight component which is added via a resizable JavaFX SwingComponent to a JavaFX Scene.
• The Java 3D rendering loop runs in parallel to the JavaFX painting loop with synchronized minimal overlapping.

A Double Off-screen Buffer and a controlling Lock with two Conditions were introduced to ensure that the threads of both loops access the common image data deadlock-free. These two buffers consist of a BufferedImage which Java 3D is rendering into and a BufferedImage which JavaFX is drawing. Both images have an identical format type. Only for the period of time it takes to copy integer values from the first into the second image the loops interrupt their regular tasks controlled by one of the two Lock's Condition. The other Condition guarantees that during resizing of a FXCanvas3D panel the Java 3D renderer thread isn't blocked.

The following sample 'FXCanvas3DComp' of the corresponding JavaFX SwingComponent has the interface FXCanvas3DRepainter implemented. This allows a FXCanvas3D object to call 'repaintFXCanvas3D()' from its 'postSwap()' method. The repaint request is handled by a FX.deferAction() - an equivalent to SwingUtilities.invokeLater() - and will be executed on the EDT. The assigned function calls firstly 'copyOffScreenBuffer()' while the Java 3D renderer thread is waiting and secondly 'repaint()' on the FXCanvas3D object. This completes the cycle of 3D off-screen rendering and image drawing.

JavaFX class FXCanvas3DComp.fx

import java.awt.BorderLayout;
import javax.swing.JPanel;
import javafx.ext.swing.SwingComponent;
import com.interactivemesh.j3d.community.gui.FXCanvas3D;
import com.interactivemesh.j3d.community.gui.FXCanvas3DRepainter;

package class FXCanvas3DComp extends SwingComponent, FXCanvas3DRepainter {

    // Container for FXCanvas3D's parent
    var container: JPanel;

    // FXCanvas3D instance
    var fxCanvas3D: FXCanvas3D;

     // Create SwingComponent - called at construction time
    override protected function createJComponent(): JPanel{    
        container = new JPanel(new BorderLayout());
    }

    // Typically called from Main.fx
    package function initFXCanvas3D(canvas: FXCanvas3D) {
        fxCanvas3D = canvas;

        fxCanvas3D.setRepainter(this);

        container.add(fxCanvas3D.getParent(), BorderLayout.CENTER);
    }

    // Interface FXCanvas3DRepainter
    
    // Called from FXCanvas3D
    override function repaintFXCanvas3D() {
    
        FX.deferAction(
            function(): Void {

                // Now we are in the JavaFX painting loop and on the EDT

                // Copy off-screen buffer and notify J3D-Renderer thread
                fxCanvas3D.copyOffScreenBuffer();

                // Repaint FXCanvas3D
                fxCanvas3D.repaint();
            }
        );
    }
}

Version 2.0 speeds up the lightweight 3D rendering of FXCanvas3D.

The java.awt.Graphics class provides a 'drawImage()' method which flips the image vertically on the fly while drawing. This allows to choose off-screen buffers in 'yUp' mode. In consequence the memory for an image is saved as well as the time to copy it within the ImageComponent2D object which Java 3D is directly rendering into.

This results in a faster running Java 3D rendering loop.

Version: 2.0
Date: 2009/03/09

Author:
August Lammersdorf, InteractiveMesh e.K.
Kolomanstrasse 2a, 85737 Ismaning
Germany / Munich Area
www.InteractiveMesh.com/org

License:

Redistribution and use are permitted according to the following license notice.

com.sun.j3d.exp.swing.JCanvas3D.java

Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistribution of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided "AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You acknowledge that this software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility.

Revision: 1.10
Date: 2007/04/11 02:08:56
State: Exp

Trademarks:

Java, Java 3D, and JavaFX are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.