javax.microedition.m3g
Class Background

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

public class Background

extends Object3D

Defines whether and how to clear the viewport.

The portions of the frame buffer that correspond to the current viewport are cleared according to a given Background object. In retained mode (that is, when rendering a World), the Background object associated with the World is used. In immediate mode, a Background object is given as a parameter to clear. In absence of a Background object, the default values specified in the constructor are used.

Clearing can be enabled and disabled individually for the color buffer and the depth buffer. The color buffer is cleared using the background color and/or the background image, as specified below. If the background image is set to null (the initial value), only the background color is used. The depth buffer is always cleared to the maximum depth value.

Background image

The background image is stored as a reference to an Image2D. If the referenced Image2D is modified by the application, or a new Image2D is bound as the background image, the modifications are immediately reflected in the Background object.

The background image must be in RGB or RGBA format. Furthermore, it must be in the same format as the currently bound rendering target. This is enforced by the render(World) and clear methods in Graphics3D.

A cropping rectangle very similar to that of Sprite3D is available to facilitate scrolling and zooming of the background image. The contents of the crop rectangle are scaled to fill the entire viewport. The crop rectangle need not lie within the source image boundaries. If it does not, the source image is either considered to repeat indefinitely in the image space (the REPEAT mode) or to not repeat at all, with pixels outside the source image having the background color (the BORDER mode).

Contrary to texture images, the width and height of a background image do not have to be powers of two. Furthermore, the maximum size of a background image is only determined by the amount of available memory; there is no fixed limit. The dimensions of the crop rectangle are also unbounded.

Implementation guidelines

The requirements and recommendations given in the Implementation guidelines of Sprite3D also apply for Background images. In particular, implementations using textured rectangles to blit the background image must follow the resampling rules specified for sprites.

See Also:

Binary format

Field Summary

static int	BORDER Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the background color.
static int	REPEAT Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the same color as the pixel in the corresponding position in the source image.

Constructor Summary

Background()
Constructs a new Background with default values.

Method Summary

int	getColor() Retrieves the current background color.
int	getCropHeight() Gets the current cropping rectangle height within the source image.
int	getCropWidth() Gets the current cropping rectangle width within the source image.
int	getCropX() Retrieves the current cropping rectangle X offset relative to the source image top left corner.
int	getCropY() Retrieves the current cropping rectangle Y offset relative to the source image top left corner.
Image2D	getImage() Gets the current background image.
int	getImageModeX() Gets the current background image repeat mode for the X dimension.
int	getImageModeY() Gets the current background image repeat mode for the Y dimension.
boolean	isColorClearEnabled() Queries whether color buffer clearing is enabled.
boolean	isDepthClearEnabled() Queries whether depth buffer clearing is enabled.
void	setColor(int ARGB) Sets the background color.
void	setColorClearEnable(boolean enable) Enables or disables color buffer clearing.
void	setCrop(int cropX, int cropY, int width, int height) Sets a cropping rectangle within the background image.
void	setDepthClearEnable(boolean enable) Enables or disables depth buffer clearing.
void	setImage(Image2D image) Sets the background image, or switches from background image mode to background color mode.
void	setImageMode(int modeX, int modeY) Sets the background image repeat mode for the X and Y directions.

Methods inherited from class javax.microedition.m3g.Object3D

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

Field Detail

BORDER

public static final int BORDER

Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the background color.

See Also:

Constant Field Values

REPEAT

public static final int REPEAT

Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are considered to have the same color as the pixel in the corresponding position in the source image. Formally, a pixel at position X will have the same color as the pixel at position X % N, where N is the width or height of the image and % is the modulo operator.

See Also:

Constant Field Values

Constructor Detail

Background

public Background()

Constructs a new Background with default values. The default values are:

• color clear enable : true (clear the color buffer)
• depth clear enable : true (clear the depth buffer)
• background color : 0x00000000 (black, transparent)
• background image : null (use the background color only)
• background image mode : BORDER, BORDER
• crop rectangle : undefined (reset at setImage

Method Detail

setColorClearEnable

public void setColorClearEnable(boolean enable)

Enables or disables color buffer clearing. If color buffer clearing is enabled, the portion of the color buffer that corresponds to the viewport is cleared with the background image and/or the background color.

Parameters:

enable - true to enable color buffer clearing; false to disable

isColorClearEnabled

public boolean isColorClearEnabled()

Queries whether color buffer clearing is enabled.

Returns:

true if color buffer clearing is enabled; false if it is disabled

setDepthClearEnable

public void setDepthClearEnable(boolean enable)

Enables or disables depth buffer clearing. If depth buffer clearing is enabled, the portion of the depth buffer that corresponds to the viewport is cleared to the maximum depth value.

This setting is ignored if depth buffering is disabled in Graphics3D (see bindTarget).

Parameters:

enable - true to enable depth buffer clearing; false to disable

isDepthClearEnabled

public boolean isDepthClearEnabled()

Queries whether depth buffer clearing is enabled.

Returns:

true if depth buffer clearing is enabled; false if it is disabled

setColor

public void setColor(int ARGB)

Sets the background color. This is the color that the imaginary pixels outside of the source image boundaries are considered to have in the BORDER mode. If there is no background image, the viewport is cleared with this color only.

The alpha component of the background color is ignored when rendering to an RGB target.

Parameters:

ARGB - the new background color in 0xAARRGGBB format

See Also:

getColor

getColor

public int getColor()

Retrieves the current background color.

Returns:

the current background color in 0xAARRGGBB format

See Also:

setColor

setImage

public void setImage(Image2D image)

Sets the background image, or switches from background image mode to background color mode. The background image must be in the same format as the rendering target: RGB or RGBA in case of an Image2D target and RGB in case of a MIDP Graphics target.

The crop rectangle is set such that its top left corner is at the top left corner of the image, and its width and height are equal to the dimensions of the image.

Parameters:

image - the background image, or null to disable the current background image (if any) and clear with the background color only

Throws:

java.lang.IllegalArgumentException - if image is not in RGB or RGBA format

See Also:

getImage

getImage

public Image2D getImage()

Gets the current background image.

Returns:

the current background image

See Also:

setImage

setImageMode

public void setImageMode(int modeX,
                         int modeY)

Sets the background image repeat mode for the X and Y directions.

Parameters:

modeX - X repeat mode; one of BORDER, REPEAT

modeY - Y repeat mode; one of BORDER, REPEAT

Throws:

java.lang.IllegalArgumentException - if modeX or modeY is not one of the enumerated values listed above

getImageModeX

public int getImageModeX()

Gets the current background image repeat mode for the X dimension.

Returns:

the X repeat mode

See Also:

setImageMode

getImageModeY

public int getImageModeY()

Gets the current background image repeat mode for the Y dimension.

Returns:

the Y repeat mode

See Also:

setImageMode

setCrop

public void setCrop(int cropX,
                    int cropY,
                    int width,
                    int height)

Sets a cropping rectangle within the background image. The contents of the crop rectangle are scaled (stretched or condensed) to fill the viewport entirely.

The position of the upper left corner of the crop rectangle is given in pixels, relative to the upper left corner of the Image2D. The relative position may be negative in either or both axes. The width and height of the crop rectangle are also given in pixels, and must not be negative. If either of them is zero, the color buffer is cleared with the background color only.

If the crop rectangle lies completely or partially outside of the source image boundaries, the values of the (imaginary) pixels outside of the image are defined by the repeat mode. In BORDER mode, the imaginary pixels are taken to have the background color. In REPEAT mode, the source image is considered to repeat indefinitely. The repeat mode can be specified independently for the X and Y directions.

Parameters:

cropX - the X position of the top left of the crop rectangle, in pixels

cropY - the Y position of the top left of the crop rectangle, in pixels

width - the width of the crop rectangle, in pixels

height - the height of the crop rectangle, in pixels

Throws:

java.lang.IllegalArgumentException - if width < 0

java.lang.IllegalArgumentException - if height < 0

getCropX

public int getCropX()

Retrieves the current cropping rectangle X offset relative to the source image top left corner.

Returns:

the X offset of the cropping rectangle

See Also:

setCrop

getCropY

public int getCropY()

Retrieves the current cropping rectangle Y offset relative to the source image top left corner.

Returns:

the X offset of the cropping rectangle

See Also:

setCrop

getCropWidth

public int getCropWidth()

Gets the current cropping rectangle width within the source image.

Returns:

the width of the cropping rectangle

See Also:

setCrop

getCropHeight

public int getCropHeight()

Gets the current cropping rectangle height within the source image.

Returns:

the height of the cropping rectangle

See Also:

setCrop