1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/media/fmp4/PlatformDecoderModule.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,197 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim:set ts=2 sw=2 sts=2 et cindent: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#if !defined(PlatformDecoderModule_h_)
1.11 +#define PlatformDecoderModule_h_
1.12 +
1.13 +#include "MediaDecoderReader.h"
1.14 +#include "mozilla/layers/LayersTypes.h"
1.15 +#include "nsTArray.h"
1.16 +#include "mozilla/RefPtr.h"
1.17 +#include <queue>
1.18 +
1.19 +namespace mp4_demuxer {
1.20 +class VideoDecoderConfig;
1.21 +class AudioDecoderConfig;
1.22 +struct MP4Sample;
1.23 +}
1.24 +
1.25 +class nsIThreadPool;
1.26 +
1.27 +namespace mozilla {
1.28 +
1.29 +namespace layers {
1.30 +class ImageContainer;
1.31 +}
1.32 +
1.33 +class MediaDataDecoder;
1.34 +class MediaDataDecoderCallback;
1.35 +class MediaInputQueue;
1.36 +class MediaTaskQueue;
1.37 +typedef int64_t Microseconds;
1.38 +
1.39 +// The PlatformDecoderModule interface is used by the MP4Reader to abstract
1.40 +// access to the H264 and AAC decoders provided by various platforms. It
1.41 +// may be extended to support other codecs in future. Each platform (Windows,
1.42 +// MacOSX, Linux, B2G etc) must implement a PlatformDecoderModule to provide
1.43 +// access to its decoders in order to get decompressed H.264/AAC from the
1.44 +// MP4Reader.
1.45 +//
1.46 +// Video decoding is asynchronous, and should be performed on the task queue
1.47 +// provided if the underlying platform isn't already exposing an async API.
1.48 +//
1.49 +// Platforms that don't have a corresponding PlatformDecoderModule won't be
1.50 +// able to play the H.264/AAC data output by the MP4Reader. In practice this
1.51 +// means that we won't have fragmented MP4 supported in Media Source
1.52 +// Extensions.
1.53 +//
1.54 +// A cross-platform decoder module that discards input and produces "blank"
1.55 +// output samples exists for testing, and is created when the pref
1.56 +// "media.fragmented-mp4.use-blank-decoder" is true.
1.57 +class PlatformDecoderModule {
1.58 +public:
1.59 + // Call on the main thread to initialize the static state
1.60 + // needed by Create().
1.61 + static void Init();
1.62 +
1.63 + // Factory method that creates the appropriate PlatformDecoderModule for
1.64 + // the platform we're running on. Caller is responsible for deleting this
1.65 + // instance. It's expected that there will be multiple
1.66 + // PlatformDecoderModules alive at the same time. There is one
1.67 + // PlatformDecoderModule created per MP4Reader.
1.68 + // This is called on the decode thread.
1.69 + static PlatformDecoderModule* Create();
1.70 +
1.71 + // Called to shutdown the decoder module and cleanup state. This should
1.72 + // block until shutdown is complete. This is called after Shutdown() has
1.73 + // been called on all MediaDataDecoders created from this
1.74 + // PlatformDecoderModule.
1.75 + // Called on the main thread only.
1.76 + virtual nsresult Shutdown() = 0;
1.77 +
1.78 + // Creates an H.264 decoder. The layers backend is passed in so that
1.79 + // decoders can determine whether hardware accelerated decoding can be used.
1.80 + // Asynchronous decoding of video should be done in runnables dispatched
1.81 + // to aVideoTaskQueue. If the task queue isn't needed, the decoder should
1.82 + // not hold a reference to it.
1.83 + // Output and errors should be returned to the reader via aCallback.
1.84 + // On Windows the task queue's threads in have MSCOM initialized with
1.85 + // COINIT_MULTITHREADED.
1.86 + // Returns nullptr if the decoder can't be created.
1.87 + // It is safe to store a reference to aConfig.
1.88 + // Called on decode thread.
1.89 + virtual MediaDataDecoder* CreateH264Decoder(const mp4_demuxer::VideoDecoderConfig& aConfig,
1.90 + layers::LayersBackend aLayersBackend,
1.91 + layers::ImageContainer* aImageContainer,
1.92 + MediaTaskQueue* aVideoTaskQueue,
1.93 + MediaDataDecoderCallback* aCallback) = 0;
1.94 +
1.95 + // Creates an AAC decoder with the specified properties.
1.96 + // Asynchronous decoding of audio should be done in runnables dispatched to
1.97 + // aAudioTaskQueue. If the task queue isn't needed, the decoder should
1.98 + // not hold a reference to it.
1.99 + // Output and errors should be returned to the reader via aCallback.
1.100 + // Returns nullptr if the decoder can't be created.
1.101 + // On Windows the task queue's threads in have MSCOM initialized with
1.102 + // COINIT_MULTITHREADED.
1.103 + // It is safe to store a reference to aConfig.
1.104 + // Called on decode thread.
1.105 + virtual MediaDataDecoder* CreateAACDecoder(const mp4_demuxer::AudioDecoderConfig& aConfig,
1.106 + MediaTaskQueue* aAudioTaskQueue,
1.107 + MediaDataDecoderCallback* aCallback) = 0;
1.108 +
1.109 + virtual ~PlatformDecoderModule() {}
1.110 +
1.111 +protected:
1.112 + PlatformDecoderModule() {}
1.113 + // Caches pref media.fragmented-mp4.use-blank-decoder
1.114 + static bool sUseBlankDecoder;
1.115 + static bool sFFmpegDecoderEnabled;
1.116 +};
1.117 +
1.118 +// A callback used by MediaDataDecoder to return output/errors to the
1.119 +// MP4Reader. Implementation is threadsafe, and can be called on any thread.
1.120 +class MediaDataDecoderCallback {
1.121 +public:
1.122 + virtual ~MediaDataDecoderCallback() {}
1.123 +
1.124 + // Called by MediaDataDecoder when a sample has been decoded. Callee is
1.125 + // responsibile for deleting aData.
1.126 + virtual void Output(MediaData* aData) = 0;
1.127 +
1.128 + // Denotes an error in the decoding process. The reader will stop calling
1.129 + // the decoder.
1.130 + virtual void Error() = 0;
1.131 +
1.132 + // Denotes that the last input sample has been inserted into the decoder,
1.133 + // and no more output can be produced unless more input is sent.
1.134 + virtual void InputExhausted() = 0;
1.135 +};
1.136 +
1.137 +// MediaDataDecoder is the interface exposed by decoders created by the
1.138 +// PlatformDecoderModule's Create*Decoder() functions. The type of
1.139 +// media data that the decoder accepts as valid input and produces as
1.140 +// output is determined when the MediaDataDecoder is created.
1.141 +//
1.142 +// All functions must be threadsafe, and be able to be called on an
1.143 +// arbitrary thread.
1.144 +//
1.145 +// Decoding is done asynchronously. Any async work can be done on the
1.146 +// MediaTaskQueue passed into the PlatformDecoderModules's Create*Decoder()
1.147 +// function. This may not be necessary for platforms with async APIs
1.148 +// for decoding.
1.149 +class MediaDataDecoder {
1.150 +protected:
1.151 + virtual ~MediaDataDecoder() {};
1.152 +
1.153 +public:
1.154 + NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaDataDecoder)
1.155 +
1.156 + // Initialize the decoder. The decoder should be ready to decode after
1.157 + // this returns. The decoder should do any initialization here, rather
1.158 + // than in its constructor or PlatformDecoderModule::Create*Decoder(),
1.159 + // so that if the MP4Reader needs to shutdown during initialization,
1.160 + // it can call Shutdown() to cancel this operation. Any initialization
1.161 + // that requires blocking the calling thread in this function *must*
1.162 + // be done here so that it can be canceled by calling Shutdown()!
1.163 + virtual nsresult Init() = 0;
1.164 +
1.165 + // Inserts a sample into the decoder's decode pipeline. The decoder must
1.166 + // delete the sample once its been decoded. If Input() returns an error,
1.167 + // aSample will be deleted by the caller.
1.168 + virtual nsresult Input(mp4_demuxer::MP4Sample* aSample) = 0;
1.169 +
1.170 + // Causes all samples in the decoding pipeline to be discarded. When
1.171 + // this function returns, the decoder must be ready to accept new input
1.172 + // for decoding. This function is called when the demuxer seeks, before
1.173 + // decoding resumes after the seek.
1.174 + // While the reader calls Flush(), it ignores all output sent to it;
1.175 + // it is safe (but pointless) to send output while Flush is called.
1.176 + // The MP4Reader will not call Input() while it's calling Flush().
1.177 + virtual nsresult Flush() = 0;
1.178 +
1.179 + // Causes all complete samples in the pipeline that can be decoded to be
1.180 + // output. If the decoder can't produce samples from the current output,
1.181 + // it drops the input samples. The decoder may be holding onto samples
1.182 + // that are required to decode samples that it expects to get in future.
1.183 + // This is called when the demuxer reaches end of stream.
1.184 + // The MP4Reader will not call Input() while it's calling Drain().
1.185 + virtual nsresult Drain() = 0;
1.186 +
1.187 + // Cancels all init/input/drain operations, and shuts down the
1.188 + // decoder. The platform decoder should clean up any resources it's using
1.189 + // and release memory etc. Shutdown() must block until the decoder has
1.190 + // completed shutdown. The reader calls Flush() before calling Shutdown().
1.191 + // The reader will delete the decoder once Shutdown() returns.
1.192 + // The MediaDataDecoderCallback *must* not be called after Shutdown() has
1.193 + // returned.
1.194 + virtual nsresult Shutdown() = 0;
1.195 +
1.196 +};
1.197 +
1.198 +} // namespace mozilla
1.199 +
1.200 +#endif
