| 包 | flash.display3D |
| 类 | public final class Program3D |
| 继承 | Program3D  Object |
| 语言版本: | ActionScript 3.0 |
| 运行时版本: | Flash Player 11, AIR 2 |
由 Program3D 对象管理的程序控制 drawTriangles 调用期间的整个三角形渲染。使用 upload 方法将二进制字节码上载到渲染上下文。（上载完成后，将不再引用原始字节数组中的数据；更改或放弃源字节数组不会更改该程序。）
这些程序始终由两个相互关联的部分组成：顶点程序和片段程序。
- 顶点程序会操作 VertexBuffer3D 中定义的数据，负责将顶点投影到剪辑空间，并将任何所需的顶点数据（例如颜色）传递到片段着色器。
- 片段着色器会操作顶点程序传递给它的属性，并为三角形的每个栅格化片段生成颜色，最终形成像素颜色。请注意，片段程序在 3D 编程文献中具有多个名称，包括片段着色器和像素着色器。
通过将相应 Program3D 实例传递到 Context3D setProgram() 方法，指定后续渲染操作要使用的程序对。
您无法直接创建 Program3D 对象；请改用 Context3D createProgram() 方法。
相关 API 元素
隐藏继承的公共属性
显示继承的公共属性| 方法 | 由以下参数定义 | ||
|---|---|---|---|
释放与此对象相关联的所有资源。 | Program3D | ||
 |
表示对象是否已经定义了指定的属性。 | Object | |
|
表示 Object 类的实例是否在指定为参数的对象的原型链中。 | Object | |
|
表示指定的属性是否存在、是否可枚举。 | Object | |
|
设置循环操作动态属性的可用性。 | Object | |
|
返回此对象的字符串表示形式，其格式设置遵守区域设置特定的约定。 | Object | |
|
返回指定对象的字符串表示形式。 | Object | |
上载以 AGAL（Adobe 图形汇编语言）字节码表示的一对渲染程序。 | Program3D | ||
|
返回指定对象的原始值。 | Object | |
dispose | () | 方法 |
public function dispose():void| 语言版本: | ActionScript 3.0 |
| 运行时版本: | Flash Player 11, AIR 3 |
释放与此对象相关联的所有资源。处置 Program3D 对象后，使用此对象调用 upload() 和渲染将失败。
upload | () | 方法 |
public function upload(vertexProgram:ByteArray, fragmentProgram:ByteArray):void| 语言版本: | ActionScript 3.0 |
| 运行时版本: | Flash Player 11, AIR 3 |
上载以 AGAL（Adobe 图形汇编语言）字节码表示的一对渲染程序。
使用 Pixel Bender 3D 脱机工具可创建程序字节码，也可动态创建。AGALMiniAssembler 类是用于将 AGAL 汇编语言程序编译为 AGAL 字节码的实用工具类。该类不是运行时的一部分。当您上载着色器程序时，字节码将编译为当前设备的本机着色器语言（例如，OpenGL 或 Direct3D）。运行时会在上载时验证字节码。
程序会在每次调用 Context3D drawTriangles() 方法时运行。顶点程序会为要绘制的三角形列表中的每个顶点执行一次。片段程序会为三角形表面的每个像素执行一次。
着色器程序使用的“变量”称为寄存器。定义了以下寄存器：
| 名称 | 每个片段程序的数量 | 每个顶点程序的数量 | 目的 |
|---|---|---|---|
| 属性 | 无 | 8 | 顶点着色器输入；读取自使用 Context3D.setVertexBufferAt() 指定的顶点缓冲区。 |
| 常量 | 28 | 128 | 着色器输入；使用 Context3D.setProgramConstants() 系列函数设置。 |
| 临时 | 8 | 8 | 用于计算的临时寄存器，无法从程序外部访问。 |
| 输出 | 1 | 1 | 着色器输出：在顶点程序中，输出为剪辑空间位置；在片段程序中，输出为颜色。 |
| 渐变 | 8 | 8 | 在顶点着色器和片段着色器之间传递插补数据。来自顶点程序的渐变寄存器将用作片段程序的输入。根据与三角形顶点的距离插补计算所需的值。 |
| 取样器 | 8 | 无 | 片段着色器输入；读取自使用 Context3D.setTextureAt() 指定的纹理 |
顶点程序会接收来自两个源的输入：顶点缓冲区和常量寄存器。使用 Context3D setVertexBufferAt() 方法指定具体顶点属性 寄存器要使用的顶点数据。您最多可以为顶点属性定义 8 个寄存器。顶点属性值读取自三角形列表中每个顶点的顶点缓冲区，并放置在属性寄存器中。使用 Context3D setProgramConstantsFromMatrix() 或 setProgramConstantsFromVector() 方法指定常量 寄存器。常量寄存器为三角形列表中的每个顶点保留相同的值。（您只能在 drawTriangles() 调用之间修改常量值。）
顶点程序负责将三角形顶点投影到剪辑空间（x 和 y 轴上 ±1 之间和 z 轴上 0-1 之间的规范可视区域），并将转换后的坐标放置到输出寄存器中。（通常，将通过一组常量寄存器为着色器提供适当的投影矩阵。）顶点程序还必须将片段程序所需的任何顶点属性或计算值复制到一组名为渐变 寄存器的特殊变量中。在运行片段程序时，将根据当前片段与三角形每个顶点的距离线性插入渐变寄存器提供的值。
片段程序接收来自渐变寄存器和一组独立常量寄存器的值（使用 setProgramConstantsFromMatrix() 或 setProgramConstantsFromVector() 设置）。您也可以从使用取样器 寄存器上载到渲染上下文的纹理读取纹理数据。使用 Context3D setTextureAt() 方法指定具体取样器寄存器要访问的纹理。片段程序负责将其输出寄存器设置为颜色值。
参数
vertexProgram:ByteArray — Vertex 程序的 AGAL 字节码。ByteArray 对象必须使用 little endian 格式。
| |
fragmentProgram:ByteArray — Fragment 程序的 AGAL 字节码。ByteArray 对象必须使用 little endian 格式。
|
引发
TypeError — Null 指针错误：如果 vertexProgram 或 fragmentProgram 为 null。
| |
Error — 对象已处置：如果通过调用 dispose() 直接或通过调用 Context3D dispose() 间接处置了 Program3D 对象，或者由于设备丢失导致渲染上下文被处置。
| |
ArgumentError — Agal 程序太小：当任一程序代码数组小于 31 字节长度时。这是单指令程序的着色器字节码的大小。
| |
ArgumentError — 程序必须是 little endian 格式：如果任一程序字节码数组不是 little endian 格式。
| |
Error — 本机着色器编译失败：如果 AGAL 翻译程序的输出不是一个可编译的本机着色器语言程序。只在发行播放器中引发此错误。
| |
Error — OpenGL 本机着色器编译失败：如果 AGAL 翻译程序的输出不是可编译的 OpengGL 着色器语言程序，包括编译诊断。只在调试播放器中引发此错误。
| |
Error — D3D9 本机着色器编译失败：如果 AGAL 翻译程序的输出不是可编译的 Direct3D 着色器语言程序，包括编译诊断。只在调试播放器中引发此错误。
当 AGAL 字节码验证失败时，会引发下列错误： | |
Error — 不是 AGAL 程序：如果标头的“magic 字节”错误。字节码的第一个字节必须为 0xa0。此错误可能指示字节数组设置为了错误的 endian 顺序。
| |
Error — 错误的 AGAL 版本：如果当前 SWF 版本不支持该 AGAL 版本。对于 SWF 版本 13，AGAL 版本必须设置为 1。
| |
Error — 错误的 AGAL 程序类型：如果 AGAL 程序类型标识符无效。字节码中的第 3 个字节必须为 0xa1。此错误可能指示字节数组设置为了错误的 endian 顺序。
| |
Error — 错误的 AGAL 着色器类型：如果着色器类型代码不是片段或定点（1 或 0）。
| |
Error — 无效 AGAL opcode 超出范围：如果在标记流中遇到了无效的 opcode。
| |
Error — 无效 AGAL opcode 未实施：如果在标记流中遇到了无效的 opcode。
| |
Error — 仅在片段程序中允许的 AGAL opcode：如果在顶点程序的标记流中遇到了仅在片段程序中才允许的 opcode，例如 KIL 或 TEX。
| |
Error — 错误的 AGAL 源操作数：如果两个源操作数都是常量寄存器。您必须在着色器程序以外计算结果，并使用单个常量寄存器将其传入。
| |
Error — 两个操作数均为间接读取：如果两个操作数均为间接读取。
| |
Error — opcode 目标必须全部为零：如果一个带有无目标 opcode（例如，KIL）的标记为目标寄存器设置了非零值。
| |
Error — Opcode 目标必须使用遮罩：如果在未使用遮罩时使用了只生成 3 个组件结果的 opcode。
| |
Error — 标记过多：如果 AGAL 程序中的标记过多（超过 200 个）。
| |
Error — 片段着色器类型：如果片段程序类型（fragmentProgram 参数的第 6 个字节）未设置为 1。
| |
Error — 顶点着色器类型：如果顶点程序类型（vertexProgram 参数的第 6 个字节）未设置为 0。
| |
Error — 渐变寄存器已读取但未写入：如果片段着色器读取了渐变寄存器，但顶点着色器从未向其中写入。
| |
Error — 渐变寄存器部分写入：如果渐变寄存器仅部分写入。必须写入渐变寄存器的所有组件。
| |
Error — 片段写入所有组件：如果片段颜色输出仅部分写入。必须写入颜色输出的所有 4 个组件。
| |
Error — 顶点写入所有组件：如果顶点剪辑空间输出仅部分写入。必须写入顶点剪辑空间输出的所有组件。
| |
Error — 未使用的操作数：如果标记中某个未使用的操作数未全部设置为零。
| |
Error — 仅在片段程序中使用取样器寄存器：如果在顶点程序中使用纹理取样器寄存器。
| |
Error — 取样器寄存器应为第二个操作数：如果将取样器寄存器用作 AGAL 标记的目标或第一个操作数。
| |
Error — 仅允许在顶点程序中使用间接寻址：如果在片段程序中使用间接寻址。
| |
Error — 仅在常量寄存器上使用间接寻址：如果在非常量寄存器上使用间接寻址。
| |
Error — 间接源类型：如果间接源类型不是属性、常量或临时寄存器。
| |
Error — 间接寻址字段必须为零：对于直接寻址，如果不是所有间接寻址字段都为零。
| |
Error — 只能在片段程序中读取渐变寄存器：如果在顶点程序中读取渐变寄存器。只能在顶点程序中写入渐变寄存器并只能在片段程序中读取它。
| |
Error — 只能在顶点程序中读取属性寄存器：如果在片段程序中读取属性寄存器。只能在顶点程序中读取属性寄存器。
| |
Error — 无法读取输出寄存器：如果读取输出（位置或颜色）寄存器。只能写入但不能读取输出寄存器。
| |
Error — 读取临时寄存器但未写入过：如果读取临时寄存器但之前未写入过。
| |
Error — 读取临时寄存器组件但未写入过：如果读取特定临时寄存器组件但之前未写入过。
| |
Error — 不能写入取样器寄存器：如果写入取样器寄存器。只能读取但不能写入取样器寄存器。
| |
Error — 渐变寄存器写入：如果在片段程序中写入渐变寄存器。只能在顶点程序中写入渐变寄存器并只能在片段程序中读取它。
| |
Error — 无法写入属性寄存器：如果写入属性寄存器。属性寄存器是只读的。
| |
Error — 无法写入常量寄存器：如果在着色器程序中写入常量寄存器。
| |
Error — 目标 Writemask 为零：如果目标 Writemask 为零。 必须设置输出寄存器的所有组件。
| |
Error — AGAL 保留位应为零：如果标记中的任何保留位不为零。这指示在创建字节码时出错（或错误的字节码）。
| |
Error — 未知寄存器类型：如果使用了无效寄存器类型索引。
| |
Error — 取样器寄存器超出边界：如果使用无效的取样器寄存器索引。
| |
Error — 渐变寄存器超出边界：如果使用无效的渐变寄存器索引。
| |
Error — 属性寄存器超出边界：如果使用无效的属性寄存器索引。
| |
Error — 常量寄存器超出边界：如果使用无效的常量寄存器索引。
| |
Error — 输出寄存器超出边界：如果使用无效的输出寄存器索引。
| |
Error — 临时寄存器超出边界：如果使用无效的临时寄存器索引。
| |
Error — 立方图取样器必须使用锁定模式：如果立方图取样器未将环绕模式设置为锁定。
| |
Error — 未知取样器维数：如果样本使用未知取样器维数。（仅支持 2D 和立方体纹理）
| |
Error — 未知滤镜模式：如果取样器使用未知滤镜模式。（仅支持最近相邻和线性过滤。）
| |
Error — 未知 Mipmap 模式：如果取样器使用未知 mipmap 模式。（仅支持无、最近相邻和线性 mipmap 模式。）
| |
Error — 未知环绕模式：如果取样器使用未知环绕模式。（仅支持锁定和重复环绕模式。）
| |
Error — 未知特殊标志：如果取样器使用未知特殊标志。
| |
Error — 输出颜色不可遮罩：在片段程序中您无法遮罩颜色输出寄存器。必须设置颜色寄存器的所有组件。
| |
Error — 第二个操作数必须是取样器寄存器：AGAL 纹理 opcode 必须使用取样器作为第二个源操作数。
| |
Error — 不允许间接寻址：在不允许的地方使用间接寻址。
| |
Error — 重排必须为标量：重排错误。
| |
Error — 无法重排第二个源：重排错误。
| |
Error — 再次使用取样器必须使用相同参数：访问相同纹理的所有取样器必须使用相同维数、环绕、滤镜、专用和 mipmap 设置。
| |
Error — 3768：后台执行期间不可使用 Stage3D API。
|
了解详细信息
相关 API 元素
Tue Jun 12 2018, 11:04 AM Z