Flutter Engine
container_layer.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter 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 FLUTTER_FLOW_LAYERS_CONTAINER_LAYER_H_
6 #define FLUTTER_FLOW_LAYERS_CONTAINER_LAYER_H_
7 
8 #include <vector>
9 
10 #include "flutter/flow/layers/layer.h"
11 
12 namespace flutter {
13 
14 class ContainerLayer : public Layer {
15  public:
17 
18 #ifdef FLUTTER_ENABLE_DIFF_CONTEXT
19 
20  void Diff(DiffContext* context, const Layer* old_layer) override;
21  void PreservePaintRegion(DiffContext* context) override;
22 
23 #endif // FLUTTER_ENABLE_DIFF_CONTEXT
24 
25  virtual void Add(std::shared_ptr<Layer> layer);
26 
27  void Preroll(PrerollContext* context, const SkMatrix& matrix) override;
28  void Paint(PaintContext& context) const override;
29 
30  const std::vector<std::shared_ptr<Layer>>& layers() const { return layers_; }
31 
32 #ifdef FLUTTER_ENABLE_DIFF_CONTEXT
33 
34  virtual void DiffChildren(DiffContext* context,
35  const ContainerLayer* old_layer);
36 
37 #endif // FLUTTER_ENABLE_DIFF_CONTEXT
38 
39  protected:
40  void PrerollChildren(PrerollContext* context,
41  const SkMatrix& child_matrix,
42  SkRect* child_paint_bounds);
43  void PaintChildren(PaintContext& context) const;
44 
45  // Try to prepare the raster cache for a given layer.
46  //
47  // The raster cache would fail if either of the followings is true:
48  // 1. The context has a platform view.
49  // 2. The context does not have a valid raster cache.
50  // 3. The layer's paint bounds does not intersect with the cull rect.
51  //
52  // We make this a static function instead of a member function that directly
53  // uses the "this" pointer as the layer because we sometimes need to raster
54  // cache a child layer and one can't access its child's protected method.
55  static void TryToPrepareRasterCache(PrerollContext* context,
56  Layer* layer,
57  const SkMatrix& matrix);
58 
59  private:
60  std::vector<std::shared_ptr<Layer>> layers_;
61 
62  FML_DISALLOW_COPY_AND_ASSIGN(ContainerLayer);
63 };
64 
65 //------------------------------------------------------------------------------
66 /// Some ContainerLayer objects perform a rendering operation or filter on
67 /// the rendered output of their children. Often that operation is changed
68 /// slightly from frame to frame as part of an animation. During such an
69 /// animation, the children can be cached if they are stable to avoid having
70 /// to render them on every frame. Even if the children are not stable,
71 /// rendering them into the raster cache during a Preroll operation will save
72 /// an extra change of rendering surface during the Paint phase as compared
73 /// to using the SaveLayer that would otherwise be needed with no caching.
74 ///
75 /// Typically the Flutter Widget objects that lead to the creation of these
76 /// layers will try to enforce only a single child Widget by their design.
77 /// Unfortunately, the process of turning Widgets eventually into engine
78 /// layers is not a 1:1 process so this layer might end up with multiple
79 /// child layers even if the Widget only had a single child Widget.
80 ///
81 /// When such a layer goes to cache the output of its children, it will
82 /// need to supply a single layer to the cache mechanism since the raster
83 /// cache uses a layer unique_id() as part of the cache key. If this layer
84 /// ended up with multiple children, then it must first collect them into
85 /// one layer for the cache mechanism. In order to provide a single layer
86 /// for all of the children, this utility class will implicitly collect
87 /// the children into a secondary ContainerLayer called the child container.
88 ///
89 /// A by-product of creating a hidden child container, though, is that the
90 /// child container is created new every time this layer is created with
91 /// different properties, such as during an animation. In that scenario,
92 /// it would be best to cache the single real child of this layer if it
93 /// is unique and if it is stable from frame to frame. To facilitate this
94 /// optimal caching strategy, this class implements two accessor methods
95 /// to be used for different purposes:
96 ///
97 /// When the layer needs to recurse to perform some operation on its children,
98 /// it can call GetChildContainer() to return the hidden container containing
99 /// all of the real children.
100 ///
101 /// When the layer wants to cache the rendered contents of its children, it
102 /// should call GetCacheableChild() for best performance. This method may
103 /// end up returning the same layer as GetChildContainer(), but only if the
104 /// conditions for optimal caching of a single child are not met.
105 ///
107  public:
109 
110  void Add(std::shared_ptr<Layer> layer) override;
111 
112 #ifdef FLUTTER_ENABLE_DIFF_CONTEXT
113  void DiffChildren(DiffContext* context,
114  const ContainerLayer* old_layer) override;
115 #endif
116 
117  protected:
118  /**
119  * @brief Returns the ContainerLayer used to hold all of the children of the
120  * MergedContainerLayer. Note that this may not be the best layer to use
121  * for caching the children.
122  *
123  * @see GetCacheableChild()
124  * @return the ContainerLayer child used to hold the children
125  */
126  ContainerLayer* GetChildContainer() const;
127 
128  /**
129  * @brief Returns the best choice for a Layer object that can be used
130  * in RasterCache operations to cache the children.
131  *
132  * The returned Layer must represent all children and try to remain stable
133  * if the MergedContainerLayer is reconstructed in subsequent frames of
134  * the scene.
135  *
136  * @see GetChildContainer()
137  * @return the best candidate Layer for caching the children
138  */
139  Layer* GetCacheableChild() const;
140 
141  private:
143 };
144 
145 } // namespace flutter
146 
147 #endif // FLUTTER_FLOW_LAYERS_CONTAINER_LAYER_H_
const std::vector< std::shared_ptr< Layer > > & layers() const
void PrerollChildren(PrerollContext *context, const SkMatrix &child_matrix, SkRect *child_paint_bounds)
void Paint(PaintContext &context) const override
virtual void Add(std::shared_ptr< Layer > layer)
void Preroll(PrerollContext *context, const SkMatrix &matrix) override
#define FML_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:27
static void TryToPrepareRasterCache(PrerollContext *context, Layer *layer, const SkMatrix &matrix)
void PaintChildren(PaintContext &context) const