Flutter Impeller
entity.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_ENTITY_H_
6 #define FLUTTER_IMPELLER_ENTITY_ENTITY_H_
7 
8 #include <cstdint>
9 
13 #include "impeller/geometry/rect.h"
14 
15 namespace impeller {
16 
17 class Renderer;
18 class RenderPass;
19 
20 /// Represents a renderable object within the Impeller scene.
21 ///
22 /// An Entity combines graphical content (`Contents`) with properties
23 /// like transformation (`Matrix`), blend mode (`BlendMode`), and stencil
24 /// clip depth. It serves as the primary unit for constructing and rendering
25 /// scenes. Entities can be created directly or from `Snapshot` objects.
26 class Entity {
27  public:
30 
31  static constexpr Scalar kDepthEpsilon = 1.0f / 262144.0;
32 
33  enum class RenderingMode {
34  /// In direct mode, the Entity's transform is used as the current
35  /// local-to-screen transform matrix.
36  kDirect,
37  /// In subpass mode, the Entity passed through the filter is in screen space
38  /// rather than local space, and so some filters (namely,
39  /// MatrixFilterContents) need to interpret the given EffectTransform as the
40  /// current transform matrix.
43  };
44 
45  /// An enum to define how to repeat, fold, or omit colors outside of the
46  /// typically defined range of the source of the colors (such as the
47  /// bounds of an image or the defining geometry of a gradient).
48  enum class TileMode {
49  /// Replicate the edge color if the shader draws outside of its original
50  /// bounds.
51  kClamp,
52 
53  /// Repeat the shader's image horizontally and vertically (or both along and
54  /// perpendicular to a gradient's geometry).
55  kRepeat,
56 
57  /// Repeat the shader's image horizontally and vertically, seamlessly
58  /// alternating mirrored images.
59  kMirror,
60 
61  /// Render the shader's image pixels only within its original bounds. If the
62  /// shader draws outside of its original bounds, transparent black is drawn
63  /// instead.
64  kDecal,
65  };
66 
67  enum class ClipOperation {
69  kIntersect,
70  };
71 
72  /// @brief Create an entity that can be used to render a given snapshot.
73  static Entity FromSnapshot(const Snapshot& snapshot,
74  BlendMode blend_mode = BlendMode::kSrcOver);
75 
76  Entity();
77 
79 
81 
83 
84  /// @brief Get the global transform matrix for this Entity.
85  const Matrix& GetTransform() const;
86 
87  /// Calculates the final transformation matrix for rendering in a shader.
88  ///
89  /// This combines the entity's transform with the render pass's orthographic
90  /// projection and applies the necessary adjustments based on the entity's
91  /// shader clip depth.
92  ///
93  /// @param[in] pass The current render pass.
94  /// @return The combined model-view-projection matrix for the shader.
95  Matrix GetShaderTransform(const RenderPass& pass) const;
96 
97  /// @brief Static utility that computes the vertex shader transform used for
98  /// drawing an Entity with a given the clip depth and RenderPass size.
99  static Matrix GetShaderTransform(Scalar clip_depth,
100  const RenderPass& pass,
101  const Matrix& transform);
102 
103  /// @brief Set the global transform matrix for this Entity.
104  void SetTransform(const Matrix& transform);
105 
106  /// Calculates the axis-aligned bounding box covering this entity after its
107  /// transformation is applied.
108  /// @return The coverage rectangle in the parent coordinate space, or
109  /// `std::nullopt` if the entity has no contents.
110  std::optional<Rect> GetCoverage() const;
111 
112  void SetContents(std::shared_ptr<Contents> contents);
113 
114  const std::shared_ptr<Contents>& GetContents() const;
115 
116  /// Sets the stencil clip depth for this entity.
117  ///
118  /// The clip depth determines the entity's level within a stack of stencil
119  /// clips. Higher values indicate the entity is nested deeper within clips.
120  /// This value is used during rendering to configure stencil buffer
121  /// operations.
122  ///
123  /// @param[in] clip_depth The integer clip depth level.
124  void SetClipDepth(uint32_t clip_depth);
125 
126  /// Gets the stencil clip depth level for this entity.
127  ///
128  /// @see SetClipDepth(uint32_t)
129  /// @see GetShaderClipDepth()
130  ///
131  /// @return The current integer clip depth level.
132  uint32_t GetClipDepth() const;
133 
134  /// Gets the shader-compatible depth value based on the entity's current clip
135  /// depth level (`clip_depth_`).
136  ///
137  /// @see GetShaderClipDepth(uint32_t) for details on the conversion logic.
138  ///
139  /// @return The floating-point depth value for shaders corresponding to the
140  /// entity's `clip_depth_`.
141  float GetShaderClipDepth() const;
142 
143  /// Converts an integer clip depth level into a floating-point depth value
144  /// suitable for use in shaders.
145  ///
146  /// The integer `clip_depth` represents discrete layers used for stencil
147  /// clipping. This function maps that integer to a depth value within the [0,
148  /// 1) range for the depth buffer. Each increment in `clip_depth` corresponds
149  /// to a small step (`kDepthEpsilon`) in the shader depth.
150  ///
151  /// The result is clamped to ensure it stays within the valid depth range and
152  /// slightly below 1.0 to avoid potential issues with the maximum depth value.
153  ///
154  /// @param[in] clip_depth The integer clip depth level.
155  /// @return The corresponding floating-point depth value for shaders.
156  static float GetShaderClipDepth(uint32_t clip_depth);
157 
158  void SetBlendMode(BlendMode blend_mode);
159 
160  BlendMode GetBlendMode() const;
161 
162  bool Render(const ContentContext& renderer, RenderPass& parent_pass) const;
163 
164  static bool IsBlendModeDestructive(BlendMode blend_mode);
165 
166  bool SetInheritedOpacity(Scalar alpha);
167 
168  /// Attempts to represent this entity as a solid background color.
169  ///
170  /// This is an optimization. If the entity's contents can be represented as a
171  /// solid color covering the entire target area, this method returns that
172  /// color.
173  ///
174  /// @param[in] target_size The size of the render target.
175  /// @return The background color if representable, otherwise `std::nullopt`.
176  std::optional<Color> AsBackgroundColor(ISize target_size) const;
177 
178  Entity Clone() const;
179 
180  private:
181  Entity(const Entity&);
182 
183  Matrix transform_;
184  std::shared_ptr<Contents> contents_;
185  BlendMode blend_mode_ = BlendMode::kSrcOver;
186  uint32_t clip_depth_ = 1u;
187 };
188 
189 } // namespace impeller
190 
191 #endif // FLUTTER_IMPELLER_ENTITY_ENTITY_H_
void SetTransform(const Matrix &transform)
Set the global transform matrix for this Entity.
Definition: entity.cc:60
Entity(Entity &&)
std::optional< Rect > GetCoverage() const
Definition: entity.cc:64
bool SetInheritedOpacity(Scalar alpha)
Definition: entity.cc:105
const std::shared_ptr< Contents > & GetContents() const
Definition: entity.cc:76
Matrix GetShaderTransform(const RenderPass &pass) const
Definition: entity.cc:48
void SetClipDepth(uint32_t clip_depth)
Definition: entity.cc:80
BlendMode GetBlendMode() const
Definition: entity.cc:101
void SetContents(std::shared_ptr< Contents > contents)
Definition: entity.cc:72
void SetBlendMode(BlendMode blend_mode)
Definition: entity.cc:97
static constexpr BlendMode kLastAdvancedBlendMode
Definition: entity.h:29
static constexpr Scalar kDepthEpsilon
Definition: entity.h:31
bool Render(const ContentContext &renderer, RenderPass &parent_pass) const
Definition: entity.cc:144
Entity Clone() const
Definition: entity.cc:158
std::optional< Color > AsBackgroundColor(ISize target_size) const
Definition: entity.cc:116
const Matrix & GetTransform() const
Get the global transform matrix for this Entity.
Definition: entity.cc:44
static constexpr BlendMode kLastPipelineBlendMode
Definition: entity.h:28
uint32_t GetClipDepth() const
Definition: entity.cc:84
static bool IsBlendModeDestructive(BlendMode blend_mode)
Returns true if the blend mode is "destructive", meaning that even fully transparent source colors wo...
Definition: entity.cc:127
static Entity FromSnapshot(const Snapshot &snapshot, BlendMode blend_mode=BlendMode::kSrcOver)
Create an entity that can be used to render a given snapshot.
Definition: entity.cc:18
Entity & operator=(Entity &&)
float GetShaderClipDepth() const
Definition: entity.cc:88
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
BlendMode
Definition: color.h:58
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
Represents a texture and its intended draw transform/sampler configuration.
Definition: snapshot.h:24