com.jme3.material
Class RenderState

java.lang.Object
  extended by com.jme3.material.RenderState
All Implemented Interfaces:
Savable, java.lang.Cloneable

public class RenderState
extends java.lang.Object
implements java.lang.Cloneable, Savable

RenderState specifies material rendering properties that cannot be controlled by a shader on a Material. The properties allow manipulation of rendering features such as depth testing, alpha blending, face culling, stencil operations, and much more.


Nested Class Summary
static class RenderState.BlendMode
          BlendMode specifies the blending operation to use.
static class RenderState.FaceCullMode
          FaceCullMode specifies the criteria for faces to be culled.
static class RenderState.StencilOperation
          StencilOperation specifies the stencil operation to use in a certain scenario as specified in setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)
static class RenderState.TestFunction
          TestFunction specifies the testing function for stencil test function and alpha test function.
 
Field Summary
static RenderState ADDITIONAL
          The ADDITIONAL render state is identical to the DEFAULT render state except that all apply values are set to false.
static RenderState DEFAULT
          The DEFAULT render state is the one used by default on all materials unless changed otherwise by the user.
static RenderState NULL
          The NULL render state is identical to the DEFAULT render state except that depth testing and face culling are disabled.
 
Constructor Summary
RenderState()
           
 
Method Summary
 RenderState clone()
          Create a clone of this RenderState
 int contentHashCode()
           
 RenderState copyMergedTo(RenderState additionalState, RenderState state)
          Merges this state and additionalState into the parameter state based on a specific criteria.
 boolean equals(java.lang.Object o)
          returns true if the given renderState is equall to this one
 float getAlphaFallOff()
          Retrieve the alpha falloff value.
 RenderState.StencilOperation getBackStencilDepthFailOperation()
          Retrieve the back depth test fail operation.
 RenderState.StencilOperation getBackStencilDepthPassOperation()
          Retrieve the back depth test pass operation.
 RenderState.TestFunction getBackStencilFunction()
          Retrieve the back stencil function.
 RenderState.StencilOperation getBackStencilStencilFailOperation()
          Retrieve the back stencil fail operation.
 RenderState.BlendMode getBlendMode()
          Retrieve the blend mode.
 RenderState.FaceCullMode getFaceCullMode()
          Retrieve the face cull mode.
 RenderState.StencilOperation getFrontStencilDepthFailOperation()
          Retrieve the front depth test fail operation.
 RenderState.StencilOperation getFrontStencilDepthPassOperation()
          Retrieve the front depth test pass operation.
 RenderState.TestFunction getFrontStencilFunction()
          Retrieve the front stencil function.
 RenderState.StencilOperation getFrontStencilStencilFailOperation()
          Retrieve the front stencil fail operation.
 float getPolyOffsetFactor()
          Retrieve the poly offset factor value.
 float getPolyOffsetUnits()
          Retrieve the poly offset units value.
 boolean isAlphaTest()
          Check if alpha test is enabled.
 boolean isApplyAlphaFallOff()
           
 boolean isApplyAlphaTest()
           
 boolean isApplyBlendMode()
           
 boolean isApplyColorWrite()
           
 boolean isApplyCullMode()
           
 boolean isApplyDepthTest()
           
 boolean isApplyDepthWrite()
           
 boolean isApplyPointSprite()
           
 boolean isApplyPolyOffset()
           
 boolean isApplyWireFrame()
           
 boolean isColorWrite()
          Check if color writing is enabled.
 boolean isDepthTest()
          Check if depth test is enabled.
 boolean isDepthWrite()
          Check if depth write is enabled.
 boolean isPointSprite()
          Check if point sprite mode is enabled
 boolean isPolyOffset()
          Check if polygon offset is enabled.
 boolean isStencilTest()
          Check if stencil test is enabled.
 boolean isWireframe()
          Check if wireframe mode is enabled.
 void read(JmeImporter im)
           
 void setAlphaFallOff(float alphaFallOff)
          Sets the alpha fall off value for alpha testing.
 void setAlphaTest(boolean alphaTest)
          Enable alpha testing.
 void setBlendMode(RenderState.BlendMode blendMode)
          Set the blending mode.
 void setColorWrite(boolean colorWrite)
          Enable writing color.
 void setDepthTest(boolean depthTest)
          Enable depth testing.
 void setDepthWrite(boolean depthWrite)
          Enable depth writing.
 void setFaceCullMode(RenderState.FaceCullMode cullMode)
          Set the face culling mode.
 void setPointSprite(boolean pointSprite)
          Enables point sprite mode.
 void setPolyOffset(float factor, float units)
          Offsets the on-screen z-order of the material's polygons, to combat visual artefacts like stitching, bleeding and z-fighting for overlapping polygons.
 void setStencil(boolean enabled, RenderState.StencilOperation _frontStencilStencilFailOperation, RenderState.StencilOperation _frontStencilDepthFailOperation, RenderState.StencilOperation _frontStencilDepthPassOperation, RenderState.StencilOperation _backStencilStencilFailOperation, RenderState.StencilOperation _backStencilDepthFailOperation, RenderState.StencilOperation _backStencilDepthPassOperation, RenderState.TestFunction _frontStencilFunction, RenderState.TestFunction _backStencilFunction)
          Enable stencil testing.
 void setWireframe(boolean wireframe)
          Enables wireframe rendering mode.
 java.lang.String toString()
           
 void write(JmeExporter ex)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT

public static final RenderState DEFAULT
The DEFAULT render state is the one used by default on all materials unless changed otherwise by the user.

It has the following properties:


NULL

public static final RenderState NULL
The NULL render state is identical to the DEFAULT render state except that depth testing and face culling are disabled.


ADDITIONAL

public static final RenderState ADDITIONAL
The ADDITIONAL render state is identical to the DEFAULT render state except that all apply values are set to false. This allows the ADDITIONAL render state to be combined with other state but only influencing values that were changed from the original.

Constructor Detail

RenderState

public RenderState()
Method Detail

write

public void write(JmeExporter ex)
           throws java.io.IOException
Specified by:
write in interface Savable
Throws:
java.io.IOException

read

public void read(JmeImporter im)
          throws java.io.IOException
Specified by:
read in interface Savable
Throws:
java.io.IOException

clone

public RenderState clone()
Create a clone of this RenderState

Overrides:
clone in class java.lang.Object
Returns:
Clone of this render state.

equals

public boolean equals(java.lang.Object o)
returns true if the given renderState is equall to this one

Overrides:
equals in class java.lang.Object
Parameters:
o - the renderState to compate to
Returns:
true if the renderStates are equal

setPointSprite

public void setPointSprite(boolean pointSprite)
Enables point sprite mode.

When point sprite is enabled, any meshes with the type of Mesh.Mode.Points will be rendered as 2D quads with texturing enabled. Fragment shaders can write to the gl_PointCoord variable to manipulate the texture coordinate for each pixel. The size of the 2D quad can be controlled by writing to the gl_PointSize variable in the vertex shader.

Parameters:
pointSprite - Enables Point Sprite mode.

setAlphaFallOff

public void setAlphaFallOff(float alphaFallOff)
Sets the alpha fall off value for alpha testing.

If the pixel's alpha value is greater than the alphaFallOff then the pixel will be rendered, otherwise the pixel will be discarded.

Parameters:
alphaFallOff - The alpha of all rendered pixels must be higher than this value to be rendered. This value should be between 0 and 1.
See Also:
setAlphaTest(boolean)

setAlphaTest

public void setAlphaTest(boolean alphaTest)
Enable alpha testing.

When alpha testing is enabled, all input pixels' alpha are compared to the constant alpha falloff. If the input alpha is greater than the falloff, the pixel will be rendered, otherwise it will be discarded.

Parameters:
alphaTest - Set to true to enable alpha testing.
See Also:
setAlphaFallOff(float)

setColorWrite

public void setColorWrite(boolean colorWrite)
Enable writing color.

When color write is enabled, the result of a fragment shader, the gl_FragColor, will be rendered into the color buffer (including alpha).

Parameters:
colorWrite - Set to true to enable color writing.

setFaceCullMode

public void setFaceCullMode(RenderState.FaceCullMode cullMode)
Set the face culling mode.

See the RenderState.FaceCullMode enum on what each value does. Face culling will project the triangle's points onto the screen and determine if the triangle is in counter-clockwise order or clockwise order. If a triangle is in counter-clockwise order, then it is considered a front-facing triangle, otherwise, it is considered a back-facing triangle.

Parameters:
cullMode - the face culling mode.

setBlendMode

public void setBlendMode(RenderState.BlendMode blendMode)
Set the blending mode.

When blending is enabled, (blendMode is not RenderState.BlendMode.Off) the input pixel will be blended with the pixel already in the color buffer. The blending operation is determined by the RenderState.BlendMode. For example, the RenderState.BlendMode.Additive will add the input pixel's color to the color already in the color buffer:
Result = Source Color + Destination Color

Parameters:
blendMode - The blend mode to use. Set to RenderState.BlendMode.Off to disable blending.

setDepthTest

public void setDepthTest(boolean depthTest)
Enable depth testing.

When depth testing is enabled, a pixel must pass the depth test before it is written to the color buffer. The input pixel's depth value must be less than or equal than the value already in the depth buffer to pass the depth test.

Parameters:
depthTest - Enable or disable depth testing.

setDepthWrite

public void setDepthWrite(boolean depthWrite)
Enable depth writing.

After passing the depth test, a pixel's depth value will be written into the depth buffer if depth writing is enabled.

Parameters:
depthWrite - True to enable writing to the depth buffer.

setWireframe

public void setWireframe(boolean wireframe)
Enables wireframe rendering mode.

When in wireframe mode, meshes rendered in triangle mode will not be solid, but instead, only the edges of the triangles will be rendered.

Parameters:
wireframe - True to enable wireframe mode.

setPolyOffset

public void setPolyOffset(float factor,
                          float units)
Offsets the on-screen z-order of the material's polygons, to combat visual artefacts like stitching, bleeding and z-fighting for overlapping polygons. Factor and units are summed to produce the depth offset. This offset is applied in screen space, typically with positive Z pointing into the screen. Typical values are (1.0f, 1.0f) or (-1.0f, -1.0f)

Parameters:
factor - scales the maximum Z slope, with respect to X or Y of the polygon
units - scales the minimum resolvable depth buffer value
See Also:
http://www.opengl.org/resources/faq/technical/polygonoffset.htm

setStencil

public void setStencil(boolean enabled,
                       RenderState.StencilOperation _frontStencilStencilFailOperation,
                       RenderState.StencilOperation _frontStencilDepthFailOperation,
                       RenderState.StencilOperation _frontStencilDepthPassOperation,
                       RenderState.StencilOperation _backStencilStencilFailOperation,
                       RenderState.StencilOperation _backStencilDepthFailOperation,
                       RenderState.StencilOperation _backStencilDepthPassOperation,
                       RenderState.TestFunction _frontStencilFunction,
                       RenderState.TestFunction _backStencilFunction)
Enable stencil testing.

Stencil testing can be used to filter pixels according to the stencil buffer. Objects can be rendered with some stencil operation to manipulate the values in the stencil buffer, then, other objects can be rendered to test against the values written previously.

Parameters:
enabled - Set to true to enable stencil functionality. If false all other parameters are ignored.
_frontStencilStencilFailOperation - Sets the operation to occur when a front-facing triangle fails the front stencil function.
_frontStencilDepthFailOperation - Sets the operation to occur when a front-facing triangle fails the depth test.
_frontStencilDepthPassOperation - Set the operation to occur when a front-facing triangle passes the depth test.
_backStencilStencilFailOperation - Set the operation to occur when a back-facing triangle fails the back stencil function.
_backStencilDepthFailOperation - Set the operation to occur when a back-facing triangle fails the depth test.
_backStencilDepthPassOperation - Set the operation to occur when a back-facing triangle passes the depth test.
_frontStencilFunction - Set the test function for front-facing triangles.
_backStencilFunction - Set the test function for back-facing triangles.

isStencilTest

public boolean isStencilTest()
Check if stencil test is enabled.

Returns:
True if stencil test is enabled.

getFrontStencilStencilFailOperation

public RenderState.StencilOperation getFrontStencilStencilFailOperation()
Retrieve the front stencil fail operation.

Returns:
the front stencil fail operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getFrontStencilDepthFailOperation

public RenderState.StencilOperation getFrontStencilDepthFailOperation()
Retrieve the front depth test fail operation.

Returns:
the front depth test fail operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getFrontStencilDepthPassOperation

public RenderState.StencilOperation getFrontStencilDepthPassOperation()
Retrieve the front depth test pass operation.

Returns:
the front depth test pass operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getBackStencilStencilFailOperation

public RenderState.StencilOperation getBackStencilStencilFailOperation()
Retrieve the back stencil fail operation.

Returns:
the back stencil fail operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getBackStencilDepthFailOperation

public RenderState.StencilOperation getBackStencilDepthFailOperation()
Retrieve the back depth test fail operation.

Returns:
the back depth test fail operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getBackStencilDepthPassOperation

public RenderState.StencilOperation getBackStencilDepthPassOperation()
Retrieve the back depth test pass operation.

Returns:
the back depth test pass operation.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getFrontStencilFunction

public RenderState.TestFunction getFrontStencilFunction()
Retrieve the front stencil function.

Returns:
the front stencil function.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getBackStencilFunction

public RenderState.TestFunction getBackStencilFunction()
Retrieve the back stencil function.

Returns:
the back stencil function.
See Also:
setStencil(boolean, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.StencilOperation, com.jme3.material.RenderState.TestFunction, com.jme3.material.RenderState.TestFunction)

getBlendMode

public RenderState.BlendMode getBlendMode()
Retrieve the blend mode.

Returns:
the blend mode.

isPointSprite

public boolean isPointSprite()
Check if point sprite mode is enabled

Returns:
True if point sprite mode is enabled.
See Also:
setPointSprite(boolean)

isAlphaTest

public boolean isAlphaTest()
Check if alpha test is enabled.

Returns:
True if alpha test is enabled.
See Also:
setAlphaTest(boolean)

getFaceCullMode

public RenderState.FaceCullMode getFaceCullMode()
Retrieve the face cull mode.

Returns:
the face cull mode.
See Also:
setFaceCullMode(com.jme3.material.RenderState.FaceCullMode)

isDepthTest

public boolean isDepthTest()
Check if depth test is enabled.

Returns:
True if depth test is enabled.
See Also:
setDepthTest(boolean)

isDepthWrite

public boolean isDepthWrite()
Check if depth write is enabled.

Returns:
True if depth write is enabled.
See Also:
setDepthWrite(boolean)

isWireframe

public boolean isWireframe()
Check if wireframe mode is enabled.

Returns:
True if wireframe mode is enabled.
See Also:
setWireframe(boolean)

isColorWrite

public boolean isColorWrite()
Check if color writing is enabled.

Returns:
True if color writing is enabled.
See Also:
setColorWrite(boolean)

getPolyOffsetFactor

public float getPolyOffsetFactor()
Retrieve the poly offset factor value.

Returns:
the poly offset factor value.
See Also:
setPolyOffset(float, float)

getPolyOffsetUnits

public float getPolyOffsetUnits()
Retrieve the poly offset units value.

Returns:
the poly offset units value.
See Also:
setPolyOffset(float, float)

isPolyOffset

public boolean isPolyOffset()
Check if polygon offset is enabled.

Returns:
True if polygon offset is enabled.
See Also:
setPolyOffset(float, float)

getAlphaFallOff

public float getAlphaFallOff()
Retrieve the alpha falloff value.

Returns:
the alpha falloff value.
See Also:
setAlphaFallOff(float)

isApplyAlphaFallOff

public boolean isApplyAlphaFallOff()

isApplyAlphaTest

public boolean isApplyAlphaTest()

isApplyBlendMode

public boolean isApplyBlendMode()

isApplyColorWrite

public boolean isApplyColorWrite()

isApplyCullMode

public boolean isApplyCullMode()

isApplyDepthTest

public boolean isApplyDepthTest()

isApplyDepthWrite

public boolean isApplyDepthWrite()

isApplyPointSprite

public boolean isApplyPointSprite()

isApplyPolyOffset

public boolean isApplyPolyOffset()

isApplyWireFrame

public boolean isApplyWireFrame()

contentHashCode

public int contentHashCode()

copyMergedTo

public RenderState copyMergedTo(RenderState additionalState,
                                RenderState state)
Merges this state and additionalState into the parameter state based on a specific criteria.

The criteria for this merge is the following:
For every given property, such as alpha test or depth write, check if it was modified from the original in the additionalState if it was modified, then copy the property from the additionalState into the parameter state, otherwise, copy the property from this into the parameter state. If additionalState is null, then no modifications are made and this is returned, otherwise, the parameter state is returned with the result of the merge.

Parameters:
additionalState - The additionalState, from which data is taken only if it was modified by the user.
state - Contains output of the method if additionalState is not null.
Returns:
state if additionalState is non-null, otherwise returns this

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object