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