De StageVideo-API's gebruiken

Werkgebiedvideo is een runtimemechanisme dat de videoweergave en de prestaties van het apparaat verbetert. De runtime creëert en onderhoudt dit mechanisme. Uw rol als ontwikkelaar bestaat uit het configureren van uw toepassing om ervan te profiteren.

Als u werkgebiedvideo wilt gebruiken, implementeert u een framework met gebeurtenishandlers die detecteren wanneer werkgebiedvideo al dan niet beschikbaar is. Wanneer wordt gemeld dat werkgebiedvideo beschikbaar is, haalt u een StageVideo-object op van de Stage.stageVideos-eigenschap. De runtime vult dit Vector-object met een of meerdere StageVideo-objecten. U kunt dan een van de verschafte StageVideo-objecten gebruiken in plaats van een Video-object om streaming video weer te geven.

Wanneer in Flash Player wordt gemeld dat werkgebiedvideo niet meer beschikbaar is, schakelt u de videostream terug naar een Video-object.

Opmerking: U kunt geen StageVideo-objecten maken.

De eigenschap Stage.stageVideos

De eigenschap Stage.stageVideos is een Vector-object dat u toegang geeft tot StageVideo-instanties. Dit Vector-object kan maximaal vier StageVideo-objecten bevatten, afhankelijk van de hardware- en systeembronnen. Op mobiele apparatuur kan dit beperkt zijn tot één of zelfs geen.

Als er geen werkgebiedvideo beschikbaar is, bevat dit Vector-object geen objecten. Zorg er, om runtimefouten te voorkomen, voor dat u leden van deze vector alleen benadert als de meest recente StageVideoAvailability-gebeurtenis aangeeft dat werkgebiedvideo beschikbaar is.

StageVideo-gebeurtenissen

Het StageVideo API-framework biedt de volgende gebeurtenissen:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY
Wordt verzonden wanneer de eigenschap Stage.stageVideos verandert. De eigenschap StageVideoAvailabilityEvent.availability geeft AVAILABLE of UNAVAILABLE aan. Gebruik deze gebeurtenis om te bepalen of de eigenschap stageVideos StageVideo-objecten bevat, in plaats van rechtstreeks de lengte van de Stage.stageVideos-vector te controleren.

StageVideoEvent.RENDER_STATE
Wordt verzonden wanneer een NetStream- of Camera-object is gekoppeld aan een StageVideo-object en wordt afgespeeld. Verwijst naar het type decodering dat momenteel wordt gebruikt: hardware, software of niet beschikbaar (er wordt niets weergegeven). Het gebeurtenisdoel bevat de eigenschappen videoWidth en videoHeight die u kunt gebruiken voor het wijzigen van het formaat van de videoviewport.
Belangrijk: De van het StageVideo-doelobject verkregen coördinaten gebruiken Stage-coördinaten, aangezien deze niet deel uitmaken van de standaardweergavelijst.

VideoEvent.RENDER_STATE
Wordt verzonden wanneer een Video-object wordt gebruikt. Geeft aan of softwaredecodering of decodering met hardwareversnelling wordt gebruikt. Als deze gebeurtenis versnelde decodering aangeeft, moet u, indien mogelijk, overschakelen op een StageVideo-object. Het gebeurtenisdoel Video bevat de eigenschappen videoWidth en videoHeight die u kunt gebruiken voor het wijzigen van het formaat van de videoviewport.

Workflow voor implementatie van de StageVideo-functie

Volg deze stappen op hoofdniveau om de StageVideo-functie te implementeren:

  1. Luister naar de gebeurtenis StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY om te kijken wanneer de Stage.stageVideos-vector is gewijzigd. Zie De gebeurtenis StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY gebruiken.

  2. Als door de StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY-gebeurtenis wordt gerapporteerd dat werkgebiedvideo beschikbaar is, gebruikt u het Vector-object Stage.stageVideos in de gebeurtenishandler om een StageVideo-object te benaderen.

  3. Koppel een NetStream-object met behulp van StageVideo.attachNetStream() of koppel een Camera-object met behulp van StageVideo.attachCamera().

  4. Speel de video af met NetStream.play().

  5. Luister naar de gebeurtenis StageVideoEvent.RENDER_STATE op het StageVideo-object om de afspeelstatus van de video te bepalen. Als u deze gebeurtenis ontvangt, betekent dat ook dat de eigenschappen voor de breedte en de hoogte van de video zijn geïnitialiseerd of gewijzigd. Zie De gebeurtenissen StageVideoEvent.RENDER_STATE en VideoEvent.RENDER_STATE gebruiken.

  6. Luister naar de gebeurtenis VideoEvent.RENDER_STATE van het Video-object. Deze gebeurtenis biedt dezelfde statussen als StageVideoEvent.RENDER_STATE. Met deze gebeurtenis kunt u dus ook bepalen of GPU-versnelling beschikbaar is. Als u deze gebeurtenis ontvangt, betekent dat ook dat de eigenschappen voor de breedte en de hoogte van de video zijn geïnitialiseerd of gewijzigd. Zie De gebeurtenissen StageVideoEvent.RENDER_STATE en VideoEvent.RENDER_STATE gebruiken.

StageVideo-gebeurtenislisteners initialiseren

Stel uw StageVideoAvailabilityEvent- en VideoEvent-listeners tijdens de initialisatie van de toepassing in. U kunt deze listeners bijvoorbeeld initialiseren in de flash.events.Event.ADDED_TO_STAGE-gebeurtenishandler. Deze gebeurtenis garandeert dat uw toepassing zichtbaar is in het werkgebied.

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

De gebeurtenis StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY gebruiken

In de StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY-handler geeft u aan of een Video- of StageVideo-object wordt gebruikt, op basis van de beschikbaarheid van StageVideo. Als de eigenschap StageVideoAvailabilityEvent.availability is ingesteld op StageVideoAvailability.AVAILABLE, gebruikt u StageVideo. In dat geval kunt u erop vertrouwen dat de Stage.stageVideos-vector een of meerdere StageVideo-objecten bevat. Haal een StageVideo-object op uit de eigenschap Stage.stageVideos en koppel het NetStream-object eraan. Aangezien StageVideo-objecten altijd op de achtergrond worden weergegeven, verwijdert u alle bestaande Video-objecten (die altijd op de voorgrond worden weergegeven). Benut deze gebeurtenishandler ook om een listener toe te voegen voor de StageVideoEvent.RENDER_STATE-gebeurtenis.

Wanneer de eigenschap StageVideoAvailabilityEvent.availability is ingesteld op StageVideoAvailability.UNAVAILABLE, gebruikt u StageVideo niet en benadert u de Stage.stageVideos-vector niet. In dit geval koppelt u het NetStream-object aan een Video-object. Ten slotte voegt u het StageVideo- of Video-object toe aan het werkgebied en roept u NetStream.play() aan.

De volgende code illustreert hoe u de gebeurtenis StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY moet afhandelen:

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); 
    } 
} 
Belangrijk: Wanneer een toepassing het vectorelement voor het eerst benadert op Stage.stageVideos[0], wordt het kader standaard ingesteld op 0,0,0,0 en worden standaardwaarden gebruikt voor pannen en zoomen. Stel deze waarden altijd weer in op de instellingen waaraan u de voorkeur geeft. U kunt de eigenschappen videoWidth en videoHeight van het gebeurtenisdoel StageVideoEvent.RENDER_STATE of VideoEvent.RENDER_STATE gebruiken om de afmetingen van de videoviewport te berekenen.

U kunt de volledige broncode van deze voorbeeldtoepassing downloaden van Aan de slag met werkgebiedvideo.

De gebeurtenissen StageVideoEvent.RENDER_STATE en VideoEvent.RENDER_STATE gebruiken

StageVideo- en Video-objecten verzenden gebeurtenissen om toepassingen te melden wanneer de weergaveomgeving verandert. StageVideoEvent.RENDER_STATE en VideoEvent.RENDER_STATE.

Een StageVideo- of Video-object verzendt een renderstatusgebeurtenis wanneer een NetStream-object wordt gekoppeld en afgespeeld. Het verzendt deze gebeurtenis ook wanneer de weergaveomgeving verandert, bijvoorbeeld wanneer het formaat van de videoviewport wordt gewijzigd. Gebruik deze meldingen om uw viewport opnieuw in te stellen op de huidige waarden voor videoHeight en videoWidth van het gebeurtenisdoelobject.

Tot de gemelde renderstatussen behoren:

  • RENDER_STATUS_UNAVAILABLE

  • RENDER_STATUS_SOFTWARE

  • RENDER_STATUS_ACCELERATED

Renderstatussen geven aan wanneer decodering met hardwareversnelling wordt gebruikt, ongeacht de klasse die de video momenteel afspeelt. Controleer de eigenschap StageVideoEvent.status om te zien of de vereiste decodering beschikbaar is. Wanneer deze eigenschap is ingesteld op ''unavailable'', kan het StageVideo-object de video niet afspelen. Deze status vereist dat u het NetStream-object meteen weer aan een Video-object koppelt. Andere statussen stellen uw toepassing op de hoogte van de huidige renderomstandigheden.

In de volgende tabel worden de implicaties beschreven van alle renderstatuswaarden voor StageVideoEvent- en VideoEvent-objecten in Flash Player:

 

VideoStatus.ACCELERATED

VideoStatus.SOFTWARE

VideoStatus.UNAVAILABLE

StageVideoEvent

Decodering en presentatie vinden beide plaats in de hardware. (Optimale prestaties.)

Presentatie in hardware, decodering in software. (Acceptabele prestaties.)

Er zijn geen GPU-bronnen beschikbaar om de video te verwerken en er wordt niets weergegeven. Fallback naar een Video-object.

VideoEvent

Presentatie in software, decodering in hardware. (Alleen acceptabele prestaties op een modern desktopsysteem. Mindere prestaties op volledig scherm.)

Presentatie in software, decodering in software. (Minst goede prestaties. Mindere prestaties op volledig scherm.)

(N.v.t.)

Kleurruimten

Werkgebiedvideo gebruikt de onderliggende hardwarefuncties om kleurruimten te ondersteunen. SWF-inhoud kan metagegevens verschaffen die de kleurruimte die de voorkeur geniet, aangeven. De grafische hardware bepaalt echter of de kleurruimte kan worden gebruikt. Bepaalde apparaten bieden ondersteuning voor verschillende kleurruimten, terwijl andere apparaten geen enkele kleurruimte ondersteunen. Als de hardware geen ondersteuning biedt voor de gewenste kleurruimte, probeert Flash Player de meest overeenkomende kleurruimte te vinden die wel wordt ondersteund.

Gebruik de eigenschap StageVideo.colorSpaces om te zien welke kleurruimten door de hardware worden ondersteund. Deze eigenschap retourneert de lijst met ondersteunde kleurruimten in een String-vector:

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

Controleer de eigenschap StageVideoEvent.colorSpace om te zien welke kleurruimte de momenteel afgespeelde video gebruikt. Controleer deze eigenschap in de gebeurtenishandler voor de gebeurtenis StageVideoEvent.RENDER_STATE:

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

Als Flash Player geen vervanging kan vinden voor een niet-ondersteunde kleurruimte, gebruikt werkgebiedvideo de standaardkleurruimte BT.601. Videostreams met H.264-codering maken bijvoorbeeld doorgaans gebruik van de BT.709-kleurruimte. Als de hardware geen ondersteuning biedt voor BT.709, retourneert de eigenschap colorSpace de waarde "BT601". De StageVideoEvent.colorSpace-waarde "unknown" geeft aan dat de hardware de kleurruimte niet kan opvragen.

Als uw toepassing de actieve kleurruimte niet acceptabel acht, kunt u van een StageVideo-object overschakelen op een Video-object. De Video-klasse ondersteunt alle kleurruimten via softwaresamenstelling.