Verwenden der StageVideo-APIs

Die Stage.stageVideos -Eigenschaft ist ein Vector-Objekt, das Ihnen Zugriff auf StageVideo-Instanzen ermöglicht. Je nach Hardware- und Systemressourcen kann dieses Vector-Objekt maximal vier StageVideo-Objekte enthalten. Auf Mobilgeräten steht möglicherweise nur ein oder auch gar kein StageVideo-Objekt zur Verfügung.

Wenn kein Bühnenvideo verfügbar ist, enthält dieses Vector-Objekt keine Objekte. Um Laufzeitfehler zu vermeiden, darf der Zugriff auf Mitglieder dieses Vektors nur erfolgen, wenn das neueste StageVideoAvailability -Ereignis darauf hinweist, dass Bühnenvideo verfügbar ist.

Die StageVideo-API bietet die folgenden Ereignisse:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Wird gesendet, wenn die Stage.stageVideos -Eigenschaft sich ändert. Die StageVideoAvailabilityEvent.availability -Eigenschaft hat den Wert AVAILABLE (VERFÜGBAR) oder UNAVAILABLE (NICHT VERFÜGBAR). Verwenden Sie dieses Ereignis, um zu ermitteln, ob die stageVideos -Eigenschaft StageVideo-Objekte enthält, anstatt direkt die Länge des Stage.stageVideos -Vektors zu überprüfen.

StageVideoEvent.RENDER_STATE

Wird gesendet, wenn ein NetStream- oder Camera-Objekt einem StageVideo-Objekt zugeordnet wurde und abgespielt wird. Gibt an, welches Dekodierverfahren gerade verwendet wird: Hardware, Software oder nicht verfügbar (nichts wird angezeigt). Das Ereignisziel enthält die videoWidth - und videoHeight -Eigenschaften, mit denen die Größe des Video-Viewports auf sichere Weise geändert werden kann.

Wichtig: Die vom StageVideo-Zielobjekt abgerufenen Koordinaten stützen sich auf Bühnenkoordinaten, da sie nicht zur Standardanzeigeliste gehören.

VideoEvent.RENDER_STATE

Wird gesendet, wenn ein Video-Objekt verwendet wird. Das Ereignis gibt an, ob die Dekodierung über die Software oder über die Hardwarebeschleunigung durchgeführt wird. Wenn dieses Ereignis auf eine hardwarebeschleunigte Dekodierung hinweist, sollten Sie nach Möglichkeit zu einem StageVideo-Objekt wechseln. Das Video-Ereignisziel enthält die videoWidth - und videoHeight -Eigenschaften, mit denen die Größe des Video-Viewports auf sichere Weise geändert werden kann.

Das Implementieren der StageVideo-Funktion besteht aus den folgenden Hauptschritten:

1. Verwenden Sie einen Listener für das StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY -Ereignis, um festzustellen, wann sich der Stage.stageVideos -Vektor geändert hat. Siehe Verwenden des StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY-Ereignisses .

2. Wenn das StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY -Ereignis meldet, dass Bühnenvideo verfügbar ist, greifen Sie mit dem Stage.stageVideos -Vektorobjekt in dieser Ereignisprozedur auf ein StageVideo-Objekt zu.

3. Fügen Sie ein NetStream-Objekt unter Verwendung von StageVideo.attachNetStream() oder ein Camera-Objekt unter Verwendung von StageVideo.attachCamera() an.

4. Spielen Sie das Video mit NetStream.play() ab.

5. Verwenden Sie einen Listener für das StageVideoEvent.RENDER_STATE -Ereignis des StageVideo-Objekts, um den Wiedergabestatus des Videos festzustellen. Der Empfang dieses Ereignisses gibt auch an, dass die width- und height-Eigenschaften (Breite und Höhe) des Videos initialisiert oder geändert wurden. Siehe Verwenden der StageVideoEvent.RENDER_STATE- und VideoEvent.RENDER_STATE-Ereignisse .

6. Verwenden Sie einen Listener für das VideoEvent.RENDER_STATE -Ereignis des Video-Objekts. Dieses Ereignis stellt dieselben Statusangaben bereit wie StageVideoEvent.RENDER_STATE , sodass Sie damit auch feststellen können, ob die GPU-Beschleunigung verfügbar ist. Der Empfang dieses Ereignisses gibt auch an, dass die width- und height-Eigenschaften (Breite und Höhe) des Videos initialisiert oder geändert wurden. Siehe Verwenden der StageVideoEvent.RENDER_STATE- und VideoEvent.RENDER_STATE-Ereignisse .

Richten Sie die StageVideoAvailabilityEvent- und VideoEvent-Listener während der Anwendungsinitialisierung ein. Beispielsweise können Sie diese Listener in der flash.events.Event.ADDED_TO_STAGE -Ereignisprozedur initialisieren. Dieses Ereignis gewährleistet, dass die Anwendung auf der Bühne sichtbar ist:

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

Geben Sie für die StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY -Prozedur ein Video- oder ein StageVideo-Objekt an, je nach der Verfügbarkeit von StageVideo. Wenn die StageVideoAvailabilityEvent.availability -Eigenschaft auf StageVideoAvailability.AVAILABLE gesetzt ist, verwenden Sie StageVideo. In diesem Fall können Sie sicher sein, dass der Stage.stageVideos-Vektor mindestens ein StageVideo-Objekt enthält. Rufen Sie ein StageVideo-Objekt von der Stage.stageVideos -Eigenschaft ab und weisen Sie ihm das NetStream-Objekt zu. Da StageVideo-Objekte immer im Hintergrund angezeigt werden, müssen Sie vorhandene Video-Objekte, die immer im Vordergrund erscheinen, entfernen. Fügen Sie mit dieser Ereignisprozedur auch einen Listener für das StageVideoEvent.RENDER_STATE -Ereignis hinzu.

Wenn die StageVideoAvailabilityEvent.availability -Eigenschaft auf StageVideoAvailability.UNAVAILABLE gesetzt ist, dürfen Sie weder StageVideo verwenden noch auf den Stage.stageVideos -Vektor zugreifen. Weisen Sie in diesem Fall das NetStream-Objekt einem Video-Objekt zu. Fügen Sie zum Schluss der Bühne das StageVideo- oder Video-Objekt hinzu und rufen Sie NetStream.play() auf.

Der folgende Code veranschaulicht die Verarbeitung des StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY -Ereignisses:

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

Sie können den vollständigen Quellcode dieser Beispielanwendung von der Website Erste Schritte mit Bühnenvideo herunterladen.

StageVideo- und Video-Objekte senden Ereignisse, um Anwendungen zu informieren, wenn die Anzeigeumgebung sich ändert. Diese Ereignisse heißen StageVideoEvent.RENDER_STATE und VideoEvent.RENDER_STATE .

Ein StageVideo- oder Video-Objekt löst ein Ereignis für den Renderstatus aus, wenn ein NetStream-Objekt zugewiesen ist und dessen Wiedergabe beginnt. Dieses Ereignis wird auch gesendet, wenn die Anzeigeumgebung sich ändert, beispielsweise wenn die Größe des Video-Viewports geändert wird. Verwenden Sie diese Benachrichtigungen, um den Viewport auf die aktuellen videoHeight - und videoWidth -Werte des Ereigniszielobjekts zurückzusetzen.

Für den Renderstatus können folgende Angaben gemeldet werden:

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

Der Renderstatus gibt an, ob die hardwarebeschleunigte Dekodierung verwendet wird, unabhängig davon, welche Klasse derzeit Video abspielt. Überprüfen Sie anhand der StageVideoEvent.status -Eigenschaft, ob die erforderliche Dekodierung verfügbar ist. Wenn diese Eigenschaft auf „unavailable“ eingestellt ist, kann das StageVideo-Objekt das Video nicht abspielen. Bei diesem Status müssen Sie das NetStream-Objekt sofort wieder einem Video-Objekt zuweisen. Andere Statusangaben informieren Ihre Anwendung über die aktuellen Renderbedingungen.

Die folgende Tabelle veranschaulicht die Bedeutung aller Renderstatuswerte für StageVideoEvent- und VideoEvent-Objekte in Flash Player:

Bühnenvideo unterstützt Farbräume über die zugrunde liegende Funktionalität der Hardware. SWF-Inhalt kann über Metadaten den bevorzugten Farbraum angeben. Ob dieser Farbraum auch verwendet werden kann, richtet sich jedoch nach der Grafikhardware des Geräts. Manche Geräte bieten Unterstützung für mehrere Farbräume, während andere Geräte gar keine Farbräume unterstützen. Wenn die Hardware den gewünschten Farbraum nicht unterstützt, versucht Flash Player, unter den unterstützten Farbräumen eine möglichst genaue Entsprechung zu finden.

Mit der StageVideo.colorSpaces -Eigenschaft können Sie feststellen, welche Farbräume von der Hardware unterstützt werden. Diese Eigenschaft gibt die Liste der unterstützten Farbräume in einem String-Vektor zurück:

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

Anhand der StageVideoEvent.colorSpace -Eigenschaft können Sie ermitteln, welchen Farbraum das derzeit wiedergegebene Video verwendet. Überprüfen Sie diese Eigenschaft in der Ereignisprozedur für das StageVideoEvent.RENDER_STATE -Ereignis:

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

Wenn Flash Player keinen Ersatz für einen nicht unterstützten Farbraum finden kann, verwendet das Bühnenvideo den standardmäßigen Farbraum, also BT.601. Videostreams mit der H.264-Kodierung verwenden beispielsweise in der Regel den Farbraum BT.709. Wenn die Gerätehardware den Farbraum BT.709 nicht unterstützt, gibt die colorSpace -Eigenschaft den Wert "BT601" zurück. Wenn StageVideoEvent.colorSpace den Wert "unknown" (unbekannt) zurückgibt, bietet die Hardware keine Möglichkeit, den Farbraum abzufragen.

Wenn der aktuelle Farbraum in Ihrer Anwendung als ungeeignet betrachtet wird, können Sie von einem StageVideo-Objekt zu einem Video-Objekt wechseln. Die Video-Klasse unterstützt alle Farbräume über das Software-Compositing.