SHOW Colour SHOW Framework

net.rim.device.api.system
Class EncodedImage

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

Direct Known Subclasses:

BMPEncodedImage, GIFEncodedImage, JPEGEncodedImage, PNGEncodedImage, TIFFEncodedImage, 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.

This class can only be extended by RIM because it contains one or more abstract methods with package access.

Since:

JDE 3.6.0

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_NO_DITHER Don't dither when decoding.
static int	DECODE_READONLY Marks the decoded bitmap as readonly.
static int	IMAGE_TYPE_BMP Indicates that an image is encoded in the BMP format.
static int	IMAGE_TYPE_GIF Indicates that an image is encoded in the GIF format.
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_TIFF Indicates that an image is encoded in the TIFF 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.
	abstract int	getAlphaType(int frameIndex) Gets the bitmap type for the given frame's alpha channel.
	Bitmap	getBitmap() Returns a bitmap of this image.
	Bitmap	getBitmap(int frameIndex) Returns a bitmap image of the specified frame.
	abstract int	getBitmapType(int frameIndex) Gets the bitmap type for the given frame.
	byte[]	getData() Returns the encoded data of this image.
	int	getDecodeMode() Gets the decoding mode for the image.
	static EncodedImage	getEncodedImageResource(String name) Creates an encoded image from provided name resource.
	static EncodedImage	getEncodedImageResource(String module, String name) Creates an encoded image from provided named resource found in module.
	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 specified 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 (unscaled) height of this image in pixels.
	int	getImageType() Returns this image's encoding format.
	int	getLength() Returns the length of the encoded image data.
	abstract String	getMIMEType() Return the commonly known MIME type associate for this encoded image object.
	int	getOffset() Returns the offset into the data where the encoded image begins.
	int	getScale() Gets the scale that is to be used when decoding this image.
	int	getScaledFrameHeight(int frameIndex) Returns the scaled height in pixels of the specified frame.
	int	getScaledFrameWidth(int frameIndex) Returns the scaled width in pixels of the specified frame.
	int	getScaledHeight() Returns the scaled height of this image in pixels.
	int	getScaledWidth() Returns the scaled width of this image in pixels.
	int	getScaleX32() Gets the x scale that is to be used when decoding this image.
	int	getScaleY32() Gets the y scale that is to be used when decoding this image.
	static Enumeration	getSupportedMIMETypes() Returns a list of the supported MIME image types.
	int	getWidth() Returns the (unscaled) width of this image in pixels.
	boolean	hasTransparency() Returns true if this image has transparency.
	static boolean	isMIMETypeSupported(String mimeType) Determines whether or not the specified MIME type is supported.
	boolean	isMonochrome() Returns true if this is a monochrome image.
	EncodedImage	scaleImage32(int scaleX, int scaleY) Returns a copy of this encoded image, but with its x and y scales set to scaleX and scaleY, respectively.
	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.

Since:

JDE 3.6.0

DECODE_NATIVE

public static final int DECODE_NATIVE

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

Since:

JDE 3.6.0

DECODE_NO_DITHER

public static final int DECODE_NO_DITHER

Don't dither when decoding.

Since:

JDE 4.0.0

DECODE_READONLY

public static final int DECODE_READONLY

Marks the decoded bitmap as readonly.

Since:

JDE 3.6.0

IMAGE_TYPE_BMP

public static final int IMAGE_TYPE_BMP

Indicates that an image is encoded in the BMP format.

Since:

JDE 4.0.2

IMAGE_TYPE_GIF

public static final int IMAGE_TYPE_GIF

Indicates that an image is encoded in the GIF format.

Since:

JDE 4.2.0

IMAGE_TYPE_JPEG

public static final int IMAGE_TYPE_JPEG

Indicates that an image is encoded in the JPEG format.

Since:

JDE 3.6.0

IMAGE_TYPE_PNG

public static final int IMAGE_TYPE_PNG

Indicates that an image is encoded in the PNG format.

Since:

JDE 3.6.0

IMAGE_TYPE_TIFF

public static final int IMAGE_TYPE_TIFF

Indicates that an image is encoded in the TIFF format.

Since:

JDE 4.0.2

IMAGE_TYPE_WBMP

public static final int IMAGE_TYPE_WBMP

Indicates that an image is encoded in the WBMP format.

Since:

JDE 3.6.0

Method Detail

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.

This method accepts an encoding of the image in a byte array format. An image encoding can be obtained by either of the following methods:

First, when an image is added to a project in the IDE, the image resource becomes available to the developer.

Second, the image encoding can be obtained manually by converting the binary image file to a java byte array. This is accomplished using the following procedure:

1. Using a binary file converter, such as xxd, convert the image to a C-style byte array.
2. Open the target file and search for the string "0x".
3. Replace the string with the following "(byte)0x".
4. Adjust the array declaration at the top of the file to conform to Java standards.
5. Remove the following string from the bottom of the file "unsigned int input_file_name_len = XXXX".

If done correctly, the file will contain a valid Java byte array containing the image encoding.

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.0

See Also:

PNGEncodedImage, WBMPEncodedImage, GIFEncodedImage, JPEGEncodedImage, BMPEncodedImage, TIFFEncodedImage

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. (NOT base64 encoded)

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.

The following MIME types are supported:

• "image/gif"
• "image/png"
• "image/vnd.wap.wbmp"
• "image/jpeg" (supported only on Colour devices)
• "image/jpg" (supported only on Colour devices)
• "image/pjpeg" (supported only on Colour devices)
• "image/bmp"
• "image/tiff"

Throws:

IllegalArgumentException - Thrown if the specified mime type is invalid.

Since:

JDE 3.6.0

See Also:

PNGEncodedImage, WBMPEncodedImage

getAlphaType

public abstract int getAlphaType(int frameIndex)

Gets the bitmap type for the given frame's alpha channel.

Parameters:

frameIndex - The index of the frame for which to return the alpha channel.

Returns:

The type of alpha bitmap that will be decoded with a call to getBitmap. If the given frame doesn't have an alpha bitmap, it will return 0

Since:

JDE 3.7.0

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.

Since:

JDE 3.6.0

getBitmap

public 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.0

getBitmapType

public abstract int getBitmapType(int frameIndex)

Gets the bitmap type for the given frame.

Parameters:

frameIndex - The index of the frame for which to return the bitmap type.

Returns:

The type of bitmap that will be decoded with a call to getBitmap.

Since:

JDE 3.7.0

getData

public final byte[] getData()

Returns the encoded data of this image.

Returns:

A byte array containing the encoded data for this image.

Since:

JDE 3.7.0

getDecodeMode

public int getDecodeMode()

Gets the decoding mode for the image.

Returns:

The decoding mode to be used for this image.

Since:

JDE 3.7.0

getEncodedImageResource

public static EncodedImage getEncodedImageResource(String name)

Creates an encoded image from provided name resource.

This method looks for the resource in both the .cod file that called this method and any .cod files that it relies on. The resource files are automatically generated by the compiler when a new graphic (PNG, GIF, or, JPG) is added to a project.

Parameters:

name - Name of the encoded image resource.

Returns:

New EncodedImage object, or null if this method couldn't find your named resource.

Throws:

NullPointerException - If the name parameter is null.

Since:

JDE 4.2.0

getEncodedImageResource

public static EncodedImage getEncodedImageResource(String module,
                                                   String name)

Creates an encoded image from provided named resource found in module.

This method looks for the resource in both the .cod file that called this method and any .cod files that it relies on. The resource files are automatically generated by the compiler when a new graphic (PNG, GIF, or, JPG) is added to a project.

Parameters:

module - Name of the module containing the encoded image resource. If not specified, the name of the calling module is used.

name - Name of the encoded image resource.

Returns:

New EncodedImage object, or null if this method couldn't find your named resource.

Throws:

NullPointerException - If the name parameter is null.

Since:

JDE 4.2.0

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.

Since:

JDE 3.6.0

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.0

getFrameMonochrome

public boolean getFrameMonochrome(int frameIndex)

Returns true if the specified 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.0

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.0

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.0

getHeight

public int getHeight()

Returns the (unscaled) height of this image in pixels.

Returns:

The height in pixels.

Since:

JDE 3.6.0

getImageType

public int getImageType()

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

Returns:

The image type.

Since:

JDE 3.6.0

getLength

public final int getLength()

Returns the length of the encoded image data.

Returns:

The length of the encoded image data returned from getData.

Since:

JDE 3.7.0

getMIMEType

public abstract String getMIMEType()

Return the commonly known MIME type associate for this encoded image object.

Returns:

A String representing the MIME type generally associated with this object.

Since:

JDE 4.2.0

Category:

Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getOffset

public final int getOffset()

Returns the offset into the data where the encoded image begins.

Returns:

The offset into the result returned from getData.

Since:

JDE 3.7.0

getScale

public int getScale()

Gets the scale that is 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.

Returns:

The downscale factor.

Since:

JDE 3.7.0

getScaledFrameHeight

public int getScaledFrameHeight(int frameIndex)

Returns the scaled height in pixels of the specified frame.

Parameters:

frameIndex - The frame in question.

Returns:

The scaled height of the frame.

Since:

JDE 4.0.0

getScaledFrameWidth

public int getScaledFrameWidth(int frameIndex)

Returns the scaled width in pixels of the specified frame.

Parameters:

frameIndex - The frame in question.

Returns:

The scaled width of the frame.

Since:

JDE 4.0.0

getScaledHeight

public final int getScaledHeight()

Returns the scaled height of this image in pixels.

Returns:

The scaled height in pixels.

Since:

JDE 3.7.0

getScaledWidth

public final int getScaledWidth()

Returns the scaled width of this image in pixels.

Returns:

The scaled width in pixels.

Since:

JDE 3.7.0

getScaleX32

public int getScaleX32()

Gets the x scale that is to be used when decoding this image.

Returns:

A Fixed32 number representing the x-scaling factor (0 < scale < 1 for upscaling, scale > 1 for downscaling).

Since:

JDE 4.2.0

getScaleY32

public int getScaleY32()

Gets the y scale that is to be used when decoding this image.

Returns:

A Fixed32 number representing the y-scaling factor (0 < scale < 1 for upscaling, scale > 1 for downscaling).

Since:

JDE 4.2.0

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.

Since:

JDE 3.6.0

getWidth

public int getWidth()

Returns the (unscaled) width of this image in pixels.

Returns:

The width in pixels.

Since:

JDE 3.6.0

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.

Since:

JDE 3.6.0

isMIMETypeSupported

public static boolean isMIMETypeSupported(String mimeType)

Determines whether or not the specified MIME type is supported.

Parameters:

mimeType - the MIME type in question. It is not case sensitive.

Returns:

true if the specified MIME type is supported for decoding; false otherwise.

Throws:

NullPointerException - when mimeType is null

Since:

JDE 4.2.0

Category:

Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

isMonochrome

public boolean isMonochrome()

Returns true if 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.

Since:

JDE 3.6.0

scaleImage32

public EncodedImage scaleImage32(int scaleX,
                                 int scaleY)

Returns a copy of this encoded image, but with its x and y scales set to scaleX and scaleY, respectively. Both provided scale values must be Fixed32 numbers (0 < scale < 1 for upscaling, and scale > 1 for downscaling).

Parameters:

scaleX - The x-scaling factor (0 < scaleX < 1 for upscaling, and scaleX > 1 for downscaling). Must be a Fixed32 number.

scaleY - The y-scaling factor (0 < scaleY < 1 for upscaling, and scaleY > 1 for downscaling). Must be a Fixed32 number.

Returns:

A copy of this encoded image, but with its x and y scales set to scaleX and scaleY, respectively.

Throws:

IllegalArgumentException - if scaleX or scaleY is <= 0.

Since:

JDE 4.2.0

setDecodeMode

public void setDecodeMode(int decodeMode)

Sets the decoding mode for the image. The decode mode can be a combination of DECODE_ALPHA, DECODE_NATIVE, DECODE_NO_DITHER 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.0

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.

Throws:

IllegalArgumentException - Thrown if scale is less than 1.

Since:

JDE 3.6.0