[Chromecast] Upgrade to new CMA backend API

chromecast/public/media/media_pipeline_backend.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_
 #define CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_
 
+#include "decoder_config.h"
+
 namespace chromecast {
+struct Size;

[erickung1, 2015/10/09 17:53:29]

nit: a blank line between #10 and #11

[kmackay, 2015/10/09 20:35:40]

I put a blank line before the media namespace. I usually don't add a blank line
before predeclared classes.

 namespace media {
+class CastDecoderBuffer;

[erickung1, 2015/10/09 17:53:29]

nit: ditto between #12 and #13

+class DecryptContext;
 
-class AudioPipelineDevice;
-class MediaClockDevice;
-struct MediaPipelineDeviceParams;
-class VideoPipelineDevice;
-
-// Interface for creating and managing ownership of platform-specific clock,
-// audio and video devices.  cast_shell owns the MediaPipelineBackend for
-// as long as it is needed; the implementation is responsible for
-// tearing down the individual components correctly when it is destroyed.
+// Interface for platform-specific output of media.
 // A new MediaPipelineBackend will be instantiated for each media player
-// instance.
+// instance and raw audio stream.  If a backend has both video and audio
+// decoders, they must be synchronized.  Platforms must support 1
+// synchronized backend and >= 3 backends with audio only simultaneously. If

[erickung1, 2015/10/09 17:53:29]

Is this the restriction in Chromecast + Chromium restriction or in OEM partner?
We don't want to put such description for the later. 

We should put something like "currently cast platform should be able to
support.... blablabla.."

[kmackay, 2015/10/09 20:35:40]

I removed the comment, but we need to have some guidelines for partners.

+// more backends are requested than the platform supports, the unsupported
+// extra backends may return nullptr for CreateAudioDecoder/CreateVideoDecoder.
+// The basic usage pattern is:
+//   * Decoder objects created, then Initialize called
+//   * Start/Stop/Pause/Resume used to manage playback state
+//   * Decoder objects are used to pass actual stream data buffers
+//   * Backend must make appropriate callbacks on the provided Delegate
+// All functions will be called on the media thread.  Delegate callbacks
+// must be made on this thread also (using provided TaskRunner if necessary).
 class MediaPipelineBackend {
  public:
+  // Return code for PushBuffer
+  enum BufferStatus {
+    kBufferSuccess,
+    kBufferFailed,
+    kBufferPending,
+  };
+
+  class Decoder {

[erickung1, 2015/10/09 17:53:29]

should we hide destructor of Decoder/VideoDecoder/AudioDecoder to private and
only be accessible by MEdiaPipelineBackend? In that case our front end code
won't be able to do stupid things like deleting the decoder by accidents.

[kmackay, 2015/10/09 20:35:40]

Done.

+   public:
+    typedef MediaPipelineBackend::BufferStatus BufferStatus;
+
+    // Statistics (computed since pipeline last started playing).
+    // For video, a sample is defined as a frame.
+    struct Statistics {
+      uint64_t decoded_bytes;
+      uint64_t decoded_samples;
+      uint64_t dropped_samples;
+    };
+
+    virtual ~Decoder() {}
+
+    // Pushes a buffer of data for decoding and output.  If the implementation
+    // cannot push the buffer now, it must store the buffer, return
+    // |kBufferPending| and execute the push at a later time when it becomes
+    // possible to do so.  The implementation must then invoke
+    // Client::OnPushComplete.  Pushing a pending buffer should be aborted if
+    // Stop is called; OnPushAudioComplete need not be invoked in this case.
+    // If |kBufferPending| is returned, the pipeline will stop pushing any
+    // further buffers until OnPushComplete is invoked.
+    // OnPushComplete should be only be invoked to indicate completion of a
+    // pending buffer push - not for the immediate |kBufferSuccess| return case.
+    // The decrypt_context and buffer's lifetimes are managed by the caller code
+    // - they MUST NOT be deleted by the MediaPipelineBackend implementation,
+    // and MUST NOT be dereferenced after completion of buffer push (i.e.
+    // kBufferSuccess/kBufferFailure for synchronous completion, OnPushComplete
+    // for kBufferPending case).
+    virtual BufferStatus PushBuffer(DecryptContext* decrypt_context,
+                                    CastDecoderBuffer* buffer) = 0;
+
+    // Returns the playback statistics since this decoder's creation.  Only
+    // called when playing or paused.
+    virtual void GetStatistics(Statistics* statistics) = 0;
+  };
+
+  class AudioDecoder : public Decoder {
+   public:
+    // Info on pipeline latency: amount of data in pipeline not rendered yet,
+    // and timestamp of system clock (must be CLOCK_MONOTONIC) at which delay
+    // measurement was taken.  Both times in microseconds.
+    struct RenderingDelay {
+      RenderingDelay()
+          : delay_microseconds(INT64_MIN), timestamp_microseconds(INT64_MIN) {}
+      RenderingDelay(int64_t delay_microseconds_in,
+                     int64_t timestamp_microseconds_in)
+          : delay_microseconds(delay_microseconds_in),
+            timestamp_microseconds(timestamp_microseconds_in) {}
+      int64_t delay_microseconds;
+      int64_t timestamp_microseconds;
+    };
+
+    // Provides the audio configuration.  Called once before the backend is
+    // initialized, and again any time the configuration changes (in any state).
+    // Returns true if the configuration is a supported configuration.
+    virtual bool SetConfig(const AudioConfig& config) = 0;
+
+    // Sets the volume multiplier for this audio stream.
+    // The multiplier is in the range [0.0, 1.0].  If not called, a default
+    // multiplier of 1.0 is assumed. Returns true if successful.
+    virtual bool SetVolume(float multiplier) = 0;
+
+    // Returns the pipeline latency: i.e. the amount of data
+    // in the pipeline that have not been rendered yet, in microseconds.
+    // Returns delay = INT64_MIN if the latency is not available.
+    virtual RenderingDelay GetRenderingDelay() = 0;
+  };
+
+  class VideoDecoder : public Decoder {
+   public:
+    // Provides the video configuration.  Called once before the backend is
+    // initialized, and again any time the configuration changes (in any state).
+    // Returns true if the configuration is a supported configuration.
+    virtual bool SetConfig(const VideoConfig& config) = 0;
+  };
+
+  // Delegate methods must be called on the main CMA thread.
+  class Delegate {
+   public:
+    // Must be called when video resolution change is detected by decoder.
+    virtual void OnVideoResolutionChanged(VideoDecoder* decoder,
+                                          const Size& size) = 0;
+
+    // See comments on PushBuffer.  Must not be called with kBufferPending.
+    virtual void OnPushBufferComplete(Decoder* decoder,
+                                      BufferStatus status) = 0;
+
+    // Must be called after an end-of-stream buffer has been rendered (ie, the
+    // last real buffer has been sent to the output hardware).
+    virtual void OnEndOfStream(Decoder* decoder) = 0;
+
+    // May be called if a decoder error occurs. No more calls to PushBuffer()
+    // will be made after this is called.
+    virtual void OnDecoderError(Decoder* decoder) = 0;
+
+   protected:
+    virtual ~Delegate() {}
+  };
+
   virtual ~MediaPipelineBackend() {}
 
-  // Returns the platform-specific pipeline clock.
-  virtual MediaClockDevice* GetClock() = 0;
+  // Creates a new AudioDecoder attached to this pipeline.  MediaPipelineBackend
+  // maintains ownership of the decoder object (and must not delete before it's
+  // destroyed).  Will be called zero or more times, all calls made before
+  // Initialize. May return nullptr if the platform implementation cannot
+  // support any additional simultaneous playback at this time.
+  virtual AudioDecoder* CreateAudioDecoder() = 0;
 
-  // Returns the platform-specific audio backend.
-  virtual AudioPipelineDevice* GetAudio() = 0;
+  // Creates a new VideoDecoder attached to this pipeline.  MediaPipelineBackend
+  // maintains ownership of the decoder object (and must not delete before it's
+  // destroyed).  Will be called zero or more times, all calls made before
+  // Initialize. Note: Even if your backend only supports audio, you must
+  // provide a default implementation of VideoDecoder; one way to do this is to
+  // inherit from MediaPipelineBackendDefault. May return nullptr if the
+  // platform implementation cannot support any additional simultaneous playback
+  // at this time.
+  virtual VideoDecoder* CreateVideoDecoder() = 0;
 
-  // Returns the platform-specific video backend.
-  virtual VideoPipelineDevice* GetVideo() = 0;
+  // Initializes the backend.  This will be called once, after Decoder creation
+  // but before all other functions.  Hardware resources for all decoders should
+  // be acquired here.  Backend is then considered in Initialized state.
+  // Returns false for failure.
+  virtual bool Initialize(Delegate* delegate) = 0;
+
+  // Places pipeline into playing state.  Playback will start at given time once
+  // buffers are pushed.  Called only when in Initialized state.
+  virtual bool Start(int64_t start_pts) = 0;
+
+  // Returns pipeline to 'Initialized' state.  May be called while playing or
+  // paused.  Buffers cannot be pushed in Initialized state.
+  virtual bool Stop() = 0;
+
+  // Pauses media playback.  Called only when in playing state.
+  virtual bool Pause() = 0;
+
+  // Resumes media playback.  Called only when in paused state.
+  virtual bool Resume() = 0;
+
+  // Gets the current playback time.

[erickung1, 2015/10/09 17:53:29]

May be better to provide the unit of the value it returns

[kmackay, 2015/10/09 20:35:40]

Done.

+  virtual int64_t GetCurrentPts() = 0;
+
+  // Sets the playback rate.  |rate| > 0.  If this is not called, a default rate
+  // of 1.0 is assumed. Returns true if successful.
+  virtual bool SetPlaybackRate(float rate) = 0;
 };
 
 }  // namespace media
 }  // namespace chromecast
 
-#endif  // CHROMECAST_MEDIA_CMA_BACKEND_MEDIA_PIPELINE_DEVICE_FACTORY_H_
+#endif  // CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_