org.j3d.aviatrix3d.pipeline.graphics
Interface GraphicsOutputDevice

All Superinterfaces:

OutputDevice

All Known Subinterfaces:

ElumensOutputDevice

All Known Implementing Classes:

BaseAWTSurface, BaseDraw2DSurface, BaseSurface, BaseSWTSurface, BaseSWTSurface, DebugAWTSurface, DebugDraw2DSurface, DebugSWTSurface, DebugSWTSurface, ElumensAWTSurface, ElumensSWTSurface, ElumensSWTSurface, PbufferSurface, SimpleAWTSurface, SimpleDraw2DSurface, SimpleSWTSurface, SimpleSWTSurface, StereoAWTSurface, StereoSWTSurface, StereoSWTSurface

public interface GraphicsOutputDevice
extends OutputDevice

Interface representing the output of a render pipeline that specifically deals with graphical (visual) information.

Mouse Interaction

When working with any form of 2D input, such as a mouse, you need to transform it's device coordinates into the 3D space of the world, so that you may then do picking or other projections in world space.

Each of the mouse methods require that you pass in extra information to help with efficiency and specifically dealing with how a screen can be divided up into multiple viewports, yet still enable dragging operations to work correctly. The problem is that once you leave one viewport, you want to keep using the projection from that same viewport, not another one on the same layer. If you wish to keep the current viewport information the you can pass in a string that represents the identifier of your input device (in case you have multiple simultaneous input devices) and a flag to say whether the last found projection information for that device should still be used. If that flag is true, and the layer and sublayer IDs match, it will just project using the previously fetched information. If any of these conditions are not met, then a new set of projection information is fetched and cached for that ID.

Version:

$Revision: 3.9 $

Author:

Justin Couch

Field Summary

static int	ALTERNATE_FRAME_STEREO The stereo rendering type draws to alternate eyes on each frame.
static int	NO_STEREO The surface will render only non-stereo projection (traditional monoscopic projection policy).
static int	QUAD_BUFFER_STEREO The stereo rendering type to be used should use quad buffered, alternate frame rendering.
static int	TWO_CANVAS_STEREO The stereo rendering uses two canvases - one for each eye.

Method Summary

void	addGraphicsResizeListener(GraphicsResizeListener l) Add a resize listener instance to this surface.
void	addSurfaceInfoListener(SurfaceInfoListener l) Add a surface info listener instance to this surface.
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.
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.
float	getStereoEyeSeparation() Get the current eye separation value, defined as the distance from the center axis to one eye.
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.
boolean	isQuadStereoAvailable() Check to see whether this surface supports Quad buffer stereo rendering.
boolean	isStereoAvailable() Check to see whether this surface supports stereo rendering.
boolean	isTwoPassTransparentEnabled() Check the state of the two pass transprent rendering flag.
void	removeGraphicsResizeListener(GraphicsResizeListener l) Remove a resize listener from this surface.
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	setStereoEyeSeparation(float sep) Set the eye separation value when rendering stereo, defined as the distance from the center axis to one eye.
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 interface org.j3d.aviatrix3d.pipeline.OutputDevice

dispose, disposeSingleThreadResources, draw, enableSingleThreaded, getSurfaceObject, isDisposed, setErrorReporter

Field Detail

NO_STEREO

static final int NO_STEREO

The surface will render only non-stereo projection (traditional monoscopic projection policy).

See Also:

Constant Field Values

QUAD_BUFFER_STEREO

static final int QUAD_BUFFER_STEREO

The stereo rendering type to be used should use quad buffered, alternate frame rendering. In this type it renders to the left back buffer, then right back buffer and then swaps both. This is useful if you have HMDs which have two separate windows for the rendering.

See Also:

Constant Field Values

ALTERNATE_FRAME_STEREO

static final int ALTERNATE_FRAME_STEREO

The stereo rendering type draws to alternate eyes on each frame. Used if you have shutter glasses where the user's vision is restricted to one eye or the other, but not both at the same time. Only uses a single double buffer to render alternate eye points

See Also:

Constant Field Values

TWO_CANVAS_STEREO

static final int TWO_CANVAS_STEREO

The stereo rendering uses two canvases - one for each eye. The canvases are placed either side by side or vertically stacked, depending on the rendering options requested.

See Also:

Constant Field Values

Method Detail

isStereoAvailable

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.

Returns:

true Stereo support is currently available

isQuadStereoAvailable

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.

Returns:

true Stereo support is currently available

setStereoRenderingPolicy

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.

Parameters:

policy - The policy to currently use

Throws:

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

getStereoRenderingPolicy

int getStereoRenderingPolicy()

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

Returns:

One of the *_STEREO values

setStereoEyeSeparation

void setStereoEyeSeparation(float sep)

Set the eye separation value when rendering stereo, defined as the distance from the center axis to one eye. The default value is 0.33 for most applications. The absolute value of the separation is always used.

Parameters:

sep - The amount of eye separation

getStereoEyeSeparation

float getStereoEyeSeparation()

Get the current eye separation value, defined as the distance from the center axis to one eye. If we are in no-stereo mode then this will return zero.

Returns:

sep The amount of eye separation

setClearColor

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.

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

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.

Parameters:

state - true if we should always locally clear first

enableTwoPassTransparentRendering

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).

Parameters:

state - true if we should enable two pass rendering

isTwoPassTransparentEnabled

boolean isTwoPassTransparentEnabled()

Check the state of the two pass transprent rendering flag.

Returns:

true if two pass rendering of transparent objects is enabled

setAlphaTestCutoff

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).

Parameters:

cutoff - The alpha value at which to enable rendering

getAlphaTestCutoff

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.

Returns:

The currently set cut off value

setDrawableObjects

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.

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

void swap()

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

getSurfaceToVWorld

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.

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

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.

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 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

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.

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

addGraphicsResizeListener

void addGraphicsResizeListener(GraphicsResizeListener l)

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

Parameters:

l - The new listener instance to add

removeGraphicsResizeListener

void removeGraphicsResizeListener(GraphicsResizeListener l)

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

Parameters:

l - The listener instance to remove

addSurfaceInfoListener

void addSurfaceInfoListener(SurfaceInfoListener l)

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

Parameters:

l - The new listener instance to add

removeSurfaceInfoListener

void removeSurfaceInfoListener(SurfaceInfoListener l)

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

Parameters:

l - The listener instance to remove