Starling框架帮助手册中文版《一》

文章转自http://www.adobe.com/cn/devnet/flashplayer/articles/introducing_Starling.html

什么是Starling

Starling是一个使用ActionScript 3开发的，基于Stage3D API的面向2D图像的开发框架。Starling主要是为游戏开发而设计，但是它也同样可以应用于其他的用况。Stargling可以使你很快速的编写的GPU加速应用程序，而无需接触底层的Stage3D API。

为什么选择Starling

大部分程序员想利用GPU加速（通过Stage 3D）而又不想编写如此高级的框架以及深入底层的Stage3D API。Starling被设计成完全遵循 ActionScript API 规则并将低级 Stage3D APIs 的复杂性抽象化以及允许每一个人方便和直观的进行编程。

很显然Starling是面向ActionScript3开发人员的，特别是那些2D游戏开发人员；当然你需要对AS3有基础的理解。通过Starling的设计，它也同样可以被应用于其他的用例，例如UI编程。这说明，任何一个东西都可以被设计的尽可能直观，如同JAVA和Net的程序员总是希望快速的得到代码异常终止的提示。

哲学

直观

Starling非常容易学习。特别是对于Flash/Flex的程序员会有宾至如归的感觉，因为它遵循大多数的ActionScript规则并将低级 Stage3D APIs 的复杂性抽象化。Starling 使用熟知的概念，例如DOM显示列表、事件模型以及熟知的如 MovieClip、Sprite、TextField 等APIs，而不是依靠诸如顶点缓冲（vertices buffer）、透视矩阵（perspective matrices）、着色程序（shader programs）和组合字节码（assembly bytecode）进行编码。

轻便

Starling在很多领域都很轻便。 类的数量是有限的（大概有80k的代码）。 除了Flash Player 11 或者 AIR 3（以及在未来的版本中使用的移动支持）之外，它没有外部依赖。 这些因素使得你的应用程序很小并使你的工作流程简单。

免费

Starling能够免费使用并富有朝气。 它根据 Simplified BSD 许可获得授权，因此你可以免费地使用它，即便是在商业应用程序中也是如此。 我们每天都在使用它并且我们依靠一个活跃的团队不断地完善它。

它是如何工作的

在后台操作中，Starling 使用 Stage3D APIs —它们是在桌面上基于 OpenGL 和 DirectX ，在移动设备上基于 OpenGL ES2而运行的低级的 GPU APIs。 需要重点注意的是，Starling 是Sparrow* 的 ActionScript 3 端口，它等同于基于 OpenGL ES2 APIs 的ISO库（参见图1）：

图1. Stage3D (Molehill) 分层位于 Starling 之上 

Starling 重新创建了很多 Flash 开发人员熟知的 APIs 。 下图列举了通过 Starling 暴露的图形元素 APIs（参见图2）。

图2. Starling支持DisplayObject继承

在 3D GPU APIs 基础上可以创建 2D 内容，这看起来有点奇怪。 当涉及 Stage3D APIs 时，很多人认为这些 APIs 是严格地限制在 3D 内容中的。 实际上这是名称造成的误解：如果它叫做 Stage3D ，那么你怎么可以使用它创建 2D 元素呢？下图说明了关于使用 drawTriangles API 绘制 MovieClip 能力的问题（参见图3）。

图3. 可以使用 drawTriangles API 创建2D影片剪辑吗？ 

GPU 具有较高的效率并能快速地绘制三角形。 通过使用 drawTriangles API ，你可以绘制两个三角形，然后选取一种纹理并且使用UV映射将它应用到三角形中。 这样可以创建了一个带有纹理的四边形，它代表一个 sprite 。 通过更新每一个帧上的三角形的纹理，最后的结果就是一个 MovieClip 。

幸好我们没有必要通过这些细节使用 Starling 。 你只需要提供帧数，将它们提供给一个 Starling MovieClip ，这就是所有需要做的（参见图4）。

图4. 使用 drawTriangles API 和一个带有纹理的四边形，你可以创建一个2D图形 

为了更好地了解 Starling 如何降低复杂性，检查你必须写入的代码以便于用低级的 Stage3D APIs 显示简单的带有纹理的四边形。

// create the vertices
var vertices:Vector. = Vector.([
-0.5,-0.5,0, 0, 0, // x, y, z, u, v
-0.5, 0.5, 0, 0, 1,
0.5, 0.5, 0, 1, 1,
0.5, -0.5, 0, 1, 0]);

// create the buffer to upload the vertices
var vertexbuffer:VertexBuffer3D = context3D.createVertexBuffer(4, 5);

// upload the vertices
vertexbuffer.uploadFromVector(vertices, 0, 4);

// create the buffer to upload the indices
var indexbuffer:IndexBuffer3D = context3D.createIndexBuffer(6);

// upload the indices
indexbuffer.uploadFromVector (Vector.([0, 1, 2, 2, 3, 0]), 0, 6);

// create the bitmap texture
var bitmap:Bitmap = new TextureBitmap();

// create the texture bitmap to upload the bitmap
var texture:Texture = context3D.createTexture(bitmap.bitmapData.width,

bitmap.bitmapData.height, Context3DTextureFormat.BGRA, false);

// upload the bitmap

texture.uploadFromBitmapData(bitmap.bitmapData);

// create the mini assembler
var vertexShaderAssembler : AGALMiniAssembler = new AGALMiniAssembler();

// assemble the vertex shader
vertexShaderAssembler.assemble( Context3DProgramType.VERTEX,

"m44 op, va0, vc0\n" + // pos to clipspace
"mov v0, va1" // copy uv
);

// assemble the fragment shader
fragmentShaderAssembler.assemble( Context3DProgramType.FRAGMENT,
"tex ft1, v0, fs0 <2d,linear, nomip>;\n" +
"mov oc, ft1"
);

// create the shader program
var program:Program3D = context3D.createProgram();

// upload the vertex and fragment shaders
program.upload( vertexShaderAssembler.agalcode, fragmentShaderAssembler.agalcode);

// clear the buffer
context3D.clear ( 1, 1, 1, 1 );

// set the vertex buffer
context3D.setVertexBufferAt(0, vertexbuffer, 0, Context3DVertexBufferFormat.FLOAT_3);
context3D.setVertexBufferAt(1, vertexbuffer, 3, Context3DVertexBufferFormat.FLOAT_2);

// set the texture
context3D.setTextureAt( 0, texture );

// set the shaders program
context3D.setProgram( program );

// create a 3D matrix 
var m:Matrix3D = new Matrix3D();

// apply rotation to the matrix to rotate vertices along the Z axis
m.appendRotation(getTimer()/50, Vector3D.Z_AXIS);

// set the program constants (matrix here)
context3D.setProgramConstantsFromMatrix(Co
ntext3DProgramType.VERTEX, 0, m, true);

// draw the triangles
context3D.drawTriangles( indexBuffer);

// present the pixels to the screen
context3D.present();

上述范例中的代码创建了一个正方形的2D实例（参见图5）：

图5. 使用drawTriangles API 和一个带有纹理的四边形创建一个2D对象的结果

上述范例中所示的代码无疑是非常复杂的。 那是访问低级 APIs 需要付出的代价。 从另一方面说，你可以控制很多方面，但是它需要大量的代码来设置一切。

通过 Starling，你可以编写如下代码替换上述代码：

// create a Texture object out of an embedded bitmap
var texture:Texture = Texture.fromBitmap ( new embeddedBitmap() );

// create an Image object our of the Texture
var image:Image = new Image(texture);

// set the properties
quad.pivotX = 50;
quad.pivotY = 50;
quad.x = 300;
quad.y = 150;
quad.rotation = Math.PI/4;

// display it
addChild(quad);

 

作为一个熟知如何使用 Flash APIs 的 ActionScript 3 开发人员，你可以立即使用这些已暴露的 APIs 开始工作，与此同时 Stage3D APIs 的所有复杂部分都可以在后台进行处理。

如果你使用重绘区域（redraw regions）功能进行试验，在 Starling 将在 Stage3D 上，而不是在预期的传统显示列表上渲染一切。 如下的截图说明了这种行为。 该四边形在每一帧上旋转，重绘区域（redraw regions）只显示FTP计数器，而不是 Stage3D 的内容（参见图6）：

图6. 使用Stage3D渲染内容的范例

需要记住在使用 Stage 3D 构架时，通过 GPU 可以完全地渲染并合成相应的内容。 因此，在 GPU 上运行的用于显示列表的重绘区域（redraw regions）功能不能使用。

分层限制

当你使用 Starling（以及Stage 3D）时，记住开发内容有一个限制。 正如之前所述，Stage3D 完全是嵌入在 Flash Player 中的全新的渲染构架。 GPU 表层放置在显示列表之下，这意味着任何在显示列表中运行的内容将放置到 Stage3D 内容之上。 在编写这篇文章时，运行在显示列表里的内容仍然不能放置在 Stage3D 分层之下（参见图7）。

图7. 使用Stage3D渲染内容的堆叠顺序

此外，还要注意 Stage3D 对象不是透明的。 如果这是可能的，那么你可以使用 Stage Video技术（Flash Player 10.2引入的功能）播放视频，同时可以用通过 Stage3D 渲染的内容覆盖视频。 希望未来的 Flash Player 版本支持这一功能。

 

作为一个熟知如何使用 Flash APIs 的 ActionScript 3 开发人员，你可以立即使用这些已暴露的 APIs 开始工作，与此同时 Stage3D APIs 的所有复杂部分都可以在后台进行处理。

如果你使用重绘区域（redraw regions）功能进行试验，在 Starling 将在 Stage3D 上，而不是在预期的传统显示列表上渲染一切。 如下的截图说明了这种行为。 该四边形在每一帧上旋转，重绘区域（redraw regions）只显示FTP计数器，而不是 Stage3D 的内容（参见图6）：

图6. 使用Stage3D渲染内容的范例

需要记住在使用 Stage 3D 构架时，通过 GPU 可以完全地渲染并合成相应的内容。 因此，在 GPU 上运行的用于显示列表的重绘区域（redraw regions）功能不能使用。

分层限制

当你使用 Starling（以及Stage 3D）时，记住开发内容有一个限制。 正如之前所述，Stage3D 完全是嵌入在 Flash Player 中的全新的渲染构架。 GPU 表层放置在显示列表之下，这意味着任何在显示列表中运行的内容将放置到 Stage3D 内容之上。 在编写这篇文章时，运行在显示列表里的内容仍然不能放置在 Stage3D 分层之下（参见图7）。

图7. 使用Stage3D渲染内容的堆叠顺序

此外，还要注意 Stage3D 对象不是透明的。 如果这是可能的，那么你可以使用 Stage Video技术（Flash Player 10.2引入的功能）播放视频，同时可以用通过 Stage3D 渲染的内容覆盖视频。 希望未来的 Flash Player 版本支持这一功能。

 

设置项目

你可以访问官方的 Github页面下载Starling。 此外，你可能发现访问Starling 网站也会受益匪浅。

Starling根据 Simplified BSD许可获得授权，所以你可以在任何类型的商业或者非商业项目上使用Starling。 如果你需要更多的信息，你可以联系Starling 框架团队。

在你下载Starling之后，你可以像引用其它AS3库一样引用Starling库。 为了使用Flash Player 11 beta的新版本，你必须把SWF版本13作为目标，这是通过将额外的编译器参数即-swf-version=13 传递给Flex编译器实现的。如果你正在使用 Adobe Flex SDK，那么请按照如下步骤操作：

1. 为 Flash Player 11下载新的playerglobal.swc。
2. 从Flex 4.5 SDK表中下载 Flex 4.5 SDK (4.5.0.20967)。
3. 将相应的版本安装到你的开发环境中。
4. 在 Flash Builder 中，通过选中File > New > ActionScript project 创建一个新的ActionScript项目。
5. 打开 Property inspector（右击并选中Properties选项）。 在左边的菜单列表中，选中ActionScript Compiler。
6. 使用右上角的 Configure Flex SDK 选项将项目指向 Flex build 20967。单击OK。
7. 设置你的项目目标为SWF版本13。
8. 打开Property inspector并从左侧菜单列表选中 ActionScript Compiler。
9. 将 -swf-version=13 添加至 'Additional compiler arguments' 输入。这就保证了输出的 SWF 把 SWF 版本13当做目标版本。如果你在命令行而不在 Flash Builder 中进行编译，那么你必须添加相同的编译器参数。
10. 核查你已经在你的浏览器中安装了新的Flash Player 11 版本。

设置场景

在你已经准备好了你的开发环境之后，你就可以深入研究相应的代码，并且看看你如何能够充分利用这一框架。 使用 Starling 非常简单，你只需创建一个
Starling 对象并添加到你的主类即可。 在本文中，当涉及到诸如 MovieClip, Sprite 以及其它对象时，我所指的都是 Starling APIs，而不是来源于 Flash Player 的本地对象。

首先，Starling构造器（constructor）需要多重参数。 下面是签名：

public function Starling(rootClass:Class, stage:flash.display.Stage, 
                         viewPort:Rectangle=null, stage3D:Stage3D=null,
                         renderMode:String="auto")

事实上，只有前面3个经常使用。 相关的 rootClass 参数需要一个至扩展 starling.display.Sprite 的类的引用，而第二个参数是我们的 stage，然后是一个 Stage3D 对象：

package 
{
    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import starling.core.Starling;
    
    [SWF(, , frameRate="60", backgroundColor="#002143")]
    public class Startup extends Sprite
    {
        private var mStarling:Starling;
        
        public function Startup()
        {
        // stats class for fps
addChild ( new Stats() );

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

// create our Starling instance
            mStarling = new Starling(Game, stage);

           // set anti-aliasing (higher is better quality but slower       performance)
               mStarling.antiAliasing = 1;

           // start it!
mStarling.start();
        }
    }
}

在下面的代码中，Game类在被添加到 Stage 时可以创建一个简单的四边形：

package 
{
    import starling.display.Quad;
    import starling.display.Sprite;
    import starling.events.Event;

    public class Game extends Sprite
    {
private var q:Quad;

        public function Game()
        {
addEventListener(Event.ADDED_TO_STAGE, onAdded);
        }

private function onAdded ( e:Event ):void
            {
q = new Quad(200, 200);
q.setVertexColor(0, 0x000000);
q.setVertexColor(1, 0xAA0000);
q.setVertexColor(2, 0x00FF00);
q.setVertexColor(3, 0x0000FF);
addChild ( q );
             }
    }
}

上述代码将一个侦听器添加到 Event.ADDED_TO_STAGE 事件中，并在事件处理程序中对应用程序进行初始化。 这样你就可以安全地访问 Stage。

注意： 关注一下这个微妙的细节：上面描述的 Game 类从 starling.display 程序包中，而不是从 flash.display 程序包中扩展了 Sprite 类。必须检查你的导入语句并确保你不是使用本地 API 来替代 Starling API。

正如在 Flash 中所预期的，Starling 中的对象有一个默认的位置0,0。因此添加几行命令使四边形位于 Stage 的中央：

q.x = stage.stageWidth - q.width >> 1; q.y = stage.stageHeight - q.height >> 1;

现在，测试一下项目以便于观察相应的结果（参见图8）：

图8. 四边形位于Stage的中央

注意锯齿消除功能（anti-aliasing）值允许你设置锯齿消除功能所需的类型。 一般来说，值为1就基本上可以接受，但是你可以选择其它值。 该框架支持的锯齿消除功能（anti-aliasing）值的变化范围是0到16，但是，下面的列表给出了最常用的值：

• 0: 无锯齿消除（anti-aliasing）。
• 2: 最低程度的锯齿消除（anti-aliasing）。
• 4: 高质量的锯齿消除（anti-aliasing）。
• 16: 极高质量的锯齿消除（anti-aliasing）。

你很少需要用到超过2的设置，尤其是对2D内容。 然而，根据你的项目要求，你需要针对具体情况作出相应的决定。 在图9中，比较一下两个截图，观察两个锯齿消除（anti-aliasing）值（1和4）之间的细微差别。

图9. 比较一下锯齿消除（anti-aliasing）值为1（左）和4（右）之间的视觉差别

试验一下使用2以上的值为你的项目设置所需的质量。 当然，选择较高的值会影响性能。 注意 Stage3D 不会受到 SWF 文件的 Stage 质量影响。

下面给出能够与 Starling 对象一起使用的其它 API 的描述：

• enableErrorChecking: 允许你启用或者禁止启用错误检查。 指定是否将渲染器遇到的问题报告给应用程序。 当 enableErrorChecking 设置为ture时，Starling 内部调用的 clear() 和 drawTriangles() 方法是同步的并可以抛出错误。 当 enableErrorChecking 设置为 false 时，clear() 和 drawTriangles() 方法是异步的且不报告错误。 启用错误检查将会减弱渲染性能。 只有当调试项目时启用错误检查功能，而在部署最终版本前禁止启用该功能。
• isStarted:指示是否调用了 start。
• juggler: juggler 是一个简单对象。 它仅保存了一列执行 IAnimatable 的对象，并且在被要求这样做的情形下提前了它们的时间（通过调用它自己的 advanceTime:方法）。 当一个动画完成时，它将会将其抛弃。
• start: 开始渲染和进行事件处理。
• stop: 停止渲染和进行事件处理。 当游戏进入后台运行状态以节约资源时，使用这个方法可以停止渲染。
• dispose: 当你希望处理当前 GPU 内存上已渲染的全部内容时，调用这个方法。 该API能够在其内部处理了一切事务（例如着色程序（shader programs）、纹理和其它一切事务）。

一旦创建了你的 Starling 对象，调试记录会自动地输出，显示关于渲染的信息。 在默认情形下，当 SWF 文件正确地嵌入到页面或者当在独立的 Flash Player 中进行测试时，Starling 会输出如下代码：

[Starling] Initialization complete.
[Starling] Display Driver:OpenGL Vendor=NVIDIA Corporation Version=2.1 NVIDIA-7.2.9 Renderer=NVIDIA GeForce GT 330M OpenGL Engine GLSL=1.20 (Direct blitting)

当然，特定的硬件细节将会随着你的配置而变化。 上述信息表明已经使用了 GPU 加速功能，因为它包括驱动版本的细节。 为了便于调试，你可能希望能够强迫 Flash Player 内部使用的软件回退，以便了解当你的内容在软件上运行时它的表现如何。

添加如下的代码以便于通知 Starling 你希望使用软件回退功能（software rasterizer）：

mStarling = new Starling(Game, stage, null, null, Context3DRenderMode.SOFTWARE);

当你使用软件时，输出的信息会确认你正在使用software 模式：

[Starling] Initialization complete.
[Starling] Display Driver:Software (Direct blitting)

 

确保你也在 software 模式下测试了你的内容，以便于更好地了解它在这种模式下的性能。 如果用户的配置使用旧版本的驱动（为了保持一致性，所有2009年之前的驱动都包含于黑名单中），那么你的内容可能回退到软件。

在下一节中，当你将你的 SWF 文件嵌入到页面时，你需要看一下 Stage3D 的要求。

Wmode 要求

你必须记住为了启用Stage 3D 和 GPU 加速功能，在页面中你必须使用 wmode=direct 作为嵌入模式。 如果你没有指定任何值或者选择除"direct"之外其它值，例如 "transparent"、"opaque" 或 "window"，则Stage 3D 将均不可用。相反，当requestContext3D onStage3D被调用时，你会得到一个运行时异常的提示，告知你Context3D对象的创建失败。

下图列举了一个运行时异常的对话框：

图10. 在 Context3D不可用的情形下，运行时异常对话框

如果你的应用程序嵌入时使用了错误的wmode，那么必须小心处理这种情形。 你需要通过显示一条解释这一问题的信息以便给出合理的响应。 幸运的是，Starling为你自动地处理了这一问题并显示如下信息：

图11. 当应用程序没有正确嵌入时显示的警告

STAGE质量

作为一个Flash开发人员，stage质量的概念对你来说并不陌生。 记住当使用 Stage3D以及作为结果的Starling时，stage质量不会影响相应的性能。

渐进的增强功能

当GPU加速功能不起作用时，Stage3D将回退到软件中，并且将在内部使用一个名称为SwiftShader (Transgaming)的软件回退引擎。 为了保证你的内容在此种情形下运行正常，你需要检测什么时候你应该在software模式下运行，并且移除在software模式下可能会减慢运行速度的潜在影响。

在2D内容环境下，软件回退功能能够处理很多对象并提供良好的性能，但是，为了检测这一点，你仍然可以使用静态的属性环境从Starling对象中读取Context3D对象：

// are we running hardware or software?
var isHW:Boolean = Starling.context.driverInfo.toLowerCase().indexOf("software") == -1;