michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim:set ts=2 sw=2 sts=2 et cindent: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #if !defined(PlatformDecoderModule_h_)
michael@0: #define PlatformDecoderModule_h_
michael@0: 
michael@0: #include "MediaDecoderReader.h"
michael@0: #include "mozilla/layers/LayersTypes.h"
michael@0: #include "nsTArray.h"
michael@0: #include "mozilla/RefPtr.h"
michael@0: #include <queue>
michael@0: 
michael@0: namespace mp4_demuxer {
michael@0: class VideoDecoderConfig;
michael@0: class AudioDecoderConfig;
michael@0: struct MP4Sample;
michael@0: }
michael@0: 
michael@0: class nsIThreadPool;
michael@0: 
michael@0: namespace mozilla {
michael@0: 
michael@0: namespace layers {
michael@0: class ImageContainer;
michael@0: }
michael@0: 
michael@0: class MediaDataDecoder;
michael@0: class MediaDataDecoderCallback;
michael@0: class MediaInputQueue;
michael@0: class MediaTaskQueue;
michael@0: typedef int64_t Microseconds;
michael@0: 
michael@0: // The PlatformDecoderModule interface is used by the MP4Reader to abstract
michael@0: // access to the H264 and AAC decoders provided by various platforms. It
michael@0: // may be extended to support other codecs in future. Each platform (Windows,
michael@0: // MacOSX, Linux, B2G etc) must implement a PlatformDecoderModule to provide
michael@0: // access to its decoders in order to get decompressed H.264/AAC from the
michael@0: // MP4Reader.
michael@0: //
michael@0: // Video decoding is asynchronous, and should be performed on the task queue
michael@0: // provided if the underlying platform isn't already exposing an async API.
michael@0: //
michael@0: // Platforms that don't have a corresponding PlatformDecoderModule won't be
michael@0: // able to play the H.264/AAC data output by the MP4Reader. In practice this
michael@0: // means that we won't have fragmented MP4 supported in Media Source
michael@0: // Extensions.
michael@0: //
michael@0: // A cross-platform decoder module that discards input and produces "blank"
michael@0: // output samples exists for testing, and is created when the pref
michael@0: // "media.fragmented-mp4.use-blank-decoder" is true.
michael@0: class PlatformDecoderModule {
michael@0: public:
michael@0:   // Call on the main thread to initialize the static state
michael@0:   // needed by Create().
michael@0:   static void Init();
michael@0: 
michael@0:   // Factory method that creates the appropriate PlatformDecoderModule for
michael@0:   // the platform we're running on. Caller is responsible for deleting this
michael@0:   // instance. It's expected that there will be multiple
michael@0:   // PlatformDecoderModules alive at the same time. There is one
michael@0:   // PlatformDecoderModule created per MP4Reader.
michael@0:   // This is called on the decode thread.
michael@0:   static PlatformDecoderModule* Create();
michael@0: 
michael@0:   // Called to shutdown the decoder module and cleanup state. This should
michael@0:   // block until shutdown is complete. This is called after Shutdown() has
michael@0:   // been called on all MediaDataDecoders created from this
michael@0:   // PlatformDecoderModule.
michael@0:   // Called on the main thread only.
michael@0:   virtual nsresult Shutdown() = 0;
michael@0: 
michael@0:   // Creates an H.264 decoder. The layers backend is passed in so that
michael@0:   // decoders can determine whether hardware accelerated decoding can be used.
michael@0:   // Asynchronous decoding of video should be done in runnables dispatched
michael@0:   // to aVideoTaskQueue. If the task queue isn't needed, the decoder should
michael@0:   // not hold a reference to it.
michael@0:   // Output and errors should be returned to the reader via aCallback.
michael@0:   // On Windows the task queue's threads in have MSCOM initialized with
michael@0:   // COINIT_MULTITHREADED.
michael@0:   // Returns nullptr if the decoder can't be created.
michael@0:   // It is safe to store a reference to aConfig.
michael@0:   // Called on decode thread.
michael@0:   virtual MediaDataDecoder* CreateH264Decoder(const mp4_demuxer::VideoDecoderConfig& aConfig,
michael@0:                                               layers::LayersBackend aLayersBackend,
michael@0:                                               layers::ImageContainer* aImageContainer,
michael@0:                                               MediaTaskQueue* aVideoTaskQueue,
michael@0:                                               MediaDataDecoderCallback* aCallback) = 0;
michael@0: 
michael@0:   // Creates an AAC decoder with the specified properties.
michael@0:   // Asynchronous decoding of audio should be done in runnables dispatched to
michael@0:   // aAudioTaskQueue. If the task queue isn't needed, the decoder should
michael@0:   // not hold a reference to it.
michael@0:   // Output and errors should be returned to the reader via aCallback.
michael@0:   // Returns nullptr if the decoder can't be created.
michael@0:   // On Windows the task queue's threads in have MSCOM initialized with
michael@0:   // COINIT_MULTITHREADED.
michael@0:   // It is safe to store a reference to aConfig.
michael@0:   // Called on decode thread.
michael@0:   virtual MediaDataDecoder* CreateAACDecoder(const mp4_demuxer::AudioDecoderConfig& aConfig,
michael@0:                                              MediaTaskQueue* aAudioTaskQueue,
michael@0:                                              MediaDataDecoderCallback* aCallback) = 0;
michael@0: 
michael@0:   virtual ~PlatformDecoderModule() {}
michael@0: 
michael@0: protected:
michael@0:   PlatformDecoderModule() {}
michael@0:   // Caches pref media.fragmented-mp4.use-blank-decoder
michael@0:   static bool sUseBlankDecoder;
michael@0:   static bool sFFmpegDecoderEnabled;
michael@0: };
michael@0: 
michael@0: // A callback used by MediaDataDecoder to return output/errors to the
michael@0: // MP4Reader. Implementation is threadsafe, and can be called on any thread.
michael@0: class MediaDataDecoderCallback {
michael@0: public:
michael@0:   virtual ~MediaDataDecoderCallback() {}
michael@0: 
michael@0:   // Called by MediaDataDecoder when a sample has been decoded. Callee is
michael@0:   // responsibile for deleting aData.
michael@0:   virtual void Output(MediaData* aData) = 0;
michael@0: 
michael@0:   // Denotes an error in the decoding process. The reader will stop calling
michael@0:   // the decoder.
michael@0:   virtual void Error() = 0;
michael@0: 
michael@0:   // Denotes that the last input sample has been inserted into the decoder,
michael@0:   // and no more output can be produced unless more input is sent.
michael@0:   virtual void InputExhausted() = 0;
michael@0: };
michael@0: 
michael@0: // MediaDataDecoder is the interface exposed by decoders created by the
michael@0: // PlatformDecoderModule's Create*Decoder() functions. The type of
michael@0: // media data that the decoder accepts as valid input and produces as
michael@0: // output is determined when the MediaDataDecoder is created.
michael@0: //
michael@0: // All functions must be threadsafe, and be able to be called on an
michael@0: // arbitrary thread.
michael@0: //
michael@0: // Decoding is done asynchronously. Any async work can be done on the
michael@0: // MediaTaskQueue passed into the PlatformDecoderModules's Create*Decoder()
michael@0: // function. This may not be necessary for platforms with async APIs
michael@0: // for decoding.
michael@0: class MediaDataDecoder {
michael@0: protected:
michael@0:   virtual ~MediaDataDecoder() {};
michael@0: 
michael@0: public:
michael@0:   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaDataDecoder)
michael@0: 
michael@0:   // Initialize the decoder. The decoder should be ready to decode after
michael@0:   // this returns. The decoder should do any initialization here, rather
michael@0:   // than in its constructor or PlatformDecoderModule::Create*Decoder(),
michael@0:   // so that if the MP4Reader needs to shutdown during initialization,
michael@0:   // it can call Shutdown() to cancel this operation. Any initialization
michael@0:   // that requires blocking the calling thread in this function *must*
michael@0:   // be done here so that it can be canceled by calling Shutdown()!
michael@0:   virtual nsresult Init() = 0;
michael@0: 
michael@0:   // Inserts a sample into the decoder's decode pipeline. The decoder must
michael@0:   // delete the sample once its been decoded. If Input() returns an error,
michael@0:   // aSample will be deleted by the caller.
michael@0:   virtual nsresult Input(mp4_demuxer::MP4Sample* aSample) = 0;
michael@0: 
michael@0:   // Causes all samples in the decoding pipeline to be discarded. When
michael@0:   // this function returns, the decoder must be ready to accept new input
michael@0:   // for decoding. This function is called when the demuxer seeks, before
michael@0:   // decoding resumes after the seek.
michael@0:   // While the reader calls Flush(), it ignores all output sent to it;
michael@0:   // it is safe (but pointless) to send output while Flush is called.
michael@0:   // The MP4Reader will not call Input() while it's calling Flush().
michael@0:   virtual nsresult Flush() = 0;
michael@0: 
michael@0:   // Causes all complete samples in the pipeline that can be decoded to be
michael@0:   // output. If the decoder can't produce samples from the current output,
michael@0:   // it drops the input samples. The decoder may be holding onto samples
michael@0:   // that are required to decode samples that it expects to get in future.
michael@0:   // This is called when the demuxer reaches end of stream.
michael@0:   // The MP4Reader will not call Input() while it's calling Drain().
michael@0:   virtual nsresult Drain() = 0;
michael@0: 
michael@0:   // Cancels all init/input/drain operations, and shuts down the
michael@0:   // decoder. The platform decoder should clean up any resources it's using
michael@0:   // and release memory etc. Shutdown() must block until the decoder has
michael@0:   // completed shutdown. The reader calls Flush() before calling Shutdown().
michael@0:   // The reader will delete the decoder once Shutdown() returns.
michael@0:   // The MediaDataDecoderCallback *must* not be called after Shutdown() has
michael@0:   // returned.
michael@0:   virtual nsresult Shutdown() = 0;
michael@0: 
michael@0: };
michael@0: 
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif