cc/output/swap_promise.h

   1 // Copyright 2013 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_OUTPUT_SWAP_PROMISE_H_
   6 #define CC_OUTPUT_SWAP_PROMISE_H_
   7
   8 #include "cc/output/compositor_frame_metadata.h"
   9
  10 namespace cc {
  11
  12 // When a change to the compositor's state/invalidation/whatever happens, a
  13 // Swap Promise can be inserted into LayerTreeHost/LayerTreeImpl, to track
  14 // whether the compositor's reply to the new state/invaliadtion/whatever is
  15 // completed in the compositor, i.e. the compositor knows it has been sent
  16 // to its output or not.
  17 //
  18 // If the commit results in a successful activation of the pending layer tree,
  19 // SwapPromise::DidActivate() will be called.
  20 //
  21 // If the new compositor state is sent to the output, SwapPromise::DidSwap()
  22 // will be called.
  23 //
  24 // If the scheduler fails to activate the pending tree, or the compositor
  25 // fails to send its new state to the output, SwapPromise::DidNotSwap() will
  26 // be called. Note that it is possible to activate, and subsequently not swap.
  27 //
  28 // Promises complete afer either DidSwap() or DidNotSwap() is called, thus
  29 // there are three possible call sequences:
  30 //   DidNotSwap()
  31 //   DidActivate() ; DidSwap()
  32 //   DidActivate() ; DidNotSwap()
  33 //
  34 // Clients that wish to use SwapPromise should have a subclass that defines
  35 // the behavior of DidActivate(), DidSwap() and DidNotSwap(). Notice that the
  36 // promise can be broken at either main or impl thread, e.g. commit fails on
  37 // main thread, new frame data has no actual damage so
  38 // LayerTreeHostImpl::SwapBuffers() bails out early on impl thread, so don't
  39 // assume that Did*() methods are called at a particular thread. It is better
  40 // to let the subclass carry thread-safe member data and operate on that
  41 // member data in Did*().
  42 class CC_EXPORT SwapPromise {
  43  public:
  44   enum DidNotSwapReason {
  45     SWAP_FAILS,
  46     COMMIT_FAILS,
  47     COMMIT_NO_UPDATE,
  48     ACTIVATION_FAILS,
  49   };
  50
  51   SwapPromise() {}
  52   virtual ~SwapPromise() {}
  53
  54   virtual void DidActivate() = 0;
  55   virtual void DidSwap(CompositorFrameMetadata* metadata) = 0;
  56   virtual void DidNotSwap(DidNotSwapReason reason) = 0;
  57   // This is called when the main thread starts a (blocking) commit
  58   virtual void OnCommit() {}
  59
  60   // A non-zero trace id identifies a trace flow object that is embedded in the
  61   // swap promise. This can be used for registering additional flow steps to
  62   // visualize the object's path through the system.
  63   virtual int64 TraceId() const = 0;
  64 };
  65
  66 }  // namespace cc
  67
  68 #endif  // CC_OUTPUT_SWAP_PROMISE_H_