chromecast/public/media/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_PUBLIC_MEDIA_MEDIA_COMPONENT_DEVICE_H_
   6 #define CHROMECAST_PUBLIC_MEDIA_MEDIA_COMPONENT_DEVICE_H_
   7
   8 #include <stdint.h>
   9 #include <string>
  10
  11 #include "cast_key_system.h"
  12
  13 namespace chromecast {
  14 namespace media {
  15 class CastDecoderBuffer;
  16 class DecryptContext;
  17
  18 // Common base interface for both platform-specific audio and video pipeline
  19 // backends.  Both follow this state machine:
  20 //                       +------------- kRunning <--+
  21 //                       |                 ^        |
  22 //                       v                 |        |
  23 // kUninitialized <--> kIdle  -------------+        |
  24 //                       ^                 |        |
  25 //                       |                 v        |
  26 //                       +------------- kPaused <---+
  27 // {any state} --> kError
  28 // kError --> kUninitialized
  29 //
  30 // Notes:
  31 // - Hardware resources should be acquired when transitioning from the
  32 //   |kUninitialized| state to the |kIdle| state.
  33 // - Buffers will be pushed only in the kRunning or kPaused states.
  34 // - The end of stream is signaled through a special buffer.
  35 //   Once the end of stream buffer is fed, no other buffer
  36 //   will be fed until the FSM goes through the kIdle state again.
  37 // - In both kPaused and kRunning states, frames can be fed.
  38 //   However, frames are possibly rendered only in the kRunning state.
  39 // - In the kRunning state, frames are rendered according to the clock rate.
  40 // - All the hardware resources must be released in the |kError| state.
  41 class MediaComponentDevice {
  42  public:
  43   enum State {
  44     kStateUninitialized,
  45     kStateIdle,
  46     kStateRunning,
  47     kStatePaused,
  48     kStateError,
  49   };
  50
  51   enum FrameStatus {
  52     kFrameSuccess,
  53     kFrameFailed,
  54     kFramePending,
  55   };
  56
  57   // Interface for receiving status when PushFrame has completed.
  58   class FrameStatusCB {
  59    public:
  60     virtual ~FrameStatusCB() {}
  61     virtual void Run(FrameStatus status) = 0;
  62   };
  63
  64   // Client callbacks interface
  65   class Client {
  66    public:
  67     virtual ~Client() {}
  68     virtual void OnEndOfStream() = 0;
  69   };
  70
  71   // The statistics are computed since the media component left the idle state.
  72   // For video, a sample is defined as a frame.
  73   struct Statistics {
  74     uint64_t decoded_bytes;
  75     uint64_t decoded_samples;
  76     uint64_t dropped_samples;
  77   };
  78
  79   // Info on pipeline latency: amount of data in pipeline not rendered yet,
  80   // and timestamp of system clock (must be CLOCK_MONOTONIC) at which delay
  81   // measurement was taken.  Both times in microseconds.
  82   struct RenderingDelay {
  83     RenderingDelay()
  84         : delay_microseconds(INT64_MIN), timestamp_microseconds(INT64_MIN) {}
  85     RenderingDelay(int64_t delay_microseconds_in,
  86                    int64_t timestamp_microseconds_in)
  87         : delay_microseconds(delay_microseconds_in),
  88           timestamp_microseconds(timestamp_microseconds_in) {}
  89     int64_t delay_microseconds;
  90     int64_t timestamp_microseconds;
  91   };
  92
  93   virtual ~MediaComponentDevice() {}
  94
  95   // Registers |client| as the media event handler.  Implementation
  96   // takes ownership of |client| and call OnEndOfStream when an end-of-stream
  97   // buffer is processed.
  98   virtual void SetClient(Client* client) = 0;
  99
 100   // Changes the state and performs any necessary transitions.
 101   // Returns true when successful.
 102   virtual bool SetState(State new_state) = 0;
 103
 104   // Returns the current state of the media component.
 105   virtual State GetState() const = 0;
 106
 107   // Sets the time where rendering should start.
 108   // Return true when successful.
 109   // Will only be invoked in state kStateIdle.
 110   virtual bool SetStartPts(int64_t microseconds) = 0;
 111
 112   // Pushes a frame.  If the implementation cannot push the buffer
 113   // now, it must store the buffer, return |kFramePending| and execute the push
 114   // at a later time when it becomes possible to do so.  The implementation must
 115   // then invoke |completion_cb|.  Pushing a pending frame should be aborted if
 116   // the state returns to kStateIdle, and |completion_cb| need not be invoked.
 117   // If |kFramePending| is returned, the pipeline will stop pushing any further
 118   // buffers until the |completion_cb| is invoked.
 119   // Ownership: |decrypt_context|, |buffer|, |completion_cb| are all owned by
 120   // the implementation and must be deleted once no longer needed (even in the
 121   // case where |completion_cb| is not called).
 122   // |completion_cb| should be only be invoked to indicate completion of a
 123   // pending buffer push - not for the immediate |kFrameSuccess| return case.
 124   virtual FrameStatus PushFrame(DecryptContext* decrypt_context,
 125                                 CastDecoderBuffer* buffer,
 126                                 FrameStatusCB* completion_cb) = 0;
 127
 128   // Returns the pipeline latency: i.e. the amount of data
 129   // in the pipeline that have not been rendered yet, in microseconds.
 130   // Returns delay = INT64_MIN if the latency is not available.
 131   virtual RenderingDelay GetRenderingDelay() const = 0;
 132
 133   // Returns the playback statistics since the last transition from idle state.
 134   // Returns true when successful.
 135   // Is only invoked in state kStateRunning.
 136   virtual bool GetStatistics(Statistics* stats) const = 0;
 137 };
 138
 139 }  // namespace media
 140 }  // namespace chromecast
 141
 142 #endif  // CHROMECAST_MEDIA_CMA_BACKEND_MEDIA_COMPONENT_DEVICE_H_