Używanie interfejsów API klasy StageVideo

Właściwość Stage.stageVideos jest obiektem Vector umożliwiającym dostęp do wystąpień obiektów StageVideo. W zależności od zasobów sprzętowych i systemowych ten wektor może zawierać do czterech obiektów StageVideo. Na urządzeniach przenośnych może występować ograniczenie do jednego takiego obiektu lub obiekt może w ogóle nie być dostępny.

Gdy wideo na stole montażowym nie jest dostępne, ten wektor nie zawiera żadnych obiektów. Aby uniknąć błędów w czasie wykonywania, dostęp do elementów tego wektora należy uzyskiwać wyłącznie wtedy, gdy najnowsze zdarzenie StageVideoAvailability wskazuje, że wideo na stole montażowym jest dostępne.

Platforma interfejsów API klasy StageVideo oferuje następujące zdarzenia:

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Jest wywoływane, gdy właściwość Stage.stageVideos ulega zmianie. Właściwość StageVideoAvailabilityEvent.availability ma wartość AVAILABLE (dostępne) lub UNAVAILABLE (niedostępne). Zamiast bezpośredniego sprawdzania długości wektora Stage.stageVideos można określić za pomocą tego zdarzenia, czy właściwość stageVideos zawiera jakiekolwiek obiekty StageVideo.

StageVideoEvent.RENDER_STATE

Jest wywoływane po dołączeniu obiektu NetStream lub Camera do obiektu StageVideo, gdy obiekt NetStream jest odtwarzany. Wskazuje typ aktualnie używanego dekodowania: hardware (sprzętowe), software (programowe) lub unavailable (nieobsługiwane; brak obrazu na wyświetlaczu). Element docelowy zdarzenia zawiera właściwości videoWidth i videoHeight , których można bezpiecznie używać na potrzeby zmian rozmiaru widoku wideo.

Ważne: Współrzędne uzyskane z obiektu docelowego StageVideo są oparte na współrzędnych obiektu Stage, gdyż nie należą one do standardowej listy wyświetlania.

VideoEvent.RENDER_STATE

Jest wywoływane, gdy jest używany obiekt Video. Wskazuje, czy jest używane dekodowanie programowe czy sprzętowe. Jeśli to zdarzenie wskazuje dekodowanie z przyspieszeniem sprzętowym, należy przełączyć strumień do obiektu StageVideo, o ile jest to możliwe. Element docelowy zdarzenia Video zawiera właściwości videoWidth i videoHeight , których można bezpiecznie używać na potrzeby zmian rozmiaru widoku wideo.

W celu uwzględnienia funkcji StageVideo w implementacji należy wykonać następujące ogólne czynności:

1. Aby wiedzieć, kiedy wektor Stage.stageVideos ulega zmianie, należy wykrywać zdarzenie StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY . Zobacz Używanie zdarzenia StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY .

2. Jeśli zdarzenie StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY zgłasza, że jest dostępne wideo na stole montażowym, należy uzyskać dostęp do obiektu StageVideo, używając w detektorze zdarzeń obiektu Stage.stageVideos klasy Vector.

3. Dołącz obiekt NetStream przy użyciu metody StageVideo.attachNetStream() lub obiekt Camera przy użyciu metody StageVideo.attachCamera() .

4. Należy odtworzyć wideo za pomocą metody NetStream.play() .

5. Aby sprawdzić stan odtwarzania wideo, należy wykryć zdarzenie StageVideoEvent.RENDER_STATE wywoływane przez obiekt StageVideo. Odebranie tego zdarzenia oznacza również, że właściwości szerokości i wysokości wideo zostały zainicjowane lub zmienione. Zobacz Używanie zdarzeń StageVideoEvent.RENDER_STATE i VideoEvent.RENDER_STATE .

6. Należy wykrywać zdarzenie VideoEvent.RENDER_STATE wywoływane przez obiekt Video. To zdarzenie oferuje te same stany co zdarzenie StageVideoEvent.RENDER_STATE , dlatego pozwala również określić, czy jest dostępne przyspieszanie GPU. Odebranie tego zdarzenia oznacza również, że właściwości szerokości i wysokości wideo zostały zainicjowane lub zmienione. Zobacz Używanie zdarzeń StageVideoEvent.RENDER_STATE i VideoEvent.RENDER_STATE .

Detektory StageVideoAvailabilityEvent i VideoEvent należy skonfigurować podczas inicjowania aplikacji. Na przykład można je skonfigurować w module obsługi zdarzeń flash.events.Event.ADDED_TO_STAGE . To zdarzenie gwarantuje, że aplikacja jest widoczna na stole montażowym:

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

W module obsługi StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY należy na podstawie dostępności obiektu StageVideo podjąć decyzję, czy używać obiektu Video czy StageVideo. Jeśli dla właściwości StageVideoAvailabilityEvent.availability jest ustawiona wartość StageVideoAvailability.AVAILABLE , należy użyć obiektu StageVideo. W takim przypadku można założyć, że wektor Stage.stageVideos będzie zawierać co najmniej jeden obiekt StageVideo. Należy uzyskać obiekt StageVideo z właściwości Stage.stageVideos i dołączyć do niego obiekt NetStream. Obiekt StageVideo jest zawsze wyświetlany w tle, dlatego należy usunąć obiekt Video (który jest zawsze wyświetlany na pierwszym planie). W tym module obsługi zdarzeń można również dodać moduł obsługi zdarzenia StageVideoEvent.RENDER_STATE .

Jeśli dla właściwości StageVideoAvailabilityEvent.availability ustawiono wartość StageVideoAvailability.UNAVAILABLE , nie należy używać obiektu StageVideo ani korzystać z wektora Stage.stageVideos . W tym przypadku należy dołączyć obiekt NetStream do obiektu Video. Na końcu należy dodać obiekt StageVideo lub Video do stołu montażowego i wywołać metodę NetStream.play() .

Poniższy kod ilustruje sposób obsługi zdarzenia 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); 
    } 
} 

Kod źródłowy tej przykładowej aplikacji można pobrać na stronie Pierwsze kroki z wideo na stole montażowym .

Obiekty StageVideo i Video wywołują zdarzenia informujące aplikacje o zmianach środowiska wyświetlania. Są to zdarzenia StageVideoEvent.RENDER_STATE i VideoEvent.RENDER_STATE .

Obiekt StageVideo lub Video wywołuje zdarzenie dotyczące stanu renderowania, gdy następuje dołączenie do niego obiektu NetStream i rozpoczęcie odtwarzania tego obiektu. Zdarzenie to jest również wywoływane w przypadku zmian środowiska wyświetlania, takich jak modyfikacja rozmiaru widoku wideo. Zależnie od tych powiadomień należy zerować widok w celu dopasowania go do bieżących wartości videoHeight i videoWidth obiektu docelowego zdarzenia.

Zgłaszane stany renderowania:

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

Stany renderowania wskazują, kiedy jest używane dekodowanie z przyspieszaniem sprzętowym — niezależnie od tego, która klasa odtwarza wideo w danej chwili. Aby sprawdzić, czy jest dostępny wymagany mechanizm dekodowania, należy odczytać właściwość StageVideoEvent.status . Jeśli ma ona wartość unavailable (niedostępne), obiekt StageVideo nie może odtwarzać wideo. Ten stan wymaga natychmiastowego przełączenia obiektu NetStream do obiektu Video. Inne stany informują aplikację o bieżących warunkach renderowania.

W poniższej tabeli wyjaśniono znaczenia poszczególnych wartości stanów renderowania obiektów StageVideoEvent i VideoEvent w programie Flash Player:

Wideo na sole montażowym obsługuje przestrzenie kolorów za pomocą podstawowych funkcji sprzętowych. Zawartość SWF może stanowić źródło metadanych wskazujących preferowaną przestrzeń kolorów. To, czy można korzystać z przestrzeni kolorów, jest jednak zależne od możliwości sprzętowych urządzenia. Jedno urządzenie może obsługiwać kilka przestrzeni kolorów, podczas gdy inne nie obsługuje żadnych. Jeśli urządzenie nie obsługuje wymaganej przestrzeni kolorów, program Flash Player próbuje znaleźć najbliższe dopasowanie spośród obsługiwanych przestrzeni kolorów.

Informacje na temat tego, które przestrzenie kolorów są obsługiwane przez urządzenie, można uzyskać, odczytując właściwość StageVideo.colorSpaces . Ta właściwość zwraca listę obsługiwanych przestrzeni kolorów w wektorze obiektów String.

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

Aby dowiedzieć się, które przestrzeń kolorów są używane przez aktualnie odtwarzane wideo, należy sprawdzić właściwość StageVideoEvent.colorSpace . Tę właściwość należy sprawdzić w module obsługi zdarzenia StageVideoEvent.RENDER_STATE .

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

Jeśli program Flash Player nie może znaleźć substytutu nieobsługiwanej przestrzeni kolorów, wideo na stole montażowym korzysta z domyślnej przestrzeni kolorów standardu BT.601. Na przykład strumienie wideo z kodowaniem H.264 korzystają zazwyczaj z przestrzeni kolorów standardu BT.709. Jeśli urządzenie nie obsługuje przestrzeni kolorów BT.709, właściwość colorSpace zwraca wartość "BT601" . Wartość "unknown" właściwości StageVideoEvent.colorSpace oznacza, że urządzenie nie oferuje możliwości uzyskania danych na temat przestrzeni kolorów.

Jeśli aplikacja uznaje aktualną przestrzeń kolorów za nie do przyjęcia, można podjąć decyzję o przełączeniu strumienia z obiektu StageVideo do obiektu Video. Klasa Video obsługuje wszystkie przestrzenie kolorów w przypadku programowego tworzenia kompozycji.