Utilizzo delle API StageVideo

Video sullo stage è un meccanismo all'interno del runtime che migliora la riproduzione video e le prestazioni del dispositivo. Il runtime crea e mantiene questo meccanismo; in qualità di sviluppatore, il vostro ruolo è configurare l'applicazione per trarne vantaggio.

Per utilizzare video sullo stage, implementate un framework di gestori di eventi che rilevano quando video sullo stage è o non è visibile. Quando ricevete la notifica che video sullo stage è disponibile, recuperate un oggetto StageVideo dalla proprietà Stage.stageVideos . Il runtime compila questo oggetto Vector con uno o più oggetti StageVideo. Potete quindi utilizzare uno degli oggetti StageVideo forniti, anziché un oggetto Video, per visualizzare video in streaming.

In Flash Player, quando ricevete la notifica che stage video non è più disponibile, riportate lo streaming video su un oggetto Video.

Nota: non potete creare oggetti StageVideo.

Proprietà Stage.stageVideos

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.

Eventi StageVideo

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.

Flusso di lavoro per l'implementazione della funzione StageVideo

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 .

Inizializzazione dei listener di eventi StageVideo

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

Uso dell'evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

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); 
    } 
} 
Importante: la prima volta che l'applicazione accede all'elemento vettore in corrispondenza di Stage.stageVideos[0], il rettangolo predefinito viene impostato su 0,0,0,0, mentre per le proprietà pan e zoom vengono utilizzati i valori predefiniti. Ripristinate sempre le impostazioni predefinite di questi valori. Potete utilizzare le proprietà videoWidth e videoHeight del destinatario dell'evento StageVideoEvent.RENDER_STATE o VideoEvent.RENDER_STATE per calcolare le dimensioni del riquadro di visualizzazione video.

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

Uso degli eventi StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE

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:

VideoStatus.ACCELERATED

VideoStatus.SOFTWARE

VideoStatus.UNAVAILABLE

StageVideoEvent

La decodifica e la presentazione vengono entrambe eseguite in hardware. (Migliori prestazioni.)

Presentazione in hardware, decodifica in software. (Prestazioni accettabili.)

Nessuna risorsa GPU disponibile per la gestione del video e nessun video visualizzato. Ripiegamento su un oggetto Video.

VideoEvent

Presentazione in software, decodifica in hardware. (Prestazioni accettabili solo su un sistema desktop moderno. Prestazioni a schermo intero ridotte.)

Presentazione in software, decodifica in software. (Peggior caso di prestazioni. Prestazioni a schermo intero ridotte.)

(N/D)

Spazi colore

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.