javax.microedition.m3d
Class CompositingMode

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.CompositingMode

public class CompositingMode

extends Object3D

An Appearance component encapsulating per-pixel compositing attributes.

Depth offset is a constant value that is added to the depth (Z) value of a pixel prior to depth test and depth write. This is to prevent a phenomenon known as Z fighting, that sometimes occurs when a polygon lies roughly in the plane of another polygon in camera space and overlaps with that polygon in screen space. Due to the finite resolution of any depth buffer, the two polygons may intersect each other seemingly at random. Depth offset has no effect if depth buffering is disabled.

Blending combines the incoming fragment's R, G, B, and A values with the R, G, B, and A values stored in the frame buffer at the incoming fragment's location.

The table below defines the available blending modes, in terms of the source color C_s = (R_s, G_s, B_s, A_s) and the destination color C_d = (R_d, G_d, B_d, A_d). The source color is the incoming fragment's color value, while the destination color is the pre-existing color value in the frame buffer. The corresponding OpenGL blend function combinations are included in the table for reference.

Mode	Definition	OpenGL src blend function	OpenGL dst blend function
REPLACE	Cd = Cs	ONE	ZERO
ALPHA_ADD	Cd = Cs As + Cd	SRC_ALPHA	ONE
ALPHA	Cd = Cs As + Cd (1 - As)	SRC_ALPHA	ONE_MINUS_SRC_ALPHA
MODULATE	Cd = Cs Cd	DST_COLOR	ZERO
MODULATE_X2	Cd = 2 Cs Cd	DST_COLOR	SRC_COLOR

Implementation guidelines

Per-fragment operations are done according to the OpenGL 1.3 specification, sections 4.1 and 4.2, with the following exceptions:

• The color index mode is not supported;
• The alpha test function is always GEQUAL;
• Stencil testing and the stencil buffer are not supported;
• The depth test function is always LEQUAL;
• The blend equation is always FUNC_ADD;
• Blend function combinations are limited to the ones listed above;
• The constant blend color is not supported;
• Logical operations are not supported;
• Color masking is limited to all-or-nothing;
• The accumulation buffer is not supported.

Multisampling is not supported explicitly, but implementations may use it internally to implement full-scene antialiasing. The full-scene antialiasing hint can be enabled or disabled in Graphics3D. Similarly, the dithering hint in Graphics3D can be implemented using the per-fragment dithering feature in OpenGL.

See Also:

Binary format

Field Summary

static int	ALPHA Selects the alpha blend mode.
static int	ALPHA_ADD Selects the additive blend mode.
static int	MODULATE Selects the basic modulating blending mode; source pixels are multiplied with the destination pixels.
static int	MODULATE_X2 Selects the brighter modulating blending mode.
static int	REPLACE Selects the replace mode.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

CompositingMode()
Constructs a CompositingMode object with default values.

Method Summary

float	getAlphaThreshold() Retrieves the current alpha threshold.
int	getBlending() Retrieves the current frame buffer blending mode.
float	getDepthOffsetFactor() Retrieves the current depth offset slope factor.
float	getDepthOffsetUnits() Retrieves the current constant depth offset.
boolean	isColorWriteEnabled() Queries whether color writing is enabled.
boolean	isDepthTestEnabled() Queries whether depth testing is enabled.
boolean	isDepthWriteEnabled() Queries whether depth writing is enabled.
void	setAlphaThreshold(float threshold) A fragment is drawn if and only if its alpha component is greater than or equal to the alpha threshold.
void	setBlending(int mode) Selects a method of combining the pixel to be rendered with the pixel already in the frame buffer.
void	setColorWriteEnable(boolean enable) Enables or disables writing of fragment color values into the color buffer.
void	setDepthOffset(float factor, float units) Defines a value that is added to the screen space Z coordinate of a pixel immediately before depth test and depth write.
void	setDepthTestEnable(boolean enable) Enables or disables depth testing.
void	setDepthWriteEnable(boolean enable) Enables or disables writing of fragment depth values into the depth buffer.

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REPLACE

public static final int REPLACE

Selects the replace mode. The destination pixel is overwritten with the source pixel.

See Also:

Constant Field Values

ALPHA

public static final int ALPHA

Selects the alpha blend mode. A weighted average of the source and destination pixels is computed.

See Also:

Constant Field Values

ALPHA_ADD

public static final int ALPHA_ADD

Selects the additive blend mode. The source pixel is first scaled by the source alpha and then summed with the destination pixel.

See Also:

Constant Field Values

MODULATE

public static final int MODULATE

Selects the basic modulating blending mode; source pixels are multiplied with the destination pixels.

See Also:

Constant Field Values

MODULATE_X2

public static final int MODULATE_X2

Selects the brighter modulating blending mode. This is the same as basic modulation, but the results are multiplied by two (and saturated to 1.0) to compensate for the loss of luminance caused by the component-wise multiplication.

See Also:

Constant Field Values

Constructor Detail

CompositingMode

public CompositingMode()

Constructs a CompositingMode object with default values. The default values are:

blending mode : REPLACE
alpha threshold : 0.0
depth offset : 0.0, 0.0
depth test : enabled
depth write : enabled
color write : enabled

Method Detail

setBlending

public void setBlending(int mode)

Selects a method of combining the pixel to be rendered with the pixel already in the frame buffer. Blending is applied as the very last step of the pixel processing pipeline.

Parameters:

mode - the new blending mode

Throws:

java.lang.IllegalArgumentException - if mode is not one of the symbolic constants listed above

See Also:

getBlending

getBlending

public int getBlending()

Retrieves the current frame buffer blending mode.

Returns:

the currently active blending mode

See Also:

setBlending

setAlphaThreshold

public void setAlphaThreshold(float threshold)

A fragment is drawn if and only if its alpha component is greater than or equal to the alpha threshold. If the threshold is 1.0, no fragments will be drawn; if the threshold is 0.0, all fragments will be drawn.

This is equivalent to doing an alpha test with the "greater than or equal" operator in OpenGL.

Parameters:

threshold - the new alpha threshold; must be [0,1]

Throws:

java.lang.IllegalArgumentException - if threshold is negative or greater than 1.0

See Also:

getAlphaThreshold

getAlphaThreshold

public float getAlphaThreshold()

Retrieves the current alpha threshold.

Returns:

the current alpha threshold [0,1]

See Also:

setAlphaThreshold

setDepthTestEnable

public void setDepthTestEnable(boolean enable)

Enables or disables depth testing. If depth testing is enabled, a fragment is written to the frame buffer if and only if its depth component is less than or equal to the corresponding value in the depth buffer. If there is no depth buffer in the current rendering target, this setting has no effect; the fragment will be written anyway.

Parameters:

enable - true to enable depth test; false to disable it

isDepthTestEnabled

public boolean isDepthTestEnabled()

Queries whether depth testing is enabled.

Returns:

true if depth testing is enabled; false if it's disabled

setDepthWriteEnable

public void setDepthWriteEnable(boolean enable)

Enables or disables writing of fragment depth values into the depth buffer. If there is no depth buffer in the current rendering target, this setting has no effect; nothing will be written anyway.

If both depth testing and depth writing are enabled, and a fragment passes the depth test, that fragment's depth value is written to the depth buffer at the corresponding position.

If depth testing is disabled and depth writing is enabled, a fragment's depth value is always written to the depth buffer.

If depth writing is disabled, a fragment's depth value is never written to the depth buffer.

Parameters:

enable - true to enable depth write; false to disable it

isDepthWriteEnabled

public boolean isDepthWriteEnabled()

Queries whether depth writing is enabled.

Returns:

true if depth writing is enabled; false if it's disabled

setColorWriteEnable

public void setColorWriteEnable(boolean enable)

Enables or disables writing of fragment color values into the color buffer.

Parameters:

enable - true to enable color write; false to disable it

isColorWriteEnabled

public boolean isColorWriteEnabled()

Queries whether color writing is enabled.

Returns:

true if color writing is enabled; false if it's disabled

setDepthOffset

public void setDepthOffset(float factor,
                           float units)

Defines a value that is added to the screen space Z coordinate of a pixel immediately before depth test and depth write. The depth offset is computed for each polygon with the following formula:

 offset = m * factor + r * units,
 r = smallest distinguishable depth buffer increment
 m = maximum depth slope (Z gradient) of the triangle

Parameters:

factor - slope dependent depth offset

units - constant depth offset

See Also:

getDepthOffsetFactor, getDepthOffsetUnits

getDepthOffsetFactor

public float getDepthOffsetFactor()

Retrieves the current depth offset slope factor. This is the factor parameter set in setDepthOffset.

Returns:

the current depth offset factor

See Also:

setDepthOffset

getDepthOffsetUnits

public float getDepthOffsetUnits()

Retrieves the current constant depth offset. This is the units parameter set in setDepthOffset.

Returns:

the current depth offset in depth units

See Also:

setDepthOffset