Android中文API（136） —— Bitmap

前言

　　本章内容android.graphics.Bitmap章节，译为"位图"，版本为Android 4.0 r1，翻译来自："StreamH"，欢迎访问他的博客："http://blog.csdn.net/qs_csu "，再次感谢"StreamH" ！期待你一起参与翻译Android的相关资料，联系我over140@gmail.com。

声明

　　欢迎转载，但请保留文章原始出处:)

　　　　博客园：http://www.cnblogs.com/

　　　　Android中文翻译组：http://androidbox.sinaapp.com/

Bitmap

译者署名：StreamH

译者链接：http://blog.csdn.net/qs_csu

版本：Android 4.0 r1

结构

继承关系

public class Bitmap extends Object implements Parcelable

java.lang.Object

android.graphics.Bitmap

内部类

　　enum Bitmap.CompressFormat

　　详细说明位图的压缩格式

　　enum Bitmap.Config

　　位图的结构

常量

Int DENSITY_NONE

标志着该位图是以未知的像素密度创建的

参见

getDensity()

setDensity(int)

公共方法

boolean compress(Bitmap.CompressFormat format, int quality, OutputStream stream)

把位图的压缩信息写入到一个指定的输出流中。如果返回true，可以通过传递一个相应的输出流到BitmapFactory.decodeStream()来重构该位图。注意：并非所有的格式都直接支持位图结构，所以通过BitmapFactory返回的位图很可能有不同的位深度，或许会丢失每个象素的alpha值(例如，JPEG 只支持不透明像素)。

（译者注：色深(color depth),也称色位深度(bitdePth),是指在一定分辨率下一个像素能够接受的颜色数量范围。通常,色深用2的n次方来表示。例如,8 bit的色深包含2的8次方）

参数

format 图像的压缩格式；

quality 图像压缩比的值，0-100。 0 意味着小尺寸压缩，100意味着高质量压缩。对于有些格式，比如无损压缩的PNG，它就会忽视quality这个参数设置。

stream 写入压缩数据的输出流

　　　　返回值

如果成功地把压缩数据写入输出流，则返回true。

public Bitmap copy (Bitmap.Config config, boolean isMutable)

根据该位图的大小产生一个新位图，根据指定的结构设置新位图的结构，然后把位图的像素拷贝到新位图中。如果不支持该转换，或者分配内存失败，那就返回NULL。返回的位图和原图有同样的像素密度。

参数

　　config 　　结果图预期的结构；

　　isMutable 　　如果是true，那么产生的图片是可变的。(比如，它的像素能被修改)

　　　　返回值

新的位图。如果拷贝操作不能执行，则返回NULL。

public void copyPixelsFromBuffer (Buffer src)

从缓存器中拷贝像素值，从当前索引开始，覆盖位图中对应的像素值。在缓存器中的数据不会被改变(不像setPixels()，会把32位去预存像素转换为该位图的格式)。

public void copyPixelsToBuffer (Buffer dst)

把该位图的像素值拷贝到指定的缓存器中(调用者分配的缓存器)。如果缓存区不够大而无法放置所有的像素值(要考虑每个像素值的位数)，或者如果该缓存器的子类不是被支持的类型中的一种(ByteBuffer，ShortBuffer，IntBuffer)，那么将会抛出一个异常。

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

返回一个不可改变的位图，该位图来自源位图的子集，并根据可选的矩阵进行转换。它被初始化为跟源位图有同样的密度。

参数

source 产生子位图的源位图；

x 子位图第一个像素在源位图的X坐标

y 子位图第一个像素在源位图的y坐标

width 子位图每一行的像素个数

height 子位图的行数

m 对像素值进行变换的可选矩阵

filter 如果为true，源图要被过滤。该参数仅在matrix包含了超过一个翻转才有效

　　返回值

一个描述了源图指定子集的位图。

异常

IllegalArgumentException 如果x，y，width，height的值超出了源图的维度，该异常会被抛出。

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

返回一个指定高度和宽度的不可改变的位图。它的初始密度由getDensity()决定。

参数

width 位图的宽度

height 位图的高度

config 位图的结构

异常

IllegalArgumentException 如果高度或宽度小于等于零，该异常被抛出。

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

返回一个不可变的位图，该位图来自源图指定的子集。新位图可能跟源图同一个对象，或者是源图的一个拷贝。它被初始化为源图同样的密度。

参数

source 用来构建子集的源位图

x 子位图第一个像素在源位图的X坐标

y 子位图第一个像素在源位图的y坐标

width 子位图每一行的像素个数

height 子位图的行数

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

返回一个指定宽度和高度的不可变位图，该位图每个像素值等于颜色数组中对应的值。它初始化的密度由getDensity()来设定。

参数

colors 用来初始化像素值得颜色数组

offset 在像素数组的第一个颜色值之前要忽略的像素个数

stride 行之间像素个数

width 位图的宽度

height 位图的高度

config 位图的结构。如果这个结构不支持每个像素的alpha通道(比如，RGB_565), 那么colors数组中的alpha位将被忽略(被假定为FF值)。

异常

IllegalArgumentException　　如果宽度值或高度值小于等于零，或者像素数组的长度小于像素个数，该异常被抛出。

public static Bitmap createBitmap (Bitmap src)

根据源位图返回一个不可改变的位图。新位图可能跟源位图是同一个对象，或者是一个拷贝。新位图被初始化为和源位图有同样的像素密度。

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

返回一个宽度和高度被指定的不可改变的位图，且该位图每一个像素值由颜色数组中对应的值来设定。它的初始像素密度由getDensity()决定。

　　参数

colors 用来初始化像素值得颜色数组。该数组必须至少和宽度*高度一样大。 width 位图的宽度

height 位图的高度

config 位图的结构。如果这个结构不支持每个像素的alpha通道(比如，RGB_565), 那么colors数组中的alpha位将被忽略(被假定为FF值)。

异常

IllegalArgumentException 如果宽度值或高度值小于等于零，或者像素数组的长度小于像素个数，该异常被抛出。

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

从当前存在的位图，按一定的比例创建一个新的位图。

参数

src 用来构建子集的源位图

dstWidth 新位图期望的宽度

dstHeight 新位图期望的高度

　　　　返回值

　　一个新的按比例变化的位图。

public int describeContents ()

没有特殊的包内容。（原文：No special parcel contents.）

返回值

一个位掩码，指明被Parcelable序列化的特殊对象类型的数据集。

public void eraseColor (int c)

用指定的颜色填充位图的像素值。

异常

IilegalStateException 当该位图不可改变时

public Bitmap extractAlpha ()

返回一个新的位图，该位图从源图中捕获了alpha值。这个方法可能跟Canvas.drawBitmap()一起被画，颜色值从传递过来的画布中获取。

返回值

一个包含源位图alpha通道值的位图。

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

返回一个从源图中获取了alpha值的新位图。这些值可能被可选的画布参数所影响，该画布参数可以包含它自己的alpha值，或可能包含一个能改变结果位图实际尺寸的遮罩滤镜(比如，一个模糊滤镜可以放大结果位图)。如果offsetXY不为空，它会返回最终位图的偏移量总数，这样它就能跟源位图对齐。比如，如果画布包含半径为2的模糊区，那么offsetXY[] 将包含-2，-2，所以位图的alpha值会按照(-2，-2)的偏移量去绘制，然后画源图时会导致模糊区域在视觉上跟源图对齐。

返回位图的初始像素密度跟源图一样。

参数

paint 可选的画布，用来修改被返回位图的alpha值。默认为空值。

offsetXY 可选的数组，它返回x(索引为0) 和y (索引为1)的偏移量，该偏移量被用来定位返回的位图，这样它才会在视觉上跟源位图对齐。

　　　　返回值

　　返回一个新的位图，该位图从源图中捕获了alpha值。这个方法可能跟Canvas.drawBitmap()一起被画，颜色值从传递过来的画布中获取。

public final Bitmap.Config getConfig ()

如果这个位图内在的配置是一种公开的格式，那么返回这个配置，否则返回空值。

public int getDensity ()

返回位图的像素密度。

默认的像素密度和当前的显示密度一样，除非当前的应用程序不支持不同的屏幕密度，当它是DENSITY_DEFAULT时。要注意到兼容模式是由最初装载到进程的应用程序决定的。

--共享同一个进程的应用程序必须有同样的兼容性，或者确保它们能明确地设置合适的位图密度。

返回值

一个默认密度的变换因子，当变换因子未知时返回DENSITY_NONE值。

参见

public final int getHeight ()

返回位图的高度值。

public byte[] getNinePatchChunk ()

返回一个装有私有数据的可选数组，该数组被UI系统在一些位图中使用。该方法不要在应用程序主动调用。

public int getPixel (int x, int y)

返回指定位置的像素颜色值。如果x或y越界(负数，或各自大于等于宽度或高度值)，讲抛出一个异常。

参数

x 待返回像素的x坐标值(0-width-1)。

y 待返回像素的y坐标值(0-height-1)

　　　　返回值

指定坐标的argb颜色值。

　　异常

如果x，y越界，IilegalArgumentExcepiton将被抛出。

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

把位图的数据拷贝到pixels[]中。每一个都由一个表示颜色值的int值来表示。幅度参数表明调用者允许的像素数组行间距。对通常的填充结果，只要传递宽度值给幅度参数。

参数

pixels 接收位图颜色值的数组

offset 写入到pixels[]中的第一个像素索引值

stride pixels[]中的行间距个数值(必须大于等于位图宽度)。不能为负数

x 从位图中读取的第一个像素的x坐标值。

y 从位图中读取的第一个像素的y坐标值

width 从每一行中读取的像素宽度

height 　　读取的行数

　　异常

IilegalArgumentExcepiton 如果x，y，width，height越界或stride的绝对值小于位图宽度时将被抛出。

ArrayIndexOutOfBoundsException 如果像素数组太小而无法接收指定书目的像素值时将被抛出。

public final int getRowBytes ()

返回位图每行像素总数的字节数。要注意，这里说的是位图中原始态存储的像素。如果你调用了getPixels()或者setPixels()，那么像素就会统一地被处理成32bit值，它是根据颜色类进行填充的。

返回值

原生态位图每行像素的字节总数。

public int getScaledHeight (int targetDensity)

一个方便的方法，它能返回被像素密度因子整除后的位图高度值。

参数

targetDensity 位图目标画布的密度

返回值

根据密度比例因子处理后位图的高度值。

public int getScaledHeight (DisplayMetrics metrics)

方便地以DisplayMetrics的目标密度值调用getScaledHeight(int)

public int getScaledHeight (Canvas canvas)

方便地以Canvas的目标密度值调用getScaledHeight(int)

public int getScaledWidth (DisplayMetrics metrics)

方便地以DisplayMetrics的目标密度值调用getScaledWidth(int)

public int getScaledWidth (int targetDensity)

一个方便的方法，它能返回被像素密度因子整除后的位图宽度值。

参数

targetDensity 位图目标画布的密度

返回值

根据密度比例因子处理后位图的宽度值。

public int getScaledWidth (Canvas canvas)

方便地以Canvas的目标密度值调用getScaledWidth (int)

public final int getWidth ()

返回位图的宽度。

public final boolean hasAlpha ()

返回true，如果位图的配置支持每个像素的alpha值，并且这些像素可能包含不透明的alpha值。对于某些配置，一般都返回false(比如，RGB_565)，因为它们不支持每个像素的alpha值。尽管如此，对配置来说，这些位图可能被标记为它所有的像素都是透明的。在这种情况下，hasAlpha()将会返回false。如果一个配置，比如ARGB_8888是没有被标记的，那么它会默认返回true。

public final boolean isMutable ()

如果该位图被标记为可改变(比如，能被画进去)，那么返回true。

public final boolean isRecycled ()

如果该位图已经被回收，返回true。如果那样，若试图获取它的像素值，一个错误将会发生，并且该位图不会被画。

返回值

　　如果位图已经被回收，返回true。

public void prepareToDraw ()

重建所有与待画位图相关的缓存。在位图可清除的情况下，这个调用会努力保证像素已经被解码。如果这个方法是被有多个位图的序列调用，优先级在LRU顺序中提供(比如，最后被调用的位图拥有最高的优先级)。对于和缓存无关的位图，这个调用时一个no-op，它是无害的。

public void recycle ()

释放和位图相关的本地对象，且清除对像素数据的引用。该方法不会同步释放像素数据。它仅仅允许在没有其它引用的情况下被系统垃圾回收。这个位图被标记为“死的”，意味着如果getPixels()或setPixels()被调用，一个异常会抛出，且它不画任何东西。这个操作不可翻转，所以只有当你确信这个位图没有更多的用处时，它才能被调用。这是一个高级的调用，且一般来说它不需要被调用，因为通常的垃圾回收过程会在该位图没有其它引用的时候，释放这些内存。

public void setDensity (int density)

指定位图的密度。当位图被画到一个有密度的画布上时，它会缩放到合适的比例

参数

density 该位图的密度缩放因子。如果密度未知，值为DENSITY_NONE。

参见

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

把指定的颜色写入到位图中x，y的坐标值的位置(假设该位图是可变的)。

参数