[Impeller] Manage the onscreen stencil in EntityPass

impeller/aiks/picture.cc

@@ -56,9 +56,22 @@ std::shared_ptr<Texture> Picture::RenderToTexture(
   auto impeller_context = context.GetContext();
   RenderTarget target;
   if (impeller_context->GetCapabilities()->SupportsOffscreenMSAA()) {
-    target = RenderTarget::CreateOffscreenMSAA(*impeller_context, size);
+    target = RenderTarget::CreateOffscreenMSAA(
+        *impeller_context,        // context
+        size,                     // size
+        "Picture Snapshot MSAA",  // label
+        RenderTarget::
+            kDefaultColorAttachmentConfigMSAA,  // color_attachment_config
+        std::nullopt                            // stencil_attachment_config
+    );
   } else {
-    target = RenderTarget::CreateOffscreen(*impeller_context, size);
+    target = RenderTarget::CreateOffscreen(
+        *impeller_context,                            // context
+        size,                                         // size
+        "Picture Snapshot",                           // label
+        RenderTarget::kDefaultColorAttachmentConfig,  // color_attachment_config
+        std::nullopt  // stencil_attachment_config
+    );
   }
   if (!target.IsValid()) {
     VALIDATION_LOG << "Could not create valid RenderTarget.";

impeller/entity/entity_pass.cc

@@ -214,37 +214,30 @@ uint32_t EntityPass::GetTotalPassReads(ContentContext& renderer) const {
 
 bool EntityPass::Render(ContentContext& renderer,
                         const RenderTarget& render_target) const {
-  if (render_target.GetColorAttachments().empty()) {
-    VALIDATION_LOG << "The root RenderTarget must have a color attachment.";
-    return false;
-  }
-
-  if (!render_target.GetStencilAttachment().has_value()) {
-    VALIDATION_LOG << "The root RenderTarget must have a stencil attachment.";
-    return false;
-  }
+  auto root_render_target = render_target;
 
-  auto stencil_texture = render_target.GetStencilAttachment()->texture;
-  if (!stencil_texture) {
-    VALIDATION_LOG << "The root RenderTarget must have a stencil texture.";
+  if (root_render_target.GetColorAttachments().empty()) {
+    VALIDATION_LOG << "The root RenderTarget must have a color attachment.";
     return false;
   }
 
   StencilCoverageStack stencil_coverage_stack = {StencilCoverageLayer{
-      .coverage = Rect::MakeSize(render_target.GetRenderTargetSize()),
+      .coverage = Rect::MakeSize(root_render_target.GetRenderTargetSize()),
       .stencil_depth = 0}};
 
-  bool supports_root_pass_reads =
+  bool supports_onscreen_backdrop_reads =
       renderer.GetDeviceCapabilities().SupportsReadFromOnscreenTexture() &&
       // If the backend doesn't have `SupportsReadFromResolve`, we need to flip
       // between two textures when restoring a previous MSAA pass.
-      renderer.GetDeviceCapabilities().SupportsReadFromResolve() &&
-      stencil_texture->GetTextureDescriptor().storage_mode !=
-          StorageMode::kDeviceTransient;
-  if (!supports_root_pass_reads && GetTotalPassReads(renderer) > 0) {
+      renderer.GetDeviceCapabilities().SupportsReadFromResolve();
+  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 (!supports_onscreen_backdrop_reads && reads_from_onscreen_backdrop) {
     auto offscreen_target =
-        CreateRenderTarget(renderer, render_target.GetRenderTargetSize(), true,
-                           clear_color_.Premultiply());
+        CreateRenderTarget(renderer, root_render_target.GetRenderTargetSize(),
+                           true, clear_color_.Premultiply());
 
     if (!OnRender(renderer,  // renderer
                   offscreen_target.GetRenderTarget()
@@ -263,22 +256,25 @@ bool EntityPass::Render(ContentContext& renderer,
     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(),
-          render_target.GetRenderTargetTexture());
+          root_render_target.GetRenderTargetTexture());
 
       if (!blit_pass->EncodeCommands(
               renderer.GetContext()->GetResourceAllocator())) {
         VALIDATION_LOG << "Failed to encode root pass blit command.";
         return false;
       }
     } else {
-      auto render_pass = command_buffer->CreateRenderPass(render_target);
+      auto render_pass = command_buffer->CreateRenderPass(root_render_target);
       render_pass->SetLabel("EntityPass Root Render Pass");
 
       {
@@ -309,11 +305,43 @@ bool EntityPass::Render(ContentContext& renderer,
     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(0)->second;
+
+  // If a root stencil was provided by the caller, then verify that it has a
+  // configuration which can be used to render this pass.
+  if (root_render_target.GetStencilAttachment().has_value()) {
+    auto stencil_texture = root_render_target.GetStencilAttachment()->texture;
+    if (!stencil_texture) {
+      VALIDATION_LOG << "The root RenderTarget must have a stencil texture.";
+      return false;
+    }
+
+    auto stencil_storage_mode =
+        stencil_texture->GetTextureDescriptor().storage_mode;
+    if (reads_from_onscreen_backdrop &&
+        stencil_storage_mode == StorageMode::kDeviceTransient) {
+      VALIDATION_LOG << "The given root RenderTarget stencil needs to be read, "
+                        "but it's marked as transient.";
+      return false;
+    }
+  }
+  // Setup a new root stencil with an optimal configuration if one wasn't
+  // provided by the caller.
+  else {
+    root_render_target.SetupStencilAttachment(
+        *renderer.GetContext(), color0.texture->GetSize(),
+        renderer.GetContext()->GetCapabilities()->SupportsOffscreenMSAA(),
+        "ImpellerOnscreen",
+        GetDefaultStencilConfig(reads_from_onscreen_backdrop));
+  }
+
   // Set up the clear color of the root pass.
-  auto color0 = render_target.GetColorAttachments().find(0)->second;
   color0.clear_color = clear_color_.Premultiply();
-
-  auto root_render_target = render_target;
   root_render_target.SetColorAttachment(color0, 0);
 
   EntityPassTarget pass_target(

impeller/renderer/backend/metal/surface_mtl.mm

@@ -108,33 +108,8 @@
   color0.store_action = StoreAction::kMultisampleResolve;
   color0.resolve_texture = resolve_tex;
 
-  TextureDescriptor stencil_tex_desc;
-  stencil_tex_desc.storage_mode = StorageMode::kDevicePrivate;
-  stencil_tex_desc.type = TextureType::kTexture2DMultisample;
-  stencil_tex_desc.sample_count = SampleCount::kCount4;
-  stencil_tex_desc.format =
-      context->GetCapabilities()->GetDefaultStencilFormat();
-  stencil_tex_desc.size = msaa_tex_desc.size;
-  stencil_tex_desc.usage =
-      static_cast<TextureUsageMask>(TextureUsage::kRenderTarget);
-  auto stencil_tex =
-      context->GetResourceAllocator()->CreateTexture(stencil_tex_desc);
-
-  if (!stencil_tex) {
-    VALIDATION_LOG << "Could not create stencil texture.";
-    return nullptr;
-  }
-  stencil_tex->SetLabel("ImpellerOnscreenStencil");
-
-  StencilAttachment stencil0;
-  stencil0.texture = stencil_tex;
-  stencil0.clear_stencil = 0;
-  stencil0.load_action = LoadAction::kClear;
-  stencil0.store_action = StoreAction::kDontCare;
-
   RenderTarget render_target_desc;
   render_target_desc.SetColorAttachment(color0, 0u);
-  render_target_desc.SetStencilAttachment(stencil0);
 
   // The constructor is private. So make_unique may not be used.
   return std::unique_ptr<SurfaceMTL>(

impeller/renderer/backend/vulkan/surface_vk.cc

@@ -60,32 +60,8 @@ std::unique_ptr<SurfaceVK> SurfaceVK::WrapSwapchainImage(
   color0.store_action = StoreAction::kMultisampleResolve;
   color0.resolve_texture = resolve_tex;
 
-  TextureDescriptor stencil0_tex;
-  stencil0_tex.storage_mode = StorageMode::kDevicePrivate;
-  stencil0_tex.type = TextureType::kTexture2DMultisample;
-  stencil0_tex.sample_count = SampleCount::kCount4;
-  stencil0_tex.format = context->GetCapabilities()->GetDefaultStencilFormat();
-  stencil0_tex.size = msaa_tex_desc.size;
-  stencil0_tex.usage =
-      static_cast<TextureUsageMask>(TextureUsage::kRenderTarget);
-
-  auto stencil_tex =
-      context->GetResourceAllocator()->CreateTexture(stencil0_tex);
-  if (!stencil_tex) {
-    VALIDATION_LOG << "Could not create stencil texture.";
-    return nullptr;
-  }
-  stencil_tex->SetLabel("ImpellerOnscreenStencil");
-
-  StencilAttachment stencil0;
-  stencil0.texture = stencil_tex;
-  stencil0.clear_stencil = 0;
-  stencil0.load_action = LoadAction::kClear;
-  stencil0.store_action = StoreAction::kDontCare;
-
   RenderTarget render_target_desc;
   render_target_desc.SetColorAttachment(color0, 0u);
-  render_target_desc.SetStencilAttachment(stencil0);
 
   // The constructor is private. So make_unique may not be used.
   return std::unique_ptr<SurfaceVK>(