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/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 // 43 // Note that the client may also choose to stop driving frame updates, such 44 // as if it believes that the frames are not visible. In this case, the 45 // client should report this via IsDrivingFrameUpdates(). 46 virtual void StartRendering() = 0; 47 virtual void StopRendering() = 0; 48 49 // Notifies the client that GetCurrentFrame() will return new data. 50 virtual void DidReceiveFrame() = 0; 51 52 // Should return true if and only if the client is actively driving frame 53 // updates. Note that this implies that the client has been told to 54 // StartRendering by the VideoFrameProvider. However, it's okay if the 55 // client chooses to elide these calls, for example to save power when the 56 // client knows that the frames are not visible. 57 virtual bool IsDrivingFrameUpdates() const = 0; 58 59 protected: ~Client()60 virtual ~Client() {} 61 }; 62 63 // May be called from any thread, but there must be some external guarantee 64 // that the provider is not destroyed before this call returns. 65 virtual void SetVideoFrameProviderClient(Client* client) = 0; 66 67 // Called by the client on a regular interval. Returns true if a new frame 68 // will be available via GetCurrentFrame() which should be displayed within 69 // the presentation interval [|deadline_min|, |deadline_max|]. 70 // 71 // Implementations may use this to drive frame acquisition from underlying 72 // sources, so it must be called by clients before calling GetCurrentFrame(). 73 virtual bool UpdateCurrentFrame(base::TimeTicks deadline_min, 74 base::TimeTicks deadline_max) = 0; 75 76 // Returns true if GetCurrentFrame() will return a non-null frame and false 77 // otherwise. Aside from thread locks, the state won't change. 78 virtual bool HasCurrentFrame() = 0; 79 80 // Returns the current frame, which may have been updated by a recent call to 81 // UpdateCurrentFrame(). A call to this method does not ensure that the frame 82 // will be rendered. A subsequent call to PutCurrentFrame() must be made if 83 // the frame is expected to be rendered. 84 // 85 // Clients should call this in response to UpdateCurrentFrame() returning true 86 // or in response to a DidReceiveFrame() call. 87 virtual scoped_refptr<media::VideoFrame> GetCurrentFrame() = 0; 88 89 // Called in response to DidReceiveFrame() or a return value of true from 90 // UpdateCurrentFrame() if the current frame was considered for rendering; the 91 // frame may not been rendered for a variety of reasons (occlusion, etc). 92 // Providers may use the absence of this call as a signal to detect when a new 93 // frame missed its intended deadline. 94 virtual void PutCurrentFrame() = 0; 95 96 // Returns the interval at which the provider expects to have new frames for 97 // the client. 98 virtual base::TimeDelta GetPreferredRenderInterval() = 0; 99 100 protected: ~VideoFrameProvider()101 virtual ~VideoFrameProvider() {} 102 }; 103 104 } // namespace cc 105 106 #endif // CC_LAYERS_VIDEO_FRAME_PROVIDER_H_ 107