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