org.j3d.aviatrix3d.pipeline.graphics
Class BaseCullStage

java.lang.Object
  org.j3d.aviatrix3d.pipeline.graphics.BaseCullStage

All Implemented Interfaces:

CullStage, GraphicsCullStage

Direct Known Subclasses:

DebugFrustumCullStage, FrustumCullStage, GenericCullStage, NullCullStage, SimpleFrustumCullStage

public abstract class BaseCullStage
extends java.lang.Object
implements GraphicsCullStage

Common implementation of many of the capabilities required by any cull stage.

The class takes care of the majority of the basic implementation requirements such as resizing various data structures, traversing the top of the scene graph super structure (layers, viewports et al) and processing offscreen sources, before sending onto the next stage. All the derived class is required to do is handle traversing a single scene instance and registering any pBuffer offscreens it happens to find. This class will make sure that they are looked after appropriately.

Version:

$Revision: 3.38 $

Author:

Justin Couch

Field Summary

protected OffscreenCullable	activeParent The active parent scene of the scene we are processing.
protected OverrideRenderable[]	appearanceStack A stack used to control the appearance override nodes down the tree
protected boolean	checkOffscreens If set, recurse into Shape3Ds looking for offscreen textures
protected EffectRenderable[]	clipList The list of clip plane nodes currently valid while traversing.
protected float[][]	clipTxList The list of clip transforms currently valid while traversing
protected java.util.ArrayList<Cullable>	currentViewpointPath Path to the current viewpoint
protected org.j3d.util.ErrorReporter	errorReporter Local reporter to put errors in
protected float[]	eyePoint Storage variable for the eye offset values
protected EffectRenderable[]	fogStack A stack used to control the depth of the fog nodes down the tree
protected int	lastAppearanceStack Index to the next place to add items in the fogStack
protected int	lastClip Index to the next place to add items in the clipList
protected int	lastFogStack Index to the next place to add items in the fogStack
protected int	lastLight Index to the next place to add items in the lightList
protected int	lastOutputLayer Index of the the next layer output
protected int	lastOutputList Index to the next output list in the validCullList
protected int	lastSubscene Index of the last subscene in the list
protected int	lastTxStack Index to the next place to add items in the transformStack
protected LayerCullable[]	layersTmp Temporary variable for fetching layers from sub scenes
protected static int	LIGHT_INCREMENT The increment size of the list if it gets overflowed
protected static int	LIGHT_START_SIZE The initial size of the light list
protected EffectRenderable[]	lightList The list of lights nodes currently valid while traversing.
protected float[][]	lightTxList The list of light transforms currently valid while traversing
protected static int	LIST_INCREMENT The increment size of the list if it gets overflowed
protected static int	LIST_START_LENGTH Initial size of the cull list for the number of offscreen surfaces
protected org.j3d.util.MatrixUtils	matrixUtils Matrix utility code for doing inversions
protected javax.vecmath.Matrix4f	orientationMatrix Rotation matrix for the orientation provided by user
protected int[]	outputLayerCounts Final list of the counts of layers in each subscene
protected ViewportCollection[][]	outputLayers Final list of the layers that are to be passed to the output
protected OffscreenBufferRenderable[][]	outputSceneParents List of valid subscene parents as we process them
protected OffscreenCullable[]	pendingParents Buffer list of sub scenes that still need processing
protected OffscreenCullable[]	pendingSubscenes Buffer list of sub scenes that still need processing
protected org.j3d.util.HashSet	processedPBufferTextures Collection of offscreen textures we've found this frame
protected float[]	screenOrientation Storage variable for the screen orientation values
protected static java.lang.String	SHARED_VP_MSG Message when setting the active view if it contains a shared parent
protected boolean	terminate Flag indicating a shutdown of the current processing is requested
protected javax.vecmath.Matrix4f[]	transformStack A stack used to control the depth of the transform tree
protected boolean	useEyePoint Flag to say explicit eyepoint values have been provided
protected boolean	useOrientation Flag to say explicit screen orientation values have been provided
protected OffscreenBufferRenderable[][]	validSceneParents List of valid subscene parents as we process them
protected javax.vecmath.Matrix4f	viewMatrix1 Matrix used for pre-computing the view stack
protected javax.vecmath.Matrix4f	viewMatrix2 Matrix used for pre-computing the view stack
protected GraphicsCullOutputDetails[]	workCullList List that is being used to fill values into
protected int[]	workLayerCounts Working list of the counts of layers in each subscene
protected ViewportCollection[][]	workLayers Working list of the layers that are to be passed to the output

Constructor Summary

BaseCullStage(int numSurfaces)
Create a basic instance of this class with the list initial internal setup for the given number of renderable surfaces.

Method Summary

protected void	checkForOffscreens(ShapeRenderable shape) Check a shape node for the offscreen textures that may be present.
protected void	cleanupOldRefs() Clean up the unused resources after the end of the cull process.
void	cull(RenderableRequestData otherData, ProfilingData profilingData, LayerCullable[] layers, int numLayers) Update and cull the scenegraph defined by a set of layers.
protected void	cullMultipassViewportLayer(SceneCullable scene, int subsceneId, int layerId, int viewIndex, int layerIndex) Cull through a multipass viewport layer.
protected abstract void	cullRenderPass(RenderPassCullable pass, int passNumber, int subsceneId, int layerId, int viewIndex, int layerIndex) Update and cull the a single pass from a multipass rendering.
protected abstract void	cullScene(RenderPassCullable scene, int subsceneId, int layerId, int viewIndex, int layerIndex) Update and cull the scenegraph.
protected abstract void	cullScene2D(RenderPassCullable scene, int subsceneId, int layerId, int viewIndex, int layerIndex) Update and cull a 2D scenegraph.
protected void	cullSingleViewportLayer(SceneCullable scene, int subsceneId, int layerId, int viewIndex, int layerIndex) Cull through a multipass viewport layer.
protected void	cullViewport(ViewportCullable view, int subsceneId, int layerId, int viewIndex) Process a single viewport for culling.
protected void	fill2DEnvData(SceneCullable scene, GraphicsEnvironmentData envData) Take a 2D scene and fill in a GraphicsEnvironmentData instance.
protected void	fillMultipassEnvData(SceneCullable scene, GraphicsEnvironmentData envData) Take a simple scene and fill in a GraphicsEnvironmentData instance.
protected void	fillRenderPassEnvData(RenderPassCullable pass, GraphicsEnvironmentData envData, BufferDetails bufferData) Take a simple scene and fill in a GraphicsEnvironmentData instance.
protected void	fillSingleEnvData(SceneCullable scene, GraphicsEnvironmentData envData) Take a simple scene and fill in a GraphicsEnvironmentData instance.
void	halt() Force a halt of the current processing.
boolean	isOffscreenCheckEnabled() Find out what the current offscreen check state is.
protected void	processLayer(LayerCullable layer, int subsceneId, int layerId) Process the layers of a pbuffer texture source.
protected void	resizeAppearanceStack() Resize the appearance stack if needed.
protected void	resizeClipList() Resize the list if needed.
protected void	resizeCullList(int cur_size) Resize the list if needed.
protected void	resizeFogStack() Resize the fog stack if needed.
protected void	resizeLightList() Resize the list if needed.
protected void	resizeOffscreenList() Resize the list if needed.
protected void	resizeOutputLists() Resize the list if needed.
protected void	resizeStack() Resize the transform stack if needed.
void	setCulledGeometryReceiver(CulledGeometryReceiver sgr) Register a reciever for the output of the sorter.
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	setEyePointOffset(float x, float y, float z) Set the eyepoint offset from the centre position.
void	setOffscreenCheckEnabled(boolean state) Set the flag for whether to check for offscreen textures or not.
void	setScreenOrientation(float x, float y, float z, float a) Set the orientation of this screen relative to the user's normal view direction.

Methods inherited from class java.lang.Object

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

Field Detail

SHARED_VP_MSG

protected static final java.lang.String SHARED_VP_MSG

Message when setting the active view if it contains a shared parent

See Also:

Constant Field Values

LIST_START_LENGTH

protected static final int LIST_START_LENGTH

Initial size of the cull list for the number of offscreen surfaces

See Also:

Constant Field Values

LIST_INCREMENT

protected static final int LIST_INCREMENT

The increment size of the list if it gets overflowed

See Also:

Constant Field Values

LIGHT_START_SIZE

protected static final int LIGHT_START_SIZE

The initial size of the light list

See Also:

Constant Field Values

LIGHT_INCREMENT

protected static final int LIGHT_INCREMENT

The increment size of the list if it gets overflowed

See Also:

Constant Field Values

checkOffscreens

protected boolean checkOffscreens

If set, recurse into Shape3Ds looking for offscreen textures

pendingSubscenes

protected OffscreenCullable[] pendingSubscenes

Buffer list of sub scenes that still need processing

pendingParents

protected OffscreenCullable[] pendingParents

Buffer list of sub scenes that still need processing

lastSubscene

protected int lastSubscene

Index of the last subscene in the list

workLayers

protected ViewportCollection[][] workLayers

Working list of the layers that are to be passed to the output

outputLayers

protected ViewportCollection[][] outputLayers

Final list of the layers that are to be passed to the output

workLayerCounts

protected int[] workLayerCounts

Working list of the counts of layers in each subscene

outputLayerCounts

protected int[] outputLayerCounts

Final list of the counts of layers in each subscene

lastOutputLayer

protected int lastOutputLayer

Index of the the next layer output

validSceneParents

protected OffscreenBufferRenderable[][] validSceneParents

List of valid subscene parents as we process them

outputSceneParents

protected OffscreenBufferRenderable[][] outputSceneParents

List of valid subscene parents as we process them

workCullList

protected GraphicsCullOutputDetails[] workCullList

List that is being used to fill values into

lastOutputList

protected int lastOutputList

Index to the next output list in the validCullList

transformStack

protected javax.vecmath.Matrix4f[] transformStack

A stack used to control the depth of the transform tree

lastTxStack

protected int lastTxStack

Index to the next place to add items in the transformStack

fogStack

protected EffectRenderable[] fogStack

A stack used to control the depth of the fog nodes down the tree

lastFogStack

protected int lastFogStack

Index to the next place to add items in the fogStack

lightList

protected EffectRenderable[] lightList

The list of lights nodes currently valid while traversing.

lightTxList

protected float[][] lightTxList

The list of light transforms currently valid while traversing

lastLight

protected int lastLight

Index to the next place to add items in the lightList

clipList

protected EffectRenderable[] clipList

The list of clip plane nodes currently valid while traversing.

clipTxList

protected float[][] clipTxList

The list of clip transforms currently valid while traversing

lastClip

protected int lastClip

Index to the next place to add items in the clipList

appearanceStack

protected OverrideRenderable[] appearanceStack

A stack used to control the appearance override nodes down the tree

lastAppearanceStack

protected int lastAppearanceStack

Index to the next place to add items in the fogStack

processedPBufferTextures

protected org.j3d.util.HashSet processedPBufferTextures

Collection of offscreen textures we've found this frame

activeParent

protected OffscreenCullable activeParent

The active parent scene of the scene we are processing. If we are processing the top level scene then this will be null

currentViewpointPath

protected java.util.ArrayList<Cullable> currentViewpointPath

Path to the current viewpoint

viewMatrix1

protected javax.vecmath.Matrix4f viewMatrix1

Matrix used for pre-computing the view stack

viewMatrix2

protected javax.vecmath.Matrix4f viewMatrix2

Matrix used for pre-computing the view stack

orientationMatrix

protected javax.vecmath.Matrix4f orientationMatrix

Rotation matrix for the orientation provided by user

screenOrientation

protected float[] screenOrientation

Storage variable for the screen orientation values

eyePoint

protected float[] eyePoint

Storage variable for the eye offset values

useOrientation

protected boolean useOrientation

Flag to say explicit screen orientation values have been provided

useEyePoint

protected boolean useEyePoint

Flag to say explicit eyepoint values have been provided

terminate

protected boolean terminate

Flag indicating a shutdown of the current processing is requested

layersTmp

protected LayerCullable[] layersTmp

Temporary variable for fetching layers from sub scenes

matrixUtils

protected org.j3d.util.MatrixUtils matrixUtils

Matrix utility code for doing inversions

errorReporter

protected org.j3d.util.ErrorReporter errorReporter

Local reporter to put errors in

Constructor Detail

BaseCullStage

public BaseCullStage(int numSurfaces)

Create a basic instance of this class with the list initial internal setup for the given number of renderable surfaces. The size is just an initial esstimate, and is used for optimisation purposes to prevent frequent array reallocations internally. As such, the number does not have to be perfect, just good enough.

Parameters:

numSurfaces - Total number of surfaces to prepare rendering for

Method Detail

cull

public void cull(RenderableRequestData otherData,
                 ProfilingData profilingData,
                 LayerCullable[] layers,
                 int numLayers)

Update and cull the scenegraph defined by a set of layers. This generates an ordered list of nodes to render. It will not return until the culling is complete.

Specified by:

cull in interface CullStage

Parameters:

otherData - data to be passed along unprocessed

profilingData - The timing and load data on each stage

layers - The collection of layers, in order, to render

numLayers - The number of valid layers to use

setCulledGeometryReceiver

public void setCulledGeometryReceiver(CulledGeometryReceiver sgr)

Register a reciever for the output of the sorter. If the value is null, it will clear the currently set receiver.

Specified by:

setCulledGeometryReceiver in interface GraphicsCullStage

Parameters:

sgr - The receiver instance to add or null

setOffscreenCheckEnabled

public void setOffscreenCheckEnabled(boolean state)

Set the flag for whether to check for offscreen textures or not. By default, this flag is set to true.

Specified by:

setOffscreenCheckEnabled in interface GraphicsCullStage

Parameters:

state - true if offscreen textures should be looked for

isOffscreenCheckEnabled

public boolean isOffscreenCheckEnabled()

Find out what the current offscreen check state is.

Specified by:

isOffscreenCheckEnabled in interface GraphicsCullStage

Returns:

true if the checking is being performed

setEyePointOffset

public void setEyePointOffset(float x,
                              float y,
                              float z)

Set the eyepoint offset from the centre position. This is used to model offset view frustums, such as multiple displays or a powerwall. This method will be called with the appropriate values from the RenderPipeline that this culler is inserted into.

Specified by:

setEyePointOffset in interface GraphicsCullStage

Parameters:

x - The x axis offset

y - The y axis offset

z - The z axis offset

setScreenOrientation

public void setScreenOrientation(float x,
                                 float y,
                                 float z,
                                 float a)
                          throws java.lang.IllegalArgumentException

Set the orientation of this screen relative to the user's normal view direction. The normal orientation of the screen is along the negative Z axis. This method provides and axis-angle reorientation of that direction to one that is facing the screen. Typically this will just involve a rotation around the Y axis of some amount (45 and 90 deg being the most common used in walls and caves). This method will be called with the appropriate values from the RenderPipeline that this culler is inserted into.

Specified by:

setScreenOrientation in interface GraphicsCullStage

Parameters:

x - The x axis component

y - The y axis component

z - The z axis component

a - The angle to rotate around the axis in radians

Throws:

java.lang.IllegalArgumentException - The length of the axis is zero

halt

public void halt()

Force a halt of the current processing. Any processing in progress should exit immediately. Used to abort the current scene processing due to application shutdown or complete scene replacement.

Specified by:

halt in interface CullStage

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 CullStage

Parameters:

reporter - The instance to use or null

cullScene

protected abstract void cullScene(RenderPassCullable scene,
                                  int subsceneId,
                                  int layerId,
                                  int viewIndex,
                                  int layerIndex)

Update and cull the scenegraph. This generates an ordered list of nodes to render. It will not return until the culling is complete.

Parameters:

scene - The scene instance to cull

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

layerIndex - The index of the layer within the viewport

cullScene2D

protected abstract void cullScene2D(RenderPassCullable scene,
                                    int subsceneId,
                                    int layerId,
                                    int viewIndex,
                                    int layerIndex)

Update and cull a 2D scenegraph. This generates an ordered list of nodes to render. It will not return until the culling is complete.

Parameters:

scene - The scene instance to cull

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

layerIndex - The index of the layer within the viewport

cullRenderPass

protected abstract void cullRenderPass(RenderPassCullable pass,
                                       int passNumber,
                                       int subsceneId,
                                       int layerId,
                                       int viewIndex,
                                       int layerIndex)

Update and cull the a single pass from a multipass rendering. This generates an ordered list of nodes to render in the same was as a normal scene, but with fewer items updated, such as only a single background for all passes. It will not return until the culling is complete.

Parameters:

pass - The rendering pass instance to cull

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

layerIndex - The index of the layer within the viewport

processLayer

protected void processLayer(LayerCullable layer,
                            int subsceneId,
                            int layerId)

Process the layers of a pbuffer texture source.

Parameters:

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

cullViewport

protected void cullViewport(ViewportCullable view,
                            int subsceneId,
                            int layerId,
                            int viewIndex)

Process a single viewport for culling.

Parameters:

view - The viewport instance to process now

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

cullSingleViewportLayer

protected void cullSingleViewportLayer(SceneCullable scene,
                                       int subsceneId,
                                       int layerId,
                                       int viewIndex,
                                       int layerIndex)

Cull through a multipass viewport layer.

Parameters:

scene - The scene instance to process

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

layerIndex - The index of the layer within the viewport

cullMultipassViewportLayer

protected void cullMultipassViewportLayer(SceneCullable scene,
                                          int subsceneId,
                                          int layerId,
                                          int viewIndex,
                                          int layerIndex)

Cull through a multipass viewport layer.

Parameters:

scene - The scene instance to process

subsceneId - The index of the subscene in the viewport output

layerId - The index of the layer in the output

viewIndex - The index of the viewport in the parent ViewportCollection

layerIndex - The index of the layer within the viewport

fillSingleEnvData

protected void fillSingleEnvData(SceneCullable scene,
                                 GraphicsEnvironmentData envData)

Take a simple scene and fill in a GraphicsEnvironmentData instance.

Parameters:

scene - The scene to take data from

envData - Data instance to copy it to

fill2DEnvData

protected void fill2DEnvData(SceneCullable scene,
                             GraphicsEnvironmentData envData)

Take a 2D scene and fill in a GraphicsEnvironmentData instance.

Parameters:

scene - The scene to take data from

envData - Data instance to copy it to

fillMultipassEnvData

protected void fillMultipassEnvData(SceneCullable scene,
                                    GraphicsEnvironmentData envData)

Take a simple scene and fill in a GraphicsEnvironmentData instance.

Parameters:

scene - The scene to take data from

envData - Data instance to copy it to

fillRenderPassEnvData

protected void fillRenderPassEnvData(RenderPassCullable pass,
                                     GraphicsEnvironmentData envData,
                                     BufferDetails bufferData)

Take a simple scene and fill in a GraphicsEnvironmentData instance.

Parameters:

pass - The render pass to take data from

envData - Data instance to copy it to

bufferData - The object to copy the extra buffer state to

checkForOffscreens

protected void checkForOffscreens(ShapeRenderable shape)

Check a shape node for the offscreen textures that may be present. If some are found, queue them up for processing.

Parameters:

shape - The object instance to process

cleanupOldRefs

protected void cleanupOldRefs()

Clean up the unused resources after the end of the cull process. This releases any references that are no longer needed, and may have been kept from the previous culling pass. This method is called just before the output is sent on to the sorting stage.

This base implementation cleans up the workLayers list. Derived classes that override this method for their own needs should also make sure to call this method too.

resizeCullList

protected final void resizeCullList(int cur_size)

Resize the list if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeOutputLists

protected final void resizeOutputLists()

Resize the list if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeOffscreenList

protected final void resizeOffscreenList()

Resize the list if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeLightList

protected final void resizeLightList()

Resize the list if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeClipList

protected final void resizeClipList()

Resize the list if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeStack

protected final void resizeStack()

Resize the transform stack if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeFogStack

protected final void resizeFogStack()

Resize the fog stack if needed. Marked as final in order to encourage the compiler to inline the code for faster execution

resizeAppearanceStack

protected final void resizeAppearanceStack()

Resize the appearance stack if needed. Marked as final in order to encourage the compiler to inline the code for faster execution