javax.microedition.m3d
Class Image2D

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

public class Image2D

extends Object3D

A two-dimensional image that can be used as a texture, background or sprite image. A mutable Image2D can also serve as a rendering target for Graphics3D. 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 powers of two. This restriction is enforced by Texture2D.

The image data supplied at construction is always copied in, not used by reference. This allows implementations to store the data in a format that is most optimal for their particular needs, and to optionally compress the data. For example, implementations may decide to reduce the bit depth of individual color components in order to save memory. Implementations on monochrome devices are allowed to map RGB colors into luminance, provided that all three color components are taken into account.

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	FORMAT_ALPHA A constructor parameter specifying that this Image2D has an alpha component only.
static int	FORMAT_LUMINANCE A constructor parameter specifying that this Image2D has a luminance component only.
static int	FORMAT_LUMINANCE_ALPHA A constructor parameter specifying that this Image2D has luminance and alpha components.
static int	FORMAT_RGB A constructor parameter specifying that this Image2D has red, green and blue color components.
static int	FORMAT_RGBA A constructor parameter specifying that this Image2D has red, green, blue and alpha components.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

Image2D(int format, int width, int height)
Constructs a new, mutable Image2D for off-screen rendering.

Image2D(int format, int width, int height, byte[] image)
Constructs a new, immutable Image2D with the given dimensions, copying the raw image data from a byte array.

Image2D(int format, int width, int height, byte[] image, byte[] palette)
Constructs a new, immutable Image2D with the given dimensions, copying the raw image data and the palette from two byte arrays.

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

Method Summary

int	getFormat() Gets the format of this Image2D, that is, one of the symbolic constants.
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.

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

FORMAT_RGB

public static final int FORMAT_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

FORMAT_RGBA

public static final int FORMAT_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

FORMAT_ALPHA

public static final int FORMAT_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.

See Also:

Constant Field Values

FORMAT_LUMINANCE

public static final int FORMAT_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.

See Also:

Constant Field Values

FORMAT_LUMINANCE_ALPHA

public static final int FORMAT_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.

See Also:

Constant Field Values

Constructor Detail

Image2D

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

Constructs a new, 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.

Parameters:

format - the internal pixel format of this Image2D

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

Throws:

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 a new, immutable Image2D with the given dimensions, copying the raw image data 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 this Image2D

width - width of this image in pixels, must be positive

height - height of this image in pixels, must be positive

image - pixel data as a byte array

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

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 a new, immutable Image2D with the given dimensions, copying the raw image data and the palette from two byte arrays.

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 above. Note that palettes mapping one byte value to another are explicitly 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 this Image2D

width - width of this image in pixels, must be positive

height - height of this 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.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)

java.lang.IllegalArgumentException - if any of the first width*height bytes in image is an illegal palette index, that is, a value greater than or equal to the number of palette entries

Image2D

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

Constructs a new, mutable Image2D for off-screen rendering. All pixels in the image are initialized to opaque white.

Parameters:

format - the internal pixel format of this Image2D

width - width of this image in pixels, must be positive

height - height of this 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

isMutable

public boolean isMutable()

Queries whether this Image2D is mutable. A mutable image can serve as a rendering target in Graphics3D while an immutable image cannot.

Returns:

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

getFormat

public int getFormat()

Gets the format of this Image2D, that is, one of the symbolic constants. Note that the format is fixed at construction and cannot be changed afterwards.

Returns:

the internal format of this Image2D

getWidth

public int getWidth()

Gets the width of this Image2D, in pixels. Note that the width and height cannot 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 cannot be changed after construction.

Returns:

the height of this image