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 
13 #include "impeller/geometry/rect.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 
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  //----------------------------------------------------------------------------
86  /// @brief Render this contents to a snapshot, respecting the entity's
87  /// transform, path, clip depth, and blend mode.
88  /// The result texture size is always the size of
89  /// `GetCoverage(entity)`.
90  ///
91  virtual std::optional<Snapshot> RenderToSnapshot(
92  const ContentContext& renderer,
93  const Entity& entity,
94  std::optional<Rect> coverage_limit = std::nullopt,
95  const std::optional<SamplerDescriptor>& sampler_descriptor = std::nullopt,
96  bool msaa_enabled = true,
97  int32_t mip_count = 1,
98  std::string_view label = "Snapshot") const;
99 
100  //----------------------------------------------------------------------------
101  /// @brief Return the color source's intrinsic size, if available.
102  ///
103  /// For example, a gradient has a size based on its end and beginning
104  /// points, ignoring any tiling. Solid colors and runtime effects have
105  /// no size.
106  ///
107  std::optional<Size> GetColorSourceSize() const;
108 
109  void SetColorSourceSize(Size size);
110 
111  //----------------------------------------------------------------------------
112  /// @brief Inherit the provided opacity.
113  ///
114  /// Use of this method is invalid if CanAcceptOpacity returns false.
115  ///
116  virtual void SetInheritedOpacity(Scalar opacity);
117 
118  //----------------------------------------------------------------------------
119  /// @brief Returns a color if this Contents will flood the given `target_size`
120  /// with a color. This output color is the "Source" color that will be
121  /// used for the Entity's blend operation.
122  ///
123  /// This is useful for absorbing full screen solid color draws into
124  /// subpass clear colors.
125  ///
126  virtual std::optional<Color> AsBackgroundColor(const Entity& entity,
127  ISize target_size) const;
128 
129  //----------------------------------------------------------------------------
130  /// @brief If possible, applies a color filter to this contents inputs on
131  /// the CPU.
132  ///
133  /// This method will either fully apply the color filter or
134  /// perform no action. Partial/incorrect application of the color
135  /// filter will never occur.
136  ///
137  /// @param[in] color_filter_proc A function that filters a given
138  /// unpremultiplied color to produce a new
139  /// unpremultiplied color.
140  ///
141  /// @return True if the color filter was able to be fully applied to all
142  /// all relevant inputs. Otherwise, this operation is a no-op and
143  /// false is returned.
144  ///
145  [[nodiscard]] virtual bool ApplyColorFilter(
146  const ColorFilterProc& color_filter_proc);
147 
148  private:
149  std::optional<Rect> coverage_hint_;
150  std::optional<Size> color_source_size_;
151 
152  Contents(const Contents&) = delete;
153 
154  Contents& operator=(const Contents&) = delete;
155 };
156 
157 } // namespace impeller
158 
159 #endif // FLUTTER_IMPELLER_ENTITY_CONTENTS_CONTENTS_H_
virtual bool Render(const ContentContext &renderer, const Entity &entity, RenderPass &pass) const =0
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:126
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, std::string_view label="Snapshot") const
Render this contents to a snapshot, respecting the entity's transform, path, clip depth,...
Definition: contents.cc:56
std::optional< Size > GetColorSourceSize() const
Return the color source's intrinsic size, if available.
Definition: contents.cc:144
virtual bool ApplyColorFilter(const ColorFilterProc &color_filter_proc)
If possible, applies a color filter to this contents inputs on the CPU.
Definition: contents.cc:131
const std::optional< Rect > & GetCoverageHint() const
Definition: contents.cc:140
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
void SetColorSourceSize(Size size)
Definition: contents.cc:148
std::function< std::optional< Rect >(const Entity &entity)> CoverageProc
Definition: contents.h:40
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.
virtual void SetInheritedOpacity(Scalar opacity)
Inherit the provided opacity.
Definition: contents.cc:121
static std::shared_ptr< Contents > MakeAnonymous(RenderProc render_proc, CoverageProc coverage_proc)
Definition: contents.cc:41
std::function< Color(Color)> ColorFilterProc
Definition: contents.h:35
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:136
std::function< bool(const ContentContext &renderer, const Entity &entity, RenderPass &pass)> RenderProc
Definition: contents.h:39
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
float Scalar
Definition: scalar.h:19
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:34
ContentContextOptions OptionsFromPass(const RenderPass &pass)
Definition: contents.cc:19
A 4x4 matrix using column-major storage.
Definition: matrix.h:37