org.j3d.aviatrix3d.output.graphics
Class StereoAWTSurface

java.lang.Object
  org.j3d.aviatrix3d.output.graphics.BaseSurface
      org.j3d.aviatrix3d.output.graphics.BaseAWTSurface
          org.j3d.aviatrix3d.output.graphics.StereoAWTSurface

All Implemented Interfaces:

GraphicsOutputDevice, OutputDevice

public class StereoAWTSurface
extends BaseAWTSurface

Implementation of the most drawable surface, supporting stereo rendering capabilities.

This implementation of GraphicsOutputDevice renders to a normal GLCanvas instance and provides pBuffer support as needed. Stereo support is provided based on the underlying hardware capabilities in combination with the user requested features.

In implementing the alternate frame mode rendering, there's some odd artifacts/bugs in the rendering process. What seems to be happening is if we draw left and then right on the same canvas one after the other, the left one always gets drawn, and the right one is drawn, with the left cleared very quickly. The effect is that the right image is very prominent, but the left is almost not seen at all.

So, for now the implementation uses an internal flag to draw to alternate eyes on each alternate call to display() from the external rendering thread. This really slows the renderer down from a frame rate perspective, so make sure your rendering cycle time is halved if you are using that to control frame rate.

Version:

$Revision: 3.13 $

Author:

Justin Couch

Field Summary

Fields inherited from class org.j3d.aviatrix3d.output.graphics.BaseAWTSurface

lightweight, resizer

Fields inherited from class org.j3d.aviatrix3d.output.graphics.BaseSurface

alphaCutoff, canCreatePBuffers, canvas, canvasContext, canvasDescriptor, canvasRenderer, errorReporter, FAILED_CONTEXT_MSG, initComplete, numRenderables, renderableList, rendererMap, sharedSurface, singleThreaded, surfaceMonitor, terminate, useTwoPassTransparent

Fields inherited from interface org.j3d.aviatrix3d.pipeline.graphics.GraphicsOutputDevice

ALTERNATE_FRAME_STEREO, NO_STEREO, QUAD_BUFFER_STEREO, TWO_CANVAS_STEREO

Constructor Summary

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, BaseSurface sharedWith, boolean lightweight, int policy)
Construct a surface shares it's GL context with the given surface.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, BaseSurface sharedWith, int policy)
Construct a surface shares it's GL context with the given surface.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, boolean lightweight, int policy)
Construct a surface that requires the given set of capabilities.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, javax.media.opengl.GLCapabilitiesChooser chooser, BaseSurface sharedWith, boolean lightweight, int policy)
Construct a surface shares it's GL context with the given surface.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, javax.media.opengl.GLCapabilitiesChooser chooser, BaseSurface sharedWith, int policy)
Construct a surface shares it's GL context with the given surface.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, javax.media.opengl.GLCapabilitiesChooser chooser, boolean lightweight, int policy)
Construct a surface that requires the given set of capabilities.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, javax.media.opengl.GLCapabilitiesChooser chooser, int policy)
Construct a surface that requires the given set of capabilities.

StereoAWTSurface(javax.media.opengl.GLCapabilities caps, int policy)
Construct a surface that requires the given set of capabilities.

Method Summary

boolean	completeCanvasInitialisation(javax.media.opengl.GL gl) Used during initialisation of the system for the first time.
protected boolean	createLightweightContext() Attempt to create a new lightweight canvas renderer now.
boolean	draw(GraphicsProfilingData profilingData) Instruct the surface to draw the collected set of nodes now.
float	getStereoEyeSeparation() Get the current eye separation value - always returns 0.
int	getStereoRenderingPolicy() Get the current stereo rendering policy in use.
java.lang.Object	getSurfaceObject() Get the underlying object that this surface is rendered to.
boolean	isQuadStereoAvailable() Check to see whether this surface supports Quad buffer stereo rendering.
boolean	isStereoAvailable() Check to see whether this surface supports stereo rendering.
void	resychronizeRenderTarget() Resynchronise the stereo rendering to be the next frame as the left eye view.
void	setStereoEyeSeparation(float sep) Set the eye separation value when rendering stereo.
void	setStereoRenderingPolicy(int policy) Set the rendering policy used when handling stereo.

Methods inherited from class org.j3d.aviatrix3d.output.graphics.BaseAWTSurface

addGraphicsResizeListener, draw, removeGraphicsResizeListener, setDrawableObjects, setErrorReporter, swap

Methods inherited from class org.j3d.aviatrix3d.output.graphics.BaseSurface

addSurfaceInfoListener, checkForExtension, createRenderingProcessor, dispose, disposeSingleThreadResources, enableSingleThreaded, enableTwoPassTransparentRendering, getAlphaTestCutoff, getCenterEyeInSurface, getGLContext, getPixelLocationInSurface, getSharedGLContext, getSurfaceToVWorld, init, initCanvas, isDisposed, isShared, isTwoPassTransparentEnabled, removeSurfaceInfoListener, setAlphaTestCutoff, setClearColor, setColorClearNeeded

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        int policy)

Construct a surface that requires the given set of capabilities. This surface acts as a standalone canvas.

Parameters:

caps - A set of required capabilities for this canvas.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        javax.media.opengl.GLCapabilitiesChooser chooser,
                        int policy)

Construct a surface that requires the given set of capabilities. This surface acts as a standalone canvas.

Parameters:

caps - A set of required capabilities for this canvas.

chooser - Custom algorithm for selecting one of the available GLCapabilities for the component;

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        boolean lightweight,
                        int policy)

Construct a surface that requires the given set of capabilities. This surface acts as a standalone canvas.

Parameters:

caps - A set of required capabilities for this canvas.

lightweight - If true, uses a GLJPanel (lightweight) JComponent, otherwise a GLCanvas. Note that setting this to true could negatively impact performance.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        javax.media.opengl.GLCapabilitiesChooser chooser,
                        boolean lightweight,
                        int policy)

Construct a surface that requires the given set of capabilities. This surface acts as a standalone canvas.

Parameters:

caps - A set of required capabilities for this canvas.

chooser - Custom algorithm for selecting one of the available GLCapabilities for the component;

lightweight - If true, uses a GLJPanel (lightweight) JComponent, otherwise a GLCanvas. Note that setting this to true could negatively impact performance.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        BaseSurface sharedWith,
                        int policy)

Construct a surface shares it's GL context with the given surface. This is useful for constructing multiple view displays of the same scene graph, but from different viewing directions, such as in a CAD application.

If the sharedWith parameter is null, then this is just treated as an ordinary non-shared frame. The return flag will be set appropriately.

Parameters:

caps - A set of required capabilities for this canvas.

sharedWith - The surface that you'd like this surface to share the GL context with, if possible. May be null.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        javax.media.opengl.GLCapabilitiesChooser chooser,
                        BaseSurface sharedWith,
                        int policy)

Construct a surface shares it's GL context with the given surface. This is useful for constructing multiple view displays of the same scene graph, but from different viewing directions, such as in a CAD application.

If the sharedWith parameter is null, then this is just treated as an ordinary non-shared frame. The return flag will be set appropriately.

Parameters:

caps - A set of required capabilities for this canvas.

chooser - Custom algorithm for selecting one of the available GLCapabilities for the component;

sharedWith - The surface that you'd like this surface to share the GL context with, if possible. May be null.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        BaseSurface sharedWith,
                        boolean lightweight,
                        int policy)

Construct a surface shares it's GL context with the given surface. This is useful for constructing multiple view displays of the same scene graph, but from different viewing directions, such as in a CAD application.

If the sharedWith parameter is null, then this is just treated as an ordinary non-shared frame. The return flag will be set appropriately.

Parameters:

caps - A set of required capabilities for this canvas.

sharedWith - The surface that you'd like this surface to share the GL context with, if possible. May be null.

lightweight - If true, uses a GLJPanel (lightweight) JComponent, otherwise a GLCanvas. Note that setting this to true could negatively impact performance.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

StereoAWTSurface

public StereoAWTSurface(javax.media.opengl.GLCapabilities caps,
                        javax.media.opengl.GLCapabilitiesChooser chooser,
                        BaseSurface sharedWith,
                        boolean lightweight,
                        int policy)

Construct a surface shares it's GL context with the given surface. This is useful for constructing multiple view displays of the same scene graph, but from different viewing directions, such as in a CAD application.

If the sharedWith parameter is null, then this is just treated as an ordinary non-shared frame. The return flag will be set appropriately.

Parameters:

caps - A set of required capabilities for this canvas.

chooser - Custom algorithm for selecting one of the available GLCapabilities for the component;

sharedWith - The surface that you'd like this surface to share the GL context with, if possible. May be null.

lightweight - If true, uses a GLJPanel (lightweight) JComponent, otherwise a GLCanvas. Note that setting this to true could negatively impact performance.

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

Method Detail

isStereoAvailable

public boolean isStereoAvailable()

Check to see whether this surface supports stereo rendering. As this is not known until after initialisation, this method will return false until it can determine whether or not stereo is available.

Specified by:

isStereoAvailable in interface GraphicsOutputDevice

Overrides:

isStereoAvailable in class BaseSurface

Returns:

true Stereo support is currently available

isQuadStereoAvailable

public boolean isQuadStereoAvailable()

Check to see whether this surface supports Quad buffer stereo rendering. Quadbuffers uses the GL_BACK_LEFT and GL_BACK_RIGHT for rendering pairs rather than drawing alternate frames to the same window.

As this is not known until after initialisation, this method will return false until it can determine whether or not stereo is available.

Specified by:

isQuadStereoAvailable in interface GraphicsOutputDevice

Overrides:

isQuadStereoAvailable in class BaseSurface

Returns:

true Stereo support is currently available

setStereoEyeSeparation

public void setStereoEyeSeparation(float sep)

Set the eye separation value when rendering stereo. The default value is 0.33 for most applications. The absolute value of the separation is always used. Ignored for this implementation.

Specified by:

setStereoEyeSeparation in interface GraphicsOutputDevice

Overrides:

setStereoEyeSeparation in class BaseSurface

Parameters:

sep - The amount of eye separation

getStereoEyeSeparation

public float getStereoEyeSeparation()

Get the current eye separation value - always returns 0.

Specified by:

getStereoEyeSeparation in interface GraphicsOutputDevice

Overrides:

getStereoEyeSeparation in class BaseSurface

Returns:

sep The amount of eye separation

setStereoRenderingPolicy

public void setStereoRenderingPolicy(int policy)

Set the rendering policy used when handling stereo. The policy must be one of the _STEREO constants defined in this interface.

Specified by:

setStereoRenderingPolicy in interface GraphicsOutputDevice

Overrides:

setStereoRenderingPolicy in class BaseSurface

Parameters:

policy - The policy to currently use

Throws:

java.lang.IllegalArgumentException - The policy type is not one of the legal selections.

getStereoRenderingPolicy

public int getStereoRenderingPolicy()

Get the current stereo rendering policy in use. If not explicitly set by the user, then it will default to NO_STEREO.

Specified by:

getStereoRenderingPolicy in interface GraphicsOutputDevice

Overrides:

getStereoRenderingPolicy in class BaseSurface

Returns:

One of the *_STEREO values

draw

public boolean draw(GraphicsProfilingData profilingData)

Instruct the surface to draw the collected set of nodes now. The registered view environment is used to draw to this surface. If no view is registered, the surface is cleared and then this call is exited. The drawing surface does not swap the buffers at this point.

The return value indicates success or failure in the ability to render this frame. Typically it will indicate failure if the underlying surface has been disposed of, either directly through the calling of the method on this interface, or through an internal check mechanism. If failure is indicated, then check to see if the surface has been disposed of and discontinue rendering if it has.

Parameters:

profilingData - The timing and load data

Returns:

true if the drawing succeeded, or false if not

getSurfaceObject

public java.lang.Object getSurfaceObject()

Get the underlying object that this surface is rendered to. If it is a screen display device, the surface can be one of AWT Component or Swing JComponent. An off-screen buffer would be a form of AWT Image etc.

Returns:

The drawable surface representation

createLightweightContext

protected boolean createLightweightContext()

Attempt to create a new lightweight canvas renderer now. This will only be called whenever the user has signalled that this is a lightweight renderer and we do not yet have a canvasRenderer instance created. If this fails, silently exit. We'll attempt to do this next frame.

Specified by:

createLightweightContext in class BaseAWTSurface

Returns:

true if this creation succeeded

completeCanvasInitialisation

public boolean completeCanvasInitialisation(javax.media.opengl.GL gl)

Used during initialisation of the system for the first time. This is called just after the extension strings have been checked, but before we return back to the main rendering loop. The default implementation is empty.

The return value indicates success or failure in the ability to initialise this surface. Typically it will indicate failure if the underlying surface has been disposed of or a failure to find the capabilities needed. The default implementation returns true.

Overrides:

completeCanvasInitialisation in class BaseSurface

Parameters:

gl - An initialised, current gl context to play with

Returns:

true if the initialisation succeeded, or false if not

resychronizeRenderTarget

public void resychronizeRenderTarget()

Resynchronise the stereo rendering to be the next frame as the left eye view. Useful when the shutter glasses or other device needs to reset with the output.