net.rim.device.api.system
Class EncodedImage

java.lang.Object
  |
  +--net.rim.device.api.system.EncodedImage

Direct Known Subclasses:

PNGEncodedImage, WBMPEncodedImage

public abstract class EncodedImage

extends Object

Encapsulates encoded images of various formats.

To decode an image, first call EncodedImage.createEncodedImage to generate an instance of EncodedImage, and then call getBitmap.

Field Summary

static int	DECODE_ALPHA Decodes an alpha channel if there is one.
static int	DECODE_NATIVE Forces the bitmap to be decoded to the native bitmap type of the device.
static int	DECODE_READONLY Marks the decoded bitmap as readonly.
static int	IMAGE_TYPE_JPEG Indicates that an image is encoded in the JPEG format.
static int	IMAGE_TYPE_PNG Indicates that an image is encoded in the PNG format.
static int	IMAGE_TYPE_WBMP Indicates that an image is encoded in the WBMP format.

Method Summary

static EncodedImage	createEncodedImage(byte[] data, int offset, int length) Creates an EncodedImage from bytes.
static EncodedImage	createEncodedImage(byte[] data, int offset, int length, String mimeType) Creates an EncodedImage from bytes.
Bitmap	getBitmap() Returns a bitmap of this image.
abstract Bitmap	getBitmap(int frameIndex) Returns a bitmap image of the specified frame.
int	getFrameCount() Returns the number of frames in this image.
int	getFrameHeight(int frameIndex) Returns the height in pixels of the specified frame.
boolean	getFrameMonochrome(int frameIndex) Returns true if the spcified frame is monochrome.
boolean	getFrameTransparency(int frameIndex) Returns true if the specified frame has transparency information.
int	getFrameWidth(int frameIndex) Returns the width in pixels of the specified frame.
int	getHeight() Returns the height of this image in pixels.
int	getImageType() Returns this image's encoding format.
static Enumeration	getSupportedMIMETypes() Returns a list of the supported MIME image types.
int	getWidth() Returns The width of this image in pixels.
boolean	hasTransparency() Returns true if this image has transparency.
boolean	isMonochrome() Returns true of this is a monochrome image.
void	setDecodeMode(int decodeMode) Sets the decoding mode for the image.
void	setScale(int scale) Sets the scale to be used when decoding this image.

Methods inherited from class java.lang.Object

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

Field Detail

DECODE_ALPHA

public static final int DECODE_ALPHA

Decodes an alpha channel if there is one.

DECODE_NATIVE

public static final int DECODE_NATIVE

Forces the bitmap to be decoded to the native bitmap type of the device.

DECODE_READONLY

public static final int DECODE_READONLY

Marks the decoded bitmap as readonly.

IMAGE_TYPE_PNG

public static final int IMAGE_TYPE_PNG

Indicates that an image is encoded in the PNG format.

IMAGE_TYPE_JPEG

public static final int IMAGE_TYPE_JPEG

Indicates that an image is encoded in the JPEG format.

IMAGE_TYPE_WBMP

public static final int IMAGE_TYPE_WBMP

Indicates that an image is encoded in the WBMP format.

Method Detail

getSupportedMIMETypes

public static Enumeration getSupportedMIMETypes()

Returns a list of the supported MIME image types.

This method returns an Enumeration containing Strings representing the MIME image types that the device supports (in lowercase). Note that MIME types are not case sensitive.

PNG format images are guaranteed to be supported.

Returns:

An Enumeration of the supported MIME image types.

createEncodedImage

public static EncodedImage createEncodedImage(byte[] data,
                                              int offset,
                                              int length)

Creates an EncodedImage from bytes. A new instance of the appropriate EncodedImage subclass is returned. If the image format is not recognized, an IllegalArgumentException is thrown.

Parameters:

data - The byte array containing the encoded image data.

offset - The starting offset of the encoded image data in the array.

length - The length in bytes of the encoded image data, or -1 to indicate the entire array should be used.

Since:

JDE 3.6

See Also:

PNGEncodedImage, WBMPEncodedImage

createEncodedImage

public static EncodedImage createEncodedImage(byte[] data,
                                              int offset,
                                              int length,
                                              String mimeType)

Creates an EncodedImage from bytes.

A new instance of the appropriate EncodedImage subclass is returned. If the image format does not match the MIME type, or the image data is otherwise invalid an IllegalArgumentException is thrown. If the MIME type is null then the system will attempt to infer the image type from the image data.

Parameters:

data - The byte array containing the encoded image data.

offset - The starting offset of the encoded image data in the array.

length - The length in bytes of the encoded image data, or -1 to indicate the entire array should be used.

mimeType - The MIME type of the image data.

Since:

JDE 3.6

See Also:

PNGEncodedImage, WBMPEncodedImage

setDecodeMode

public void setDecodeMode(int decodeMode)

Sets the decoding mode for the image. The decode mode can be one of DECODE_ALPHA, DECODE_NATIVE, or DECODE_READONLY (described above). The default decode mode is DECODE_ALPHA.

Parameters:

decodeMode - the decoding mode to be used for this image.

Since:

JDE 3.6

setScale

public void setScale(int scale)

Sets the scale to be used when decoding this image.

Images can be downscaled by an integer factor when decoding. This is a more efficient way of scaling instead of decoding the image normally and using Graphics to scale.

Parameters:

scale - The downscale factor.

Since:

JDE 3.6

getImageType

public int getImageType()

Returns this image's encoding format. This will be one of the predefined image types.

Returns:

The image type.

getWidth

public int getWidth()

Returns The width of this image in pixels.

Returns:

The width in pixels.

getHeight

public int getHeight()

Returns the height of this image in pixels.

Returns:

The height in pixels.

getFrameCount

public int getFrameCount()

Returns the number of frames in this image. All images have at least a single frame, but some can have multiple frames.

Returns:

The number of frames present.

isMonochrome

public boolean isMonochrome()

Returns true of this is a monochrome image. If the only two colours used in the image are black and white, the image is considered to be monochrome.

Returns:

true if this image is monochrome, false otherwise.

hasTransparency

public boolean hasTransparency()

Returns true if this image has transparency. If one or more of the image frames contains transparency information, the image is considered to have transparency.

Returns:

true if this image contains transparency, false otherwise.

getFrameWidth

public int getFrameWidth(int frameIndex)

Returns the width in pixels of the specified frame.

Parameters:

frameIndex - The frame in question.

Returns:

The width of the frame.

Since:

JDE 3.6

getFrameHeight

public int getFrameHeight(int frameIndex)

Returns the height in pixels of the specified frame.

Parameters:

frameIndex - The frame in question.

Returns:

The height of the frame.

Since:

JDE 3.6

getFrameMonochrome

public boolean getFrameMonochrome(int frameIndex)

Returns true if the spcified frame is monochrome. If the only two colours used in the frame are black and white, the frame is considered to be monochrome.

Parameters:

frameIndex - The frame in question.

Returns:

true if this frame is monochrome, false otherwise.

Since:

JDE 3.6

getFrameTransparency

public boolean getFrameTransparency(int frameIndex)

Returns true if the specified frame has transparency information.

Parameters:

frameIndex - The frame in question.

Returns:

true if this frame contains transparency, false otherwise.

Since:

JDE 3.6

getBitmap

public Bitmap getBitmap()

Returns a bitmap of this image.

This method decodes the image represented by this EncodedImage and returns a Bitmap. This call can be expensive.

Returns:

a Bitmap representation of the image.

getBitmap

public abstract Bitmap getBitmap(int frameIndex)

Returns a bitmap image of the specified frame.

This method decodes the given frame of the image represented by this EncodedImage. This call can be expensive.

Parameters:

frameIndex - The frame in question.

Returns:

A Bitmap representation of the image frame.

Since:

JDE 3.6