| Flutter Impeller |

entity_pass.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 #pragma once
6
7 #include <functional>
8 #include <memory>
9 #include <optional>
10 #include <vector>
11
12 #include "flutter/fml/macros.h"
13 #include "impeller/core/texture.h"
14 #include "impeller/entity/contents/contents.h"
15 #include "impeller/entity/contents/filters/filter_contents.h"
16 #include "impeller/entity/entity.h"
17 #include "impeller/entity/entity_pass_delegate.h"
18 #include "impeller/entity/inline_pass_context.h"
19 #include "impeller/renderer/render_target.h"
20 #include "impeller/typographer/lazy_glyph_atlas.h"
21
22 namespace impeller {
23
24 class ContentContext;
25
26 class EntityPass {
27 public:
28 /// Elements are renderable items in the `EntityPass`. Each can either be an
29 /// `Entity` or a child `EntityPass`.
30 ///
31 /// When the element is a child `EntityPass`, it may be rendered to an
32 /// offscreen texture and converted into an `Entity` that draws the texture
33 /// into the current pass, or its children may be collapsed into the current
34 ///
35 /// `EntityPass`. Elements are converted to Entities in
36 /// `GetEntityForElement()`.
37 using Element = std::variant<Entity, std::unique_ptr<EntityPass>>;
38
39 static const std::string kCaptureDocumentName;
40
41 using BackdropFilterProc = std::function<std::shared_ptr<FilterContents>(
42 FilterInput::Ref,
43 const Matrix& effect_transform,
44 Entity::RenderingMode rendering_mode)>;
45
46 struct StencilCoverageLayer {
47 std::optional<Rect> coverage;
48 size_t stencil_depth;
49 };
50
51 using StencilCoverageStack = std::vector<StencilCoverageLayer>;
52
53 EntityPass();
54
55 ~EntityPass();
56
57 void SetDelegate(std::shared_ptr<EntityPassDelegate> delgate);
58
59 /// @brief Set the bounds limit, which is provided by the user when creating
60 /// a SaveLayer. This is a hint that allows the user to communicate
61 /// that it's OK to not render content outside of the bounds.
62 ///
63 /// For consistency with Skia, we effectively treat this like a
64 /// rectangle clip by forcing the subpass texture size to never exceed
65 /// it.
66 void SetBoundsLimit(std::optional<Rect> bounds_limit);
67
68 /// @brief Get the bounds limit, which is provided by the user when creating
69 /// a SaveLayer.
70 std::optional<Rect> GetBoundsLimit() const;
71
72 size_t GetSubpassesDepth() const;
73
74 std::unique_ptr<EntityPass> Clone() const;
75
76 void AddEntity(Entity entity);
77
78 void SetElements(std::vector<Element> elements);
79
80 //----------------------------------------------------------------------------
81 /// @brief Appends a given pass as a subpass.
82 ///
83 EntityPass* AddSubpass(std::unique_ptr<EntityPass> pass);
84
85 //----------------------------------------------------------------------------
86 /// @brief Merges a given pass into this pass. Useful for drawing
87 /// pre-recorded pictures that don't require rendering into a separate
88 /// subpass.
89 ///
90 void AddSubpassInline(std::unique_ptr<EntityPass> pass);
91
92 EntityPass* GetSuperpass() const;
93
94 bool Render(ContentContext& renderer,
95 const RenderTarget& render_target) const;
96
97 /// @brief Iterate all elements (entities and subpasses) in this pass,
98 /// recursively including elements of child passes. The iteration
99 /// order is depth-first. Whenever a subpass elements is encountered,
100 /// it's included in the stream before its children.
101 void IterateAllElements(const std::function<bool(Element&)>& iterator);
102
103 //----------------------------------------------------------------------------
104 /// @brief Iterate all entities in this pass, recursively including entities
105 /// of child passes. The iteration order is depth-first.
106 ///
107 void IterateAllEntities(const std::function<bool(Entity&)>& iterator);
108
109 //----------------------------------------------------------------------------
110 /// @brief Iterate all entities in this pass, recursively including entities
111 /// of child passes. The iteration order is depth-first and does not
112 /// allow modification of the entities.
113 ///
114 void IterateAllEntities(
115 const std::function<bool(const Entity&)>& iterator) const;
116
117 //----------------------------------------------------------------------------
118 /// @brief Iterate entities in this pass up until the first subpass is found.
119 /// This is useful for limiting look-ahead optimizations.
120 ///
121 /// @return Returns whether a subpass was encountered.
122 ///
123 bool IterateUntilSubpass(const std::function<bool(Entity&)>& iterator);
124
125 //----------------------------------------------------------------------------
126 /// @brief Return the number of elements on this pass.
127 ///
128 size_t GetElementCount() const;
129
130 void SetTransformation(Matrix xformation);
131
132 void SetStencilDepth(size_t stencil_depth);
133
134 size_t GetStencilDepth();
135
136 void SetBlendMode(BlendMode blend_mode);
137
138 Color GetClearColor(ISize size = ISize::Infinite()) const;
139
140 void SetBackdropFilter(BackdropFilterProc proc);
141
142 void SetEnableOffscreenCheckerboard(bool enabled);
143
144 //----------------------------------------------------------------------------
145 /// @brief Get the coverage of an unfiltered subpass.
146 ///
147 std::optional<Rect> GetSubpassCoverage(
148 const EntityPass& subpass,
149 std::optional<Rect> coverage_limit) const;
150
151 std::optional<Rect> GetElementsCoverage(
152 std::optional<Rect> coverage_limit) const;
153
154 private:
155 struct EntityResult {
156 enum Status {
157 /// The entity was successfully resolved and can be rendered.
158 kSuccess,
159 /// An unexpected rendering error occurred while resolving the Entity.
160 kFailure,
161 /// The entity should be skipped because rendering it will contribute
162 /// nothing to the frame.
163 kSkip,
164 };
165
166 /// @brief The resulting entity that should be rendered. If `std::nullopt`,
167 /// there is nothing to render.
168 Entity entity;
169 /// @brief This is set to `false` if there was an unexpected rendering
170 /// error while resolving the Entity.
171 Status status = kFailure;
172
173 static EntityResult Success(const Entity& e) { return {e, kSuccess}; }
174 static EntityResult Failure() { return {{}, kFailure}; }
175 static EntityResult Skip() { return {{}, kSkip}; }
176 };
177
178 EntityResult GetEntityForElement(const EntityPass::Element& element,
179 ContentContext& renderer,
180 Capture& capture,
181 InlinePassContext& pass_context,
182 ISize root_pass_size,
183 Point global_pass_position,
184 uint32_t pass_depth,
185 StencilCoverageStack& stencil_coverage_stack,
186 size_t stencil_depth_floor) const;
187
188 //----------------------------------------------------------------------------
189 /// @brief OnRender is the internal command recording routine for
190 /// `EntityPass`. Its job is to walk through each `Element` which
191 /// was appended to the scene (either an `Entity` via `AddEntity()`
192 /// or a child `EntityPass` via `AddSubpass()`) and render them to
193 /// the given `pass_target`.
194 /// @param[in] renderer The Contents context, which manages
195 /// pipeline state.
196 /// @param[in] root_pass_size The size of the texture being
197 /// rendered into at the root of the
198 /// `EntityPass` tree. This is the size
199 /// of the `RenderTarget` color
200 /// attachment passed to the public
201 /// `EntityPass::Render` method.
202 /// @param[out] pass_target Stores the render target that should
203 /// be used for rendering.
204 /// @param[in] global_pass_position The position that this `EntityPass`
205 /// will be drawn to the parent pass
206 /// relative to the root pass origin.
207 /// Used for offsetting drawn `Element`s,
208 /// whose origins are all in root
209 /// pass/screen space,
210 /// @param[in] local_pass_position The position that this `EntityPass`
211 /// will be drawn to the parent pass
212 /// relative to the parent pass origin.
213 /// Used for positioning backdrop
214 /// filters.
215 /// @param[in] pass_depth The tree depth of the `EntityPass` at
216 /// render time. Only used for labeling
217 /// and debugging purposes. This can vary
218 /// depending on whether passes are
219 /// collapsed or not.
220 /// @param[in] stencil_coverage_stack A global stack of coverage rectangles
221 /// for the stencil buffer at each depth.
222 /// Higher depths are more restrictive.
223 /// Used to cull Elements that we
224 /// know won't result in a visible
225 /// change.
226 /// @param[in] stencil_depth_floor The stencil depth that a value of
227 /// zero corresponds to in the given
228 /// `pass_target` stencil buffer.
229 /// When new `pass_target`s are created
230 /// for subpasses, their stencils are
231 /// initialized at zero, and so this
232 /// value is used to offset Entity clip
233 /// depths to match the stencil.
234 /// @param[in] backdrop_filter_contents Optional. Is supplied, this contents
235 /// is rendered prior to anything else in
236 /// the `EntityPass`, offset by the
237 /// `local_pass_position`.
238 /// @param[in] collapsed_parent_pass Optional. If supplied, this
239 /// `InlinePassContext` state is used to
240 /// begin rendering elements instead of
241 /// creating a new `RenderPass`. This
242 /// "collapses" the Elements into the
243 /// parent pass.
244 ///
245 bool OnRender(ContentContext& renderer,
246 Capture& capture,
247 ISize root_pass_size,
248 EntityPassTarget& pass_target,
249 Point global_pass_position,
250 Point local_pass_position,
251 uint32_t pass_depth,
252 StencilCoverageStack& stencil_coverage_stack,
253 size_t stencil_depth_floor = 0,
254 std::shared_ptr<Contents> backdrop_filter_contents = nullptr,
255 const std::optional<InlinePassContext::RenderPassResult>&
256 collapsed_parent_pass = std::nullopt) const;
257
258 /// The list of renderable items in the scene. Each of these items is
259 /// evaluated and recorded to an `EntityPassTarget` by the `OnRender` method.
260 std::vector<Element> elements_;
261
262 EntityPass* superpass_ = nullptr;
263 Matrix xformation_;
264 size_t stencil_depth_ = 0u;
265 BlendMode blend_mode_ = BlendMode::kSourceOver;
266 bool flood_clip_ = false;
267 bool enable_offscreen_debug_checkerboard_ = false;
268 std::optional<Rect> bounds_limit_;
269
270 /// These values are incremented whenever something is added to the pass that
271 /// requires reading from the backdrop texture. Currently, this can happen in
272 /// the following scenarios:
273 /// 1. An entity with an "advanced blend" is added to the pass.
274 /// 2. A subpass with a backdrop filter is added to the pass.
275 /// These are tracked as separate values because we may ignore
276 /// blend_reads_from_pass_texture_ if the device supports framebuffer based
277 /// advanced blends.
278 uint32_t advanced_blend_reads_from_pass_texture_ = 0;
279 uint32_t backdrop_filter_reads_from_pass_texture_ = 0;
280
281 uint32_t GetTotalPassReads(ContentContext& renderer) const;
282
283 BackdropFilterProc backdrop_filter_proc_ = nullptr;
284
285 std::shared_ptr<EntityPassDelegate> delegate_ =
286 EntityPassDelegate::MakeDefault();
287
288 FML_DISALLOW_COPY_AND_ASSIGN(EntityPass);
289 };
290
291 } // namespace impeller
impeller::EntityPass::AddSubpassInline
void AddSubpassInline(std::unique_ptr< EntityPass > pass)
Merges a given pass into this pass. Useful for drawing pre-recorded pictures that don't require rende...
Definition: entity_pass.cc:245
impeller::BlendMode
BlendMode
Definition: color.h:57
impeller::EntityPass::IterateAllEntities
void IterateAllEntities(const std::function< bool(Entity &)> &iterator)
Iterate all entities in this pass, recursively including entities of child passes....
Definition: entity_pass.cc:1030
impeller::EntityPass::SetTransformation
void SetTransformation(Matrix xformation)
Definition: entity_pass.cc:1126
impeller::EntityPass::SetBackdropFilter
void SetBackdropFilter(BackdropFilterProc proc)
Definition: entity_pass.cc:1160
lazy_glyph_atlas.h
contents.h
entity_pass_delegate.h
impeller::EntityPass::BackdropFilterProc
std::function< std::shared_ptr< FilterContents >(FilterInput::Ref, const Matrix &effect_transform, Entity::RenderingMode rendering_mode)> BackdropFilterProc
Definition: entity_pass.h:44
impeller::EntityPass::GetSubpassCoverage
std::optional< Rect > GetSubpassCoverage(const EntityPass &subpass, std::optional< Rect > coverage_limit) const
Get the coverage of an unfiltered subpass.
Definition: entity_pass.cc:195
entity.h
impeller::EntityPass::GetSubpassesDepth
size_t GetSubpassesDepth() const
Definition: entity_pass.cc:93
impeller::EntityPass::SetBoundsLimit
void SetBoundsLimit(std::optional< Rect > bounds_limit)
Set the bounds limit, which is provided by the user when creating a SaveLayer. This is a hint that al...
Definition: entity_pass.cc:69
impeller::EntityPass::StencilCoverageLayer::stencil_depth
size_t stencil_depth
Definition: entity_pass.h:48
impeller::Color
Definition: color.h:122
impeller::EntityPass::EntityPass
EntityPass()
impeller::EntityPassDelegate::MakeDefault
static std::unique_ptr< EntityPassDelegate > MakeDefault()
Definition: entity_pass_delegate.cc:48
impeller::EntityPass::AddSubpass
EntityPass * AddSubpass(std::unique_ptr< EntityPass > pass)
Appends a given pass as a subpass.
Definition: entity_pass.cc:226
impeller::EntityPass::IterateUntilSubpass
bool IterateUntilSubpass(const std::function< bool(Entity &)> &iterator)
Iterate entities in this pass up until the first subpass is found. This is useful for limiting look-a...
Definition: entity_pass.cc:1073
impeller::FilterInput::Ref
std::shared_ptr< FilterInput > Ref
Definition: filter_input.h:31
impeller::EntityPass::IterateAllElements
void IterateAllElements(const std::function< bool(Element &)> &iterator)
Iterate all elements (entities and subpasses) in this pass, recursively including elements of child p...
Definition: entity_pass.cc:1014
impeller::EntityPass::GetElementsCoverage
std::optional< Rect > GetElementsCoverage(std::optional< Rect > coverage_limit) const
Definition: entity_pass.cc:104
impeller::EntityPass::~EntityPass
~EntityPass()
impeller::EntityPass::SetStencilDepth
void SetStencilDepth(size_t stencil_depth)
Definition: entity_pass.cc:1130
impeller::EntityPass::SetBlendMode
void SetBlendMode(BlendMode blend_mode)
Definition: entity_pass.cc:1138
impeller::Entity
Definition: entity.h:21
impeller::TSize< int64_t >
impeller::Point
TPoint< Scalar > Point
Definition: point.h:306
impeller::EntityPass::StencilCoverageStack
std::vector< StencilCoverageLayer > StencilCoverageStack
Definition: entity_pass.h:51
impeller::EntityPass::SetElements
void SetElements(std::vector< Element > elements)
Definition: entity_pass.cc:89
filter_contents.h
impeller::EntityPass::GetBoundsLimit
std::optional< Rect > GetBoundsLimit() const
Get the bounds limit, which is provided by the user when creating a SaveLayer.
Definition: entity_pass.cc:73
impeller::BlendMode::kSourceOver
@ kSourceOver
impeller::EntityPass::GetSuperpass
EntityPass * GetSuperpass() const
Definition: entity_pass.cc:222
impeller::EntityPass
Definition: entity_pass.h:26
impeller::EntityPass::GetStencilDepth
size_t GetStencilDepth()
Definition: entity_pass.cc:1134
impeller::EntityPass::Element
std::variant< Entity, std::unique_ptr< EntityPass > > Element
Definition: entity_pass.h:37
impeller::EntityPass::GetElementCount
size_t GetElementCount() const
Return the number of elements on this pass.
Definition: entity_pass.cc:1091
impeller::RenderTarget
Definition: render_target.h:48
impeller::ISize
TSize< int64_t > ISize
Definition: size.h:136
impeller::EntityPass::StencilCoverageLayer
Definition: entity_pass.h:46
impeller::EntityPass::GetClearColor
Color GetClearColor(ISize size=ISize::Infinite()) const
Definition: entity_pass.cc:1143
impeller::EntityPass::Render
bool Render(ContentContext &renderer, const RenderTarget &render_target) const
Definition: entity_pass.cc:323
texture.h
impeller::TSize< int64_t >::Infinite
static constexpr TSize Infinite()
Definition: size.h:37
impeller::EntityPass::kCaptureDocumentName
static const std::string kCaptureDocumentName
Definition: entity_pass.h:39
impeller::EntityPass::SetDelegate
void SetDelegate(std::shared_ptr< EntityPassDelegate > delgate)
Definition: entity_pass.cc:62
impeller::Entity::RenderingMode
RenderingMode
Definition: entity.h:26
impeller::EntityPass::SetEnableOffscreenCheckerboard
void SetEnableOffscreenCheckerboard(bool enabled)
Definition: entity_pass.cc:1169
render_target.h
impeller::EntityPass::StencilCoverageLayer::coverage
std::optional< Rect > coverage
Definition: entity_pass.h:47
impeller
Definition: aiks_context.cc:10
impeller::ContentContext
Definition: content_context.h:344
impeller::Matrix
A 4x4 matrix using column-major storage.
Definition: matrix.h:36
impeller::EntityPass::AddEntity
void AddEntity(Entity entity)
Definition: entity_pass.cc:77
inline_pass_context.h
impeller::EntityPass::Clone
std::unique_ptr< EntityPass > Clone() const
Definition: entity_pass.cc:1095