English | Site Directory

Android - An Open Handset Alliance Project

android.graphics
public final class

android.graphics.Bitmap

java.lang.Object
android.graphics.Bitmap Parcelable
Nested Classes
Bitmap.CompressFormat Specifies the known formats a bitmap can be compressed into  
Bitmap.Config  

Summary

Constants

      Value  
Creator  CREATOR       

Public Methods

        void  buildMipMap(boolean forceRebuild)
Builds an associated mipmap for this Bitmap.
        boolean  compress(CompressFormat format, int quality, OutputStream stream)
Write a compressed version of the bitmap to the specified outputstream.
        Bitmap  copy(Config config, boolean isMutable)
Tries to make a new bitmap based on the dimensions of this bitmap, setting the new bitmap's config to the one specified, and then copying this bitmap's pixels into the new bitmap.
      static  Bitmap  createBitmap(int width, int height, boolean hasAlpha)
      static  Bitmap  createBitmap(Bitmap src)
Returns an immutable bitmap from the source bitmap.
      static  Bitmap  createBitmap(int[] colors, int width, int height, Config config)
Returns a immutable bitmap with the specified width and height, with each pixel value set to the corresponding value in the colors array.
      static  Bitmap  createBitmap(Bitmap source, int x, int y, int width, int height, Matrix m, boolean filter)
Returns an immutable bitmap from subset of the source bitmap, transformed by the optional matrix.
      static  Bitmap  createBitmap(int width, int height, Config config)
Returns a mutable bitmap with the specified width and height.
      static  Bitmap  createBitmap(Bitmap source, int x, int y, int width, int height)
Returns an immutable bitmap from the specified subset of the source bitmap.
        void  eraseColor(int c)
Fills the bitmap's pixels with the specified Color.
        Bitmap  extractAlpha()
Returns a new bitmap of the same dimensions as the original, but whose pixels represent the corresponding alpha values of the original.
        Bitmap  extractAlpha(Paint paint, int[] offsetXY)
Returns a new bitmap that captures the alpha values of the original.
    final    int  getHeight()
Returns the bitmap's height
        byte[]  getNinePatchChunk()
Returns an optional array of private data, used by the UI system for some bitmaps.
        int  getPixel(int x, int y)
Returns the Color at the specified location.
        void  getPixels(int[] pixels, int offset, int stride, int x, int y, int width, int height)
Returns in pixels[[]] a copy of the data in the bitmap.
    final    int  getWidth()
Returns the bitmap's width
    final    boolean  hasAlpha()
Returns true if the bitmap's pixels support levels of alpha
        boolean  hasMipMap()
Returns true if the Bitmap has an associated mipmap.
        int  height()
    final    boolean  isMutable()
Returns true if the bitmap is marked as mutable (i.e.
        void  removeMipMap()
Remove the associated mipmap (if any) from this Bitmap.
        void  setPixel(int x, int y, int color)
Write the specified Color into the bitmap (assuming it is mutable) at the x,y coordinate.
        void  setPixels(int[] pixels, int offset, int stride, int x, int y, int width, int height)
Replace pixels in the bitmap with the colors in the array.
        int  width()
        void  writeToParcel(Parcel p)
Write the bitmap and its pixels to the parcel.

Protected Methods

        void  finalize()
Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
Methods inherited from class java.lang.Object
Methods inherited from interface android.os.Parcelable

Details

Constants

public static final Creator CREATOR

Public Methods

public void buildMipMap(boolean forceRebuild)

Builds an associated mipmap for this Bitmap. If there is already a mipmap and forceBuild is false, then nothing happens (the previous mipmap is preserved.)

public boolean compress(CompressFormat format, int quality, OutputStream stream)

Write a compressed version of the bitmap to the specified outputstream. If this returns true, the bitmap can be reconstructed by passing a corresponding inputstream to BitmapFactory.decodeStream(). Note: not all Formats support all bitmap configs directly, so it is possible that the returned bitmap from BitmapFactory could be in a different bitdepth, and/or may have lost per-pixel alpha (e.g. JPEG only supports opaque pixels). The ZLIB format is guaranteed to never change the config of the bitmap returned by BitmapFactory.

Parameters

format The format of the compressed image
quality Hint to the compressor, 0-100. 0 meaning compress for small size, 100 meaning compress for max quality.
stream The outputstream to write the compressed data.

Returns

  • true if successfully compressed to the specified stream.

public Bitmap copy(Config config, boolean isMutable)

Tries to make a new bitmap based on the dimensions of this bitmap, setting the new bitmap's config to the one specified, and then copying this bitmap's pixels into the new bitmap. If the conversion is not supported, or the allocator fails, then this returns NULL.

Parameters

config The desired config for the resulting bitmap
isMutable True if the resulting bitmap should be mutable (i.e. its pixels can be modified)

Returns

  • the new bitmap, or null if the copy could not be made.

public static Bitmap createBitmap(int width, int height, boolean hasAlpha)

public static Bitmap createBitmap(Bitmap src)

Returns an immutable bitmap from the source bitmap. The new bitmap may be the same object as source, or a copy may have been made.

public static Bitmap createBitmap(int[] colors, int width, int height, Config config)

Returns a immutable bitmap with the specified width and height, with each pixel value set to the corresponding value in the colors array.

Parameters

colors Array of Color used to initialize the pixels. This array must be at least as large as width * height.
width The width of the bitmap
height The height of the bitmap
config The bitmap config to create.

Throws

IllegalArgumentException if the width or height are <= 0, or if the color array's length is less than the number of pixels.

public static Bitmap createBitmap(Bitmap source, int x, int y, int width, int height, Matrix m, boolean filter)

Returns an immutable bitmap from subset of the source bitmap, transformed by the optional matrix.

Parameters

source The bitmap we are subsetting
x The x coordinate of the first pixel in source
y The y coordinate of the first pixel in source
width The number of pixels in each row
height The number of rows
m Option matrix to be applied to the pixels
filter true if the source should be filtered. Only applies if the matrix contains more than just translation.

Returns

  • A bitmap that represents the specified subset of source

Throws

IllegalArgumentException if the x, y, width, height values are outside of the dimensions of the source bitmap.

public static Bitmap createBitmap(int width, int height, Config config)

Returns a mutable bitmap with the specified width and height.

Parameters

width The width of the bitmap
height The height of the bitmap
config The bitmap config to create.

Throws

IllegalArgumentException if the width or height are <= 0

public static Bitmap createBitmap(Bitmap source, int x, int y, int width, int height)

Returns an immutable bitmap from the specified subset of the source bitmap. The new bitmap may be the same object as source, or a copy may have been made.

Parameters

source The bitmap we are subsetting
x The x coordinate of the first pixel in source
y The y coordinate of the first pixel in source
width The number of pixels in each row
height The number of rows

public void eraseColor(int c)

Fills the bitmap's pixels with the specified Color.

Throws

IllegalStateException if the bitmap is not mutable.

public Bitmap extractAlpha()

Returns a new bitmap of the same dimensions as the original, but whose pixels represent the corresponding alpha values of the original. The color values for each pixel will be black, but their alpha will match the original.

public Bitmap extractAlpha(Paint paint, int[] offsetXY)

Returns a new bitmap that captures the alpha values of the original. These values may be affected by the optional Paint parameter, which can contain its own alpha, and may also contain a MaskFilter which could change the actual dimensions of the resulting bitmap (e.g. a blur maskfilter might enlarge the resulting bitmap). If offsetXY is not null, it returns the amount to offset the returned bitmap so that it will logically align with the original. For example, if the paint contains a blur of radius 2, then offsetXY[] would contains -2, -2, so that drawing the alpha bitmap offset by (-2, -2) and then drawing the original would result in the blur visually aligning with the original.

Parameters

paint Optional paint used to modify the alpha values in the resulting bitmap. Pass null for default behavior.
offsetXY Optional array that returns the X (index 0) and Y (index 1) offset needed to position the returned bitmap so that it visually lines up with the original.

Returns

  • new bitmap containing the (optionally modified by paint) alpha channel of the original bitmap. This may be drawn with Canvas.drawBitmap(), where the color(s) will be taken from the paint that is passed to the draw call.

public final int getHeight()

Returns the bitmap's height

public byte[] getNinePatchChunk()

Returns an optional array of private data, used by the UI system for some bitmaps. Not intended to be called by applications.

public int getPixel(int x, int y)

Returns the Color at the specified location. Throws an exception if x or y are out of bounds (negative or >= to the width or height respectively).

Parameters

x The x coordinate (0...width-1) of the pixel to return
y The y coordinate (0...height-1) of the pixel to return

Returns

  • The argb Color at the specified coordinate

Throws

IllegalArgumentException if x, y exceed the bitmap's bounds

public void getPixels(int[] pixels, int offset, int stride, int x, int y, int width, int height)

Returns in pixels[] a copy of the data in the bitmap. Each value is a packed int representing a Color. The stride parameter allows the caller to allow for gaps in the returned pixels array between rows. For normal packed results, just pass width for the stride value.

Parameters

pixels The array to receive the bitmap's colors
offset The first index to write into pixels[]
stride The number of entries in pixels[] to skip between rows (must be >= bitmap's width). Can be negative.
x The x coordinate of the first pixel to read from the bitmap
y The y coordinate of the first pixel to read from the bitmap
width The number of pixels to read from each row
height The number of rows to read

Throws

IllegalArgumentException if x, y, width, height exceed the bounds of the bitmap, or if abs(stride) < width.
ArrayIndexOutOfBoundsException if the pixels array is too small to receive the specified number of pixels.

public final int getWidth()

Returns the bitmap's width

public final boolean hasAlpha()

Returns true if the bitmap's pixels support levels of alpha

public boolean hasMipMap()

Returns true if the Bitmap has an associated mipmap.

public int height()

public final boolean isMutable()

Returns true if the bitmap is marked as mutable (i.e. can be drawn into)

public void removeMipMap()

Remove the associated mipmap (if any) from this Bitmap.

public void setPixel(int x, int y, int color)

Write the specified Color into the bitmap (assuming it is mutable) at the x,y coordinate.

Parameters

x The x coordinate of the pixel to replace (0...width-1)
y The y coordinate of the pixel to replace (0...height-1)
color The Color to write into the bitmap

Throws

IllegalStateException if the bitmap is not mutable
IllegalArgumentException if x, y are outside of the bitmap's bounds.

public void setPixels(int[] pixels, int offset, int stride, int x, int y, int width, int height)

Replace pixels in the bitmap with the colors in the array. Each element in the array is a packed int prepresenting a Color

Parameters

pixels The colors to write to the bitmap
offset The index of the first color to read from pixels[]
stride The number of colors in pixels[] to skip between rows. Normally this value will be the same as the width of the bitmap, but it can be larger (or negative).
x The x coordinate of the first pixel to write to in the bitmap.
y The y coordinate of the first pixel to write to in the bitmap.
width The number of colors to copy from pixels[] per row
height The number of rows to write to the bitmap

Throws

IllegalStateException if the bitmap is not mutable
IllegalArgumentException if x, y, width, height are outside of the bitmap's bounds.
ArrayIndexOutOfBoundsException if the pixels array is too small to receive the specified number of pixels.

public int width()

public void writeToParcel(Parcel p)

Write the bitmap and its pixels to the parcel. The bitmap can be rebuilt from the parcel by calling CREATOR.createFromParcel().

Parameters

p Parcel object to write the bitmap data into

Protected Methods

protected void finalize()

Called by the virtual machine when there are no longer any (non-weak) references to the receiver. Subclasses can use this facility to guarantee that any associated resources are cleaned up before the receiver is garbage collected. Uncaught exceptions which are thrown during the running of the method cause it to terminate immediately, but are otherwise ignored.

Note: The virtual machine assumes that the implementation in class Object is empty.

Throws

Throwable
Build m5-rc15g - 14 May 2008 12:50