Context3D - Adobe ActionScript® 3 (AS3 ) API 参考

包	flash.display3D
类	public final class Context3D
继承	Context3D EventDispatcher 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 实例的 x 和 y 属性指定舞台上渲染区域的位置。

若要呈现并显示某个场景（在获取 Context3D 对象后），下面是典型的步骤：

通过调用 configureBackBuffer() 来配置主显示缓冲区属性。
创建并初始化您的呈现资源，包括：
- 定义场景几何的顶点和索引缓冲区
- 用于呈现场景的顶点和像素程序（着色器）
- 纹理
呈现帧：
- 为场景中的一个对象或一组对象设置适当的呈现状态。
- 调用 drawTriangles() 方法可以呈现一组三角形。
- 更改下一组对象的呈现状态。
- 调用 drawTriangles() 可以绘制定义对象的三角形。
- 重复直至场景全部呈现。
- 调用 present() 方法可以在舞台上显示呈现的场景。

下列限制适用于呈现：

资源限制：

资源	允许的数量	总内存
`Vertex buffers`	4096	256 MB
`Index buffers`	4096	128 MB
`Programs`	4096	16 MB
`Textures`	4096	128 MB
`Cube textures`	4096	256 MB

AGAL 限制：每个程序 200 个 opcode。

绘制调用限制：每个 present() 调用 32,768 个 drawTriangles() 调用。

下列限制适用于纹理：

AIR 32 位的纹理限制：

纹理	最大大小	GPU 总内存
`常规纹理（扩展基准以下）`	2048 x 2048	512 MB
`常规纹理（扩展基准和扩展基准以上）`	4096 x 4096	512 MB
`矩形纹理（扩展基准以下）`	2048 x 2048	512 MB
`矩形纹理（扩展基准和扩展基准以上）`	4096 x 4096	512 MB
`立方体纹理`	1024 x 1024	256 MB

针对 AIR 64 位的纹理限制（桌面）

纹理	最大大小	GPU 总内存
`常规纹理（扩展基准以下）`	2048 x 2048	512 MB
`法线纹理（基线已扩展为标准)`	4096 x 4096	512 MB
`法线纹理（已扩展标准或高于标准）`	4096 x 4096	2048 MB
`矩形纹理（扩展基准以下）`	2048 x 2048	512 MB
`矩形纹理（基线已扩展为标准)`	4096 x 4096	512 MB
`矩形纹理（已扩展标准或高于标准）`	4096 x 4096	2048 MB
`立方体纹理`	1024 x 1024	256 MB

512 MB 是纹理的绝对限制，包括 mipmap 所需的纹理内存。但对于立方体纹理，内存限制为 256 MB。

您无法使用 Context3D 构造函数创建 Context3D 对象。它是作为 Stage3D 实例的属性构建并提供的。Context3D 类可用于桌面和移动平台，在 Flash Player 和 AIR 中运行时都适用。

查看示例

公共属性

隐藏继承的公共属性

显示继承的公共属性

	属性		由以下参数定义
		backBufferHeight : int [只读] 指定后台缓冲区的高度，可以通过成功调用 configureBackBuffer() 方法来更改。	Context3D
		backBufferWidth : int [只读] 指定后台缓冲区的宽度，可以通过成功调用 configureBackBuffer() 方法来更改。	Context3D
		constructor : 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

公共方法

隐藏继承的公共方法

显示继承的公共方法

	方法		由以下参数定义
		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
		createProgram():Program3D 创建 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
		createVideoTexture():flash.display3D.textures:VideoTexture 创建 VideoTexture 对象。	Context3D
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	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
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	EventDispatcher
		hasOwnProperty(name:String):Boolean 表示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 表示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		present():void 显示后台渲染缓冲区。	Context3D
		propertyIsEnumerable(name:String):Boolean 表示指定的属性是否存在、是否可枚举。	Object
		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
		setProgram(program:Program3D):void 设置用于后续渲染的顶点和片段着色器程序。	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
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		setRenderToBackBuffer():void 将后台渲染缓冲区设置为渲染目标。	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
		setScissorRectangle(rectangle:Rectangle):void 设置一个裁剪矩形，绘制遮罩的类型。	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
		setTextureAt(sampler:int, texture:flash.display3D.textures:TextureBase):void 指定要为片段程序的纹理输入寄存器使用的纹理。	Context3D
		setVertexBufferAt(index:int, buffer:VertexBuffer3D, bufferOffset:int = 0, format:String = "float4"):void 指定与单个着色器程序输入相对应的顶点数据组件。	Context3D
		toLocaleString():String 返回此对象的字符串表示形式，其格式设置遵守区域设置特定的约定。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		valueOf():Object 返回指定对象的原始值。	Object
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何祖代为指定事件类型注册了事件侦听器。	EventDispatcher

事件

单击此处了解有关事件的更多信息

隐藏继承的事件

显示继承的事件

	事件		摘要	由以下参数定义
		activate	[广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。	EventDispatcher
		deactivate	[广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。	EventDispatcher

属性详细信息

backBufferHeight

属性

backBufferHeight:int [只读]

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 15, AIR 15

指定后台缓冲区的高度，可以通过成功调用 configureBackBuffer() 方法来更改。在最后成功调用 configureBackBuffer() 方法时，如果 wantsBestResolutionOnBrowserZoom 设置为 true，则浏览器缩放系数变化时，高度可能会发生更改。高度的更改可以通过对浏览器缩放系数更改事件注册一个事件侦听器来加以检测。

实现
public function get backBufferHeight():int

backBufferWidth

属性

backBufferWidth:int [只读]

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 15, AIR 15

指定后台缓冲区的宽度，可以通过成功调用 configureBackBuffer() 方法来更改。在最后成功调用 configureBackBuffer 方法时，如果 wantsBestResolutionOnBrowserZoom 设置为 true，则浏览器缩放系数变化时，宽度可能会发生更改。宽度的更改可以通过对浏览器缩放系数更改事件注册一个事件侦听器来加以检测。

实现
public function get backBufferWidth():int

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

实现
public function get driverInfo():String

enableErrorChecking

属性

enableErrorChecking:Boolean

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 11, AIR 3

指定渲染器遇到的错误是否报告给应用程序。

当 enableErrorChecking 为 true 时，clear() 和 drawTriangles() 方法处于同步状态，可能会引发错误。当 enableErrorChecking 为 false 时，default、clear() 和 drawTriangles() 方法处于异步状态，不会报告这些错误。启用错误检查会降低呈现性能。您仅应在调试时启用错误检查。

实现
public function get enableErrorChecking():Boolean
public function set enableErrorChecking(value:Boolean):void

相关 API 元素

clear()
drawTriangles()

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 元素

Context3DProfile

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）。当渲染到后台缓冲区时，必须在调用任何 clear() 之前调用 configureBackBuffer() 方法。

注意：如果指定的参数值超出允许范围，则 Numeric 参数值将被锁定到范围 0 到 1 且不会显示任何提示。同样，如果 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 元素

Context3DClearMask

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() 方法时，后台缓冲区与可见的前台缓冲区交换。缓冲区的最小大小为 32 x 32 像素。后台缓冲区的最大大小受到设备能力的限制，也可以由用户通过 maxBackBufferWidth 和 maxBackBufferHeight 属性进行设置。配置缓冲区是一个缓慢的操作。在正常渲染操作期间，请避免更改缓冲区大小或属性。

参数

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。可设置 maxBackBufferWidth 和 maxBackBufferHeight 属性来限制后台缓冲区大小的增加。可使用 backBufferWidth 和 backBufferHeight 确定后台缓冲区的当前大小。

引发

	`Error` — 对象已处置：此 Context3D 对象已通过调用 `dispose()` 进行处置，或已失去基础渲染硬件。

	`Error` — 输入大小错误：width 或 height 参数小于允许的后置缓冲区最小大小或大于允许的后置缓冲区最大大小。

	`Error` — 3709：应用程序描述符中的 `depthAndStencil` 标记必须匹配传递到 Context3D 对象上 `configureBackBuffer()` 的 `enableDepthAndStencil` 布尔值。

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 对象将立方体纹理位图上载到渲染上下文，并在渲染期间引用立方体纹理。立方体纹理由 6 个大小相等的正方形纹理组成，采用立方拓扑结构排列，可用于描述环境映射。

您无法使用 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。在加载了 8x8 像素的图像后，将此属性设置为 3 以呈现图像。注意：将此属性设置为大于 0 的值会影响内存使用和性能。

flash.display3D.textures:CubeTexture

引发

	`Error` — 对象已处置：此 Context3D 对象已通过调用 `dispose()` 进行处置，或已失去基础渲染硬件。

	`Error` — 超过资源限制：如果创建了过多纹理对象，或超出分配给纹理的内存数量。

	`ArgumentError` — 未实现深度纹理：如果您试图创建深度纹理。

	`ArgumentError` — 纹理大小为零：如果 `size` 参数不大于零。

	`ArgumentError` — 纹理不是 2 的幂数：如果 `size` 参数不是 2 的幂数。

	`ArgumentError` — 纹理太大：如果 `size` 参数大于 1024。

	`Error` — 纹理创建失败：如果渲染上下文无法创建 CubeTexture 对象（但是与原因有关的信息不可用）。

	`ArgumentError` — 无效的流级别：如果 `streamingLevels` 大于或等于 log2(size)。

createIndexBuffer

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 11, AIR 3

创建 IndexBuffer3D 对象。

使用 IndexBuffer3D 对象将一组三角形索引上载到渲染上下文，并在渲染时引用这组索引。索引缓冲区中的每个索引引用顶点缓冲区中一个相对应的顶点。由 3 个索引组成的每一组索引标识一个三角形。将 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 元素

IndexBuffer3D

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 元素

Program3D
Program3D.upload()

示例 ( 如何使用本示例 )

此示例说明如何向渲染上下文创建、上载并激活一对顶点和像素程序。请注意对象 renderContext 是 Context3D 类的实例。此示例中的程序是使用 Adobe 图形汇编语言 (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 对象。

使用 Rectangle Texture 对象将纹理位图上载到渲染上下文，并在渲染期间引用纹理。

您无法使用 Rectangle Texture 构造函数创建 Rectangle Texture 对象；请改用此方法。创建 RectangleTexture 对象后，请使用 Texture uploadFromBitmapData() 或 uploadFromByteArray() 方法上载纹理位图。

请注意，32 位整数纹理采用打包 BGRA 格式存储，以便与 Flash BitmapData 格式匹配。浮点纹理采用常规 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` — 超过资源限制：如果创建了过多纹理对象，或超出分配给纹理的内存数量。

	`ArgumentError` — 纹理大小为零：如果 `width` 或 `height` 参数小于等于零。

	`ArgumentError` — 纹理太大：如果 `width` 或 `height` 参数大于 2048。

	`Error` — 纹理创建失败：如果渲染上下文无法创建 Texture 对象（但是与原因有关的信息不可用）。

	`Error` — 需要基准配置文件或更高版本：如果矩形纹理是使用限定基准的配置文件创建的。

相关 API 元素

Context3DTextureFormat

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() 方法上载纹理位图。

请注意，32 位整数纹理采用打包 BGRA 格式存储，以便与 Flash BitmapData 格式匹配。浮点纹理采用常规 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。在加载了 8x8 像素的图像后，将此属性设置为 3 以呈现图像。注意：将此属性设置为大于 0 的值会影响内存使用和性能。

flash.display3D.textures:Texture

引发

	`Error` — 对象已处置：此 Context3D 对象已通过调用 `dispose()` 进行处置，或已失去基础渲染硬件。

	`Error` — 超过资源限制：如果创建了过多纹理对象，或超出分配给纹理的内存数量。

	`ArgumentError` — 未实现深度纹理：如果您试图创建深度纹理。

	`ArgumentError` — 纹理大小为零：如果 `width` 或 `height` 参数小于零或等于零。

	`ArgumentError` — 纹理不是 2 的幂数：如果 `width` 和 `height` 参数不是 2 的幂数。

	`ArgumentError` — 纹理太大：对于基准和限定基准的配置文件，如果 `width` 或 `height` 参数大于 2048；对于基准扩展和更高基准的配置文件，如果 `width` 或 `height` 参数大于 4096。

	`Error` — 纹理创建失败：如果渲染上下文无法创建 Texture 对象（但是与原因有关的信息不可用）。

	`ArgumentError` — 无效的流级别：如果 `streamingLevels` 大于或等于 log2(min(width,height))。

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 元素

VertexBuffer3D
setVertexBufferAt()

示例 ( 如何使用本示例 )

下面的示例说明如何创建和加载顶点数据缓冲区。此示例中的缓冲区为每个顶点包含两种数据类型：位置，表示为 x、y、z 坐标；颜色，表示为 rgb 组件。创建顶点缓冲区后，该示例调用 setVertexBufferAt() 方法以指定前三个数据点作为 va0 中的 3 个浮点值传递到顶点程序，后三个数据点作为 va1 中的 3 个浮点值传递到顶点程序。顶点程序最多可以有 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 位值。

参数

	`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` — 每元素实例数无效：如果 instancesPerElement 不大于零。

相关 API 元素

VertexBuffer3D
setVertexBufferAt()

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 不包含 mipmap。如果将 VideoTexture 与一个使用 mipmap 过滤或重复环绕的取样器一起使用，则 drawTriangles 调用将会失败。可将 VideoTexture 视为着色器使用的 BGRA 纹理。如果是使用软件渲染模式请求 Context3D 的，则试图实例化 VideoTexture 对象将失败。

每个 Context3D 实例最多 4 个 VideoTexture 对象。在移动设备上，由于平台的限制，支持的 VideoTexture 对象实际数目可能少于 4。

flash.display3D.textures:VideoTexture

引发

	`Error` — 对象已处置：此 Context3D 对象已通过调用 `dispose()` 进行处置，或已失去基础渲染硬件。

	`Error` — 超过资源限制：如果创建了过多纹理对象，或超出分配给纹理的内存数量。

	`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() 将模拟设备丢失。它将在 Stage3D 上创建一个新 Context3D，并再次发出 Events.CONTEXT3D_CREATE 事件。如果这不是希望的结果，可在调用 dispose() 之前删除 Stage3D 对象的事件侦听器，或将 recreate 参数设置为 false。

参数

recreate:Boolean (default = true)

相关 API 元素

Stage3D
flash.display.Stage3D

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)，则 BitmapData 对象中存储的像素应具有以下 rgba 值：(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:Point` 或 `srcRect:Rectangle` 中的任意一个超出位图/stage3D 坐标边界，或者如果 non-Numeric(NaN) 值作为输入传递。

示例 ( 如何使用本示例 )

下面的示例同时向常规渲染缓冲区和 BitmapData 对象呈现两个三角形。使用添加到正常显示列表的 Bitmap 对象，可以显示 BitmapData 对象。投影滤镜会应用到位图呈现。

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() 方法，否则渲染将失败。

当 enableErrorChecking 为 false 时，此函数会立即返回值，无需等待结果，仅在此 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` — 相同的纹理需要相同的取样器参数：如果纹理用于多个取样器寄存器，则所有取样器必须具有相同的设置。例如，您无法将一个取样器设置为锁定并将另一个设置为环绕。

	`Error` — 纹理已绑定但未使用：纹理已设置为着色器输入，但未使用。

	`Error` — 流未使用：顶点缓冲区分配给了顶点属性输入，但顶点程序未引用相应的寄存器。

	`Error` — 流无效：分配给顶点程序输入的 VertexBuffer3D 对象不是有效的对象。

	`RangeError` — 流没有足够的顶点：用于为绘制指定三角形提供数据的顶点缓冲区没有足够的数据。

	`RangeError` — 流顶点偏移量超出边界：`setVertexBufferAt()` 调用中指定的偏移量为负或超过了缓冲区的末尾。

	`Error` — 流已读取但未设置：当前顶点程序使用的一个顶点属性未设置（使用 `setVertexBufferAt()`）。

示例 ( 如何使用本示例 )

下面的类向舞台上的 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 以及当前的混合模式。渲染目标可以是主渲染缓冲区或纹理。

在调用 present() 方法之前，渲染的实例化三角形将不会在视口中显示。每次调用 present() 之后，必须在首次调用 drawTrianglesInstanced() 之前调用 clear() 方法，否则渲染将失败。

如果实例化缓冲区不恰当地使用 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` — 如果使用负的 numInstances 调用此方法。以下错误仅当 `enableErrorChecking` 属性为 `true` 时引发：

	`Error` — 需要在绘制前清除：如果缓冲区从上一次 `present()` 调用后未曾清除。

	`Error` — 如果未设置有效的 Program3D 对象。

	`Error` — 未设置有效的索引缓冲区：如果未设置 IndexBuffer3D 对象。

	`Error` — 参数完整性检查失败：当要绘制的三角形数量或 `firstIndex` 超出了允许值时。

	`RangeError` — 此缓冲区中没有足够的索引：当缓冲区内没有足够的索引来定义要绘制的三角形数量时。

	`Error` — 样本绑定的纹理也绑定到渲染：当渲染目标为纹理，并且该纹理已分配给当前片段程序的纹理输入时。

	`Error` — 样本绑定了无效的纹理：将无效的纹理指定为当前片段程序的输入。

	`Error` — 取样器格式与纹理格式不匹配：当分配为当前片段程序输入的纹理与取样器寄存器所指定的格式不同时。例如，将 2D 纹理分配给立方体纹理取样器。

	`Error` — 样本绑定了未定义的纹理：当前片段程序访问了未设置的纹理寄存器（使用 `setTextureAt()`）。

	`Error` — 相同的纹理需要相同的取样器参数：如果纹理用于多个取样器寄存器，则所有取样器必须具有相同的设置。例如，您无法将一个取样器设置为锁定并将另一个设置为环绕。

	`Error` — 纹理已绑定但未使用：纹理已设置为着色器输入，但未使用。

	`Error` — 流未使用：顶点缓冲区分配给了顶点属性输入，但顶点程序未引用相应的寄存器。

	`Error` — 流无效：分配给顶点程序输入的 VertexBuffer3D 对象不是有效的对象。

	`RangeError` — 流没有足够的顶点：用于为绘制指定三角形提供数据的顶点缓冲区没有足够的数据。

	`RangeError` — 流顶点偏移量超出边界：`setVertexBufferAt()` 调用中指定的偏移量为负或超过了缓冲区的末尾。

	`Error` — 流已读取但未设置：当前顶点程序使用的一个顶点属性未设置（使用 `setVertexBufferAt()`）。

	`Error` — 顶点缓冲区流对实例未包含足够的元素：如果顶点缓冲区流对实例数未包含足够的元素。

	`Error` — 使用最小索引属性寄存器不恰当地设置了实例的顶点缓冲区流：如果用 `CreateVertexBuffer()` 生成的顶点缓冲区被指定一个更大的索引号，大于用 `CreateVertexBufferForInstance()` 生成的顶点缓冲区对应的索引号。

示例 ( 如何使用本示例 )

下面这个类将使用一个单独的绘制调用而不是多个绘制调用来绘制三个使用功能实例化绘图的三角形。

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 之后，必须在调用另一个 drawTriangles() 之前调用 clear()。否则，此函数会将渲染缓冲区清除为黄色和绿色，或在 enableErrorChecking 设置为 true 的情况下，将引发错误。

与调用 setRenderToBackBuffer() 相同，调用 present() 也会重置渲染目标。

引发

	`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.ONE 和 destinationFactor = Context3DBlendFactor.ZERO，这会导致源颜色覆盖目标颜色（也就是说，不会发生两种颜色混合）。对于正常 alpha 混合，请使用 sourceFactor = Context3DBlendFactor.SOURCE_ALPHA 和 destinationFactor = Context3DBlendFactor.ONE_MINUS_SOURCE_ALPHA。

使用 Context3DBlendFactor 类中定义的常量设置此函数的参数。

参数

	`sourceFactor:String` — 用于与源颜色相乘的系数。默认为 `Context3DBlendFactor.ONE`。

	`destinationFactor:String` — 用于与目标颜色相乘的系数。默认为 `Context3DBlendFactor.ZERO`。

引发

Error — 无效的枚举：当 sourceFactor 或 destinationFactor 不是 Context3DBlendFactor 类中定义的识别值之一时。

相关 API 元素

Context3DBlendFactor

示例 ( 如何使用本示例 )

下面的类说明了不同的混合系数。该示例向渲染缓冲区绘制了四个不同颜色的矩形。此矩形集是混合“目标”。接下来，会设置源和目标混合模式，绘制一个大的矩形作为混合“源”。使用“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 元素

Context3DTriangleFace

setDepthTest

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 11, AIR 3

设置用于深度测试的比较类型。

像素着色器程序的源像素输出的深度将与深度缓冲区中的当前值进行比较。如果比较计算结果为 false，则丢弃源像素。如果为 true，则呈现管道中的下一步“印模测试”将处理源像素。此外，只要 depthMask 参数设置为 true，就会使用源像素的深度更新深度缓冲区。

设置用于比较源像素和目标像素的深度值的测试。当比较为 true 时，源像素与目标像素合成。将比较运算符按该顺序作为源像素值和目标像素值之间的中缀运算符应用。

参数

	`depthMask:Boolean` — 为 true 时，将从源像素更新目标深度值。

	`passCompareMode:String` — 深度比较测试操作。一个 Context3DCompareMode 值。

相关 API 元素

Context3DCompareMode

setFillMode

()

方法

public function setFillMode(fillMode:String):void

语言版本:

ActionScript 3.0

运行时版本:

AIR 16

设置用于渲染的填充模式。此接口仅在 AIR 桌面中可用。

参数

fillMode:String — 如果值为 WIREFRAME，则对象将显示为网格线。如果值为 SOLID，则对象将显示为实心阴影多边形。

相关 API 元素

Context3DFillMode

setProgram

()

方法

public function setProgram(program:Program3D):void

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 11, AIR 3

设置用于后续渲染的顶点和片段着色器程序。

参数

program:Program3D — Program3D 对象表示要使用的顶点和片段程序。

相关 API 元素

drawTriangles()
Program3D

示例 ( 如何使用本示例 )

//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` — kNullPointerError，当 `data` 为 null 时。

	`RangeError` — kConstantRegisterOutOfBounds，当尝试设置的着色器常量的数量超过最大数量时。

	`RangeError` — 如果 `byteArrayOffset` 大于或等于 `data` 的长度，或者如果 `data` - `byteArrayOffset` 中没有元素小于 `numRegisters`*16，则为 kBadInputSize

相关 API 元素

Context3DProgramType

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.VERTEX` 或 `Context3DProgramType.FRAGMENT`。

	`firstRegister:int` — 要设置的首个常量寄存器的索引。由于 Matrix3D 具有 16 个值，因此要设置 4 个寄存器。

	`matrix:Matrix3D` — 包含常量值的矩阵。

	`transposedMatrix:Boolean` (default = `false`) — 如果为 `true`，则将按颠倒顺序将矩阵条目复制到寄存器中。默认值为 `false`。

引发

	`TypeError` — Null 指针错误：当 `matrix` 为 null 时。

	`RangeError` — 常量寄存器超出边界：当尝试设置超出最大数量的着色器常量寄存器时。

了解详细信息

http://www.adobe.com/go/learn_as3_agal_bytecode_cn

相关 API 元素

Context3DProgramType

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）组成。因此，每个寄存器都要求数据 Vector 中有 4 个条目。可以为顶点程序和片段程序设置的寄存器数量取决于 Context3DProfile。

参数

	`programType:String` — 着色器程序类型，`Context3DProgramType.VERTEX` 或 `Context3DProgramType.FRAGMENT`。

	`firstRegister:int` — 要设置的首个常量寄存器的索引。

	`data:Vector.<Number>` — 浮点常量值。`data` 中至少有 `numRegisters` 4 个元素。

	`numRegisters:int` (default = `-1`) — 要设置的常量数量。指定 -1（默认值），设置足够的寄存器以使用所有可用数据。

引发

	`TypeError` — Null 指针错误：当 `data` 为 `null` 时。

	`RangeError` — 常量寄存器超出边界：当尝试设置超出最大数量的着色器常量寄存器时。

	`RangeError` — 输入大小错误：当 `data` 中的元素数大于 `numRegisters`*4 时

了解详细信息

http://www.adobe.com/go/learn_as3_agal_bytecode_cn

相关 API 元素

Context3DProgramType

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() 方法的后续调用会更新指定纹理而不是后台缓冲区。将自动创建 mipmap。使用 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`) — 指定要更新的纹理元素：纹理对象具有一个表面，因此您必须指定 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`。

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` — 环绕、滤镜、mipfilter 枚举错误

	`Error` — 对象已处置：已通过调用 `dispose()` 处置此 Context3D 对象，或由于已丢失基础渲染硬件。

setScissorRectangle

()

方法

public function setScissorRectangle(rectangle:Rectangle):void

语言版本:

ActionScript 3.0

运行时版本:

Flash Player 11, AIR 3

设置一个裁剪矩形，绘制遮罩的类型。渲染器仅绘制到裁剪矩形内部的区域。裁剪不影响清除操作。

传递 null 以关闭裁剪。

参数

rectangle:Rectangle — 要在其中绘制的矩形。指定矩形的位置和尺寸（以像素为单位）。坐标系统原点为视口的左上角，向下和向右为递增的正值（与正常 Flash 显示坐标系统相同）。

示例 ( 如何使用本示例 )

下面的类会将两个三角形绘制到舞台上的 640x480 像素视图端口。这些三角形共享一个顶点，该顶点位于原点 (0,0,0)。

在此示例中，不会执行 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`") — 用于比较当前印模引用值和目标像素印模值的测试运算符。当比较结果为 true 时，会执行目标像素颜色和深度更新。根据下面操作参数中的请求执行印模操作。将比较运算符按该顺序作为当前引用值和目标引用值之间的中缀运算符应用（以伪代码表示：`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` — 无效枚举错误：当 `actionOnBothPass`、`actionOnDepthFail` 或 `actionOnDepthPassStencilFail` 不是 Context3DStencilAction 类中定义的值之一时。

示例 ( 如何使用本示例 )

下面的类说明如何绘制印模，并将其用作后续绘制操作的遮罩。此示例执行下列步骤：

将印模缓冲区清除为 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 位。使用 readMask 和 writeMask 来将印模缓冲区用作位域。

参数

	`referenceValue:uint` — 一个 8 位引用值，用于引用值比较测试中。

	`readMask:uint` (default = `255`) — 一个 8 位遮罩，在进行比较前应用于当前印模缓冲区值和引用值。

	`writeMask:uint` (default = `255`) — 一个 8 位遮罩，在更新印模缓冲区之前应用于引用值。

相关 API 元素

setStencilActions()

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 实例。

了解详细信息

http://www.adobe.com/go/learn_as3_agal_bytecode_cn

相关 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

假定在 VertexBuffer3D 对象中定义了名为 buffer 的对象，则可使用以下代码将其分配给顶点着色器：

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 个顶点属性寄存器。）

了解详细信息

http://www.adobe.com/go/learn_as3_agal_bytecode_cn

示例如何使用本示例

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 );
        }
    }
}

法律声明 | 在线隐私策略

Context3D - AS3

包x

语言元素

附录

包 flash.display3D

backBufferHeight

backBufferWidth

driverInfo

enableErrorChecking

maxBackBufferHeight

maxBackBufferWidth

profile

supportsVideoTexture

totalGPUMemory

clear

configureBackBuffer

createCubeTexture

createIndexBuffer

createProgram

createRectangleTexture

createTexture

createVertexBuffer

createVertexBufferForInstances

createVideoTexture

dispose

drawToBitmapData

drawTriangles

drawTrianglesInstanced

present

setBlendFactors

setColorMask

setCulling

setDepthTest

setFillMode

setProgram

setProgramConstantsFromByteArray

setProgramConstantsFromMatrix

setProgramConstantsFromVector

setRenderToBackBuffer

setRenderToTexture

setSamplerStateAt

setScissorRectangle

setStencilActions

setStencilReferenceValue

setTextureAt

setVertexBufferAt