| Flutter Impeller |

filter_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_FILTERS_FILTER_CONTENTS_H_
6 #define FLUTTER_IMPELLER_ENTITY_CONTENTS_FILTERS_FILTER_CONTENTS_H_
7
8 #include <memory>
9 #include <optional>
10 #include <variant>
11 #include <vector>
12
13 #include "impeller/core/formats.h"
14 #include "impeller/entity/contents/filters/inputs/filter_input.h"
15 #include "impeller/entity/contents/runtime_effect_contents.h"
16 #include "impeller/entity/entity.h"
17 #include "impeller/entity/geometry/geometry.h"
18 #include "impeller/geometry/matrix.h"
19 #include "impeller/geometry/sigma.h"
20 #include "impeller/runtime_stage/runtime_stage.h"
21
22 namespace impeller {
23
24 class FilterContents : public Contents {
25 public:
26 static const int32_t kBlurFilterRequiredMipCount;
27
28 enum class BlurStyle {
29 /// Blurred inside and outside.
30 kNormal,
31 /// Solid inside, blurred outside.
32 kSolid,
33 /// Nothing inside, blurred outside.
34 kOuter,
35 /// Blurred inside, nothing outside.
36 kInner,
37 };
38
39 enum class MorphType { kDilate, kErode };
40
41 /// Creates a gaussian blur that operates in 2 dimensions.
42 ///
43 /// For definition of parameters, see DlBlurImageFilter.
44 static std::shared_ptr<FilterContents> MakeGaussianBlur(
45 const FilterInput::Ref& input,
46 Sigma sigma_x,
47 Sigma sigma_y,
48 Entity::TileMode tile_mode = Entity::TileMode::kDecal,
49 std::optional<Rect> bounds = std::nullopt,
50 BlurStyle mask_blur_style = BlurStyle::kNormal,
51 const Geometry* mask_geometry = nullptr);
52
53 static std::shared_ptr<FilterContents> MakeBorderMaskBlur(
54 FilterInput::Ref input,
55 Sigma sigma_x,
56 Sigma sigma_y,
57 BlurStyle blur_style = BlurStyle::kNormal);
58
59 static std::shared_ptr<FilterContents> MakeDirectionalMorphology(
60 FilterInput::Ref input,
61 Radius radius,
62 Vector2 direction,
63 MorphType morph_type);
64
65 static std::shared_ptr<FilterContents> MakeMorphology(FilterInput::Ref input,
66 Radius radius_x,
67 Radius radius_y,
68 MorphType morph_type);
69
70 static std::shared_ptr<FilterContents> MakeMatrixFilter(
71 FilterInput::Ref input,
72 const Matrix& matrix,
73 const SamplerDescriptor& desc);
74
75 static std::shared_ptr<FilterContents> MakeLocalMatrixFilter(
76 FilterInput::Ref input,
77 const Matrix& matrix);
78
79 static std::shared_ptr<FilterContents> MakeYUVToRGBFilter(
80 std::shared_ptr<Texture> y_texture,
81 std::shared_ptr<Texture> uv_texture,
82 YUVColorSpace yuv_color_space);
83
84 static std::shared_ptr<FilterContents> MakeRuntimeEffect(
85 FilterInput::Ref input,
86 std::shared_ptr<RuntimeStage> runtime_stage,
87 std::shared_ptr<std::vector<uint8_t>> uniforms,
88 std::vector<RuntimeEffectContents::TextureInput> texture_inputs);
89
90 FilterContents();
91
92 ~FilterContents() override;
93
94 /// @brief The input texture sources for this filter. Each input's emitted
95 /// texture is expected to have premultiplied alpha colors.
96 ///
97 /// The number of required or optional textures depends on the
98 /// particular filter's implementation.
99 void SetInputs(FilterInput::Vector inputs);
100
101 /// @brief Sets the transform which gets appended to the effect of this
102 /// filter. Note that this is in addition to the entity's transform.
103 ///
104 /// This is useful for subpass rendering scenarios where it's
105 /// difficult to encode the current transform of the layer into the
106 /// Entity being rendered.
107 void SetEffectTransform(const Matrix& effect_transform);
108
109 /// @brief Create an Entity that renders this filter's output.
110 std::optional<Entity> GetEntity(
111 const ContentContext& renderer,
112 const Entity& entity,
113 const std::optional<Rect>& coverage_hint) const;
114
115 // |Contents|
116 bool Render(const ContentContext& renderer,
117 const Entity& entity,
118 RenderPass& pass) const override;
119
120 // |Contents|
121 std::optional<Rect> GetCoverage(const Entity& entity) const override;
122
123 // |Contents|
124 std::optional<Snapshot> RenderToSnapshot(
125 const ContentContext& renderer,
126 const Entity& entity,
127 const SnapshotOptions& options) const override;
128
129 /// @brief Determines the coverage of source pixels that will be needed
130 /// to produce results for the specified |output_limit| under the
131 /// specified |effect_transform|. This is essentially a reverse of
132 /// the |GetCoverage| method computing a source coverage from
133 /// an intended |output_limit| coverage.
134 ///
135 /// Both the |output_limit| and the return value are in the
136 /// transformed coordinate space, and so do not need to be
137 /// transformed or inverse transformed by the |effect_transform|
138 /// but individual parameters on the filter might be in the
139 /// untransformed space and should be transformed by the
140 /// |effect_transform| before applying them to the coverages.
141 ///
142 /// The method computes a result such that if the filter is applied
143 /// to a set of pixels filling the computed source coverage, it
144 /// should produce an output that covers the entire specified
145 /// |output_limit|.
146 ///
147 /// This is useful for subpass rendering scenarios where a filter
148 /// will be applied to the output of the subpass and we need to
149 /// determine how large of a render target to allocate in order
150 /// to collect all pixels that might affect the supplied output
151 /// coverage limit. While we might end up clipping the rendering
152 /// of the subpass to its destination, we want to avoid clipping
153 /// out any pixels that contribute to the output limit via the
154 /// filtering operation.
155 ///
156 /// @return The coverage bounds in the transformed space of any source pixel
157 /// that may be needed to produce output for the indicated filter
158 /// that covers the indicated |output_limit|.
159 std::optional<Rect> GetSourceCoverage(const Matrix& effect_transform,
160 const Rect& output_limit) const;
161
162 virtual Matrix GetLocalTransform(const Matrix& parent_transform) const;
163
164 Matrix GetTransform(const Matrix& parent_transform) const;
165
166 /// @brief Marks this filter chain as applying in a subpass scenario.
167 ///
168 /// Subpasses render in screenspace, and this setting informs filters
169 /// that the current transform matrix of the entity is not stored
170 /// in the Entity transform matrix. Instead, the effect transform
171 /// is used in this case.
172 virtual void SetRenderingMode(Entity::RenderingMode rendering_mode);
173
174 private:
175 /// @brief Internal utility method for |GetLocalCoverage| that computes
176 /// the output coverage of this filter across the specified inputs,
177 /// ignoring the coverage hint.
178 virtual std::optional<Rect> GetFilterCoverage(
179 const FilterInput::Vector& inputs,
180 const Entity& entity,
181 const Matrix& effect_transform) const;
182
183 /// @brief Internal utility method for |GetSourceCoverage| that computes
184 /// the inverse effect of this transform on the specified output
185 /// coverage, ignoring the inputs which will be accommodated by
186 /// the caller.
187 virtual std::optional<Rect> GetFilterSourceCoverage(
188 const Matrix& effect_transform,
189 const Rect& output_limit) const = 0;
190
191 /// Applies the specific filter logic to the given inputs and returns an
192 /// Entity representing the filtered result.
193 ///
194 /// This is the primary method that subclasses must implement to define their
195 /// filtering behavior. It takes the results of evaluating the filter inputs
196 /// (as Snapshots) and produces a new Entity containing the filtered output.
197 ///
198 /// @param[in] inputs The evaluated inputs to the filter, typically as
199 /// Snapshots.
200 /// @param[in] renderer The content context providing rendering resources.
201 /// @param[in] entity The entity applying this filter, providing transform,
202 /// blend mode, and other context.
203 /// @param[in] effect_transform An additional transform applied after the
204 /// entity's transform, often used in subpass scenarios.
205 /// @param[in] coverage The calculated coverage area of the filter's output
206 /// in the coordinate space after applying the entity and effect transforms.
207 /// @param[in] coverage_hint An optional hint representing the desired output
208 /// coverage area, which can be used for optimization (e.g., rendering only a
209 /// portion of the input).
210 ///
211 /// @return An optional Entity containing the rendered result of the filter.
212 /// Returns `std::nullopt` if the filter cannot be applied or results in empty
213 /// output.
214 virtual std::optional<Entity> RenderFilter(
215 const FilterInput::Vector& inputs,
216 const ContentContext& renderer,
217 const Entity& entity,
218 const Matrix& effect_transform,
219 const Rect& coverage,
220 const std::optional<Rect>& coverage_hint) const = 0;
221
222 /// @brief Internal utility method to compute the coverage of this
223 /// filter across its internally specified inputs and subject
224 /// to the coverage hint.
225 ///
226 /// Uses |GetFilterCoverage|.
227 std::optional<Rect> GetLocalCoverage(const Entity& local_entity) const;
228
229 FilterInput::Vector inputs_;
230 Matrix effect_transform_ = Matrix();
231
232 FilterContents(const FilterContents&) = delete;
233
234 FilterContents& operator=(const FilterContents&) = delete;
235 };
236
237 } // namespace impeller
238
239 #endif // FLUTTER_IMPELLER_ENTITY_CONTENTS_FILTERS_FILTER_CONTENTS_H_
impeller::ContentContext
Definition: content_context.h:122
impeller::Contents
Definition: contents.h:31
impeller::Entity
Definition: entity.h:26
impeller::Entity::TileMode
TileMode
Definition: entity.h:48
impeller::Entity::TileMode::kDecal
@ kDecal
impeller::Entity::RenderingMode
RenderingMode
Definition: entity.h:33
impeller::FilterContents
Definition: filter_contents.h:24
impeller::FilterContents::MakeGaussianBlur
static std::shared_ptr< FilterContents > MakeGaussianBlur(const FilterInput::Ref &input, Sigma sigma_x, Sigma sigma_y, Entity::TileMode tile_mode=Entity::TileMode::kDecal, std::optional< Rect > bounds=std::nullopt, BlurStyle mask_blur_style=BlurStyle::kNormal, const Geometry *mask_geometry=nullptr)
Definition: filter_contents.cc:37
impeller::FilterContents::kBlurFilterRequiredMipCount
static const int32_t kBlurFilterRequiredMipCount
Definition: filter_contents.h:26
impeller::FilterContents::BlurStyle
BlurStyle
Definition: filter_contents.h:28
impeller::FilterContents::BlurStyle::kNormal
@ kNormal
Blurred inside and outside.
impeller::FilterContents::BlurStyle::kOuter
@ kOuter
Nothing inside, blurred outside.
impeller::FilterContents::BlurStyle::kInner
@ kInner
Blurred inside, nothing outside.
impeller::FilterContents::BlurStyle::kSolid
@ kSolid
Solid inside, blurred outside.
impeller::FilterContents::GetEntity
std::optional< Entity > GetEntity(const ContentContext &renderer, const Entity &entity, const std::optional< Rect > &coverage_hint) const
Create an Entity that renders this filter's output.
Definition: filter_contents.cc:234
impeller::FilterContents::MakeDirectionalMorphology
static std::shared_ptr< FilterContents > MakeDirectionalMorphology(FilterInput::Ref input, Radius radius, Vector2 direction, MorphType morph_type)
Definition: filter_contents.cc:64
impeller::FilterContents::FilterContents
FilterContents()
impeller::FilterContents::GetCoverage
std::optional< Rect > GetCoverage(const Entity &entity) const override
Get the area of the render pass that will be affected when this contents is rendered.
Definition: filter_contents.cc:178
impeller::FilterContents::~FilterContents
~FilterContents() override
impeller::FilterContents::GetTransform
Matrix GetTransform(const Matrix &parent_transform) const
Definition: filter_contents.cc:280
impeller::FilterContents::MorphType
MorphType
Definition: filter_contents.h:39
impeller::FilterContents::MorphType::kErode
@ kErode
impeller::FilterContents::MorphType::kDilate
@ kDilate
impeller::FilterContents::Render
bool Render(const ContentContext &renderer, const Entity &entity, RenderPass &pass) const override
Definition: filter_contents.cc:149
impeller::FilterContents::MakeMorphology
static std::shared_ptr< FilterContents > MakeMorphology(FilterInput::Ref input, Radius radius_x, Radius radius_y, MorphType morph_type)
Definition: filter_contents.cc:77
impeller::FilterContents::MakeBorderMaskBlur
static std::shared_ptr< FilterContents > MakeBorderMaskBlur(FilterInput::Ref input, Sigma sigma_x, Sigma sigma_y, BlurStyle blur_style=BlurStyle::kNormal)
Definition: filter_contents.cc:52
impeller::FilterContents::MakeLocalMatrixFilter
static std::shared_ptr< FilterContents > MakeLocalMatrixFilter(FilterInput::Ref input, const Matrix &matrix)
Definition: filter_contents.cc:100
impeller::FilterContents::RenderToSnapshot
std::optional< Snapshot > RenderToSnapshot(const ContentContext &renderer, const Entity &entity, const SnapshotOptions &options) const override
Render this contents to a snapshot, respecting the entity's transform, path, clip depth,...
Definition: filter_contents.cc:255
impeller::FilterContents::SetInputs
void SetInputs(FilterInput::Vector inputs)
The input texture sources for this filter. Each input's emitted texture is expected to have premultip...
Definition: filter_contents.cc:137
impeller::FilterContents::SetRenderingMode
virtual void SetRenderingMode(Entity::RenderingMode rendering_mode)
Marks this filter chain as applying in a subpass scenario.
Definition: filter_contents.cc:284
impeller::FilterContents::GetSourceCoverage
std::optional< Rect > GetSourceCoverage(const Matrix &effect_transform, const Rect &output_limit) const
Determines the coverage of source pixels that will be needed to produce results for the specified |ou...
Definition: filter_contents.cc:212
impeller::FilterContents::SetEffectTransform
void SetEffectTransform(const Matrix &effect_transform)
Sets the transform which gets appended to the effect of this filter. Note that this is in addition to...
Definition: filter_contents.cc:141
impeller::FilterContents::MakeMatrixFilter
static std::shared_ptr< FilterContents > MakeMatrixFilter(FilterInput::Ref input, const Matrix &matrix, const SamplerDescriptor &desc)
Definition: filter_contents.cc:89
impeller::FilterContents::MakeYUVToRGBFilter
static std::shared_ptr< FilterContents > MakeYUVToRGBFilter(std::shared_ptr< Texture > y_texture, std::shared_ptr< Texture > uv_texture, YUVColorSpace yuv_color_space)
Definition: filter_contents.cc:109
impeller::FilterContents::MakeRuntimeEffect
static std::shared_ptr< FilterContents > MakeRuntimeEffect(FilterInput::Ref input, std::shared_ptr< RuntimeStage > runtime_stage, std::shared_ptr< std::vector< uint8_t >> uniforms, std::vector< RuntimeEffectContents::TextureInput > texture_inputs)
Definition: filter_contents.cc:120
impeller::FilterContents::GetLocalTransform
virtual Matrix GetLocalTransform(const Matrix &parent_transform) const
Definition: filter_contents.cc:276
impeller::FilterInput::Ref
std::shared_ptr< FilterInput > Ref
Definition: filter_input.h:32
impeller::FilterInput::Vector
std::vector< FilterInput::Ref > Vector
Definition: filter_input.h:33
impeller::Geometry
Definition: geometry.h:50
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
formats.h
entity.h
filter_input.h
geometry.h
matrix.h
impeller
Definition: allocation.cc:12
impeller::YUVColorSpace
YUVColorSpace
Definition: color.h:54
runtime_effect_contents.h
runtime_stage.h
sigma.h
impeller::Contents::SnapshotOptions
Definition: contents.h:85
impeller::Matrix
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
impeller::Radius
For convolution filters, the "radius" is the size of the convolution kernel to use on the local space...
Definition: sigma.h:48
impeller::SamplerDescriptor
Definition: sampler_descriptor.h:14
impeller::Sigma
In filters that use Gaussian distributions, "sigma" is a size of one standard deviation in terms of t...
Definition: sigma.h:32
impeller::TPoint< Scalar >
impeller::TRect< Scalar >