| Flutter Impeller |

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
impeller::Entity Class Reference

`#include <entity.h>`

## Public Types
enum | RenderingMode { RenderingMode::kDirect, RenderingMode::kSubpassAppendSnapshotTransform, RenderingMode::kSubpassPrependSnapshotTransform }
enum | TileMode { TileMode::kClamp, TileMode::kRepeat, TileMode::kMirror, TileMode::kDecal }
enum | ClipOperation { ClipOperation::kDifference, ClipOperation::kIntersect }

## Public Member Functions
| Entity ()
| ~Entity ()
| Entity (Entity &&)
Entity & | operator= (Entity &&)
const Matrix & | GetTransform () const
| Get the global transform matrix for this Entity. More...
Matrix | GetShaderTransform (const RenderPass &pass) const
| Get the vertex shader transform used for drawing this Entity. More...
void | SetTransform (const Matrix &transform)
| Set the global transform matrix for this Entity. More...
std::optional< Rect > | GetCoverage () const
Contents::ClipCoverage | GetClipCoverage (const std::optional< Rect > &current_clip_coverage) const
void | SetContents (std::shared_ptr< Contents > contents)
const std::shared_ptr< Contents > & | GetContents () const
void | SetClipDepth (uint32_t clip_depth)
uint32_t | GetClipDepth () const
float | GetShaderClipDepth () const
void | SetBlendMode (BlendMode blend_mode)
BlendMode | GetBlendMode () const
bool | Render (const ContentContext &renderer, RenderPass &parent_pass) const
bool | SetInheritedOpacity (Scalar alpha)
std::optional< Color > | AsBackgroundColor (ISize target_size) const
Entity | Clone () const

## Static Public Member Functions
static Entity | FromSnapshot (const Snapshot &snapshot, BlendMode blend_mode=BlendMode::kSourceOver)
| Create an entity that can be used to render a given snapshot. More...
static Matrix | GetShaderTransform (Scalar clip_depth, const RenderPass &pass, const Matrix &transform)
| Static utility that computes the vertex shader transform used for drawing an Entity with a given the clip depth and RenderPass size. More...
static float | GetShaderClipDepth (uint32_t clip_depth)
static bool | IsBlendModeDestructive (BlendMode blend_mode)
| Returns true if the blend mode is "destructive", meaning that even fully transparent source colors would result in the destination getting changed. More...

## Static Public Attributes
static constexpr BlendMode | kLastPipelineBlendMode = BlendMode::kModulate
static constexpr BlendMode | kLastAdvancedBlendMode = BlendMode::kLuminosity
static constexpr Scalar | kDepthEpsilon = 1.0f / 262144.0

## Detailed Description

Definition at line 20 of file entity.h.

## Member Enumeration Documentation

## ◆ ClipOperation

enum impeller::Entity::ClipOperation
| strong

Enumerator
kDifference |
kIntersect |

Definition at line 61 of file entity.h.

61 {
62 kDifference,
63 kIntersect,
64 };

## ◆ RenderingMode

enum impeller::Entity::RenderingMode
| strong

Enumerator
kDirect | In direct mode, the Entity's transform is used as the current local-to-screen transform matrix.
kSubpassAppendSnapshotTransform | In subpass mode, the Entity passed through the filter is in screen space rather than local space, and so some filters (namely, MatrixFilterContents) need to interpret the given EffectTransform as the current transform matrix.
kSubpassPrependSnapshotTransform |

Definition at line 27 of file entity.h.

27 {
28 /// In direct mode, the Entity's transform is used as the current
29 /// local-to-screen transform matrix.
30 kDirect,
31 /// In subpass mode, the Entity passed through the filter is in screen space
32 /// rather than local space, and so some filters (namely,
33 /// MatrixFilterContents) need to interpret the given EffectTransform as the
34 /// current transform matrix.
35 kSubpassAppendSnapshotTransform,
36 kSubpassPrependSnapshotTransform,
37 };

## ◆ TileMode

enum impeller::Entity::TileMode
| strong

An enum to define how to repeat, fold, or omit colors outside of the typically defined range of the source of the colors (such as the bounds of an image or the defining geometry of a gradient).

Enumerator
kClamp | Replicate the edge color if the shader draws outside of its original bounds.
kRepeat | Repeat the shader's image horizontally and vertically (or both along and perpendicular to a gradient's geometry).
kMirror | Repeat the shader's image horizontally and vertically, seamlessly alternating mirrored images.
kDecal | Render the shader's image pixels only within its original bounds. If the shader draws outside of its original bounds, transparent black is drawn instead.

Definition at line 42 of file entity.h.

42 {
43 /// Replicate the edge color if the shader draws outside of its original
44 /// bounds.
45 kClamp,
46
47 /// Repeat the shader's image horizontally and vertically (or both along and
48 /// perpendicular to a gradient's geometry).
49 kRepeat,
50
51 /// Repeat the shader's image horizontally and vertically, seamlessly
52 /// alternating mirrored images.
53 kMirror,
54
55 /// Render the shader's image pixels only within its original bounds. If the
56 /// shader draws outside of its original bounds, transparent black is drawn
57 /// instead.
58 kDecal,
59 };

## Constructor & Destructor Documentation

## ◆ Entity() [1/2]

impeller::Entity::Entity | ( |  | ) |
| default

Referenced by Clone().

## ◆ ~Entity()

impeller::Entity::~Entity | ( |  | ) |
| default

## ◆ Entity() [2/2]

impeller::Entity::Entity | ( | Entity && |  | ) |
| default

## Member Function Documentation

## ◆ AsBackgroundColor()

std::optional< Color > impeller::Entity::AsBackgroundColor | ( | ISize | target_size | ) | const

Definition at line 128 of file entity.cc.

128 {
129 return contents_->AsBackgroundColor(*this, target_size);
130 }

## ◆ Clone()

Entity impeller::Entity::Clone | ( |  | ) | const

Definition at line 170 of file entity.cc.

170 {
171 return Entity(*this);
172 }

References Entity().

Referenced by impeller::ColorSourceContents::DrawGeometry(), impeller::FilterContents::GetCoverage(), impeller::FilterContents::GetEntity(), impeller::FilterInput::GetLocalCoverage(), and impeller::EntityPassClipStack::RecordEntity().

## ◆ FromSnapshot()

Entity impeller::Entity::FromSnapshot | ( | const Snapshot & | snapshot,
|  | BlendMode | blend_mode = `BlendMode::kSourceOver`
| ) |  |
| static

Create an entity that can be used to render a given snapshot.

Definition at line 21 of file entity.cc.

21 {
22 auto texture_rect = Rect::MakeSize(snapshot.texture->GetSize());
23
24 auto contents = TextureContents::MakeRect(texture_rect);
25 contents->SetTexture(snapshot.texture);
26 contents->SetSamplerDescriptor(snapshot.sampler_descriptor);
27 contents->SetSourceRect(texture_rect);
28 contents->SetOpacity(snapshot.opacity);
29
30 Entity entity;
31 entity.SetBlendMode(blend_mode);
32 entity.SetTransform(snapshot.transform);
33 entity.SetContents(contents);
34 return entity;
35 }

References impeller::TextureContents::MakeRect(), impeller::TRect< Scalar >::MakeSize(), impeller::Snapshot::opacity, impeller::Snapshot::sampler_descriptor, SetBlendMode(), SetContents(), SetTransform(), impeller::Snapshot::texture, and impeller::Snapshot::transform.

Referenced by impeller::AdvancedBlend(), and impeller::PipelineBlend().

## ◆ GetBlendMode()

BlendMode impeller::Entity::GetBlendMode | ( |  | ) | const

Definition at line 112 of file entity.cc.

112 {
113 return blend_mode_;
114 }

Referenced by impeller::AdvancedBlend(), impeller::ColorSourceContents::DrawGeometry(), impeller::OptionsFromPassAndEntity(), impeller::PipelineBlend(), impeller::SolidRRectBlurContents::Render(), impeller::Canvas::Restore(), and impeller::testing::TEST_P().

## ◆ GetClipCoverage()

Contents::ClipCoverage impeller::Entity::GetClipCoverage | ( | const std::optional< Rect > & | current_clip_coverage | ) | const

Definition at line 75 of file entity.cc.

76 {
77 if (!contents_) {
78 return {};
79 }
80 return contents_->GetClipCoverage(*this, current_clip_coverage);
81 }

Referenced by impeller::Canvas::Restore().

## ◆ GetClipDepth()

uint32_t impeller::Entity::GetClipDepth | ( |  | ) | const

Definition at line 95 of file entity.cc.

95 {
96 return clip_depth_;
97 }

Referenced by impeller::EntityPassClipStack::GetNextReplayResult(), impeller::GetShaderClipDepth(), and impeller::FilterContents::Render().

## ◆ GetContents()

const std::shared_ptr< Contents > & impeller::Entity::GetContents | ( |  | ) | const

Definition at line 87 of file entity.cc.

87 {
88 return contents_;
89 }

Referenced by impeller::AdvancedBlend(), impeller::EntityPassClipStack::ApplyClipState(), impeller::ContentsFilterInput::GetSnapshot(), impeller::PipelineBlend(), and impeller::Canvas::Restore().

## ◆ GetCoverage()

std::optional< Rect > impeller::Entity::GetCoverage | ( |  | ) | const

Definition at line 67 of file entity.cc.

67 {
68 if (!contents_) {
69 return std::nullopt;
70 }
71
72 return contents_->GetCoverage(*this);
73 }

Referenced by impeller::Canvas::Restore(), and impeller::testing::TEST_P().

## ◆ GetShaderClipDepth() [1/2]

Scalar impeller::Entity::GetShaderClipDepth | ( |  | ) | const

Definition at line 99 of file entity.cc.

99 {
100 return Entity::GetShaderClipDepth(clip_depth_);
101 }

Referenced by impeller::ColorSourceContents::DrawGeometry(), impeller::GetShaderClipDepth(), GetShaderTransform(), impeller::SolidRRectBlurContents::Render(), and impeller::TextContents::Render().

## ◆ GetShaderClipDepth() [2/2]

Scalar impeller::Entity::GetShaderClipDepth | ( | uint32_t | clip_depth | ) |
| static

Definition at line 103 of file entity.cc.

103 {
104 Scalar result = std::clamp(clip_depth * kDepthEpsilon, 0.0f, 1.0f);
105 return std::min(result, 1.0f - kDepthEpsilon);
106 }

References kDepthEpsilon.

## ◆ GetShaderTransform() [1/2]

Matrix impeller::Entity::GetShaderTransform | ( | const RenderPass & | pass | ) | const

Get the vertex shader transform used for drawing this Entity.

Definition at line 51 of file entity.cc.

51 {
52 return Entity::GetShaderTransform(GetShaderClipDepth(), pass, transform_);
53 }

References GetShaderClipDepth().

Referenced by impeller::Geometry::ComputePositionGeometry(), impeller::RectGeometry::GetPositionBuffer(), impeller::DlVerticesGeometry::GetPositionBuffer(), impeller::DlVerticesGeometry::GetPositionUVColorBuffer(), impeller::SolidRRectBlurContents::Render(), impeller::AtlasContents::Render(), impeller::TextContents::Render(), and impeller::TextureContents::Render().

## ◆ GetShaderTransform() [2/2]

Matrix impeller::Entity::GetShaderTransform | ( | Scalar | clip_depth,
|  | const RenderPass & | pass,
|  | const Matrix & | transform
| ) |  |
| static

Static utility that computes the vertex shader transform used for drawing an Entity with a given the clip depth and RenderPass size.

Definition at line 55 of file entity.cc.

57 {
58 return Matrix::MakeTranslation({0, 0, shader_clip_depth}) *
59 Matrix::MakeScale({1, 1, Entity::kDepthEpsilon}) *
60 pass.GetOrthographicTransform() * transform;
61 }

References impeller::RenderPass::GetOrthographicTransform(), kDepthEpsilon, impeller::Matrix::MakeScale(), impeller::Matrix::MakeTranslation(), and transform.

## ◆ GetTransform()

const Matrix & impeller::Entity::GetTransform | ( |  | ) | const

Get the global transform matrix for this Entity.

Definition at line 47 of file entity.cc.

47 {
48 return transform_;
49 }

Referenced by impeller::SolidColorContents::AsBackgroundColor(), impeller::ClipContents::GetClipCoverage(), impeller::SolidColorContents::GetCoverage(), impeller::SolidRRectBlurContents::GetCoverage(), impeller::VerticesSimpleBlendContents::GetCoverage(), impeller::AtlasContents::GetCoverage(), impeller::TextureContents::GetCoverage(), impeller::TextContents::GetCoverage(), impeller::ColorSourceContents::GetCoverage(), impeller::FilterContents::GetCoverage(), impeller::FilterContents::GetEntity(), impeller::FilterContentsFilterInput::GetLocalTransform(), impeller::FilterContentsFilterInput::GetTransform(), impeller::FilterInput::GetTransform(), impeller::TiledTextureContents::Render(), impeller::ClipContents::Render(), impeller::SolidColorContents::Render(), impeller::SolidRRectBlurContents::Render(), impeller::TextContents::Render(), impeller::TextureContents::RenderToSnapshot(), impeller::Contents::RenderToSnapshot(), impeller::Canvas::Restore(), SetInheritedOpacity(), and impeller::testing::TEST_P().

## ◆ IsBlendModeDestructive()

bool impeller::Entity::IsBlendModeDestructive | ( | BlendMode | blend_mode | ) |
| static

Returns true if the blend mode is "destructive", meaning that even fully transparent source colors would result in the destination getting changed.

This is useful for determining if EntityPass textures can be shrinkwrapped to their Entities' coverage; they can be shrinkwrapped if all of the contained Entities have non-destructive blends.

Definition at line 139 of file entity.cc.

139 {
140 switch (blend_mode) {
141 case BlendMode::kClear:
142 case BlendMode::kSource:
143 case BlendMode::kSourceIn:
144 case BlendMode::kDestinationIn:
145 case BlendMode::kSourceOut:
146 case BlendMode::kDestinationOut:
147 case BlendMode::kDestinationATop:
148 case BlendMode::kXor:
149 case BlendMode::kModulate:
150 return true;
151 default:
152 return false;
153 }
154 }

References impeller::kClear, impeller::kDestinationATop, impeller::kDestinationIn, impeller::kDestinationOut, impeller::kModulate, impeller::kSource, impeller::kSourceIn, impeller::kSourceOut, and impeller::kXor.

Referenced by impeller::Canvas::SaveLayer().

## ◆ operator=()

Entity & impeller::Entity::operator= | ( | Entity && |  | ) |
| default

## ◆ Render()

bool impeller::Entity::Render | ( | const ContentContext & | renderer,
|  | RenderPass & | parent_pass
| ) |  | const

Definition at line 156 of file entity.cc.

157 {
158 if (!contents_) {
159 return true;
160 }
161
162 if (!contents_->GetCoverageHint().has_value()) {
163 contents_->SetCoverageHint(
164 Rect::MakeSize(parent_pass.GetRenderTargetSize()));
165 }
166
167 return contents_->Render(renderer, *this, parent_pass);
168 }

References impeller::RenderPass::GetRenderTargetSize(), and impeller::TRect< Scalar >::MakeSize().

Referenced by impeller::ColorSourceContents::DrawGeometry(), impeller::EntityPlayground::OpenPlaygroundHere(), impeller::PipelineBlend(), impeller::Canvas::Restore(), impeller::Canvas::SaveLayer(), and impeller::testing::TEST_P().

## ◆ SetBlendMode()

void impeller::Entity::SetBlendMode | ( | BlendMode | blend_mode | ) |

Definition at line 108 of file entity.cc.

108 {
109 blend_mode_ = blend_mode;
110 }

Referenced by impeller::Canvas::DrawAtlas(), impeller::Canvas::DrawCircle(), impeller::Canvas::DrawImageRect(), impeller::Canvas::DrawLine(), impeller::Canvas::DrawOval(), impeller::Canvas::DrawPaint(), impeller::Canvas::DrawPath(), impeller::Canvas::DrawPoints(), impeller::Canvas::DrawRect(), impeller::Canvas::DrawRRect(), impeller::Canvas::DrawTextFrame(), impeller::Canvas::DrawVertices(), FromSnapshot(), impeller::DlImageImpeller::MakeFromYUVTextures(), impeller::PipelineBlend(), impeller::Contents::RenderToSnapshot(), impeller::Canvas::Restore(), and impeller::testing::TEST_P().

## ◆ SetClipDepth()

void impeller::Entity::SetClipDepth | ( | uint32_t | clip_depth | ) |

Definition at line 91 of file entity.cc.

91 {
92 clip_depth_ = clip_depth;
93 }

Referenced by impeller::Canvas::DrawTextFrame(), impeller::Canvas::Restore(), and impeller::Canvas::SaveLayer().

## ◆ SetContents()

void impeller::Entity::SetContents | ( | std::shared_ptr< Contents > | contents | ) |

Definition at line 83 of file entity.cc.

83 {
84 contents_ = std::move(contents);
85 }

Referenced by impeller::Canvas::ClipGeometry(), impeller::Canvas::DrawAtlas(), impeller::Canvas::DrawImageRect(), impeller::Canvas::DrawTextFrame(), impeller::Canvas::DrawVertices(), FromSnapshot(), impeller::PipelineBlend(), impeller::Canvas::Restore(), impeller::Canvas::SaveLayer(), impeller::testing::TEST(), and impeller::testing::TEST_P().

## ◆ SetInheritedOpacity()

bool impeller::Entity::SetInheritedOpacity | ( | Scalar | alpha | ) |

Definition at line 116 of file entity.cc.

116 {
117 if (alpha >= 1.0) {
118 return true;
119 }
120 if (blend_mode_ == BlendMode::kSource &&
121 contents_->IsOpaque(GetTransform())) {
122 blend_mode_ = BlendMode::kSourceOver;
123 }
124 contents_->SetInheritedOpacity(alpha);
125 return true;
126 }

References GetTransform(), impeller::kSource, and impeller::kSourceOver.

## ◆ SetTransform()

void impeller::Entity::SetTransform | ( | const Matrix & | transform | ) |

Set the global transform matrix for this Entity.

Definition at line 63 of file entity.cc.

63 {
64 transform_ = transform;
65 }

References transform.

Referenced by impeller::Canvas::ClipGeometry(), impeller::Canvas::DrawAtlas(), impeller::Canvas::DrawCircle(), impeller::Canvas::DrawImageRect(), impeller::Canvas::DrawLine(), impeller::Canvas::DrawOval(), impeller::Canvas::DrawPaint(), impeller::Canvas::DrawPath(), impeller::Canvas::DrawPoints(), impeller::Canvas::DrawRect(), impeller::Canvas::DrawRRect(), impeller::Canvas::DrawTextFrame(), impeller::Canvas::DrawVertices(), FromSnapshot(), impeller::FilterContents::GetCoverage(), impeller::FilterContents::GetEntity(), impeller::FilterInput::GetLocalCoverage(), impeller::Contents::RenderToSnapshot(), impeller::Canvas::Restore(), impeller::Canvas::SaveLayer(), impeller::testing::TEST(), and impeller::testing::TEST_P().

## Member Data Documentation

## ◆ kDepthEpsilon

constexpr Scalar impeller::Entity::kDepthEpsilon = 1.0f / 262144.0
| static constexpr

Definition at line 25 of file entity.h.

Referenced by GetShaderClipDepth(), and GetShaderTransform().

## ◆ kLastAdvancedBlendMode

constexpr BlendMode impeller::Entity::kLastAdvancedBlendMode = BlendMode::kLuminosity
| static constexpr

Definition at line 23 of file entity.h.

Referenced by impeller::testing::GetBlendModeSelection(), impeller::ColorFilterContents::MakeBlend(), and impeller::BlendFilterContents::SetBlendMode().

## ◆ kLastPipelineBlendMode

constexpr BlendMode impeller::Entity::kLastPipelineBlendMode = BlendMode::kModulate
| static constexpr

Definition at line 22 of file entity.h.

Referenced by impeller::ContentContextOptions::ApplyToPipelineDescriptor(), impeller::ColorFilterContents::MakeBlend(), impeller::VerticesSimpleBlendContents::Render(), impeller::RequiresReadbackForBlends(), impeller::Canvas::Restore(), impeller::BlendFilterContents::SetBlendMode(), and impeller::testing::TEST_P().

The documentation for this class was generated from the following files:

- impeller/entity/entity.h
- impeller/entity/entity.cc

impeller::Entity::GetShaderTransform
Matrix GetShaderTransform(const RenderPass &pass) const
Get the vertex shader transform used for drawing this Entity.
Definition: entity.cc:51
impeller::BlendMode::kDestinationATop
@ kDestinationATop
impeller::Entity::GetShaderClipDepth
float GetShaderClipDepth() const
Definition: entity.cc:99
impeller::Scalar
float Scalar
Definition: scalar.h:18
impeller::Entity::kDepthEpsilon
static constexpr Scalar kDepthEpsilon
Definition: entity.h:25
impeller::Entity::GetTransform
const Matrix & GetTransform() const
Get the global transform matrix for this Entity.
Definition: entity.cc:47
impeller::BlendMode::kSource
@ kSource
impeller::Entity::Entity
Entity()
impeller::BlendSelectValues::kDifference
@ kDifference
impeller::Matrix::MakeTranslation
static constexpr Matrix MakeTranslation(const Vector3 &t)
Definition: matrix.h:95
impeller::BlendMode::kModulate
@ kModulate
impeller::BlendMode::kSourceOut
@ kSourceOut
transform
Matrix transform
Definition: gaussian_blur_filter_contents.cc:213
impeller::BlendMode::kClear
@ kClear
impeller::BlendMode::kDestinationIn
@ kDestinationIn
impeller::BlendMode::kDestinationOut
@ kDestinationOut
impeller::SamplerAddressMode::kMirror
@ kMirror
impeller::TRect< Scalar >::MakeSize
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:150
impeller::BlendMode::kSourceIn
@ kSourceIn
impeller::BlendMode::kXor
@ kXor
impeller::TextureContents::MakeRect
static std::shared_ptr< TextureContents > MakeRect(Rect destination)
A common case factory that marks the texture contents as having a destination rectangle....
Definition: texture_contents.cc:28
impeller::Matrix::MakeScale
static constexpr Matrix MakeScale(const Vector3 &s)
Definition: matrix.h:104
impeller::BlendMode::kSourceOver
@ kSourceOver
impeller::SamplerAddressMode::kRepeat
@ kRepeat
impeller::SamplerAddressMode::kDecal
@ kDecal
decal sampling mode is only supported on devices that pass the Capabilities.SupportsDecalSamplerAddre...