Utilizzo delle API StageVideo

La proprietà Stage.stageVideos è un oggetto Vector che consente di accedere alle istanze StageVideo. Questo vettore può contenere un massimo di quattro oggetti StageVideo, in base alle risorse hardware e di sistema. I dispositivi mobili possono essere limitati a uno solo o nessuno.

Se video sullo stage non è disponibile, questo vettore non contiene nessun oggetto. Per evitare errori in fase di esecuzione, accertatevi di accedere ai membri di questo vettore solo quando l'evento StageVideoAvailability più recente indica che video sullo stage è disponibile.

Il framework API StageVideo fornisce gli eventi seguenti:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Inviato quando la proprietà Stage.stageVideos cambia. La proprietà StageVideoAvailabilityEvent.availability indica AVAILABLE o UNAVAILABLE . Utilizzare questo evento per determinare se la proprietà stageVideos contiene eventuali oggetti StageVideo, anziché controllando direttamente la lunghezza del vettore Stage.stageVideos .

StageVideoEvent.RENDER_STATE

Inviato quando un oggetto NetStream o Camera è stato allegato a un oggetto StageVideo ed è in fase di riproduzione. Indica il tipo di decodifica attualmente in uso: hardware, software o non disponibile (nessuna visualizzazione). Il destinatario dell'evento contiene le proprietà videoWidth e videoHeight utilizzabili per ridimensionare il riquadro di visualizzazione video.

Importante: le coordinate ottenute dall'oggetto di destinazione StageVideo utilizzano le coordinate Stage, poiché non fanno parte dell'elenco di visualizzazione standard.

VideoEvent.RENDER_STATE

Inviato durante l'utilizzo di un oggetto Video. Indica se è utilizzata la decodifica con accelerazione hardware o software. Se l'evento indica decodifica con accelerazione hardware, passare a un oggetto StageVideo se possibile. Il destinatario dell'evento Video contiene le proprietà videoWidth e videoHeight utilizzabili per ridimensionare il riquadro di visualizzazione video.

Seguire i passaggi di alto livello sottostanti per implementare la funzione StageVideo:

1. Intercettate l'evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY per rilevare il momento in cui il vettore Stage.stageVideos viene modificato. Consultate Uso dell'evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY .

2. Se l'evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY segnala che stage video è disponibile, usate l'oggetto Vector Stage.stageVideos all'interno del gestore di eventi per accedere a un oggetto StageVideo.

3. Associate un oggetto NetStream utilizzando StageVideo.attachNetStream() oppure un oggetto Camera mediante StageVideo.attachCamera() .

4. Riproducete il video utilizzando NetStream.play() .

5. Intercettate l'evento StageVideoEvent.RENDER_STATE sull'oggetto StageVideo per determinare lo stato di riproduzione del video. Il ricevimento di questo evento indica inoltre che le proprietà relative alla larghezza e all'altezza del video sono state inizializzate o modificate. Vedete Uso degli eventi StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE .

6. Intercettate l'evento VideoEvent.RENDER_STATE dell'oggetto Video. Questo evento presenta gli stessi stati di StageVideoEvent.RENDER_STATE , quindi potete usarlo anche per determinare se è disponibile l'accelerazione tramite GPU. Il ricevimento di questo evento indica inoltre che le proprietà relative alla larghezza e all'altezza del video sono state inizializzate o modificate. Vedete Uso degli eventi StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE .

Impostate i listener StageVideoAvailabilityEvent e VideoEvent durante l'inizializzazione dell'applicazione. Ad esempio, potete inizializzare questi listener nel gestore eventi flash.events.Event.ADDED_TO_STAGE . Questo evento garantisce che l'applicazione è visibile sullo 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); 
        //... 
    }

Nel gestore StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY , decidete se utilizzare un oggetto Video o StageVideo in base alla disponibilità di StageVideo. Se la proprietà StageVideoAvailabilityEvent.availability è impostata su StageVideoAvailability.AVAILABLE , utilizzate StageVideo. In questo caso, potete fare affidamento sul vettore Stage.stageVideos per contenere uno o più oggetti StageVideo. Ottenete un oggetto StageVideo dalla proprietà Stage.stageVideos e allegate ad esso l'oggetto NetStream. Poiché gli oggetti StageVideo appaiono sempre sullo sfondo, rimuovete eventuali oggetti Video esistenti (sempre in primo piano). Utilizzate inoltre questo gestore eventi per aggiungere un listener per l'evento StageVideoEvent.RENDER_STATE .

Se la proprietà StageVideoAvailabilityEvent.availability è impostata su StageVideoAvailability.UNAVAILABLE , non utilizzate StageVideo né effettuate l'accesso al vettore Stage.stageVideos . In questo caso, allegate l'oggetto NetStream a un oggetto Video. Infine, aggiungete l'oggetto StageVideo o Video allo stage e chiamate NetStream.play() .

Il codice seguente mostra come gestire l'evento 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); 
    } 
} 

Scaricate il codice di origine completo per questa applicazione di esempio da Getting Started with Stage Video (Guida introduttiva a video sullo stage).

Gli oggetti StageVideo e Video inviano eventi che informano le applicazioni quando l'ambiente di visualizzazione cambia. Questi eventi sono StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE .

Un oggetto StageVideo o Video invia un evento stato rendering quando un oggetto NetStream viene allegato e inizia la riproduzione. Questo evento viene inviato anche quando l'ambiente di visualizzazione cambia; ad esempio, quando il riquadro di visualizzazione video viene ridimensionato. Utilizzate queste notifiche per ripristinare il riquadro di visualizzazione ai valori videoHeight e videoWidth correnti dell'oggetto destinatario dell'evento.

Gli stati di rendering segnalati includono:

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

Gli stati di rendering indicano quando la decodifica con accelerazione hardware è in uso, indipendentemente dalla classe corrente che esegue la riproduzione video. Controllate la proprietà StageVideoEvent.status per apprendere se la decodifica necessaria è disponibile. Se questa proprietà è impostata su “unavailable”, l'oggetto StageVideo non può riprodurre il video. Questo stato richiede che l'oggetto NetStream venga immediatamente ricollegato a un oggetto Video. Altri stati informano l'applicazione delle condizioni di rendering correnti.

La tabella seguente descrive le implicazioni di tutti i valori dello stato di rendering per gli oggetti StageVideoEvent e VideoEvent in Flash Player:

Video sullo stage utilizza le funzionalità sottostanti per supportare spazi colore. Il contenuto SWF può fornire metadati che indicano lo spazio colore preferito. Tuttavia, l'hardware grafico del dispositivo determina se lo spazio colore può essere utilizzato. Un dispositivo può supportare diversi spazi colore, mentre un altro non ne supporta nessuno. Se l'hardware non supporta lo spazio colore richiesto, Flash Player ricerca la corrispondenza più vicina tra gli spazi colore supportati.

Per verificare quali spazi colore sono supportati dall'hardware, utilizzare la proprietà StageVideo.colorSpaces . Questa proprietà restituisce l'elenco degli spazi colore supportati in un vettore String:

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

Per conoscere lo spazio colore utilizzato dal video attualmente riprodotto, controllare la proprietà StageVideoEvent.colorSpace nel gestore eventi per l'evento StageVideoEvent.RENDER_STATE :

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

Se Flash Player non è in grado di trovare un sostituto per uno spazio colore non supportato, video sullo stage utilizza lo spazio colore predefinito BT.601. Ad esempio, flussi video con codifica H.264 utilizzano in genere lo spazio colore BT.709. Se l'hardware del dispositivo non supporta BT.709, la proprietà colorSpace restituisce "BT601" . Un valore StageVideoEvent.colorSpace pari a "unknown" indica che l'hardware non fornisce un metodo per eseguire la query dello spazio colore.

Se l'applicazione reputa inaccettabile lo spazio colore corrente, potete scegliere di passare da un oggetto StageVideo a un oggetto Video. La classe Video supporta tutti gli spazi colore tramite la composizione software.