dom/media/MediaDecoderOwner.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6 #ifndef MediaDecoderOwner_h_
   7 #define MediaDecoderOwner_h_
   8
   9 #include "mozilla/UniquePtr.h"
  10 #include "MediaInfo.h"
  11 #include "MediaSegment.h"
  12 #include "nsSize.h"
  13 #include "TrackID.h"
  14
  15 namespace mozilla {
  16
  17 class AbstractThread;
  18 class GMPCrashHelper;
  19 class VideoFrameContainer;
  20 class MediaInfo;
  21 class MediaResult;
  22
  23 namespace dom {
  24 class Document;
  25 class HTMLMediaElement;
  26 }  // namespace dom
  27
  28 class MediaDecoderOwner {
  29  public:
  30   // Called by the media decoder to indicate that the download is progressing.
  31   virtual void DownloadProgressed() = 0;
  32
  33   // Dispatch an asynchronous event to the decoder owner
  34   virtual void DispatchAsyncEvent(const nsAString& aName) = 0;
  35
  36   // Triggers a recomputation of readyState.
  37   virtual void UpdateReadyState() = 0;
  38
  39   /**
  40    * Fires a timeupdate event. If aPeriodic is true, the event will only
  41    * be fired if we've not fired a timeupdate event (for any reason) in the
  42    * last 250ms, as required by the spec when the current time is periodically
  43    * increasing during playback.
  44    */
  45   virtual void FireTimeUpdate(bool aPeriodic) = 0;
  46
  47   // Return true if decoding should be paused
  48   virtual bool GetPaused() = 0;
  49
  50   // Called by the video decoder object, on the main thread,
  51   // when it has read the metadata containing video dimensions,
  52   // etc.
  53   // Must take ownership of MetadataTags aTags argument.
  54   virtual void MetadataLoaded(const MediaInfo* aInfo,
  55                               UniquePtr<const MetadataTags> aTags) = 0;
  56
  57   // Called by the decoder object, on the main thread,
  58   // when it has read the first frame of the video or audio.
  59   virtual void FirstFrameLoaded() = 0;
  60
  61   // Called by the decoder object, on the main thread,
  62   // when the resource has a network error during loading.
  63   // The decoder owner should call Shutdown() on the decoder and drop the
  64   // reference to the decoder to prevent further calls into the decoder.
  65   virtual void NetworkError(const MediaResult& aError) = 0;
  66
  67   // Called by the decoder object, on the main thread, when the
  68   // resource has a decode error during metadata loading or decoding.
  69   // The decoder owner should call Shutdown() on the decoder and drop the
  70   // reference to the decoder to prevent further calls into the decoder.
  71   virtual void DecodeError(const MediaResult& aError) = 0;
  72
  73   // Called by the decoder object, on the main thread, when the
  74   // resource has a decode issue during metadata loading or decoding, but can
  75   // continue decoding.
  76   virtual void DecodeWarning(const MediaResult& aError) = 0;
  77
  78   // Return true if media element error attribute is not null.
  79   virtual bool HasError() const = 0;
  80
  81   // Called by the video decoder object, on the main thread, when the
  82   // resource load has been cancelled.
  83   virtual void LoadAborted() = 0;
  84
  85   // Called by the video decoder object, on the main thread,
  86   // when the video playback has ended.
  87   virtual void PlaybackEnded() = 0;
  88
  89   // Called by the video decoder object, on the main thread,
  90   // when the resource has started seeking.
  91   virtual void SeekStarted() = 0;
  92
  93   // Called by the video decoder object, on the main thread,
  94   // when the resource has completed seeking.
  95   virtual void SeekCompleted() = 0;
  96
  97   // Called by the media stream, on the main thread, when the download
  98   // has been suspended by the cache or because the element itself
  99   // asked the decoder to suspend the download.
 100   virtual void DownloadSuspended() = 0;
 101
 102   // Called by the media decoder to indicate whether the media cache has
 103   // suspended the channel.
 104   virtual void NotifySuspendedByCache(bool aSuspendedByCache) = 0;
 105
 106   // called to notify that the principal of the decoder's media resource has
 107   // changed.
 108   virtual void NotifyDecoderPrincipalChanged() = 0;
 109
 110   // The status of the next frame which might be available from the decoder
 111   enum NextFrameStatus {
 112     // The next frame of audio/video is available
 113     NEXT_FRAME_AVAILABLE,
 114     // The next frame of audio/video is unavailable because the decoder
 115     // is paused while it buffers up data
 116     NEXT_FRAME_UNAVAILABLE_BUFFERING,
 117     // The next frame of audio/video is unavailable for the decoder is seeking.
 118     NEXT_FRAME_UNAVAILABLE_SEEKING,
 119     // The next frame of audio/video is unavailable for some other reasons
 120     NEXT_FRAME_UNAVAILABLE,
 121     // Sentinel value
 122     NEXT_FRAME_UNINITIALIZED
 123   };
 124
 125   // Called by media decoder when the audible state changed
 126   virtual void SetAudibleState(bool aAudible) = 0;
 127
 128   // Notified by the decoder that XPCOM shutdown has begun.
 129   // The decoder owner should call Shutdown() on the decoder and drop the
 130   // reference to the decoder to prevent further calls into the decoder.
 131   virtual void NotifyXPCOMShutdown() = 0;
 132
 133   // Dispatches a "encrypted" event to the HTMLMediaElement, with the
 134   // provided init data. Actual dispatch may be delayed until HAVE_METADATA.
 135   // Main thread only.
 136   virtual void DispatchEncrypted(const nsTArray<uint8_t>& aInitData,
 137                                  const nsAString& aInitDataType) = 0;
 138
 139   // Called by the media decoder to create audio/video tracks and add to its
 140   // owner's track list.
 141   virtual void ConstructMediaTracks(const MediaInfo* aInfo) = 0;
 142
 143   // Called by the media decoder to removes all audio/video tracks from its
 144   // owner's track list.
 145   virtual void RemoveMediaTracks() = 0;
 146
 147   // Called by the media decoder to notify the owner to resolve a seek promise.
 148   virtual void AsyncResolveSeekDOMPromiseIfExists() = 0;
 149
 150   // Called by the media decoder to notify the owner to reject a seek promise.
 151   virtual void AsyncRejectSeekDOMPromiseIfExists() = 0;
 152
 153   // Notified by the decoder that a decryption key is required before emitting
 154   // further output.
 155   virtual void NotifyWaitingForKey() {}
 156
 157   /*
 158    * Methods that are used only in Gecko go here. We provide defaul
 159    * implementations so they can compile in Servo without modification.
 160    */
 161   // Return an abstract thread on which to run main thread runnables.
 162   virtual AbstractThread* AbstractMainThread() const { return nullptr; }
 163
 164   // Get the HTMLMediaElement object if the decoder is being used from an
 165   // HTML media element, and null otherwise.
 166   virtual dom::HTMLMediaElement* GetMediaElement() { return nullptr; }
 167
 168   // Called by the media decoder and the video frame to get the
 169   // ImageContainer containing the video data.
 170   virtual VideoFrameContainer* GetVideoFrameContainer() { return nullptr; }
 171
 172   // Return the decoder owner's owner document.
 173   virtual mozilla::dom::Document* GetDocument() const { return nullptr; }
 174
 175   // Called by the media decoder to create a GMPCrashHelper.
 176   virtual already_AddRefed<GMPCrashHelper> CreateGMPCrashHelper() {
 177     return nullptr;
 178   }
 179
 180   // Called by the frame container to notify the layout engine that the
 181   // size of the image has changed, or the video needs to be be repainted
 182   // for some other reason.
 183   virtual void Invalidate(bool aImageSizeChanged,
 184                           Maybe<nsIntSize>& aNewIntrinsicSize,
 185                           bool aForceInvalidate) {}
 186
 187   // Called after the MediaStream we're playing rendered a frame to aContainer
 188   // with a different principalHandle than the previous frame.
 189   virtual void PrincipalHandleChangedForVideoFrameContainer(
 190       VideoFrameContainer* aContainer,
 191       const PrincipalHandle& aNewPrincipalHandle) {}
 192
 193   /*
 194    * Servo only methods go here. Please provide default implementations so they
 195    * can build in Gecko without any modification.
 196    */
 197 };
 198
 199 }  // namespace mozilla
 200
 201 #endif