適用於 Adobe® Flash® Platform 的 ActionScript® 3.0 參考
首頁  |  隱藏套件和類別清單 |  套件  |  類別  |  新增內容  |  索引  |  附錄  |  為什麼顯示英文?
篩選: AIR 30.0 和更早版本, Flash Player 30.0 和更早版本, Flash Lite 4
Flex 4.6 和更早版本, Flash Pro CS6 和更早版本
隱藏篩選
flash.display3D 

Context3D  - AS3

套件x

最上層
adobe.utils
air.desktop
air.net
air.update
air.update.events
coldfusion.air
coldfusion.air.errors
coldfusion.air.events
coldfusion.service
coldfusion.service.events
coldfusion.service.mxml
com.adobe.acm.solutions.authoring.domain.extensions
com.adobe.acm.solutions.ccr.domain.extensions
com.adobe.consulting.pst.vo
com.adobe.dct.component
com.adobe.dct.component.datadictionary
com.adobe.dct.component.datadictionaryElement
com.adobe.dct.component.dataElementsPanel
com.adobe.dct.component.toolbars
com.adobe.dct.event
com.adobe.dct.exp
com.adobe.dct.model
com.adobe.dct.service
com.adobe.dct.service.provider
com.adobe.dct.transfer
com.adobe.dct.util
com.adobe.dct.view
com.adobe.ep.taskmanagement.domain
com.adobe.ep.taskmanagement.event
com.adobe.ep.taskmanagement.filter
com.adobe.ep.taskmanagement.services
com.adobe.ep.taskmanagement.util
com.adobe.ep.ux.attachmentlist.component
com.adobe.ep.ux.attachmentlist.domain
com.adobe.ep.ux.attachmentlist.domain.events
com.adobe.ep.ux.attachmentlist.domain.renderers
com.adobe.ep.ux.attachmentlist.skin
com.adobe.ep.ux.attachmentlist.skin.renderers
com.adobe.ep.ux.content.event
com.adobe.ep.ux.content.factory
com.adobe.ep.ux.content.handlers
com.adobe.ep.ux.content.managers
com.adobe.ep.ux.content.model.asset
com.adobe.ep.ux.content.model.preview
com.adobe.ep.ux.content.model.relation
com.adobe.ep.ux.content.model.search
com.adobe.ep.ux.content.model.toolbar
com.adobe.ep.ux.content.search
com.adobe.ep.ux.content.services
com.adobe.ep.ux.content.services.load
com.adobe.ep.ux.content.services.permissions
com.adobe.ep.ux.content.services.preview
com.adobe.ep.ux.content.services.providers
com.adobe.ep.ux.content.services.query
com.adobe.ep.ux.content.services.relationships
com.adobe.ep.ux.content.services.search.lccontent
com.adobe.ep.ux.content.services.version
com.adobe.ep.ux.content.view
com.adobe.ep.ux.content.view.components.activate
com.adobe.ep.ux.content.view.components.grid
com.adobe.ep.ux.content.view.components.grid.hover
com.adobe.ep.ux.content.view.components.grid.hover.component
com.adobe.ep.ux.content.view.components.grid.renderers
com.adobe.ep.ux.content.view.components.relationships
com.adobe.ep.ux.content.view.components.review
com.adobe.ep.ux.content.view.components.search.renderers
com.adobe.ep.ux.content.view.components.searchpod
com.adobe.ep.ux.content.view.components.toolbar
com.adobe.ep.ux.content.view.components.toolbar.controlRenderers
com.adobe.ep.ux.content.view.components.version
com.adobe.ep.ux.documentsubmit.component
com.adobe.ep.ux.documentsubmit.domain
com.adobe.ep.ux.documentsubmit.skin
com.adobe.ep.ux.taskaction.component
com.adobe.ep.ux.taskaction.domain
com.adobe.ep.ux.taskaction.domain.events
com.adobe.ep.ux.taskaction.skin
com.adobe.ep.ux.taskdetails.component
com.adobe.ep.ux.taskdetails.domain
com.adobe.ep.ux.taskdetails.skin
com.adobe.ep.ux.tasklist.component
com.adobe.ep.ux.tasklist.domain
com.adobe.ep.ux.tasklist.skin
com.adobe.ep.ux.webdocumentviewer.domain
com.adobe.exm.expression
com.adobe.exm.expression.error
com.adobe.exm.expression.event
com.adobe.exm.expression.impl
com.adobe.fiber.runtime.lib
com.adobe.fiber.services
com.adobe.fiber.services.wrapper
com.adobe.fiber.styles
com.adobe.fiber.util
com.adobe.fiber.valueobjects
com.adobe.gravity.binding
com.adobe.gravity.context
com.adobe.gravity.flex.bundleloader
com.adobe.gravity.flex.progress
com.adobe.gravity.flex.serviceloader
com.adobe.gravity.framework
com.adobe.gravity.init
com.adobe.gravity.service.bundleloader
com.adobe.gravity.service.logging
com.adobe.gravity.service.manifest
com.adobe.gravity.service.progress
com.adobe.gravity.tracker
com.adobe.gravity.ui
com.adobe.gravity.utility
com.adobe.gravity.utility.async
com.adobe.gravity.utility.error
com.adobe.gravity.utility.events
com.adobe.gravity.utility.factory
com.adobe.gravity.utility.flex.async
com.adobe.gravity.utility.logging
com.adobe.gravity.utility.message
com.adobe.gravity.utility.sequence
com.adobe.gravity.utility.url
com.adobe.guides.control
com.adobe.guides.domain
com.adobe.guides.i18n
com.adobe.guides.spark.components.skins
com.adobe.guides.spark.components.skins.mx
com.adobe.guides.spark.headers.components
com.adobe.guides.spark.headers.skins
com.adobe.guides.spark.layouts.components
com.adobe.guides.spark.layouts.skins
com.adobe.guides.spark.navigators.components
com.adobe.guides.spark.navigators.renderers
com.adobe.guides.spark.navigators.skins
com.adobe.guides.spark.util
com.adobe.guides.spark.wrappers.components
com.adobe.guides.spark.wrappers.skins
com.adobe.guides.submit
com.adobe.icc.dc.domain
com.adobe.icc.dc.domain.factory
com.adobe.icc.editors.events
com.adobe.icc.editors.handlers
com.adobe.icc.editors.managers
com.adobe.icc.editors.model
com.adobe.icc.editors.model.config
com.adobe.icc.editors.model.el
com.adobe.icc.editors.model.el.operands
com.adobe.icc.editors.model.el.operators
com.adobe.icc.enum
com.adobe.icc.external.dc
com.adobe.icc.obj
com.adobe.icc.services
com.adobe.icc.services.category
com.adobe.icc.services.config
com.adobe.icc.services.download
com.adobe.icc.services.export
com.adobe.icc.services.external
com.adobe.icc.services.formbridge
com.adobe.icc.services.fragmentlayout
com.adobe.icc.services.layout
com.adobe.icc.services.letter
com.adobe.icc.services.locator
com.adobe.icc.services.module
com.adobe.icc.services.render
com.adobe.icc.services.submit
com.adobe.icc.services.user
com.adobe.icc.token
com.adobe.icc.vo
com.adobe.icc.vo.render
com.adobe.icomm.assetplacement.controller
com.adobe.icomm.assetplacement.controller.utils
com.adobe.icomm.assetplacement.data
com.adobe.icomm.assetplacement.model
com.adobe.livecycle.assetmanager.client
com.adobe.livecycle.assetmanager.client.event
com.adobe.livecycle.assetmanager.client.handler
com.adobe.livecycle.assetmanager.client.managers
com.adobe.livecycle.assetmanager.client.model
com.adobe.livecycle.assetmanager.client.model.cms
com.adobe.livecycle.assetmanager.client.service
com.adobe.livecycle.assetmanager.client.service.search
com.adobe.livecycle.assetmanager.client.service.search.cms
com.adobe.livecycle.assetmanager.client.utils
com.adobe.livecycle.content
com.adobe.livecycle.rca.model
com.adobe.livecycle.rca.model.constant
com.adobe.livecycle.rca.model.document
com.adobe.livecycle.rca.model.participant
com.adobe.livecycle.rca.model.reminder
com.adobe.livecycle.rca.model.stage
com.adobe.livecycle.rca.service
com.adobe.livecycle.rca.service.core
com.adobe.livecycle.rca.service.core.delegate
com.adobe.livecycle.rca.service.process
com.adobe.livecycle.rca.service.process.delegate
com.adobe.livecycle.rca.token
com.adobe.livecycle.ria.security.api
com.adobe.livecycle.ria.security.service
com.adobe.mosaic.layouts
com.adobe.mosaic.layouts.dragAndDrop
com.adobe.mosaic.layouts.interfaces
com.adobe.mosaic.mxml
com.adobe.mosaic.om.constants
com.adobe.mosaic.om.events
com.adobe.mosaic.om.impl
com.adobe.mosaic.om.interfaces
com.adobe.mosaic.skinning
com.adobe.mosaic.sparklib.editors
com.adobe.mosaic.sparklib.optionMenu
com.adobe.mosaic.sparklib.scrollableMenu
com.adobe.mosaic.sparklib.scrollableMenu.skins
com.adobe.mosaic.sparklib.tabLayout
com.adobe.mosaic.sparklib.tabLayout.events
com.adobe.mosaic.sparklib.tabLayout.layouts
com.adobe.mosaic.sparklib.tabLayout.skins
com.adobe.mosaic.sparklib.text
com.adobe.mosaic.sparklib.util
com.adobe.solutions.acm.authoring.presentation
com.adobe.solutions.acm.authoring.presentation.actionbar
com.adobe.solutions.acm.authoring.presentation.common
com.adobe.solutions.acm.authoring.presentation.events
com.adobe.solutions.acm.authoring.presentation.fragment
com.adobe.solutions.acm.authoring.presentation.letter
com.adobe.solutions.acm.authoring.presentation.letter.data
com.adobe.solutions.acm.authoring.presentation.preview
com.adobe.solutions.acm.authoring.presentation.rte
com.adobe.solutions.acm.ccr.presentation
com.adobe.solutions.acm.ccr.presentation.contentcapture
com.adobe.solutions.acm.ccr.presentation.contentcapture.events
com.adobe.solutions.acm.ccr.presentation.contentcapture.preview
com.adobe.solutions.acm.ccr.presentation.datacapture
com.adobe.solutions.acm.ccr.presentation.datacapture.renderers
com.adobe.solutions.acm.ccr.presentation.pdf
com.adobe.solutions.exm
com.adobe.solutions.exm.authoring
com.adobe.solutions.exm.authoring.components.controls
com.adobe.solutions.exm.authoring.components.toolbars
com.adobe.solutions.exm.authoring.domain
com.adobe.solutions.exm.authoring.domain.expression
com.adobe.solutions.exm.authoring.domain.impl
com.adobe.solutions.exm.authoring.domain.method
com.adobe.solutions.exm.authoring.domain.variable
com.adobe.solutions.exm.authoring.enum
com.adobe.solutions.exm.authoring.events
com.adobe.solutions.exm.authoring.model
com.adobe.solutions.exm.authoring.renderer
com.adobe.solutions.exm.authoring.view
com.adobe.solutions.exm.expression
com.adobe.solutions.exm.impl
com.adobe.solutions.exm.impl.method
com.adobe.solutions.exm.method
com.adobe.solutions.exm.mock
com.adobe.solutions.exm.mock.method
com.adobe.solutions.exm.runtime
com.adobe.solutions.exm.runtime.impl
com.adobe.solutions.exm.variable
com.adobe.solutions.prm.constant
com.adobe.solutions.prm.domain
com.adobe.solutions.prm.domain.factory
com.adobe.solutions.prm.domain.impl
com.adobe.solutions.prm.domain.manager
com.adobe.solutions.prm.presentation.asset
com.adobe.solutions.prm.presentation.constant
com.adobe.solutions.prm.presentation.document
com.adobe.solutions.prm.presentation.event
com.adobe.solutions.prm.presentation.file
com.adobe.solutions.prm.presentation.project
com.adobe.solutions.prm.presentation.team
com.adobe.solutions.prm.presentation.util
com.adobe.solutions.prm.service
com.adobe.solutions.prm.services.impl
com.adobe.solutions.prm.vo
com.adobe.solutions.rca.constant
com.adobe.solutions.rca.domain
com.adobe.solutions.rca.domain.common
com.adobe.solutions.rca.domain.factory
com.adobe.solutions.rca.domain.impl
com.adobe.solutions.rca.domain.impl.manager
com.adobe.solutions.rca.domain.manager
com.adobe.solutions.rca.presentation
com.adobe.solutions.rca.presentation.comment
com.adobe.solutions.rca.presentation.constant
com.adobe.solutions.rca.presentation.event
com.adobe.solutions.rca.presentation.gantt
com.adobe.solutions.rca.presentation.gantt.ruler
com.adobe.solutions.rca.presentation.template
com.adobe.solutions.rca.presentation.template.audit
com.adobe.solutions.rca.presentation.template.definition
com.adobe.solutions.rca.presentation.template.documents
com.adobe.solutions.rca.presentation.template.stages
com.adobe.solutions.rca.presentation.util
com.adobe.solutions.rca.service
com.adobe.solutions.rca.services.impl
com.adobe.solutions.rca.vo
com.adobe.solutions.rca.vo.um
com.adobe.viewsource
fl.accessibility
fl.containers
fl.controls
fl.controls.dataGridClasses
fl.controls.listClasses
fl.controls.progressBarClasses
fl.core
fl.data
fl.display
fl.events
fl.ik
fl.lang
fl.livepreview
fl.managers
fl.motion
fl.motion.easing
fl.rsl
fl.text
fl.transitions
fl.transitions.easing
fl.video
flash.accessibility
flash.concurrent
flash.crypto
flash.data
flash.desktop
flash.display
flash.display3D
flash.display3D.textures
flash.errors
flash.events
flash.external
flash.filesystem
flash.filters
flash.geom
flash.globalization
flash.html
flash.media
flash.net
flash.net.dns
flash.net.drm
flash.notifications
flash.permissions
flash.printing
flash.profiler
flash.sampler
flash.security
flash.sensors
flash.system
flash.text
flash.text.engine
flash.text.ime
flash.ui
flash.utils
flash.xml
flashx.textLayout
flashx.textLayout.compose
flashx.textLayout.container
flashx.textLayout.conversion
flashx.textLayout.edit
flashx.textLayout.elements
flashx.textLayout.events
flashx.textLayout.factory
flashx.textLayout.formats
flashx.textLayout.operations
flashx.textLayout.utils
flashx.undo
ga.controls
ga.layouts
ga.model
ga.uiComponents
ga.util
ga.views
ga.wrappers
lc.foundation
lc.foundation.domain
lc.foundation.events
lc.foundation.ui
lc.foundation.util
lc.preloader
lc.procmgmt
lc.procmgmt.commands
lc.procmgmt.domain
lc.procmgmt.events
lc.procmgmt.formbridge
lc.procmgmt.impl
lc.procmgmt.ui.attachments
lc.procmgmt.ui.controls
lc.procmgmt.ui.controls.card
lc.procmgmt.ui.controls.renderer
lc.procmgmt.ui.help
lc.procmgmt.ui.layout
lc.procmgmt.ui.presentationmodel
lc.procmgmt.ui.process
lc.procmgmt.ui.search
lc.procmgmt.ui.startpoint
lc.procmgmt.ui.task
lc.procmgmt.ui.task.form
lc.procmgmt.ui.task.form.commands
lc.procmgmt.ui.tracking
mx.accessibility
mx.automation
mx.automation.air
mx.automation.delegates
mx.automation.delegates.advancedDataGrid
mx.automation.delegates.charts
mx.automation.delegates.containers
mx.automation.delegates.controls
mx.automation.delegates.controls.dataGridClasses
mx.automation.delegates.controls.fileSystemClasses
mx.automation.delegates.core
mx.automation.delegates.flashflexkit
mx.automation.events
mx.binding
mx.binding.utils
mx.charts
mx.charts.chartClasses
mx.charts.effects
mx.charts.effects.effectClasses
mx.charts.events
mx.charts.renderers
mx.charts.series
mx.charts.series.items
mx.charts.series.renderData
mx.charts.styles
mx.collections
mx.collections.errors
mx.containers
mx.containers.accordionClasses
mx.containers.dividedBoxClasses
mx.containers.errors
mx.containers.utilityClasses
mx.controls
mx.controls.advancedDataGridClasses
mx.controls.dataGridClasses
mx.controls.listClasses
mx.controls.menuClasses
mx.controls.olapDataGridClasses
mx.controls.scrollClasses
mx.controls.sliderClasses
mx.controls.textClasses
mx.controls.treeClasses
mx.controls.videoClasses
mx.core
mx.core.windowClasses
mx.data
mx.data.crypto
mx.data.errors
mx.data.events
mx.data.messages
mx.data.mxml
mx.data.offline.errors
mx.data.utils
mx.effects
mx.effects.easing
mx.effects.effectClasses
mx.events
mx.filters
mx.flash
mx.formatters
mx.geom
mx.graphics
mx.graphics.codec
mx.graphics.shaderClasses
mx.logging
mx.logging.errors
mx.logging.targets
mx.managers
mx.messaging
mx.messaging.channels
mx.messaging.config
mx.messaging.errors
mx.messaging.events
mx.messaging.management
mx.messaging.messages
mx.modules
mx.netmon
mx.olap
mx.olap.aggregators
mx.preloaders
mx.printing
mx.resources
mx.rpc
mx.rpc.events
mx.rpc.http
mx.rpc.http.mxml
mx.rpc.livecycle
mx.rpc.mxml
mx.rpc.remoting
mx.rpc.remoting.mxml
mx.rpc.soap
mx.rpc.soap.mxml
mx.rpc.wsdl
mx.rpc.xml
mx.skins
mx.skins.halo
mx.skins.spark
mx.skins.wireframe
mx.skins.wireframe.windowChrome
mx.states
mx.styles
mx.utils
mx.validators
org.osmf.containers
org.osmf.display
org.osmf.elements
org.osmf.events
org.osmf.layout
org.osmf.logging
org.osmf.media
org.osmf.metadata
org.osmf.net
org.osmf.net.dvr
org.osmf.net.httpstreaming
org.osmf.net.metrics
org.osmf.net.qos
org.osmf.net.rtmpstreaming
org.osmf.net.rules
org.osmf.traits
org.osmf.utils
spark.accessibility
spark.automation.delegates
spark.automation.delegates.components
spark.automation.delegates.components.gridClasses
spark.automation.delegates.components.mediaClasses
spark.automation.delegates.components.supportClasses
spark.automation.delegates.skins.spark
spark.automation.events
spark.collections
spark.components
spark.components.calendarClasses
spark.components.gridClasses
spark.components.mediaClasses
spark.components.supportClasses
spark.components.windowClasses
spark.core
spark.effects
spark.effects.animation
spark.effects.easing
spark.effects.interpolation
spark.effects.supportClasses
spark.events
spark.filters
spark.formatters
spark.formatters.supportClasses
spark.globalization
spark.globalization.supportClasses
spark.layouts
spark.layouts.supportClasses
spark.managers
spark.modules
spark.preloaders
spark.primitives
spark.primitives.supportClasses
spark.skins
spark.skins.mobile
spark.skins.mobile.supportClasses
spark.skins.spark
spark.skins.spark.mediaClasses.fullScreen
spark.skins.spark.mediaClasses.normal
spark.skins.spark.windowChrome
spark.skins.wireframe
spark.skins.wireframe.mediaClasses
spark.skins.wireframe.mediaClasses.fullScreen
spark.transitions
spark.utils
spark.validators
spark.validators.supportClasses
xd.core.axm.enterprise.view.components
xd.core.axm.enterprise.view.skins
xd.core.axm.view.components
xd.core.axm.view.components.support

語言元素

全域常數
全域函數
運算子
陳述式、關鍵字和指令
特殊類型

附錄

新增內容
編譯器錯誤
編譯器警告
執行階段錯誤
移轉至 ActionScript 3
支援的字元集
僅限 MXML 標籤
移動 XML 元素
Timed Text 標籤
不建議元素清單
AccessibilityImplementation 常數
如何使用 ActionScript 範例
法律聲明
套件flash.display3D
類別public final class Context3D
繼承Context3D Inheritance EventDispatcher Inheritance Object

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

Context3D 類別會提供用於顯示以幾何圖形定義之圖像的內容。

顯示內容包括繪製表面及其關聯的資源和狀態。如果可以,顯示內容會使用硬體圖像處理單元 (GPU)。否則,顯示內容會使用軟體 (如果平台不支援透過 Context3D 顯示,則 Stage 物件的 stage3Ds 屬性會包含空白清單)。

Context3D 顯示內容是可程式化的管線,與 OpenGL ES 2 非常類似,但它是抽象的,因此與各種硬體和 GPU 介面相容。雖然專為 3D 圖像而設計,但是顯示管線不會將顯示視為三維。因此,您可以提供適當的頂點和像素片段程式,藉此建立 2D 輸出器。在 3D 和 2D 情況中,唯一支援的幾何基本圖形為三角形。

透過呼叫 Stage3D 物件的 requestContext3D() 方法,取得 Context3D 類別的實體。每個舞台都有有限數目的 Context3D 物件;Stage.stage3Ds 清單中的每個 Stage3D 各有一個。當建立內容時,Stage3D 物件會傳送 context3DCreate 事件。顯示內容可以隨時移除再重新建立,例如,另一個使用 GPU 的應用程式取得焦點時。您的程式碼應預期會收到多個 context3DCreate 事件。請使用關聯 Stage3D 實體的 xy 屬性,將顯示區域放置在舞台上。

若要顯示一個場景 (在取得 Context3D 物件之後),通常會執行下列步驟:

  1. 呼叫 configureBackBuffer() 來設定主要顯示緩衝屬性。
  2. 建立並初始化您的顯示資源,包括:
    • 定義場景幾何的頂點和索引緩衝區
    • 用於顯示場景的頂點和像素程式 (著色器)
    • 紋理
  3. 顯示影格:
    • 適時為場景中的物件或物件集合設定顯示狀態。
    • 呼叫 drawTriangles() 方法來顯示一組三角形。
    • 變更下一個物件群組的顯示狀態。
    • 呼叫 drawTriangles() 來繪製定義物件的三角形。
    • 重複執行,直到完整顯示場景為止。
    • 呼叫 present() 方法,讓顯示的場景在舞台上顯示。

顯示時會套用下列限制:

資源限制:

資源允許的數目記憶體總數
頂點緩衝區 4096256 MB
索引緩衝區 4096128 MB
程式 409616 MB
紋理 4096128 MB
立方體紋理 4096256 MB

AGAL 限制:每個程式各有 200 個 opcode。

繪製呼叫限制:每個 present() 呼叫有 32,768 個 drawTriangles() 呼叫。

下列限制會套用至紋理:

AIR 32 位元的紋理限制:

紋理大小上限總計 GPU 記憶體
一般紋理 (在延伸的基線之下) 2048x2048512 MB
一般紋理 (延伸的基線以及以上) 4096x4096512 MB
矩形紋理 (在延伸的基線之下) 2048x2048512 MB
矩形紋理 (延伸的基線以及以上) 4096x4096512 MB
立方體紋理 1024x1024256 MB

AIR 64 位元的紋理限制 (桌上型電腦):

紋理大小上限總計 GPU 記憶體
一般紋理 (在延伸的基線之下) 2048x2048512 MB
一般紋理 (基線延伸到標準) 4096x4096512 MB
一般紋理 (延伸的標準以及以上) 4096x40962048 MB
矩形紋理 (在延伸的基線之下) 2048x2048512 MB
矩形紋理 (基線延伸到標準) 4096x4096512 MB
矩形紋理 (延伸的標準以及以上) 4096x40962048 MB
立方體紋理 1024x1024256 MB

512 MB 是紋理的絕對限制,其中包括 MIP 映射所需的紋理記憶體。然而,立方體紋理的記憶體限制為 256 MB。

您無法搭配 Context3D 建構函式建立 Context3D 物件。它是建構及做為 Stage3D 實體的屬性使用。Context3D 類別可以在桌上型電腦和行動裝置平台上使用,而且兩者皆在 Flash Player 和 AIR 中執行。

檢視範例

相關 API 元素



公用屬性
 屬性定義自
  backBufferHeight : int
[唯讀] 指定背景緩衝區的高度,成功呼叫 configureBackBuffer() 方法即可加以變更。
Context3D
  backBufferWidth : int
[唯讀] 指定背景緩衝區的寬度,成功呼叫 configureBackBuffer() 方法即可加以變更。
Context3D
 Inheritedconstructor : Object
類別物件的參照或是特定物件實體的建構函數。
Object
  driverInfo : String
[唯讀] 此顯示內容使用的圖形庫驅動程式類型。
Context3D
  enableErrorChecking : Boolean
指定是否要將輸出器遇到的錯誤回報給應用程式。
Context3D
  maxBackBufferHeight : int
指定背景緩衝區的最大高度。
Context3D
  maxBackBufferWidth : int
指定背景緩衝區的最大寬度。
Context3D
  profile : String
[唯讀] 這個 Context3D 物件所使用的功能支援描述檔。
Context3D
  supportsVideoTexture : Boolean
[靜態] [唯讀] 指出 Context3D 是否支援視訊紋理。
Context3D
  totalGPUMemory : Number
[唯讀] 傳回應用程式的 Stage3D 資料結構所配置的 GPU 記憶體總數。每當建立 GPU 資源物件時,所使用的記憶體都會儲存在 Context3D 中。
Context3D
公用方法
 方法定義自
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
會在 EventDispatcher 物件註冊事件偵聽程式,以便讓偵聽程式收到事件的通知。
EventDispatcher
  
clear(red:Number = 0.0, green:Number = 0.0, blue:Number = 0.0, alpha:Number = 1.0, depth:Number = 1.0, stencil:uint = 0, mask:uint = 0xffffffff):void
清除與此 Context3D 物件相關聯的顏色、深度和模板緩衝區,然後以指定的值填入那些緩衝區。
Context3D
  
configureBackBuffer(width:int, height:int, antiAlias:int, enableDepthAndStencil:Boolean = true, wantsBestResolution:Boolean = false, wantsBestResolutionOnBrowserZoom:Boolean = false):void
設定顯示緩衝區的檢視區域尺寸和其它屬性。
Context3D
  
createCubeTexture(size:int, format:String, optimizeForRenderToTexture:Boolean, streamingLevels:int = 0):flash.display3D.textures:CubeTexture
建立 CubeTexture 物件。
Context3D
  
createIndexBuffer(numIndices:int, bufferUsage:String = "staticDraw"):IndexBuffer3D
建立 IndexBuffer3D 物件。
Context3D
  
建立 Program3D 物件。
Context3D
  
createRectangleTexture(width:int, height:int, format:String, optimizeForRenderToTexture:Boolean):flash.display3D.textures:RectangleTexture
建立 Rectangle Texture 物件。
Context3D
  
createTexture(width:int, height:int, format:String, optimizeForRenderToTexture:Boolean, streamingLevels:int = 0):flash.display3D.textures:Texture
建立 Texture 物件。
Context3D
  
createVertexBuffer(numVertices:int, data32PerVertex:int, bufferUsage:String = "staticDraw"):VertexBuffer3D
建立 VertexBuffer3D 物件。
Context3D
  
    createVertexBufferForInstances(numVertices:int, data32PerVertex:int, instancesPerElement:int, bufferUsage:String = "staticDraw"):VertexBuffer3D
建立適用於實體資料的 VertexBuffer3D 物件。
Context3D
  
建立 VideoTexture 物件。
Context3D
 Inherited
會將事件傳送到事件流程。
EventDispatcher
  
dispose(recreate:Boolean = true):void
釋放與此 Context3D 關聯的所有資源和內部儲存空間。
Context3D
  
    drawToBitmapData(destination:BitmapData, srcRect:Rectangle = null, destPoint:Point = null):void
繪製目前顯示緩衝區的點陣圖。
Context3D
  
drawTriangles(indexBuffer:IndexBuffer3D, firstIndex:int = 0, numTriangles:int = -1):void
請使用此 Context3D 物件的目前緩衝區和狀態來顯示指定的三角形。
Context3D
  
    drawTrianglesInstanced(indexBuffer:IndexBuffer3D, numInstances:int, firstIndex:int = 0, numTriangles:int = -1):void
請使用此 Context3D 物件的目前緩衝區和狀態來顯示指定的實體化三角形。
Context3D
 Inherited
會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。
EventDispatcher
 Inherited
指出物件是否有已定義的指定屬性。
Object
 Inherited
指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。
Object
  
顯示背景顯示緩衝區。
Context3D
 Inherited
指出指定的屬性是否存在,以及是否可列舉。
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
會從 EventDispatcher 物件移除偵聽程式。
EventDispatcher
  
setBlendFactors(sourceFactor:String, destinationFactor:String):void
指定用於將繪製作業的輸出顏色與現有顏色混合的係數。
Context3D
  
setColorMask(red:Boolean, green:Boolean, blue:Boolean, alpha:Boolean):void
設定將顏色寫入顯示緩衝區時所用的遮色片。
Context3D
  
setCulling(triangleFaceToCull:String):void
設定三角形剔除模式。
Context3D
  
setDepthTest(depthMask:Boolean, passCompareMode:String):void
設定用於深度測試的比較類型。
Context3D
  
    setFillMode(fillMode:String):void
設定用於顯示的填色模式。
Context3D
  
設定頂點和片段著色器程式,以供後續顯示使用。
Context3D
  
setProgramConstantsFromByteArray(programType:String, firstRegister:int, numRegisters:int, data:ByteArray, byteArrayOffset:uint):void
使用 ByteArray 中儲存的值,設定著色器程式所使用的常數。
Context3D
  
setProgramConstantsFromMatrix(programType:String, firstRegister:int, matrix:Matrix3D, transposedMatrix:Boolean = false):void
使用 Matrix3D 中儲存的值,設定著色器程式所使用的常數。
Context3D
  
setProgramConstantsFromVector(programType:String, firstRegister:int, data:Vector.<Number>, numRegisters:int = -1):void
設定著色器程式的常數輸入。
Context3D
 Inherited
為迴圈作業設定動態屬性的可用性。
Object
  
設定背景顯示緩衝區做為顯示目標。
Context3D
  
setRenderToTexture(texture:flash.display3D.textures:TextureBase, enableDepthAndStencil:Boolean = false, antiAlias:int = 0, surfaceSelector:int = 0, colorOutputIndex:int = 0):void
設定指定的紋理做為顯示目標。
Context3D
  
setSamplerStateAt(sampler:int, wrap:String, filter:String, mipfilter:String):void
手動覆寫紋理取樣程式狀態。
Context3D
  
設定剪刀矩形,這是繪製遮色片類型。
Context3D
  
setStencilActions(triangleFace:String = "frontAndBack", compareMode:String = "always", actionOnBothPass:String = "keep", actionOnDepthFail:String = "keep", actionOnDepthPassStencilFail:String = "keep"):void
設定模板模式和作業。
Context3D
  
setStencilReferenceValue(referenceValue:uint, readMask:uint = 255, writeMask:uint = 255):void
設定用於模板測試的模板比較值。
Context3D
  
指定要用於片段程式之紋理輸出暫存器的紋理。
Context3D
  
setVertexBufferAt(index:int, buffer:VertexBuffer3D, bufferOffset:int = 0, format:String = "float4"):void
指定對應至單一頂點著色器程式輸入的頂點資料組件。
Context3D
 Inherited
傳回代表此物件的字串,根據地區特定慣例進行格式化。
Object
 Inherited
會傳回指定之物件的字串形式。
Object
 Inherited
會傳回指定之物件的基本值。
Object
 Inherited
檢查此 EventDispatcher 物件是否已註冊事件偵聽程式,或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。
EventDispatcher
事件
 事件 摘要 定義自
 Inherited[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。EventDispatcher
 Inherited[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。EventDispatcher
屬性詳細資訊

backBufferHeight

屬性
backBufferHeight:int  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: Flash Player 15, AIR 15

指定背景緩衝區的高度,成功呼叫 configureBackBuffer() 方法即可加以變更。在最後一次成功呼叫 configureBackBuffer() 方法中,如果 wantsBestResolutionOnBrowserZoom 設定為 true,則瀏覽器縮放係數變更時可能會修改高度。透過為瀏覽器縮放變更事件註冊事件偵聽程式,即可偵測高度的變更。



實作
    public function get backBufferHeight():int

相關 API 元素

backBufferWidth

屬性 
backBufferWidth:int  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: Flash Player 15, AIR 15

指定背景緩衝區的寬度,成功呼叫 configureBackBuffer() 方法即可加以變更。在最後一次成功呼叫 configureBackBuffer() 方法中,如果 wantsBestResolutionOnBrowserZoom 設定為 true,則瀏覽器縮放係數變更時可能會修改寬度。透過為瀏覽器縮放變更事件註冊事件偵聽程式,即可偵測寬度的變更。



實作
    public function get backBufferWidth():int

相關 API 元素

driverInfo

屬性 
driverInfo:String  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

此顯示內容使用的圖形庫驅動程式類型。指出要使用 DirectX 驅動程式或是使用 OpenGL 驅動程式來顯示。同時指出硬體顯示是否失敗。如果硬體顯示失敗,則 Flash Player 會為 Stage3D 使用軟體顯示,並且 driverInfo 會包含下列其中一個值:

  • 「Software Hw_disabled=userDisabled」:未選取 Adobe Flash Player「設定 UI」中的「啟用硬體加速」核取方塊。
  • 「Software Hw_disabled=oldDriver」:硬體圖形驅動程式發生已知問題。更新圖形驅動程式或許可以修正這個問題。
  • 「Software Hw_disabled=unavailable」:硬體圖形驅動程式發生已知問題,或者硬體圖形初始化失敗。
  • 「Software Hw_disabled=explicit」:內容已明確透過 requestContext3D 要求軟體顯示。
  • 「Software Hw_disabled=domainMemory」:內容使用 domainMemory,但後者需要授權才能與 Stage3D 硬體顯示搭配使用。請造訪 adobe.com/go/fpl_tw



實作
    public function get driverInfo():String

enableErrorChecking

屬性 
enableErrorChecking:Boolean

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

指定是否要將輸出器遇到的錯誤回報給應用程式。

enableErrorCheckingtrue 時,clear()drawTriangles() 方法是同步的,並且可以擲回錯誤。當 enableErrorCheckingfalse 時,預設值、clear()drawTriangles() 方法是非同步的,而且不會報告錯誤。啟用錯誤檢查功能會降低顯示效能。請只在除錯時啟用錯誤檢查功能。



實作
    public function get enableErrorChecking():Boolean
    public function set enableErrorChecking(value:Boolean):void

相關 API 元素

maxBackBufferHeight

屬性 
maxBackBufferHeight:int

語言版本: ActionScript 3.0
執行階段版本: Flash Player 15, AIR 15

指定背景緩衝區的最大高度。初始值是平台的系統限制。屬性可以設定為小於或等於但不大於系統限制的值。屬性可以設定為大於或等於但不小於最小限制的值。未設定背景緩衝區時,最小限制為常數值 32。設定背景緩衝區之後,最小限制會是最後一次成功呼叫 configureBackBuffer() 方法中的高度參數值。



實作
    public function get maxBackBufferHeight():int
    public function set maxBackBufferHeight(value:int):void

maxBackBufferWidth

屬性 
maxBackBufferWidth:int

語言版本: ActionScript 3.0
執行階段版本: Flash Player 15, AIR 15

指定背景緩衝區的最大寬度。初始值是平台的系統限制。屬性可以設定為小於或等於但不大於系統限制的值。屬性可以設定為大於或等於但不小於最小限制的值。未設定背景緩衝區時,最小限制為常數值 32。設定背景緩衝區之後,最小限制會是最後一次成功呼叫 configureBackBuffer() 方法中的寬度參數值。



實作
    public function get maxBackBufferWidth():int
    public function set maxBackBufferWidth(value:int):void

profile

屬性 
profile:String  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: Flash Player 12, AIR 4

這個 Context3D 物件所使用的功能支援描述檔。



實作
    public function get profile():String

相關 API 元素

supportsVideoTexture

屬性 
supportsVideoTexture:Boolean  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: AIR 17.0, Flash Player 18.0

指出 Context3D 是否支援視訊紋理。



實作
    public static function get supportsVideoTexture():Boolean

totalGPUMemory

屬性 
totalGPUMemory:Number  [唯讀]

語言版本: ActionScript 3.0
執行階段版本: Flash Player 21, AIR 21

傳回應用程式的 Stage3D 資料結構所配置的 GPU 記憶體總數。

每當建立 GPU 資源物件時,所使用的記憶體都會儲存在 Context3D 中。這個記憶體包括索引緩衝區、頂點緩衝區,以及透過這個 Context3D 所建立的紋理 (不包括視訊紋理) 和程式。

API totalGPUMemory 會傳回上述資源為使用者所耗用的記憶體總數。傳回的預設值為 0。傳回的 GPU 記憶體總數以位元組計算。資訊僅以行動裝置上的直接模式,以及桌上型電腦上的直接模式和 GPU 模式提供 (在桌上型電腦上,使用 <renderMode>gpu</renderMode> 將會回復至 <renderMode>direct</renderMode>)。

當 SWF 版本為 32 以上版本時,可以使用這個 API。



實作
    public function get totalGPUMemory():Number
方法詳細資訊

clear

()方法
public function clear(red:Number = 0.0, green:Number = 0.0, blue:Number = 0.0, alpha:Number = 1.0, depth:Number = 1.0, stencil:uint = 0, mask:uint = 0xffffffff):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

清除與此 Context3D 物件相關聯的顏色、深度和模板緩衝區,然後以指定的值填入那些緩衝區。

設定 mask 參數,以指定要清除的緩衝區。使用 Context3DClearMask 類別中定義的常數可設定 mask 參數。使用位元 OR 運算子「|」,可以將多個緩衝區加入遮色片 (或使用 Context3DClearMask.ALL)。當顯示到背景緩衝區時,configureBackBuffer() 方法必須在任何 clear() 呼叫之前呼叫。

注意:如果您指定允許的範圍以外的參數值,Numeric 參數值就會以無訊息方式緊縮為範圍零到一。同樣地,如果 stencil 大於 0xff,就設定為 0xff。

參數

red:Number (default = 0.0) — 要清除顏色緩衝區之顏色的紅色組件,範圍為零到一。
 
green:Number (default = 0.0) — 要清除顏色緩衝區之顏色的綠色組件,範圍為零到一。
 
blue:Number (default = 0.0) — 要清除顏色緩衝區之顏色的藍色組件,範圍為零到一。
 
alpha:Number (default = 1.0) — 要清除顏色緩衝區之顏色的 Alpha 組件,範圍為零到一。Alpha 組件非使用於混合。會直接將其寫入緩衝區 Alpha。
 
depth:Number (default = 1.0) — 要清除深度緩衝區的值,範圍為零到一。
 
stencil:uint (default = 0) — 要清除模板緩衝區的 8 位元值,範圍為 0x00 到 0xff。
 
mask:uint (default = 0xffffffff) — 指定要清除的緩衝區。


擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。

相關 API 元素

configureBackBuffer

()方法 
public function configureBackBuffer(width:int, height:int, antiAlias:int, enableDepthAndStencil:Boolean = true, wantsBestResolution:Boolean = false, wantsBestResolutionOnBrowserZoom:Boolean = false):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定顯示緩衝區的檢視區域尺寸和其它屬性。

顯示經過雙重緩衝。呼叫 present() 方法時,背景緩衝區會替換為可見的前景緩衝區。緩衝區的大小下限為 32x32 像素。背景緩衝區的大小上限會依裝置功能而有所限制,並且也可以由使用者透過屬性 maxBackBufferWidthmaxBackBufferHeight 加以設定。設定緩衝區作業很慢。請避免在一般顯示作業期間變更緩衝區大小或屬性。

參數

width:int — 緩衝區的寬度 (以像素為單位)。
 
height:int — 緩衝區的高度 (以像素為單位)。
 
antiAlias:int — 指定所要求消除鋸齒品質的整數值。使用消除鋸齒時,值會關聯至子樣本的數目。雖然相對效能衝擊取決於特定的顯示硬體,但是若要使用更多子樣本,還是必須執行更多計算。消除鋸齒類型以及是否執行消除鋸齒,完全取決於裝置和顯示模式。軟體顯示內容完全不支援消除鋸齒。
0不消除鋸齒
2最小消除鋸齒
4高品質消除鋸齒
16極佳品質消除鋸齒
 
enableDepthAndStencil:Boolean (default = true)false 指出不建立深度或模板緩衝區,true 將建立深度和模板緩衝區。若是以 SWF 版本 15 或更新版本編譯的 AIR 3.2 或更新版本應用程式,如果應用程式描述器檔案中的 renderMode 元素是 direct,則應用程式描述器檔案中的 depthAndStencil 元素必須具有與這個引數相同的值。根據預設,depthAndStencil 元素的值是 false
 
wantsBestResolution:Boolean (default = false)true 表示,如果裝置支援 HiDPI 螢幕,將會嘗試配置相較於寬度和高度參數所標示更大的背景緩衝區。由於這會增加更多像素,並且可能會改變著色器作業的結果,因此,預設是關閉的。請使用 Stage.contentsScaleFactor 判斷原生背景緩衝區放大了多少。
 
wantsBestResolutionOnBrowserZoom:Boolean (default = false)true 表示背景緩衝區的大小應依瀏覽器縮放係數增加的比例而增加。這個值的設定在多個瀏覽器縮放間具有持續性。參數的預設值是 false。設定 maxBackBufferWidthmaxBackBufferHeight 屬性可以限制背景緩衝區大小的增加。使用 backBufferWidthbackBufferHeight 即可判斷背景緩衝區的目前大小。


擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 輸入大小錯誤:width 或 height 參數小於允許的背景緩衝區大小下限,或大於允許的背景緩衝區大小上限。
 
Error — 3709:應用程式描述器中的 depthAndStencil 旗標必須符合傳遞至 Context3D 物件之 configureBackBuffer()enableDepthAndStencil Boolean。

createCubeTexture

()方法 
public function createCubeTexture(size:int, format:String, optimizeForRenderToTexture:Boolean, streamingLevels:int = 0):flash.display3D.textures:CubeTexture

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

建立 CubeTexture 物件。

使用 CubeTexture 物件可以將立方體紋理點陣圖上傳到顯示內容,也可以在顯示期間參考立方體紋理。一個立方體紋理包含六個相等大小的矩形紋理,這些紋理在立方體拓撲中排列,並可用來說明環境對應。

您無法搭配 CubeTexture 建構函式建立 CubeTexture 物件;請改用這個方法。建立 CubeTexture 物件之後,請使用 CubeTexture uploadFromBitmapData()uploadFromByteArray()uploadCompressedTextureFromByteArray() 方法上傳紋理點陣圖資料。

參數

size:int — 以紋理為單位表示的紋理邊緣長度。
 
format:String — Context3DTextureFormat 列舉清單的紋理格式。

紋理壓縮可讓您以壓縮格式直接將紋理影像儲存在 GPU 上,以便節省 GPU 記憶體和記憶體頻寬。一般來說,壓縮的紋理是以使用 Texture.uploadCompressedTextureFromByteArray 方法的壓縮格式離線壓縮後上傳到 GPU。桌面平台上的 Flash Player 11.4 和 AIR 3.4 已為執行階段紋理壓縮新增支援,在特定情況下,例如顯示向量圖像中的動態紋理時,此壓縮會很有用。請注意,行動平台目前並未提供這項功能,因此,將改為擲回 ArgumentError (紋理格式不相符)。若要使用執行階段紋理壓縮,請執行下列步驟:1. 呼叫 Context3D.createCubeTexture() 方法、以格式參數傳遞 flash.display3D.Context3DTextureFormat.COMPRESSED 或 flash.display3D.Context3DTextureFormat.COMPRESSED_ALPHA,藉此建立紋理物件。2. 使用 createCubeTexture() 所傳回的 flash.display3D.textures.Texture 實體,呼叫 flash.display3D.textures.CubeTexture.uploadFromBitmapData() 或 flash.display3D.textures.CubeTexture.uploadFromByteArray(),以一個步驟上傳並壓縮紋理。

 
optimizeForRenderToTexture:Boolean — 如果紋理可能當做顯示目標使用,則設為 true
 
streamingLevels:int (default = 0) — 必須在影像顯示之前載入的 MIP 對應層級。「紋理串流」能優先載入並顯示最小的 MIP 層級,然後以漸進方式一邊載入紋理一邊顯示品質較高的影像。使用者可以一邊在應用程式中檢視品質較低的影像,一邊載入品質較高的影像。

根據預設,streamingLevels 為 0,這表示 MIP 對應中最高品質的影像必須在影像顯示之前載入。這個參數是 Flash Player 11.3 及 AIR 3.3 中新增的參數。使用預設值會維持 Flash Player 及 AIR 先前版本的行為。

streamingLevels 設定成介於 1 和 MIP 對應中影像數目之間的值,則可啟用紋理串流。舉例來說,您的 MIP 對應包含具有最高品質 64x64 像素的主要影像。MIP 對應中較低品質的影像為 32x32、16x16、8x8、4x4、2x2 和 1x1 像素,總共 7 個影像或 7 個層級。層級 0 是最高品質的影像。這個屬性的最大值為 log2(min(width,height))。因此,以 64x64 像素的主要影像來說,streamingLevels 的最大值為 7。將這個屬性設定為 3,即可在 8x8 像素影像載入後顯示影像。

注意:將這個屬性設定為大於 0 的值可能會影響記憶體用量和效能。

傳回值
flash.display3D.textures:CubeTexture

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多 Texture 物件,或是超過配置給紋理的記憶體數量。
 
ArgumentError — 未實作深度紋理:嘗試建立深度紋理。
 
ArgumentError — 紋理大小為零:size 參數不大於零。
 
ArgumentError — 紋理非 2 的倍數:size 參數不是 2 的倍數。
 
ArgumentError — 紋理太大:size 參數大於 1024。
 
Error — 紋理建立失敗:無法利用顯示內容建立 CubeTexture 物件 (但沒有其原因的相關資訊)。
 
ArgumentError — 無效的串流層級:streamingLevels 大於或等於 log2(size)。

相關 API 元素

createIndexBuffer

()方法 
public function createIndexBuffer(numIndices:int, bufferUsage:String = "staticDraw"):IndexBuffer3D

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

建立 IndexBuffer3D 物件。

使用 IndexBuffer3D 物件可以將一組三角形索引上傳到顯示內容,並且參考該索引進行顯示。索引緩衝區中的每個索引會參考頂點緩衝區中的對應頂點。透過每組三個索引,可識別出三角形。將 IndexBuffer3D 物件傳遞到 drawTriangles() 方法,即可顯示索引緩衝區中定義的一或多個三角形。

您無法搭配 IndexBuffer3D 類別建構函式建立 IndexBuffer3D 物件;請改用這個方法。建立 IndexBuffer3D 物件之後,請使用 IndexBuffer3D uploadFromVector()uploadFromByteArray() 方法上傳索引。

參數

numIndices:int — 要在緩衝區中儲存的頂點數目。
 
bufferUsage:String (default = "staticDraw") — 預期的緩衝區使用量。使用 Context3DBufferUsage 中定義的其中一個常數。當您設定正確時,硬體驅動程式可以達到適當的最佳化。這個參數僅在 Flash 12/AIR 4 之後的版本中提供。

傳回值
IndexBuffer3D

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多索引緩衝區,或是超過配置給索引緩衝區的記憶體數量。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。
 
ArgumentError — 緩衝區太大:numIndices 大於或等於 0xf0000。

相關 API 元素

createProgram

()方法 
public function createProgram():Program3D

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

建立 Program3D 物件。

使用 Program3D 物件可以將著色器程式上傳到顯示內容,也可以在顯示期間參考上傳的程式。Program3D 物件會儲存兩個程式,分別為頂點程式和片段程式 (又稱為像素程式)。將以二進位著色器組合語言編寫這些程式。

您無法搭配 Program3D 建構函式建立 Program3D 物件;請改用這個方法。建立 Program3D 物件之後,請使用 Program3D upload() 方法上傳程式。

傳回值
Program3D

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 程式數目超過 4096 個,或者記憶體總數超過 16MB (使用 dispose 可釋放 Program3D 資源)。

相關 API 元素


範例  ( 如何使用本範例 )

此範例說明如何建立、上傳及啟用顯示內容的一組頂點與像素程式。請注意,renderContext 物件是 Context3D 類別的實體。範例中的程式是使用 Adobe Graphics Assembly Language (AGAL) 所撰寫。
//A simple vertex program in AGAL
const VERTEX_SHADER:String =
    "m44 op, va0, vc0 \n" +    
    "mov v0, va1"; 

//A simple fragment (or pixel) program in AGAL        
const FRAGMENT_SHADER:String = "mov oc, v0";  

var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
var programPair:Program3D;

//Compile shaders
vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            

//Upload programs to render context
programPair = renderContext.createProgram();
programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
renderContext.setProgram( programPair );
            

createRectangleTexture

()方法 
public function createRectangleTexture(width:int, height:int, format:String, optimizeForRenderToTexture:Boolean):flash.display3D.textures:RectangleTexture

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11.8, AIR 3.8

建立 Rectangle Texture 物件。

使用 RectangleTexture 物件可以將紋理點陣圖上傳到顯示內容,也可以在顯示期間參考紋理。

您無法搭配 RectangleTexture 建構函式建立 RectangleTexture 物件;請改用這個方法。建立 RectangleTexture 物件之後,請使用 Texture uploadFromBitmapData()uploadFromByteArray() 方法上傳紋理點陣圖。

請注意,會以符合 Flash BitmapData 格式的封裝 BGRA 格式來儲存 32 位元整數紋理。浮點數紋理使用慣用的 RGBA 格式。

矩形紋理不同於一般 2D 紋理,因為它的寬度和高度不一定要是 2 的次方。此外,矩形紋理不包含 MIP 對應。在顯示紋理時,矩形紋理是最有用的。如果矩形紋理與使用 MIP 對應篩選或重複換行的取樣程式搭配使用,drawTriangles 呼叫將會失敗。此外,矩形紋理也不允許使用串流。矩形紋理支援的紋理格式為 BGRA、BGR_PACKED、BGRA_PACKED。矩形紋理不支援壓縮的紋理格式。

參數

width:int — 以紋理為單位表示的紋理寬度。
 
height:int — 以紋理為單位表示的紋理高度。
 
format:String — Context3DTextureFormat 列舉清單的紋理格式。
 
optimizeForRenderToTexture:Boolean — 如果紋理可能當做顯示目標使用,則設為 true

傳回值
flash.display3D.textures:RectangleTexture

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多 Texture 物件,或是超過配置給紋理的記憶體數量。
 
ArgumentError — 紋理大小為零:widthheight 參數兩者均不大於零。
 
ArgumentError — 紋理太大:widthheight 參數大於 2048。
 
Error — 紋理建立失敗:無法利用顯示內容建立 Texture 物件 (但沒有其原因的相關資訊)。
 
Error — 需要基線描述檔或更高版本:矩形紋理是以基線限制描述檔建立的。

相關 API 元素

createTexture

()方法 
public function createTexture(width:int, height:int, format:String, optimizeForRenderToTexture:Boolean, streamingLevels:int = 0):flash.display3D.textures:Texture

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

建立 Texture 物件。

使用 Texture 物件可以將紋理點陣圖上傳到顯示內容,也可以在顯示期間參考紋理。

您無法搭配 Texture 建構函式建立 Texture 物件;請改用這個方法。建立 Texture 物件之後,請使用 Texture uploadFromBitmapData()uploadFromByteArray()uploadCompressedTextureFromByteArray() 方法上傳紋理點陣圖。

請注意,會以符合 Flash BitmapData 格式的封裝 BGRA 格式來儲存 32 位元整數紋理。浮點數紋理使用慣用的 RGBA 格式。

參數

width:int — 以紋理為單位表示的紋理寬度。
 
height:int — 以紋理為單位表示的紋理高度。
 
format:String — Context3DTextureFormat 列舉清單的紋理格式。

紋理壓縮可讓您以壓縮格式直接將紋理影像儲存在 GPU 上,以便節省 GPU 記憶體和記憶體頻寬。一般來說,壓縮的紋理是以使用 Texture.uploadCompressedTextureFromByteArray 方法的壓縮格式離線壓縮後上傳到 GPU。桌面平台上的 Flash Player 11.4 和 AIR 3.4 已為執行階段紋理壓縮新增支援,在特定情況下,例如顯示向量圖像中的動態紋理時,此壓縮會很有用。請注意,行動平台目前並未提供這項功能,因此,將改為擲回 ArgumentError (紋理格式不相符)。若要使用執行階段紋理壓縮,請執行下列步驟:1. 呼叫 Context3D.createTexture() 方法、以格式參數傳遞 flash.display3D.Context3DTextureFormat.COMPRESSED 或 flash.display3D.Context3DTextureFormat.COMPRESSED_ALPHA,藉此建立紋理物件。2. 使用 createTexture() 所傳回的 flash.display3D.textures.Texture 實體,呼叫 flash.display3D.textures.Texture.uploadFromBitmapData() 或 flash.display3D.textures.Texture.uploadFromByteArray(),以一個步驟上傳並壓縮紋理。

 
optimizeForRenderToTexture:Boolean — 如果紋理可能當做顯示目標使用,則設為 true
 
streamingLevels:int (default = 0) — 必須在影像顯示之前載入的 MIP 對應層級。「紋理串流」能優先載入並顯示最小的 MIP 層級,然後以漸進方式一邊載入紋理一邊顯示品質較高的影像。使用者可以一邊在應用程式中檢視品質較低的影像,一邊載入品質較高的影像。

根據預設,streamingLevels 為 0,這表示 MIP 對應中最高品質的影像必須在影像顯示之前載入。這個參數是 Flash Player 11.3 及 AIR 3.3 中新增的參數。使用預設值會維持 Flash Player 及 AIR 先前版本的行為。

streamingLevels 設定成介於 1 和 MIP 對應中影像數目之間的值,則可啟用紋理串流。舉例來說,您的 MIP 對應包含具有最高品質 64x64 像素的主要影像。MIP 對應中較低品質的影像為 32x32、16x16、8x8、4x4、2x2 和 1x1 像素,總共 7 個影像或 7 個層級。層級 0 是最高品質的影像。這個屬性的最大值為 log2(min(width,height))。因此,以 64x64 像素的主要影像來說,streamingLevels 的最大值為 7。將這個屬性設定為 3,即可在 8x8 像素影像載入後顯示影像。

注意:將這個屬性設定為大於 0 的值可能會影響記憶體用量和效能。

傳回值
flash.display3D.textures:Texture

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多 Texture 物件,或是超過配置給紋理的記憶體數量。
 
ArgumentError — 未實作深度紋理:嘗試建立深度紋理。
 
ArgumentError — 紋理大小為零:widthheight 參數兩者均不大於零。
 
ArgumentError — 紋理非 2 的倍數:widthheight 參數不是 2 的倍數。
 
ArgumentError — 紋理太大:widthheight 參數大於基線的 2048 和基線限制描述檔,或者 widthheight 參數大於延伸以上的描述檔基線的 4096。
 
Error — 紋理建立失敗:無法利用顯示內容建立 Texture 物件 (但沒有其原因的相關資訊)。
 
ArgumentError — 無效的串流層級:streamingLevels 大於或等於 log2(min(width,height))。

相關 API 元素

createVertexBuffer

()方法 
public function createVertexBuffer(numVertices:int, data32PerVertex:int, bufferUsage:String = "staticDraw"):VertexBuffer3D

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

建立 VertexBuffer3D 物件。

使用 VertexBuffer3D 物件可以將一組頂點資料上傳到顯示內容。頂點緩衝區包含要在場景幾何中顯示每個點時所需的資料。與每個頂點關聯的資料屬性通常包含位置、顏色和紋理座標,並且可當做頂點著色器程式的輸入。使用 setVertexBufferAt() 方法可以識別對應至其中一個頂點程式輸入的資料值。每個頂點最多可以指定 64 個 32 位元值。

您無法搭配 VertexBuffer3D 建構函式建立 VertexBuffer3D 物件;請改用這個方法。建立 VertexBuffer3D 物件之後,請使用 VertexBuffer3D uploadFromVector()uploadFromByteArray() 方法上傳頂點資料。

參數

numVertices:int — 要在緩衝區中儲存的頂點數目。單一緩衝區中的頂點數上限為 65535。
 
data32PerVertex:int — 每一個頂點相關的 32 位元 (4 位元組) 資料值數目。每個頂點的 32 位元資料元素數目為 64 (或 256 位元組)。請注意,一個頂點著色器程式任何時間都只能存取 8 個屬性暫存器。使用 SetVertextBufferAt() 可選取頂點緩衝區內的屬性。
 
bufferUsage:String (default = "staticDraw") — 預期的緩衝區使用量。使用 Context3DBufferUsage 中定義的其中一個常數。當您設定正確時,硬體驅動程式可以達到適當的最佳化。這個參數僅在 Flash 12/AIR 4 之後的版本中提供

傳回值
VertexBuffer3D

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多頂點緩衝區,或是超過配置給頂點緩衝區的記憶體數量。
 
ArgumentError — 緩衝區太大:numVertices 大於 0x10000 或 data32PerVertex 大於 64。
 
ArgumentError — 緩衝區大小為零:numVertices 為零,或是 data32PerVertex 為零。
 
ArgumentError — 緩衝區建立失敗:無法利用顯示內容建立 VertexBuffer3D 物件 (但沒有其原因的其他相關資訊)。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。

相關 API 元素


範例  ( 如何使用本範例 )

下列範例說明如何建立和載入頂點資料緩衝區。在此範例中,緩衝區的每個頂點都包含兩種資料類型:位置 (例如 x、y、z) 與顏色 (例如 RGB 組件)。建立頂點緩衝區之後,此範例會呼叫 setVertexBufferAt() 方法,指定將前三個資料點傳遞給頂點程式,做為 va0 的 3 個浮點值,並傳遞次三個資料點做為 va1。頂點程式 (也稱為頂點屬性暫存器) 最多可有 8 個輸入,定義如下。
const dataPerVertex:int = 6;
var vertexData:Vector.<Number> = Vector.<Number>(
    [
      // x, y, z    r, g, b format
         0, 0, 0,   1, 1, 1,
        -1, 1, 0,   0, 0,.5,
         1, 1, 0,   0, 0, 1,
         1,-1, 0,  .5, 0, 0,
        -1,-1, 0,   1, 0, 0
    ]
);
var vertexes:VertexBuffer3D = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
//Identify vertex data inputs for vertex program
renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //Defines shader input va0 as the position data
renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //Defines shader input va1 as the color data

    createVertexBufferForInstances

()方法 
public function createVertexBufferForInstances(numVertices:int, data32PerVertex:int, instancesPerElement:int, bufferUsage:String = "staticDraw"):VertexBuffer3D

語言版本: ActionScript 3.0
執行階段版本: AIR 20.0

建立適用於實體資料的 VertexBuffer3D 物件。

使用 VertexBuffer3D 物件可以將一組實體資料上傳到顯示內容。頂點緩衝區包含要在場景幾何中顯示每個實體時所需的資料。含有實體資料的頂點緩衝區提供實體的所有頂點都適用的特質,並且可當做頂點著色器程式的輸入。使用 setVertexBufferAt() 方法可以識別對應至其中一個頂點程式輸入的資料值。每個頂點緩衝區的元素最多可以指定 64 個 32 位元值。

您無法搭配 VertexBuffer3D 建構函式建立 VertexBuffer3D 物件;請改用這個方法。建立 VertexBuffer3D 物件之後,請使用 VertexBuffer3D uploadFromVector()uploadFromByteArray() 方法上傳頂點資料。

參數

numVertices:int — 要在緩衝區中儲存的元素數目。單一緩衝區中的元素數上限為 65535。
 
data32PerVertex:int — 每一個元素相關的 32 位元 (4 位元組) 資料值數目。每個頂點的 32 位元資料元素數目為 64 (或 256 位元組)。
 
instancesPerElement:int — 將使用頂點緩衝區其中一個元素的實體數目。
 
bufferUsage:String (default = "staticDraw") — 預期的緩衝區使用量。使用 Context3DBufferUsage 中定義的其中一個常數。當您設定正確時,硬體驅動程式可以達到適當的最佳化。這個參數僅在 Flash 12/AIR 4 之後的版本中提供

傳回值
VertexBuffer3D

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多頂點緩衝區,或是超過配置給頂點緩衝區的記憶體數量。
 
ArgumentError — 緩衝區太大:numVertices 大於 0x10000 或 data32PerVertex 大於 64。
 
ArgumentError — 緩衝區大小為零:numVertices 為零,或是 data32PerVertex 為零。
 
ArgumentError — 緩衝區建立失敗:無法利用顯示內容建立 VertexBuffer3D 物件 (但沒有其原因的其他相關資訊)。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。
 
Error — 需要標準延伸描述檔或以上版本:當要求的描述檔版本低於標準延伸描述檔時,呼叫這個方法。
 
Error — 無效的 Instances Per Element:instancesPerElement 未大於零。

相關 API 元素

createVideoTexture

()方法 
public function createVideoTexture():flash.display3D.textures:VideoTexture

語言版本: ActionScript 3.0
執行階段版本: AIR 17.0, Flash Player 18.0

建立 VideoTexture 物件。

使用 VideoTexture 物件能以紋理形式從 NetStream 或 Camera 物件取得視訊影格,並且將視訊影格上傳到顯示內容。

無法使用 VideoTexture 建構函式建立 VideoTexture 物件;請改用這個方法。建立 VideoTexture 物件之後,請附加 NetStream 物件或 Camera 物件,透過 VideoTexture attachNetStream()attachCamera() 方法取得視訊影格。

請注意,如果系統不支援這個功能,這個方法就會傳回 null。

VideoTexture 未包含 MIP 對應。如果 VideoTexture 與使用 MIP 對應篩選或重複換行的取樣程式搭配使用,drawTriangles 呼叫將會失敗。VideoTexture 會被著色器視為 BGRA 紋理。如果以軟體顯示模式要求 Context3D,則嘗試初始化 VideoTexture 物件將會失敗。

每個 Context3D 實體最多有 4 個 VideoTexture 物件可以使用。在行動裝置版本上,由於平台限制,支援的 VideoTexture 物件實際數目可能少於 4 個。

傳回值
flash.display3D.textures:VideoTexture

擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 超過資源限制:建立太多 Texture 物件,或是超過配置給紋理的記憶體數量。
 
Error — 紋理建立失敗:無法利用顯示內容建立 Texture 物件 (但沒有其原因的相關資訊)。

dispose

()方法 
public function dispose(recreate:Boolean = true):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

釋放與此 Context3D 關聯的所有資源和內部儲存空間。

透過此 Context3D 建立的所有索引緩衝區、頂點緩衝區、紋理和程式的處理方式,與個別在其上呼叫 dispose() 予以處理是相同的。此外,Context3D 本身將釋放所有暫存緩衝區和背景緩衝區予以處理。如果您呼叫 dispose() 之後呼叫 configureBackBuffer()、clear()、drawTriangles()、createCubeTexture()、createTexture()、createProgram()、createIndexBuffer()、createVertexBuffer() 或 drawToBitmapData(),則執行階段會擲出例外。

警告:當關聯的 Stage3D 物件上仍有一個所設定之 Events.CONTEXT3D_CREATE 的事件偵聽程式時,若呼叫 Context3D 上的 dispose(),則 dispose() 呼叫會模擬裝置損失。它會在 Stage3D 上建立新的 Context3D,並再次發出 Events.CONTEXT3D_CREATE 事件。如果這不是所需的行為,請先移除 Stage3D 物件中的事件偵聽程式,然後再呼叫 dispose(),或者將 recreate 參數設定為 false。

參數

recreate:Boolean (default = true)

相關 API 元素

    drawToBitmapData

()方法 
public function drawToBitmapData(destination:BitmapData, srcRect:Rectangle = null, destPoint:Point = null):void

語言版本: ActionScript 3.0
執行階段版本: AIR 3

繪製目前顯示緩衝區的點陣圖。

背景顯示緩衝區的目前內容會複製到 BitmapData 物件。這項作業可能執行得很慢,可能需要花上一些時間。請小心使用。請注意,這個函數不會複製前景顯示緩衝區 (舞台上顯示的緩衝區),而是要繪製到的緩衝區。若要在顯示的影像出現在舞台時加以擷取,請在呼叫 present() 之前,先立即呼叫 drawToBitmapData()

從 AIR 25 開始,API drawToBitmapData() 中引進兩個新參數。這個 API 現在接受三個參數。第一個是現有參數 destination:BitmapData。第二個參數是 srcRect:Rectangle,這是 stage3D 上的目標矩形。第三個參數是 destPoint:Point,這是目的地點陣圖上的座標。參數 srcRect 和 destPoint 為選用,分別預設為 (0,0,bitmapWidth,bitmapHeight) 和 (0,0)。

繪製影像時,影像不會縮放為點陣圖的大小。相反地,內容將符合目的地點陣圖的大小。

Flash BitmapData 物件會儲存已經乘以 Alpha 組件的顏色。例如,如果像素的「純」RGB 顏色組件為 (0x0A, 0x12, 0xBB),而 Alpha 組件為 0x7F (.5),則像素會以 RGBA 值儲存在 BitmapData 物件中:(0x05, 0x09, 0x5D, 0x7F)。您可以設定混合係數,使顯示至緩衝區的顏色乘以 Alpha 或是在片段著色器中執行此作業。顯示內容不會驗證顏色是否以預先相乘的格式來儲存。

參數

destination:BitmapData
 
srcRect:Rectangle (default = null)
 
destPoint:Point (default = null)


擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。
 
Error — 3802:參數 destPoint:PointsrcRect:Rectangle 位於點陣圖/stage3D 座標界限之外,或者非數值 (NaN) 值傳遞做為輸入。

範例  ( 如何使用本範例 )

下列範例會在一般顯示緩衝區與 BitmapData 物件顯示兩個三角形。BitmapData 物件是使用新增至一般顯示清單的 Bitmap 物件來顯示。陰影濾鏡適用於點陣圖顯示。
package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Bitmap;
    import flash.display.BitmapData;
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    import flash.filters.DropShadowFilter;
    
    public class Context3D_drawToBitmapData extends Sprite
    {
        public const viewWidth:Number = 320;
        public const viewHeight:Number = 200;
        
        private var bitmap:Bitmap;
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        public function Context3D_drawToBitmapData()
        {
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 0;
            stage3D.y = 0;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );            
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [ 0, 1, 2, 0, 3, 4 ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  // x, y, z    r, g, b format
                     0, 0, 0,   1, 1, 1,
                    -1, 1, 0,   0, 0,.5,
                     1, 1, 0,   0, 0, 1,
                     1,-1, 0,  .5, 0, 0,
                    -1,-1, 0,   1, 0, 0
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            //Clear required before first drawTriangles() call
            renderContext.clear( .3,.3,.3 );
            
            
            //Draw the 2 triangles
            renderContext.drawTriangles( indexList, 0, 2 );
            
            var renderedBitmapData:BitmapData = new BitmapData( viewWidth, viewHeight, true );
            renderContext.drawToBitmapData( renderedBitmapData );
            
            renderContext.present();
            
            //Add to stage
            bitmap = new Bitmap( renderedBitmapData );
            this.addChild( bitmap );
            bitmap.x = 55;
            bitmap.y = 25;
            bitmap.filters = [new DropShadowFilter( 8, 235, .4 )];
        }
    }
}

drawTriangles

()方法 
public function drawTriangles(indexBuffer:IndexBuffer3D, firstIndex:int = 0, numTriangles:int = -1):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

請使用此 Context3D 物件的目前緩衝區和狀態來顯示指定的三角形。

就每個三角形而言,三角形頂點會經過頂點著色器程式的處理,而三角形表面則經由像素著色器程式處理。來自像素程式之輸出色彩的每一像素會根據視模板作業、深度測試、來源和目的地 Alpha 以及目前混合模式,繪製到顯示目標。顯示目的地可以是主要顯示緩衝區或紋理。

如果啟用剔除功能 (透過使用 setCulling() 方法),則會在執行像素程式之前捨棄場景中的三角形。如果啟用模板和深度測試,則會捨棄像素程式中的輸出像素,而不會更新顯示目的地。此外,像素程式可以決定不要輸出像素的顏色。

在您呼叫 present() 方法之前,顯示的三角形不會出現在檢視區域中。在每個 present() 呼叫之後,必須在第一個 drawTriangles() 呼叫之前呼叫 clear() 方法,否則顯示會失敗。

enableErrorCheckingfalse 時,此函數會立即傳回而不等候結果,並且只有在此 COntext3D 實體已加以處理或是有太多繪製呼叫時,才會擲回例外。如果顯示內容狀態無效,則顯示會無訊息失敗。當 enableErrorChecking 屬性為 true 時,此函數會在繪製三角形之後傳回,並針對任何繪製錯誤或無效的內容狀態擲回例外。

參數

indexBuffer:IndexBuffer3D — 一組頂點索引,這些索引參考要顯示的頂點。
 
firstIndex:int (default = 0) — 選取顯示的第一個頂點索引的索引。預設為 0。
 
numTriangles:int (default = -1) — 要顯示的三角形數目。每一個三角形耗用三個索引。傳遞 -1 可在索引緩衝區中繪製所有三角形。預設為 -1。


擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 如果在 present() 的呼叫之間呼叫此方法太多次。呼叫的最大次數為 32,768 次。

下列錯誤只會在 enableErrorChecking 屬性為 true 時擲回:

 
Error — 繪製前必須先清除:自最後一次 present() 呼叫以來不曾清除過緩衝區。
 
Error — 未設定有效的 Program3D 物件。
 
Error — 未設定有效的索引緩衝區:未設定 IndexBuffer3D 物件。
 
Error — 參數的例行性檢查失敗:要繪製的三角形數目或 firstIndex 超過允許的值。
 
RangeError — 這個緩衝區中沒有足夠的索引:緩衝區中沒有足夠的索引,無法定義要繪製的三角形數目。
 
Error — 樣本繫結紋理同時繫結至顯示:顯示目標是紋理,而該紋理已指定給目前片段程式的紋理輸入。
 
Error — 樣本繫結無效的紋理:指定無效的紋理做為目前片段程式的輸入。
 
Error — 取樣程式格式不符合紋理格式:指定做為目前片段程式輸入的紋理,具有與為取樣程式暫存器所指定不同的格式。例如,將 2D 紋理指定給立方體紋理取樣程式。
 
Error — 樣本繫結未定義的紋理:目前片段程式存取尚未設定 (使用 setTextureAt()) 的紋理暫存器。
 
Error — 相同紋理需要相同取樣程式參數:如果紋理用於一個以上的取樣程式暫存器,則所有取樣程式都必須具有相同的設定。例如,您無法將一個取樣程式設定為 clamp,另一個設定為圍繞。
 
Error — 紋理已繫結但未使用:紋理已設定為著色器輸入,但未使用過。
 
Error — 串流不在使用中:頂點緩衝區已指定至頂點屬性輸入,但頂點程式不會參考對應的暫存器。
 
Error — 串流無效:指定給頂點程式輸入的 VertexBuffer3D 物件不是有效的物件。
 
RangeError — 串流沒有足夠的頂點:提供資料以供繪製指定之三角形的頂點緩衝區沒有足夠的資料。
 
RangeError — 串流頂點偏移值超出範圍:setVertexBufferAt() 呼叫中指定的偏移值是負數或超過緩衝區結尾。
 
Error — 串流已讀取但未設定:目前頂點程式所使用的頂點屬性未設定 (使用 setVertexBufferAt())。

相關 API 元素


範例  ( 如何使用本範例 )

下列類別會在舞台的 Stage3D 檢視區域繪製兩個三角形。這兩個三角形共用一個頂點,其位於原點 (0,0,0)。

三角形是使用頂點緩衝區和索引緩衝區來定義。頂點緩衝區包含每個三角形頂點的位置和顏色資訊。索引緩衝區包含頂點緩衝區的索引。三個索引定義一個三角形。例如,由頂點緩衝區中前三個點所組成的三角形,在索引緩衝區中列示為 0,1,2。

在這個簡單範例中,不會執行 3D 變形。只有標準化檢視區域 (2x2x1 單位體積) 內的物件才會顯示,且所定義的三角形座標必須位在此區域內。不過,在顯示典型的 3D 場景時,請使用透視或正視投影,將要顯示的物件從「世界」座標系統投影至此檢視區域。

package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    
    public class Context3D_drawTriangles extends Sprite
    {
        public const viewWidth:Number = 320;
        public const viewHeight:Number = 200;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        public function Context3D_drawTriangles()
        {
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );            
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [ 0, 1, 2, 0, 3, 4 ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  // x, y, z    r, g, b format
                     0, 0, 0,   1, 1, 1,
                    -1, 1, 0,   0, 0,.5,
                     1, 1, 0,   0, 0, 1,
                     1,-1, 0,  .5, 0, 0,
                    -1,-1, 0,   1, 0, 0
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            //Clear required before first drawTriangles() call
            renderContext.clear( .3,.3,.3 );
            
            //Draw the 2 triangles
            renderContext.drawTriangles( indexList, 0, 2 );
            
            //Show the frame
            renderContext.present();
        }
    }
}

    drawTrianglesInstanced

()方法 
public function drawTrianglesInstanced(indexBuffer:IndexBuffer3D, numInstances:int, firstIndex:int = 0, numTriangles:int = -1):void

語言版本: ActionScript 3.0
執行階段版本: AIR 20.0

請使用此 Context3D 物件的目前緩衝區和狀態來顯示指定的實體化三角形。

就每一個實體的每個三角形而言,三角形頂點會經過頂點著色器程式的處理,而三角形表面則經由像素著色器程式處理。來自像素程式之輸出色彩的每一像素會根據視模板作業、深度測試、來源和目的地 Alpha 以及目前混合模式,繪製到顯示目標。顯示目的地可以是主要顯示緩衝區或紋理。

如果啟用剔除功能 (透過使用 setCulling() 方法),則會在執行像素程式之前捨棄場景中的三角形。如果啟用模板和深度測試,則會捨棄像素程式中的輸出像素,而不會更新顯示目的地。此外,像素程式可以決定不要輸出像素的顏色。

在您呼叫 present() 方法之前,顯示的實體化三角形不會出現在檢視區域中。在每個 present() 呼叫之後,必須在第一個 drawTrianglesInstanced() 呼叫之前呼叫 clear() 方法,否則顯示會失敗。

enableErrorCheckingfalse 時,此函數會立即傳回而不等候結果,並且只有在此 COntext3D 實體已加以處理或是有太多繪製呼叫時,才會擲回例外。如果顯示內容狀態無效,則顯示會無訊息失敗。當 enableErrorChecking 屬性為 true 時,此函數會在繪製三角形之後傳回,並針對任何繪製錯誤或無效的內容狀態擲回例外。

如果實體化緩衝區以 SetVertexAt() 不當地排序,這個方法可能會擲回例外。以 Direct 3D 9 為例,所要繪製的實體的已編製索引幾何資料和數目,必須永遠以 SetStreamSourceFreq() API 在串流零中設定。

這表示,以 SetVertexBufferAt() 作為頂點著色器程式的輸入時,使用 CreateVertexBufferForInstance() 建立的頂點緩衝區不應設為最小索引號碼。使用 CreateVertexBuffer() 所產生之頂點緩衝區的索引號碼,必須設為小於 CreateVertexBufferForInstance() 的索引號碼。一般來說,幾何資料必須放在具有 SetVertexBufferAt() 的每個實體資料前。

參數

indexBuffer:IndexBuffer3D — 一組頂點索引,這些索引參考要顯示的頂點。
 
numInstances:int — 要顯示的實體數目。
 
firstIndex:int (default = 0) — 選取顯示的第一個頂點索引的索引。預設為 0。
 
numTriangles:int (default = -1) — 要顯示的三角形數目。每一個三角形耗用三個索引。傳遞 -1 可在索引緩衝區中繪製所有三角形。預設為 -1。


擲回值
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。
 
Error — 如果在 present() 的呼叫之間呼叫此方法太多次。呼叫的最大次數為 32,768 次。
 
Error — 需要標準延伸描述檔或以上版本:當要求的描述檔版本低於標準延伸描述檔時,呼叫這個方法。
 
Error — 以負數 numInstance 呼叫了這個方法。

下列錯誤只會在 enableErrorChecking 屬性為 true 時擲回:

 
Error — 繪製前必須先清除:自最後一次 present() 呼叫以來不曾清除過緩衝區。
 
Error — 未設定有效的 Program3D 物件。
 
Error — 未設定有效的索引緩衝區:未設定 IndexBuffer3D 物件。
 
Error — 參數的例行性檢查失敗:要繪製的三角形數目或 firstIndex 超過允許的值。
 
RangeError — 這個緩衝區中沒有足夠的索引:緩衝區中沒有足夠的索引,無法定義要繪製的三角形數目。
 
Error — 樣本繫結紋理同時繫結至顯示:顯示目標是紋理,而該紋理已指定給目前片段程式的紋理輸入。
 
Error — 樣本繫結無效的紋理:指定無效的紋理做為目前片段程式的輸入。
 
Error — 取樣程式格式不符合紋理格式:指定做為目前片段程式輸入的紋理,具有與為取樣程式暫存器所指定不同的格式。例如,將 2D 紋理指定給立方體紋理取樣程式。
 
Error — 樣本繫結未定義的紋理:目前片段程式存取尚未設定 (使用 setTextureAt()) 的紋理暫存器。
 
Error — 相同紋理需要相同取樣程式參數:如果紋理用於一個以上的取樣程式暫存器,則所有取樣程式都必須具有相同的設定。例如,您無法將一個取樣程式設定為 clamp,另一個設定為圍繞。
 
Error — 紋理已繫結但未使用:紋理已設定為著色器輸入,但未使用過。
 
Error — 串流不在使用中:頂點緩衝區已指定至頂點屬性輸入,但頂點程式不會參考對應的暫存器。
 
Error — 串流無效:指定給頂點程式輸入的 VertexBuffer3D 物件不是有效的物件。
 
RangeError — 串流沒有足夠的頂點:提供資料以供繪製指定之三角形的頂點緩衝區沒有足夠的資料。
 
RangeError — 串流頂點偏移值超出範圍:setVertexBufferAt() 呼叫中指定的偏移值是負數或超過緩衝區結尾。
 
Error — 串流已讀取但未設定:目前頂點程式所使用的頂點屬性未設定 (使用 setVertexBufferAt())。
 
Error — 頂點緩衝區串流沒有足夠的元素可供實體使用:頂點緩衝區串流沒有足夠的元素可供一些實體使用。
 
Error — 實體的頂點緩衝區串流不當設定為最小索引屬性暫存器:使用 CreateVertexBuffer() 所產生之頂點緩衝區的索引號碼,大於使用 CreateVertexBufferForInstance() 所產生之頂點緩衝區的索引號碼。

相關 API 元素


範例  ( 如何使用本範例 )

下列類別會使用以單一繪製呼叫 (而非多個繪製呼叫) 進行實體化繪製的功能,繪製三個三角形。
package
{
    import com.adobe.utils.v3.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DTriangleFace;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    import flash.geom.Matrix3D;
    import flash.utils.ByteArray;
    
    public class Context3D_HelloInstancedDrawing extends Sprite
    {
        private var W:int;
        private var H:int;
        
        private var renderContext:Context3D;
        private var program:Program3D;
        private var vertexBuffer:VertexBuffer3D;
        private var instanceBufferColor:VertexBuffer3D;
        private var instanceBufferTranslation:VertexBuffer3D;
        private var indexBuffer:IndexBuffer3D;
        private var m:Matrix3D;
        private var vertexShader:ByteArray;
        private var fragmentShader:ByteArray;
        
        public function Context3D_HelloInstancedDrawing()
        {
            if (hasEventListener(Event.ADDED_TO_STAGE))
                removeEventListener(Event.ADDED_TO_STAGE, init);
            W = stage.stageWidth;
            H = stage.stageHeight;
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;
            stage.stage3Ds[0].addEventListener(Event.CONTEXT3D_CREATE, contextCreated);
            //We need to request context3D in standard extended profile as instanced drawing requires standard extended profile.
            stage.stage3Ds[0].requestContext3D("auto","standardExtended");            
            
        }
        
        //Note: <code>context3DCreate</code> event can happen at any time. For example, when the hardware resources are taken up by another process.
        private function contextCreated( event:Event ):void
        {
            var t:Stage3D = event.target as Stage3D;
            renderContext = t.context3D;
            trace( "3D driver: " + renderContext.driverInfo );
            setupScene();
        }
        
        
        private function setupScene():void
        {
            renderContext.enableErrorChecking = true;
            renderContext.configureBackBuffer( W, H, 2, false );
            renderContext.setCulling( Context3DTriangleFace.BACK );
            
            //create vertex buffer for geometry information of the instances (same geometry of the instances)
            vertexBuffer = renderContext.createVertexBuffer(3, 3);
            
            //The color and translation information varies across the instances. Use <code>createVertexBufferForInstances</code> for color and translation information.
            //the intancesPerElement parameter used is 1 which means that each instance will use unique element of the instances buffer
            //if the intancesPerElement is 3 then sets of 3 instances will use the same element of the instances buffer
            instanceBufferColor = renderContext.createVertexBufferForInstances(4,3,1);
            instanceBufferTranslation = renderContext.createVertexBufferForInstances(4,3,1);
            //create index buffer for the triangle
            indexBuffer = renderContext.createIndexBuffer(3);
            
            //create and compile program
            program = renderContext.createProgram();
            var assembler:AGALMiniAssembler = new AGALMiniAssembler();
            
            // VERTEX SHADER
            var code:String = "";
            //The vertex shader code runs for every vertex of each instance.
            //The vertex buffers uploaded for instance data (va1,va2) are used when the vertex shader for that particular instance is being executed.
            code += "add vt0, va0, va2\n";
            code += "mov op, vt0\n";
            code += "mov v0, va1\n";
            
            vertexShader = assembler.assemble(Context3DProgramType.VERTEX, code);
            
            //FRAGMENT SHADER
            code = "mov oc, v0\n"; 
            
            // Compile the agal code into bytecode using agalminiassembler
            fragmentShader = assembler.assemble(Context3DProgramType.FRAGMENT, code);
            
            //upload program to gpu
            program.upload(vertexShader, fragmentShader);
            
            //geometry data for the instances
            var vertexData:Vector.<Number>=Vector.<Number>([
                -0.3, -0.3, 0,     // - 1st vertex x,y,z
                0, 0.3, 1,         // - 2nd vertex x,y,z 
                0.3, -0.3, 0    // - 3rd vertex x,y,z
            ]);
            
            //per instance color data
            var instanceColorData:Vector.<Number>=Vector.<Number>([
                1.0, 0.0, 0.0,     // - 1st instance r,g,b
                0.0, 1.0, 0.0,  // - 2nd instance r,g,b
                1.0, 1.0, 1.0,    // - 3rd instance r,g,b
                0.7, 0.0, 1.0   // - 4th instance r,g,b
            ]);
            //per instance translation data
            var instanceTranslationData:Vector.<Number>=Vector.<Number>([
                -0.3, -0.3, 0.0,     // - 1st instance x,y,z
                0.3, 0.3, 0.0,         // - 2nd instance x,y,z
                -0.3, 0.3, 0.0,        // - 3rd instance x,y,z
                0.3, -0.3, 0.0      // - 4th instance x,y,z
            ]);
            
            vertexBuffer.uploadFromVector(vertexData, 0, 3);
            instanceBufferColor.uploadFromVector(instanceColorData, 0, 4);
            indexBuffer.uploadFromVector(Vector.<uint>([0, 1, 2]), 0, 3);
            instanceBufferTranslation.uploadFromVector(instanceTranslationData, 0, 4);
            
            //pass data to program
            renderContext.setVertexBufferAt(0, vertexBuffer, 0, Context3DVertexBufferFormat.FLOAT_3);
            renderContext.setVertexBufferAt(1, instanceBufferColor, 0, Context3DVertexBufferFormat.FLOAT_3);
            renderContext.setVertexBufferAt(2, instanceBufferTranslation, 0, Context3DVertexBufferFormat.FLOAT_3);
            
            //set active program
            renderContext.setProgram(program);
            renderContext.enableErrorChecking = true;
            addEventListener(Event.ENTER_FRAME, render);
            
        }
        
        private function render( event:Event ):void
        {
            renderContext.clear(0.3, 0.2, 1, 1); // Clear the backbuffer by filling it with the given color
            //Draw three instances of the same geometry but with varying instance data specified using <code>vertexBufferForInstances</code>.
            renderContext.drawTrianglesInstanced(indexBuffer,4);
            renderContext.present(); // render the backbuffer on screen.
        }    
    }
}

下列類別會使用以單一繪製呼叫 (而非多個繪製呼叫) 進行實體化繪製的功能,繪製三個三角形。
package
{
    import com.adobe.utils.v3.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DTriangleFace;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    import flash.geom.Matrix3D;
    import flash.utils.ByteArray;
    
    public class Context3D_HelloInstanceIdRegister extends Sprite
    {
        private var W:int;
        private var H:int;
        
        private var renderContext:Context3D;
        private var program:Program3D;
        private var vertexBuffer:VertexBuffer3D;
        private var instanceBufferColor:VertexBuffer3D;
        private var instanceBufferTranslation:VertexBuffer3D;
        private var indexBuffer:IndexBuffer3D;
        private var m:Matrix3D;
        private var vertexShader:ByteArray;
        private var fragmentShader:ByteArray;
        
        public function Context3D_HelloInstanceIdRegister()
        {
            if (hasEventListener(Event.ADDED_TO_STAGE))
                removeEventListener(Event.ADDED_TO_STAGE, init);
            W = stage.stageWidth;
            H = stage.stageHeight;
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;
            stage.stage3Ds[0].addEventListener(Event.CONTEXT3D_CREATE, contextCreated);
            //We need to request context3D in standard extended profile as instanced drawing requires standard extended profile.
            stage.stage3Ds[0].requestContext3D("auto","standardExtended");            
            
        }
        
        //Note: <code>context3DCreate</code> event can happen at any time. For example, when the hardware resources are taken up by another process.
        private function contextCreated( event:Event ):void
        {
            var t:Stage3D = event.target as Stage3D;
            renderContext = t.context3D;
            trace( "3D driver: " + renderContext.driverInfo );
            setupScene();
        }
        
        
        private function setupScene():void
        {
            renderContext.enableErrorChecking = true;
            renderContext.configureBackBuffer( W, H, 2, false );
            renderContext.setCulling( Context3DTriangleFace.BACK );
            
            //create vertex buffer for geometry information of the instances (same geometry of the instances)
            vertexBuffer = renderContext.createVertexBuffer(3, 3);
            
            //The color and translation information varies across the instances. Use <code>createVertexBufferForInstances</code> for color and translation information.
            //the intancesPerElement parameter used is 1 which means that each instance will use unique element of the instances buffer
            //if the intancesPerElement is 3 then sets of 3 instances will use the same element of the instances buffer
            instanceBufferColor = renderContext.createVertexBufferForInstances(4,3,1);
            instanceBufferTranslation = renderContext.createVertexBufferForInstances(4,3,1);
            //create index buffer for the triangle
            indexBuffer = renderContext.createIndexBuffer(3);
            
            //create and compile program
            program = renderContext.createProgram();
            //Note : for instance id support , use the latest AgalMiniAssembler from github - https://github.com/adobe-flash/graphicscorelib/blob/master/src/com/adobe/utils/v3/AGALMiniAssembler.as
            var assembler:AGALMiniAssembler = new AGALMiniAssembler();
            
            // VERTEX SHADER
            var code:String = "";
            //the vertex shader code will run for every vertex of every instance , 
            //the vertex buffers uploaded for instance data (va1,va2) will be used when vertex shader for that particular instance is being executed 
            //the vertex shader code below indexes the program constants matrix using iid.x. iid is a new register introduced in vertex shader for instanced drawing
            //it is a read only register , iid.x gives the current instance id whose shader is being executed
            code += "add vt0, va0, va2\n";
            code += "mul vt1, vt0, vc[iid.x]\n"
            code += "mov op, vt1\n";
            code += "mov v0, va1\n";
            
            vertexShader = assembler.assemble(Context3DProgramType.VERTEX, code, 3);
            
            //FRAGMENT SHADER
            code = "mov oc, v0\n"; 
            
            // Compile the agal code into bytecode using agalminiassembler
            fragmentShader = assembler.assemble(Context3DProgramType.FRAGMENT, code, 3);
            
            //upload program to gpu
            program.upload(vertexShader, fragmentShader);
            
            //geometry data for the instances
            var vertexData:Vector.<Number>=Vector.<Number>([
                -0.3, -0.3, 0,     // - 1st vertex x,y,z
                0, 0.3, 1,         // - 2nd vertex x,y,z 
                0.3, -0.3, 0    // - 3rd vertex x,y,z
            ]);
            
            //per instance color data
            var instanceColorData:Vector.<Number>=Vector.<Number>([
                1.0, 0.0, 0.0,     // - 1st instance r,g,b
                0.0, 1.0, 0.0,  // - 2nd instance r,g,b
                1.0, 1.0, 1.0,    // - 3rd instance r,g,b
                0.7, 0.0, 1.0   // - 4th instance r,g,b
            ]);
            //per instance translation data
            var instanceTranslationData:Vector.<Number>=Vector.<Number>([
                -0.3, -0.3, 0.0,     // - 1st instance x,y,z
                0.3, 0.3, 0.0,         // - 2nd instance x,y,z
                -0.3, 0.3, 0.0,        // - 3rd instance x,y,z
                0.3, -0.3, 0.0      // - 4th instance x,y,z
            ]);
            
            vertexBuffer.uploadFromVector(vertexData, 0, 3);
            instanceBufferColor.uploadFromVector(instanceColorData, 0, 4);
            indexBuffer.uploadFromVector(Vector.<uint>([0, 1, 2]), 0, 3);
            instanceBufferTranslation.uploadFromVector(instanceTranslationData, 0, 4);
            
            //pass data to program
            renderContext.setVertexBufferAt(0, vertexBuffer, 0, Context3DVertexBufferFormat.FLOAT_3);
            renderContext.setVertexBufferAt(1, instanceBufferColor, 0, Context3DVertexBufferFormat.FLOAT_3);
            renderContext.setVertexBufferAt(2, instanceBufferTranslation, 0, Context3DVertexBufferFormat.FLOAT_3);
            
            //set active program
            renderContext.setProgram(program);
            renderContext.enableErrorChecking = true;
            addEventListener(Event.ENTER_FRAME, render);
            
        }
        
        private function render( event:Event ):void
        {
            renderContext.clear(0.3, 0.2, 1, 1); // Clear the backbuffer by filling it with the given color
            var instanceScalingData:Vector.<Number>=Vector.<Number>([
                1.0, 1.0, 1.0, 1.0,     // - 1st instance x,y,z,w
                1.4, 1.4, 1.4, 1.0,        // - 2nd instance x,y,z,w
                0.6, 0.6, 0.6, 1.0,        // - 3rd instance x,y,z,w
                0.6, 0.6, 0.6, 1.0
            ]);
            var m:Matrix3D = new Matrix3D();
            m.copyRawDataFrom(instanceScalingData);
            renderContext.setProgramConstantsFromMatrix("vertex",0,m,false);
            
            //Draw three instances of the same geometry but with varying instance data specified using <code>vertexBufferForInstances</code>.
            renderContext.drawTrianglesInstanced(indexBuffer,4);
            renderContext.present(); // render the backbuffer on screen.
        }    
    }
}

present

()方法 
public function present():void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

顯示背景顯示緩衝區。

呼叫 present() 方法會使自最後一次可見的 present() 呼叫以來的所有顯示作業產生結果,並且啟動新的顯示循環。呼叫 present 之後,您必須先呼叫 clear() 再進行其他 drawTriangles() 呼叫。否則,這個函數會交替清除黃色和綠色的顯示緩衝區,或者如果 enableErrorChecking 已設定為 true,則會擲回例外。

呼叫 present() 也會重設顯示目標,就如同呼叫 setRenderToBackBuffer()


擲回值
Error — 繪製前必須先清除:自上一次呼叫 present() 以來不曾呼叫過 clear() (不允許兩個連續 present() 呼叫未在彼此間呼叫 clear())。
 
Error — 3768:在背景執行期間不會使用 Stage3D API。

setBlendFactors

()方法 
public function setBlendFactors(sourceFactor:String, destinationFactor:String):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

指定用於將繪製作業的輸出顏色與現有顏色混合的係數。

像素著色器程式的輸出 (來源) 顏色會根據下列公式,與該像素位置的現有 (目標) 顏色相結合:

result color = (source color * sourceFactor) + (destination color * destinationFactor)

該像素的目標顏色是顯示緩衝區中的目前顏色。因此,這是最近 clear() 呼叫和任何中介 drawTriangles() 呼叫的結果。

使用 setBlendFactors() 可以設定來源顏色和目標顏色相加之前先相乘所用的係數。預設混合係數是 sourceFactor = Context3DBlendFactor.ONEdestinationFactor = Context3DBlendFactor.ZERO,結果來源顏色會覆寫目標顏色 (換句話說,兩個顏色沒有產生混合)。若是一般 Alpha 混合,請使用 sourceFactor = Context3DBlendFactor.SOURCE_ALPHAdestinationFactor = Context3DBlendFactor.ONE_MINUS_SOURCE_ALPHA

使用 Context3DBlendFactor 類別中定義的常數可以設定這個函數的參數。

參數

sourceFactor:String — 要乘以來源顏色的係數。預設為 Context3DBlendFactor.ONE
 
destinationFactor:String — 要乘以目標顏色的係數。預設為 Context3DBlendFactor.ZERO


擲回值
Error — 無效的列舉:sourceFactordestinationFactor 不是其中一個可辨識的值的時候,這些值是在 Context3DBlendFactor 類別中定義。

相關 API 元素


範例  ( 如何使用本範例 )

下列類別說明各種不同的混合係數。此範例會在顯示緩衝區繪製四種不同顏色的矩形。這組矩形便是混合「目標」。接下來,設定來源與目標混合模式,並繪製一個較大的矩形,也就是混合「來源」。請使用按鍵「1」與「2」來循環切換來源混合模式。使用按鍵「3」與「4」來循環切換目標混合模式。
package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DBlendFactor;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.ErrorEvent;
    import flash.events.Event;
    import flash.events.KeyboardEvent;
    import flash.ui.Keyboard;
    
    public class Context3D_setBlendMode extends Sprite
    {
        public const viewWidth:Number = 320;
        public const viewHeight:Number = 200;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        private var sourceFactor:int = 6;
        private var destinationFactor:int = 4;
        private var blendFactors:Array = [Context3DBlendFactor.DESTINATION_ALPHA,
                                          Context3DBlendFactor.DESTINATION_COLOR,
                                          Context3DBlendFactor.ONE,
                                          Context3DBlendFactor.ONE_MINUS_DESTINATION_ALPHA,
                                          Context3DBlendFactor.ONE_MINUS_SOURCE_ALPHA,
                                          Context3DBlendFactor.ONE_MINUS_SOURCE_COLOR,
                                          Context3DBlendFactor.SOURCE_ALPHA,
                                          Context3DBlendFactor.SOURCE_COLOR,
                                          Context3DBlendFactor.ZERO];
            
        public function Context3D_setBlendMode()
        {
            this.stage.addEventListener( KeyboardEvent.KEY_DOWN, keyHandler );
            
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );
            stage3D.addEventListener( ErrorEvent.ERROR, contextError );
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [  0, 3 , 2, 
                                                            0, 1, 3,
                                                            6, 4, 5,
                                                            5, 7, 6,
                                                            10, 8, 9,
                                                            9, 11, 10,
                                                            12, 15, 14,
                                                            12, 13, 15,
                                                            16, 17, 19,
                                                            16, 19, 18
                                                         ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 7;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  // x, y, z    r, g, b, a format
                    -1, 1, 0,   1, 1, 1, .5,
                     0, 1, 0,   1, 1, 1, .5,
                    -1, 0, 0,   1, 1, 1, .5,
                     0, 0, 0,   1, 1, 1, .5,
                     
                     0, 1, 0,  .8,.8,.8, .6,
                     1, 1, 0,  .8,.8,.8, .6,
                     0, 0, 0,  .8,.8,.8, .6,
                     1, 0, 0,  .8,.8,.8, .6,
                     
                    -1, 0, 0,   1, 0, 0, .5,
                     0, 0, 0,   0, 1, 0, .5,
                    -1,-1, 0,   0, 0, 1, .5,
                     0,-1, 0,   1, 0, 1, .5,
                     
                     0, 0, 0,   0, 0, 0, .5,
                     1, 0, 0,   0, 0, 0, .5,
                     0,-1, 0,   0, 0, 0, .5,
                     1,-1, 0,   0, 0, 0, .5,
                     
                   -.8,.8, 0,  .6,.4,.2,.4,
                    .8,.8, 0,  .6,.4,.2,.4,
                  -.8,-.8, 0,  .6,.4,.2,.4,
                   .8,-.8, 0,  .6,.4,.2,.4
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_4 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            render();
        }
        
        private function render():void
        {
            //Clear required before first drawTriangles() call
            renderContext.clear( 1, 1, 1, 1 );
            //Draw the back triangles
            renderContext.setBlendFactors( Context3DBlendFactor.ONE, Context3DBlendFactor.ZERO ); //No blending
            renderContext.drawTriangles( indexList, 0, 8 );

            //Set blend
            renderContext.setBlendFactors( blendFactors[sourceFactor], blendFactors[destinationFactor] );
            
            //Draw the front triangles
            renderContext.drawTriangles( indexList, 24, 2 );
            
            //Show the frame
            renderContext.present();
        }
        
        private function contextError( error:ErrorEvent ):void
        {
            trace( error.errorID + ": " + error.text );
        }
        
        private function keyHandler( event:KeyboardEvent ):void
        {
            switch ( event.keyCode )
            {
                case Keyboard.NUMBER_1:
                    if( --sourceFactor < 0 ) sourceFactor = blendFactors.length - 1; 
                    break;
                case Keyboard.NUMBER_2:
                    if( ++sourceFactor > blendFactors.length - 1) sourceFactor = 0;
                    break;
                case Keyboard.NUMBER_3:
                    if( --destinationFactor < 0 ) destinationFactor = blendFactors.length - 1; 
                    break;
                case Keyboard.NUMBER_4:
                    if( ++destinationFactor > blendFactors.length - 1) destinationFactor = 0;
                    break;
            }
            trace( "Source blend factor: " + blendFactors[sourceFactor] + ", destination blend factor: " + blendFactors[destinationFactor] );
            render();
        }
    }
}

setColorMask

()方法 
public function setColorMask(red:Boolean, green:Boolean, blue:Boolean, alpha:Boolean):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定將顏色寫入顯示緩衝區時所用的遮色片。

將顏色寫入顯示緩衝區時,只會更新對應顏色遮色片參數為 true 的顏色組件。例如,如果您呼叫 setColorMask( true, false, false, false ),在您再次變更顏色遮色片之前,只有顏色的紅色組件會寫入緩衝區。顏色遮色片不會影響 clear() 方法的行為。

參數

red:Boolean — 設定 false 可防止變更紅色色版。
 
green:Boolean — 設定 false 可防止變更綠色色版。
 
blue:Boolean — 設定 false 可防止變更藍色色版。
 
alpha:Boolean — 設定 false 可防止變更 Alpha 色版。


範例  ( 如何使用本範例 )

下列範例說明設定顏色遮色片的效果。此範例會描繪兩個顏色相同的三角形。上方的三角形是在設定遮色片之前描繪,因而顯示為白色。下方的三角形是在遮住紅色色版以外的所有色版之後描繪。因為只能更新紅色色版,所以白色三角形會顯示為紅色。
package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    
    public class Context3D_setColorMask extends Sprite
    {
        public const viewWidth:Number = 320;
        public const viewHeight:Number = 200;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        public function Context3D_setColorMask()
        {
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );            
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [ 0, 1, 2, 0, 3, 4 ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  // x, y, z    r, g, b format
                     0, 0, 0,   1, 1, 1,
                    -1, 1, 0,   1, 1, 1,
                     1, 1, 0,   1, 1, 1,
                     1,-1, 0,   1, 1, 1,
                    -1,-1, 0,   1, 1, 1
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            renderContext.clear( .3,.3,.3,1 );
            renderContext.drawTriangles( indexList, 0, 1 ); //Top triangle draws all colors, so is white
            renderContext.setColorMask( true, false, false, false ); //Mask all but red channel            
            renderContext.drawTriangles( indexList, 3, 1 ); //Bottom triangle only updates red
            
            //Show the frame
            renderContext.present();
        }
    }
}

setCulling

()方法 
public function setCulling(triangleFaceToCull:String):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定三角形剔除模式。

可根據其相對於檢視平面的方向,從顯示管線中的早期場景中排除三角形。正確地從要剔除的模型外部檢視,一致地指定頂點順序 (順時針或逆時針)。

參數

triangleFaceToCull:String — 剔除模式。使用 Context3DTriangleFace 類別中定義的其中一個常數。


擲回值
Error — 無效的列舉錯誤:triangleFaceToCull 不是 Context3DTriangleFace 類別中定義的其中一個值。

相關 API 元素

setDepthTest

()方法 
public function setDepthTest(depthMask:Boolean, passCompareMode:String):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定用於深度測試的比較類型。

像素著色器程式中的來源像素輸出深度會與深度緩衝區中的目前值相比較。如果比較評估為 false,則會捨棄來源像素。如果為 true,則來源像素會進行顯示管線中的下一個步驟,即模板測試。此外,只要 depthMask 參數設定為 true,深度緩衝區還會以來源像素的深度進行更新。

設定用來比較來源和目的地像素的深度值之測試。當比較為 true 時,來源像素將與目的地像素複合。comparison 運算子將依照該順序,做為來源與目的地像素值之間的 infix 運算子予以套用。

參數

depthMask:Boolean — 若為 true,則從來源像素更新目的地深度值。
 
passCompareMode:String — 深度比較測試作業。其中一個 Context3DCompareMode 值。

相關 API 元素

    setFillMode

()方法 
public function setFillMode(fillMode:String):void

語言版本: ActionScript 3.0
執行階段版本: AIR 16

設定用於顯示的填色模式。此介面只在 AIR 桌面中提供使用。

參數

fillMode:String — 如果值是 WIREFRAME,將會以線條組成的網格來顯示物件。如果值是 SOLID,將會以純色著色的多邊形來顯示物件。

相關 API 元素

setProgram

()方法 
public function setProgram(program:Program3D):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定頂點和片段著色器程式,以供後續顯示使用。

參數

program:Program3D — 代表要使用頂點和片段程的 Program3D 物件。

相關 API 元素


範例  ( 如何使用本範例 )

此範例說明如何建立、上傳及啟用顯示內容的一組頂點與像素程式。請注意,renderContext 物件是 Context3D 類別的實體。範例中的程式是使用 Adobe Graphics Assembly Language (AGAL) 所撰寫。
//A simple vertex program in AGAL
const VERTEX_SHADER:String =
    "m44 op, va0, vc0 \n" +    
    "mov v0, va1"; 

//A simple fragment (or pixel) program in AGAL        
const FRAGMENT_SHADER:String = "mov oc, v0";  

var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
var programPair:Program3D;

//Compile shaders
vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            

//Upload programs to render context
programPair = renderContext.createProgram();
programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
renderContext.setProgram( programPair );
            

setProgramConstantsFromByteArray

()方法 
public function setProgramConstantsFromByteArray(programType:String, firstRegister:int, numRegisters:int, data:ByteArray, byteArrayOffset:uint):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11.1, AIR 3.1

使用 ByteArray 中儲存的值,設定著色器程式所使用的常數。

設定可從頂點或片段程式中存取的常數。

參數

programType:String — 其中一個 Context3DProgramType。
 
firstRegister:int — 要設定的第一個著色器程式常數的索引。
 
numRegisters:int — 要設定的暫存器數目。每個暫存器會讀取為四個浮點值。
 
data:ByteArray — 來源 ByteArray 物件
 
byteArrayOffset:uint — ByteArray 進行讀取時的偏移值


擲回值
TypeError — 當 data 為 null 時,則為 kNullPointerError。
 
RangeError — 當嘗試設定的著色器常數的數目超過其上限時,則為 kConstantRegisterOutOfBounds。
 
RangeError — 如果 byteArrayOffset 大於或等於 data 的長度,或 data 中的元素數目 - byteArrayOffset 小於 numRegisters*16,則會發生 kBadInputSize。

相關 API 元素

setProgramConstantsFromMatrix

()方法 
public function setProgramConstantsFromMatrix(programType:String, firstRegister:int, matrix:Matrix3D, transposedMatrix:Boolean = false):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

使用 Matrix3D 中儲存的值,設定著色器程式所使用的常數。

使用這個函數可將矩陣傳遞至著色器程式。函數會設定頂點或片段程式所使用的 4 個常數暫存器。矩陣已逐列指定給暫存器。第一個常數暫存器已指定矩陣的頂端列。您可以為頂點程式設定 128 個暫存器,為片段程式設定 28 個。

參數

programType:String — 著色器程式類型,可能是 Context3DProgramType.VERTEXContext3DProgramType.FRAGMENT
 
firstRegister:int — 第一個要設定的常數暫存器索引。由於 Matrix3D 有 16 個值,因此,設定 4 個暫存器。
 
matrix:Matrix3D — 包含常數值的矩陣。
 
transposedMatrix:Boolean (default = false) — 若為 true,則依反方向將矩陣項目複製到暫存器。預設值是 false


擲回值
TypeError — Null 指標錯誤:matrix 為 null。
 
RangeError — 常數暫存器超出範圍:嘗試設定超過著色器常數暫存器上限。

詳細資訊

相關 API 元素

setProgramConstantsFromVector

()方法 
public function setProgramConstantsFromVector(programType:String, firstRegister:int, data:Vector.<Number>, numRegisters:int = -1):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定著色器程式的常數輸入。

設定頂點或片段著色器程式存取的常數陣列。Program3D 中的常數集是在著色器程式中做為常數暫存器存取。每一個常數暫存器包含 4 個浮點數值 (x, y, z, w)。因此每個暫存器在 data 向量中需要 4 個項目。您可以針對頂點程式和片段程式設定的暫存器數目,取決於 Context3DProfile

參數

programType:String — 著色器程式類型,可能是 Context3DProgramType.VERTEXContext3DProgramType.FRAGMENT
 
firstRegister:int — 第一個要設定的常數暫存器索引。
 
data:Vector.<Number> — 浮點常數值。data 中至少必須有 numRegisters 4 個元素。
 
numRegisters:int (default = -1) — 要設定的常數數目。指定 -1 預設值,可設定足夠的暫存器來使用所有可用資料。


擲回值
TypeError — Null 指標錯誤:datanull
 
RangeError — 常數暫存器超出範圍:嘗試設定超過著色器常數暫存器上限。
 
RangeError — 輸入大小錯誤:data 中的元素數目小於 numRegisters*4

詳細資訊

相關 API 元素

setRenderToBackBuffer

()方法 
public function setRenderToBackBuffer():void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定背景顯示緩衝區做為顯示目標。後續呼叫 drawTriangles()clear() 方法將導致背景緩衝區更新。在使用 setRenderToTexture() 方法之後,使用這個方法可恢復一般顯示。

setRenderToTexture

()方法 
public function setRenderToTexture(texture:flash.display3D.textures:TextureBase, enableDepthAndStencil:Boolean = false, antiAlias:int = 0, surfaceSelector:int = 0, colorOutputIndex:int = 0):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定指定的紋理做為顯示目標。

後續呼叫 drawTriangles()clear() 方法會更新指定的紋理,而非背景緩衝區。自動建立 Mip 映射。使用 setRenderToBackBuffer() 可恢復背景緩衝區的一般顯示。

繪圖前不需執行任何清除動作。如果沒有清除作業,將會保留顯示內容。深度緩衝區和模板緩衝區也不會遭到清除。但是,第一次繪圖時會強制清除。呼叫 present() 會將目標重設為背景緩衝區。

參數

texture:flash.display3D.textures:TextureBase — 要向其顯示的目標紋理。設定為 null 可恢復顯示至背景緩衝區 (setRenderToBackBuffer()present 也會將目標重設為背景緩衝區)。
 
enableDepthAndStencil:Boolean (default = false) — 如果為 true,則可以使用深度和模板測試。如果為 false,則會忽略後續繪製作業的所有深度和模板狀態。
 
antiAlias:int (default = 0) — 消除鋸齒品質。使用 0 可停用消除鋸齒;較高的值能改善消除鋸齒品質,但需要更多計算。此值目前被行動平台和軟體顯示內容忽略。
 
surfaceSelector:int (default = 0) — 指定要更新的紋理元素。Texture 物件有 1 個表面,因此,您必須指定預設值 0。CubeTexture 物件有 6 個表面,因此,您可以指定 0 到 5 的整數。
 
colorOutputIndex:int (default = 0) — 輸出色彩暫存器。對於限制或基線模式,必須為 0。或者,請指定輸出色彩暫存器。


擲回值
ArgumentError — 因為 surfaceSelector 參數不符。2D 紋理的值必須是 0,而立方體對應的值必須是 0~5。
 
ArgumentError texture 並非衍生自 TextureBase 類別 (Texture 或 CubeTexture 類別)。
 
ArgumentError colorOutputIndex 必須是介於 0 和 3 之間的整數。
 
ArgumentError — 這個呼叫需要以標準描述檔或更高版本建立的 Context3D

相關 API 元素

setSamplerStateAt

()方法 
public function setSamplerStateAt(sampler:int, wrap:String, filter:String, mipfilter:String):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11.6, AIR 3.6

手動覆寫紋理取樣程式狀態。

紋理取樣狀態通常是在呼叫 setProgram 時設定的。不過,您可以使用此函數覆寫紋理取樣程式狀態。如果您不希望程式變更取樣程式狀態,請在 AGAL 中設定 ignoresamnpler 位元並使用此函數。

參數

sampler:int — 取樣程式 暫存器要使用的取樣程式。AGAL 中取樣程式暫存器的對應。
 
wrap:String — 換行模式。已定義於 Context3DWrapMode。預設值為 repeat。
 
filter:String — 紋理篩選模式。已定義於 Context3DTextureFilter。預設值為 nearest。
 
mipfilter:String — MIP 對應濾鏡。已定義於 Context3DMipFilter。預設值為 none。


擲回值
Error — 取樣程式超出範圍
 
Error — 包裝、濾鏡、MIP 濾鏡列舉錯誤
 
Error — 物件已處理:這個 Context3D 物件已經透過呼叫 dispose() 的方式處理,或是因為遺失基礎顯示硬體。

相關 API 元素

setScissorRectangle

()方法 
public function setScissorRectangle(rectangle:Rectangle):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定剪刀矩形,這是繪製遮色片類型。輸出器只會繪製到剪刀矩形內的區域。剪斷不影響清除作業。

傳遞 null 即可關閉剪斷。

參數

rectangle:Rectangle — 要在其中繪製的矩形。以像素為單位指定矩形位置和尺寸。座標系統原點是在檢視區域的左上角,隨著正數值增加而往下及往右 (就像一般 Flash 顯示座標系統)。


範例  ( 如何使用本範例 )

下列類別會將兩個三角形繪製至舞台上的 640x480 像素檢視連接埠。這兩個三角形共用一個頂點,其位於原點 (0,0,0)。

三角形是使用頂點緩衝區和索引緩衝區來定義。頂點緩衝區包含每個三角形頂點的位置和顏色資訊。索引緩衝區包含頂點緩衝區的索引。三個索引定義一個三角形。例如,由頂點緩衝區中前三個點所組成的三角形,在索引緩衝區中列示為 0,1,2。

在這個簡單範例中,不會執行 3D 變形。只會顯示標準檢視區域 (以原點為中心,體積為 2x2x2 的立方體) 內的物件。不過,在顯示典型的 3D 場景時,請使用透視或正視投影,將要顯示的物件投影至此檢視區域。

package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DBlendFactor;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    import flash.events.KeyboardEvent;
    import flash.events.TimerEvent;
    import flash.geom.Rectangle;
    import flash.ui.Keyboard;
    import flash.utils.Timer;
    
    public class Context3D_ScissorRectangle extends Sprite
    {
        public const viewWidth:Number = 640;
        public const viewHeight:Number = 480;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        private var scissorOn:Boolean = false;
        private var toggler:Timer = new Timer( 750 );
        
        public function Context3D_ScissorRectangle()
        {            
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );            
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );
            
            //Set up timer to turn scissoring on and off
            toggler.addEventListener( TimerEvent.TIMER, toggleScissor );
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [  0, 3 , 2, 
                                                            0, 1, 3
                                                         ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  // x, y, z    r, g, b, a format 
                   -1, 1, 0,  1,0,0,
                    1, 1, 0,  0,0,1,
                   -1,-1, 0,  0,1,0,
                    1,-1, 0,  1,0,1
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            render();
            toggler.start();
        }
        
        private function render():void
        {
            //Clear required before first drawTriangles() call
            renderContext.clear();

            //Sciss a region excluding the outer 100 pixels of the viewport
            var scissor:Rectangle = new Rectangle( 100, 100, viewWidth - 200, viewHeight - 200 );
            if( scissorOn )    renderContext.setScissorRectangle( scissor ); //on
            else renderContext.setScissorRectangle( null ); //off

            //Draw the triangles
            renderContext.drawTriangles( indexList, 0, 2 );
            
            //Show the frame
            renderContext.present();
        }
        
        private function toggleScissor( event:Event ):void
        {
            scissorOn = !scissorOn;
            render();
        }
        
    }
}

setStencilActions

()方法 
public function setStencilActions(triangleFace:String = "frontAndBack", compareMode:String = "always", actionOnBothPass:String = "keep", actionOnDepthFail:String = "keep", actionOnDepthPassStencilFail:String = "keep"):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定模板模式和作業。

一個 8 位元模板參考值可關聯每一個繪製呼叫。在顯示期間,可針對影格緩衝區先前的儲存值測試參考值。測試的結果可控制繪製動作,及是否或如何更新儲存的模板值。此外,深度測試控制是否執行模板測試。也可以使用失敗的深度測試,控制模板緩衝區上執行的動作。

在像素處理管線中,將首先執行深度測試。如果深度測試失敗,可執行模板緩衝區更新動作,但不會進一步評估模板緩衝區值。如果通過深度測試,則執行模板測試。可依據模板測試的結果來執行替代動作。

模板參考值是使用 setStencilReferenceValue() 所設定。

參數

triangleFace:String (default = "frontAndBack") — 允許在模板作業中使用的三角形方向。其中一個 Context3DTriangleFace。
 
compareMode:String (default = "always") — test 運算子,可用來比較目前的模板參考值和目的地像素模板值。當 comparison 為 true 時將執行目的地像素顏色和深度更新。在下列動作參數中,將在要求時執行模板動作。comparison 運算子將依照該順序,做為目前與目的地像素值之間的 infix 運算子予以套用 (在 pseudocode 中:若為 if stencilReference OPERATOR stencilBuffer then pass)。使用 Context3DCompareMode 類別中定義的其中一個常數。
 
actionOnBothPass:String (default = "keep") — 當深度和模板比較通過時所採取的動作。使用 Context3DStencilAction 類別中定義的其中一個常數。
 
actionOnDepthFail:String (default = "keep") — 深度比較失敗時所採取的動作。使用 Context3DStencilAction 類別中定義的其中一個常數。
 
actionOnDepthPassStencilFail:String (default = "keep") — 深度比較通過且模板比較失敗時所採取的動作。使用 Context3DStencilAction 類別中定義的其中一個常數。


擲回值
Error — 無效的列舉錯誤:triangleFace 不是 Context3DTriangleFace 類別中定義的其中一個值。
 
Error — 無效的列舉錯誤:compareMode 不是 Context3DCompareMode 類別中定義的其中一個值。
 
Error — 無效的列舉錯誤:actionOnBothPassactionOnDepthFailactionOnDepthPassStencilFail 不是 Context3DStencilAction 類別中定義的其中一個值。

相關 API 元素


範例  ( 如何使用本範例 )

下列類別說明如何繪製模板並做為遮色片,用於後續繪製作業。這個範例會執行以下步驟:
  • 清除模板緩衝區並設為 0。
  • 通過模板測試後,將模板動作設定為遞增。
  • 將模板參考值設定為 0。
  • 繪製三角形遮色片。因為已清除模板緩衝區並設為 0 且參考值為 0,所以不論在哪裡繪製三角形,都會通過模板測試。因此,在繪製三角形遮色片的位置,模板緩衝區會遞增為 1。
  • 變更要保留的模板動作,以便讓後續繪製作業不會變更模板緩衝區。
  • 繪製全螢幕的矩形 (多重顏色)。因為模板參考值仍為 0,所以在遮色區域進行模板測試會失敗。因此,可在遮色區域以外的位置繪製矩形。
  • 將模板參考值變更為 1。
  • 繪製另一個全螢幕的矩形 (紅色)。現在,若在遞增為 1 的遮色區域以外的位置進行模板測試都會失敗。因此,只會在遮色區域繪製矩形。

將滑鼠移至範例上方,即可依序查閱主要步驟。

package
{
    import com.adobe.utils.AGALMiniAssembler;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DBlendFactor;
    import flash.display3D.Context3DCompareMode;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DStencilAction;
    import flash.display3D.Context3DTriangleFace;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.Event;
    import flash.events.KeyboardEvent;
    import flash.events.MouseEvent;
    import flash.events.TimerEvent;
    import flash.geom.Rectangle;
    import flash.text.TextField;
    import flash.text.TextFormat;
    import flash.ui.Keyboard;
    import flash.utils.Timer;
    
    public class Context3D_Stencil extends Sprite
    {
        public const viewWidth:Number = 350;
        public const viewHeight:Number = 240;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private const VERTEX_SHADER:String =
            "mov op, va0    \n" +    //copy position to output 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
                
        public function Context3D_Stencil()
        {            
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );            
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );
        
            non3DSetup();
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
            renderContext = Stage3D( event.target ).context3D;
            trace( "3D driver: " + renderContext.driverInfo );

            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, true );
            
            //Create vertex index list for the triangles
            var triangles:Vector.<uint> = Vector.<uint>( [  0, 3, 2, 
                                                            0, 1, 3,
                                                            4, 7, 6,
                                                            4, 5, 7,
                                                            8, 9, 10
                                                         ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                  //x, y, z  r,g,b format 
                   -1, 1, 0,  1,0,0,
                    1, 1, 0,  0,0,1,
                   -1,-1, 0,  0,1,0,
                    1,-1, 0,  1,0,1,

                   -1, 1, 0,  .5,0,0,
                    1, 1, 0,  .5,0,0,
                   -1,-1, 0,  .5,0,0,
                    1,-1, 0,  .5,0,0,
                    
                    0, .7,.1, 0,0,0,
                  -.7,-.7,.1, 0,0,0,
                   .7,-.7,.1, 0,0,0
                ]);
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            render();
        }
        private function render():void
        {
            //Clear, setting stencil to 0
            renderContext.clear( .3, .3, .3, 1, 1, 0 );
            
            //Draw stencil, incrementing the stencil buffer value
            renderContext.setStencilReferenceValue( 0 );
            renderContext.setStencilActions( Context3DTriangleFace.FRONT_AND_BACK, 
                Context3DCompareMode.EQUAL, Context3DStencilAction.INCREMENT_SATURATE );            
            if( state > 0 ) renderContext.drawTriangles( indexList, 12, 1 );

            //Change stencil action when stencil passes so stencil buffer is not changed
            renderContext.setStencilActions( Context3DTriangleFace.FRONT_AND_BACK, 
                Context3DCompareMode.EQUAL, Context3DStencilAction.KEEP );
            
            //Draw quad -- doesn't draw where stencil has already drawn
            if( state > 1 ) renderContext.drawTriangles( indexList, 0, 2 );
            
            //Change the reference to 1 so this quad only draws into stenciled area
            renderContext.setStencilReferenceValue( 1 );
            if( state > 2 ) renderContext.drawTriangles( indexList, 6, 2 );
            
            //Show the frame
            renderContext.present();
        }
        
        //The rest of the code is for the example UI and timer 
        private function doState( event:TimerEvent ):void
        {
            switch (state)
            {
                case 0:
                    description.text = "Draw triangle with stencil action == increment";
                    state = 1;
                    break;
                case 1:
                    description.text = "Draw the first plane where stencil == 0";
                    state = 2;
                    break;
                case 2:
                    description.text = "Draw second plane where stencil == 1";
                    state = 3;
                    break;
                case 3:
                    description.text = "Clear, setting stencil to 0";
                    state = 0;
                    break;

                default:
                    description.text = "";
                    state = 0;        
            }
            render();
        }

        private var state:int = 3;
        private var stateTimer:Timer = new Timer( 1250 );
        private var description:TextField = new TextField();
        
        private function non3DSetup():void
        {
            //Setup timer to animate the stages of drawing the scene
            stateTimer.addEventListener( TimerEvent.TIMER, doState );
            this.stage.addEventListener( MouseEvent.MOUSE_OVER, function(event:Event):void{stateTimer.start()} );
            this.stage.addEventListener( MouseEvent.MOUSE_OUT, function(event:Event):void{stateTimer.stop()} );
            
            description.height = 30;
            description.width = viewWidth;
            this.addChild( description );
            description.y = viewHeight + 15;
            description.defaultTextFormat = new TextFormat( null, 18, 0xffffff );
            description.text = "Mouse over to view.";
            
            //Allows mouse-over events
            var coverSprite:Sprite = new Sprite();
            coverSprite.graphics.beginFill( 0, .01 )
            coverSprite.graphics.lineTo( stage.stageWidth, 0 );
            coverSprite.graphics.lineTo( stage.stageWidth, stage.stageHeight );
            coverSprite.graphics.lineTo( 0, stage.stageHeight );
            coverSprite.graphics.lineTo( 0, 0 );
            this.addChild( coverSprite );            
        }
    }
}

setStencilReferenceValue

()方法 
public function setStencilReferenceValue(referenceValue:uint, readMask:uint = 255, writeMask:uint = 255):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

設定用於模板測試的模板比較值。

僅使用參考值較低的 8 位元。模板緩衝區值的長度也是 8 位元。使用 readMaskwriteMask 可以將模板緩衝區當做位元欄位使用。

參數

referenceValue:uint — 在參考值比較測試中使用的 8 位元參考值。
 
readMask:uint (default = 255) — 在比較之前同時套用至目前模板緩衝區值和參考值的 8 位元遮色片。
 
writeMask:uint (default = 255) — 在更新模板緩衝區之前套用至參考值的 8 位元遮色片。

相關 API 元素

setTextureAt

()方法 
public function setTextureAt(sampler:int, texture:flash.display3D.textures:TextureBase):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

指定要用於片段程式之紋理輸出暫存器的紋理。

片段程式可以從最多 8 個紋理物件中讀取資訊。使用這個函數,可將 Texture 或 CubeTexture 物件指定給片段程式所使用的其中一個取樣程式暫存器。

注意:如果您要將作用中的片段程式 (使用 setProgram) 變更為使用較少紋理的著色器,請將未使用的暫存器設定為 null

         setTextureAt( 7, null );
         

參數

sampler:int — 取樣程式暫存器索引,值為 0 到 7。
 
texture:flash.display3D.textures:TextureBase — 可供使用的紋理物件,可能是 Texture 或 CubeTexture 實體。

詳細資訊

相關 API 元素

Texture
CubeTexture

setVertexBufferAt

()方法 
public function setVertexBufferAt(index:int, buffer:VertexBuffer3D, bufferOffset:int = 0, format:String = "float4"):void

語言版本: ActionScript 3.0
執行階段版本: Flash Player 11, AIR 3

指定對應至單一頂點著色器程式輸入的頂點資料組件。

使用 setVertexBufferAt 方法,可識別 VertexBuffer3D 緩衝區中為每個頂點定義的哪些資料組件屬於頂點程式的哪些輸入。頂點程式的開發人員可決定每個頂點需要的資料量。資料從 1 或更多的 VertexBuffer3D 串流,對應至頂點著色器程式的屬性暫存器。

頂點著色器耗用的資料之最小單位為 32 位元資料。至頂點串流的偏移量是以 32 位元的倍數指定。

例如,程式設計人員可能會使用下列資料定義每個頂點:
position:  x    float32
           y    float32
           z    float32
color:     r    unsigned byte
           g    unsigned byte
           b    unsigned byte
           a    unsigned byte
假設在一個名為 buffer 的 VertexBuffer3D 物件中定義頂點,則可使用下列程式碼將它指定給頂點著色器:
setVertexBufferAt( 0, buffer, 0, Context3DVertexBufferFormat.FLOAT_3 );   // attribute #0 will contain the position information
setVertexBufferAt( 1, buffer, 3, Context3DVertexBufferFormat.BYTES_4 );    // attribute #1 will contain the color information

參數

index:int — 頂點著色器中屬性暫存器的索引 (0 到 7)。
 
buffer:VertexBuffer3D — 包含要饋送至頂點著色器的來源頂點資料之緩衝區。
 
bufferOffset:int (default = 0) — 單一頂點的資料開頭與開始讀取此屬性的偏移值。在上述範例中,位置資料的偏移值為 0,因為它是第一個屬性;顏色的偏移值為 3,因為顏色屬性遵循 3 個 32 位元位置值。偏移值以 32 位元為單位指定。
 
format:String (default = "float4") — Context3DVertexBufferFormat 類別的值,可指定這個屬性的資料類型。


擲回值
Error — 無效的列舉:格式不是 Context3DVertexBufferFormat 類別中定義的其中一個值。
 
RangeError — 屬性暫存器超出範圍:index 參數不在 0 到 7 的範圍 (著色器最多可以使用 8 個頂點屬性暫存器)。

詳細資訊

相關 API 元素

Context3DExample.as

下列類別會使用透視投影繪製旋轉立方體。
package
{
    import com.adobe.utils.AGALMiniAssembler;
    import com.adobe.utils.PerspectiveMatrix3D;
    
    import flash.display.Sprite;
    import flash.display.Stage3D;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.display3D.Context3D;
    import flash.display3D.Context3DProgramType;
    import flash.display3D.Context3DRenderMode;
    import flash.display3D.Context3DTriangleFace;
    import flash.display3D.Context3DVertexBufferFormat;
    import flash.display3D.IndexBuffer3D;
    import flash.display3D.Program3D;
    import flash.display3D.VertexBuffer3D;
    import flash.events.ErrorEvent;
    import flash.events.Event;
    import flash.geom.Matrix3D;
    import flash.geom.Vector3D;
    
    public class Context3DExample extends Sprite
    {
        public const viewWidth:Number = 320;
        public const viewHeight:Number = 200;
        public const zNear:Number = 1;
        public const zFar:Number = 500;
        
        public const fov:Number = 45;
        
        private var stage3D:Stage3D;
        private var renderContext:Context3D;
        private var indexList:IndexBuffer3D;
        private var vertexes:VertexBuffer3D;
        
        private var projection:PerspectiveMatrix3D = new PerspectiveMatrix3D();
        private var model:Matrix3D = new Matrix3D();
        private var view:Matrix3D = new Matrix3D();
        private var finalTransform:Matrix3D = new Matrix3D();
        
        //For rotating the cube
        private const pivot:Vector3D = new Vector3D();
        
        private const VERTEX_SHADER:String =
            "m44 op, va0, vc0    \n" +    // 4x4 matrix transform 
            "mov v0, va1"; //copy color to varying variable v0
        
        private const FRAGMENT_SHADER:String = 
            "mov oc, v0"; //Set the output color to the value interpolated from the three triangle vertices 

        private var vertexAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var fragmentAssembly:AGALMiniAssembler = new AGALMiniAssembler();
        private var programPair:Program3D;
        
        public function Context3DExample()
        {
            this.stage.scaleMode = StageScaleMode.NO_SCALE;
            this.stage.align = StageAlign.TOP_LEFT;
            this.stage.nativeWindow.activate(); //AIR only
                         
            stage3D = this.stage.stage3Ds[0];
            stage3D.x = 10;
            stage3D.y = 10;

            //Add event listener before requesting the context
            stage3D.addEventListener( Event.CONTEXT3D_CREATE, contextCreated );
            stage3D.addEventListener( ErrorEvent.ERROR, contextCreationError );
            stage3D.requestContext3D( Context3DRenderMode.AUTO );
            
            //Compile shaders
            vertexAssembly.assemble( Context3DProgramType.VERTEX, VERTEX_SHADER, false );
            fragmentAssembly.assemble( Context3DProgramType.FRAGMENT, FRAGMENT_SHADER, false );            
        }
        
        //Note, context3DCreate event can happen at any time, such as when the hardware resources are taken by another process
        private function contextCreated( event:Event ):void
        {
                renderContext = Stage3D( event.target ).context3D;
                trace( "3D driver: " + renderContext.driverInfo );
                setupScene();
        }
        
        private function setupScene():void
        {
            renderContext.enableErrorChecking = true; //Can slow rendering - only turn on when developing/testing
            renderContext.configureBackBuffer( viewWidth, viewHeight, 2, false );
            renderContext.setCulling( Context3DTriangleFace.BACK );
            
            //Create vertex index list for the triangles forming a cube
            var triangles:Vector.<uint> = Vector.<uint>( [ 
                2,1,0, //front face
                3,2,0,
                4,7,5, //bottom face
                7,6,5,
                8,11,9, //back face
                9,11,10,
                12,15,13, //top face
                13,15,14,
                16,19,17, //left face
                17,19,18,
                20,23,21, //right face
                21,23,22
            ] );
            indexList = renderContext.createIndexBuffer( triangles.length );
            indexList.uploadFromVector( triangles, 0, triangles.length );
            
            //Create vertexes - cube faces do not share vertexes
            const dataPerVertex:int = 6;
            var vertexData:Vector.<Number> = Vector.<Number>(
                [
                    // x,y,z r,g,b format
                    0,0,0, 1,0,0, //front face
                    0,1,0, 1,0,0,
                    1,1,0, 1,0,0,
                    1,0,0, 1,0,0,
                    
                    0,0,0, 0,1,0, //bottom face
                    1,0,0, 0,1,0,
                    1,0,1, 0,1,0,
                    0,0,1, 0,1,0,
                    
                    0,0,1, 1,0,0, //back face
                    1,0,1, 1,0,0,
                    1,1,1, 1,0,0,
                    0,1,1, 1,0,0,
                    
                    0,1,1, 0,1,0, //top face
                    1,1,1, 0,1,0,
                    1,1,0, 0,1,0,
                    0,1,0, 0,1,0,
                    
                    0,1,1, 0,0,1, //left face
                    0,1,0, 0,0,1,
                    0,0,0, 0,0,1,
                    0,0,1, 0,0,1,
                    
                    1,1,0, 0,0,1, //right face
                    1,1,1, 0,0,1,
                    1,0,1, 0,0,1,
                    1,0,0, 0,0,1
                ]
            );
            vertexes = renderContext.createVertexBuffer( vertexData.length/dataPerVertex, dataPerVertex );
            vertexes.uploadFromVector( vertexData, 0, vertexData.length/dataPerVertex );
            
            //Identify vertex data inputs for vertex program
            renderContext.setVertexBufferAt( 0, vertexes, 0, Context3DVertexBufferFormat.FLOAT_3 ); //va0 is position
            renderContext.setVertexBufferAt( 1, vertexes, 3, Context3DVertexBufferFormat.FLOAT_3 ); //va1 is color
            
            //Upload programs to render context
            programPair = renderContext.createProgram();
            programPair.upload( vertexAssembly.agalcode, fragmentAssembly.agalcode );
            renderContext.setProgram( programPair );
            
            //Set up 3D transforms
            projection.perspectiveFieldOfViewRH( fov, viewWidth/viewHeight, zNear, zFar );            
            view.appendTranslation( 0, 0, -2 );    //Move view back
            model.appendTranslation( -.5, -.5, -.5 ); //center cube on origin
            this.stage.addEventListener( Event.ENTER_FRAME, render );
        }
        
        private function render( event:Event ):void
        {
            //Rotate model on each frame
            model.appendRotation( .5, Vector3D.Z_AXIS, pivot );
            model.appendRotation( .5, Vector3D.Y_AXIS, pivot );
            model.appendRotation( .5, Vector3D.X_AXIS, pivot );
            
            //Combine transforms
            finalTransform.identity();
            finalTransform.append( model );
            finalTransform.append( view );
            finalTransform.append( projection );
            
            //Pass the final transform to the vertex shader as program constant, vc0
            renderContext.setProgramConstantsFromMatrix( Context3DProgramType.VERTEX, 0, finalTransform, true );
            
            //Clear is required before drawTriangles on each frame
            renderContext.clear( .3,.3,.3 );
            
            //Draw the 12 triangles that make up the cube
            renderContext.drawTriangles( indexList, 0, 12 );
            
            //Show the frame
            renderContext.present();
        }
        
        private function contextCreationError( error:ErrorEvent ):void
        {
            trace( error.errorID + ": " + error.text );
        }
    }
}




[ X ]為什麼顯示英文?
「ActionScript 3.0 參考」的內容是以英文顯示

並非所有「ActionScript 3.0 參考」的內容都翻譯為所有語言。當語言元素未翻譯時,就會以英文顯示。例如,ga.controls.HelpBox 類別並沒有翻譯為任何語言。因此在參考的繁體中文版本中,ga.controls.HelpBox 類別就會以英文顯示。