javax.microedition.m3g
Class Image2D

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

public class Image2D

extends Object3D

A two-dimensional image that can be used as a texture, background or sprite image.

There are two kinds of images: mutable and immutable. The contents of a mutable image can be updated at any time by rendering into it or by using the set method. The changes are immediately reflected to the textures and other objects where the Image2D is used. The contents of an immutable image, on the other hand, are fixed at construction time and can not be changed later. Knowing that an image is immutable, the implementation can safely preprocess the image to optimize it for speed or memory consumption. For example, it may compress the image, reorder the pixels, or reduce the color depth.

The dimensions of the image are restricted only by the amount of available memory. However, if the image is to be used as a texture, its dimensions must be non-negative powers of two. This restriction is enforced by Texture2D.

The image contents are copied in from a byte array or from an Image object. All byte data supplied to an Image2D is treated as unsigned. That is, byte values in [-128, -1] are interpreted as values in [128, 255], in that order.

See Also:

Binary format

Field Summary

static int	ALPHA A constructor parameter specifying that this Image2D has an alpha component only.
static int	LUMINANCE A constructor parameter specifying that this Image2D has a luminance component only.
static int	LUMINANCE_ALPHA A constructor parameter specifying that this Image2D has luminance and alpha components.
static int	RGB A constructor parameter specifying that this Image2D has red, green and blue color components.
static int	RGBA A constructor parameter specifying that this Image2D has red, green, blue and alpha components.

Constructor Summary

Image2D(int format, int width, int height)
Constructs an empty, mutable Image2D with the given dimensions.

Image2D(int format, int width, int height, byte[] image)
Constructs an immutable Image2D by copying pixels from a byte array.

Image2D(int format, int width, int height, byte[] image, byte[] palette)
Constructs an immutable Image2D by copying palette indices from a byte array, and the palette entries from another byte array.

Image2D(int format, java.lang.Object image)
Constructs an immutable Image2D by copying pixels from a MIDP or AWT Image.

Method Summary

int	getFormat() Gets the internal format of this Image2D.
int	getHeight() Gets the height of this Image2D, in pixels.
int	getWidth() Gets the width of this Image2D, in pixels.
boolean	isMutable() Queries whether this Image2D is mutable.
void	set(int x, int y, int width, int height, byte[] image) Updates a rectangular area of this Image2D by copying pixels from a byte array.

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

A constructor parameter specifying that this Image2D has an alpha component only. If the image data is supplied as a byte array, it must have one byte per pixel, representing the alpha value. This image format is useful for rendering objects with varying opacities, such as clouds. An ALPHA image can not be used as a rendering target or background.

See Also:

Constant Field Values

LUMINANCE

public static final int LUMINANCE

A constructor parameter specifying that this Image2D has a luminance component only. If the image data is supplied as a byte array, it must have one byte per pixel, representing the luminance value. This image format is a cheaper alternative to RGB in cases where colors are not needed, for instance in light mapping. A LUMINANCE image can not be used as a rendering target or background.

See Also:

Constant Field Values

LUMINANCE_ALPHA

public static final int LUMINANCE_ALPHA

A constructor parameter specifying that this Image2D has luminance and alpha components. If the image data is supplied as a byte array, it must have two bytes per pixel, representing the luminance and alpha values, in that order. This image format is a cheap alternative to RGBA in cases where colors are not needed; for instance in light mapping. A LUMINANCE_ALPHA image can not be used as a rendering target or background.

See Also:

Constant Field Values

RGB

public static final int RGB

A constructor parameter specifying that this Image2D has red, green and blue color components. If the image data is supplied as a byte array, it must be in RGB order, one byte per component.

See Also:

Constant Field Values

RGBA

public static final int RGBA

A constructor parameter specifying that this Image2D has red, green, blue and alpha components. If the image data is supplied as a byte array, it must be in RGBA order, one byte per component.

See Also:

Constant Field Values

Constructor Detail

Image2D

public Image2D(int format,
               java.lang.Object image)

Constructs an immutable Image2D by copying pixels from a MIDP or AWT Image. The type of the Image object depends on the Java profile that this specification is implemented on, as follows:

• java.awt.Image on profiles supporting AWT;
• javax.microedition.lcdui.Image on profiles supporting LCDUI;
• either of the above on profiles supporting both AWT and LCDUI.

The width and height of the created Image2D are set equal to those of the given Image. If the internal format of this Image2D is incompatible with the source Image, the pixels are converted to the internal format as they are copied in. The conversion is done according to the general rules that are specified in the package description. Note, in particular, that conversion from RGBA to ALPHA is done by copying in the alpha values as such and discarding the RGB values.

Because the internal pixel format of an Image is not exposed in MIDP, this method treats all mutable MIDP Images as RGB and all immutable Images as RGBA. The actual pixel format is respected on platforms such as AWT that do expose it to the application.

Parameters:

format - the internal pixel format of the new Image2D

image - pixels and image properties to copy into the new Image2D

Throws:

java.lang.NullPointerException - if image is null

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

java.lang.IllegalArgumentException - if image is not an Image object appropriate to the underlying Java profile

Image2D

public Image2D(int format,
               int width,
               int height,
               byte[] image)

Constructs an immutable Image2D by copying pixels from a byte array.

Pixels in image are ordered from left to right and top to bottom. The number of bytes per pixel and the order of components are determined by the specified format; see above.

Parameters:

format - the internal pixel format of the new Image2D

width - width of the created image in pixels; must be positive

height - height of the created image in pixels; must be positive

image - pixel data as a byte array

Throws:

java.lang.NullPointerException - if image is null

java.lang.IllegalArgumentException - if width <= 0

java.lang.IllegalArgumentException - if height <= 0

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

java.lang.IllegalArgumentException - if image.length < width*height*bpp, where bpp is the number of bytes per pixel

Image2D

public Image2D(int format,
               int width,
               int height,
               byte[] image,
               byte[] palette)

Constructs an immutable Image2D by copying palette indices from a byte array, and the palette entries from another byte array.

Pixels in image are ordered from left to right and top to bottom. Each pixel is composed of one byte, representing a palette index.

The palette consists of 256 entries, all with the same number of color components. The number and ordering of the color components is determined by the specified format; see the symbolic constants listed above. Note that a palette consisting of only alpha or luminance values is also allowed.

The palette entries are copied in from the palette array, starting at index 0. If the array has N entries, N < 256, the remaining entries [N, 255] are left undefined. If the array has more than 256 entries, only the first 256 are copied in.

Parameters:

format - the internal pixel format of the new Image2D

width - width of the created image in pixels; must be positive

height - height of the created image in pixels; must be positive

image - pixel data as a byte array, one byte per pixel

palette - palette entries as a byte array

Throws:

java.lang.NullPointerException - if image is null

java.lang.NullPointerException - if palette is null

java.lang.IllegalArgumentException - if width <= 0

java.lang.IllegalArgumentException - if height <= 0

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

java.lang.IllegalArgumentException - if image.length < width*height

java.lang.IllegalArgumentException - if (palette.length < 256*C) && ((palette.length % C) != 0), where C is the number of color components (for instance, 3 for RGB)

Image2D

public Image2D(int format,
               int width,
               int height)

Constructs an empty, mutable Image2D with the given dimensions. All pixels in the image are initialized to opaque white. The image contents can be set later by using the image as a rendering target in Graphics3D, or by using the set method. Note that only RGB and RGBA images can be used as rendering targets.

Parameters:

format - the internal pixel format of the new Image2D

width - width of the created image in pixels; must be positive

height - height of the created image in pixels; must be positive

Throws:

java.lang.IllegalArgumentException - if width <= 0

java.lang.IllegalArgumentException - if height <= 0

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

Method Detail

set

public void set(int x,
                int y,
                int width,
                int height,
                byte[] image)

Updates a rectangular area of this Image2D by copying pixels from a byte array. This method is only available for mutable images.

The area that is to be updated is specified in pixels, relative to the upper left corner of this Image2D. The area must lie completely within the bounds of the image.

Pixels in image are ordered from left to right and top to bottom. The number of bytes per pixel and the order of components are determined by the specified internal format; see the symbolic constants listed above.

Parameters:

x - the X coordinate of the area to update, relative to the top left corner

y - the Y coordinate of the area to update, relative to the top left corner

width - width of the area in the image to update, in pixels

height - height of the area in the image to update, in pixels

image - pixel data as a byte array

Throws:

java.lang.NullPointerException - if image is null

java.lang.IllegalStateException - if this Image2D is immutable

java.lang.IllegalArgumentException - if x < 0

java.lang.IllegalArgumentException - if y < 0

java.lang.IllegalArgumentException - if width <= 0

java.lang.IllegalArgumentException - if height <= 0

java.lang.IllegalArgumentException - if (x + width) > getWidth

java.lang.IllegalArgumentException - if (y + height) > getHeight

java.lang.IllegalArgumentException - if image.length < width * height * bpp, where bpp is the number of bytes per pixel (depends on the internal format specified at construction)

isMutable

public boolean isMutable()

Queries whether this Image2D is mutable. The contents of a mutable image can be changed after construction, while the contents of an immutable image can not.

Returns:

true if this Image2D is mutable; false if it is immutable

getFormat

public int getFormat()

Gets the internal format of this Image2D. Note that the format can not be changed after construction.

Returns:

the internal format of this Image2D; one of the symbolic constants listed above

getWidth

public int getWidth()

Gets the width of this Image2D, in pixels. Note that the width and height can not be changed after construction.

Returns:

the width of this image

getHeight

public int getHeight()

Gets the height of this Image2D, in pixels. Note that the width and height can not be changed after construction.

Returns:

the height of this image