gecko/content/media/fmp4/PlatformDecoderModule.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#if !defined(PlatformDecoderModule_h_)
#define PlatformDecoderModule_h_

#include "MediaDecoderReader.h"
#include "mozilla/layers/LayersTypes.h"

namespace mozilla {

namespace layers {
class ImageContainer;
}

class MediaDataDecoder;
typedef int64_t Microseconds;

// The PlatformDecoderModule interface is used by the MP4Reader to abstract
// access to the H264 and AAC decoders provided by various platforms. It
// may be extended to support other codecs in future. Each platform (Windows,
// MacOSX, Linux etc) must implement a PlatformDecoderModule to provide access
// to its decoders in order to get decompressed H.264/AAC from the MP4Reader.
//
// Platforms that don't have a corresponding PlatformDecoderModule won't be
// able to play the H.264/AAC data output by the MP4Reader. In practice this
// means that we won't have fragmented MP4 supported in Media Source
// Extensions on platforms without PlatformDecoderModules.
//
// A cross-platform decoder module that discards input and produces "blank"
// output samples exists for testing, and is created if the pref
// "media.fragmented-mp4.use-blank-decoder" is true.
class PlatformDecoderModule {
public:

  // Factory method that creates the appropriate PlatformDecoderModule for
  // the platform we're running on. Caller is responsible for deleting this
  // instance. It's expected that there will be multiple
  // PlatformDecoderModules alive at the same time. There is one
  // PlatformDecoderModule's created per MP4Reader.
  // This is called on the main thread.
  static PlatformDecoderModule* Create();

  // Called to shutdown the decoder module and cleanup state. This should
  // block until shutdown is complete. This is called after Shutdown() has
  // been called on all MediaDataDecoders created from this
  // PlatformDecoderModule.
  // Called on the main thread only.
  virtual nsresult Shutdown() = 0;

  // Creates and initializes an H.264 decoder. The layers backend is
  // passed in so that decoders can determine whether hardware accelerated
  // decoding can be used. Returns nullptr if the decoder can't be
  // initialized.
  // Called on decode thread.
  virtual MediaDataDecoder* CreateH264Decoder(layers::LayersBackend aLayersBackend,
                                              layers::ImageContainer* aImageContainer) = 0;

  // Creates and initializes an AAC decoder with the specified properties.
  // The raw AAC AudioSpecificConfig as contained in the esds box. Some
  // decoders need that to initialize. The caller owns the AAC config,
  // so it must be copied if it is to be retained by the decoder.
  // Returns nullptr if the decoder can't be initialized.
  // Called on decode thread.
  virtual MediaDataDecoder* CreateAACDecoder(uint32_t aChannelCount,
                                             uint32_t aSampleRate,
                                             uint16_t aBitsPerSample,
                                             const uint8_t* aAACConfig,
                                             uint32_t aAACConfigLength) = 0;

  // Called when a decode thread is started. Called on decode thread.
  virtual void OnDecodeThreadStart() {}

  // Called just before a decode thread is finishing. Called on decode thread.
  virtual void OnDecodeThreadFinish() {}

  virtual ~PlatformDecoderModule() {}
protected:
  PlatformDecoderModule() {}
};

// Return value of the MediaDataDecoder functions.
enum DecoderStatus {
  DECODE_STATUS_NOT_ACCEPTING, // Can't accept input at this time. Decoder can produce output.
  DECODE_STATUS_NEED_MORE_INPUT, // Can't produce output. Decoder can accept input.
  DECODE_STATUS_OK,
  DECODE_STATUS_ERROR
};

// MediaDataDecoder is the interface exposed by decoders created by the
// PlatformDecoderModule's Create*Decoder() functions. The type of
// media data that the decoder accepts as valid input and produces as
// output is determined when the MediaDataDecoder is created.
// The decoder is assumed to be in one of three mutually exclusive and
// implicit states: able to accept input, able to produce output, and
// shutdown. The decoder is assumed to be able to accept input by the time
// that it's returned by PlatformDecoderModule::Create*Decoder().
class MediaDataDecoder {
public:
  virtual ~MediaDataDecoder() {};

  // Inserts aData into the decoding pipeline. Decoding may begin
  // asynchronously. The caller owns aData, so it may need to be copied.
  // The MP4Reader calls Input() with new input in a loop until Input()
  // stops returning DECODE_STATUS_OK.
  // Called on the media decode thread.
  // Returns:
  //  - DECODE_STATUS_OK if input was successfully inserted into
  //    the decode pipeline.
  //  - DECODE_STATUS_NOT_ACCEPTING if the decoder cannot accept any input
  //    at this time. The MP4Reader will assume that the decoder can now
  //    produce one or more output samples, and call the Output() function.
  //    The MP4Reader will call Input() again with the same data later,
  //    after the decoder's Output() function has stopped producing output.
  //  - DECODE_STATUS_ERROR if the decoder has been shutdown, or some
  //    unspecified error.
  // This function should not return DECODE_STATUS_NEED_MORE_INPUT.
  virtual DecoderStatus Input(const uint8_t* aData,
                              uint32_t aLength,
                              Microseconds aDTS,
                              Microseconds aPTS,
                              int64_t aOffsetInStream) = 0;

  // Blocks until a decoded sample is produced by the deoder. The MP4Reader
  // calls this until it stops returning DECODE_STATUS_OK.
  // Called on the media decode thread.
  // Returns:
  //  - DECODE_STATUS_OK if an output sample was successfully placed in
  //    aOutData. More samples for output may still be available, the
  //    MP4Reader will call again to check.
  //  - DECODE_STATUS_NEED_MORE_INPUT if the decoder needs more input to
  //    produce a sample. The decoder should return this once it can no
  //    longer produce output. This signals to the MP4Reader that it should
  //    start feeding in data via the Input() function.
  //  - DECODE_STATUS_ERROR if the decoder has been shutdown, or some
  //    unspecified error.
  // This function should not return DECODE_STATUS_NOT_ACCEPTING.
  virtual DecoderStatus Output(nsAutoPtr<MediaData>& aOutData) = 0;

  // Causes all samples in the decoding pipeline to be discarded. When
  // this function returns, the decoder must be ready to accept new input
  // for decoding. This function is called when the demuxer seeks, before
  // decoding resumes after the seek.
  // Called on the media decode thread.
  virtual DecoderStatus Flush() = 0;

  // Cancels all decode operations, and shuts down the decoder. This should
  // block until shutdown is complete. The decoder should return
  // DECODE_STATUS_ERROR for all calls to its functions once this is called.
  // Called on main thread.
  virtual nsresult Shutdown() = 0;

};

} // namespace mozilla

#endif