Flutter Impeller
impeller::Entity Class Reference

#include <entity.h>

Public Types

enum class  RenderingMode {
  kDirect ,
  kSubpassAppendSnapshotTransform ,
  kSubpassPrependSnapshotTransform
}
 
enum class  TileMode {
  kClamp ,
  kRepeat ,
  kMirror ,
  kDecal
}
 
enum class  ClipOperation {
  kDifference ,
  kIntersect
}
 

Public Member Functions

 Entity ()
 
 ~Entity ()
 
 Entity (Entity &&)
 
Entityoperator= (Entity &&)
 
const MatrixGetTransform () const
 Get the global transform matrix for this Entity. More...
 
Matrix GetShaderTransform (const RenderPass &pass) const
 
void SetTransform (const Matrix &transform)
 Set the global transform matrix for this Entity. More...
 
std::optional< RectGetCoverage () 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< ColorAsBackgroundColor (ISize target_size) const
 
Entity Clone () const
 

Static Public Member Functions

static Entity FromSnapshot (const Snapshot &snapshot, BlendMode blend_mode=BlendMode::kSrcOver)
 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

Represents a renderable object within the Impeller scene.

An Entity combines graphical content (Contents) with properties like transformation (Matrix), blend mode (BlendMode), and stencil clip depth. It serves as the primary unit for constructing and rendering scenes. Entities can be created directly or from Snapshot objects.

Definition at line 26 of file entity.h.

Member Enumeration Documentation

◆ ClipOperation

Enumerator
kDifference 
kIntersect 

Definition at line 67 of file entity.h.

67  {
69  kIntersect,
70  };

◆ RenderingMode

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 33 of file entity.h.

33  {
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  };

◆ 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 48 of file entity.h.

48  {
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  };
@ kDecal
decal sampling mode is only supported on devices that pass the Capabilities.SupportsDecalSamplerAddre...

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

Attempts to represent this entity as a solid background color.

This is an optimization. If the entity's contents can be represented as a solid color covering the entire target area, this method returns that color.

Parameters
[in]target_sizeThe size of the render target.
Returns
The background color if representable, otherwise std::nullopt.

Definition at line 116 of file entity.cc.

116  {
117  return contents_->AsBackgroundColor(*this, target_size);
118 }

◆ Clone()

Entity impeller::Entity::Clone ( ) const

◆ FromSnapshot()

Entity impeller::Entity::FromSnapshot ( const Snapshot snapshot,
BlendMode  blend_mode = BlendMode::kSrcOver 
)
static

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

Definition at line 18 of file entity.cc.

18  {
19  auto texture_rect = Rect::MakeSize(snapshot.texture->GetSize());
20 
21  auto contents = TextureContents::MakeRect(texture_rect);
22  contents->SetTexture(snapshot.texture);
23  contents->SetSamplerDescriptor(snapshot.sampler_descriptor);
24  contents->SetSourceRect(texture_rect);
25  contents->SetOpacity(snapshot.opacity);
26 
27  Entity entity;
28  entity.SetBlendMode(blend_mode);
29  entity.SetTransform(snapshot.transform);
30  entity.SetContents(contents);
31  return entity;
32 }
static std::shared_ptr< TextureContents > MakeRect(Rect destination)
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:150

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()

◆ GetClipDepth()

uint32_t impeller::Entity::GetClipDepth ( ) const

Gets the stencil clip depth level for this entity.

See also
SetClipDepth(uint32_t)
GetShaderClipDepth()
Returns
The current integer clip depth level.

Definition at line 84 of file entity.cc.

84  {
85  return clip_depth_;
86 }

Referenced by impeller::ColorSourceContents::DrawGeometry(), impeller::TextShadowCache::Lookup(), and impeller::FilterContents::Render().

◆ GetContents()

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

Definition at line 76 of file entity.cc.

76  {
77  return contents_;
78 }

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

◆ GetCoverage()

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

Calculates the axis-aligned bounding box covering this entity after its transformation is applied.

Returns
The coverage rectangle in the parent coordinate space, or std::nullopt if the entity has no contents.

Definition at line 64 of file entity.cc.

64  {
65  if (!contents_) {
66  return std::nullopt;
67  }
68 
69  return contents_->GetCoverage(*this);
70 }

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

◆ GetShaderClipDepth() [1/2]

Scalar impeller::Entity::GetShaderClipDepth ( ) const

Gets the shader-compatible depth value based on the entity's current clip depth level (clip_depth_).

See also
GetShaderClipDepth(uint32_t) for details on the conversion logic.
Returns
The floating-point depth value for shaders corresponding to the entity's clip_depth_.

Definition at line 88 of file entity.cc.

88  {
89  return Entity::GetShaderClipDepth(clip_depth_);
90 }
float GetShaderClipDepth() const
Definition: entity.cc:88

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

◆ GetShaderClipDepth() [2/2]

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

Converts an integer clip depth level into a floating-point depth value suitable for use in shaders.

The integer clip_depth represents discrete layers used for stencil clipping. This function maps that integer to a depth value within the [0, 1) range for the depth buffer. Each increment in clip_depth corresponds to a small step (kDepthEpsilon) in the shader depth.

The result is clamped to ensure it stays within the valid depth range and slightly below 1.0 to avoid potential issues with the maximum depth value.

Parameters
[in]clip_depthThe integer clip depth level.
Returns
The corresponding floating-point depth value for shaders.

Definition at line 92 of file entity.cc.

92  {
93  Scalar result = std::clamp(clip_depth * kDepthEpsilon, 0.0f, 1.0f);
94  return std::min(result, 1.0f - kDepthEpsilon);
95 }
static constexpr Scalar kDepthEpsilon
Definition: entity.h:31
float Scalar
Definition: scalar.h:19

References kDepthEpsilon.

◆ GetShaderTransform() [1/2]

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

Calculates the final transformation matrix for rendering in a shader.

This combines the entity's transform with the render pass's orthographic projection and applies the necessary adjustments based on the entity's shader clip depth.

Parameters
[in]passThe current render pass.
Returns
The combined model-view-projection matrix for the shader.

Definition at line 48 of file entity.cc.

48  {
49  return Entity::GetShaderTransform(GetShaderClipDepth(), pass, transform_);
50 }
Matrix GetShaderTransform(const RenderPass &pass) const
Definition: entity.cc:48

References GetShaderClipDepth().

Referenced by impeller::Geometry::ComputePositionGeometry(), impeller::DlVerticesGeometry::GetPositionBuffer(), impeller::FillRectGeometry::GetPositionBuffer(), impeller::StrokeRectGeometry::GetPositionBuffer(), impeller::DlVerticesGeometry::GetPositionUVColorBuffer(), impeller::AtlasContents::Render(), impeller::ColorFilterAtlasContents::Render(), impeller::SolidRRectLikeBlurContents::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 52 of file entity.cc.

54  {
56  {0, 0, shader_clip_depth}) *
57  pass.GetOrthographicTransform() * transform;
58 }
static constexpr Matrix MakeTranslateScale(const Vector3 &s, const Vector3 &t)
Definition: matrix.h:113

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

◆ GetTransform()

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

127  {
128  switch (blend_mode) {
129  case BlendMode::kClear:
130  case BlendMode::kSrc:
131  case BlendMode::kSrcIn:
132  case BlendMode::kDstIn:
133  case BlendMode::kSrcOut:
134  case BlendMode::kDstOut:
135  case BlendMode::kDstATop:
136  case BlendMode::kXor:
138  return true;
139  default:
140  return false;
141  }
142 }

References impeller::kClear, impeller::kDstATop, impeller::kDstIn, impeller::kDstOut, impeller::kModulate, impeller::kSrc, impeller::kSrcIn, impeller::kSrcOut, 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 144 of file entity.cc.

145  {
146  if (!contents_) {
147  return true;
148  }
149 
150  if (!contents_->GetCoverageHint().has_value()) {
151  contents_->SetCoverageHint(
152  Rect::MakeSize(parent_pass.GetRenderTargetSize()));
153  }
154 
155  return contents_->Render(renderer, *this, parent_pass);
156 }

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

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

◆ SetBlendMode()

◆ SetClipDepth()

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

Sets the stencil clip depth for this entity.

The clip depth determines the entity's level within a stack of stencil clips. Higher values indicate the entity is nested deeper within clips. This value is used during rendering to configure stencil buffer operations.

Parameters
[in]clip_depthThe integer clip depth level.

Definition at line 80 of file entity.cc.

80  {
81  clip_depth_ = clip_depth;
82 }

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

◆ SetContents()

◆ SetInheritedOpacity()

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

Definition at line 105 of file entity.cc.

105  {
106  if (alpha >= 1.0) {
107  return true;
108  }
109  if (blend_mode_ == BlendMode::kSrc && contents_->IsOpaque(GetTransform())) {
110  blend_mode_ = BlendMode::kSrcOver;
111  }
112  contents_->SetInheritedOpacity(alpha);
113  return true;
114 }
const Matrix & GetTransform() const
Get the global transform matrix for this Entity.
Definition: entity.cc:44

References GetTransform(), impeller::kSrc, and impeller::kSrcOver.

◆ SetTransform()

Member Data Documentation

◆ kDepthEpsilon

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

Definition at line 31 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: