| 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
10 #include "impeller/entity/contents/contents.h"
11 #include "impeller/geometry/color.h"
12 #include "impeller/geometry/matrix.h"
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:
28 static constexpr BlendMode kLastPipelineBlendMode = BlendMode::kModulate;
29 static constexpr BlendMode kLastAdvancedBlendMode = BlendMode::kLuminosity;
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.
41 kSubpassAppendSnapshotTransform,
42 kSubpassPrependSnapshotTransform,
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 {
68 kDifference,
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
78 ~Entity();
79
80 Entity(Entity&&);
81
82 Entity& operator=(Entity&&);
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_
impeller::ContentContext
Definition: content_context.h:138
impeller::Entity
Definition: entity.h:26
impeller::Entity::SetTransform
void SetTransform(const Matrix &transform)
Set the global transform matrix for this Entity.
Definition: entity.cc:60
impeller::Entity::Entity
Entity()
impeller::Entity::Entity
Entity(Entity &&)
impeller::Entity::TileMode
TileMode
Definition: entity.h:48
impeller::Entity::TileMode::kDecal
@ kDecal
impeller::Entity::TileMode::kRepeat
@ kRepeat
impeller::Entity::TileMode::kClamp
@ kClamp
impeller::Entity::TileMode::kMirror
@ kMirror
impeller::Entity::GetCoverage
std::optional< Rect > GetCoverage() const
Definition: entity.cc:64
impeller::Entity::SetInheritedOpacity
bool SetInheritedOpacity(Scalar alpha)
Definition: entity.cc:105
impeller::Entity::RenderingMode
RenderingMode
Definition: entity.h:33
impeller::Entity::RenderingMode::kDirect
@ kDirect
impeller::Entity::RenderingMode::kSubpassPrependSnapshotTransform
@ kSubpassPrependSnapshotTransform
impeller::Entity::RenderingMode::kSubpassAppendSnapshotTransform
@ kSubpassAppendSnapshotTransform
impeller::Entity::GetContents
const std::shared_ptr< Contents > & GetContents() const
Definition: entity.cc:76
impeller::Entity::GetShaderTransform
Matrix GetShaderTransform(const RenderPass &pass) const
Definition: entity.cc:48
impeller::Entity::~Entity
~Entity()
impeller::Entity::SetClipDepth
void SetClipDepth(uint32_t clip_depth)
Definition: entity.cc:80
impeller::Entity::GetBlendMode
BlendMode GetBlendMode() const
Definition: entity.cc:101
impeller::Entity::SetContents
void SetContents(std::shared_ptr< Contents > contents)
Definition: entity.cc:72
impeller::Entity::SetBlendMode
void SetBlendMode(BlendMode blend_mode)
Definition: entity.cc:97
impeller::Entity::kLastAdvancedBlendMode
static constexpr BlendMode kLastAdvancedBlendMode
Definition: entity.h:29
impeller::Entity::kDepthEpsilon
static constexpr Scalar kDepthEpsilon
Definition: entity.h:31
impeller::Entity::Render
bool Render(const ContentContext &renderer, RenderPass &parent_pass) const
Definition: entity.cc:144
impeller::Entity::Clone
Entity Clone() const
Definition: entity.cc:158
impeller::Entity::AsBackgroundColor
std::optional< Color > AsBackgroundColor(ISize target_size) const
Definition: entity.cc:116
impeller::Entity::GetTransform
const Matrix & GetTransform() const
Get the global transform matrix for this Entity.
Definition: entity.cc:44
impeller::Entity::kLastPipelineBlendMode
static constexpr BlendMode kLastPipelineBlendMode
Definition: entity.h:28
impeller::Entity::GetClipDepth
uint32_t GetClipDepth() const
Definition: entity.cc:84
impeller::Entity::IsBlendModeDestructive
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
impeller::Entity::FromSnapshot
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
impeller::Entity::operator=
Entity & operator=(Entity &&)
impeller::Entity::GetShaderClipDepth
float GetShaderClipDepth() const
Definition: entity.cc:88
impeller::Entity::ClipOperation
ClipOperation
Definition: entity.h:67
impeller::Entity::ClipOperation::kIntersect
@ kIntersect
impeller::Entity::ClipOperation::kDifference
@ kDifference
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
color.h
contents.h
transform
Matrix transform
Definition: gaussian_blur_filter_contents.cc:214
matrix.h
impeller
Definition: allocation.cc:12
impeller::Scalar
float Scalar
Definition: scalar.h:19
impeller::BlendMode
BlendMode
Definition: color.h:58
impeller::BlendMode::kModulate
@ kModulate
impeller::BlendMode::kSrcOver
@ kSrcOver
impeller::BlendMode::kLuminosity
@ kLuminosity
rect.h
impeller::Matrix
A 4x4 matrix using column-major storage.
Definition: matrix.h:37
impeller::Snapshot
Represents a texture and its intended draw transform/sampler configuration.
Definition: snapshot.h:24
impeller::TSize
Definition: size.h:25