[Impeller] Document the capabilities. (#45253)

bdero · web-flow · commit 749e67a947bc · 2023-08-29T23:42:56.000Z
Add docstrings for the capabilities. Include examples/extra detail for the more confusing concepts. Also renames a couple of capabilities for consistency with format terminology: * SupportsDecalTileMode -> SupportsDecalSamplerAddressMode * SupportsMemorylessTextures -> SupportsDeviceTransientTextures PR is built on #45240 (waiting for tree to reopen).
diff --git a/impeller/core/formats.h b/impeller/core/formats.h
@@ -383,7 +383,7 @@ enum class SamplerAddressMode {
   // supported) defaults.
 
   /// @brief decal sampling mode is only supported on devices that pass
-  ///        the Capabilities.SupportsDecalTileMode check.
+  ///        the `Capabilities.SupportsDecalSamplerAddressMode` check.
   kDecal,
 };
 
diff --git a/impeller/entity/contents/atlas_contents.cc b/impeller/entity/contents/atlas_contents.cc
@@ -258,7 +258,7 @@ bool AtlasContents::Render(const ContentContext& renderer,
     VS::FrameInfo frame_info;
 
     auto dst_sampler_descriptor = sampler_descriptor_;
-    if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+    if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
       dst_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
       dst_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
     }
diff --git a/impeller/entity/contents/filters/blend_filter_contents.cc b/impeller/entity/contents/filters/blend_filter_contents.cc
@@ -176,7 +176,7 @@ static std::optional<Entity> AdvancedBlend(
     typename VS::FrameInfo frame_info;
 
     auto dst_sampler_descriptor = dst_snapshot->sampler_descriptor;
-    if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+    if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
       dst_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
       dst_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
     }
@@ -195,7 +195,7 @@ static std::optional<Entity> AdvancedBlend(
       FS::BindTextureSamplerSrc(cmd, dst_snapshot->texture, dst_sampler);
     } else {
       auto src_sampler_descriptor = src_snapshot->sampler_descriptor;
-      if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+      if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
         src_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
         src_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
       }
@@ -344,7 +344,7 @@ std::optional<Entity> BlendFilterContents::CreateForegroundAdvancedBlend(
     VS::FrameInfo frame_info;
 
     auto dst_sampler_descriptor = dst_snapshot->sampler_descriptor;
-    if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+    if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
       dst_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
       dst_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
     }
@@ -466,7 +466,7 @@ std::optional<Entity> BlendFilterContents::CreateForegroundPorterDuffBlend(
     VS::FrameInfo frame_info;
 
     auto dst_sampler_descriptor = dst_snapshot->sampler_descriptor;
-    if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+    if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
       dst_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
       dst_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
     }
diff --git a/impeller/entity/contents/filters/gaussian_blur_filter_contents.cc b/impeller/entity/contents/filters/gaussian_blur_filter_contents.cc
@@ -230,7 +230,8 @@ std::optional<Entity> DirectionalGaussianBlurFilterContents::RenderFilter(
     auto source_descriptor = source_snapshot->sampler_descriptor;
     switch (tile_mode_) {
       case Entity::TileMode::kDecal:
-        if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+        if (renderer.GetDeviceCapabilities()
+                .SupportsDecalSamplerAddressMode()) {
           input_descriptor.width_address_mode = SamplerAddressMode::kDecal;
           input_descriptor.height_address_mode = SamplerAddressMode::kDecal;
           source_descriptor.width_address_mode = SamplerAddressMode::kDecal;
@@ -263,7 +264,7 @@ std::optional<Entity> DirectionalGaussianBlurFilterContents::RenderFilter(
     bool has_alpha_mask = blur_style_ != BlurStyle::kNormal;
     bool has_decal_specialization =
         tile_mode_ == Entity::TileMode::kDecal &&
-        !renderer.GetDeviceCapabilities().SupportsDecalTileMode();
+        !renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode();
 
     if (has_alpha_mask && has_decal_specialization) {
       cmd.pipeline = renderer.GetGaussianBlurAlphaDecalPipeline(options);
diff --git a/impeller/entity/contents/filters/morphology_filter_contents.cc b/impeller/entity/contents/filters/morphology_filter_contents.cc
@@ -123,7 +123,7 @@ std::optional<Entity> DirectionalMorphologyFilterContents::RenderFilter(
     cmd.BindVertices(vtx_buffer);
 
     auto sampler_descriptor = input_snapshot->sampler_descriptor;
-    if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+    if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
       sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;
       sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;
     }
diff --git a/impeller/entity/contents/framebuffer_blend_contents.cc b/impeller/entity/contents/framebuffer_blend_contents.cc
@@ -136,7 +136,7 @@ bool FramebufferBlendContents::Render(const ContentContext& renderer,
   FS::FragInfo frag_info;
 
   auto src_sampler_descriptor = src_snapshot->sampler_descriptor;
-  if (!renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {
+  if (!renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {
     // No known devices that support framebuffer fetch but not decal tile mode.
     return false;
   }
diff --git a/impeller/entity/contents/tiled_texture_contents.cc b/impeller/entity/contents/tiled_texture_contents.cc
@@ -30,7 +30,7 @@ static std::optional<SamplerAddressMode> TileModeToAddressMode(
       return SamplerAddressMode::kRepeat;
       break;
     case Entity::TileMode::kDecal:
-      if (capabilities.SupportsDecalTileMode()) {
+      if (capabilities.SupportsDecalSamplerAddressMode()) {
         return SamplerAddressMode::kDecal;
       }
       return std::nullopt;
diff --git a/impeller/renderer/backend/gles/context_gles.cc b/impeller/renderer/backend/gles/context_gles.cc
@@ -75,8 +75,8 @@ ContextGLES::ContextGLES(std::unique_ptr<ProcTableGLES> gl,
             .SetSupportsComputeSubgroups(false)
             .SetSupportsReadFromResolve(false)
             .SetSupportsReadFromOnscreenTexture(false)
-            .SetSupportsDecalTileMode(false)
-            .SetSupportsMemorylessTextures(false)
+            .SetSupportsDecalSamplerAddressMode(false)
+            .SetSupportsDeviceTransientTextures(false)
             .Build();
   }
 
diff --git a/impeller/renderer/backend/metal/allocator_mtl.mm b/impeller/renderer/backend/metal/allocator_mtl.mm
@@ -14,7 +14,7 @@
 
 namespace impeller {
 
-static bool DeviceSupportsMemorylessTargets(id<MTLDevice> device) {
+static bool DeviceSupportsDeviceTransientTargets(id<MTLDevice> device) {
   // Refer to the "Memoryless render targets" feature in the table below:
   // https://developer.apple.com/metal/Metal-Feature-Set-Tables.pdf
   if (@available(ios 13.0, tvos 13.0, macos 10.15, *)) {
@@ -95,7 +95,7 @@ static bool SupportsLossyTextureCompression(id<MTLDevice> device) {
     return;
   }
 
-  supports_memoryless_targets_ = DeviceSupportsMemorylessTargets(device_);
+  supports_memoryless_targets_ = DeviceSupportsDeviceTransientTargets(device_);
   supports_uma_ = DeviceHasUnifiedMemoryArchitecture(device_);
   max_texture_supported_ = DeviceMaxTextureSizeSupported(device_);
 
diff --git a/impeller/renderer/backend/metal/context_mtl.mm b/impeller/renderer/backend/metal/context_mtl.mm
@@ -56,7 +56,7 @@ static bool DeviceSupportsComputeSubgroups(id<MTLDevice> device) {
       .SetSupportsSSBO(true)
       .SetSupportsBufferToTextureBlits(true)
       .SetSupportsTextureToTextureBlits(true)
-      .SetSupportsDecalTileMode(true)
+      .SetSupportsDecalSamplerAddressMode(true)
       .SetSupportsFramebufferFetch(DeviceSupportsFramebufferFetch(device))
       .SetDefaultColorFormat(color_format)
       .SetDefaultStencilFormat(PixelFormat::kS8UInt)
@@ -65,7 +65,7 @@ static bool DeviceSupportsComputeSubgroups(id<MTLDevice> device) {
       .SetSupportsComputeSubgroups(DeviceSupportsComputeSubgroups(device))
       .SetSupportsReadFromResolve(true)
       .SetSupportsReadFromOnscreenTexture(true)
-      .SetSupportsMemorylessTextures(true)
+      .SetSupportsDeviceTransientTextures(true)
       .Build();
 }
 
diff --git a/impeller/renderer/backend/vulkan/allocator_vk.cc b/impeller/renderer/backend/vulkan/allocator_vk.cc
@@ -163,7 +163,8 @@ AllocatorVK::AllocatorVK(std::weak_ptr<Context> context,
   staging_buffer_pool_.reset(CreateBufferPool(allocator));
   created_buffer_pool_ &= staging_buffer_pool_.is_valid();
   allocator_.reset(allocator);
-  supports_memoryless_textures_ = capabilities.SupportsMemorylessTextures();
+  supports_memoryless_textures_ =
+      capabilities.SupportsDeviceTransientTextures();
   is_valid_ = true;
 }
 
diff --git a/impeller/renderer/backend/vulkan/capabilities_vk.cc b/impeller/renderer/backend/vulkan/capabilities_vk.cc
@@ -378,7 +378,7 @@ bool CapabilitiesVK::SetPhysicalDevice(const vk::PhysicalDevice& device) {
     for (auto i = 0u; i < memory_properties.memoryTypeCount; i++) {
       if (memory_properties.memoryTypes[i].propertyFlags &
           vk::MemoryPropertyFlagBits::eLazilyAllocated) {
-        supports_memoryless_textures_ = true;
+        supports_device_transient_textures_ = true;
       }
     }
   }
@@ -448,13 +448,13 @@ bool CapabilitiesVK::SupportsReadFromOnscreenTexture() const {
   return false;
 }
 
-bool CapabilitiesVK::SupportsDecalTileMode() const {
+bool CapabilitiesVK::SupportsDecalSamplerAddressMode() const {
   return true;
 }
 
 // |Capabilities|
-bool CapabilitiesVK::SupportsMemorylessTextures() const {
-  return supports_memoryless_textures_;
+bool CapabilitiesVK::SupportsDeviceTransientTextures() const {
+  return supports_device_transient_textures_;
 }
 
 // |Capabilities|
diff --git a/impeller/renderer/backend/vulkan/capabilities_vk.h b/impeller/renderer/backend/vulkan/capabilities_vk.h
@@ -85,10 +85,10 @@ class CapabilitiesVK final : public Capabilities,
   bool SupportsReadFromOnscreenTexture() const override;
 
   // |Capabilities|
-  bool SupportsDecalTileMode() const override;
+  bool SupportsDecalSamplerAddressMode() const override;
 
   // |Capabilities|
-  bool SupportsMemorylessTextures() const override;
+  bool SupportsDeviceTransientTextures() const override;
 
   // |Capabilities|
   PixelFormat GetDefaultColorFormat() const override;
@@ -108,7 +108,7 @@ class CapabilitiesVK final : public Capabilities,
   PixelFormat default_depth_stencil_format_ = PixelFormat::kUnknown;
   vk::PhysicalDeviceProperties device_properties_;
   bool supports_compute_subgroups_ = false;
-  bool supports_memoryless_textures_ = false;
+  bool supports_device_transient_textures_ = false;
   bool is_valid_ = false;
 
   bool HasExtension(const std::string& ext) const;
diff --git a/impeller/renderer/capabilities.cc b/impeller/renderer/capabilities.cc
@@ -57,8 +57,8 @@ class StandardCapabilities final : public Capabilities {
   }
 
   // |Capabilities|
-  bool SupportsDecalTileMode() const override {
-    return supports_decal_tile_mode_;
+  bool SupportsDecalSamplerAddressMode() const override {
+    return supports_decal_sampler_address_mode_;
   }
 
   // |Capabilities|
@@ -76,8 +76,8 @@ class StandardCapabilities final : public Capabilities {
     return default_depth_stencil_format_;
   }
 
-  bool SupportsMemorylessTextures() const override {
-    return supports_memoryless_textures_;
+  bool SupportsDeviceTransientTextures() const override {
+    return supports_device_transient_textures_;
   }
 
  private:
@@ -90,8 +90,8 @@ class StandardCapabilities final : public Capabilities {
                        bool supports_compute_subgroups,
                        bool supports_read_from_onscreen_texture,
                        bool supports_read_from_resolve,
-                       bool supports_decal_tile_mode,
-                       bool supports_memoryless_textures,
+                       bool supports_decal_sampler_address_mode,
+                       bool supports_device_transient_textures,
                        PixelFormat default_color_format,
                        PixelFormat default_stencil_format,
                        PixelFormat default_depth_stencil_format)
@@ -105,8 +105,9 @@ class StandardCapabilities final : public Capabilities {
         supports_read_from_onscreen_texture_(
             supports_read_from_onscreen_texture),
         supports_read_from_resolve_(supports_read_from_resolve),
-        supports_decal_tile_mode_(supports_decal_tile_mode),
-        supports_memoryless_textures_(supports_memoryless_textures),
+        supports_decal_sampler_address_mode_(
+            supports_decal_sampler_address_mode),
+        supports_device_transient_textures_(supports_device_transient_textures),
         default_color_format_(default_color_format),
         default_stencil_format_(default_stencil_format),
         default_depth_stencil_format_(default_depth_stencil_format) {}
@@ -122,8 +123,8 @@ class StandardCapabilities final : public Capabilities {
   bool supports_compute_subgroups_ = false;
   bool supports_read_from_onscreen_texture_ = false;
   bool supports_read_from_resolve_ = false;
-  bool supports_decal_tile_mode_ = false;
-  bool supports_memoryless_textures_ = false;
+  bool supports_decal_sampler_address_mode_ = false;
+  bool supports_device_transient_textures_ = false;
   PixelFormat default_color_format_ = PixelFormat::kUnknown;
   PixelFormat default_stencil_format_ = PixelFormat::kUnknown;
   PixelFormat default_depth_stencil_format_ = PixelFormat::kUnknown;
@@ -204,14 +205,15 @@ CapabilitiesBuilder& CapabilitiesBuilder::SetDefaultDepthStencilFormat(
   return *this;
 }
 
-CapabilitiesBuilder& CapabilitiesBuilder::SetSupportsDecalTileMode(bool value) {
-  supports_decal_tile_mode_ = value;
+CapabilitiesBuilder& CapabilitiesBuilder::SetSupportsDecalSamplerAddressMode(
+    bool value) {
+  supports_decal_sampler_address_mode_ = value;
   return *this;
 }
 
-CapabilitiesBuilder& CapabilitiesBuilder::SetSupportsMemorylessTextures(
+CapabilitiesBuilder& CapabilitiesBuilder::SetSupportsDeviceTransientTextures(
     bool value) {
-  supports_memoryless_textures_ = value;
+  supports_device_transient_textures_ = value;
   return *this;
 }
 
@@ -226,8 +228,8 @@ std::unique_ptr<Capabilities> CapabilitiesBuilder::Build() {
       supports_compute_subgroups_,                                        //
       supports_read_from_onscreen_texture_,                               //
       supports_read_from_resolve_,                                        //
-      supports_decal_tile_mode_,                                          //
-      supports_memoryless_textures_,                                      //
+      supports_decal_sampler_address_mode_,                               //
+      supports_device_transient_textures_,                                //
       default_color_format_.value_or(PixelFormat::kUnknown),              //
       default_stencil_format_.value_or(PixelFormat::kUnknown),            //
       default_depth_stencil_format_.value_or(PixelFormat::kUnknown)       //
diff --git a/impeller/renderer/capabilities.h b/impeller/renderer/capabilities.h
diff --git a/impeller/renderer/capabilities_unittests.cc b/impeller/renderer/capabilities_unittests.cc

Original file line number	Diff line number	Diff line change
`@@ -258,7 +258,7 @@ bool AtlasContents::Render(const ContentContext& renderer,`
`258`	`258`	`VS::FrameInfo frame_info;`
`259`	`259`
`260`	`260`	`auto dst_sampler_descriptor = sampler_descriptor_;`
`261`		`- if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {`
	`261`	`+ if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {`
`262`	`262`	`dst_sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;`
`263`	`263`	`dst_sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;`
`264`	`264`	`}`
Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,7 @@ std::optional<Entity> DirectionalMorphologyFilterContents::RenderFilter(`
`123`	`123`	`cmd.BindVertices(vtx_buffer);`
`124`	`124`
`125`	`125`	`auto sampler_descriptor = input_snapshot->sampler_descriptor;`
`126`		`- if (renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {`
	`126`	`+ if (renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {`
`127`	`127`	`sampler_descriptor.width_address_mode = SamplerAddressMode::kDecal;`
`128`	`128`	`sampler_descriptor.height_address_mode = SamplerAddressMode::kDecal;`
`129`	`129`	`}`
Original file line number	Diff line number	Diff line change
`@@ -136,7 +136,7 @@ bool FramebufferBlendContents::Render(const ContentContext& renderer,`
`136`	`136`	`FS::FragInfo frag_info;`
`137`	`137`
`138`	`138`	`auto src_sampler_descriptor = src_snapshot->sampler_descriptor;`
`139`		`- if (!renderer.GetDeviceCapabilities().SupportsDecalTileMode()) {`
	`139`	`+ if (!renderer.GetDeviceCapabilities().SupportsDecalSamplerAddressMode()) {`
`140`	`140`	`// No known devices that support framebuffer fetch but not decal tile mode.`
`141`	`141`	`return false;`
`142`	`142`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ static std::optional<SamplerAddressMode> TileModeToAddressMode(`
`30`	`30`	`return SamplerAddressMode::kRepeat;`
`31`	`31`	`break;`
`32`	`32`	`case Entity::TileMode::kDecal:`
`33`		`- if (capabilities.SupportsDecalTileMode()) {`
	`33`	`+ if (capabilities.SupportsDecalSamplerAddressMode()) {`
`34`	`34`	`return SamplerAddressMode::kDecal;`
`35`	`35`	`}`
`36`	`36`	`return std::nullopt;`