| 套件 | flash.display3D |
| 類別 | public final class Program3D |
| 繼承 | Program3D  Object |
| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | Flash Player 11, AIR 2 |
Program3D 物件管理的程式會控制 Context3D drawTriangles() 呼叫期間，三角形的整個顯示。使用 upload 方法即可將二進位位元組碼上傳到顯示內容 (上傳之後，就不再參考原始位元組陣列中的程式；變更或捨棄來源位元組陣列並不會變更程式)。
程式一律由兩個連結的部分組成：一個頂點和一個片段程式。
- 頂點程式會在 VertexBuffer3D 物件中定義的資料上運作，並且負責將頂點投射到片段空間，以及將任何必要的頂點資料 (例如顏色) 傳遞到片段著色器。
- 片段著色器會在由頂點程式傳給它的屬性上運作，並且會為三角形的每個點陣化片段產生顏色，進而產生像素顏色。請注意，在 3D 程式設計文獻中，片段程式有好幾個名稱，其中包括片段著色器和像素著色器。
透過將對應的 Program3D 實體傳遞到 Context3D setProgram() 方法，可指定哪個程式配對要用於後續顯示作業。
您無法直接建立 Program3D 物件，請改用 Context3D createProgram() 方法。
相關 API 元素
隱藏繼承公用屬性
顯示繼承公用屬性| 方法 | 定義自 | ||
|---|---|---|---|
釋放與這個物件關聯的所有資源。 | Program3D | ||
 |
指出物件是否有已定義的指定屬性。 | Object | |
|
指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。 | Object | |
|
指出指定的屬性是否存在，以及是否可列舉。 | Object | |
|
為迴圈作業設定動態屬性的可用性。 | Object | |
|
傳回代表此物件的字串，根據地區特定慣例進行格式化。 | Object | |
|
會傳回指定之物件的字串形式。 | Object | |
上傳一對以 AGAL (Adobe Graphics Assembly Language) 位元組碼表示的顯示程式。 | Program3D | ||
|
會傳回指定之物件的基本值。 | Object | |
dispose | () | 方法 |
public function dispose():void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | Flash Player 11, AIR 3 |
釋放與這個物件關聯的所有資源。處置 Program3D 物件後，透過這個物件呼叫 upload() 和顯示都會失敗。
upload | () | 方法 |
public function upload(vertexProgram:ByteArray, fragmentProgram:ByteArray):void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | Flash Player 11, AIR 3 |
上傳一對以 AGAL (Adobe Graphics Assembly Language) 位元組碼表示的顯示程式。
使用 Pixel Bender 3D 離線工具可建立程式位元組碼。也可以動態建立它。AGALMiniAssembler 類別是公用程式類別，可將 AGAL 組合語言程式編譯為 AGAL 位元組碼。此類別不是執行階段的一部分。當您上傳著色器程式時，位元組碼會編譯至目前裝置的原生著色器語言 (例如 OpenGL 或 Direct3D)。執行階段會在上傳時驗證位元組碼。
每當叫用 Context3D drawTriangles() 方法時，程式都會執行。在要繪製的三角形清單中，頂點程式會針對每個頂點執行一次。片段程式會針對三角形表面的每個像素執行一次。
著色器程式所使用的「變數」稱為「暫存器」。下列是定義的暫存器：
| 名稱 | 每個片段程式的數目 | 每個頂點程式的數目 | 目的 |
|---|---|---|---|
| 特質 | 不適用 | 8 | 頂點著色器輸入；從使用 Context3D.setVertexBufferAt() 指定的頂點緩衝區中讀取。 |
| 常數 | 28 | 128 | 著色器輸入；使用函數的 Context3D.setProgramConstants() 系列來設定。 |
| 暫時 | 8 | 8 | 計算用的暫時暫存器，無法從程式外存取。 |
| 輸出 | 1 | 1 | 著色器輸出：在頂點程式中，輸出是片段空間位置；在片段程式中，輸出則是顏色。 |
| 不同 | 8 | 8 | 在頂點和片段著色器之間傳輸插補的資料。頂點程式中的不同暫存器會以輸入形式套用到片段程式。值是根據與三角形頂點的距離來插補。 |
| 取樣程式 | 8 | 不適用 | 片段著色器輸入；從使用 Context3D.setTextureAt() 指定的紋理讀取。 |
頂點程式會從兩個來源收到輸入：頂點緩衝區和常數暫存器。使用 Context3D setVertexBufferAt() 方法，指定哪些頂點資料要用於特定頂點 attribute 暫存器。您最多可以為頂點屬性定義 8 個輸入暫存器。頂點屬性值是從三角形清單中每個頂點的頂點緩衝區讀取，並置於屬性暫存器中。使用 Context3D setProgramConstantsFromMatrix() 或 setProgramConstantsFromVector() 方法，可以指定 constant 暫存器。常數暫存器會保持三角形清單中每個頂點的值都一樣 (您可以只修改 drawTriangles() 呼叫之間的常數值)。
頂點程式負責將三角形頂點投射到片段空間 (x 軸和 y 軸上 ±1 與 z 軸上 0-1 內的標準檢視區域)，以及將變形座標放在輸出暫存器中 (通常會提供適當的投射矩陣給一組常數暫存器中的著色器)。此外，頂點程式還必須將片段程式所需的任何頂點屬性或算出的值複製給一組特殊的變數，稱為 varying 暫存器。當片段著色器執行時，不同暫存器中提供的值在線性上會根據目前片段與每個三角形頂點的距離來插補。
片段程式會收到來自不同暫存器和個別常數暫存器 (使用 setProgramConstantsFromMatrix() 或 setProgramConstantsFromVector() 設定) 的輸入。您也可以使用 sampler 暫存器，從上傳到顯示內容的紋理讀取紋理資料。使用 Context3D setTextureAt() 方法，指定要與特定取樣程式暫存器一起存取的紋理。片段程式負責將它的輸出暫存器設定為顏色值。
參數
vertexProgram:ByteArray — 頂點程式的 AGAL 位元組碼。ByteArray 物件必須使用 little endian 格式。
| |
fragmentProgram:ByteArray — 片段程式的 AGAL 位元組碼。ByteArray 物件必須使用 little endian 格式。
|
擲回值
TypeError — Null 指標錯誤：vertexProgram 或 fragmentProgram 為 null。
| |
Error — 物件已處理：Program3D 物件已透過呼叫 dispose() 的方式直接處理，或是透過呼叫 Context3D dispose() 的方式間接處理，或是因為裝置損失而處理顯示內容。
| |
ArgumentError — AGAL 程式太小：有任一程式碼陣列的長度小於 31 個位元組。這是單一指示程式的著色器位元組碼大小。
| |
ArgumentError — 程式必須為 Little Endian：有任一程式位元組程式碼陣列不是 Little Endian。
| |
Error — 原生著色器編譯失敗：AGAL 轉譯程式的輸出不是可編譯的原生著色器語言程式。只有在發佈播放程式才會擲回此錯誤。
| |
Error — 原生著色器編譯失敗 (OpenGL)：AGAL 轉譯程式的輸出不是可編譯的 OpengGL 著色器語言程式，並且包含編譯診斷。只有在除錯播放程式才會擲回此錯誤。
| |
Error — 原生著色器編譯失敗 (D3D9)：AGAL 轉譯程式的輸出不是可編譯的 Direct3D 著色器語言程式，並且包含編譯診斷。只有在除錯播放程式才會擲回此錯誤。
當 AGAL 位元組碼驗證失敗時，會擲回下列錯誤： | |
Error — 不是 AGAL 程式：標題「魔術位元組」不正確。位元組碼的第一個位元組必須是 0xa0。這個錯誤可代表位元組陣列設定為錯誤的 endian 順序。
| |
Error — AGAL 版本不正確：目前 SWF 版本不支援 AGAL 版本SWF 版本 13 的 AGAL 版本必須設定為 1。
| |
Error — AGAL 程式類型不正確：AGAL 程式類型識別名稱無效。位元組碼中的第三位元組必須是 0xa1。這個錯誤可代表位元組陣列設定為錯誤的 endian 順序。
| |
Error — AGAL 著色器類型不正確：著色器類型代碼不是片段或頂點 (1 或 0)。
| |
Error — 無效的 AGAL Opcode 超出範圍：在字符串流中遇到無效的 opcode。
| |
Error — 無效的 AGAL Opcode 未實作：在字符串流中遇到無效的 opcode。
| |
Error — AGAL Opcode 只允許用於片段程式：在只允許用於片段程式之頂點程式的字符串流中遇到 opcode，例如 KIL 或 TEX。
| |
Error — AGAL 來源運算元不正確：兩個來源運算元都是常數暫存器。您必須計算著色器程式之外的結果，然後使用單一常數暫存器將它傳入。
| |
Error — 兩個運算元都是間接讀取：兩個運算元都是間接讀取。
| |
Error — Opcode 目的地必須全為零：字符的 opcode (例如 KIL) 沒有目的地，並且未設定目的地暫存器的非零值。
| |
Error — Opcode 目的地必須使用遮色片：opcode 只產生 3 個組件結果，並且使用時未先套用遮色片。
| |
Error — 太多字符：AGAL 程式中有太多字符 (超過 200 個)。
| |
Error — 片段著色器類型：片段程式類型 (fragmentProgram 參數的第 6 個位元組) 不是設定為 1。
| |
Error — 頂點著色器類型：頂點程式類型 (vertexProgram 參數的第 6 個位元組) 不是設定為 0。
| |
Error — 不同的讀取但未寫入：片段著色器讀取不同暫存器，該暫存器從未由頂點著色器寫入。
| |
Error — 不同部分寫入：僅部分寫入不同暫存器。必須寫入不同暫存器的所有組件。
| |
Error — 片段寫入所有組件：僅部分寫入片段色彩輸出。必須寫入之色彩輸出的全部四個組件。
| |
Error — 頂點寫入所有組件：僅部分寫入頂點片段空間輸出。必須寫入之頂點片段空間輸出的所有組件。
| |
Error — 未使用的運算元：字符中未使用的運算元未全部設定為零。
| |
Error — 僅限在片段程式中使用取樣程式暫存器：在頂點程式中使用紋理取樣程式暫存器。
| |
Error — 取樣程式暫存器的第二個運算元：使用取樣程式暫存器做為 AGAL 字符的目標或第一個運算元。
| |
Error — 僅允許在頂點程式中間接定址：在片段程式中使用間接定址。
| |
Error — 僅限在常數暫存器間接定址：在非常數暫存器中使用間接定址。
| |
Error — 間接來源類型：間接來源類型不是屬性、常數或暫時暫存器。
| |
Error — 間接定址欄位必須為零：並非所有間接定址欄位均為零，以用於直接定址。
| |
Error — 僅限在片段程式讀取不同暫存器：在頂點程式中讀取不同暫存器。不同暫存器只能以頂點程式寫入並以片段程式讀取。
| |
Error — 僅限在頂點程式讀取屬性暫存器：在片段程式中讀取屬性暫存器。屬性暫存器只能以頂點程式讀取。
| |
Error — 無法讀取輸出暫存器：讀取輸出 (位置或顏色) 暫存器。輸出暫存器只能寫入而不可讀取。
| |
Error — 未寫入即讀取暫時暫存器：之前並未寫入暫時暫存器便加以讀取。
| |
Error — 未寫入即讀取暫時暫存器組件：之前並未寫入特定暫時暫存器組件，便加以讀取。
| |
Error — 無法寫入取樣程式暫存器：寫入取樣程式暫存器。取樣程式暫存器只能讀取而不可寫入。
| |
Error — 寫入不同暫存器：將不同暫存器寫入片段程式。不同暫存器只能以頂點程式寫入並以片段程式讀取。
| |
Error — 無法寫入屬性暫存器：寫入屬性暫存器。屬性暫存器是唯讀的。
| |
Error — 無法寫入常數暫存器：寫入著色器程式內的常數暫存器。
| |
Error — 目標寫入遮色片為零：目標寫入遮色片為零。輸出暫存器的所有組件必須都已設定。
| |
Error — AGAL 保留位元應為零：字符中有任何非零的保留位元。這表示建立位元組碼時發生錯誤 (或位元組碼格式錯誤)。
| |
Error — 不明的暫存器類型：使用無效的暫存器類型索引。
| |
Error — 取樣程式暫存器超出範圍：使用無效的取樣程式暫存器索引。
| |
Error — 不同暫存器超出範圍：使用無效的不同暫存器索引。
| |
Error — 屬性暫存器超出範圍：使用無效的屬性暫存器索引。
| |
Error — 常數暫存器超出範圍：使用無效的常數暫存器索引。
| |
Error — 輸出暫存器超出範圍：使用無效的輸出暫存器索引。
| |
Error — 暫時暫存器超出範圍：使用無效的暫時暫存器索引。
| |
Error — 立方體對應取樣程式必須使用固定：立方體對應取樣程式未將換行模式設定為固定。
| |
Error — 不明的取樣程式尺寸：有樣本使用不明的取樣程式尺寸 (僅支援 2D 與立方體紋理)。
| |
Error — 不明的濾鏡模式：取樣程式使用不明的濾鏡模式 (僅支援最近鄰點與線性濾鏡處理)。
| |
Error — 不明的 MIP 映射模式：取樣程式使用不明的 MIP 映射模式 (僅支援無、最近鄰點及線性 MIP 映射模式)。
| |
Error — 不明的換行模式：取樣程式使用不明的換行模式 (僅支援固定與重複換行模式)。
| |
Error — 不明的特殊旗標：取樣程式使用不明的特殊旗標。
| |
Error — 無法遮蔽輸出色彩：您無法以片段程式來遮蔽色彩輸出暫存器。色彩暫存器的所有組件必須都已設定。
| |
Error — 第二個運算元必須是取樣程式暫存器：AGAL 紋理 opcode 必須讓某取樣程式做為第二個來源運算元。
| |
Error — 不允許間接定址：在不允許的地方使用間接定址。
| |
Error — 拌和必須為純量：拌和時發生錯誤。
| |
Error — 無法拌和第二個來源：拌和時發生錯誤。
| |
Error — 再次使用的取樣程式必須有相同的參數：處理相同紋理的所有取樣程式都必須使用相同的尺寸、換行、濾鏡、特殊及 MIP 映射設定。
| |
Error — 3768：在背景執行期間不會使用 Stage3D API。
|
詳細資訊
相關 API 元素
Tue Jun 12 2018, 03:47 PM Z