cc/layer_iterator.h

   1 // Copyright 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_LAYER_ITERATOR_H_
   6 #define CC_LAYER_ITERATOR_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "cc/cc_export.h"
  10 #include "cc/layer_tree_host_common.h"
  11
  12 namespace cc {
  13
  14 // These classes provide means to iterate over the RenderSurfaceImpl-Layer tree.
  15
  16 // Example code follows, for a tree of Layer/RenderSurface objects. See below for details.
  17 //
  18 // void doStuffOnLayers(const std::vector<scoped_refptr<Layer> >& renderSurfaceLayerList)
  19 // {
  20 //     typedef LayerIterator<Layer, RenderSurface, LayerIteratorActions::FrontToBack> LayerIteratorType;
  21 //
  22 //     LayerIteratorType end = LayerIteratorType::end(&renderSurfaceLayerList);
  23 //     for (LayerIteratorType it = LayerIteratorType::begin(&renderSurfaceLayerList); it != end; ++it) {
  24 //         // Only one of these will be true
  25 //         if (it.representsTargetRenderSurface())
  26 //             foo(*it); // *it is a layer representing a target RenderSurfaceImpl
  27 //         if (it.representsContributingRenderSurface())
  28 //             bar(*it); // *it is a layer representing a RenderSurfaceImpl that contributes to the layer's target RenderSurfaceImpl
  29 //         if (it.representsItself())
  30 //             baz(*it); // *it is a layer representing itself, as it contributes to its own target RenderSurfaceImpl
  31 //     }
  32 // }
  33
  34 // A RenderSurfaceImpl R may be referred to in one of two different contexts. One RenderSurfaceImpl is "current" at any time, for
  35 // whatever operation is being performed. This current surface is referred to as a target surface. For example, when R is
  36 // being painted it would be the target surface. Once R has been painted, its contents may be included into another
  37 // surface S. While S is considered the target surface when it is being painted, R is called a contributing surface
  38 // in this context as it contributes to the content of the target surface S.
  39 //
  40 // The iterator's current position in the tree always points to some layer. The state of the iterator indicates the role of the
  41 // layer, and will be one of the following three states. A single layer L will appear in the iteration process in at least one,
  42 // and possibly all, of these states.
  43 // 1. Representing the target surface: The iterator in this state, pointing at layer L, indicates that the target RenderSurfaceImpl
  44 // is now the surface owned by L. This will occur exactly once for each RenderSurfaceImpl in the tree.
  45 // 2. Representing a contributing surface: The iterator in this state, pointing at layer L, refers to the RenderSurfaceImpl owned
  46 // by L as a contributing surface, without changing the current target RenderSurfaceImpl.
  47 // 3. Representing itself: The iterator in this state, pointing at layer L, refers to the layer itself, as a child of the
  48 // current target RenderSurfaceImpl.
  49 //
  50 // The BackToFront iterator will return a layer representing the target surface before returning layers representing themselves
  51 // as children of the current target surface. Whereas the FrontToBack ordering will iterate over children layers of a surface
  52 // before the layer representing the surface as a target surface.
  53 //
  54 // To use the iterators:
  55 //
  56 // Create a stepping iterator and end iterator by calling LayerIterator::begin() and LayerIterator::end() and passing in the
  57 // list of layers owning target RenderSurfaces. Step through the tree by incrementing the stepping iterator while it is != to
  58 // the end iterator. At each step the iterator knows what the layer is representing, and you can query the iterator to decide
  59 // what actions to perform with the layer given what it represents.
  60
  61 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  62
  63 // Non-templated constants
  64 struct LayerIteratorValue {
  65     static const int InvalidTargetRenderSurfaceLayerIndex = -1;
  66     // This must be -1 since the iterator action code assumes that this value can be
  67     // reached by subtracting one from the position of the first layer in the current
  68     // target surface's child layer list, which is 0.
  69     static const int LayerIndexRepresentingTargetRenderSurface = -1;
  70 };
  71
  72 // The position of a layer iterator that is independent of its many template types.
  73 template <typename LayerType>
  74 struct LayerIteratorPosition {
  75     bool representsTargetRenderSurface;
  76     bool representsContributingRenderSurface;
  77     bool representsItself;
  78     LayerType* targetRenderSurfaceLayer;
  79     LayerType* currentLayer;
  80 };
  81
  82 // An iterator class for walking over layers in the RenderSurfaceImpl-Layer tree.
  83 template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename IteratorActionType>
  84 class LayerIterator {
  85     typedef LayerIterator<LayerType, LayerList, RenderSurfaceType, IteratorActionType> LayerIteratorType;
  86
  87 public:
  88     LayerIterator() : m_renderSurfaceLayerList(0) { }
  89
  90     static LayerIteratorType begin(const LayerList* renderSurfaceLayerList) { return LayerIteratorType(renderSurfaceLayerList, true); }
  91     static LayerIteratorType end(const LayerList* renderSurfaceLayerList) { return LayerIteratorType(renderSurfaceLayerList, false); }
  92
  93     LayerIteratorType& operator++() { m_actions.next(*this); return *this; }
  94     bool operator==(const LayerIterator& other) const
  95     {
  96         return m_targetRenderSurfaceLayerIndex == other.m_targetRenderSurfaceLayerIndex
  97             && m_currentLayerIndex == other.m_currentLayerIndex;
  98     }
  99     bool operator!=(const LayerIteratorType& other) const { return !(*this == other); }
 100
 101     LayerType* operator->() const { return currentLayer(); }
 102     LayerType* operator*() const { return currentLayer(); }
 103
 104     bool representsTargetRenderSurface() const { return currentLayerRepresentsTargetRenderSurface(); }
 105     bool representsContributingRenderSurface() const { return !representsTargetRenderSurface() && currentLayerRepresentsContributingRenderSurface(); }
 106     bool representsItself() const { return !representsTargetRenderSurface() && !representsContributingRenderSurface(); }
 107
 108     LayerType* targetRenderSurfaceLayer() const { return getRawPtr((*m_renderSurfaceLayerList)[m_targetRenderSurfaceLayerIndex]); }
 109
 110     operator const LayerIteratorPosition<LayerType>() const
 111     {
 112         LayerIteratorPosition<LayerType> position;
 113         position.representsTargetRenderSurface = representsTargetRenderSurface();
 114         position.representsContributingRenderSurface = representsContributingRenderSurface();
 115         position.representsItself = representsItself();
 116         position.targetRenderSurfaceLayer = targetRenderSurfaceLayer();
 117         position.currentLayer = currentLayer();
 118         return position;
 119     }
 120
 121 private:
 122     LayerIterator(const LayerList* renderSurfaceLayerList, bool start)
 123         : m_renderSurfaceLayerList(renderSurfaceLayerList)
 124         , m_targetRenderSurfaceLayerIndex(0)
 125     {
 126         for (size_t i = 0; i < renderSurfaceLayerList->size(); ++i) {
 127             if (!(*renderSurfaceLayerList)[i]->renderSurface()) {
 128                 NOTREACHED();
 129                 m_actions.end(*this);
 130                 return;
 131             }
 132         }
 133
 134         if (start && !renderSurfaceLayerList->empty())
 135             m_actions.begin(*this);
 136         else
 137             m_actions.end(*this);
 138     }
 139
 140     inline static Layer* getRawPtr(const scoped_refptr<Layer>& ptr) { return ptr.get(); }
 141     inline static LayerImpl* getRawPtr(LayerImpl* ptr) { return ptr; }
 142
 143     inline LayerType* currentLayer() const { return currentLayerRepresentsTargetRenderSurface() ? targetRenderSurfaceLayer() : getRawPtr(targetRenderSurfaceChildren()[m_currentLayerIndex]); }
 144
 145     inline bool currentLayerRepresentsContributingRenderSurface() const { return LayerTreeHostCommon::renderSurfaceContributesToTarget<LayerType>(currentLayer(), targetRenderSurfaceLayer()->id()); }
 146     inline bool currentLayerRepresentsTargetRenderSurface() const { return m_currentLayerIndex == LayerIteratorValue::LayerIndexRepresentingTargetRenderSurface; }
 147
 148     inline RenderSurfaceType* targetRenderSurface() const { return targetRenderSurfaceLayer()->renderSurface(); }
 149     inline const LayerList& targetRenderSurfaceChildren() const { return targetRenderSurface()->layerList(); }
 150
 151     IteratorActionType m_actions;
 152     const LayerList* m_renderSurfaceLayerList;
 153
 154     // The iterator's current position.
 155
 156     // A position in the renderSurfaceLayerList. This points to a layer which owns the current target surface.
 157     // This is a value from 0 to n-1 (n = size of renderSurfaceLayerList = number of surfaces). A value outside of
 158     // this range (for example, LayerIteratorValue::InvalidTargetRenderSurfaceLayerIndex) is used to
 159     // indicate a position outside the bounds of the tree.
 160     int m_targetRenderSurfaceLayerIndex;
 161     // A position in the list of layers that are children of the current target surface. When pointing to one of
 162     // these layers, this is a value from 0 to n-1 (n = number of children). Since the iterator must also stop at
 163     // the layers representing the target surface, this is done by setting the currentLayerIndex to a value of
 164     // LayerIteratorValue::LayerRepresentingTargetRenderSurface.
 165     int m_currentLayerIndex;
 166
 167     friend struct LayerIteratorActions;
 168 };
 169
 170 // Orderings for iterating over the RenderSurfaceImpl-Layer tree.
 171 struct CC_EXPORT LayerIteratorActions {
 172     // Walks layers sorted by z-order from back to front.
 173     class CC_EXPORT BackToFront {
 174     public:
 175         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 176         void begin(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 177
 178         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 179         void end(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 180
 181         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 182         void next(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 183
 184     private:
 185         int m_highestTargetRenderSurfaceLayer;
 186     };
 187
 188     // Walks layers sorted by z-order from front to back
 189     class CC_EXPORT FrontToBack {
 190     public:
 191         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 192         void begin(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 193
 194         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 195         void end(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 196
 197         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 198         void next(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 199
 200     private:
 201         template <typename LayerType, typename LayerList, typename RenderSurfaceType, typename ActionType>
 202         void goToHighestInSubtree(LayerIterator<LayerType, LayerList, RenderSurfaceType, ActionType>&);
 203     };
 204 };
 205
 206 } // namespace cc
 207
 208 #endif  // CC_LAYER_ITERATOR_H_