org.j3d.aviatrix3d
Class StencilBufferState

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.BufferState
          org.j3d.aviatrix3d.StencilBufferState

All Implemented Interfaces:

java.lang.Comparable, BufferStateRenderable, Renderable

public class StencilBufferState
extends BufferState
implements BufferStateRenderable

Describes attributes used when interacting with the stencil buffer.

Including this state class in the global setup automatically enables stencil testing and the stencil buffer.

The default setup for this class is:

• Compare Mask: ~0
• Write Mask: ~0
• Reference Value: 0
• Stencil Function: FUNCTION_ALWAYS
• Fail Operation: STENCIL_KEEP
• Depth Fail Operation = STENCIL_KEEP
• Depth Pass Operation = STENCIL_KEEP

Internationalisation Resource Names

• invalidStencilFunctionMsg: Error message when the given function type does not match one of the available types.
• invalidStencilOpMsg: Error message when the given operation type does not match one of the available types.

Version:

$Revision: 2.7 $

Author:

Justin Couch

Field Summary

static int	FUNCTION_ALWAYS Comparison function that always passes.
static int	FUNCTION_EQUAL Comparison function that passes if (ref & mask) == (stencil & mask).
static int	FUNCTION_GREATER Comparison function that passes if (ref & mask) > (stencil & mask).
static int	FUNCTION_GREATER_OR_EQUAL Comparison function that passes if (ref & mask) >= (stencil & mask).
static int	FUNCTION_LESS Comparison function that passes if (ref & mask) < (stencil & mask).
static int	FUNCTION_LESS_OR_EQUAL Comparison function that passes if (ref & mask) <= (stencil & mask).
static int	FUNCTION_NEVER Comparison function that always fails.
static int	FUNCTION_NOTEQUAL Comparison function that passes if (ref & mask) not equal to (stencil & mask).
static short	STENCIL_DECREMENT When the stencil function matches, decrement the stencil value.
static short	STENCIL_INCREMENT When the stencil function matches, increment the stencil value.
static short	STENCIL_INVERT When the stencil function matches, bitwise invert the stencil value.
static short	STENCIL_KEEP When the stencil function matches, keep the current stencil value.
static short	STENCIL_REPLACE When the stencil function matches, set the stencil value to the reference value.
static short	STENCIL_ZERO When the stencil function matches, set the stencil value to zero.

Fields inherited from class org.j3d.aviatrix3d.BufferState

lastParent, liveCount, parentList

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.rendering.BufferStateRenderable

ACCUMULATION_BUFFER, COLOR_BUFFER, DEPTH_BUFFER, GENERAL_BUFFER, STENCIL_BUFFER

Constructor Summary

StencilBufferState()
Constructs a state set with default values.

Method Summary

boolean	checkClearBufferState() Check to see if this buffer should be cleared at the start of this run.
void	clearBufferState(javax.media.opengl.GL gl) Restore all state to the default values.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
int	compareTo(StencilBufferState sbs) Compares this object with the specified object for order.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
boolean	equals(StencilBufferState sbs) Compares this object with the specified object to check for equivalence.
int	getBufferBitMask() Get the GL buffer bit flag that this state class represents.
int	getBufferType() Get the type of buffer this state represents.
int	getClearMask() Get the current function comparison mask.
int	getDepthFailOperation() Get the current operation used when the stencil test passes, but depth test fails.
int	getDepthPassOperation() Get the current operation used when the stencil and depth tests pass.
int	getFunctionCompareMask() Get the current function comparison mask.
int	getFunctionReferenceValue() Get the current stencil reference value for use in the stencil function setup.
int	getStencilFailOperation() Get the current function comparison mask.
int	getStencilFunction() Get the function type used when the stencil and depth tests pass.
int	getStencilWriteMask() Get the current write mask.
void	setBufferState(javax.media.opengl.GL gl) Issue ogl commands needed for this buffer to set the initial state, including the initial enabling.
void	setClearBufferState(boolean clear) Set the flag for whether the buffer state should be cleared when this state object is executed.
void	setClearMask(int mask) Set the bitmask used during the clear of the buffer.
void	setDepthFailOperation(int op) Set the operation that should be performed if the stencil test passes but the depth test fails.
void	setDepthPassOperation(int op) Set the operation that should be performed if the stencil and depth tests pass.
void	setFunctionCompareMask(int mask) Set the bitmask used for the stencil comparison operation.
void	setFunctionReferenceValue(int value) Set the reference value used for the stencil comparison operation.
void	setStencilFailOperation(int op) Set the operation that should be performed if the stencil test fails.
void	setStencilFunction(int func) Set the operation that should be performed if the stencil and depth tests pass.
void	setStencilWriteMask(int mask) Set the bitmask used for the stencil write operation.
void	updateBufferState(javax.media.opengl.GL gl) Issue ogl commands needed for this component to change the state, assuming that it is already enabled.

Methods inherited from class org.j3d.aviatrix3d.BufferState

addParent, getParents, numParents, removeParent

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicChild, checkForCyclicParent, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setLive, setUpdateHandler, setUserData

Methods inherited from class java.lang.Object

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

Field Detail

STENCIL_INCREMENT

public static final short STENCIL_INCREMENT

When the stencil function matches, increment the stencil value.

See Also:

Constant Field Values

STENCIL_DECREMENT

public static final short STENCIL_DECREMENT

When the stencil function matches, decrement the stencil value.

See Also:

Constant Field Values

STENCIL_KEEP

public static final short STENCIL_KEEP

When the stencil function matches, keep the current stencil value.

See Also:

Constant Field Values

STENCIL_INVERT

public static final short STENCIL_INVERT

When the stencil function matches, bitwise invert the stencil value.

See Also:

Constant Field Values

STENCIL_ZERO

public static final short STENCIL_ZERO

When the stencil function matches, set the stencil value to zero.

See Also:

Constant Field Values

STENCIL_REPLACE

public static final short STENCIL_REPLACE

When the stencil function matches, set the stencil value to the reference value.

See Also:

Constant Field Values

FUNCTION_NEVER

public static final int FUNCTION_NEVER

Comparison function that always fails.

See Also:

Constant Field Values

FUNCTION_LESS

public static final int FUNCTION_LESS

Comparison function that passes if (ref & mask) < (stencil & mask).

See Also:

Constant Field Values

FUNCTION_LESS_OR_EQUAL

public static final int FUNCTION_LESS_OR_EQUAL

Comparison function that passes if (ref & mask) <= (stencil & mask).

See Also:

Constant Field Values

FUNCTION_GREATER

public static final int FUNCTION_GREATER

Comparison function that passes if (ref & mask) > (stencil & mask).

See Also:

Constant Field Values

FUNCTION_GREATER_OR_EQUAL

public static final int FUNCTION_GREATER_OR_EQUAL

Comparison function that passes if (ref & mask) >= (stencil & mask).

See Also:

Constant Field Values

FUNCTION_EQUAL

public static final int FUNCTION_EQUAL

Comparison function that passes if (ref & mask) == (stencil & mask).

See Also:

Constant Field Values

FUNCTION_NOTEQUAL

public static final int FUNCTION_NOTEQUAL

Comparison function that passes if (ref & mask) not equal to (stencil & mask).

See Also:

Constant Field Values

FUNCTION_ALWAYS

public static final int FUNCTION_ALWAYS

Comparison function that always passes.

See Also:

Constant Field Values

Constructor Detail

StencilBufferState

public StencilBufferState()

Constructs a state set with default values.

Method Detail

getBufferType

public int getBufferType()

Get the type of buffer this state represents.

Specified by:

getBufferType in interface BufferStateRenderable

Returns:

One of the _BUFFER constants

getBufferBitMask

public int getBufferBitMask()

Get the GL buffer bit flag that this state class represents. Used for bulk clearing all the states at once.

Specified by:

getBufferBitMask in interface BufferStateRenderable

Returns:

The bit state constant for Stencil Buffers

checkClearBufferState

public boolean checkClearBufferState()

Check to see if this buffer should be cleared at the start of this run. If it should be, add the bit mask from this state to the global list.

Specified by:

checkClearBufferState in interface BufferStateRenderable

Returns:

true if the state should be cleared

setBufferState

public void setBufferState(javax.media.opengl.GL gl)

Issue ogl commands needed for this buffer to set the initial state, including the initial enabling.

Specified by:

setBufferState in interface BufferStateRenderable

Parameters:

gl - The gl context to draw with

updateBufferState

public void updateBufferState(javax.media.opengl.GL gl)

Issue ogl commands needed for this component to change the state, assuming that it is already enabled.

Specified by:

updateBufferState in interface BufferStateRenderable

Parameters:

gl - The gl context to draw with

clearBufferState

public void clearBufferState(javax.media.opengl.GL gl)

Restore all state to the default values.

Specified by:

clearBufferState in interface BufferStateRenderable

Parameters:

gl - The gl context to draw with

compareTo

public int compareTo(java.lang.Object o)
              throws java.lang.ClassCastException

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - The objec to be compared

Returns:

-1, 0 or 1 depending on order

Throws:

java.lang.ClassCastException - The specified object's type prevents it from being compared to this Object

equals

public boolean equals(java.lang.Object o)

Compare this object for equality to the given object.

Specified by:

equals in interface Renderable

Overrides:

equals in class java.lang.Object

Parameters:

o - The object to be compared

Returns:

True if these represent the same values

setClearBufferState

public void setClearBufferState(boolean clear)
                         throws InvalidWriteTimingException

Set the flag for whether the buffer state should be cleared when this state object is executed.

Parameters:

clear - True if the buffer should be cleared when this is the first state to be used in the current operation

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

setClearMask

public void setClearMask(int mask)
                  throws InvalidWriteTimingException

Set the bitmask used during the clear of the buffer. Note that the the mask will only support the number of bits defined by the current hardware. Flags above the number of supported bit planes are ignored.

Parameters:

mask - The bit mask of plane values to set during clear

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getClearMask

public int getClearMask()

Get the current function comparison mask.

Returns:

An integer bit flag.

setFunctionCompareMask

public void setFunctionCompareMask(int mask)
                            throws InvalidWriteTimingException

Set the bitmask used for the stencil comparison operation. Note that the the mask will only support the number of bits defined by the current hardware. Flags above the number of supported bit planes are ignored.

Parameters:

mask - The bit mask of planes to compare

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getFunctionCompareMask

public int getFunctionCompareMask()

Get the current function comparison mask.

Returns:

An integer bit flag.

setStencilWriteMask

public void setStencilWriteMask(int mask)
                         throws InvalidWriteTimingException

Set the bitmask used for the stencil write operation. Note that the the mask will only support the number of bits defined by the current hardware. Flags above the number of supported bit planes are ignored.

Parameters:

mask - The bit mask of planes to write when operations succeed

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getStencilWriteMask

public int getStencilWriteMask()

Get the current write mask.

Returns:

An integer bit flag.

setFunctionReferenceValue

public void setFunctionReferenceValue(int value)
                               throws InvalidWriteTimingException

Set the reference value used for the stencil comparison operation.

Parameters:

value - A value to compare for the depth testing

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getFunctionReferenceValue

public int getFunctionReferenceValue()

Get the current stencil reference value for use in the stencil function setup.

Returns:

An integer bit flag.

setStencilFailOperation

public void setStencilFailOperation(int op)
                             throws java.lang.IllegalArgumentException,
                                    InvalidWriteTimingException

Set the operation that should be performed if the stencil test fails. This should be one of the STENCIL_ constants at the top of this class.

Parameters:

op - One of the STENCIL_ constants

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

java.lang.IllegalArgumentException - The operation value was not one of the valid types.

getStencilFailOperation

public int getStencilFailOperation()

Get the current function comparison mask.

Returns:

An integer bit flag.

setDepthFailOperation

public void setDepthFailOperation(int op)
                           throws java.lang.IllegalArgumentException,
                                  InvalidWriteTimingException

Set the operation that should be performed if the stencil test passes but the depth test fails. This should be one of the STENCIL_ constants at the top of this class.

Parameters:

op - One of the STENCIL_ constants

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

java.lang.IllegalArgumentException - The operation value was not one of the valid types.

getDepthFailOperation

public int getDepthFailOperation()

Get the current operation used when the stencil test passes, but depth test fails.

Returns:

One of the STENCIL_ constants

setDepthPassOperation

public void setDepthPassOperation(int op)
                           throws java.lang.IllegalArgumentException,
                                  InvalidWriteTimingException

Set the operation that should be performed if the stencil and depth tests pass. This should be one of the STENCIL_ constants at the top of this class.

Parameters:

op - One of the STENCIL_ constants

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

java.lang.IllegalArgumentException - The operation value was not one of the valid types.

getDepthPassOperation

public int getDepthPassOperation()

Get the current operation used when the stencil and depth tests pass.

Returns:

One of the STENCIL_ constants

setStencilFunction

public void setStencilFunction(int func)
                        throws java.lang.IllegalArgumentException,
                               InvalidWriteTimingException

Set the operation that should be performed if the stencil and depth tests pass. This should be one of the FUNCTION_ constants at the top of this class.

Parameters:

func - One of the FUNCTION_ constants

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

java.lang.IllegalArgumentException - The operation value was not one of the valid types.

getStencilFunction

public int getStencilFunction()

Get the function type used when the stencil and depth tests pass.

Returns:

One of the FUNCTION constants

compareTo

public int compareTo(StencilBufferState sbs)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

sbs - The attributes instance to be comsbsred

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(StencilBufferState sbs)

Compares this object with the specified object to check for equivalence.

Parameters:

sbs - The attributes instance to be compared

Returns:

true if the objects represent identical values