将 StageVideo 类用于硬件加速呈现

Flash Player 10.2 和更高版本,用于电视的 Adobe AIR 2.5 和更高版本

Flash Player 将使用用于 H.264 解码的硬件加速来优化视频性能。您可以使用 StageVideo API 进一步增强性能。舞台视频允许您的应用程序利用硬件加速呈现。

支持 StageVideo API 的运行时包括:

  • Flash Player 10.2 和更高版本

  • 用于电视的 Adobe AIR 2.5 及更高版本

用于电视的 Adobe AIR 2.5 和用于 Google TV 的 Adobe Flash Player Beta 通过完整 API 的一个子集来支持舞台视频。在这些平台上,存在配置差异和更多限制。有关在这些平台上使用舞台视频的说明,请参阅在电视上传送 Flash Platform 视频和内容

舞台视频快速入门提供了舞台视频功能的可下载源代码和其他详细信息。要获得 StageVideo 快速入门教程,请参阅使用舞台视频

关于使用 StageVideo 实现硬件加速

Video 类通常使用软件呈现。软件呈现通过设备 CPU 来实现,会消耗大量的系统资源。在提供 GPU(硬件)加速功能的设备上,可以使用 flash.media.StageVideo 对象直接在设备硬件上呈现视频。直接呈现会释放 CPU,令其可以在 GPU 呈现视频时执行其他任务。硬件加速呈现会增强硬件加速解码的性能优势。

当前,只有很少的设备提供完全 GPU 加速。不过,舞台视频允许应用程序最大限度地利用可用硬件加速功能。

StageVideo 类不会令 Video 类废弃。组合使用这两个类,可以在任何给定时间提供设备资源所允许的最佳视频显示体验。应用程序通过侦听相应的事件并根据需要在 StageVideo 和 Video 之间切换,从而利用硬件加速功能。

StageVideo 类对视频的使用施加某些限制。在实现 StageVideo 之前,请查看原则,并确保您的应用程序可以接受这些原则。如果您接受这些限制,则不论何时 Flash Player 检测到硬件加速呈现可用时,都请使用 StageVideo 类。请参阅指导准则和限制

平行面:舞台视频和 Flash 显示列表

利用舞台视频模型,Flash Player 可以将视频从显示列表中分离。Flash Player 在两个按 Z 轴排列的平面之间拆分复合显示。

舞台视频平面
舞台视频平面位于背景中。该屏幕仅显示硬件加速视频。按照此设计方案,当设备不支持硬件加速或硬件加速不可用时,该平面不可用。在 ActionScript 中,StageVideo 对象处理舞台视频平面上播放的视频。

Flash 显示列表平面
Flash 显示列表实体组合显示在位于舞台视频平面前方的平面上。显示列表实体包含运行时呈现的所有内容(包括回放控件)。当硬件加速不可用时,只能使用 Video 类对象在此平面上播放视频。舞台视频始终显示在 Flash 显示列表图形的后面。

查看完全大小图形
视频显示平面

StageVideo 对象显示在屏幕上窗口对齐的非旋转矩形区域中。您不能在舞台视频平面后分层显示对象。不过,可以使用 Flash 显示列表平面将其他图形分层显示在舞台视频平面的上方。舞台视频与显示列表并行运行。因此,您可以组合使用这两种机制利用两个不同平面创建统一的视觉效果。例如,可以使用前面的平面显示播放控件,用于操作在背景中运行的舞台视频。

舞台视频和 H.264 编解码器

在 Flash Player 应用程序中,实现视频加速涉及到两个步骤:

  1. 将视频编码为 H.264

  2. 实现 StageVideo API

为了获得最佳结果,请执行下面两个步骤:H.264 编解码器允许您在目标设备上最大限度利用硬件加速功能,包括从视频解码到呈现。

舞台视频不再执行从 GPU 到 CPU 回读。换言之,GPU 不再将已解码的帧发送回 CPU 以便与显示列表对象复合,而是将已解码和已呈现的帧直接以位块形式传输到屏幕上,并将其置于显示列表对象后面。此项技术会减少 CPU 和内存的使用,另外还提供更好的像素保真度。

指导准则和限制

当视频在全屏模式下运行时,如果设备支持硬件加速,则舞台视频始终可用。不过,Flash Player 还会在浏览器内运行。在浏览器上下文中,wmode 设置会影响舞台视频的可用性。如果您希望使用舞台视频,请始终尝试使用wmode="direct"。在非全屏模式下,舞台视频与其他 wmode 设置不兼容。此项限制意味着在运行时,舞台视频可能会在可用和不可用之间摇摆不定。例如,在运行舞台视频时,如果用户退出全屏模式,则视频上下文将恢复为浏览器。如果浏览器的 wmode 参数未设置为 "direct",则视频会突然变得不可用。Flash Player 会通过一组事件将回放上下文更改发送给应用程序。如果您实现 StageVideo API,当舞台视频变得不可用时,请将 Video 对象保留为备份。

由于舞台视频直接与硬件建立关系,因此舞台视频会限制一些视频功能。舞台视频执行以下限制:

  • 对于每个 SWF 文件,Flash Player 将可并发显示的 StageVideo 对象数量限制为 4 个。但是,实际限值可能会更低,具体取决于设备硬件资源。在用于电视的 AIR 设备和大多数移动设备上,一次只有一个 StageVideo 对象可以显示视频。

  • 视频计时与运行时显示的内容的计时不同步。

  • 视频显示区域只能是矩形。您无法使用更先进的显示区域,如椭圆形或不规则形状。

  • 无法旋转视频。

  • 无法以位图形式缓存视频,也无法使用 BitmapData 对象访问视频。

  • 无法对视频应用滤镜。

  • 无法对视频应用颜色转化。

  • 无法对视频应用 Alpha 值。

  • 您应用到显示列表平面中对象的混合模式不会应用到舞台视频。

  • 只能将视频放置在全像素边界上。

  • 尽管 GPU 呈现模式是给定设备硬件的最佳可用模式,但不同设备并不能实现 100%“像素相同”。像素会因驱动程序和平台的不同而略有差异。

  • 少数设备不支持所有必需的色彩空间。例如,一些设备不支持 H.264 标准 BT.709。在此类情况下,可使用 BT.601 进行快速显示。

  • 如果 WMODE 设置为“normal”、“opaque”或“transparent”,则无法使用舞台视频。在非全屏模式下,舞台视频仅支持 WMODE=direct。在 Safari 4 或更高版本、IE 9 或更高版本或者用于电视的 AIR 中,WMODE 没有任何效果。

大多数情况下,上述限制对视频播放器应用程序没有影响。如果您能够接受上述限制,则应尽可能使用舞台视频。

使用 StageVideo API

舞台视频是运行时中的一种视频呈现机制,可增强视频播放和设备性能。运行时负责创建并维护该机制;作为开发人员,您的职责是配置应用程序以利用该机制。

为了使用舞台视频,您需要实现事件处理函数框架,以检测舞台视频何时可用以及何时不可用。当接收到指示舞台视频可用的通知时,从 Stage.stageVideos 属性中检索 StageVideo 对象。运行时使用一个或多个 StageVideo 对象填充此 Vector 对象。然后,您就可以使用所提供的 StageVideo 对象替代 Video 对象来显示流式传输视频。

在 Flash Player 中,当您接收到指示舞台视频不再可用的通知时,请将视频流切换回 Video 对象。此步骤不适用于用于电视的 AIR 2.5 应用程序。

注: 您不能创建 StageVideo 对象。

Stage.stageVideos 属性

Stage.stageVideos 属性是一个 Vector 对象,通过该对象可访问 StageVideo 实例。此矢量最多可包含 4 个 StageVideo 对象,具体取决于硬件和系统资源。用于电视的 AIR 设备仅能播放单一 StageVideo 实例。移动设备可以限制为 1 个对象或无对象。

当舞台视频不可用时,该矢量不包含任何对象。为了避免运行时错误,当接收到指示舞台视频可用的最近 StageVideoAvailability 事件时,请确保仅访问该矢量的成员。

StageVideo 事件

StageVideo API 框架提供了以下事件:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY
(在用于电视的 AIR 2.5 中不支持)当 Stage.stageVideos 属性更改时发送该事件。StageVideoAvailabilityEvent.availability 属性指示 AVAILABLEUNAVAILABLE。使用该事件可确定 stageVideos 属性是否包含任何 StageVideo 对象,而不必直接检查 Stage.stageVideos 矢量的长度。

StageVideoEvent.RENDER_STATE
当 NetStream 对象已附加到 StageVideo 对象并正在播放时发送该事件。指示当前使用的解码类型:硬件、软件或不可用(不显示任何内容)。事件目标包含 videoWidthvideoHeight 属性,调整视频视口的大小时可以安全地使用这些属性。
重要说明: 从 StageVideo 目标对象获取的坐标使用舞台坐标,这是因为他们不是标准显示列表的一部分。

VideoEvent.RENDER_STATE
(在用于电视的 AIR 2.5 中不支持)当使用 Video 对象时发送该事件。指示当前使用的是软件解码还是硬件加速解码。如果该事件指示硬件加速解码,则在可能的情况下,应切换到 StageVideo 对象。Video 事件目标包含 videoWidthvideoHeight 属性,调整视频视口大小时可以安全地使用这些属性。

实现 StageVideo 功能的工作流程

请执行这些顶级步骤来实现 StageVideo 功能:

  1. 侦听 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件以了解 Stage.st geVideos 矢量何时更改。请参阅使用 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件。(在用于电视的 AIR 2.5 中不支持。)

  2. 如果 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件报告舞台视频可用,则可以在事件处理函数中使用 Stage.stageVideos Vector 对象来访问 StageVideo 对象。在用于电视的 AIR 2.5 中,呈现第一个 SWF 帧后,访问 Stage.stageVideos

  3. 使用 StageVideo.attachNetStream() 连接 NetStream 对象。

  4. 使用 NetStream.play() 播放视频。

  5. 侦听 StageVideo 对象上的 StageVideoEvent.RENDER_STATE 事件,以确定播放视频的状态。收到此事件还说明,视频的宽度和高度属性已初始化或更改。请参阅使用 StageVideoEvent.RENDER_STATE 和 VideoEvent.RENDER_STATE 事件

  6. 侦听 Video 对象上的 VideoEvent.RENDER_STATE 事件。此事件提供与 StageVideoEvent.RENDER_STATE 相同的状态,因此您也可以使用它来确定 GPU 加速是否可用。收到此事件还说明,视频的宽度和高度属性已初始化或更改。(在用于电视的 AIR 2.5 中不支持。)请参阅使用 StageVideoEvent.RENDER_STATE 和 VideoEvent.RENDER_STATE 事件

初始化 StageVideo 事件侦听器

在应用程序初始化过程中设置 StageVideoAvailabilityEvent 和 VideoEvent 侦听器。例如,可以在 flash.events.Event.ADDED_TO_STAGE 事件处理函数中初始化这些侦听器。此事件可保证您的应用程序在舞台上可见;

public class SimpleStageVideo extends Sprite 
    private var nc:NetConnection; 
    private var ns:NetStream; 
 
    public function SimpleStageVideo() 
    { 
        // Constructor for SimpleStageVideo class 
        // Make sure the app is visible and stage available 
        addEventListener(Event.ADDED_TO_STAGE, onAddedToStage); 
    } 
     
    private function onAddedToStage(event:Event):void 
    { 
        //... 
        // Connections 
        nc = new NetConnection(); 
        nc.connect(null); 
        ns = new NetStream(nc); 
        ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus); 
        ns.client = this; 
 
        // Screen 
        video = new Video(); 
        video.smoothing = true; 
 
        // Video Events 
        // the StageVideoEvent.STAGE_VIDEO_STATE informs you whether 
        // StageVideo is available 
        stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY, 
            onStageVideoState); 
        // in case of fallback to Video, listen to the VideoEvent.RENDER_STATE 
        // event to handle resize properly and know about the acceleration mode running 
        video.addEventListener(VideoEvent.RENDER_STATE, videoStateChange); 
        //... 
    }

使用 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 处理函数中,根据 StageVideo 的可用性确定是使用 Video 对象还是使用 StageVideo 对象。如果 StageVideoAvailabilityEvent.availability 属性设置为 StageVid oAvailability.AVAILABLE,则使用 StageVideo。在这种情况下,可依赖于 Stage.stageVideos 矢量来包含一个或多个 StageVideo 对象。从 Stage.stageVideos 属性获取 StageVideo 对象,并将 NetStream 对象附加到它。由于 StageVideo 对象始终显示在背景中,因此需删除所有现有的 Video 对象(始终位于前景中)。还可以使用此事件处理函数添加 StageVideoEvent.RENDER_STATE 事件的侦听器。

如果 StageVideoAvailabilityEvent.availability 属性设置为 StageVid oAvailability.UNAVAILABLE,请勿使用 StageVideo 或访问 Stage.stageVideos 矢量。在这种情况下,请将 NetStream 对象附加到 Video 对象。最后,请将 StageVideo 或 Video 对象添加到舞台,并调用 NetStream.play()

下面的代码显示如何处理 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 事件:

private var sv:StageVideo; 
private var video:Video; 
 
private function onStageVideoState(event:StageVideoAvailabilityEvent):void 
{     
    // Detect if StageVideo is available and decide what to do in toggleStageVideo 
    toggleStageVideo(event.availability == StageVideoAvailability.AVAILABLE); 
} 
 
private function toggleStageVideo(on:Boolean):void 
{     
    // To choose StageVideo attach the NetStream to StageVideo 
    if (on) 
    { 
        stageVideoInUse = true; 
        if ( sv == null ) 
        { 
            sv = stage.stageVideos[0]; 
            sv.addEventListener(StageVideoEvent.RENDER_STATE, stageVideoStateChange); 
                sv.attachNetStream(ns); 
        } 
 
        if (classicVideoInUse) 
        { 
            // If you use StageVideo, remove from the display list the 
            // Video object to avoid covering the StageVideo object 
            // (which is always in the background) 
            stage.removeChild ( video ); 
            classicVideoInUse = false; 
        } 
    } else 
    { 
        // Otherwise attach it to a Video object 
        if (stageVideoInUse) 
            stageVideoInUse = false; 
        classicVideoInUse = true; 
        video.attachNetStream(ns); 
        stage.addChildAt(video, 0); 
    } 
     
    if ( !played ) 
    { 
        played = true; 
        ns.play(FILE_NAME); 
    } 
} 
重要说明: 当应用程序第一次在 Stage.stageVideos[0] 访问 vector 元素时,默认矩形设置为 0,0,0,0, 并使用默认值平移和缩放属性。请始终将这些值设置您首选的设置。您可以使用 StageVideoEvent.RENDER_STATEVideoEvent.RENDER_STATE 事件的 videoWidthvideoHeight 属性来计算视频视口尺寸。

可从舞台视频快速入门下载本示例应用程序的完整源代码。

使用 StageVideoEvent.RENDER_STATE 和 VideoEvent.RENDER_STATE 事件

当呈现环境变化时,StageVideo 和 Video 对象会发送事件以通知应用程序。这些事件为 StageVideoEvent.RENDER_STATEVideoEve t.RENDER_STATE

当 NetStream 对象已附加并开始播放时,StageVideo 或 Video 对象会调度一个呈现状态事件。当呈现环境变化时,它还会发送此事件;例如,当视频视口的大小调整时。请使用这些通知将视口重新设置为事件目标对象的当前 videoHeight 和 videoWidth 值。

已报告的呈现状态包括:

  • RENDER_STATUS_UNAVAILABLE

  • RENDER_STATUS_SOFTWARE

  • RENDER_STATUS_ACCELERATED

不论当前播放视频的是哪个类,呈现状态均指示何时使用硬件加速解码。请查看 StageVideoEvent.status 属性了解必要的解码是否可用。如果此属性设置为“unavailable”,则 StageVideo 对象不能播放此视频。此状态要求您立即将 NetStream 对象重新附加到 Video 对象。其他状态会将当前的呈现情况通知您的应用程序。

下表说明了 Flash Player 中 StageVideoEvent 和 VideoEvent 对象的所有呈现状态值的影响。

 

VideoStatus.ACCELERATED

VideoStatus.SOFTWARE

VideoStatus.UNAVAILABLE

StageVideoEvent

呈现和解码均通过硬件实现。(最佳性能。)

通过硬件呈现,使用软件解码。(可接受的性能。)

没有可用的 GPU 资源来呈现视频,不显示任何内容。回退到 Video 对象。

VideoEvent

使用软件呈现,通过硬件解码。(仅在现代桌面系统中可达到可接受的性能。全屏性能会下降。)

使用软件呈现,使用软件解码。(最差的性能表现。全屏性能会下降。)

(不适用)

注: 用于电视的 AIR 2.5 不定义 VideoStatus 类,不使用软件解码 H.264。请参阅在《ActionScript 3 参考》中的 StageVideoEvent 类,以了解有关用于电视的 AIR 2.5 事件实现的详细信息。

色彩空间

舞台视频使用基础硬件功能提供色彩空间支持。SWF 内容可提供指示其首选色彩空间的元数据。但是,设备图形硬件决定是否可使用该色彩空间。某一台设备可能会支持多种色彩空间,而另一台设备却不支持任何色彩空间。如果硬件不支持所请求的色彩空间,则 Flash Player 将尝试在所支持的色彩空间中查找匹配度最高的色彩空间。

若要查询硬件支持的色彩空间,请使用 StageVideo.colorSpaces 属性。此属性以 String 矢量的形式返回所支持的色彩空间列表:

var colorSpace:Vector.<String> = stageVideo.colorSpaces();

若要了解当前播放的视频所使用的色彩空间,请检查 StageVideoEvent.colorSpace 属性。在 StageVideoEvent.RENDER_STATE 事件的事件处理函数中检查此属性:

var currColorSpace:String; 
 
//StageVideoEvent.RENDER_STATE event handler 
private function stageVideoRenderState(event:Object):void 
{ 
    //... 
    currColorSpace = (event as StageVideoEvent).colorSpace; 
    //... 
}

如果 Flash Player 无法为不支持的色彩空间找到替代色彩空间,舞台视频将使用默认的 BT.601 色彩空间。例如,采用 H.264 编码的视频流通常使用 BT.709 色彩空间。如果设备硬件不支持 BT.709,则 colorSpace 属性将返回 "BT601"。如果 StageVideoEvent.colorSpace 的值为 "unknown",则指示硬件未提供色彩空间查询方法。

注: 在用于电视的 AIR 2.5 中,StageVideo 不支持色彩空间。在此平台上,StageVideoEvent.colorSpace 属性返回“BT709”或“BT601”,前者指示硬件呈现,后者指示软件呈现。

如果您的应用程序认为当前色彩空间不可接受,可选择从 StageVideo 对象切换到 Video 对象。Video 类通过软件合成支持所有色彩空间。