impeller::EntityPass Class Reference

#include <entity_pass.h>

Public Types
using	Element = std::variant< Entity, std::unique_ptr< EntityPass > >
using	BackdropFilterProc = std::function< std::shared_ptr< FilterContents >(FilterInput::Ref, const Matrix &effect_transform, Entity::RenderingMode rendering_mode)>

Public Member Functions
	EntityPass ()
	~EntityPass ()
void	SetDelegate (std::shared_ptr< EntityPassDelegate > delgate)
void	SetBoundsLimit (std::optional< Rect > bounds_limit, ContentBoundsPromise bounds_promise=ContentBoundsPromise::kUnknown)
	Set the bounds limit, which is provided by the user when creating a SaveLayer. This is a hint that allows the user to communicate that it's OK to not render content outside of the bounds. More...
std::optional< Rect >	GetBoundsLimit () const
	Get the bounds limit, which is provided by the user when creating a SaveLayer. More...
bool	GetBoundsLimitMightClipContent () const
	Indicates if the bounds limit set using |SetBoundsLimit()| might clip the contents of the pass. More...
bool	GetBoundsLimitIsSnug () const
	Indicates if the bounds limit set using |SetBoundsLimit()| is a reasonably tight estimate of the bounds of the contents. More...
size_t	GetSubpassesDepth () const
void	AddEntity (Entity entity)
	Add an entity to the current entity pass. More...
void	PushClip (Entity entity)
void	PopClips (size_t num_clips, uint64_t depth)
void	PopAllClips (uint64_t depth)
void	SetElements (std::vector< Element > elements)
EntityPass *	AddSubpass (std::unique_ptr< EntityPass > pass)
	Appends a given pass as a subpass. More...
void	AddSubpassInline (std::unique_ptr< EntityPass > pass)
	Merges a given pass into this pass. Useful for drawing pre-recorded pictures that don't require rendering into a separate subpass. More...
EntityPass *	GetSuperpass () const
bool	Render (ContentContext &renderer, const RenderTarget &render_target) const
void	IterateAllElements (const std::function< bool(Element &)> &iterator)
	Iterate all elements (entities and subpasses) in this pass, recursively including elements of child passes. The iteration order is depth-first. Whenever a subpass elements is encountered, it's included in the stream before its children. More...
void	IterateAllElements (const std::function< bool(const Element &)> &iterator) const
void	IterateAllEntities (const std::function< bool(Entity &)> &iterator)
	Iterate all entities in this pass, recursively including entities of child passes. The iteration order is depth-first. More...
void	IterateAllEntities (const std::function< bool(const Entity &)> &iterator) const
	Iterate all entities in this pass, recursively including entities of child passes. The iteration order is depth-first and does not allow modification of the entities. More...
bool	IterateUntilSubpass (const std::function< bool(Entity &)> &iterator)
	Iterate entities in this pass up until the first subpass is found. This is useful for limiting look-ahead optimizations. More...
size_t	GetElementCount () const
	Return the number of elements on this pass. More...
void	SetTransform (Matrix transform)
void	SetClipDepth (size_t clip_depth)
size_t	GetClipDepth () const
void	SetNewClipDepth (size_t clip_depth)
uint32_t	GetNewClipDepth () const
void	SetBlendMode (BlendMode blend_mode)
std::optional< Color >	GetClearColor (ISize size=ISize::Infinite()) const
	Return the premultiplied clear color of the pass entities, if any. More...
Color	GetClearColorOrDefault (ISize size=ISize::Infinite()) const
	Return the premultiplied clear color of the pass entities. More...
void	SetBackdropFilter (BackdropFilterProc proc)
void	SetEnableOffscreenCheckerboard (bool enabled)
int32_t	GetRequiredMipCount () const
void	SetRequiredMipCount (int32_t mip_count)
std::optional< Rect >	GetSubpassCoverage (const EntityPass &subpass, std::optional< Rect > coverage_limit) const
	Computes the coverage of a given subpass. This is used to determine the texture size of a given subpass before it's rendered to and passed through the subpass ImageFilter, if any. More...
std::optional< Rect >	GetElementsCoverage (std::optional< Rect > coverage_limit) const

Static Public Attributes
static const std::string	kCaptureDocumentName = "EntityPass"

Detailed Description

Definition at line 43 of file entity_pass.h.

Member Typedef Documentation

BackdropFilterProc

using impeller::EntityPass::BackdropFilterProc = std::function<std::shared_ptr<FilterContents>( FilterInput::Ref, const Matrix& effect_transform, Entity::RenderingMode rendering_mode)>

Definition at line 61 of file entity_pass.h.

Element

using impeller::EntityPass::Element = std::variant<Entity, std::unique_ptr<EntityPass> >

Elements are renderable items in the EntityPass. Each can either be an Entity or a child EntityPass.

When the element is a child EntityPass, it may be rendered to an offscreen texture and converted into an Entity that draws the texture into the current pass, or its children may be collapsed into the current

EntityPass. Elements are converted to Entities in GetEntityForElement().

Definition at line 54 of file entity_pass.h.

Constructor & Destructor Documentation

EntityPass()

impeller::EntityPass::EntityPass ( )

default

~EntityPass()

impeller::EntityPass::~EntityPass ( )

default

Member Function Documentation

AddEntity()

void impeller::EntityPass::AddEntity

(

Entity

entity

)

Add an entity to the current entity pass.

Definition at line 106 of file entity_pass.cc.

                                        {
  if (entity.GetBlendMode() == BlendMode::kSourceOver &&
      entity.GetContents()->IsOpaque()) {
    entity.SetBlendMode(BlendMode::kSource);
  }
 
  if (entity.GetBlendMode() > Entity::kLastPipelineBlendMode) {
    advanced_blend_reads_from_pass_texture_ += 1;
  }
  elements_.emplace_back(std::move(entity));
}

References impeller::Entity::GetBlendMode(), impeller::Entity::GetContents(), impeller::Entity::kLastPipelineBlendMode, impeller::kSource, impeller::kSourceOver, and impeller::Entity::SetBlendMode().

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

AddSubpass()

EntityPass * impeller::EntityPass::AddSubpass

(

std::unique_ptr< EntityPass >

pass

)

Appends a given pass as a subpass.

Definition at line 272 of file entity_pass.cc.

                                                                 {
  if (!pass) {
    return nullptr;
  }
  FML_DCHECK(pass->superpass_ == nullptr);
  pass->superpass_ = this;
 
  if (pass->backdrop_filter_proc_) {
    backdrop_filter_reads_from_pass_texture_ += 1;
  }
  if (pass->blend_mode_ > Entity::kLastPipelineBlendMode) {
    advanced_blend_reads_from_pass_texture_ += 1;
  }
 
  auto subpass_pointer = pass.get();
  elements_.emplace_back(std::move(pass));
  return subpass_pointer;
}

References impeller::Entity::kLastPipelineBlendMode.

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

AddSubpassInline()

void impeller::EntityPass::AddSubpassInline

(

std::unique_ptr< EntityPass >

pass

)

Merges a given pass into this pass. Useful for drawing pre-recorded pictures that don't require rendering into a separate subpass.

Definition at line 291 of file entity_pass.cc.

                                                                {
  if (!pass) {
    return;
  }
  FML_DCHECK(pass->superpass_ == nullptr);
 
  std::vector<Element>& elements = pass->elements_;
  for (auto i = 0u; i < elements.size(); i++) {
    elements_.emplace_back(std::move(elements[i]));
  }
 
  backdrop_filter_reads_from_pass_texture_ +=
      pass->backdrop_filter_reads_from_pass_texture_;
  advanced_blend_reads_from_pass_texture_ +=
      pass->advanced_blend_reads_from_pass_texture_;
}

GetBoundsLimit()

std::optional< Rect > impeller::EntityPass::GetBoundsLimit

(

)

const

Get the bounds limit, which is provided by the user when creating a SaveLayer.

Definition at line 71 of file entity_pass.cc.

                                                   {
  return bounds_limit_;
}

GetBoundsLimitIsSnug()

bool impeller::EntityPass::GetBoundsLimitIsSnug

(

)

const

Indicates if the bounds limit set using |SetBoundsLimit()| is a reasonably tight estimate of the bounds of the contents.

Definition at line 94 of file entity_pass.cc.

                                            {
  switch (bounds_promise_) {
    case ContentBoundsPromise::kUnknown:
      return false;
    case ContentBoundsPromise::kContainsContents:
    case ContentBoundsPromise::kMayClipContents:
      FML_DCHECK(bounds_limit_.has_value());
      return true;
  }
  FML_UNREACHABLE();
}

References impeller::kContainsContents, impeller::kMayClipContents, and impeller::kUnknown.

Referenced by GetSubpassCoverage().

GetBoundsLimitMightClipContent()

bool impeller::EntityPass::GetBoundsLimitMightClipContent

(

)

const

Indicates if the bounds limit set using |SetBoundsLimit()| might clip the contents of the pass.

Definition at line 75 of file entity_pass.cc.

                                                      {
  switch (bounds_promise_) {
    case ContentBoundsPromise::kUnknown:
      // If the promise is unknown due to not having a bounds limit,
      // then no clipping will occur. But if we have a bounds limit
      // and it is unkown, then we can make no promises about whether
      // it causes clipping of the entity pass contents and we
      // conservatively return true.
      return bounds_limit_.has_value();
    case ContentBoundsPromise::kContainsContents:
      FML_DCHECK(bounds_limit_.has_value());
      return false;
    case ContentBoundsPromise::kMayClipContents:
      FML_DCHECK(bounds_limit_.has_value());
      return true;
  }
  FML_UNREACHABLE();
}

References impeller::kContainsContents, impeller::kMayClipContents, and impeller::kUnknown.

Referenced by impeller::OpacityPeepholePassDelegate::CanCollapseIntoParentPass().

GetClearColor()

std::optional< Color > impeller::EntityPass::GetClearColor

(

ISize

size = ISize::Infinite()

)

const

Return the premultiplied clear color of the pass entities, if any.

Definition at line 1187 of file entity_pass.cc.

                                                                    {
  if (backdrop_filter_proc_) {
    return std::nullopt;
  }
 
  std::optional<Color> result = std::nullopt;
  for (const Element& element : elements_) {
    auto [entity_color, blend_mode] =
        ElementAsBackgroundColor(element, target_size);
    if (!entity_color.has_value()) {
      break;
    }
    result = result.value_or(Color::BlackTransparent())
                 .Blend(entity_color.value(), blend_mode);
  }
  if (result.has_value()) {
    return result->Premultiply();
  }
  return result;
}

References impeller::Color::BlackTransparent().

Referenced by GetClearColorOrDefault().

GetClearColorOrDefault()

Color impeller::EntityPass::GetClearColorOrDefault

(

ISize

size = ISize::Infinite()

)

const

Return the premultiplied clear color of the pass entities.

If the entity pass has no clear color, this will return transparent black.

Definition at line 1183 of file entity_pass.cc.

                                                         {
  return GetClearColor(size).value_or(Color::BlackTransparent());
}

References impeller::Color::BlackTransparent(), and GetClearColor().

Referenced by Render().

GetClipDepth()

size_t impeller::EntityPass::GetClipDepth

(

)

const

Definition at line 1166 of file entity_pass.cc.

                                      {
  return clip_depth_;
}

GetElementCount()

size_t impeller::EntityPass::GetElementCount

(

)

const

Return the number of elements on this pass.

Definition at line 1154 of file entity_pass.cc.

                                         {
  return elements_.size();
}

Referenced by impeller::OpacityPeepholePassDelegate::CanCollapseIntoParentPass().

GetElementsCoverage()

std::optional< Rect > impeller::EntityPass::GetElementsCoverage

(

std::optional< Rect >

coverage_limit

)

const

Definition at line 160 of file entity_pass.cc.

                                            {
  std::optional<Rect> accumulated_coverage;
  for (const auto& element : elements_) {
    std::optional<Rect> element_coverage;
 
    if (auto entity = std::get_if<Entity>(&element)) {
      element_coverage = entity->GetCoverage();
 
      // When the coverage limit is std::nullopt, that means there is no limit,
      // as opposed to empty coverage.
      if (element_coverage.has_value() && coverage_limit.has_value()) {
        const auto* filter = entity->GetContents()->AsFilter();
        if (!filter || filter->IsTranslationOnly()) {
          element_coverage =
              element_coverage->Intersection(coverage_limit.value());
        }
      }
    } else if (auto subpass_ptr =
                   std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      auto& subpass = *subpass_ptr->get();
 
      std::optional<Rect> unfiltered_coverage =
          GetSubpassCoverage(subpass, std::nullopt);
 
      // If the current pass elements have any coverage so far and there's a
      // backdrop filter, then incorporate the backdrop filter in the
      // pre-filtered coverage of the subpass.
      if (accumulated_coverage.has_value() && subpass.backdrop_filter_proc_) {
        std::shared_ptr<FilterContents> backdrop_filter =
            subpass.backdrop_filter_proc_(
                FilterInput::Make(accumulated_coverage.value()),
                subpass.transform_, Entity::RenderingMode::kSubpass);
        if (backdrop_filter) {
          auto backdrop_coverage = backdrop_filter->GetCoverage({});
          unfiltered_coverage =
              Rect::Union(unfiltered_coverage, backdrop_coverage);
        } else {
          VALIDATION_LOG << "The EntityPass backdrop filter proc didn't return "
                            "a valid filter.";
        }
      }
 
      if (!unfiltered_coverage.has_value()) {
        continue;
      }
 
      // Additionally, subpass textures may be passed through filters, which may
      // modify the coverage.
      //
      // Note that we currently only assume that ImageFilters (such as blurs and
      // matrix transforms) may modify coverage, although it's technically
      // possible ColorFilters to affect coverage as well. For example: A
      // ColorMatrixFilter could output a completely transparent result, and
      // we could potentially detect this case as zero coverage in the future.
      std::shared_ptr<FilterContents> image_filter =
          subpass.delegate_->WithImageFilter(*unfiltered_coverage,
                                             subpass.transform_);
      if (image_filter) {
        Entity subpass_entity;
        subpass_entity.SetTransform(subpass.transform_);
        element_coverage = image_filter->GetCoverage(subpass_entity);
      } else {
        element_coverage = unfiltered_coverage;
      }
 
      element_coverage = Rect::Intersection(element_coverage, coverage_limit);
    } else {
      FML_UNREACHABLE();
    }
 
    accumulated_coverage = Rect::Union(accumulated_coverage, element_coverage);
  }
  return accumulated_coverage;
}

References GetSubpassCoverage(), impeller::TRect< Scalar >::Intersection(), impeller::Entity::kSubpass, impeller::FilterInput::Make(), impeller::Entity::SetTransform(), impeller::TRect< Scalar >::Union(), and VALIDATION_LOG.

Referenced by GetSubpassCoverage(), and impeller::testing::TEST_P().

GetNewClipDepth()

uint32_t impeller::EntityPass::GetNewClipDepth

(

)

const

Definition at line 1174 of file entity_pass.cc.

                                           {
  return new_clip_depth_;
}

GetRequiredMipCount()

int32_t impeller::EntityPass::GetRequiredMipCount ( ) const

inline

Definition at line 186 of file entity_pass.h.

{ return required_mip_count_; }

Referenced by Render().

GetSubpassCoverage()

std::optional< Rect > impeller::EntityPass::GetSubpassCoverage	(	const EntityPass &	subpass,
		std::optional< Rect >	coverage_limit
	)		const

Computes the coverage of a given subpass. This is used to determine the texture size of a given subpass before it's rendered to and passed through the subpass ImageFilter, if any.

Parameters

[in]	subpass	The EntityPass for which to compute pre-filteredcoverage.
[in]	coverage_limit	Confines coverage to a specified area. This hint is used to trim coverage to the root framebuffer area. std::nullopt means there is no limit.

Returns

The screen space pixel area that the subpass contents will render into, prior to being transformed by the subpass ImageFilter, if any. std::nullopt means rendering the subpass will have no effect on the color attachment.

Definition at line 236 of file entity_pass.cc.

                                            {
  if (subpass.bounds_limit_.has_value() && subpass.GetBoundsLimitIsSnug()) {
    return subpass.bounds_limit_->TransformBounds(subpass.transform_);
  }
 
  std::shared_ptr<FilterContents> image_filter =
      subpass.delegate_->WithImageFilter(Rect(), subpass.transform_);
 
  // If the subpass has an image filter, then its coverage space may deviate
  // from the parent pass and make intersecting with the pass coverage limit
  // unsafe.
  if (image_filter && coverage_limit.has_value()) {
    coverage_limit = image_filter->GetSourceCoverage(subpass.transform_,
                                                     coverage_limit.value());
  }
 
  auto entities_coverage = subpass.GetElementsCoverage(coverage_limit);
  // The entities don't cover anything. There is nothing to do.
  if (!entities_coverage.has_value()) {
    return std::nullopt;
  }
 
  if (!subpass.bounds_limit_.has_value()) {
    return entities_coverage;
  }
  auto user_bounds_coverage =
      subpass.bounds_limit_->TransformBounds(subpass.transform_);
  return entities_coverage->Intersection(user_bounds_coverage);
}

References GetBoundsLimitIsSnug(), and GetElementsCoverage().

Referenced by GetElementsCoverage(), and impeller::testing::TEST_P().

GetSubpassesDepth()

size_t impeller::EntityPass::GetSubpassesDepth

(

)

const

Definition at line 149 of file entity_pass.cc.

                                           {
  size_t max_subpass_depth = 0u;
  for (const auto& element : elements_) {
    if (auto subpass = std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      max_subpass_depth =
          std::max(max_subpass_depth, subpass->get()->GetSubpassesDepth());
    }
  }
  return max_subpass_depth + 1u;
}

GetSuperpass()

EntityPass * impeller::EntityPass::GetSuperpass

(

)

const

Definition at line 268 of file entity_pass.cc.

                                           {
  return superpass_;
}

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

IterateAllElements() [1/2]

void impeller::EntityPass::IterateAllElements

(

const std::function< bool(const Element &)> &

iterator

)

const

TODO(gaaclarke): Remove duplication here between const and non-const versions.

Definition at line 1074 of file entity_pass.cc.

                                                             {
  /// TODO(gaaclarke): Remove duplication here between const and non-const
  /// versions.
  if (!iterator) {
    return;
  }
 
  for (auto& element : elements_) {
    if (!iterator(element)) {
      return;
    }
    if (auto subpass = std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      const EntityPass* entity_pass = subpass->get();
      entity_pass->IterateAllElements(iterator);
    }
  }
}

References IterateAllElements().

IterateAllElements() [2/2]

void impeller::EntityPass::IterateAllElements

(

const std::function< bool(Element &)> &

iterator

)

Iterate all elements (entities and subpasses) in this pass, recursively including elements of child passes. The iteration order is depth-first. Whenever a subpass elements is encountered, it's included in the stream before its children.

Definition at line 1058 of file entity_pass.cc.

                                                 {
  if (!iterator) {
    return;
  }
 
  for (auto& element : elements_) {
    if (!iterator(element)) {
      return;
    }
    if (auto subpass = std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      subpass->get()->IterateAllElements(iterator);
    }
  }
}

Referenced by IterateAllElements().

IterateAllEntities() [1/2]

void impeller::EntityPass::IterateAllEntities

(

const std::function< bool(const Entity &)> &

iterator

)

const

Iterate all entities in this pass, recursively including entities of child passes. The iteration order is depth-first and does not allow modification of the entities.

Definition at line 1114 of file entity_pass.cc.

                                                            {
  if (!iterator) {
    return;
  }
 
  for (const auto& element : elements_) {
    if (auto entity = std::get_if<Entity>(&element)) {
      if (!iterator(*entity)) {
        return;
      }
      continue;
    }
    if (auto subpass = std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      const EntityPass* entity_pass = subpass->get();
      entity_pass->IterateAllEntities(iterator);
      continue;
    }
    FML_UNREACHABLE();
  }
}

References IterateAllEntities().

IterateAllEntities() [2/2]

void impeller::EntityPass::IterateAllEntities

(

const std::function< bool(Entity &)> &

iterator

)

Iterate all entities in this pass, recursively including entities of child passes. The iteration order is depth-first.

Definition at line 1093 of file entity_pass.cc.

                                                {
  if (!iterator) {
    return;
  }
 
  for (auto& element : elements_) {
    if (auto entity = std::get_if<Entity>(&element)) {
      if (!iterator(*entity)) {
        return;
      }
      continue;
    }
    if (auto subpass = std::get_if<std::unique_ptr<EntityPass>>(&element)) {
      subpass->get()->IterateAllEntities(iterator);
      continue;
    }
    FML_UNREACHABLE();
  }
}

Referenced by IterateAllEntities(), and Render().

IterateUntilSubpass()

bool impeller::EntityPass::IterateUntilSubpass

(

const std::function< bool(Entity &)> &

iterator

)

Iterate entities in this pass up until the first subpass is found. This is useful for limiting look-ahead optimizations.

Returns

Returns whether a subpass was encountered.

Definition at line 1136 of file entity_pass.cc.

                                                {
  if (!iterator) {
    return true;
  }
 
  for (auto& element : elements_) {
    if (auto entity = std::get_if<Entity>(&element)) {
      if (!iterator(*entity)) {
        return false;
      }
      continue;
    }
    return true;
  }
  return false;
}

Referenced by impeller::OpacityPeepholePassDelegate::CanCollapseIntoParentPass().

PopAllClips()

void impeller::EntityPass::PopAllClips

(

uint64_t

depth

)

Definition at line 141 of file entity_pass.cc.

                                           {
  PopClips(active_clips_.size(), depth);
}

References PopClips().

Referenced by impeller::EntityPlayground::OpenPlaygroundHere().

PopClips()

void impeller::EntityPass::PopClips	(	size_t	num_clips,
		uint64_t	depth
	)

Definition at line 123 of file entity_pass.cc.

                                                          {
  if (num_clips > active_clips_.size()) {
    VALIDATION_LOG
        << "Attempted to pop more clips than are currently active. Active: "
        << active_clips_.size() << ", Popped: " << num_clips
        << ", Depth: " << depth;
  }
 
  size_t max = std::min(num_clips, active_clips_.size());
  for (size_t i = 0; i < max; i++) {
    FML_DCHECK(active_clips_.back() < elements_.size());
    Entity* element = std::get_if<Entity>(&elements_[active_clips_.back()]);
    FML_DCHECK(element);
    element->SetNewClipDepth(depth);
    active_clips_.pop_back();
  }
}

References impeller::Entity::SetNewClipDepth(), and VALIDATION_LOG.

Referenced by PopAllClips(), and impeller::Canvas::Restore().

PushClip()

void impeller::EntityPass::PushClip

(

Entity

entity

)

Definition at line 118 of file entity_pass.cc.

                                       {
  elements_.emplace_back(std::move(entity));
  active_clips_.emplace_back(elements_.size() - 1);
}

Render()

bool impeller::EntityPass::Render	(	ContentContext &	renderer,
		const RenderTarget &	render_target
	)		const

Definition at line 376 of file entity_pass.cc.

                                                                 {
  auto capture =
      renderer.GetContext()->capture.GetDocument(kCaptureDocumentName);
 
  renderer.GetRenderTargetCache()->Start();
  fml::ScopedCleanupClosure reset_state([&renderer]() {
    renderer.GetLazyGlyphAtlas()->ResetTextFrames();
    renderer.GetRenderTargetCache()->End();
  });
 
  auto root_render_target = render_target;
 
  if (root_render_target.GetColorAttachments().find(0u) ==
      root_render_target.GetColorAttachments().end()) {
    VALIDATION_LOG << "The root RenderTarget must have a color attachment.";
    return false;
  }
  if (root_render_target.GetDepthAttachment().has_value() !=
      root_render_target.GetStencilAttachment().has_value()) {
    VALIDATION_LOG << "The root RenderTarget should have a stencil attachment "
                      "iff it has a depth attachment.";
    return false;
  }
 
  capture.AddRect("Coverage",
                  Rect::MakeSize(root_render_target.GetRenderTargetSize()),
                  {.readonly = true});
 
  const auto& lazy_glyph_atlas = renderer.GetLazyGlyphAtlas();
  IterateAllEntities([&lazy_glyph_atlas](const Entity& entity) {
    if (const auto& contents = entity.GetContents()) {
      contents->PopulateGlyphAtlas(lazy_glyph_atlas, entity.DeriveTextScale());
    }
    return true;
  });
 
  EntityPassClipStack clip_stack = EntityPassClipStack(
      Rect::MakeSize(root_render_target.GetRenderTargetSize()));
 
  bool reads_from_onscreen_backdrop = GetTotalPassReads(renderer) > 0;
  // In this branch path, we need to render everything to an offscreen texture
  // and then blit the results onto the onscreen texture. If using this branch,
  // there's no need to set up a stencil attachment on the root render target.
  if (reads_from_onscreen_backdrop) {
    EntityPassTarget offscreen_target = CreateRenderTarget(
        renderer, root_render_target.GetRenderTargetSize(),
        GetRequiredMipCount(),
        GetClearColorOrDefault(render_target.GetRenderTargetSize()));
 
    if (!OnRender(renderer,  // renderer
                  capture,   // capture
                  offscreen_target.GetRenderTarget()
                      .GetRenderTargetSize(),  // root_pass_size
                  offscreen_target,            // pass_target
                  Point(),                     // global_pass_position
                  Point(),                     // local_pass_position
                  0,                           // pass_depth
                  clip_stack                   // clip_coverage_stack
                  )) {
      // Validation error messages are triggered for all `OnRender()` failure
      // cases.
      return false;
    }
 
    auto command_buffer = renderer.GetContext()->CreateCommandBuffer();
    command_buffer->SetLabel("EntityPass Root Command Buffer");
 
    // If the context supports blitting, blit the offscreen texture to the
    // onscreen texture. Otherwise, draw it to the parent texture using a
    // pipeline (slower).
    if (renderer.GetContext()
            ->GetCapabilities()
            ->SupportsTextureToTextureBlits()) {
      auto blit_pass = command_buffer->CreateBlitPass();
      blit_pass->AddCopy(
          offscreen_target.GetRenderTarget().GetRenderTargetTexture(),
          root_render_target.GetRenderTargetTexture());
      if (!blit_pass->EncodeCommands(
              renderer.GetContext()->GetResourceAllocator())) {
        VALIDATION_LOG << "Failed to encode root pass blit command.";
        return false;
      }
      if (!renderer.GetContext()
               ->GetCommandQueue()
               ->Submit({command_buffer})
               .ok()) {
        return false;
      }
    } else {
      auto render_pass = command_buffer->CreateRenderPass(root_render_target);
      render_pass->SetLabel("EntityPass Root Render Pass");
 
      {
        auto size_rect = Rect::MakeSize(
            offscreen_target.GetRenderTarget().GetRenderTargetSize());
        auto contents = TextureContents::MakeRect(size_rect);
        contents->SetTexture(
            offscreen_target.GetRenderTarget().GetRenderTargetTexture());
        contents->SetSourceRect(size_rect);
        contents->SetLabel("Root pass blit");
 
        Entity entity;
        entity.SetContents(contents);
        entity.SetBlendMode(BlendMode::kSource);
 
        if (!entity.Render(renderer, *render_pass)) {
          VALIDATION_LOG << "Failed to render EntityPass root blit.";
          return false;
        }
      }
 
      if (!render_pass->EncodeCommands()) {
        VALIDATION_LOG << "Failed to encode root pass command buffer.";
        return false;
      }
      if (!renderer.GetContext()
               ->GetCommandQueue()
               ->Submit({command_buffer})
               .ok()) {
        return false;
      }
    }
 
    return true;
  }
 
  // If we make it this far, that means the context is capable of rendering
  // everything directly to the onscreen texture.
 
  // The safety check for fetching this color attachment is at the beginning of
  // this method.
  auto color0 = root_render_target.GetColorAttachments().find(0u)->second;
 
  auto stencil_attachment = root_render_target.GetStencilAttachment();
  auto depth_attachment = root_render_target.GetDepthAttachment();
  if (!stencil_attachment.has_value() || !depth_attachment.has_value()) {
    // Setup a new root stencil with an optimal configuration if one wasn't
    // provided by the caller.
    root_render_target.SetupDepthStencilAttachments(
        *renderer.GetContext(), *renderer.GetContext()->GetResourceAllocator(),
        color0.texture->GetSize(),
        renderer.GetContext()->GetCapabilities()->SupportsOffscreenMSAA(),
        "ImpellerOnscreen", kDefaultStencilConfig);
  }
 
  // Set up the clear color of the root pass.
  color0.clear_color =
      GetClearColorOrDefault(render_target.GetRenderTargetSize());
  root_render_target.SetColorAttachment(color0, 0);
 
  EntityPassTarget pass_target(
      root_render_target,
      renderer.GetDeviceCapabilities().SupportsReadFromResolve(),
      renderer.GetDeviceCapabilities().SupportsImplicitResolvingMSAA());
 
  return OnRender(                               //
      renderer,                                  // renderer
      capture,                                   // capture
      root_render_target.GetRenderTargetSize(),  // root_pass_size
      pass_target,                               // pass_target
      Point(),                                   // global_pass_position
      Point(),                                   // local_pass_position
      0,                                         // pass_depth
      clip_stack);                               // clip_coverage_stack
}

References impeller::CreateRenderTarget(), GetClearColorOrDefault(), impeller::Entity::GetContents(), impeller::ContentContext::GetContext(), impeller::ContentContext::GetDeviceCapabilities(), impeller::ContentContext::GetLazyGlyphAtlas(), impeller::EntityPassTarget::GetRenderTarget(), impeller::ContentContext::GetRenderTargetCache(), impeller::RenderTarget::GetRenderTargetSize(), impeller::RenderTarget::GetRenderTargetTexture(), GetRequiredMipCount(), IterateAllEntities(), kCaptureDocumentName, impeller::kDefaultStencilConfig, impeller::kSource, impeller::TextureContents::MakeRect(), impeller::TRect< Scalar >::MakeSize(), impeller::Entity::Render(), impeller::Entity::SetBlendMode(), impeller::Entity::SetContents(), impeller::Capabilities::SupportsImplicitResolvingMSAA(), impeller::Capabilities::SupportsReadFromResolve(), and VALIDATION_LOG.

Referenced by impeller::EntityPlayground::OpenPlaygroundHere().

SetBackdropFilter()

void impeller::EntityPass::SetBackdropFilter

(

BackdropFilterProc

proc

)

Definition at line 1208 of file entity_pass.cc.

                                                          {
  if (superpass_) {
    VALIDATION_LOG << "Backdrop filters cannot be set on EntityPasses that "
                      "have already been appended to another pass.";
  }
 
  backdrop_filter_proc_ = std::move(proc);
}

References VALIDATION_LOG.

SetBlendMode()

void impeller::EntityPass::SetBlendMode

(

BlendMode

blend_mode

)

Definition at line 1178 of file entity_pass.cc.

                                                  {
  blend_mode_ = blend_mode;
  flood_clip_ = Entity::IsBlendModeDestructive(blend_mode);
}

References impeller::Entity::IsBlendModeDestructive().

SetBoundsLimit()

void impeller::EntityPass::SetBoundsLimit	(	std::optional< Rect >	bounds_limit,
		ContentBoundsPromise	bounds_promise = ContentBoundsPromise::kUnknown
	)

Set the bounds limit, which is provided by the user when creating a SaveLayer. This is a hint that allows the user to communicate that it's OK to not render content outside of the bounds.

For consistency with Skia, we effectively treat this like a rectangle clip by forcing the subpass texture size to never exceed it.

The entity pass will assume that these bounds cause a clipping effect on the layer unless this call is followed up with a call to |SetBoundsClipsContent()| specifying otherwise.

Definition at line 64 of file entity_pass.cc.

                                                                     {
  bounds_limit_ = bounds_limit;
  bounds_promise_ = bounds_limit.has_value() ? bounds_promise
                                             : ContentBoundsPromise::kUnknown;
}

References impeller::kUnknown.

SetClipDepth()

void impeller::EntityPass::SetClipDepth

(

size_t

clip_depth

)

Definition at line 1162 of file entity_pass.cc.

                                               {
  clip_depth_ = clip_depth;
}

SetDelegate()

void impeller::EntityPass::SetDelegate

(

std::shared_ptr< EntityPassDelegate >

delgate

)

Definition at line 57 of file entity_pass.cc.

                                                                       {
  if (!delegate) {
    return;
  }
  delegate_ = std::move(delegate);
}

SetElements()

void impeller::EntityPass::SetElements

(

std::vector< Element >

elements

)

Definition at line 145 of file entity_pass.cc.

                                                        {
  elements_ = std::move(elements);
}

SetEnableOffscreenCheckerboard()

void impeller::EntityPass::SetEnableOffscreenCheckerboard

(

bool

enabled

)

Definition at line 1217 of file entity_pass.cc.

                                                            {
  enable_offscreen_debug_checkerboard_ = enabled;
}

SetNewClipDepth()

void impeller::EntityPass::SetNewClipDepth

(

size_t

clip_depth

)

Definition at line 1170 of file entity_pass.cc.

                                                  {
  new_clip_depth_ = clip_depth;
}

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

SetRequiredMipCount()

void impeller::EntityPass::SetRequiredMipCount ( int32_t  mip_count )

inline

Definition at line 188 of file entity_pass.h.

                                              {
    required_mip_count_ = mip_count;
  }

SetTransform()

void impeller::EntityPass::SetTransform

(

Matrix

transform

)

Definition at line 1158 of file entity_pass.cc.

                                              {
  transform_ = transform;
}

Member Data Documentation

kCaptureDocumentName

const std::string impeller::EntityPass::kCaptureDocumentName = "EntityPass"

static

Definition at line 56 of file entity_pass.h.

Referenced by Render().

---

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

• impeller/entity/entity_pass.h
• impeller/entity/entity_pass.cc