Aviatrix3D
2.1.0

org.j3d.aviatrix3d.pipeline.graphics
Class BaseCullStage

java.lang.Object
  extended by 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


Aviatrix3D
2.1.0

Latest Info from http://aviatrix3d.j3d.org/
Copyright © 2003 - 2009 j3d.org