org.j3d.aviatrix3d.output.graphics
Class BaseSurface

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

All Implemented Interfaces:

GraphicsOutputDevice, OutputDevice

Direct Known Subclasses:

BaseAWTSurface, BaseDraw2DSurface, BaseSWTSurface, BaseSWTSurface, PbufferSurface

public abstract class BaseSurface
extends java.lang.Object
implements GraphicsOutputDevice

Implementation of the most basic drawable surface, supporting the minimal number of features that is to be used by other, more complete implementations.

This implementation of GraphicsOutputDevice renders to a normal GLCanvas or GLJPanel (depending on if "lightweight" is true) instance and provides pBuffer support as needed. Stereo support is not provided and all associated methods always indicate negative returns on query about support.

Version:

$Revision: 3.50 $

Author:

Justin Couch

Field Summary

protected float	alphaCutoff Alpha Test value for the parts of transparent objects that should be handled as opaque
protected boolean	canCreatePBuffers Flag to say whether the underlying factory can create pbuffers
protected javax.media.opengl.GLDrawable	canvas The real canvas that we draw to
protected javax.media.opengl.GLContext	canvasContext The context of the main canvas
protected org.j3d.aviatrix3d.output.graphics.MainCanvasDescriptor	canvasDescriptor Buffer descriptor for the main canvas
protected RenderingProcessor	canvasRenderer Abstract representation of the underlying primary renderer
protected org.j3d.util.ErrorReporter	errorReporter Error reporter used to send out messages
protected static java.lang.String	FAILED_CONTEXT_MSG Message when the GL context failed to initialise
protected boolean	initComplete Flag to say that init has been called on the canvas
protected int	numRenderables Number of items in the renderable list
protected OffscreenBufferRenderable[]	renderableList Local storage of the nodes that need to be rendered
protected java.util.Map<OffscreenBufferRenderable,RenderingProcessor>	rendererMap Maps from a ofscreen texture instance to the rendererProcessor for it
protected BaseSurface	sharedSurface Flag indicating if this surface is shared with another
protected boolean	singleThreaded Single threaded rendering mode operation state.
protected SurfaceMonitor	surfaceMonitor Manager of surface status so that we know what to do with the context (ie refresh it or makeCurrent again).
protected boolean	terminate Flag indicating whether rendering should be stopped right now
protected boolean	useTwoPassTransparent Flag indicating if we should do single or two-pass rendering of transparent objects.

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

ALTERNATE_FRAME_STEREO, NO_STEREO, QUAD_BUFFER_STEREO, TWO_CANVAS_STEREO

Constructor Summary

protected

BaseSurface(BaseSurface sharedWith) Construct a surface shares it's GL context with the given surface.

Method Summary

void	addSurfaceInfoListener(SurfaceInfoListener l) Add a surface info listener instance to this surface.
void	checkForExtension(java.lang.String glExtensionString) Add an extension string to check for at startup.
boolean	completeCanvasInitialisation(javax.media.opengl.GL gl) Used during initialisation of the system for the first time.
protected RenderingProcessor	createRenderingProcessor(javax.media.opengl.GLContext ctx) Create a new RenderingProcessor instance for this surface.
void	dispose() Instruct this surface that you have finished with the resources needed and to dispose all rendering resources.
void	disposeSingleThreadResources() If the output device is marked as single threaded, this instructs the device that the current rendering thread has exited.
boolean	draw(ProfilingData profilingData) Instruct the surface to draw the collected set of nodes now.
void	enableSingleThreaded(boolean state) Notification that this surface is being drawn to with a single thread.
void	enableTwoPassTransparentRendering(boolean state) Enable or disable two pass rendering of transparent objects.
float	getAlphaTestCutoff() Get the current value of the alpha test cutoff number.
boolean	getCenterEyeInSurface(int x, int y, int layer, int subLayer, javax.vecmath.Point3f position, java.lang.String deviceId, boolean useLastFound) Get the Center Eye position in surface coordinates.
javax.media.opengl.GLContext	getGLContext() Package local method to fetch the GLContext that this surface has.
boolean	getPixelLocationInSurface(int x, int y, int layer, int subLayer, javax.vecmath.Point3f position, java.lang.String deviceId, boolean useLastFound) Convert a pixel location to surface coordinates.
protected javax.media.opengl.GLContext	getSharedGLContext() Get the context object from the shared surface, if there is one set.
float	getStereoEyeSeparation() Get the current eye separation value - always returns 0.
int	getStereoRenderingPolicy() Get the current stereo rendering policy in use.
boolean	getSurfaceToVWorld(int x, int y, int layer, int subLayer, javax.vecmath.Matrix4f matrix, java.lang.String deviceId, boolean useLastFound) Get the surface to VWorld transformation matrix.
protected void	init() Common internal initialisation for the constructors.
protected boolean	initCanvas() Called by the drawable immediately after the OpenGL context is initialized; the GLContext has already been made current when this method is called.
boolean	isDisposed() Check to see the disposal state of the surface.
boolean	isQuadStereoAvailable() Check to see whether this surface supports Quad buffer stereo rendering - which it does not.
boolean	isShared() Check to see whether this object is currently shared.
boolean	isStereoAvailable() Check to see whether this surface supports stereo rendering - which is does not.
boolean	isTwoPassTransparentEnabled() Check the state of the two pass transprent rendering flag.
void	removeSurfaceInfoListener(SurfaceInfoListener l) Remove a surface info listener from this surface.
void	setAlphaTestCutoff(float cutoff) If two pass rendering of transparent objects is enabled, this is the alpha test value used when deciding what to render.
void	setClearColor(float r, float g, float b, float a) Set the background colour that this surface should be cleared to before the drawing step.
void	setColorClearNeeded(boolean state) Set whether we should always force a local colour clear before beginning any drawing.
void	setDrawableObjects(GraphicsRequestData otherData, GraphicsInstructions[] commands, int numValid) Update the list of items to be rendered to the current list.
void	setErrorReporter(org.j3d.util.ErrorReporter reporter) Register an error reporter with the engine so that any errors generated by the node's internals can be reported in a nice, pretty fashion.
void	setStereoEyeSeparation(float sep) Set the eye separation value when rendering stereo.
void	setStereoRenderingPolicy(int policy) Set the rendering policy used when handling stereo.
void	swap() Swap the buffers now if the surface supports multiple buffer drawing.

Methods inherited from class java.lang.Object

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

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

addGraphicsResizeListener, removeGraphicsResizeListener

Methods inherited from interface org.j3d.aviatrix3d.pipeline.OutputDevice

getSurfaceObject

Field Detail

FAILED_CONTEXT_MSG

protected static final java.lang.String FAILED_CONTEXT_MSG

Message when the GL context failed to initialise

See Also:

Constant Field Values

canvas

protected javax.media.opengl.GLDrawable canvas

The real canvas that we draw to

canvasContext

protected javax.media.opengl.GLContext canvasContext

The context of the main canvas

surfaceMonitor

protected SurfaceMonitor surfaceMonitor

Manager of surface status so that we know what to do with the context (ie refresh it or makeCurrent again). This must be initialised in the constructor.

canvasRenderer

protected RenderingProcessor canvasRenderer

Abstract representation of the underlying primary renderer

canvasDescriptor

protected org.j3d.aviatrix3d.output.graphics.MainCanvasDescriptor canvasDescriptor

Buffer descriptor for the main canvas

renderableList

protected OffscreenBufferRenderable[] renderableList

Local storage of the nodes that need to be rendered

numRenderables

protected int numRenderables

Number of items in the renderable list

initComplete

protected boolean initComplete

Flag to say that init has been called on the canvas

rendererMap

protected java.util.Map<OffscreenBufferRenderable,RenderingProcessor> rendererMap

Maps from a ofscreen texture instance to the rendererProcessor for it

sharedSurface

protected BaseSurface sharedSurface

Flag indicating if this surface is shared with another

canCreatePBuffers

protected boolean canCreatePBuffers

Flag to say whether the underlying factory can create pbuffers

errorReporter

protected org.j3d.util.ErrorReporter errorReporter

Error reporter used to send out messages

terminate

protected boolean terminate

Flag indicating whether rendering should be stopped right now

singleThreaded

protected boolean singleThreaded

Single threaded rendering mode operation state. Defaults to false.

alphaCutoff

protected float alphaCutoff

Alpha Test value for the parts of transparent objects that should be handled as opaque

useTwoPassTransparent

protected boolean useTwoPassTransparent

Flag indicating if we should do single or two-pass rendering of transparent objects.

Constructor Detail

BaseSurface

protected BaseSurface(BaseSurface sharedWith)

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:

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

Method Detail

isStereoAvailable

public boolean isStereoAvailable()

Check to see whether this surface supports stereo rendering - which is does not. Always returns false. May be overridden by derived class to provide a different answer.

Specified by:

isStereoAvailable in interface GraphicsOutputDevice

Returns:

false Stereo is not available

isQuadStereoAvailable

public boolean isQuadStereoAvailable()

Check to see whether this surface supports Quad buffer stereo rendering - which it does not. Always returns false for this implementation. May be overridden by derived class to provide a different answer.

Specified by:

isQuadStereoAvailable in interface GraphicsOutputDevice

Returns:

false The surface does not support stereo at all

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. May be overridden by derived class to provide a different answer.

Specified by:

setStereoEyeSeparation in interface GraphicsOutputDevice

Parameters:

sep - The amount of eye separation

getStereoEyeSeparation

public float getStereoEyeSeparation()

Get the current eye separation value - always returns 0. May be overridden by derived class to provide a different answer.

Specified by:

getStereoEyeSeparation in interface GraphicsOutputDevice

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. May be overridden by derived class to provide a different answer.

Specified by:

setStereoRenderingPolicy in interface GraphicsOutputDevice

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. May be overridden by derived class to provide a different answer.

Specified by:

getStereoRenderingPolicy in interface GraphicsOutputDevice

Returns:

One of the *_STEREO values

setClearColor

public void setClearColor(float r,
                          float g,
                          float b,
                          float a)

Set the background colour that this surface should be cleared to before the drawing step. Colours range from 0 to 1 in the normal manner.

Specified by:

setClearColor in interface GraphicsOutputDevice

Parameters:

r - The red component of the background clear colour

g - The green component of the background clear colour

b - The blue component of the background clear colour

a - The alpha component of the background clear colour

setColorClearNeeded

public void setColorClearNeeded(boolean state)

Set whether we should always force a local colour clear before beginning any drawing. If this is set to false, then we can assume that there is at least one background floating around that we can use to clear whatever was drawn in the previous frame, and so we can ignore the glClear(GL.GL_COLOR_BUFFER_BIT) call. The default is set to true.

Specified by:

setColorClearNeeded in interface GraphicsOutputDevice

Parameters:

state - true if we should always locally clear first

enableTwoPassTransparentRendering

public void enableTwoPassTransparentRendering(boolean state)

Enable or disable two pass rendering of transparent objects. By default it is disabled. This flag applies to this surface and any offscreen surfaces that are children of this surface (FBOs, PBuffers etc).

Specified by:

enableTwoPassTransparentRendering in interface GraphicsOutputDevice

Parameters:

state - true if we should enable two pass rendering

isTwoPassTransparentEnabled

public boolean isTwoPassTransparentEnabled()

Check the state of the two pass transprent rendering flag.

Specified by:

isTwoPassTransparentEnabled in interface GraphicsOutputDevice

Returns:

true if two pass rendering of transparent objects is enabled

setAlphaTestCutoff

public void setAlphaTestCutoff(float cutoff)

If two pass rendering of transparent objects is enabled, this is the alpha test value used when deciding what to render. The default value is 1.0. No sanity checking is performed, but the value should be between [0,1].

This flag applies to this surface and any offscreen surfaces that are children of this surface (FBOs, PBuffers etc).

Specified by:

setAlphaTestCutoff in interface GraphicsOutputDevice

Parameters:

cutoff - The alpha value at which to enable rendering

getAlphaTestCutoff

public float getAlphaTestCutoff()

Get the current value of the alpha test cutoff number. Will always return the currently set number regardless of the state of the two pass rendering flag.

Specified by:

getAlphaTestCutoff in interface GraphicsOutputDevice

Returns:

The currently set cut off value

setDrawableObjects

public void setDrawableObjects(GraphicsRequestData otherData,
                               GraphicsInstructions[] commands,
                               int numValid)

Update the list of items to be rendered to the current list. Draw them at the next oppourtunity.

Specified by:

setDrawableObjects in interface GraphicsOutputDevice

Parameters:

otherData - data to be processed before the rendering

commands - The list of drawable surfaces to render

numValid - The number of valid items in the array

swap

public void swap()

Swap the buffers now if the surface supports multiple buffer drawing. For surfaces that don't support multiple buffers, this does nothing.

Specified by:

swap in interface GraphicsOutputDevice

getSurfaceToVWorld

public boolean getSurfaceToVWorld(int x,
                                  int y,
                                  int layer,
                                  int subLayer,
                                  javax.vecmath.Matrix4f matrix,
                                  java.lang.String deviceId,
                                  boolean useLastFound)

Get the surface to VWorld transformation matrix.

Specified by:

getSurfaceToVWorld in interface GraphicsOutputDevice

Parameters:

x - The X coordinate in the entire surface

y - The Y coordinate in the entire surface

layer - The layer ID to fetch from. Layer 0 is the front-most

subLayer - The ID of the viewport-layer that is needed. If there are no sub-layers, use 0.

matrix - The matrix to copy into

deviceId - A user-defined identifier for the requesting device when using the lastFound items

useLastFound - Should we skip the search process and use the last data found for this layer/sublayer combo.

Returns:

Whether the coordinates where on the layer

getPixelLocationInSurface

public boolean getPixelLocationInSurface(int x,
                                         int y,
                                         int layer,
                                         int subLayer,
                                         javax.vecmath.Point3f position,
                                         java.lang.String deviceId,
                                         boolean useLastFound)

Convert a pixel location to surface coordinates.

Specified by:

getPixelLocationInSurface in interface GraphicsOutputDevice

Parameters:

x - The X coordinate

y - The Y coordinate

layer - The layer ID to fetch from. Layer 0 is the front-most

subLayer - The ID of the viewport-layer that is needed. If there are no sub-layers, use 0.

position - The converted position. It must be preallocated.

deviceId - A user-defined identifier for the requesting device when using the lastFound items

useLastFound - Should we skip the search process and use the last data found for this layer/sublayer combo.

Returns:

Whether the coordinates where on the layer

getCenterEyeInSurface

public boolean getCenterEyeInSurface(int x,
                                     int y,
                                     int layer,
                                     int subLayer,
                                     javax.vecmath.Point3f position,
                                     java.lang.String deviceId,
                                     boolean useLastFound)

Get the Center Eye position in surface coordinates.

Specified by:

getCenterEyeInSurface in interface GraphicsOutputDevice

Parameters:

x - The X coordinate in the entire surface

y - The Y coordinate in the entire surface

layer - The layer ID to fetch from. Layer 0 is the front-most

subLayer - The ID of the viewport-layer that is needed. If there are no sub-layers, use 0.

position - The current eye position. It must be preallocated.

deviceId - A user-defined identifier for the requesting device when using the lastFound items

useLastFound - Should we skip the search process and use the last data found for this layer/sublayer combo.

Returns:

Whether the coordinates where on the layer

addSurfaceInfoListener

public void addSurfaceInfoListener(SurfaceInfoListener l)

Add a surface info listener instance to this surface. Duplicate listener instance add requests are ignored, as are null values.

Specified by:

addSurfaceInfoListener in interface GraphicsOutputDevice

Parameters:

l - The new listener instance to add

removeSurfaceInfoListener

public void removeSurfaceInfoListener(SurfaceInfoListener l)

Remove a surface info listener from this surface. If the listener is not currently registered the request is ignored.

Specified by:

removeSurfaceInfoListener in interface GraphicsOutputDevice

Parameters:

l - The listener instance to remove

setErrorReporter

public void setErrorReporter(org.j3d.util.ErrorReporter reporter)

Register an error reporter with the engine so that any errors generated by the node's internals can be reported in a nice, pretty fashion. Setting a value of null will clear the currently set reporter. If one is already set, the new value replaces the old.

Specified by:

setErrorReporter in interface OutputDevice

Parameters:

reporter - The instance to use or null

draw

public boolean draw(ProfilingData 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.

Specified by:

draw in interface OutputDevice

Parameters:

profilingData - The timing and load data

Returns:

true if the drawing succeeded, or false if not

dispose

public void dispose()

Instruct this surface that you have finished with the resources needed and to dispose all rendering resources.

Specified by:

dispose in interface OutputDevice

isDisposed

public boolean isDisposed()

Check to see the disposal state of the surface. Will return true if the dispose() method has been called or an internal dispose handler has detected the underlying surface is no longer valid to draw to.

Specified by:

isDisposed in interface OutputDevice

Returns:

true if the surface is disposed and no longer usable

enableSingleThreaded

public void enableSingleThreaded(boolean state)

Notification that this surface is being drawn to with a single thread. This can be used to optmise internal state handling when needed in a single versus multithreaded environment.

This method should never be called by end user code. It is purely for the purposes of the RenderManager to inform the device about what state it can expect.

Specified by:

enableSingleThreaded in interface OutputDevice

Parameters:

state - true if the device can expect single threaded behaviour

disposeSingleThreadResources

public void disposeSingleThreadResources()

If the output device is marked as single threaded, this instructs the device that the current rendering thread has exited. Next time the draw method is called, a new rendering context will need to be created for a new incoming thread instance. Also, if any other per-thread resources are around, clean those up now. This is called just before that thread exits.

Specified by:

disposeSingleThreadResources in interface OutputDevice

createRenderingProcessor

protected RenderingProcessor createRenderingProcessor(javax.media.opengl.GLContext ctx)

Create a new RenderingProcessor instance for this surface. Used extended implementations of this surface to create a processor instance that matches the specifics. The default implementation provides an instance of StandardRenderingProcessor. Implementations may override this to provide their own processor instance.

Parameters:

ctx - The parent context to use for the processor

Returns:

The rendering processor instance to use

checkForExtension

public void checkForExtension(java.lang.String glExtensionString)

Add an extension string to check for at startup.

Parameters:

glExtensionString - String to check for being valid

isShared

public boolean isShared()

Check to see whether this object is currently shared. If it is shared return true, otherwise return false.

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.

Parameters:

gl - An initialised, current gl context to play with

Returns:

true if the initialisation succeeded, or false if not

init

protected void init()

Common internal initialisation for the constructors. Derived classes must call this during their constructor otherwise this class will crash in some spectacular ways.

initCanvas

protected boolean initCanvas()

Called by the drawable immediately after the OpenGL context is initialized; the GLContext has already been made current when this method is called. Any surface that overrides the draw method should also call this method if the class variable initComplete is currently set to false.

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.

Returns:

true if the initialisation succeeded, or false if not

getGLContext

public javax.media.opengl.GLContext getGLContext()

Package local method to fetch the GLContext that this surface has. Allows there to be sharing between different surface types - for example having an elumens surface on one screen and a normal renderer on another.

Returns:

The context used by this surface

getSharedGLContext

protected javax.media.opengl.GLContext getSharedGLContext()

Get the context object from the shared surface, if there is one set. If there is no surface set then this will return null

Returns:

The context from the shared surface or null