Flutter Impeller
impeller::Entity Class Reference

#include <entity.h>

Public Types

enum  RenderingMode {
  RenderingMode::kDirect,
  RenderingMode::kSubpass
}
 
enum  TileMode {
  TileMode::kClamp,
  TileMode::kRepeat,
  TileMode::kMirror,
  TileMode::kDecal
}
 
enum  ClipOperation {
  ClipOperation::kDifference,
  ClipOperation::kIntersect
}
 

Public Member Functions

 Entity ()
 
 ~Entity ()
 
 Entity (Entity &&)
 
const MatrixGetTransform () 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< RectGetCoverage () const
 
Contents::ClipCoverage GetClipCoverage (const std::optional< Rect > &current_clip_coverage) const
 
bool ShouldRender (const std::optional< Rect > &clip_coverage) const
 
void SetContents (std::shared_ptr< Contents > contents)
 
const std::shared_ptr< Contents > & GetContents () const
 
void SetClipDepth (uint32_t clip_depth)
 
void IncrementStencilDepth (uint32_t increment)
 
uint32_t GetClipDepth () const
 
void SetNewClipDepth (uint32_t clip_depth)
 
uint32_t GetNewClipDepth () const
 
float GetShaderClipDepth () const
 
void SetBlendMode (BlendMode blend_mode)
 
BlendMode GetBlendMode () const
 
bool Render (const ContentContext &renderer, RenderPass &parent_pass) const
 
bool CanInheritOpacity () const
 
bool SetInheritedOpacity (Scalar alpha)
 
std::optional< ColorAsBackgroundColor (ISize target_size) const
 
Scalar DeriveTextScale () const
 
CaptureGetCapture () const
 
void SetCapture (Capture capture) const
 
Entity Clone () const
 

Static Public Member Functions

static Entity FromSnapshot (const Snapshot &snapshot, BlendMode blend_mode=BlendMode::kSourceOver, uint32_t clip_depth=0)
 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 21 of file entity.h.

Member Enumeration Documentation

◆ ClipOperation

Enumerator
kDifference 
kIntersect 

Definition at line 61 of file entity.h.

61  {
63  kIntersect,
64  };

◆ RenderingMode

Enumerator
kDirect 

In direct mode, the Entity's transform is used as the current local-to-screen transform matrix.

kSubpass 

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.

Definition at line 28 of file entity.h.

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

◆ TileMode

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 160 of file entity.cc.

160  {
161  return contents_->AsBackgroundColor(*this, target_size);
162 }

◆ CanInheritOpacity()

bool impeller::Entity::CanInheritOpacity ( ) const

Definition at line 138 of file entity.cc.

138  {
139  if (!contents_) {
140  return false;
141  }
142  if (!((blend_mode_ == BlendMode::kSource && contents_->IsOpaque()) ||
143  blend_mode_ == BlendMode::kSourceOver)) {
144  return false;
145  }
146  return contents_->CanInheritOpacity(*this);
147 }

References impeller::kSource, and impeller::kSourceOver.

Referenced by impeller::OpacityPeepholePassDelegate::CanCollapseIntoParentPass(), and SetInheritedOpacity().

◆ Clone()

◆ DeriveTextScale()

Scalar impeller::Entity::DeriveTextScale ( ) const

Definition at line 202 of file entity.cc.

202  {
204 }

References impeller::Matrix::GetMaxBasisLengthXY(), and GetTransform().

◆ FromSnapshot()

Entity impeller::Entity::FromSnapshot ( const Snapshot snapshot,
BlendMode  blend_mode = BlendMode::kSourceOver,
uint32_t  clip_depth = 0 
)
static

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

Definition at line 22 of file entity.cc.

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

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

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

◆ GetBlendMode()

BlendMode impeller::Entity::GetBlendMode ( ) const

◆ GetCapture()

Capture & impeller::Entity::GetCapture ( ) const

Definition at line 206 of file entity.cc.

206  {
207  return capture_;
208 }

Referenced by impeller::EntityPassClipStack::ApplyClipState(), impeller::SolidColorContents::Render(), and impeller::TextureContents::Render().

◆ GetClipCoverage()

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

Definition at line 77 of file entity.cc.

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

◆ GetClipDepth()

◆ GetContents()

◆ GetCoverage()

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

Definition at line 69 of file entity.cc.

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

Referenced by impeller::EntityPassClipStack::ApplyClipState(), and impeller::testing::TEST_P().

◆ GetNewClipDepth()

uint32_t impeller::Entity::GetNewClipDepth ( ) const

Definition at line 113 of file entity.cc.

113  {
114  return new_clip_depth_;
115 }

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

◆ GetShaderClipDepth() [1/2]

Scalar impeller::Entity::GetShaderClipDepth ( ) const

◆ GetShaderClipDepth() [2/2]

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

Definition at line 121 of file entity.cc.

121  {
122  Scalar result = std::clamp(clip_depth * kDepthEpsilon, 0.0f, 1.0f);
123  return std::min(result, 1.0f - kDepthEpsilon);
124 }

References kDepthEpsilon.

◆ GetShaderTransform() [1/2]

◆ 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 57 of file entity.cc.

59  {
60  return Matrix::MakeTranslation({0, 0, shader_clip_depth}) *
62  pass.GetOrthographicTransform() * transform;
63 }

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

◆ GetTransform()

◆ IncrementStencilDepth()

void impeller::Entity::IncrementStencilDepth ( uint32_t  increment)

Definition at line 126 of file entity.cc.

126  {
127  clip_depth_ += increment;
128 }

◆ 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 171 of file entity.cc.

171  {
172  switch (blend_mode) {
173  case BlendMode::kClear:
174  case BlendMode::kSource:
180  case BlendMode::kXor:
182  return true;
183  default:
184  return false;
185  }
186 }

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

Referenced by impeller::EntityPass::SetBlendMode().

◆ Render()

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

Definition at line 188 of file entity.cc.

189  {
190  if (!contents_) {
191  return true;
192  }
193 
194  if (!contents_->GetCoverageHint().has_value()) {
195  contents_->SetCoverageHint(
196  Rect::MakeSize(parent_pass.GetRenderTargetSize()));
197  }
198 
199  return contents_->Render(renderer, *this, parent_pass);
200 }

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

Referenced by impeller::EntityPlayground::OpenPlaygroundHere(), impeller::PipelineBlend(), impeller::EntityPass::Render(), and impeller::testing::TEST_P().

◆ SetBlendMode()

◆ SetCapture()

void impeller::Entity::SetCapture ( Capture  capture) const

Definition at line 214 of file entity.cc.

214  {
215  capture_ = std::move(capture);
216 }

◆ SetClipDepth()

◆ SetContents()

◆ SetInheritedOpacity()

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

Definition at line 149 of file entity.cc.

149  {
150  if (!CanInheritOpacity()) {
151  return false;
152  }
153  if (blend_mode_ == BlendMode::kSource && contents_->IsOpaque()) {
154  blend_mode_ = BlendMode::kSourceOver;
155  }
156  contents_->SetInheritedOpacity(alpha);
157  return true;
158 }

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

◆ SetNewClipDepth()

void impeller::Entity::SetNewClipDepth ( uint32_t  clip_depth)

Definition at line 109 of file entity.cc.

109  {
110  new_clip_depth_ = clip_depth;
111 }

Referenced by impeller::EntityPass::PopClips().

◆ SetTransform()

◆ ShouldRender()

bool impeller::Entity::ShouldRender ( const std::optional< Rect > &  clip_coverage) const

Definition at line 85 of file entity.cc.

85  {
86 #ifdef IMPELLER_CONTENT_CULLING
87  return contents_->ShouldRender(*this, clip_coverage);
88 #else
89  return true;
90 #endif // IMPELLER_CONTENT_CULLING
91 }

Referenced by impeller::testing::TEST_P().

Member Data Documentation

◆ kDepthEpsilon

constexpr Scalar impeller::Entity::kDepthEpsilon = 1.0f / 262144.0
staticconstexpr

Definition at line 26 of file entity.h.

Referenced by GetShaderClipDepth(), and GetShaderTransform().

◆ kLastAdvancedBlendMode

constexpr BlendMode impeller::Entity::kLastAdvancedBlendMode = BlendMode::kLuminosity
staticconstexpr

◆ kLastPipelineBlendMode


The documentation for this class was generated from the following files:
impeller::Entity::GetShaderTransform
Matrix GetShaderTransform(const RenderPass &pass) const
Get the vertex shader transform used for drawing this Entity.
Definition: entity.cc:53
impeller::BlendMode::kDestinationATop
@ kDestinationATop
impeller::Entity::GetShaderClipDepth
float GetShaderClipDepth() const
Definition: entity.cc:117
impeller::Scalar
float Scalar
Definition: scalar.h:18
impeller::Entity::kDepthEpsilon
static constexpr Scalar kDepthEpsilon
Definition: entity.h:26
impeller::Entity::GetTransform
const Matrix & GetTransform() const
Get the global transform matrix for this Entity.
Definition: entity.cc:49
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
impeller::Entity::CanInheritOpacity
bool CanInheritOpacity() const
Definition: entity.cc:138
impeller::BlendMode::kClear
@ kClear
impeller::BlendMode::kDestinationIn
@ kDestinationIn
impeller::BlendMode::kDestinationOut
@ kDestinationOut
impeller::Matrix::GetMaxBasisLengthXY
constexpr Scalar GetMaxBasisLengthXY() const
Definition: matrix.h:295
impeller::SamplerAddressMode::kMirror
@ kMirror
impeller::TRect< Scalar >::MakeSize
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:146
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:27
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...