Build 1.0_r1(from source)

android.graphics
Class Bitmap

java.lang.Object
  extended by android.graphics.Bitmap
All Implemented Interfaces:
Parcelable

public final class Bitmap
extends Object
implements Parcelable


Nested Class Summary
static class Bitmap.CompressFormat
          Specifies the known formats a bitmap can be compressed into
static class Bitmap.Config
           
 
Nested classes/interfaces inherited from interface android.os.Parcelable
Parcelable.Creator<T>
 
Field Summary
static Parcelable.Creator<Bitmap> CREATOR
           
 
Fields inherited from interface android.os.Parcelable
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
 
Method Summary
 boolean compress(Bitmap.CompressFormat format, int quality, OutputStream stream)
          Write a compressed version of the bitmap to the specified outputstream.
 Bitmap copy(Bitmap.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.
 void copyPixelsToBuffer(Buffer dst)
          Copy the bitmap's pixels into the specified buffer (allocated by the caller).
static Bitmap createBitmap(Bitmap src)
          Returns an immutable bitmap from the source bitmap.
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.
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[] colors, int width, int height, Bitmap.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(int[] colors, int offset, int stride, int width, int height, Bitmap.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(int width, int height, Bitmap.Config config)
          Returns a mutable bitmap with the specified width and height.
static Bitmap createScaledBitmap(Bitmap src, int dstWidth, int dstHeight, boolean filter)
           
 int describeContents()
          No special parcel contents.
 void eraseColor(int c)
          Fills the bitmap's pixels with the specified Color.
 Bitmap extractAlpha()
          Returns a new bitmap that captures the alpha values of the original.
 Bitmap extractAlpha(Paint paint, int[] offsetXY)
          Returns a new bitmap that captures the alpha values of the original.
protected  void finalize()
          Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
 Bitmap.Config getConfig()
          If the bitmap's internal config is in one of the public formats, return that config, otherwise return null.
 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.
 int getRowBytes()
          Return the number of bytes between rows in the bitmap's pixels.
 int getWidth()
          Returns the bitmap's width
 boolean hasAlpha()
          Returns true if the bitmap's pixels support levels of alpha
 boolean isMutable()
          Returns true if the bitmap is marked as mutable (i.e.
 boolean isRecycled()
          Returns true if this bitmap has been recycled.
(package private)  int ni()
           
 void recycle()
          Free up the memory associated with this bitmap's pixels, and mark the bitmap as "dead", meaning it will throw an exception if getPixels() or setPixels() is called, and will draw nothing.
 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.
 void writeToParcel(Parcel p, int flags)
          Write the bitmap and its pixels to the parcel.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CREATOR

public static final Parcelable.Creator<Bitmap> CREATOR
Method Detail

recycle

public void recycle()
Free up the memory associated with this bitmap's pixels, and mark the bitmap as "dead", meaning it will throw an exception if getPixels() or setPixels() is called, and will draw nothing. This operation cannot be reversed, so it should only be called if you are sure there are no further uses for the bitmap. This is an advanced call, and normally need not be called, since the normal GC process will free up this memory when there are no more references to this bitmap.


isRecycled

public final boolean isRecycled()
Returns true if this bitmap has been recycled. If so, then it is an error to try to access its pixels, and the bitmap will not draw.

Returns:
true if the bitmap has been recycled

copyPixelsToBuffer

public void copyPixelsToBuffer(Buffer dst)
Copy the bitmap's pixels into the specified buffer (allocated by the caller). An exception is thrown if the buffer is not large enough to hold all of the pixels (taking into account the number of bytes per pixel) or if the Buffer subclass is not one of the support types (ByteBuffer, ShortBuffer, IntBuffer).


copy

public Bitmap copy(Bitmap.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.

createScaledBitmap

public static Bitmap createScaledBitmap(Bitmap src,
                                        int dstWidth,
                                        int dstHeight,
                                        boolean filter)

createBitmap

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.


createBitmap

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

createBitmap

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.

createBitmap

public static Bitmap createBitmap(int width,
                                  int height,
                                  Bitmap.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 <=>

createBitmap

public static Bitmap createBitmap(int[] colors,
                                  int offset,
                                  int stride,
                                  int width,
                                  int height,
                                  Bitmap.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.
offset - Number of values to skip before the first color in the array of colors.
stride - Number of colors in the array between rows (must be >= width or <=>
width - The width of the bitmap
height - The height of the bitmap
config - The bitmap config to create. If the config does not support per-pixel alpha (e.g. RGB_565), then the alpha bytes in the colors[] will be ignored (assumed to be FF)
Throws:
IllegalArgumentException - if the width or height are <= 0,="" or="" if="" the="" color="" array's="" length="" is="" less="" than="" the="" number="" of="">

createBitmap

public static Bitmap createBitmap(int[] colors,
                                  int width,
                                  int height,
                                  Bitmap.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. If the config does not support per-pixel alpha (e.g. RGB_565), then the alpha bytes in the colors[] will be ignored (assumed to be FF)
Throws:
IllegalArgumentException - if the width or height are <= 0,="" or="" if="" the="" color="" array's="" length="" is="" less="" than="" the="" number="" of="">

getNinePatchChunk

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.


compress

public boolean compress(Bitmap.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).

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. Some formats, like PNG which is lossless, will ignore the quality setting
stream - The outputstream to write the compressed data.
Returns:
true if successfully compressed to the specified stream.

isMutable

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


getWidth

public final int getWidth()
Returns the bitmap's width


getHeight

public final int getHeight()
Returns the bitmap's height


getRowBytes

public final int getRowBytes()
Return the number of bytes between rows in the bitmap's pixels. Note that this refers to the pixels as stored natively by the bitmap. If you call getPixels() or setPixels(), then the pixels are uniformly treated as 32bit values, packed according to the Color class.

Returns:
number of bytes between rows of the native bitmap pixels.

getConfig

public final Bitmap.Config getConfig()
If the bitmap's internal config is in one of the public formats, return that config, otherwise return null.


hasAlpha

public final boolean hasAlpha()
Returns true if the bitmap's pixels support levels of alpha


eraseColor

public void eraseColor(int c)
Fills the bitmap's pixels with the specified Color.

Throws:
IllegalStateException - if the bitmap is not mutable.

getPixel

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

getPixels

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.

setPixel

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.

setPixels

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.

describeContents

public int describeContents()
No special parcel contents.

Specified by:
describeContents in interface Parcelable
Returns:
a bitmask indicating the set of special object types marshalled by the Parcelable.

writeToParcel

public void writeToParcel(Parcel p,
                          int flags)
Write the bitmap and its pixels to the parcel. The bitmap can be rebuilt from the parcel by calling CREATOR.createFromParcel().

Specified by:
writeToParcel in interface Parcelable
Parameters:
p - Parcel object to write the bitmap data into
flags - Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE.

extractAlpha

public Bitmap extractAlpha()
Returns a new bitmap that captures the alpha values of the original. This may be drawn with Canvas.drawBitmap(), where the color(s) will be taken from the paint that is passed to the draw call.

Returns:
new bitmap containing the alpha channel of the original bitmap.

extractAlpha

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.

finalize

protected void finalize()
                 throws Throwable
Description copied from class: Object
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.

Overrides:
finalize in class Object
Throws:
Throwable - The virtual machine ignores any exceptions which are thrown during finalization.

ni

final int ni()

Build 1.0_r1(from source)

Please submit a feedback, bug or feature