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.

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

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.
   MetaDataControl getMetaData()
          Gets the metadata for this image.
 Category: Colour Category: Framework 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.
 Category: Colour Category: Framework 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)
          Deprecated. Use scaleImage32
 
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

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:
JDE 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:
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)
Deprecated. Use scaleImage32

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



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.