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.

 // Create an EncodedImage from bytes
 EncodedImage image = EncodedImage.createEncodedImage(imageData, 0, imageData.length);
 screen.add(new BitmapField(image.getBitmap()));

 // Create an encoded image from provided name resource
 EncodedImage  eImage = EncodedImage.getEncodedImageResource( "img/new.png" )

 // A scaled EncodedImage
 EncodedImage  scaledIcon = icon.scaleImage32( scaleX, scaleY );
 

Set the decoding mode

Invoke EncodedImage.setDecodeMode() to set the decoding mode of the image. Provide one of the following modes as a parameter to the method:

DECODE_ALPHA: Decodes an alpha channel, if one exists (this is the default mode)
DECODE_NATIVE: Forces the bitmap to be decoded to the native bitmap type of the handheld software
DECODE_READONLY: Marks the decoded bitmap as read-only

Set the scaling factor

To set the integer factor that is used to downscale an image when decoding, invoke EncodedImage.setScale(). The image is scaled by the inverse of the integer specified by the scale parameter. For example, if you set the scaling factor to 2, the image is decoded at 50% of its original size.

See Also:

PNGEncodedImage, JPEGEncodedImage, GIFEncodedImage, WBMPEncodedImage, BMPEncodedImage, TIFFEncodedImage, ICOEncodedImage

Since:

BlackBerry API 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_ICO Indicates that an image is encoded in the ICO 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.
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	getImageHeight(int scaledHeight) Returns the source image height of scaledHeight in pixels.
int	getImageType() Returns this image's encoding format.
int	getImageWidth(int scaledWidth) Returns the source image width of scaledWidth in pixels.
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.
MetaDataControl	getMetaData() Gets the metadata for this image.
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	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.
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	getScaledHeight(int srcHeight) Returns the scaled height of srcHeight image in pixels.
int	getScaledWidth() Returns the scaled width of this image in pixels.
int	getScaledWidth(int srcWidth) Returns the scaled width of srcWidth in pixels.
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.
boolean	isAnimated() Returns true if the image is considered animated.
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.
EncodedImage	scaleImageToFill(int desiredWidth, int desiredHeight) Returns a copy of this EncodedImage scaled to fill the desired dimensions Note: This method does not crop the image (the image can remain larger than one of the desired dimensions).
void	setDecodeMode(int decodeMode) Sets the decoding mode for the image.
void	setScale(int scale) Deprecated. Use EncodedImage.scaleImage32(int, int)

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.

See Also:

Constant Field Values

Since:

BlackBerry API 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.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

DECODE_READONLY

public static final int DECODE_READONLY

Marks the decoded bitmap as readonly.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

DECODE_NO_DITHER

public static final int DECODE_NO_DITHER

Don't dither when decoding.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

IMAGE_TYPE_GIF

public static final int IMAGE_TYPE_GIF

Indicates that an image is encoded in the GIF format.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

IMAGE_TYPE_PNG

public static final int IMAGE_TYPE_PNG

Indicates that an image is encoded in the PNG format.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

IMAGE_TYPE_JPEG

public static final int IMAGE_TYPE_JPEG

Indicates that an image is encoded in the JPEG format.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

IMAGE_TYPE_WBMP

public static final int IMAGE_TYPE_WBMP

Indicates that an image is encoded in the WBMP format.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

IMAGE_TYPE_BMP

public static final int IMAGE_TYPE_BMP

Indicates that an image is encoded in the BMP format.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

IMAGE_TYPE_TIFF

public static final int IMAGE_TYPE_TIFF

Indicates that an image is encoded in the TIFF format.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

IMAGE_TYPE_ICO

public static final int IMAGE_TYPE_ICO

Indicates that an image is encoded in the ICO format.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.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.

See Also:

PNGEncodedImage, JPEGEncodedImage, GIFEncodedImage, WBMPEncodedImage, BMPEncodedImage, TIFFEncodedImage, ICOEncodedImage

Since:

BlackBerry API 3.6.0

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"
• "image/jpg"
• "image/pjpeg"
• "image/bmp"
• "image/tiff"

Throws:

IllegalArgumentException - Thrown if the specified mime type is invalid.

Since:

BlackBerry API 3.6.0

getAlphaType

public final 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 3.6.0

isAnimated

public boolean isAnimated()

Returns true if the image is considered animated.

Returns:

true if the image is considered animated.

Since:

BlackBerry API 6.0.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:

BlackBerry API 3.6.0

getFrameMonochrome

public boolean getFrameMonochrome(int frameIndex)

Returns true if the specified frame is monochrome. If the only two colors 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 3.6.0

getHeight

public int getHeight()

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

Returns:

The height in pixels.

Since:

BlackBerry API 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:

BlackBerry API 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.

See Also:

EncodedImage.getOffset()

Since:

BlackBerry API 3.7.0

getMetaData

public MetaDataControl getMetaData()

Gets the metadata for this image. This operation may be expensive, and implementation may want to cache the results for the purpose of indexing or searching.

Returns:

Since:

BlackBerry API 4.5.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:

BlackBerry API 4.2.0

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.

See Also:

EncodedImage.getLength()

Since:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 4.0.0

getScaledHeight

public final int getScaledHeight()

Returns the scaled height of this image in pixels.

Returns:

The scaled height in pixels.

Since:

BlackBerry API 3.7.0

getScaledWidth

public final int getScaledWidth()

Returns the scaled width of this image in pixels.

Returns:

The scaled width in pixels.

Since:

BlackBerry API 3.7.0

getScaledWidth

public final int getScaledWidth(int srcWidth)

Returns the scaled width of srcWidth in pixels.

Returns:

The scaled width in pixels.

Since:

BlackBerry API 5.0.0

getScaledHeight

public final int getScaledHeight(int srcHeight)

Returns the scaled height of srcHeight image in pixels.

Returns:

The scaled height in pixels.

Since:

BlackBerry API 5.0.0

getImageWidth

public final int getImageWidth(int scaledWidth)

Returns the source image width of scaledWidth in pixels.

Returns:

The scaled width in pixels.

Since:

BlackBerry API 5.0.0

getImageHeight

public final int getImageHeight(int scaledHeight)

Returns the source image height of scaledHeight in pixels.

Returns:

The scaled height in pixels.

Since:

BlackBerry API 5.0.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:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 3.6.0

getWidth

public int getWidth()

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

Returns:

The width in pixels.

Since:

BlackBerry API 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:

BlackBerry API 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:

BlackBerry API 4.2.0

isMonochrome

public boolean isMonochrome()

Returns true if this is a monochrome image. If the only two colors 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:

BlackBerry API 3.6.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:

BlackBerry API 3.6.0

setScale

public void setScale(int scale)

Deprecated. Use EncodedImage.scaleImage32(int, int)

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:

BlackBerry API 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:

BlackBerry API 4.2.0

scaleImageToFill

public EncodedImage scaleImageToFill(int desiredWidth,
                                     int desiredHeight)

Returns a copy of this EncodedImage scaled to fill the desired dimensions

Note: This method does not crop the image (the image can remain larger than one of the desired dimensions). Note 2: This method will not stretch the encoded image. If either original dimension is smaller than the desired the image will not be scaled.

Parameters:

desiredWidth - the desired width in pixels of the encoded image

desiredHeight - the deisred height in pixels of the encoded image

Returns:

new EncodedImage filling the desiredWidth and desiredHeight subject to the Notes in the description of this function.

Throws:

IllegalArgumentException - if desiredWidth or desiredHeight is <= 0.

Since:

BlackBerry API 7.0.0