Android中文API（136） —— Bitmap

前言

　　本章內容android.graphics.Bitmap章節，譯為"位圖"，版本為Android 4.0 r1，翻譯來自："StreamH"。

  

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值。

           參見

           setDensity(int)

DENSITY_DEFAULT

densityDpi

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。

參見

      getDensity()

DENSITY_DEFAULT

densityDpi

DENSITY_NONE

 

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

把指定的顏色寫入到位圖中x，y的坐標值的位置(假設該位圖是可變的)。

參數

X               待替換像素的x坐標(0到width-1)。

Y               待替換像素的y坐標(0到height-1)

color         寫入到位圖的顏色值

拋出

         IilegalStateException                      如果這個位圖不可改變

IIlegalArgumentException   如果x，y的值超出位圖的邊界

 

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

用數組中的顏色值替換位圖的像素值。數組中的每個元素是包裝的整型，代表了顏色值。

參數

      pixels        寫到位圖中的顏色值

offset        從pixels[]中讀取的第一個顏色值的索引

stride        位圖行之間跳過的顏色個數。通常這個值等於位圖寬度，但它可以更更大(或負數)

X               被寫入位圖中第一個像素的x坐標。

Y               被寫入位圖中第一個像素的y坐標

width        從pixels[]中拷貝的每行的顏色個數

height       寫入到位圖中的行數

異常

      IilegalStateException                      如果這個位圖不可改變

IIlegalArgumentException   如果x，y，width，height的值超出位圖的邊界

ArrayIndexOutOfBoundsException 如果像素隊列太小以致不能接受指定的像素位數。

 

public void writeToParcel (Parcel p, int flags)

把位圖和它的像素值寫入到parcel中。位圖可以通過調用CREATOR.createFromParcel()進行重建。

參數

　　p                可以寫入位圖數據的parcel對象

flages       附加的標記，表明這個對象以什麼方式寫入。可能是0或PARCELABLE_WRITE_RETURN_VALUE