JCanvas3D (Java 3D Javadocs 0-SNAPSHOT API)

java.lang.Object
- java.awt.Component
- - java.awt.Container
  - - javax.swing.JComponent
    - - javax.swing.JPanel
      - org.scijava.java3d.exp.swing.JCanvas3D

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, EventListener, Accessible, AncestorListener
```
public class JCanvas3D
extends JPanel
implements AncestorListener
```
This class provides a lightweight capability to Java 3D. The component handles bidirectional messaging between swing and Java 3D so that repaint ordonned by swing are sent to the universe if necessary and refreshes from the universe are painted accordingly. In order to get responsive interfaces during layout changes, the canvas has a feature (disabled by default) that lets true resizes occur only after a timer expires. Images between real resizes can eventually be slightly wrong and pixelated, but their display will be stutterless.
Lightweight canvas also handles redirection to heavyweight canvas for the following events:
- InputMethodEvent
- KeyEvent
- FocusEvent
- ComponentKeyEvent
- MouseWheelEvent
- MouseEvent
- MouseMotionEvent

When Swing is waiting for a canvas to be retrieved and that canvas is in rendering stage,a loop takes place, which includes small calls to wait(). The canvas status is tested for readiness before and after the wait(). If the canvas is not ready to be retrieved after the wait(), counter is decremented and control is given back to awt thread, which will repaint old buffer. If the loop goes over a certain amount of iterations, the canvas is declared 'crashed' and won't be updated anymore. This was done so that a crashed canvas/universe does not remove control over your GUI and does not leave you with a frozen application. In current implementation, the delay before a canvas is declared crashed is of :
30 Math.max(20.0, getView().getMinimumFrameCycleTime() )

Since:

Java 3D 1.5

Author:

Frederic 'pepe' Barachant

See Also:

getLightweightComponent(), setResizeValidationDelay(), setResizeMode(), Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class javax.swing.JPanel
  JPanel.AccessibleJPanel
- Nested classes/interfaces inherited from class javax.swing.JComponent
  JComponent.AccessibleJComponent
- Nested classes/interfaces inherited from class java.awt.Container
  Container.AccessibleAWTContainer
- Nested classes/interfaces inherited from class java.awt.Component
  Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`RESIZE_DELAYED` Resizing the canvas or component will be done if no resizing occurs after expiration of a certain delay.
`static int`	`RESIZE_IMMEDIATELY` Resizing the canvas or component will be done immediately.

Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors
Constructor and Description
`JCanvas3D()` Constructs and initializes a new JCanvas3D object that Java 3D can render into.
`JCanvas3D(GraphicsConfigTemplate3D template)` Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified template.
`JCanvas3D(GraphicsConfigTemplate3D template, GraphicsDevice device)` Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified template and graphics device.
`JCanvas3D(GraphicsDevice device)` Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified graphics device.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`ancestorAdded(AncestorEvent event)`
`void`	`ancestorMoved(AncestorEvent event)`
`void`	`ancestorRemoved(AncestorEvent event)`
`Canvas3D`	`getOffscreenCanvas3D()` Returns the offscreen heavyweight canvas of that lightweight component.
`int`	`getResizeMode()` Retrieves the resize mode for that component.
`int`	`getResizeValidationDelay()` Retrieves the validation delay for that canvas, whatever the resize mode is set to.
`void`	`paintComponent(Graphics g)` Paints the result of the rendering.
`protected void`	`processComponentKeyEvent(KeyEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processFocusEvent(FocusEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processInputMethodEvent(InputMethodEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processKeyEvent(KeyEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processMouseEvent(MouseEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processMouseMotionEvent(MouseEvent e)` Redirects event to canvas and to superclass.
`protected void`	`processMouseWheelEvent(MouseWheelEvent e)` Redirects event to canvas and to superclass.
`void`	`setBounds(int x, int y, int width, int height)`
`void`	`setResizeMode(int resizeMode)` Sets resize mode to be used on this component.
`void`	`setResizeValidationDelay(int resizeValidationDelay)` Sets the validation delay for the component.

Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processKeyBinding, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - RESIZE_IMMEDIATELY
```
public static final int RESIZE_IMMEDIATELY
```
    Resizing the canvas or component will be done immediately. This operation might take some time and make the application look sluggish.
    
    See Also:
    
    setResizeMode(), Constant Field Values
  - RESIZE_DELAYED
```
public static final int RESIZE_DELAYED
```
    Resizing the canvas or component will be done if no resizing occurs after expiration of a certain delay. Rendering will be eventually stretched or deformed. It can be useful on certain applications where smooth update of UI during layout is needed or desired.
    
    See Also:
    
    setResizeMode(), Constant Field Values
- Constructor Detail
  - JCanvas3D
```
public JCanvas3D()
```
    Constructs and initializes a new JCanvas3D object that Java 3D can render into. The screen device is obtained from GraphicsEnvironment.getLocalGraphicsEnvironment().getDefaultScreenDevice(), which might not be the one you should use if you are in a multiscreen environment. The JCanvas3D is constructed using the following default parameters:
    resize mode : RESIZE_IMMEDIATELY
    validation delay : 100ms
    double buffer enable : false
    stereo enable : false
  - JCanvas3D
```
public JCanvas3D(GraphicsDevice device)
```
    Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified graphics device.
    
    Parameters:
    
    device - the screen graphics device that will be used to construct a GraphicsConfiguration.
  - JCanvas3D
```
public JCanvas3D(GraphicsConfigTemplate3D template)
```
    Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified template. The screen device is obtained from GraphicsEnvironment.getLocalGraphicsEnvironment().getDefaultScreenDevice(), which might not be the one you should use if you are in a multiscreen environment.
    
    Parameters:
    
    template - The template that will be used to construct a GraphicsConfiguration. The stereo and doublebuffer properties are forced to UNNECESSARY.
  - JCanvas3D
```
public JCanvas3D(GraphicsConfigTemplate3D template,
                 GraphicsDevice device)
```
    Constructs and initializes a new Canvas3D object that Java 3D can render into, using the specified template and graphics device.
    
    Parameters:
    
    template - The template that will be used to construct a GraphicsConfiguration. The stereo and doublebuffer properties are forced to UNNECESSARY.
    
    device - the screen graphics device that will be used to construct a GraphicsConfiguration in conjunction with the template.
- Method Detail
  - ancestorAdded
```
public void ancestorAdded(AncestorEvent event)
```
    Specified by:
    
    ancestorAdded in interface AncestorListener
    
    Parameters:
    
    event -
  - ancestorMoved
```
public void ancestorMoved(AncestorEvent event)
```
    Specified by:
    
    ancestorMoved in interface AncestorListener
    
    Parameters:
    
    event -
  - ancestorRemoved
```
public void ancestorRemoved(AncestorEvent event)
```
    Specified by:
    
    ancestorRemoved in interface AncestorListener
    
    Parameters:
    
    event -
  - getOffscreenCanvas3D
```
public Canvas3D getOffscreenCanvas3D()
```
    Returns the offscreen heavyweight canvas of that lightweight component.
    
    Returns:
    
    the heavyweight canvas that lies in the deepness of this Component.
  - getResizeMode
```
public int getResizeMode()
```
    Retrieves the resize mode for that component.
    
    Returns:
    
    the resize mode, which can be one of RESIZE_IMMEDIATELY or RESIZE_DELAYED
  - getResizeValidationDelay
```
public int getResizeValidationDelay()
```
    Retrieves the validation delay for that canvas, whatever the resize mode is set to.
    
    Returns:
    
    the validation delay.
  - paintComponent
```
public void paintComponent(Graphics g)
```
    Paints the result of the rendering. If the rendered buffer is not useable (render thread being between [code]postRender()[/code] and [code]postSwap()[/code]), it will wait for it to be ready. Otherwise it will directly paint the previous buffer.
    
    Overrides:
    
    paintComponent in class JComponent
    
    Parameters:
    
    g -
  - processComponentKeyEvent
```
protected void processComponentKeyEvent(KeyEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processComponentKeyEvent in class JComponent
    
    Parameters:
    
    e -
  - processFocusEvent
```
protected void processFocusEvent(FocusEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processFocusEvent in class Component
    
    Parameters:
    
    e -
  - processInputMethodEvent
```
protected void processInputMethodEvent(InputMethodEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processInputMethodEvent in class Component
    
    Parameters:
    
    e -
  - processKeyEvent
```
protected void processKeyEvent(KeyEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processKeyEvent in class JComponent
    
    Parameters:
    
    e -
  - processMouseEvent
```
protected void processMouseEvent(MouseEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processMouseEvent in class JComponent
    
    Parameters:
    
    e -
  - processMouseMotionEvent
```
protected void processMouseMotionEvent(MouseEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processMouseMotionEvent in class JComponent
    
    Parameters:
    
    e -
  - processMouseWheelEvent
```
protected void processMouseWheelEvent(MouseWheelEvent e)
```
    Redirects event to canvas and to superclass.
    
    Overrides:
    
    processMouseWheelEvent in class Component
    
    Parameters:
    
    e -
  - setBounds
```
public void setBounds(int x,
                      int y,
                      int width,
                      int height)
```
    Overrides:
    
    setBounds in class Component
    
    Parameters:
    
    x -
    
    y -
    
    width -
    
    height -
  - setResizeMode
```
public void setResizeMode(int resizeMode)
```
    Sets resize mode to be used on this component. Resize mode permits to have smoother canvas resizes. The time taken by a canvas to be resized can be pretty long: renderer has to stop, current render has to end, everything has to be initialized again, and after all that has been done, renderer is started again, then the image is displayed once rendered. Resize mode uses a timer to make those steps only after the last refresh request occured. 'Latest refresh' is determined by the amount of time between now and the last time you asked for a size change. If that time expires, a real resize is done. In between, the same size is rendered, but the drawn image is scaled down/up. This has some drawbacks, as the image can appear blocked, imprecise, distorted, incomplete for that while, but most of the time only some of the drawbacks will be users will see nothing. Default delay is set to 100ms, which is low enough for common human not to be able to really see that the rendered image is scaled.
    
    Parameters:
    
    resizeMode - can be one of RESIZE_IMMEDIATELY or RESIZE_DELAYED
    
    See Also:
    
    RESIZE_IMMEDIATELY, RESIZE_DELAYED
  - setResizeValidationDelay
```
public void setResizeValidationDelay(int resizeValidationDelay)
```
    Sets the validation delay for the component. The validation delay is the maximum time allowed for the canvas resizing to occur using rendered buffer scaling. Once that delay expired, the canvas is resized at the lowest level possible, thus in the rendering pipeline. Note: Changing this field is only useful if resize mode is set to RESIZE_IMMEDIATELY or RESIZE_DELAYED
    
    Parameters:
    
    resizeValidationDelay - the delay before a real resize would occur.
    
    See Also:
    
    RESIZE_IMMEDIATELY, RESIZE_DELAYED

Class JCanvas3D

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

Nested classes/interfaces inherited from class java.awt.Container

Nested classes/interfaces inherited from class java.awt.Component

Field Summary

Fields inherited from class javax.swing.JComponent

Fields inherited from class java.awt.Component

Fields inherited from interface java.awt.image.ImageObserver

Constructor Summary

Method Summary

Methods inherited from class javax.swing.JPanel

Methods inherited from class javax.swing.JComponent

Methods inherited from class java.awt.Container

Methods inherited from class java.awt.Component

Methods inherited from class java.lang.Object

Field Detail

RESIZE_IMMEDIATELY

RESIZE_DELAYED

Constructor Detail

JCanvas3D

JCanvas3D

JCanvas3D

JCanvas3D

Method Detail

ancestorAdded

ancestorMoved

ancestorRemoved

getOffscreenCanvas3D

getResizeMode

getResizeValidationDelay

paintComponent

processComponentKeyEvent

processFocusEvent

processInputMethodEvent

processKeyEvent

processMouseEvent

processMouseMotionEvent

processMouseWheelEvent

setBounds

setResizeMode

setResizeValidationDelay