| Flutter Impeller |

contents.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 <vector>
10
11 #include "flutter/fml/macros.h"
12 #include "impeller/core/sampler_descriptor.h"
13 #include "impeller/core/texture.h"
14 #include "impeller/geometry/color.h"
15 #include "impeller/geometry/rect.h"
16 #include "impeller/renderer/snapshot.h"
17 #include "impeller/typographer/lazy_glyph_atlas.h"
18
19 namespace impeller {
20
21 class ContentContext;
22 struct ContentContextOptions;
23 class Entity;
24 class Surface;
25 class RenderPass;
26 class FilterContents;
27
28 ContentContextOptions OptionsFromPass(const RenderPass& pass);
29
30 ContentContextOptions OptionsFromPassAndEntity(const RenderPass& pass,
31 const Entity& entity);
32
33 class Contents {
34 public:
35 /// A procedure that filters a given unpremultiplied color to produce a new
36 /// unpremultiplied color.
37 using ColorFilterProc = std::function<Color(Color)>;
38
39 struct StencilCoverage {
40 enum class Type { kNoChange, kAppend, kRestore };
41
42 Type type = Type::kNoChange;
43 std::optional<Rect> coverage = std::nullopt;
44 };
45
46 using RenderProc = std::function<bool(const ContentContext& renderer,
47 const Entity& entity,
48 RenderPass& pass)>;
49 using CoverageProc = std::function<std::optional<Rect>(const Entity& entity)>;
50
51 static std::shared_ptr<Contents> MakeAnonymous(RenderProc render_proc,
52 CoverageProc coverage_proc);
53
54 Contents();
55
56 virtual ~Contents();
57
58 /// @brief Add any text data to the specified lazy atlas. The scale parameter
59 /// must be used again later when drawing the text.
60 virtual void PopulateGlyphAtlas(
61 const std::shared_ptr<LazyGlyphAtlas>& lazy_glyph_atlas,
62 Scalar scale) {}
63
64 virtual bool Render(const ContentContext& renderer,
65 const Entity& entity,
66 RenderPass& pass) const = 0;
67
68 //----------------------------------------------------------------------------
69 /// @brief Get the screen space bounding rectangle that this contents affects.
70 ///
71 virtual std::optional<Rect> GetCoverage(const Entity& entity) const = 0;
72
73 //----------------------------------------------------------------------------
74 /// @brief Hint that specifies the coverage area of this Contents that will
75 /// actually be used during rendering. This is for optimization
76 /// purposes only and can not be relied on as a clip. May optionally
77 /// affect the result of `GetCoverage()`.
78 ///
79 void SetCoverageHint(std::optional<Rect> coverage_hint);
80
81 const std::optional<Rect>& GetCoverageHint() const;
82
83 //----------------------------------------------------------------------------
84 /// @brief Whether this Contents only emits opaque source colors from the
85 /// fragment stage. This value does not account for any entity
86 /// properties (e.g. the blend mode), clips/visibility culling, or
87 /// inherited opacity.
88 ///
89 virtual bool IsOpaque() const;
90
91 //----------------------------------------------------------------------------
92 /// @brief Given the current screen space bounding rectangle of the stencil,
93 /// return the expected stencil coverage after this draw call. This
94 /// should only be implemented for contents that may write to the
95 /// stencil buffer.
96 ///
97 virtual StencilCoverage GetStencilCoverage(
98 const Entity& entity,
99 const std::optional<Rect>& current_stencil_coverage) const;
100
101 //----------------------------------------------------------------------------
102 /// @brief Render this contents to a snapshot, respecting the entity's
103 /// transform, path, stencil depth, and blend mode.
104 /// The result texture size is always the size of
105 /// `GetCoverage(entity)`.
106 ///
107 virtual std::optional<Snapshot> RenderToSnapshot(
108 const ContentContext& renderer,
109 const Entity& entity,
110 std::optional<Rect> coverage_limit = std::nullopt,
111 const std::optional<SamplerDescriptor>& sampler_descriptor = std::nullopt,
112 bool msaa_enabled = true,
113 const std::string& label = "Snapshot") const;
114
115 virtual bool ShouldRender(const Entity& entity,
116 const std::optional<Rect> stencil_coverage) const;
117
118 //----------------------------------------------------------------------------
119 /// @brief Return the color source's intrinsic size, if available.
120 ///
121 /// For example, a gradient has a size based on its end and beginning
122 /// points, ignoring any tiling. Solid colors and runtime effects have
123 /// no size.
124 ///
125 std::optional<Size> GetColorSourceSize() const;
126
127 void SetColorSourceSize(Size size);
128
129 //----------------------------------------------------------------------------
130 /// @brief Whether or not this contents can accept the opacity peephole
131 /// optimization.
132 ///
133 /// By default all contents return false. Contents are responsible
134 /// for determining whether or not their own geometries intersect in
135 /// a way that makes accepting opacity impossible. It is always safe
136 /// to return false, especially if computing overlap would be
137 /// computationally expensive.
138 ///
139 virtual bool CanInheritOpacity(const Entity& entity) const;
140
141 //----------------------------------------------------------------------------
142 /// @brief Inherit the provided opacity.
143 ///
144 /// Use of this method is invalid if CanAcceptOpacity returns false.
145 ///
146 virtual void SetInheritedOpacity(Scalar opacity);
147
148 //----------------------------------------------------------------------------
149 /// @brief Returns a color if this Contents will flood the given `target_size`
150 /// with a color. This output color is the "Source" color that will be
151 /// used for the Entity's blend operation.
152 ///
153 /// This is useful for absorbing full screen solid color draws into
154 /// subpass clear colors.
155 ///
156 virtual std::optional<Color> AsBackgroundColor(const Entity& entity,
157 ISize target_size) const;
158
159 //----------------------------------------------------------------------------
160 /// @brief Cast to a filter. Returns `nullptr` if this Contents is not a
161 /// filter.
162 ///
163 virtual const FilterContents* AsFilter() const;
164
165 //----------------------------------------------------------------------------
166 /// @brief If possible, applies a color filter to this contents inputs on
167 /// the CPU.
168 ///
169 /// This method will either fully apply the color filter or
170 /// perform no action. Partial/incorrect application of the color
171 /// filter will never occur.
172 ///
173 /// @param[in] color_filter_proc A function that filters a given
174 /// unpremultiplied color to produce a new
175 /// unpremultiplied color.
176 ///
177 /// @return True if the color filter was able to be fully applied to all
178 /// all relevant inputs. Otherwise, this operation is a no-op and
179 /// false is returned.
180 ///
181 [[nodiscard]] virtual bool ApplyColorFilter(
182 const ColorFilterProc& color_filter_proc);
183
184 private:
185 std::optional<Rect> coverage_hint_;
186 std::optional<Size> color_source_size_;
187
188 FML_DISALLOW_COPY_AND_ASSIGN(Contents);
189 };
190
191 } // namespace impeller
impeller::Contents::GetColorSourceSize
std::optional< Size > GetColorSourceSize() const
Return the color source's intrinsic size, if available.
Definition: contents.cc:158
impeller::OptionsFromPass
ContentContextOptions OptionsFromPass(const RenderPass &pass)
Definition: contents.cc:20
lazy_glyph_atlas.h
impeller::Scalar
float Scalar
Definition: scalar.h:15
impeller::Contents::SetCoverageHint
void SetCoverageHint(std::optional< Rect > coverage_hint)
Hint that specifies the coverage area of this Contents that will actually be used during rendering....
Definition: contents.cc:150
impeller::Contents::AsBackgroundColor
virtual std::optional< Color > AsBackgroundColor(const Entity &entity, ISize target_size) const
Returns a color if this Contents will flood the given target_size with a color. This output color is ...
Definition: contents.cc:121
impeller::Color
Definition: color.h:122
impeller::Contents::SetColorSourceSize
void SetColorSourceSize(Size size)
Definition: contents.cc:162
impeller::Contents::CanInheritOpacity
virtual bool CanInheritOpacity(const Entity &entity) const
Whether or not this contents can accept the opacity peephole optimization.
Definition: contents.cc:112
impeller::Contents::Contents
Contents()
impeller::Contents::GetCoverage
virtual std::optional< Rect > GetCoverage(const Entity &entity) const =0
Get the screen space bounding rectangle that this contents affects.
impeller::Contents::StencilCoverage::Type::kNoChange
@ kNoChange
impeller::Contents::ShouldRender
virtual bool ShouldRender(const Entity &entity, const std::optional< Rect > stencil_coverage) const
Definition: contents.cc:135
impeller::Entity
Definition: entity.h:21
impeller::OptionsFromPassAndEntity
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:30
impeller::Contents::GetCoverageHint
const std::optional< Rect > & GetCoverageHint() const
Definition: contents.cc:154
impeller::TSize
Definition: size.h:18
impeller::Contents::StencilCoverage
Definition: contents.h:39
impeller::Contents::~Contents
virtual ~Contents()
impeller::Contents::ColorFilterProc
std::function< Color(Color)> ColorFilterProc
Definition: contents.h:37
impeller::Contents::PopulateGlyphAtlas
virtual void PopulateGlyphAtlas(const std::shared_ptr< LazyGlyphAtlas > &lazy_glyph_atlas, Scalar scale)
Add any text data to the specified lazy atlas. The scale parameter must be used again later when draw...
Definition: contents.h:60
impeller::Contents::StencilCoverage::coverage
std::optional< Rect > coverage
Definition: contents.h:43
impeller::Contents::StencilCoverage::Type::kRestore
@ kRestore
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:27
sampler_descriptor.h
impeller::Contents::RenderProc
std::function< bool(const ContentContext &renderer, const Entity &entity, RenderPass &pass)> RenderProc
Definition: contents.h:48
impeller::Contents::Render
virtual bool Render(const ContentContext &renderer, const Entity &entity, RenderPass &pass) const =0
snapshot.h
rect.h
impeller::Contents::SetInheritedOpacity
virtual void SetInheritedOpacity(Scalar opacity)
Inherit the provided opacity.
Definition: contents.cc:116
texture.h
impeller::Contents::StencilCoverage::type
Type type
Definition: contents.h:42
color.h
impeller::Contents::MakeAnonymous
static std::shared_ptr< Contents > MakeAnonymous(RenderProc render_proc, CoverageProc coverage_proc)
Definition: contents.cc:37
impeller::Contents::ApplyColorFilter
virtual bool ApplyColorFilter(const ColorFilterProc &color_filter_proc)
If possible, applies a color filter to this contents inputs on the CPU.
Definition: contents.cc:130
impeller::Contents::CoverageProc
std::function< std::optional< Rect >(const Entity &entity)> CoverageProc
Definition: contents.h:49
impeller::Contents
Definition: contents.h:33
impeller::Contents::StencilCoverage::Type::kAppend
@ kAppend
impeller::Contents::IsOpaque
virtual bool IsOpaque() const
Whether this Contents only emits opaque source colors from the fragment stage. This value does not ac...
Definition: contents.cc:48
impeller::Contents::StencilCoverage::Type
Type
Definition: contents.h:40
impeller
Definition: aiks_context.cc:10
impeller::ContentContext
Definition: content_context.h:344
impeller::Contents::AsFilter
virtual const FilterContents * AsFilter() const
Cast to a filter. Returns nullptr if this Contents is not a filter.
Definition: contents.cc:126
impeller::Contents::GetStencilCoverage
virtual StencilCoverage GetStencilCoverage(const Entity &entity, const std::optional< Rect > &current_stencil_coverage) const
Given the current screen space bounding rectangle of the stencil, return the expected stencil coverag...
Definition: contents.cc:52
impeller::FilterContents
Definition: filter_contents.h:19
impeller::Contents::RenderToSnapshot
virtual std::optional< Snapshot > RenderToSnapshot(const ContentContext &renderer, const Entity &entity, std::optional< Rect > coverage_limit=std::nullopt, const std::optional< SamplerDescriptor > &sampler_descriptor=std::nullopt, bool msaa_enabled=true, const std::string &label="Snapshot") const
Render this contents to a snapshot, respecting the entity's transform, path, stencil depth,...
Definition: contents.cc:59