org.j3d.aviatrix3d
Class BlendAttributes

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.NodeComponent
          org.j3d.aviatrix3d.BlendAttributes

All Implemented Interfaces:

java.lang.Comparable, AppearanceAttributeRenderable, ObjectRenderable, Renderable

public class BlendAttributes
extends NodeComponent
implements AppearanceAttributeRenderable

Describes attributes used for blending any drawing primitives.

The default blending mode is set up to mimic the defaults used by OpenGL. However, this class should only be used when the GL_ARB_imaging subset is available. This code automatically checks for it's existance and will disable calling itself if it detects the lack of existance.

Note: If you have semi-transparent objects that need blending, you do not need to provide an instance of this class. Aviatrix3D will internally handle the correct settings that you need, so there is no need to provide your own. Only use this when you want to blend objects with something different than the standard blending setup for non-transparent and transparent objects as it will remove this object from the normal transparency sorting processing and into a separate state.

Default Values

When intialised, this class follows the default OpenGL values for blending:

 Blend Equation:    EQ_FUNC_ADD
 RGB Source Mode:   BLEND_SRC_COLOR
 RGB Dest Mode:     BLEND_ONE_MINUS_SRC_COLOR
 Alpha Source Mode: BLEND_SRC_ALPHA
 Alpha Dest Mode:   BLEND_ONE_MINUS_SRC_ALPHA
 Separated Blend:   false
 Blend colour not set
 

Internationalisation Resource Names

• invalidAlphaDestMsg: Error message when the given function type does not match one of the available types.
• invalidBlendMsg: Error message when the given blend source type does not match one of the available types.
• invalidModeMsg: Error message when the given blend mode type does not match one of the available types.
• noImgSubsetMsg: Error message when the OpenGL does not support the ARB_imaging subset

Version:

$Revision: 1.21 $

Author:

Justin Couch

Field Summary

static int	BLEND_CONSTANT_ALPHA Set the blend factor to use the provided constant alpha value.The constant colour value is provide through the setBlendColour() method.
static int	BLEND_CONSTANT_COLOR Set the blend factor to use the provided constant colour.
static int	BLEND_DEST_ALPHA Set the blend factor to use the destination object's alpha value
static int	BLEND_DEST_COLOR Set the blend factor to use the destination object colour
static int	BLEND_ONE Set the blend factor to ones.
static int	BLEND_ONE_MINUS_CONSTANT_ALPHA Set the blend factor to use one minus the constant colour alpha value (1-c).
static int	BLEND_ONE_MINUS_CONSTANT_COLOR Set the blend factor to use one minus the constant colour (1-c).
static int	BLEND_ONE_MINUS_DEST_ALPHA Set the blend factor to use one minus the destination object alpha value (1-dest).
static int	BLEND_ONE_MINUS_DEST_COLOR Set the blend factor to use one minus the destination object colour (1-dest).
static int	BLEND_ONE_MINUS_SRC_ALPHA Set the blend factor to use one minus source object alpha value (1-src).
static int	BLEND_ONE_MINUS_SRC_COLOR Set the blend factor to use one minus source object colour (1-src).
static int	BLEND_SRC_ALPHA Set the blend factor to use the source object's alpha value
static int	BLEND_SRC_ALPHA_SATURATE Set the blend function to saturage the colour value using the alpha state.
static int	BLEND_SRC_COLOR Set the blend factor to use the source object colour
static int	BLEND_ZERO Set the blend factor to zeros.
static int	EQ_FUNC_ADD Set the blending equation to be CsS + CdD
static int	EQ_FUNC_MAX Set the blending equation to be max(CdD, CsS)
static int	EQ_FUNC_MIN Set the blending equation to be min(CdD, CsS)
static int	EQ_FUNC_SUBTRACT Set the blending equation to be CsS - CdD
static int	EQ_FUNC_SUBTRACT_REVERSE Set the blending equation to be CdD - CsS

Fields inherited from class org.j3d.aviatrix3d.NodeComponent

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.AppearanceAttributeRenderable

ALPHA_ATTRIBUTE, BLEND_ATTRIBUTE, DEPTH_ATTRIBUTE, LINE_ATTRIBUTE, POINT_ATTRIBUTE, POLYGON_ATTRIBUTE, STENCIL_ATTRIBUTE

Constructor Summary

BlendAttributes()
Constructs a attribute set with default values as specified above.

Method Summary

int	compareTo(BlendAttributes ba) Compares this object with the specified object for order.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
boolean	equals(BlendAttributes ba) Compares this object with the specified object to check for equivalence.
boolean	equals(java.lang.Object o) Compare this object for equality to the given object.
int	getAlphaDestinationBlendFactor() Request the currently set destination blend factor for the alpha component.
int	getAlphaSourceBlendFactor() Request the currently set source blend factor for the alpha component.
int	getAttributeType() Get the type this visual attribute represents.
void	getBlendColor(float[] col) Get the current blend colour.
int	getBlendEquation() Request the currently set blend equation
int	getDestinationBlendFactor() Request the currently set destination blend factor.
boolean	getSeparatedBlendFactors() Check to see the current state of whether separated blending is used or not.
int	getSourceBlendFactor() Request the currently set source blend factor.
boolean	isBlendingAvailable() Check to see if the code has detected the lack of the imaging subset.
void	postRender(javax.media.opengl.GL gl) Restore all openGL state to the given drawable.
void	render(javax.media.opengl.GL gl) Issue ogl commands needed for this component
void	setAlphaDestinationBlendFactor(int factor) Set the destination blend factor to use.
void	setAlphaSourceBlendFactor(int factor) Set the source blend factor to use.
void	setBlendColor(float r, float g, float b, float a) Set the blend colour to use for this texture.
void	setBlendEquation(int mode) Set the blend equation to use.
void	setDestinationBlendFactor(int factor) Set the destination blend factor to use.
void	setSeparatedBlendFactors(boolean state) Instruct the system whether to use separated RGB and Alpha blending functions.
void	setSourceBlendFactor(int factor) Set the source blend factor to use.

Methods inherited from class org.j3d.aviatrix3d.NodeComponent

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

BLEND_ZERO

public static final int BLEND_ZERO

Set the blend factor to zeros.

See Also:

Constant Field Values

BLEND_ONE

public static final int BLEND_ONE

Set the blend factor to ones.

See Also:

Constant Field Values

BLEND_SRC_COLOR

public static final int BLEND_SRC_COLOR

Set the blend factor to use the source object colour

See Also:

Constant Field Values

BLEND_ONE_MINUS_SRC_COLOR

public static final int BLEND_ONE_MINUS_SRC_COLOR

Set the blend factor to use one minus source object colour (1-src).

See Also:

Constant Field Values

BLEND_DEST_COLOR

public static final int BLEND_DEST_COLOR

Set the blend factor to use the destination object colour

See Also:

Constant Field Values

BLEND_ONE_MINUS_DEST_COLOR

public static final int BLEND_ONE_MINUS_DEST_COLOR

Set the blend factor to use one minus the destination object colour (1-dest).

See Also:

Constant Field Values

BLEND_SRC_ALPHA

public static final int BLEND_SRC_ALPHA

Set the blend factor to use the source object's alpha value

See Also:

Constant Field Values

BLEND_ONE_MINUS_SRC_ALPHA

public static final int BLEND_ONE_MINUS_SRC_ALPHA

Set the blend factor to use one minus source object alpha value (1-src).

See Also:

Constant Field Values

BLEND_DEST_ALPHA

public static final int BLEND_DEST_ALPHA

Set the blend factor to use the destination object's alpha value

See Also:

Constant Field Values

BLEND_ONE_MINUS_DEST_ALPHA

public static final int BLEND_ONE_MINUS_DEST_ALPHA

Set the blend factor to use one minus the destination object alpha value (1-dest).

See Also:

Constant Field Values

BLEND_CONSTANT_COLOR

public static final int BLEND_CONSTANT_COLOR

Set the blend factor to use the provided constant colour. The constant colour value is provide through the setBlendColour() method.

See Also:

Constant Field Values

BLEND_ONE_MINUS_CONSTANT_COLOR

public static final int BLEND_ONE_MINUS_CONSTANT_COLOR

Set the blend factor to use one minus the constant colour (1-c). The constant colour value is provide through the setBlendColour() method.

See Also:

Constant Field Values

BLEND_CONSTANT_ALPHA

public static final int BLEND_CONSTANT_ALPHA

Set the blend factor to use the provided constant alpha value.The constant colour value is provide through the setBlendColour() method.

See Also:

Constant Field Values

BLEND_ONE_MINUS_CONSTANT_ALPHA

public static final int BLEND_ONE_MINUS_CONSTANT_ALPHA

Set the blend factor to use one minus the constant colour alpha value (1-c). The constant colour value is provide through the setBlendColour() method.

See Also:

Constant Field Values

BLEND_SRC_ALPHA_SATURATE

public static final int BLEND_SRC_ALPHA_SATURATE

Set the blend function to saturage the colour value using the alpha state. The RGB value is calculated using the min(Asrc, 1 - Adest). The alpha value is treated as equivalent to GL_ONE. Can only be used as the source blend factor. An error will be generated if you try to use this for the destination factor.

See Also:

Constant Field Values

EQ_FUNC_ADD

public static final int EQ_FUNC_ADD

Set the blending equation to be C_sS + C_dD

See Also:

Constant Field Values

EQ_FUNC_SUBTRACT

public static final int EQ_FUNC_SUBTRACT

Set the blending equation to be C_sS - C_dD

See Also:

Constant Field Values

EQ_FUNC_SUBTRACT_REVERSE

public static final int EQ_FUNC_SUBTRACT_REVERSE

Set the blending equation to be C_dD - C_sS

See Also:

Constant Field Values

EQ_FUNC_MIN

public static final int EQ_FUNC_MIN

Set the blending equation to be min(C_dD, C_sS)

See Also:

Constant Field Values

EQ_FUNC_MAX

public static final int EQ_FUNC_MAX

Set the blending equation to be max(C_dD, C_sS)

See Also:

Constant Field Values

Constructor Detail

BlendAttributes

public BlendAttributes()

Constructs a attribute set with default values as specified above.

Method Detail

getAttributeType

public int getAttributeType()

Get the type this visual attribute represents.

Specified by:

getAttributeType in interface AppearanceAttributeRenderable

Returns:

One of the _ATTRIBUTE constants

render

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

Issue ogl commands needed for this component

Specified by:

render in interface ObjectRenderable

Parameters:

gl - The gl context to draw with

postRender

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

Restore all openGL state to the given drawable. Does nothing as it assumes the system will disable blending outside of this class.

Specified by:

postRender in interface ObjectRenderable

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

setSourceBlendFactor

public void setSourceBlendFactor(int factor)
                          throws InvalidWriteTimingException

Set the source blend factor to use. Used for both non-separated blending and the RGB component when separated.

Parameters:

factor - The value to set for the factor

Throws:

java.lang.IllegalArgumentException - The blend factor is not one of the permitted types

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

getSourceBlendFactor

public int getSourceBlendFactor()

Request the currently set source blend factor.

Returns:

One of the BLEND_* constant values

setDestinationBlendFactor

public void setDestinationBlendFactor(int factor)
                               throws InvalidWriteTimingException

Set the destination blend factor to use. Used for both non-separated blending and the RGB component when separated.

Parameters:

factor - The value to set for the factor

Throws:

java.lang.IllegalArgumentException - The blend factor is not one of the permitted types or is SRC_ALPHA_SATURATED

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

getDestinationBlendFactor

public int getDestinationBlendFactor()

Request the currently set destination blend factor.

Returns:

One of the BLEND_* constant values

setAlphaSourceBlendFactor

public void setAlphaSourceBlendFactor(int factor)
                               throws InvalidWriteTimingException

Set the source blend factor to use. Only used for seperated blending mode's alpha component. If non-separated mode is used, this setting is ignored.

Parameters:

factor - The value to set for the factor

Throws:

java.lang.IllegalArgumentException - The blend factor is not one of the permitted types

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

getAlphaSourceBlendFactor

public int getAlphaSourceBlendFactor()

Request the currently set source blend factor for the alpha component.

Returns:

One of the BLEND_* constant values

setAlphaDestinationBlendFactor

public void setAlphaDestinationBlendFactor(int factor)
                                    throws InvalidWriteTimingException

Set the destination blend factor to use. Only used for seperated blending mode's alpha component. If non-separated mode is used, this setting is ignored.

Parameters:

factor - The value to set for the factor

Throws:

java.lang.IllegalArgumentException - The blend factor is not one of the permitted types or is SRC_ALPHA_SATURATED

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

getAlphaDestinationBlendFactor

public int getAlphaDestinationBlendFactor()

Request the currently set destination blend factor for the alpha component.

Returns:

One of the BLEND_* constant values

setSeparatedBlendFactors

public void setSeparatedBlendFactors(boolean state)
                              throws InvalidWriteTimingException

Instruct the system whether to use separated RGB and Alpha blending functions. By default this is not enabled, but may be turned on or off using this method.

Parameters:

state - True to enable the use of separate RGB and alpha blending

Throws:

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

setBlendEquation

public void setBlendEquation(int mode)

Set the blend equation to use. By default, after multiplying the source color by the source blend factor and the destination color by the destination blend factor, the two values are then added together to get the final color. If you want to use other operation besides addition, this function needs to be called. Available blending equations and their descriptions are listed below.

EQ_FUNC_ADD: Set the blending equation to be C_sS + C_dD EQ_FUNC_SUBTRACT: Set the blending equation to be C_sS - C_dD EQ_FUNC_SUBTRACT_REVERSE: Set the blending equation to be C_dD - C_sS EQ_FUNC_MIN: Set the blending equation to be min(C_dD, C_sS) EQ_FUNC_MAX: Set the blending equation to be max(C_dD, C_sS)

Parameters:

mode - Blending equation mode

Throws:

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

getBlendEquation

public int getBlendEquation()

Request the currently set blend equation

Returns:

Blend equation value

getSeparatedBlendFactors

public boolean getSeparatedBlendFactors()

Check to see the current state of whether separated blending is used or not.

Returns:

true if separated RGB and Alpha blending is used

setBlendColor

public void setBlendColor(float r,
                          float g,
                          float b,
                          float a)
                   throws InvalidWriteTimingException

Set the blend colour to use for this texture. Blend is a 4-component colour value.

Parameters:

r - The red component of the blend colour

g - The green component of the blend colour

b - The blue component of the blend colour

a - The alpha component of the blend colour

Throws:

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

getBlendColor

public void getBlendColor(float[] col)

Get the current blend colour. If it hasn't been set previously, the call is ignored.

Parameters:

col - An array to copy the colour in, in RGBA format

compareTo

public int compareTo(BlendAttributes ba)

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:

ba - The attributes instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(BlendAttributes ba)

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

Parameters:

ba - The attributes instance to be compared

Returns:

true if the objects represent identical values

isBlendingAvailable

public boolean isBlendingAvailable()

Check to see if the code has detected the lack of the imaging subset. This call will always return false until the first time an instance of this class has been rendered. After that time, the real answer is known.

Returns:

true if the blending operations are allowed