cc/layers/video_frame_provider.h

   1 // Copyright (c) 2012 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 CC_LAYERS_VIDEO_FRAME_PROVIDER_H_
   6 #define CC_LAYERS_VIDEO_FRAME_PROVIDER_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "base/time/time.h"
  10 #include "cc/base/cc_export.h"
  11
  12 namespace media {
  13 class VideoFrame;
  14 }
  15
  16 namespace cc {
  17
  18 // VideoFrameProvider and VideoFrameProvider::Client define the relationship by
  19 // which video frames are exchanged between a provider and client.
  20 //
  21 // Threading notes: This class may be used in a multithreaded manner. However,
  22 // if the Client implementation calls GetCurrentFrame()/PutCurrentFrame() from
  23 // one thread, the provider must ensure that all client methods (except
  24 // StopUsingProvider()) are called from that thread (typically the compositor
  25 // thread).
  26 class CC_EXPORT VideoFrameProvider {
  27  public:
  28   class CC_EXPORT Client {
  29    public:
  30     // The provider will call this method to tell the client to stop using it.
  31     // StopUsingProvider() may be called from any thread. The client should
  32     // block until it has PutCurrentFrame() any outstanding frames.
  33     virtual void StopUsingProvider() = 0;
  34
  35     // Notifies the client that it should start or stop making regular
  36     // UpdateCurrentFrame() calls to the provider. No further calls to
  37     // UpdateCurrentFrame() should be made once StopRendering() returns.
  38     //
  39     // Callers should use these methods to indicate when it expects and no
  40     // longer expects (respectively) to have new frames for the client. Clients
  41     // may use this information for power conservation.
  42     virtual void StartRendering() = 0;
  43     virtual void StopRendering() = 0;
  44
  45     // Notifies the client that GetCurrentFrame() will return new data.
  46     // TODO(dalecurtis): Nuke this once VideoFrameProviderClientImpl is using a
  47     // BeginFrameObserver based approach. http://crbug.com/336733
  48     virtual void DidReceiveFrame() = 0;
  49
  50     // Notifies the client of a new UV transform matrix to be used.
  51     virtual void DidUpdateMatrix(const float* matrix) = 0;
  52
  53    protected:
  54     virtual ~Client() {}
  55   };
  56
  57   // May be called from any thread, but there must be some external guarantee
  58   // that the provider is not destroyed before this call returns.
  59   virtual void SetVideoFrameProviderClient(Client* client) = 0;
  60
  61   // Called by the client on a regular interval. Returns true if a new frame
  62   // will be available via GetCurrentFrame() which should be displayed within
  63   // the presentation interval [|deadline_min|, |deadline_max|].
  64   //
  65   // Implementations may use this to drive frame acquisition from underlying
  66   // sources, so it must be called by clients before calling GetCurrentFrame().
  67   virtual bool UpdateCurrentFrame(base::TimeTicks deadline_min,
  68                                   base::TimeTicks deadline_max) = 0;
  69
  70   // Returns true if GetCurrentFrame() will return a non-null frame and false
  71   // otherwise. Aside from thread locks, the state won't change.
  72   virtual bool HasCurrentFrame() = 0;
  73
  74   // Returns the current frame, which may have been updated by a recent call to
  75   // UpdateCurrentFrame(). A call to this method does not ensure that the frame
  76   // will be rendered. A subsequent call to PutCurrentFrame() must be made if
  77   // the frame is expected to be rendered.
  78   //
  79   // Clients should call this in response to UpdateCurrentFrame() returning true
  80   // or in response to a DidReceiveFrame() call.
  81   //
  82   // TODO(dalecurtis): Remove text about DidReceiveFrame() once the old path
  83   // has been removed. http://crbug.com/439548
  84   virtual scoped_refptr<media::VideoFrame> GetCurrentFrame() = 0;
  85
  86   // Called in response to DidReceiveFrame() or a return value of true from
  87   // UpdateCurrentFrame() if the current frame was considered for rendering; the
  88   // frame may not been rendered for a variety of reasons (occlusion, etc).
  89   // Providers may use the absence of this call as a signal to detect when a new
  90   // frame missed its intended deadline.
  91   virtual void PutCurrentFrame() = 0;
  92
  93  protected:
  94   virtual ~VideoFrameProvider() {}
  95 };
  96
  97 }  // namespace cc
  98
  99 #endif  // CC_LAYERS_VIDEO_FRAME_PROVIDER_H_