Aviatrix3D
2.0 Dev

org.j3d.aviatrix3d.pipeline.graphics
Class BaseCullStage

java.lang.Object
  extended byorg.j3d.aviatrix3d.pipeline.graphics.BaseCullStage
All Implemented Interfaces:
CullStage, GraphicsCullStage
Direct Known Subclasses:
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.11 $
Author:
Justin Couch

Field Summary
protected  PBufferTextureSource activeParent
          The active parent scene of the scene we are processing.
protected  boolean checkOffscreens
          If set, recurse into Shape3Ds looking for offscreen textures
protected  ClipPlane[] clipList
          The list of clip plane nodes currently valid while traversing.
protected  float[][] clipTxList
          The list of clip transforms currently valid while traversing
protected  TransformGroup[] currentViewpointPath
          Path to the current viewpoint
protected  float[] eyePoint
          Storage variable for the eye offset values
protected  Fog[] fogStack
          A stack used to control the depth of the fog nodes down the tree
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  int[] layerCounts
          List of the final layers that are to be passed to the output
protected  Layer[] 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  Light[] 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  MatrixUtils matrixUtils
          Matrix utility code for doing inversions
protected  javax.vecmath.Matrix4f orientationMatrix
          Rotation matrix for the orientation provided by user
protected  ViewportCollection[][] outputLayers
          List of the final layers that are to be passed to the output
protected  SceneGraphObject[][] outputSceneParents
          List of valid subscene parents as we process them
protected  PBufferTextureSource[] pendingParents
          Buffer list of sub scenes that still need processing
protected  PBufferTextureSource[] pendingSubscenes
          Buffer list of sub scenes that still need processing
protected  HashSet processedPBufferTextures
          Collection of offscreen textures we've found this frame
protected  CulledGeometryReceiver receiver
          Handler for the output
protected  float[] screenOrientation
          Storage variable for the screen orientation values
protected static java.lang.String SHARED_BG_MSG
          Message when setting the active background if it contains a shared parent
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  TextureUnit[] textureUnits
          Temp used to get texture units when looking for offscreen textures.
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  SceneGraphObject[][] 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  HashSet visitedNodes
          Collection of textures we've found for the current parent texture
protected  GraphicsCullOutputDetails[] workCullList
          List that is being used to fill values into
 
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(Shape3D shape, int buffer)
          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(Layer[] layers, int numLayers, int buffer)
          Update and cull the scenegraph defined by a set of layers.
protected  void cull2DLayer(Layer2D layer, int subsceneId, int layerId, int buffer)
          Local internal method to process a single Layer2D instance.
protected  void cullCompositeLayer(CompositeLayer layer, int subsceneId, int layerId, int buffer)
          Local internal method to process a single CompositeLayer instance.
protected  void cullCompositeViewport(CompositeViewport viewport, int subsceneId, int layerId, int viewIndex, int buffer)
          Cull a composite viewport instance.
protected  void cullMultipassViewport(MultipassViewport viewport, int subsceneId, int layerId, int viewIndex, int buffer)
          Cull through a simple viewport instance.
protected  void cullMultipassViewportLayer(MultipassScene scene, int subsceneId, int layerId, int viewIndex, int layerIndex, int buffer)
          Cull through a simple viewport instance.
protected abstract  void cullRenderPass(RenderPass pass, int passNumber, int subsceneId, int layerId, int viewIndex, int layerIndex, int buffer)
          Update and cull the a single pass from a multipass rendering.
protected abstract  void cullScene(SimpleScene scene, int subsceneId, int layerId, int viewIndex, int layerIndex, int buffer)
          Update and cull the scenegraph.
protected  void cullSimpleLayer(SimpleLayer layer, int subsceneId, int layerId, int buffer)
          Local internal method to process a single SimpleLayer instance.
protected  void cullSimpleViewport(SimpleViewport viewport, int subsceneId, int layerId, int viewIndex, int buffer)
          Cull through a simple viewport instance.
protected abstract  int cullSingle(Group node, int buffer)
          Update and cull the scenegraph of a single node without doing any other processing.
protected  void cullViewport(Viewport view, int subsceneId, int layerId, int viewIndex, int buffer)
          Process a single viewport for culling.
protected  void fillEnvData(MultipassScene scene, GraphicsEnvironmentData envData, int buffer)
          Take a simple scene and fill in a GraphicsEnvironmentData instance.
protected  void fillEnvData(RenderPass pass, GraphicsEnvironmentData envData, BufferDetails bufferData, int buffer)
          Take a simple scene and fill in a GraphicsEnvironmentData instance.
protected  void fillEnvData(SimpleScene scene, GraphicsEnvironmentData envData, int buffer)
          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 processSubsceneLayers(Layer[] layers, int subsceneId, int numLayers, int buffer)
          Process the layers of a pbuffer texture source.
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 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

SHARED_BG_MSG

protected static final java.lang.String SHARED_BG_MSG
Message when setting the active background 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 PBufferTextureSource[] pendingSubscenes
Buffer list of sub scenes that still need processing


pendingParents

protected PBufferTextureSource[] pendingParents
Buffer list of sub scenes that still need processing


lastSubscene

protected int lastSubscene
Index of the last subscene in the list


outputLayers

protected ViewportCollection[][] outputLayers
List of the final layers that are to be passed to the output


layerCounts

protected int[] layerCounts
List of the final layers that are to be passed to the output


lastOutputLayer

protected int lastOutputLayer
Index of the the next layer output


validSceneParents

protected SceneGraphObject[][] validSceneParents
List of valid subscene parents as we process them


outputSceneParents

protected SceneGraphObject[][] 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 Fog[] 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 Light[] 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 ClipPlane[] 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


textureUnits

protected TextureUnit[] textureUnits
Temp used to get texture units when looking for offscreen textures.


processedPBufferTextures

protected HashSet processedPBufferTextures
Collection of offscreen textures we've found this frame


visitedNodes

protected HashSet visitedNodes
Collection of textures we've found for the current parent texture


receiver

protected CulledGeometryReceiver receiver
Handler for the output


activeParent

protected PBufferTextureSource activeParent
The active parent scene of the scene we are processing.


currentViewpointPath

protected TransformGroup[] 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 Layer[] layersTmp
Temporary variable for fetching layers from sub scenes


matrixUtils

protected MatrixUtils matrixUtils
Matrix utility code for doing inversions

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(Layer[] layers,
                 int numLayers,
                 int buffer)
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:
layers - The collection of layers, in order, to render
numLayers - The number of valid layers to use
buffer - The buffer ID to use to output the data to when multi-threaded

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

cullScene

protected abstract void cullScene(SimpleScene scene,
                                  int subsceneId,
                                  int layerId,
                                  int viewIndex,
                                  int layerIndex,
                                  int buffer)
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
buffer - The buffer ID to use to output the data to when multi-threaded

cullRenderPass

protected abstract void cullRenderPass(RenderPass pass,
                                       int passNumber,
                                       int subsceneId,
                                       int layerId,
                                       int viewIndex,
                                       int layerIndex,
                                       int buffer)
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
buffer - The buffer ID to use to output the data to when multi-threaded

cullSingle

protected abstract int cullSingle(Group node,
                                  int buffer)
Update and cull the scenegraph of a single node without doing any other processing. This generates an ordered list of nodes to render. It will not return until the culling is complete.

Parameters:
node - The root node to start the cull from
buffer - The buffer ID to use to output the data to when multi-threaded
Returns:
The index of the last item on the cull list

cullSimpleLayer

protected void cullSimpleLayer(SimpleLayer layer,
                               int subsceneId,
                               int layerId,
                               int buffer)
Local internal method to process a single SimpleLayer instance.

Parameters:
layer - The layer instance to process
subsceneId - The index of the subscene in the viewport output
layerId - The index of the layer in the output
buffer - The id of the buffer to process for this round

cullCompositeLayer

protected void cullCompositeLayer(CompositeLayer layer,
                                  int subsceneId,
                                  int layerId,
                                  int buffer)
Local internal method to process a single CompositeLayer instance.

Parameters:
layer - The layer instance to process
subsceneId - The index of the subscene in the viewport output
layerId - The index of the layer in the output
buffer - The id of the buffer to process for this round

cull2DLayer

protected void cull2DLayer(Layer2D layer,
                           int subsceneId,
                           int layerId,
                           int buffer)
Local internal method to process a single Layer2D instance.

Parameters:
layer - The layer instance to process
subsceneId - The index of the subscene in the viewport output
layerId - The index of the layer in the output
buffer - The id of the buffer to process for this round

cullViewport

protected void cullViewport(Viewport view,
                            int subsceneId,
                            int layerId,
                            int viewIndex,
                            int buffer)
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
buffer - The id of the buffer to process for this round

cullCompositeViewport

protected void cullCompositeViewport(CompositeViewport viewport,
                                     int subsceneId,
                                     int layerId,
                                     int viewIndex,
                                     int buffer)
Cull a composite viewport instance. A composite viewport has a number of layers to work through. Each layer is held to the size of the viewport.

Parameters:
viewport - The viewport 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
buffer - The id of the buffer to process for this round

cullSimpleViewport

protected void cullSimpleViewport(SimpleViewport viewport,
                                  int subsceneId,
                                  int layerId,
                                  int viewIndex,
                                  int buffer)
Cull through a simple viewport instance. A simple viewport only has a single layer, with the scene directly handled.

Parameters:
viewport - The viewport 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
buffer - The id of the buffer to process for this round

cullMultipassViewport

protected void cullMultipassViewport(MultipassViewport viewport,
                                     int subsceneId,
                                     int layerId,
                                     int viewIndex,
                                     int buffer)
Cull through a simple viewport instance. A simple viewport only has a single layer, with the scene directly handled.

Parameters:
viewport - The viewport 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
buffer - The id of the buffer to process for this round

cullMultipassViewportLayer

protected void cullMultipassViewportLayer(MultipassScene scene,
                                          int subsceneId,
                                          int layerId,
                                          int viewIndex,
                                          int layerIndex,
                                          int buffer)
Cull through a simple viewport instance. A simple viewport only has a single layer, with the scene directly handled.

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
buffer - The id of the buffer to process for this round

processSubsceneLayers

protected void processSubsceneLayers(Layer[] layers,
                                     int subsceneId,
                                     int numLayers,
                                     int buffer)
Process the layers of a pbuffer texture source.

Parameters:
subsceneId - The index of the subscene in the viewport output

fillEnvData

protected void fillEnvData(SimpleScene scene,
                           GraphicsEnvironmentData envData,
                           int buffer)
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
buffer - The buffer ID to use to output the data to when multi-threaded

fillEnvData

protected void fillEnvData(MultipassScene scene,
                           GraphicsEnvironmentData envData,
                           int buffer)
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
buffer - The buffer ID to use to output the data to when multi-threaded

fillEnvData

protected void fillEnvData(RenderPass pass,
                           GraphicsEnvironmentData envData,
                           BufferDetails bufferData,
                           int buffer)
Take a simple scene and fill in a GraphicsEnvironmentData instance.

Parameters:
envData - Data instance to copy it to
buffer - The buffer ID to use to output the data to when multi-threaded

checkForOffscreens

protected void checkForOffscreens(Shape3D shape,
                                  int buffer)
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
buffer - The id of the buffer to process for this round

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


Aviatrix3D
2.0 Dev

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