javax.microedition.m3g
Class CompositingMode

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.CompositingMode

public class CompositingMode

extends Object3D

An Appearance component encapsulating per-pixel compositing attributes.

Depth offset is added to the depth (Z) value of a pixel prior to depth test and depth write. The offset is constant across a polygon. Depth offset is used to prevent Z fighting, which makes coplanar polygons intersect each other on the screen due to the limited resolution of the depth buffer. Depth offset allows, for example, white lines on a highway or scorch marks on a wall (decals in general) to be implemented with polygons instead of textures. 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 source and destination blend functions are included in the table for reference.

Mode	Definition	OpenGL src blend func	OpenGL dst blend func
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

Depth offset is computed according to section 3.5.5 in the OpenGL 1.3 specification. Per-fragment operations are done according to sections 4.1 and 4.2, with the following exceptions:

• 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;
• Individual masking of R, G and B is not supported;
• 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 may be implemented using the per-fragment dithering feature of 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.

Constructor Summary

CompositingMode()
Constructs a CompositingMode object with default values.

Method Summary

float	getAlphaThreshold() Retrieves the current alpha testing 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	isAlphaWriteEnabled() Queries whether alpha writing is enabled.
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) Sets the threshold value for alpha testing.
void	setAlphaWriteEnable(boolean enable) Enables or disables writing of fragment alpha values into the color buffer.
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.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Field Detail

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

REPLACE

public static final int REPLACE

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

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
• alpha 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)

Sets the threshold value for alpha testing. If the alpha component of a fragment is less than the alpha threshold, the fragment is not rendered. Consequently, if the threshold is 1.0, only fragments with the maximum alpha value (1.0) will be drawn, and if the threshold is 0.0, all fragments will be drawn.

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 testing threshold.

Returns:

the current alpha threshold [0, 1]

See Also:

setAlphaThreshold

setAlphaWriteEnable

public void setAlphaWriteEnable(boolean enable)

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

Parameters:

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

See Also:

setColorWriteEnable

isAlphaWriteEnabled

public boolean isAlphaWriteEnabled()

Queries whether alpha writing is enabled.

Returns:

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

See Also:

isColorWriteEnabled

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

See Also:

setAlphaWriteEnable

isColorWriteEnabled

public boolean isColorWriteEnabled()

Queries whether color writing is enabled.

Returns:

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

See Also:

isAlphaWriteEnabled

setDepthWriteEnable

public void setDepthWriteEnable(boolean enable)

Enables or disables writing of fragment depth values into the depth buffer. If depth buffering is not enabled in the current Graphics3D, 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

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

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