javax.microedition.m2g
Class ScalableGraphics

java.lang.Object
  javax.microedition.m2g.ScalableGraphics

public final class ScalableGraphics
extends Object

This is the fundamental class for 2D rendering. The ScalableGraphics context class provides and handles all the rendering capability within this package. In other words, the rendering can only be achieved through the render methods provided in this class. Note that the ScalableGraphics instance must be bound to the rendering target prior to calling the render method. The implementation must clip to the viewport boundaries.

Field Summary

static int	RENDERING_QUALITY_HIGH Defines a high rendering quality level.
static int	RENDERING_QUALITY_LOW Defines a low rendering quality level.

Method Summary

void	bindTarget(Object target) Bind the given Graphics as the rendering target of this ScalableGraphics context.
static ScalableGraphics	createInstance() Retrieve a new instance of ScalableGraphics that can be associated to an application.
void	releaseTarget() Flushes the rendered ScalableImage to the currently bound target and then releases the target.
void	render(int x, int y, ScalableImage image) Renders the specified ScalableImage using the supplied anchor point.
void	setRenderingQuality(int mode) Set the quality of rendering in the ScalableGraphics context.
void	setTransparency(float alpha) Set the transparency in the ScalableGraphics context with the supplied alpha value.

Methods inherited from class java.lang.Object

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

Field Detail

RENDERING_QUALITY_LOW

public static final int RENDERING_QUALITY_LOW

Defines a low rendering quality level.

See Also:

Constant Field Values

RENDERING_QUALITY_HIGH

public static final int RENDERING_QUALITY_HIGH

Defines a high rendering quality level.

See Also:

Constant Field Values

Method Detail

bindTarget

public final void bindTarget(Object target)

Bind the given Graphics as the rendering target of this ScalableGraphics context. The type of the Graphics object depends on the Java profile that this specification is implemented on, as follows:

• android.graphics.Canvas on profiles supporting Android.

Parameters:

target - the object Canvas to receive the rendered image.

Throws:

NullPointerException - if target is null.

IllegalArgumentException - if target is invalid.

IllegalStateException - if target is already bound.

releaseTarget

public final void releaseTarget()

Flushes the rendered ScalableImage to the currently bound target and then releases the target. This ensures that the ScalableImage is actually made visible on the target that was set in bindTarget. Otherwise, the image may or may not become visible.

Throws:

IllegalStateException - if target is not bound.

render

public final void render(int x,
                         int y,
                         ScalableImage image)

Renders the specified ScalableImage using the supplied anchor point. The anchor point given is relative to the upper left corner of the rendering surface. It is important to note that the content is made visible or flushed to the display only after a call is made to releaseTarget.

IMPL NOTE 1: the target canvas clipping is taken into account.

IMPL NOTE 2: the target canvas translation is taken into account.

IMPL NOTE 3: the target canvas context is saved before drawing and restored before leaving.

TODO: check if the target canvas current matrix should be taken into account. For now, the matrix is reset to identity before drawing the image.

Parameters:

x - the X coordinate of the anchor point, in pixels, relative to the target canvas origin (including the current translated position).

y - the Y coordinate of the anchor point, in pixels, relative to the target canvas origin (including the current translated position).

image - the ScalableImage to be rendered.

Throws:

NullPointerException - if image is null.

IllegalStateException - if target is not bound.

See Also:

releaseTarget()

setRenderingQuality

public final void setRenderingQuality(int mode)

Set the quality of rendering in the ScalableGraphics context. It can take one of the values, RENDERING_QUALITY_LOW or RENDERING_QUALITY_HIGH. Default=RENDERING_QUALITY_HIGH. The implementation of these quality levels is implementation dependent and should be mapped to definitions in SVG spec (shape, text, image and color rendering).

Parameters:

mode - this value indicates the quality of rendering required.

Throws:

IllegalArgumentException - if the mode is invalid.

setTransparency

public final void setTransparency(float alpha)

Set the transparency in the ScalableGraphics context with the supplied alpha value. Alpha value must be a floating point number in the range [0.0, 1.0]. The source pixels are always combined with destination pixels using the Source Over Destination rule [Porter-Duff]. In this context, the Source Over Destination rule has the following properties: a fully opaque pixel in the source must replace the destination pixel, a fully transparent pixel in the source must leave the destination pixel unchanged, and a semitransparent pixel in the source must be alpha blended with the destination pixel using the supplied value. The default alpha value is 1.0 (fully opaque), when not specified.

Parameters:

alpha - the constant alpha value to be used for rendering.

Throws:

IllegalArgumentException - if alpha is out of range.

createInstance

public static final ScalableGraphics createInstance()

Retrieve a new instance of ScalableGraphics that can be associated to an application.

Returns:

the newly created ScalableGraphics instance.