| 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 #ifndef FLUTTER_IMPELLER_ENTITY_CONTENTS_CONTENTS_H_
6 #define FLUTTER_IMPELLER_ENTITY_CONTENTS_CONTENTS_H_
7
8 #include <functional>
9 #include <memory>
10
11 #include "impeller/core/sampler_descriptor.h"
12 #include "impeller/geometry/color.h"
13 #include "impeller/geometry/rect.h"
14 #include "impeller/renderer/snapshot.h"
15 #include "impeller/typographer/lazy_glyph_atlas.h"
16
17 namespace impeller {
18
19 class ContentContext;
20 struct ContentContextOptions;
21 class Entity;
22 class Surface;
23 class RenderPass;
24 class FilterContents;
25
26 ContentContextOptions OptionsFromPass(const RenderPass& pass);
27
28 ContentContextOptions OptionsFromPassAndEntity(const RenderPass& pass,
29 const Entity& entity);
30
31 class Contents {
32 public:
33 /// A procedure that filters a given unpremultiplied color to produce a new
34 /// unpremultiplied color.
35 using ColorFilterProc = std::function<Color(Color)>;
36
37 using RenderProc = std::function<bool(const ContentContext& renderer,
38 const Entity& entity,
39 RenderPass& pass)>;
40 using CoverageProc = std::function<std::optional<Rect>(const Entity& entity)>;
41
42 static std::shared_ptr<Contents> MakeAnonymous(RenderProc render_proc,
43 CoverageProc coverage_proc);
44
45 Contents();
46
47 virtual ~Contents();
48
49 virtual bool Render(const ContentContext& renderer,
50 const Entity& entity,
51 RenderPass& pass) const = 0;
52
53 //----------------------------------------------------------------------------
54 /// @brief Get the area of the render pass that will be affected when this
55 /// contents is rendered.
56 ///
57 /// During rendering, coverage coordinates count pixels from the top
58 /// left corner of the framebuffer.
59 ///
60 /// @return The coverage rectangle. An `std::nullopt` result means that
61 /// rendering this contents has no effect on the output color.
62 ///
63 virtual std::optional<Rect> GetCoverage(const Entity& entity) const = 0;
64
65 //----------------------------------------------------------------------------
66 /// @brief Hint that specifies the coverage area of this Contents that will
67 /// actually be used during rendering. This is for optimization
68 /// purposes only and can not be relied on as a clip. May optionally
69 /// affect the result of `GetCoverage()`.
70 ///
71 void SetCoverageHint(std::optional<Rect> coverage_hint);
72
73 const std::optional<Rect>& GetCoverageHint() const;
74
75 //----------------------------------------------------------------------------
76 /// @brief Whether this Contents only emits opaque source colors from the
77 /// fragment stage. This value does not account for any entity
78 /// properties (e.g. the blend mode), clips/visibility culling, or
79 /// inherited opacity.
80 ///
81 /// @param transform The current transform matrix of the entity that will
82 /// render this contents.
83 virtual bool IsOpaque(const Matrix& transform) const;
84
85 struct SnapshotOptions {
86 std::optional<Rect> coverage_limit = std::nullopt;
87 const std::optional<SamplerDescriptor>& sampler_descriptor = std::nullopt;
88 bool msaa_enabled = true;
89 int32_t mip_count = 1;
90 std::string_view label = "Snapshot";
91 int32_t coverage_expansion = 1;
92 };
93
94 //----------------------------------------------------------------------------
95 /// @brief Render this contents to a snapshot, respecting the entity's
96 /// transform, path, clip depth, and blend mode.
97 /// The result texture size is always the size of
98 /// `GetCoverage(entity)`.
99 ///
100 virtual std::optional<Snapshot> RenderToSnapshot(
101 const ContentContext& renderer,
102 const Entity& entity,
103 const SnapshotOptions& options) const;
104
105 //----------------------------------------------------------------------------
106 /// @brief Return the color source's intrinsic size, if available.
107 ///
108 /// For example, a gradient has a size based on its end and beginning
109 /// points, ignoring any tiling. Solid colors and runtime effects have
110 /// no size.
111 ///
112 std::optional<Size> GetColorSourceSize() const;
113
114 void SetColorSourceSize(Size size);
115
116 //----------------------------------------------------------------------------
117 /// @brief Inherit the provided opacity.
118 ///
119 /// Use of this method is invalid if CanAcceptOpacity returns false.
120 ///
121 virtual void SetInheritedOpacity(Scalar opacity);
122
123 //----------------------------------------------------------------------------
124 /// @brief Returns a color if this Contents will flood the given `target_size`
125 /// with a color. This output color is the "Source" color that will be
126 /// used for the Entity's blend operation.
127 ///
128 /// This is useful for absorbing full screen solid color draws into
129 /// subpass clear colors.
130 ///
131 virtual std::optional<Color> AsBackgroundColor(const Entity& entity,
132 ISize target_size) const;
133
134 //----------------------------------------------------------------------------
135 /// @brief If possible, applies a color filter to this contents inputs on
136 /// the CPU.
137 ///
138 /// This method will either fully apply the color filter or
139 /// perform no action. Partial/incorrect application of the color
140 /// filter will never occur.
141 ///
142 /// @param[in] color_filter_proc A function that filters a given
143 /// unpremultiplied color to produce a new
144 /// unpremultiplied color.
145 ///
146 /// @return True if the color filter was able to be fully applied to all
147 /// all relevant inputs. Otherwise, this operation is a no-op and
148 /// false is returned.
149 ///
150 [[nodiscard]] virtual bool ApplyColorFilter(
151 const ColorFilterProc& color_filter_proc);
152
153 private:
154 std::optional<Rect> coverage_hint_;
155 std::optional<Size> color_source_size_;
156
157 Contents(const Contents&) = delete;
158
159 Contents& operator=(const Contents&) = delete;
160 };
161
162 } // namespace impeller
163
164 #endif // FLUTTER_IMPELLER_ENTITY_CONTENTS_CONTENTS_H_
impeller::ContentContext
Definition: content_context.h:138
impeller::Contents
Definition: contents.h:31
impeller::Contents::Render
virtual bool Render(const ContentContext &renderer, const Entity &entity, RenderPass &pass) const =0
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:123
impeller::Contents::~Contents
virtual ~Contents()
impeller::Contents::GetColorSourceSize
std::optional< Size > GetColorSourceSize() const
Return the color source's intrinsic size, if available.
Definition: contents.cc:141
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:128
impeller::Contents::GetCoverageHint
const std::optional< Rect > & GetCoverageHint() const
Definition: contents.cc:137
impeller::Contents::IsOpaque
virtual bool IsOpaque(const Matrix &transform) const
Whether this Contents only emits opaque source colors from the fragment stage. This value does not ac...
Definition: contents.cc:52
impeller::Contents::RenderToSnapshot
virtual std::optional< Snapshot > RenderToSnapshot(const ContentContext &renderer, const Entity &entity, const SnapshotOptions &options) const
Render this contents to a snapshot, respecting the entity's transform, path, clip depth,...
Definition: contents.cc:56
impeller::Contents::SetColorSourceSize
void SetColorSourceSize(Size size)
Definition: contents.cc:145
impeller::Contents::Contents
Contents()
impeller::Contents::CoverageProc
std::function< std::optional< Rect >(const Entity &entity)> CoverageProc
Definition: contents.h:40
impeller::Contents::GetCoverage
virtual std::optional< Rect > GetCoverage(const Entity &entity) const =0
Get the area of the render pass that will be affected when this contents is rendered.
impeller::Contents::SetInheritedOpacity
virtual void SetInheritedOpacity(Scalar opacity)
Inherit the provided opacity.
Definition: contents.cc:118
impeller::Contents::MakeAnonymous
static std::shared_ptr< Contents > MakeAnonymous(RenderProc render_proc, CoverageProc coverage_proc)
Definition: contents.cc:41
impeller::Contents::ColorFilterProc
std::function< Color(Color)> ColorFilterProc
Definition: contents.h:35
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:133
impeller::Contents::RenderProc
std::function< bool(const ContentContext &renderer, const Entity &entity, RenderPass &pass)> RenderProc
Definition: contents.h:39
impeller::Entity
Definition: entity.h:26
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
color.h
transform
Matrix transform
Definition: gaussian_blur_filter_contents.cc:214
lazy_glyph_atlas.h
impeller
Definition: allocation.cc:12
impeller::Scalar
float Scalar
Definition: scalar.h:19
impeller::OptionsFromPassAndEntity
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:34
impeller::OptionsFromPass
ContentContextOptions OptionsFromPass(const RenderPass &pass)
Definition: contents.cc:19
rect.h
sampler_descriptor.h
snapshot.h
impeller::Color
Definition: color.h:124
impeller::Contents::SnapshotOptions
Definition: contents.h:85
impeller::Contents::SnapshotOptions::label
std::string_view label
Definition: contents.h:90
impeller::Contents::SnapshotOptions::mip_count
int32_t mip_count
Definition: contents.h:89
impeller::Contents::SnapshotOptions::sampler_descriptor
const std::optional< SamplerDescriptor > & sampler_descriptor
Definition: contents.h:87
impeller::Contents::SnapshotOptions::coverage_expansion
int32_t coverage_expansion
Definition: contents.h:91
impeller::Contents::SnapshotOptions::coverage_limit
std::optional< Rect > coverage_limit
Definition: contents.h:86
impeller::Contents::SnapshotOptions::msaa_enabled
bool msaa_enabled
Definition: contents.h:88
impeller::Matrix
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
impeller::TSize< Scalar >