SHOW Colour
 

net.rim.device.api.system
Class Bitmap

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

public final class Bitmap
extends Object

Encapsulates a Bitmap graphic usable for display on the device.

When constructing a bitmap object, you have the option to specify the type of encoding used.

 // Construct a blank bitmap object
 Bitmap bm = new Bitmap(Display.getWidth(), Display.getHeight());
 
 // Create a bitmap from provided name resource
 Bitmap _marker = Bitmap.getBitmapResource("marker.PNG");
 
 // Retrieve one of the predefined system bitmaps
 Bitmap original = Bitmap.getPredefinedBitmap(Bitmap.INFORMATION);
 
 // Create a bitmap from image data
 Bitmap image = Bitmap.createBitmapFromBytes( rawBytes, 0, -1, scale );
 
Use raw image data

To retrieve raw image data from a specified region of a bitmap and store the data in an integer array, invoke Bitmap.getARGB(). Applications can then manipulate the raw image data directly.

Initialize an integer array, and then invoke Bitmap.getARGB() to store the raw image data of the new or predefined bitmap in the integer array.

 Bitmap original = Bitmap.getPredefinedBitmap(Bitmap.INFORMATION);
 int[] argb = new int[original.getWidth() * original.getHeight()];
 original.getARGB(argb, 0, original.getWidth(), 0, 0, original.getWidth(), original.getHeight());
 
Compare two images:
 Invoke Bitmap.equals() to determine if the two bitmaps are identical.
 if(restored.equals(original)) 
 {
      
 }
 

See Also:
Bitmap.PNGInfo

Inner Class Summary
static class Bitmap.PNGInfo
          Provides additional information relevant for PNG bitmap graphics.
 
Field Summary
 Category: Colour static int ALPHA_BITDEPTH_8BPP
          8-bit Alpha Channel type identifier.
 Category: Colour static int ALPHA_BITDEPTH_MONO
          1-bit Alpha Channel type identifier.
  static int COLUMNWISE_MONOCHROME
          Columnwise, monochrome bitmap type.
  static int EXCLAMATION
          Predefined bitmap used for alert dialogs.
  static int HOURGLASS
          Predefined bitmap used for busy cursors.
  static int INFORMATION
          Predefined bitmap used for information dialogs.
  static int QUESTION
          Predefined bitmap used for query dialogs.
 Category: Colour static int ROWWISE_16BIT_COLOR
          Rowwise, color bitmap type.
 Category: Colour static int ROWWISE_MONOCHROME
          Rowwise, monochrome bitmap type.
  static int TRUE_BLACK
          The hexadecimal representation of pure black.
  static int TRUE_WHITE
          The hexadecimal representation of pure white.
 
Constructor Summary
Bitmap(int width, int height)
          Constructs a blank bitmap object.
Bitmap(int type, int width, int height)
          Constructs a blank bitmap object of a specific type.
Bitmap(int type, int width, int height, byte[] data)
          Constructs a new bitmap of a specific type from existing data.
 
Method Summary
 Category: Colour  void createAlpha(int bitDepth)
          Create the alpha map associated with this Bitmap.
  static Bitmap createBitmapFromBytes(byte[] bytes, int offset, int length, int scale)
          Creates a bitmap from image data.
  static Bitmap createBitmapFromPNG(byte[] png, int offset, int length)
          Creates a bitmap from provided PNG format data.
   boolean equals(Object obj)
          Tests if provided bitmap is equal to this bitmap.
 Category: Colour  void getARGB(int[] argbData, int offset, int scanLength, int x, int y, int width, int height)
          Gets raw ARGB data from region of this Bitmap and stores it in the provided array.
  static Bitmap getBitmapResource(String name)
          Creates a bitmap from provided name resource.
  static Bitmap getBitmapResource(String module, String name)
          Creates a bitmap from provided named resource found in module.
   int getBitsPerPixel()
          Get the bits per pixel of the bitmap.
  static int getDefaultType()
          Query the default Bitmap type for the device.
   int getHeight()
          Retrieves this bitmap's height.
  static Bitmap getPredefinedBitmap(int predefinedBitmap)
          Retrieves one of the predefined system bitmaps.
 Category: Colour  void getRGB565(byte[] rgbData, int offset, int scanLength, int x, int y, int width, int height)
          Gets raw 16-bit RGB 565 data from region of this Bitmap and stores it in the provided byte array (Big Endian format), i.e. byte[0] = RRRRRGGG, byte[1] = GGGBBBBB.
   int getType()
          Retrieves this bitmap's type.
   int getWidth()
          Retrieves this bitmap's width.
   boolean hasAlpha()
          Tests whether there is an alpha map associated with this Bitmap.
   boolean isWritable()
          Indicates whether the Bitmap object is read-only.
   void setARGB(int[] data, int offset, int scanLength, int left, int top, int width, int height)
          Changes the bitmap to match the data in the provided array.
 Category: Colour  void setRGB565(byte[] rgbData, int offset, int scanLength, int x, int y, int width, int height)
          Sets the bitmap colour data for a specified rectangular region using the provided raw 16-bit RGB 565 data array.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail


ALPHA_BITDEPTH_8BPP

public static final int ALPHA_BITDEPTH_8BPP
8-bit Alpha Channel type identifier.

Used as an input to createAlpha to create an 8-bit alpha channel (8 bit opacity per pixel).

Since:
JDE 4.0.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

ALPHA_BITDEPTH_MONO

public static final int ALPHA_BITDEPTH_MONO
1-bit Alpha Channel type identifier.

Used as an input to createAlpha to create a 1-bit alpha channel (1 bit opacity per pixel).

Since:
JDE 4.0.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

COLUMNWISE_MONOCHROME

public static final int COLUMNWISE_MONOCHROME
Columnwise, monochrome bitmap type.

This bitmap type stores data in pixel wide columns in successive bytes. Each bit in a byte is a pixel value: 0 is white and 1 is black. Uppermost pixels are in the less significant bits within a byte, and lower numbered bytes contain the uppermost pixels within a column.


EXCLAMATION

public static final int EXCLAMATION
Predefined bitmap used for alert dialogs.

HOURGLASS

public static final int HOURGLASS
Predefined bitmap used for busy cursors.

INFORMATION

public static final int INFORMATION
Predefined bitmap used for information dialogs.

QUESTION

public static final int QUESTION
Predefined bitmap used for query dialogs.

ROWWISE_16BIT_COLOR

public static final int ROWWISE_16BIT_COLOR
Rowwise, color bitmap type.

This bitmap type stores data in rows, with 2 bytes per pixel. A 0 is black and a 0xffff (65535) is white. Each row is padded (if necessary) so that each row is a multiple of 4 bytes in width.

Since:
JDE 3.7.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

ROWWISE_MONOCHROME

public static final int ROWWISE_MONOCHROME
Rowwise, monochrome bitmap type.

This bitmap type stores data in rows, with 1 bit per pixel. A 0 is black and 1 is white. Each row is a multiple of 4 bytes. Leftmost pixels are in the less significant bits within a byte, and lower numbered bytes contain the leftmost pixels within a row.

Since:
JDE 3.7.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

TRUE_BLACK

public static final int TRUE_BLACK
The hexadecimal representation of pure black.
Since:
JDE 3.6.0

TRUE_WHITE

public static final int TRUE_WHITE
The hexadecimal representation of pure white.
Since:
JDE 3.6.0
Constructor Detail

Bitmap

public Bitmap(int width,
              int height)
Constructs a blank bitmap object.

Parameters:
width - Width of this bitmap.
height - Height of this bitmap.
Throws:
IllegalArgumentException - Thrown if width or height parameters are invalid.

Bitmap

public Bitmap(int type,
              int width,
              int height)
Constructs a blank bitmap object of a specific type.

Parameters:
width - Width of this bitmap.
height - Height of this bitmap.
type - Type of this bitmap.
Throws:
IllegalArgumentException - Thrown if the width, height, or the type is invalid.

Bitmap

public Bitmap(int type,
              int width,
              int height,
              byte[] data)
Constructs a new bitmap of a specific type from existing data.

Note that this method makes a copy of your provided bitmap data.

This method requires that the provided data be consistent with the specified bitmap type and dimensions. This includes any necessary padding to ensure that stride breaks occur on DWORD (4-byte) boundaries.

Parameters:
type - Type of this bitmap.
width - Width of this bitmap.
height - Height of this bitmap.
data - Data from which to build this bitmap.
Throws:
IllegalArgumentException - Thrown if the length of the data array is incorrect, the width or height are invalid, or the type is invalid.
Method Detail

createAlpha

public void createAlpha(int bitDepth)
Create the alpha map associated with this Bitmap.

Alpha maps can only be set for Bitmaps of type ROWWISE_16BIT_COLOR. The alpha Bitmap bitdepth must be ALPHA_BITDEPTH_MONO or ALPHA_BITDEPTH_8BPP, be the same width and height as the image Bitmap, and must not have an a Bitmap itself.

Parameters:
bitDepth - The bitdepth (pixels per bit) of the alpha data.
Throws:
IllegalArgumentException - If the bitdepth is not valid.
Since:
JDE 4.2.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

createBitmapFromBytes

public static Bitmap createBitmapFromBytes(byte[] bytes,
                                           int offset,
                                           int length,
                                           int scale)
Creates a bitmap from image data. See EncodedImage.getSupportedMIMETypes to determine what image formats are supported.

The image can be optionally downscaled during decoding by an integer scale factor.

Parameters:
bytes - Image data.
offset - Start of image data in the passed byte array.
length - Length of image data in the passed byte array: -1 means to the end of the data array.
scale - Integer downscale factor: 1 means no scaling.
Returns:
New bitmap.
Throws:
OutOfMemoryError - If insufficient memory to process the image data into a bitmap.
NullPointerException - If the bytes parameter is null.
IllegalArgumentException - If the bytes parameter is invalid, offset or length are invalid.
ArithmeticException - is scale is 0.

createBitmapFromPNG

public static Bitmap createBitmapFromPNG(byte[] png,
                                         int offset,
                                         int length)
Creates a bitmap from provided PNG format data.

Parameters:
png - PNG data.
offset - Start of PNG data in the passed byte array.
length - Length of PNG data in the passed byte array: -1 means to the end of the data array.
Returns:
New Bitmap object.
Throws:
OutOfMemoryError - Thrown if insufficient memory to process the PNG data into a bitmap.
NullPointerException - Thrown if the png parameter is null.
IllegalArgumentException - Thrown if the png parameter is invalid, or offset or length are invalid.

equals

public boolean equals(Object obj)
Tests if provided bitmap is equal to this bitmap.

A bitmap is equal to another if the types are the same, the dimensions are the same, and the data is the same.

Overrides:
equals in class Object
Parameters:
obj - The object to compare to this bitmap.
Returns:
True if your obj parameter is equivalent to this bitmap; otherwise, false.

getARGB

public void getARGB(int[] argbData,
                    int offset,
                    int scanLength,
                    int x,
                    int y,
                    int width,
                    int height)
Gets raw ARGB data from region of this Bitmap and stores it in the provided array.
Parameters:
argbData - Array of data where the ARGB data will be stored. Each pixel is stored in 0xAARRGGBB format.
offset - Offset into the data to start writing to.
scanLength - Width of a scanline within the data array.
x - Left edge of rectangle to copy from.
y - Top edge of the rectangle to copy from.
width - Width of the rectangle to copy from.
height - Height of the rectangle to copy from.
Throws:
NullPointerException - Thrown if 'argbData' is null.
ArrayIndexOutOfBoundsException - Thrown if the data parameters are invalid.
Since:
JDE 3.7.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

getBitmapResource

public static Bitmap getBitmapResource(String name)
Creates a bitmap 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 bitmap resource.
Returns:
New Bitmap object, or null if this method couldn't find your named resource.
Throws:
NullPointerException - If the name parameter is null.

getBitmapResource

public static Bitmap getBitmapResource(String module,
                                       String name)
Creates a bitmap 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 bitmap resource. If not specified, the name of the calling module is used.
name - Name of the bitmap resource.
Returns:
New Bitmap object, or null if this method couldn't find your named resource.
Throws:
NullPointerException - If the name parameter is null.

getBitsPerPixel

public int getBitsPerPixel()
Get the bits per pixel of the bitmap.

Returns:
Bit depth of bitmap.
Since:
JDE 3.7.0

getDefaultType

public static int getDefaultType()
Query the default Bitmap type for the device.
Returns:
The type of the natural device Bitmap.
Since:
JDE 3.6.0

getHeight

public int getHeight()
Retrieves this bitmap's height.

Returns:
Height of this bitmap in pixels.

getPredefinedBitmap

public static Bitmap getPredefinedBitmap(int predefinedBitmap)
Retrieves one of the predefined system bitmaps.

Parameters:
predefinedBitmap - System graphic to retrieve. If you specify a value not currently assigned to a standard system bitmap, this method returns the INFORMATION bitmap.
Returns:
New Bitmap object equivalent to the system graphic you specify.

getRGB565

public void getRGB565(byte[] rgbData,
                      int offset,
                      int scanLength,
                      int x,
                      int y,
                      int width,
                      int height)
Gets raw 16-bit RGB 565 data from region of this Bitmap and stores it in the provided byte array (Big Endian format), i.e. byte[0] = RRRRRGGG, byte[1] = GGGBBBBB. This Bitmap must be of type ROWWISE_16BIT_COLOR.
Parameters:
rgbData - Array of data where the 16-bit RGB 565 data will be stored in Big Endian format.
offset - Offset into the data to start writing to.
scanLength - Width of a scanline (in bytes) within the data array.
x - Left edge of rectangle to copy from.
y - Top edge of the rectangle to copy from.
width - Width of the rectangle to copy from.
height - Height of the rectangle to copy from.
Throws:
NullPointerException - Thrown if 'rgbData' is null.
IllegalArgumentException - Thrown if the data parameters are invalid or if this Bitmap is wrong type.
Since:
JDE 4.6.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.

getType

public int getType()
Retrieves this bitmap's type.

Returns:
Type of this bitmap.

getWidth

public int getWidth()
Retrieves this bitmap's width.

Returns:
Width of this bitmap in pixels.

hasAlpha

public boolean hasAlpha()
Tests whether there is an alpha map associated with this Bitmap.
Returns:
True if this Bitmap has transparency information.
Since:
JDE 3.6.0

isWritable

public boolean isWritable()
Indicates whether the Bitmap object is read-only.

Readonly bitmaps cannot be drawn to by attaching a Graphics object.

Returns:
True if the Bitmap object is writable, false if it is read-only.
Since:
JDE 3.6.0

setARGB

public void setARGB(int[] data,
                    int offset,
                    int scanLength,
                    int left,
                    int top,
                    int width,
                    int height)
Changes the bitmap to match the data in the provided array.
Parameters:
data - Array of ARGB data that will be used as the new bitmap data. Each pixel is stored in 0xAARRGGBB format.
offset - Offset into the data to start writing to.
scanLength - Width of a scanline within the data array.
left - Start x position in bitmap for ARGB data.
top - Start y position in bitmap for ARGB data.
width - Width of ARGB data.
height - Height of ARGB data.
Throws:
NullPointerException - if 'data' is null.
IllegalArgumentException - if data/coordinates(top,left,width,height) are invalid or bitmap is read-only
Since:
JDE 3.7.0

setRGB565

public void setRGB565(byte[] rgbData,
                      int offset,
                      int scanLength,
                      int x,
                      int y,
                      int width,
                      int height)
Sets the bitmap colour data for a specified rectangular region using the provided raw 16-bit RGB 565 data array.

The RGB565 data is provided in a byte array (Big Endian format), i.e. byte[0] = RRRRRGGG, byte[1] = GGGBBBBB.

This is only supported for bitmaps of type ROWWISE_16BIT_COLOR. This method has no effect on a bitmap that is not of this type.

The source data must be sufficient to provide data for the specified destination region. The destination region must be fully contained within the current bitmap.

Parameters:
rgbData - Array of source 16-bit RGB 565 data will be stored in Big Endian format.
offset - Starting offset (bytes) for the source data.
scanLength - Width of a scanline (in bytes) within the data array.
x - Left edge of destination rectangle.
y - Top edge of the destination rectangle.
width - Width of the destination rectangle.
height - Height of the destination rectangle.
Throws:
NullPointerException - Thrown if 'rgbData' is null.
IllegalArgumentException - Thrown if the data parameters are invalid.
Since:
JDE 4.6.0
Category:
Colour: Pertains to devices' ability to display colour. May only be applicable on colour devices.



Copyright 1999-2008 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.