chromecast/media/cma/backend/media_component_device.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROMECAST_MEDIA_CMA_BACKEND_MEDIA_COMPONENT_DEVICE_H_
   6 #define CHROMECAST_MEDIA_CMA_BACKEND_MEDIA_COMPONENT_DEVICE_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/callback.h"
  12 #include "base/macros.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/threading/non_thread_safe.h"
  15 #include "base/time/time.h"
  16
  17 namespace chromecast {
  18 namespace media {
  19 class DecoderBufferBase;
  20 class DecryptContext;
  21
  22 // MediaComponentDevice -
  23 //
  24 // State machine:
  25 //                       -------------- kRunning <---
  26 //                       |                 ^        |
  27 //                       v                 |        |
  28 // kUninitialized <--> kIdle  --------------        |
  29 //                       ^                 |        |
  30 //                       |                 v        |
  31 //                       -------------- kPaused <----
  32 // {any state} --> kError
  33 // kError --> kUninitialized
  34 //
  35 // Notes:
  36 // - Hardware resources are acquired when transitioning from the
  37 //   |kUninitialized| state to the |kIdle| state.
  38 // - Buffers can be pushed only in the kRunning or kPaused states.
  39 // - The end of stream is signaled through a special buffer.
  40 //   Once the end of stream buffer is fed, no other buffer
  41 //   can be fed until the FSM goes through the kIdle state again.
  42 // - In both kPaused and kRunning states, frames can be fed.
  43 //   However, frames are possibly rendered only in the kRunning state.
  44 // - In the kRunning state, frames are rendered according to the clock rate.
  45 // - All the hardware resources must be released in the |kError| state.
  46 //
  47 class MediaComponentDevice
  48     : NON_EXPORTED_BASE(public base::NonThreadSafe) {
  49  public:
  50   enum State {
  51     kStateUninitialized,
  52     kStateIdle,
  53     kStateRunning,
  54     kStatePaused,
  55     kStateError,
  56   };
  57
  58   enum FrameStatus {
  59     kFrameSuccess,
  60     kFrameFailed,
  61     kFramePending,
  62   };
  63   typedef base::Callback<void(FrameStatus)> FrameStatusCB;
  64
  65   struct Client {
  66     Client();
  67     ~Client();
  68
  69     // Invoked when playback reaches the end of stream.
  70     base::Closure eos_cb;
  71   };
  72
  73   // The statistics are computed since the media component left the idle state.
  74   // For video, a sample is defined as a frame.
  75   struct Statistics {
  76     uint64 decoded_bytes;
  77     uint64 decoded_samples;
  78     uint64 dropped_samples;
  79   };
  80
  81   // Returns whether or not transitioning from |state1| to |state2| is valid.
  82   static bool IsValidStateTransition(State state1, State state2);
  83
  84   // Returns string representation of state (for logging)
  85   static std::string StateToString(const State& state);
  86
  87   MediaComponentDevice();
  88   virtual ~MediaComponentDevice();
  89
  90   // Register |client| as the media event handler.
  91   virtual void SetClient(const Client& client) = 0;
  92
  93   // Changes the state and performs any necessary transitions.
  94   // Returns true when successful.
  95   virtual bool SetState(State new_state) = 0;
  96
  97   // Returns the current state of the media component.
  98   virtual State GetState() const = 0;
  99
 100   // Sets the time where rendering should start.
 101   // Return true when successful.
 102   // Can only be invoked in state kStateIdle.
 103   virtual bool SetStartPts(base::TimeDelta time) = 0;
 104
 105   // Pushes a frame.
 106   // |completion_cb| is only invoked if the returned value is |kFramePending|.
 107   // In this specific case, no additional frame can be pushed before
 108   // |completion_cb| is invoked.
 109   // Note: |completion_cb| cannot be invoked with |kFramePending|.
 110   // Note: pushing the pending frame should be aborted when the state goes back
 111   // to kStateIdle. |completion_cb| is not invoked in that case.
 112   virtual FrameStatus PushFrame(
 113       const scoped_refptr<DecryptContext>& decrypt_context,
 114       const scoped_refptr<DecoderBufferBase>& buffer,
 115       const FrameStatusCB& completion_cb) = 0;
 116
 117   // Returns the rendering time of the latest rendered sample.
 118   // Can be invoked only in states kStateRunning or kStatePaused.
 119   // Returns |kNoTimestamp()| if the playback time cannot be retrieved.
 120   virtual base::TimeDelta GetRenderingTime() const = 0;
 121
 122   // Returns the pipeline latency: i.e. the amount of data
 123   // in the pipeline that have not been rendered yet.
 124   // Returns |kNoTimestamp()| if the latency is not available.
 125   virtual base::TimeDelta GetRenderingDelay() const = 0;
 126
 127   // Returns the playback statistics. Statistics are computed since the media
 128   // component left the idle state.
 129   // Returns true when successful.
 130   // Can only be invoked in state kStateRunning.
 131   virtual bool GetStatistics(Statistics* stats) const = 0;
 132
 133  private:
 134   DISALLOW_COPY_AND_ASSIGN(MediaComponentDevice);
 135 };
 136
 137 }  // namespace media
 138 }  // namespace chromecast
 139
 140 #endif  // CHROMECAST_MEDIA_CMA_BACKEND_MEDIA_COMPONENT_DEVICE_H_