BitmapData  - AS3

點陣圖影像的高度，以像素為單位。

定義點陣圖影像大小和位置的矩形。 矩形的頂端和左側的位置都是 0；寬度和高度等於 BitmapData 物件的像素寬度和高度。

定義點陣圖影像是否支援每個像素透明度。 您只可以在建構 BitmapData 物件時設定此值，方法為將建構函式的 transparent 參數傳遞為 true。 接著，在您建立 BitmapData 物件之後，可以藉由判斷 transparent 屬性的值是否為 true，來檢查它是否支援每個像素透明度。

點陣圖影像的寬度，以像素為單位。

以指定的寬度和高度來建立 BitmapData 物件。 如果指定 fillColor 參數的值，點陣圖中的每個像素都會設定為此顏色。

根據預設，建立的點陣圖為透明，除非您傳遞 false 值供 transparent 參數使用。 當您建立不透明的點陣圖時，就無法再變更為透明的點陣圖。 不透明點陣圖中的每個像素，僅使用 24 位元的顏色色版資訊。 如果將點陣圖定義為透明，每個像素會使用 32 位元的顏色色版資訊，包含 Alpha 透明度色版。

在 AIR 1.5 和 Flash Player 10 中，BitmapData 物件的大小上限為 8,191 像素寬度或高度，且像素總計不得超過 16,777,215 像素 (因此，如果 BitmapData 物件的寬度為 8,191 像素，則其高度上限為 2,048 像素)。若為 Flash Player 9 和 AIR 1.1 及其更早版本，高度和寬度的上限都是 2,880 像素。如果指定的寬度或高度值大於 2880，就不會建立新實體。

採用來源影像和濾鏡物件並產生已套用濾鏡的影像。

此方法會依賴內建濾鏡物件的行為，該物件會決定受到輸入來源矩形影響的目標矩形。

套用濾鏡之後，結果影像會比輸入影像大。 例如，如果使用 BlurFilter 類別來模糊化 (50,50,100,100) 的來源矩形以及 (10,10) 的目標點，目標影像中變更的區域將會因為模糊化而比 (10,10,60,60) 大。 這通常會在呼叫 applyFilter() 時，在內部發生。

如果 sourceBitmapData 參數的 sourceRect 參數是一個內部區域，如在一個 200 x 200 影像的 (50,50,100,100) 中，濾鏡會使用 sourceRect 參數外部的來源像素來產生目標矩形。

如果 BitmapData 物件與指定為 sourceBitmapData 參數的物件是同一個物件，則應用程式會使用物件的暫存副本來執行濾鏡操作。為了達到最佳效能，請避免這種情況發生。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Rectangle;
import flash.filters.BlurFilter;

var bmd:BitmapData = new BitmapData(80, 30, false, 0xFFCC00);
var rect:Rectangle = new Rectangle(10, 10, 40, 10);
bmd.fillRect(rect, 0xFF0000);

var pt:Point = new Point(10, 10);
var filter:BlurFilter = new BlurFilter();
bmd.applyFilter(bmd, rect, pt, filter);

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

傳回具有和內含點陣圖完全相同副本、且為原始實體副本的新 BitmapData 物件。

import flash.display.Bitmap;
import flash.display.BitmapData;

var bmd1:BitmapData = new BitmapData(100, 80, false, 0x00000000);
var bmd2:BitmapData = bmd1.clone();

bmd1.setPixel32(1, 1, 0xFFFFFFFF);

trace(bmd1.getPixel32(1, 1).toString(16)); // ffffffff
trace(bmd2.getPixel32(1, 1).toString(16)); // ff000000

var bm1:Bitmap = new Bitmap(bmd1);
this.addChild(bm1);

var bm2:Bitmap = new Bitmap(bmd2);
bm2.x = 110;
this.addChild(bm2);

使用 ColorTransform 物件調整點陣圖影像指定區域中的顏色值。 如果矩形符合點陣圖影像的邊界，則此方法將會變化整個影像的顏色值。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.ColorTransform;

var bmd:BitmapData = new BitmapData(80, 30, false, 0xFF0000);

var cTransform:ColorTransform = new ColorTransform();
cTransform.alphaMultiplier = 0.5
var rect:Rectangle = new Rectangle(0, 0, 40, 30);
bmd.colorTransform(rect, cTransform);

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

比較兩個 BitmapData 物件。 如果兩個 BitmapData 物件都具有相同的尺寸 (寬度與高度)，則方法會傳回新的 BitmapData 物件，而且在兩個來源物件中的所有像素裡，每個像素就是其它像素的「色差」：

• 如果兩個像素相等，則像素色差為 0x00000000。
• 如果兩個像素具有不同的 RGB 值 (忽略 Alpha 值)，則像素色差為 0xRRGGBB，其中 RR/GG/BB 是紅色、綠色和藍色色版之間的個別色差 (來源物件中的像素值減去 otherBitmapData 物件中的像素值)。 在這裡 Alpha 色版的色差會被忽略。
• 如果只有 Alpha 色版值不同， 像素值為 0xZZFFFFFF，當中的 ZZ 為 Alpha 值中的差異 (來源物件的 Alpha 值減去 otherBitmapData 物件中的 Alpha 值)。

例如，假設有下列兩個 BitmapData 物件：

     var bmd1:BitmapData = new BitmapData(50, 50, true, 0xFFFF8800);
     var bmd2:BitmapData = new BitmapData(50, 50, true, 0xCCCC6600);
     var diffBmpData:BitmapData = bmd1.compare(bmd2) as BitmapData;
     trace ("0x" + diffBmpData.getPixel(0,0).toString(16); // 0x332200
     

注意： 用來填滿兩個 BitmapData 物件的所有顏色在 RGB 值上都有些許的色差 (0xFF0000 與 0xFFAA00)。 compare() 方法的結果會產生新的 BitmapData 物件，其中每個像素在兩個點陣圖之中會有 RGB 值的色差。

假設下列兩個 BitmapData 物件當中，RGB 顏色都一樣，但是 Alpha 值不同：

     var bmd1:BitmapData = new BitmapData(50, 50, true, 0xFFFFAA00);
     var bmd2:BitmapData = new BitmapData(50, 50, true, 0xCCFFAA00);
     var diffBmpData:BitmapData = bmd1.compare(bmd2) as BitmapData;
     trace ("0x" + diffBmpData.getPixel32(0,0).toString(16); // 0x33ffffff
     

compare() 方法的結果會產生新的 BitmapData 物件，其中每個像素在兩個點陣圖之中會有 Alpha 值的色差。

如果這些 BitmapData 物件都相等 (具有相同的寬度、高度以及相同的像素值)，則方法會傳回數字 0。

如果 BitmapData 物件的寬度不相等，方法會傳回數字 -3。

如果這些 BitmapData 物件的高度不相等，但是寬度相等，則方法會傳回數字 -4。

下列範例將使用不同的寬度 (50 與 60) 來比較兩個 Bitmap 物件：

     var bmd1:BitmapData = new BitmapData(100, 50, false, 0xFFFF0000);
     var bmd2:BitmapData = new BitmapData(100, 60, false, 0xFFFFAA00);
     trace(bmd1.compare(bmd2)); // -4
     

參數

import flash.display.Bitmap;
import flash.display.BitmapData;

var bmd1:BitmapData = new BitmapData(50, 50, true, 0xFFFFAA00);
var bmd2:BitmapData = new BitmapData(50, 50, true, 0xCCFFAA00);
var diffBmpData:BitmapData = BitmapData(bmd1.compare(bmd2));
var diffValue:String = diffBmpData.getPixel32(1, 1).toString(16);
trace (diffValue); // 33ffffff

var bm1:Bitmap = new Bitmap(bmd1);
addChild(bm1);
var bm2:Bitmap = new Bitmap(bmd2);
addChild(bm2);
bm2.x = 60;

從另一個 BitmapData 物件或目前 BitmapData 物件的一個色版，將資料傳送到目前 BitmapData 物件的色版。 在目標 BitmapData 物件裡其它色版中的所有資料都會保留下來。

來源色版值和目標色版值可能為下列值的其中之一：

• BitmapDataChannel.RED
• BitmapDataChannel.GREEN
• BitmapDataChannel.BLUE
• BitmapDataChannel.ALPHA

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var bmd:BitmapData = new BitmapData(100, 80, false, 0x00FF0000);

var rect:Rectangle = new Rectangle(0, 0, 20, 20);
var pt:Point = new Point(10, 10);
bmd.copyChannel(bmd, rect, pt, BitmapDataChannel.RED, BitmapDataChannel.BLUE);

var bm:Bitmap = new Bitmap(bmd);
this.addChild(bm);    

在影像之間提供執行不含延伸、旋轉或顏色特效的像素處理快速程序。 這個方法會將來源影像的矩形區域，複製到目標 BitmapData 物件之目標點上相同大小的矩形區域中。

如果包含 alphaBitmap 和 alphaPoint 參數，則可以使用次要的影像當作來源影像的 Alpha 來源。 如果來源影像具有 Alpha 資料，則兩組 Alpha 資料都會用來將來源影像的像素合成至目標影像上。 alphaPoint 參數是 Alpha 影像對應至來源矩形左上角的點。 任何位於來源影像和 Alpha 影像交會點外的像素都不會複製到目標影像上。

mergeAlpha 屬性會控制當透明影像複製到另一個透明影像時，是否要使用 Alpha 色版。 若要複製包含 Alpha 色版資料的像素，請將 mergeAlpha 屬性設定為 true。 根據預設，mergeAlpha 屬性為 false。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var bmd1:BitmapData = new BitmapData(40, 40, false, 0x000000FF);
var bmd2:BitmapData = new BitmapData(80, 40, false, 0x0000CC44);

var rect:Rectangle = new Rectangle(0, 0, 20, 20);
var pt:Point = new Point(10, 10);
bmd2.copyPixels(bmd1, rect, pt);

var bm1:Bitmap = new Bitmap(bmd1);
this.addChild(bm1);
var bm2:Bitmap = new Bitmap(bmd2);
this.addChild(bm2);
bm2.x = 50;

從像素資料的矩形區域中將位元組陣列填色。這個方法會從 ByteArray 的 position 索引開始，將每個像素的無正負號整數 (32 位元未相乘的像素值) 寫入位元組陣列中。必要時，位元組陣列的大小會增加到所需的位元組數目，以容納所有像素資料。

參數

相關 API 元素

釋放用來儲存 BitmapData 物件的記憶體。

某個影像呼叫 dispose() 方法時，會將此影像的高度和寬度都設定為 0。 所有針對此 BitmapData 實體之方法或屬性的後續呼叫都會失敗，並擲回例外。

BitmapData.dispose() 立即釋放實際點陣圖資料佔用的記憶體 (一個點陣圖會消耗 64 MB 的記憶體)。使用 BitmapData.dispose() 之後，BitmapData 物件再也無法使用，如果您在 BitmapData 物件上呼叫函數，則 Flash 執行階段會擲出例外。不過，BitmapData.dispose() 並不會對 BitmapData 物件 (大約 128 個位元組) 進行垃圾回收；垃圾回收程式收集 BitmapData 物件時，會釋放實際 BitmapData 物件佔用的記憶體。

相關 API 元素

import flash.display.BitmapData;

var myBitmapData:BitmapData = new BitmapData(100, 80, false, 0x000000FF);
trace(myBitmapData.getPixel(1, 1)); // 255 == 0xFF

myBitmapData.dispose();
try {
    trace(myBitmapData.getPixel(1, 1));
} catch (error:Error) {
    trace(error); // ArgumentError
}

使用 Flash 執行階期的向量描繪器，在點陣圖影像上繪製 source 顯示物件。您可以指定 matrix、colorTransform、blendMode，以及目標 clipRect 參數來控制顯示的執行方式。 或者，您也可以指定是否在點陣圖縮放時平滑化處理 (只有當來源物件是 BitmapData 物件才能這麼處理)。

注意：drawWithQuality() 方法的運作方式與 draw() 方法完全相同，只是它不會使用 Stage.quality 屬性來決定向量顯示的品質，請將 quality 參數指定給 drawWithQuality() 方法。

這個方法會直接對應至編寫工具介面中使用物件標準向量描繪器來繪製物件的方式。

來源顯示物件並不會針對此呼叫使用所套用的任何變形。 會將它當做存在於元件庫或檔案中，而且不具有矩陣變形、顏色轉換和混合模式。 若要藉由使用顯示物件的轉換屬性來加以繪製 (例如繪製影片片段)，可以將其 transform 屬性物件複製到使用 BitmapData 物件之 Bitmap 物件的 transform 屬性上。

Flash Player 9.0.115.0 和更新版本以及 Adobe AIR 透過 RTMP 支援此方法。您可以使用伺服器端指令碼控制 Flash Media Server 上串流的存取。如需詳細資訊，請參閱「Adobe Flash Media Server 伺服器端 ActionScript 語言參考」中的 Client.audioSampleAccess 和 Client.videoSampleAccess 屬性。

如果 source 物件及其所有子物件 (在 Sprite 或 MovieClip 物件的情況下) 不是來自與呼叫者相同的網域，也不是位於呼叫者可存取的內容中 (藉由呼叫 Security.allowDomain() 方法進行存取)，呼叫 draw() 會擲回 SecurityError 例外。應用程式安全執行程序中的 AIR 內容不受此限制。

使用載入的點陣圖影像當做 source 還存有一些限制。如果載入的影像與呼叫端來自相同網域，呼叫 draw() 方法就會成功。再者，影像伺服器上的跨網域原則檔可能授與權限，允許 SWF 內容的網域呼叫 draw() 方法。在此情況下，您必須設定 LoaderContext 物件的 checkPolicyFile 屬性，並且使用該物件做為 context 參數來呼叫 Loader 物件的 load() 方法以載入影像。應用程式安全執行程序中的 AIR 內容不受這些限制。

在 Windows 中，draw() 方法無法捕捉內嵌於 Adobe AIR 之 HTMLLoader 物件的 HTML 網頁內之 SWF 內容。

draw() 方法既無法捕捉 Adobe AIR 中的 PDF 內容，也無法捕捉 Adobe AIR 中內嵌於 wmode 特質設為 "window" 之 HTML 的 SWF 內容。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.text.TextField;

var tf:TextField = new TextField();
tf.text = "bitmap text";

var myBitmapData:BitmapData = new BitmapData(80, 20);
myBitmapData.draw(tf);
var bmp:Bitmap = new Bitmap(myBitmapData);
this.addChild(bmp);

使用 Flash 執行階期的向量描繪器，在點陣圖影像上繪製 source 顯示物件。您可以指定 matrix、colorTransform、blendMode，以及目標 clipRect 參數來控制顯示的執行方式。 或者，您也可以指定是否在點陣圖縮放時平滑化處理 (只有當來源物件是 BitmapData 物件才能這麼處理)。

注意：drawWithQuality() 方法的運作方式與 draw() 方法完全相同，只是它不會使用 Stage.quality 屬性來決定向量顯示的品質，請將 quality 參數指定給 drawWithQuality() 方法。

這個方法會直接對應至編寫工具介面中使用物件標準向量描繪器來繪製物件的方式。

來源顯示物件並不會針對此呼叫使用所套用的任何變形。 會將它當做存在於元件庫或檔案中，而且不具有矩陣變形、顏色轉換和混合模式。 若要藉由使用顯示物件的轉換屬性來加以繪製 (例如繪製影片片段)，可以將其 transform 屬性物件複製到使用 BitmapData 物件之 Bitmap 物件的 transform 屬性上。

Flash Player 9.0.115.0 和更新版本以及 Adobe AIR 透過 RTMP 支援此方法。您可以使用伺服器端指令碼控制 Flash Media Server 上串流的存取。如需詳細資訊，請參閱 Adobe Flash Media Server 伺服器端 ActionScript 語言參考中的 Client.audioSampleAccess 和 Client.videoSampleAccess 屬性。

如果 source 物件及其所有子物件 (在 Sprite 或 MovieClip 物件的情況下) 不是來自與呼叫者相同的網域，也不是位於呼叫者可存取的內容中 (藉由呼叫 Security.allowDomain() 方法進行存取)，呼叫 drawWithQuality() 會擲回 SecurityError 例外。應用程式安全執行程序中的 AIR 內容不受此限制。

使用載入的點陣圖影像當做 source 還存有一些限制。如果載入的影像與呼叫者來自相同網域，呼叫 drawWithQuality() 方法就會成功。再者，影像伺服器上的跨網域原則檔可能授與權限，允許 SWF 內容的網域呼叫 drawWithQuality() 方法。在此情況下，您必須設定 LoaderContext 物件的 checkPolicyFile 屬性，並且使用該物件做為 context 參數來呼叫 Loader 物件的 load() 方法以載入影像。應用程式安全執行程序中的 AIR 內容不受這些限制。

在 Windows 中，drawWithQuality() 方法無法捕捉內嵌於 Adobe AIR HTMLLoader 物件中 HTML 網頁的 SWF 內容。

drawWithQuality() 方法既無法捕捉 Adobe AIR 中的 PDF 內容，也無法捕捉 Adobe AIR 中內嵌於 wmode 特質設為 "window" 之 HTML 的 SWF 內容。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.text.TextField;

var tf:TextField = new TextField();
tf.text = "bitmap text";

var myBitmapData:BitmapData = new BitmapData(80, 20);
myBitmapData.drawWithQuality(tf, , , , , , StageQuality.LOW);
var bmp:Bitmap = new Bitmap(myBitmapData);
this.addChild(bmp);

使用選取的壓縮程式演算法壓縮這個 BitmapData 物件，並傳回新的 ByteArray 物件。或者，將產生的資料寫入指定的 ByteArray。compressor 引數會指定編碼演算法，並且可以是 PNGEncoderOptions、JPEGEncoderOptions 或 JPEGXREncoderOptions。

下列範例使用 JPEGEncoderOptions 壓縮 BitmapData 物件：

     // Compress a BitmapData object as a JPEG file.
     var bitmapData:BitmapData = new BitmapData(640,480,false,0x00FF00);
     var byteArray:ByteArray = new ByteArray();
     bitmapData.encode(new Rectangle(0,0,640,480), new flash.display.JPEGEncoderOptions(), byteArray); 

參數

相關 API 元素

以指定的 ARGB 顏色對像素的矩形區域填色。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;

var myBitmapData:BitmapData = new BitmapData(40, 40, false, 0x0000FF00);

var rect:Rectangle = new Rectangle(0, 0, 20, 20);
myBitmapData.fillRect(rect, 0x0000FF);

var bm:Bitmap = new Bitmap(myBitmapData);
addChild(bm);

對於從 (x, y) 座標開始的影像，執行填色作業，並填入特定顏色。 floodFill() 方法和多種繪圖程式裡的油漆桶工具類似。 顏色為 ARGB 顏色，其中包含 Alpha 資訊和顏色資訊。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;

var myBitmapData:BitmapData = new BitmapData(40, 40, false, 0x0000FF00);

var rect:Rectangle = new Rectangle(0, 0, 20, 20);
myBitmapData.fillRect(rect, 0x000000FF);
rect = new Rectangle(15, 15, 25, 25);
myBitmapData.fillRect(rect, 0x000000FF);

myBitmapData.floodFill(10, 10, 0x00FF0000);

var bm:Bitmap = new Bitmap(myBitmapData);
addChild(bm);

指定 BitmapData 物件、來源矩形以及濾鏡物件，來決定 applyFilter() 方法呼叫所影響的目標矩形。

例如，模糊濾鏡通常會影響大於來源影像大小的區域。 由預設 BlurFilter 實體所篩選的 100 x 200 像素影像，其中 blurX = blurY = 4 會產生 (-2,-2,104,204) 的目標矩形。 generateFilterRect() 方法可讓您預先找出此目標矩形的大小，因此您可以在執行濾鏡操作前適當調整目標影像的大小。

有些濾鏡會依據來源影像大小來裁切其目標矩形。 例如，內部 DropShadow 不會產生大於來源影像的結果。 在此 API 中，BitmapData 物件是當做來源邊界來使用，而不是來源 rect 參數。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Rectangle;
import flash.filters.BlurFilter;

var bmd:BitmapData = new BitmapData(80, 30, false, 0xFFCC00);
var rect:Rectangle = new Rectangle(10, 10, 40, 10);
bmd.fillRect(rect, 0xFF0000);

var pt:Point = new Point(10, 10);
var filter:BlurFilter = new BlurFilter();

trace(bmd.generateFilterRect(rect, filter));
// (x=8, y=8, w=44, h=14)

bmd.applyFilter(bmd, rect, pt, filter);
var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

決定矩形區域，將位於點陣圖影像內所有指定顏色的像素全部封閉起來 (如果 findColor 參數設為 true)，或者將不包含指定顏色的所有像素封閉起來 (如果 findColor 參數設為 false)。

例如，如果您有一個來源影像，而且想要決定包含非零 Alpha 色版的影像矩形，請傳遞 {mask: 0xFF000000, color: 0x00000000} 做為參數。 如果 findColor 參數設為 true，則會搜尋整個影像，以找出 (value & mask) == color 的像素邊界 (其中 value 是指像素的顏色值)。 如果 findColor 參數設為 false，則會搜尋整個影像，以找出 (value & mask) ! 的像素邊界= color 的像素邊界 (其中 value 是指像素的顏色值)。 若要決定影像周圍的空白，請傳遞 {mask: 0xFFFFFFFF, color: 0xFFFFFFFF} 以尋找非白色像素的邊界。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;

var bmd:BitmapData = new BitmapData(80, 40, false, 0xFFFFFF);
var rect:Rectangle = new Rectangle(0, 0, 80, 20);
bmd.fillRect(rect, 0xFF0000);

var maskColor:uint = 0xFFFFFF; 
var color:uint = 0xFF0000;  
var redBounds:Rectangle = bmd.getColorBoundsRect(maskColor, color, true);
trace(redBounds); // (x=0, y=0, w=80, h=20)

var notRedBounds:Rectangle = bmd.getColorBoundsRect(maskColor, color, false);
trace(notRedBounds); // (x=0, y=20, w=80, h=20)

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

傳回整數，代表在特定點 (x, y) 上 BitmapData 物件的 RGB 像素值。 getPixel() 方法會傳回未相乘的像素值。 不會傳回任何 Alpha 資訊。

BitmapData 物件裡的所有像素都會當作預先相乘的顏色值來儲存。 預先相乘的影像像素具有已和 Alpha 資料相乘的紅、綠和藍的顏色色版值。 例如，如果 Alpha 值為 0，則 RGB 色版的值也為 0，與未相乘的值無關。 這種資料遺失狀況可能導致執行操作時的一些問題。 所有的 BitmapData 方法都會採用並傳回未相乘的值。 內部像素形式在傳回數值之前會從預先相乘轉換為未相乘。 在集合操作中，像素值會在設定原始影像像素前會預先相乘。

參數

相關 API 元素

import flash.display.BitmapData;

var bmd:BitmapData = new BitmapData(80, 40, false, 0xFF0000);

var pixelValue:uint = bmd.getPixel(0, 0);
trace(pixelValue.toString(16)); // ff0000;

傳回 ARGB 顏色數值，其中包含 Alpha 色版資料和 RGB 資料。 此方法和 getPixel() 方法類似，都會傳回不具 Alpha 色版資料的 RGB 顏色。

BitmapData 物件裡的所有像素都會當作預先相乘的顏色值來儲存。 預先相乘的影像像素具有已和 Alpha 資料相乘的紅、綠和藍的顏色色版值。 例如，如果 Alpha 值為 0，則 RGB 色版的值也為 0，與未相乘的值無關。 這種資料遺失狀況可能導致執行操作時的一些問題。 所有的 BitmapData 方法都會採用並傳回未相乘的值。 內部像素形式在傳回數值之前會從預先相乘轉換為未相乘。 在集合操作中，像素值會在設定原始影像像素前會預先相乘。

參數

相關 API 元素

import flash.display.BitmapData;

var bmd:BitmapData = new BitmapData(80, 40, true, 0xFF44AACC);

var pixelValue:uint = bmd.getPixel32(0, 0);
var alphaValue:uint = pixelValue >> 24 & 0xFF;
var red:uint = pixelValue >> 16 & 0xFF;
var green:uint = pixelValue >> 8 & 0xFF;
var blue:uint = pixelValue & 0xFF;

trace(alphaValue.toString(16)); // ff
trace(red.toString(16)); // 44
trace(green.toString(16)); // aa
trace(blue.toString(16)); // cc

從像素資料的矩形區域產生位元組陣列。 將每個像素的無正負號整數 (32 位元未相乘的像素值) 寫入位元組陣列中。

參數

相關 API 元素

import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.utils.ByteArray;

var bmd:BitmapData = new BitmapData(80, 40, true);
var seed:int = int(Math.random() * int.MAX_VALUE);
bmd.noise(seed);

var bounds:Rectangle = new Rectangle(0, 0, bmd.width, bmd.height);
var pixels:ByteArray = bmd.getPixels(bounds);

從矩形區域的像素資料產生向量陣列。傳回指定矩形的無正負號整數 (32 位元未相乘的像素值) Vector 物件。

參數

計算 BitmapData 物件的 256 色二進位長條圖。這個方法會傳回包含 4 個 Vector 的 Vector 物件。<Number> 實體 (4 個包含 Number 物件的 Vector 物件)。這 4 個 Vector 實體依序代表紅色、綠色、藍色和 Alpha 組件。每個 Vector 實體都包含 256 個值，分別代表個別組件值的填入次數 (從 0 至 255)。

參數

在一個點陣圖影像和一個點、矩形或其它點陣圖影像之間，執行像素層級作用區域偵測。 碰撞定義為某個點或矩形在一個不透明像素上重疊，或兩個重疊的不透明像素。在執行碰撞測試時，不會考慮任一個物件的延伸、旋轉或其它變化。

如果影像是不透明影像，則此方法會將其視為完全不透明的矩形。 若要執行考量透明度的像素層級碰撞測試，兩個影像必須都為透明影像。 當您在測試兩個透明影像時，會將控制 Alpha 色版值 (從 0 到 255) 的 Alpha 臨界值參數視為不透明。

參數

import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var bmd1:BitmapData = new BitmapData(80, 80, true, 0x00000000);
var rect:Rectangle = new Rectangle(20, 20, 40, 40);
bmd1.fillRect(rect, 0xFF0000FF);

var pt1:Point = new Point(1, 1);
trace(bmd1.hitTest(pt1, 0xFF, pt1)); // false
var pt2:Point = new Point(40, 40);
trace(bmd1.hitTest(pt1, 0xFF, pt2)); // true

鎖定影像，以便當這個 BitmapData 物件變更時，其它參照此 BitmapData 物件 (例如 Bitmap 物件) 的任何物件不會跟著更新。 若要改善效能，請在您多次呼叫 setPixel() 或 setPixel32() 方法之前與之後，搭配使用這方法與 unlock() 方法。

相關 API 元素

import flash.display.BitmapData;

var bitmapData:BitmapData = picture.bitmapData;
bitmapData.lock();
bitmapData = complexTransformation(bitmapData);
bitmapData.unlock();
picture.bitmapData = bitmapData;

執行從來源影像到目標影像的每個色版的混合。 程式會根據來源和目標像素的色版值，為每個色版和每個像素計算新值。 例如，在紅色色版中，新值的計算方式如下 (其中 redSrc 是來源影像中像素的紅色色版值，而 redDest 則是目標影像中對應像素的紅色色版值)：

new redDest = [(redSrc * redMultiplier) + (redDest * (256 - redMultiplier))] / 256;

redMultiplier、greenMultiplier、blueMultiplier 和 alphaMultiplier 值都是每個顏色色版的倍數。 請使用介於 0 到 0x100 (256) 之間的十六進位值，其中 0 指定在結果中使用來自目標的完整數值，0x100 指定使用來自來源的完整數值，中間的數字則指定使用混合 (例如 0x80 代表 50%)。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var bmd1:BitmapData = new BitmapData(100, 80, true, 0xFF00FF00);
var bmd2:BitmapData = new BitmapData(100, 80, true, 0xFFFF0000);
var rect:Rectangle = new Rectangle(0, 0, 20, 20);
var pt:Point = new Point(20, 20);
var mult:uint = 0x80; // 50% 
bmd1.merge(bmd2, rect, pt, mult, mult, mult, mult);

var bm1:Bitmap = new Bitmap(bmd1);
addChild(bm1);
var bm2:Bitmap = new Bitmap(bmd2);
addChild(bm2);
bm2.x = 110;

以呈現隨機雜點的像素來填色影像。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.BitmapDataChannel;

var bmd1:BitmapData = new BitmapData(80, 80);
var bmd2:BitmapData = new BitmapData(80, 80);

var seed:int = int(Math.random() * int.MAX_VALUE);
bmd1.noise(seed, 0, 0xFF, BitmapDataChannel.RED, false);
bmd2.noise(seed, 0, 0xFF, BitmapDataChannel.RED, true);

var bm1:Bitmap = new Bitmap(bmd1);
this.addChild(bm1);
var bm2:Bitmap = new Bitmap(bmd2);
this.addChild(bm2);
bm2.x = 90;

重新對應影像 (最多具有四個顏色面板資料陣列) 中的顏色色版值，每個顏色色版值對應一個色版。

Flash 執行階段會使用下列步驟來產生結果影像：

1. 在計算了紅、綠、藍和 Alpha 值之後，就會使用標準 32 位元整數數值將這些值加總起來。
2. 每個像素的紅、綠、藍和 Alpha 色版值會擷取至個別 0 至 255 的值。 這些值會用來查詢適當陣列中的新顏色值：redArray、greenArray、blueArray 和 alphaArray。 這四個陣列中的每一個都應該包含 256 個值。
3. 在全部擷取完這四種新色版值之後，會將這些值結合成標準的 ARGB 值以套用至像素中。

此方法可以支援跨色版特效。 每個輸入陣列可以包含完整的 32 位元值，而且當這些值加總在一起時不會進位。 這個程序不支援每個色版的固定。

如果沒有為色版指定陣列，則僅會將顏色色版從來源影像複製到目標影像。

您可以使用這個方法產生各種不同的特效，如一般面板對應 (使用一個色版並將它轉換為 false 顏色影像)。 您也可以使用此方法來進行各種進階色彩操作演算法，如 Gamma、曲線、色階和量子化。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var myBitmapData:BitmapData = new BitmapData(80, 80, false, 0x00FF0000);
myBitmapData.fillRect(new Rectangle(20, 20, 40, 40), 0x0000FF00);

var redArray:Array = new Array(256);
var greenArray:Array = new Array(256);

for(var i:uint = 0; i < 255; i++) {
    redArray[i] = 0x00000000;
    greenArray[i] = 0x00000000;
}

redArray[0xFF] = 0x0000FF00;
greenArray[0xFF] = 0x00FF0000;

var bottomHalf:Rectangle = new Rectangle(0, 0, 100, 40);
var pt:Point = new Point(0, 0);
myBitmapData.paletteMap(myBitmapData, bottomHalf, pt, redArray, greenArray);

var bm1:Bitmap = new Bitmap(myBitmapData);
addChild(bm1);

產生 Perlin 雜點影像。

Perlin 雜點產生演算法會插入並結合個別的隨機雜點函數 (稱為 octave) 為單一函數，以產生看起來更自然的隨機雜點。 就像音樂的八度音一樣，每個 octave 函數是前一個函數頻率的兩倍。 Perlin 雜點被描述為「雜點的不規則總和」，因為它結合了多組雜點資料和不同層級的細節。

Perlin 雜點函數可以用來模擬自然現象和山水風情，如木紋、雲朵和山脈。 在大部分情況下，Perlin 雜點函數的輸出並不會直接顯示出來，而是用來加強其它影像與賦予這些影像虛擬亂數的變化。

簡單的數位隨機雜點函數通常會產生具有粗大對比粒子的影像。 這樣的粗大對比在自然界是找不到的。 Perlin 雜點演算法會混合多個運作不同層級細節的雜點函數。 此演算法會讓相鄰像素值有較平滑的變化結果。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;

var bmd:BitmapData = new BitmapData(200, 200, false, 0x00CCCCCC);

var seed:Number = Math.floor(Math.random() * 10);
var channels:uint = BitmapDataChannel.RED | BitmapDataChannel.BLUE;
bmd.perlinNoise(100, 80, 6, seed, false, true, channels, false, null);

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

執行從來源影像至目標影像，或使用相同影像的像素溶解效果。 Flash 執行階段會使用 randomSeed 值來產生隨機像素溶解效果。函數的傳回值必須傳遞至後續的呼叫中，以持續進行像素溶解效果直到完成為止。

如果來源影像不等於目標影像，就會使用所有的屬性將像素由來源複製到目標。 這樣一來，就可讓空白影像經過溶解處理而產生一張完全填滿的影像。

如果來源影像等於目標影像，則會以 color 參數對像素進行填色。 這樣一來，將會溶解為非完全填滿的影像。 在這種模式中，會忽略目標 point 參數。

參數

import flash.display.BitmapData;
import flash.display.Bitmap;
import flash.geom.Point;
import flash.geom.Rectangle;
import flash.utils.Timer;
import flash.events.TimerEvent;

var bmd:BitmapData = new BitmapData(100, 80, false, 0x00CCCCCC);
var bitmap:Bitmap = new Bitmap(bmd);
addChild(bitmap);

var tim:Timer = new Timer(20);
tim.start();
tim.addEventListener(TimerEvent.TIMER, timerHandler);
 
function timerHandler(event:TimerEvent):void {
    var randomNum:Number = Math.floor(Math.random() * int.MAX_VALUE);
    dissolve(randomNum);
}

function dissolve(randomNum:Number):void {
    var rect:Rectangle = bmd.rect;
    var pt:Point = new Point(0, 0);
    var numberOfPixels:uint = 100;
    var red:uint = 0x00FF0000;
    bmd.pixelDissolve(bmd, rect, pt, randomNum, numberOfPixels, red);
    var grayRegion:Rectangle = bmd.getColorBoundsRect(0xFFFFFFFF, 0x00CCCCCC, true);
    if(grayRegion.width == 0 && grayRegion.height == 0 ) {
        tim.stop();
    }
}

以一定的 (x, y) 像素量來捲動影像。 捲動區域外圍的邊緣區域維持不變。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Rectangle;

var bmd:BitmapData = new BitmapData(80, 80, true, 0xFFCCCCCC);
var rect:Rectangle = new Rectangle(0, 0, 40, 40);
bmd.fillRect(rect, 0xFFFF0000);
            
var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

trace (bmd.getPixel32(50, 20).toString(16)); // ffcccccccc

bmd.scroll(30, 0); 

trace (bmd.getPixel32(50, 20).toString(16)); // ffff0000

設定 BitmapData 物件的單一像素。 目前的影像像素 Alpha 色版值會在此作業期間保留下來。 RGB 顏色參數值會被視為未相乘的顏色值。

注意：為了提升效能，當您重複使用 setPixel() 或 setPixel32() 方法時，請先呼叫 lock() 方法，再呼叫 setPixel() 或 setPixel32() 方法，然後在完成所有像素變更之後呼叫 unlock() 方法。 這個程序可預防參照此 BitmapData 實體的物件，在您尚未完成像素變更之前提早進行更新。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;

var bmd:BitmapData = new BitmapData(80, 80, false, 0xCCCCCC);

for (var i:uint = 0; i < 80; i++) {
    var red:uint = 0xFF0000;
    bmd.setPixel(i, 40, red);
}

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

設定 BitmapData 物件單一像素的顏色和 Alpha 透明度值。 此方法近似於 setPixel() 方法；最大的不同在於 setPixel32() 方法採用了包含 Alpha 色版資訊的 ARGB 顏色值。

BitmapData 物件裡的所有像素都會當作預先相乘的顏色值來儲存。 預先相乘的影像像素具有已和 Alpha 資料相乘的紅、綠和藍的顏色色版值。 例如，如果 Alpha 值為 0，則 RGB 色版的值也為 0，與未相乘的值無關。 這種資料遺失狀況可能導致執行操作時的一些問題。 所有的 BitmapData 方法都會採用並傳回未相乘的值。 內部像素形式在傳回數值之前會從預先相乘轉換為未相乘。 在集合操作中，像素值會在設定原始影像像素前會預先相乘。

注意：為了提升效能，當您重複使用 setPixel() 或 setPixel32() 方法時，請先呼叫 lock() 方法，再呼叫 setPixel() 或 setPixel32() 方法，然後在完成所有像素變更之後呼叫 unlock() 方法。 這個程序可預防參照此 BitmapData 實體的物件，在您尚未完成像素變更之前提早進行更新。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;

var bmd:BitmapData = new BitmapData(80, 80, true, 0xFFCCCCCC);

for (var i:uint = 0; i < 80; i++) {
    var red:uint = 0x60FF0000;
    bmd.setPixel32(i, 40, red);
}

var bm:Bitmap = new Bitmap(bmd);
addChild(bm);

將位元組陣列轉換為像素資料的矩形區域。 對於每個像素，會呼叫 ByteArray.readUnsignedInt() 方法，並將傳回值寫入像素中。 如果位元組陣列在寫入完整的矩形之前就結束，就會傳回函數。 位元組陣列中的資料預期將為 32 位元 ARGB 像素值。 無論像素是否讀取，都不會在位元組陣列上執行搜尋。

參數

相關 API 元素

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.utils.ByteArray;
import flash.geom.Rectangle;

var bmd1:BitmapData = new BitmapData(100, 100, true, 0xFFCCCCCC);
var bmd2:BitmapData = new BitmapData(100, 100, true, 0xFFFF0000);

var rect:Rectangle = new Rectangle(0, 0, 100, 100);
var bytes:ByteArray = bmd1.getPixels(rect);

bytes.position = 0;
bmd2.setPixels(rect, bytes);

var bm1:Bitmap = new Bitmap(bmd1);
addChild(bm1);
var bm2:Bitmap = new Bitmap(bmd2);
addChild(bm2);
bm2.x = 110;

將向量轉換為像素資料的矩形區域。對於每一個象素，讀取 Vector 元素並寫入 BitmapData 像素。Vector 中的資料預期將為 32 位元 ARGB 像素值。

參數

根據指定的臨界值來測試影像的像素值，並設定將測試傳遞至新顏色值的像素。 使用 threshold() 方法，您可以獨立和取代影像的顏色範圍，並在影像像素上執行其它邏輯運算。

threshold() 方法的測試邏輯如下所示：

1. 如果 ((pixelValue & mask) operation (threshold & mask))，則將像素設為 color；
2. 否則，如果為 copySource == true，則將像素設為來自 sourceBitmap 的對應像素值。

operation 參數會指定用於臨界值測試的比較運算子。 例如，您可以將 "==" 當作 operation 參數來使用，將影像中的特定顏色值獨立出來。 或使用 {operation: "<", mask: 0xFF000000, threshold: 0x7F000000, color: 0x00000000}，在來源影像像素的 Alpha 值小於 0x7F 時，將所有目標像素設定為完全透明。 您可以將這個技巧用於動畫般的轉換和其它特效。

參數

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.BitmapDataChannel;
import flash.geom.Point;
import flash.geom.Rectangle;

var bmd1:BitmapData = new BitmapData(200, 200, true, 0xFFCCCCCC);

var seed:int = int(Math.random() * int.MAX_VALUE);
var channels:uint = BitmapDataChannel.RED | BitmapDataChannel.BLUE;
bmd1.perlinNoise(100, 80, 12, seed, false, true, channels, false, null);

var bitmap1:Bitmap = new Bitmap(bmd1);
addChild(bitmap1);

var bmd2:BitmapData = new BitmapData(200, 200, true, 0xFFCCCCCC);
var pt:Point = new Point(0, 0);
var rect:Rectangle = new Rectangle(0, 0, 200, 200);
var threshold:uint =  0x00800000; 
var color:uint = 0x20FF0000;
var maskColor:uint = 0x00FF0000;
bmd2.threshold(bmd1, rect, pt, ">", threshold, color, maskColor, true);

var bitmap2:Bitmap = new Bitmap(bmd2);
bitmap2.x = bitmap1.x + bitmap1.width + 10;
addChild(bitmap2);

解除鎖定影像，以便當這個 BitmapData 物件變更時，其它參照此 BitmapData 物件 (例如 Bitmap 物件) 的任何物件不會跟著更新。 若要改善效能，請在您多次呼叫 setPixel() 或 setPixel32() 方法之前與之後，搭配使用這方法與 lock() 方法。

參數

相關 API 元素

import flash.display.BitmapData;

var bitmapData:BitmapData = picture.bitmapData;
bitmapData.lock();
bitmapData = complexTransformation(bitmapData);
bitmapData.unlock();
picture.bitmapData = bitmapData;

1. 會建立 url 屬性，此屬性為影像檔的位置與名稱。
2. 此類別建構函式會建立 Loader 物件，然後將事件偵聽程式實體化，並且在 completeHandler() 方法完成影像操作後傳送。
3. 然後將 request URLRequest 物件傳送至 loader.load()，並使用顯示物件將影像載入記憶體。
4. 影像接著會被放置到顯示清單中，並於螢幕上 x = 0, y = 0 的座標位置顯示該影像。
5. 此 completeHandler() 方法接著會進行下列動作：
   • 建立第二個 Loader 物件，並建立以此 Loader 物件初始化的 Bitmap 物件。
   • 建立第二個點陣圖物件，duplicate，此物件會反過來呼叫 duplicateImage() 方法，以建立原始影像的副本。
   • 建立 BitmapData 物件並指定給 duplicate 物件的 BitmapData 物件。
   • 建立新的 Rectangle 物件，並使用與原始影像相同的座標、寬度與高度。
   • 建立新的 Point 物件，並將其座標預設為 x = 0, y = 0。
   • 建立下列變數：
     • operation — 當臨界值大於或等於原始值時，就會套用新的顏色。
     • threshold — 每個像素都會針對其進行比較的值 (在此範例中則是 Alpha 值為 0xCC 的淺灰色)。
     • color — 通過臨界值測試，而且為像素所設定的顏色 (在此範例中則是純黃色)。
     • mask — 完全對比的顏色 (透明藍色)。
     • copySource — 設為 false，表示如果臨界值並未通過，就不會複製像素值。由於影像會重製，並且只會變更通過臨界測試的像素，所以這個值並不具意義。
   • 使用上面的變數來呼叫 threshold() 方法。 產生的臨界值方程式如下：if (current pixel Value & 0x000000FF) >= (0xCCCCCCCC & 0x000000FF) then set pixel to 0xFFFFFF00。

注意：

• 在編譯 SWF 檔時，您必須將「本機播放安全性」設定為「只存取本機檔案」。
• 在此範例中，您需要將名為 Image.gif 的檔案放在與 SWF 檔案所處的相同目錄中。
• 我們建議您使用寬度最多約為 80 像素的影像。

package {
    import flash.display.Bitmap;
    import flash.display.BitmapData;
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.*;
    import flash.geom.Point;
    import flash.geom.Rectangle;
    import flash.net.URLRequest;

    public class BitmapDataExample extends Sprite {
        private var url:String = "Image.gif";
        private var size:uint = 80;

        public function BitmapDataExample() {
            configureAssets();
        }

        private function configureAssets():void {
            var loader:Loader = new Loader();
            loader.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler);
            loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);

            var request:URLRequest = new URLRequest(url);
            loader.x = size * numChildren;
            loader.load(request);
            addChild(loader);
        }

        private function duplicateImage(original:Bitmap):Bitmap {
            var image:Bitmap = new Bitmap(original.bitmapData.clone());
            image.x = size * numChildren;
            addChild(image);
            return image;
        }

        private function completeHandler(event:Event):void {
            var loader:Loader = Loader(event.target.loader);
            var image:Bitmap = Bitmap(loader.content);

            var duplicate:Bitmap = duplicateImage(image);
            var bitmapData:BitmapData = duplicate.bitmapData;
            var sourceRect:Rectangle = new Rectangle(0, 0, bitmapData.width, bitmapData.height);
            var destPoint:Point = new Point();
            var operation:String = ">=";
            var threshold:uint = 0xCCCCCCCC;
            var color:uint = 0xFFFFFF00;
            var mask:uint = 0x000000FF;
            var copySource:Boolean = true;

            bitmapData.threshold(bitmapData,
                                 sourceRect,
                                 destPoint,
                                 operation,
                                 threshold,
                                 color,
                                 mask,
                                 copySource);
        }
        
        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("Unable to load image: " + url);
        }
    }
}