[Impeller] Implement draw order optimization.

ci/licenses_golden/excluded_files

@@ -162,6 +162,7 @@
 ../../../flutter/impeller/entity/contents/host_buffer_unittests.cc
 ../../../flutter/impeller/entity/contents/test
 ../../../flutter/impeller/entity/contents/tiled_texture_contents_unittests.cc
+../../../flutter/impeller/entity/draw_order_resolver_unittests.cc
 ../../../flutter/impeller/entity/entity_pass_target_unittests.cc
 ../../../flutter/impeller/entity/entity_pass_unittests.cc
 ../../../flutter/impeller/entity/entity_unittests.cc

ci/licenses_golden/licenses_flutter

@@ -42128,6 +42128,8 @@ ORIGIN: ../../../flutter/impeller/entity/contents/tiled_texture_contents.cc + ..
 ORIGIN: ../../../flutter/impeller/entity/contents/tiled_texture_contents.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/impeller/entity/contents/vertices_contents.cc + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/impeller/entity/contents/vertices_contents.h + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/impeller/entity/draw_order_resolver.cc + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/impeller/entity/draw_order_resolver.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/impeller/entity/entity.cc + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/impeller/entity/entity.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/impeller/entity/entity_pass.cc + ../../../flutter/LICENSE
@@ -45010,6 +45012,8 @@ FILE: ../../../flutter/impeller/entity/contents/tiled_texture_contents.cc
 FILE: ../../../flutter/impeller/entity/contents/tiled_texture_contents.h
 FILE: ../../../flutter/impeller/entity/contents/vertices_contents.cc
 FILE: ../../../flutter/impeller/entity/contents/vertices_contents.h
+FILE: ../../../flutter/impeller/entity/draw_order_resolver.cc
+FILE: ../../../flutter/impeller/entity/draw_order_resolver.h
 FILE: ../../../flutter/impeller/entity/entity.cc
 FILE: ../../../flutter/impeller/entity/entity.h
 FILE: ../../../flutter/impeller/entity/entity_pass.cc

impeller/entity/BUILD.gn

@@ -166,6 +166,8 @@ impeller_component("entity") {
     "contents/tiled_texture_contents.h",
     "contents/vertices_contents.cc",
     "contents/vertices_contents.h",
+    "draw_order_resolver.cc",
+    "draw_order_resolver.h",
     "entity.cc",
     "entity.h",
     "entity_pass.cc",
@@ -248,6 +250,7 @@ impeller_component("entity_unittests") {
     "contents/filters/matrix_filter_contents_unittests.cc",
     "contents/host_buffer_unittests.cc",
     "contents/tiled_texture_contents_unittests.cc",
+    "draw_order_resolver_unittests.cc",
     "entity_pass_target_unittests.cc",
     "entity_pass_unittests.cc",
     "entity_playground.cc",

impeller/entity/contents/color_source_contents.h

@@ -213,6 +213,11 @@ class ColorSourceContents : public Contents {
     pass.SetVertexBuffer(std::move(geometry_result.vertex_buffer));
     options.primitive_type = geometry_result.type;
 
+    // Enable depth writing for all opaque entities in order to allow
+    // reordering. Opaque entities are coerced to source blending by
+    // `EntityPass::AddEntity`.
+    options.depth_write_enabled = options.blend_mode == BlendMode::kSource;
+
     // Take the pre-populated vertex shader uniform struct and set managed
     // values.
     frame_info.mvp = geometry_result.transform;

impeller/entity/contents/texture_contents.cc

@@ -153,6 +153,9 @@ bool TextureContents::Render(const ContentContext& renderer,
   }
   pipeline_options.primitive_type = PrimitiveType::kTriangleStrip;
 
+  pipeline_options.depth_write_enabled =
+      stencil_enabled_ && pipeline_options.blend_mode == BlendMode::kSource;
+
   pass.SetPipeline(strict_source_rect_enabled_
                        ? renderer.GetTextureStrictSrcPipeline(pipeline_options)
                        : renderer.GetTexturePipeline(pipeline_options));

impeller/entity/draw_order_resolver.cc

@@ -0,0 +1,77 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "impeller/entity/draw_order_resolver.h"
+
+#include "flutter/fml/logging.h"
+#include "impeller/base/validation.h"
+
+namespace impeller {
+
+DrawOrderResolver::DrawOrderResolver() : draw_order_layers_({{}}){};
+
+void DrawOrderResolver::AddElement(size_t element_index, bool is_opaque) {
+  DrawOrderLayer& layer = draw_order_layers_.back();
+  if (is_opaque) {
+    layer.opaque_elements.push_back(element_index);
+  } else {
+    layer.dependent_elements.push_back(element_index);
+  }
+}
+void DrawOrderResolver::PushClip(size_t element_index) {
+  draw_order_layers_.back().dependent_elements.push_back(element_index);
+  draw_order_layers_.push_back({});
+};
+
+void DrawOrderResolver::PopClip() {
+  if (draw_order_layers_.size() == 1u) {
+    // This is likely recoverable, so don't assert.
+    VALIDATION_LOG
+        << "Attemped to pop the root draw order layer. This is a bug in "
+           "`EntityPass`.";
+    return;
+  }
+
+  DrawOrderLayer& layer = draw_order_layers_.back();
+  DrawOrderLayer& parent_layer =
+      draw_order_layers_[draw_order_layers_.size() - 2];
+
+  layer.WriteCombinedDraws(parent_layer.dependent_elements, 0, 0);
+
+  draw_order_layers_.pop_back();
+}
+
+DrawOrderResolver::ElementRefs DrawOrderResolver::GetSortedDraws(
+    size_t opaque_skip_count,
+    size_t translucent_skip_count) const {
+  FML_DCHECK(draw_order_layers_.size() == 1u);
+
+  ElementRefs sorted_elements;
+  draw_order_layers_.back().WriteCombinedDraws(
+      sorted_elements, opaque_skip_count, translucent_skip_count);
+
+  return sorted_elements;
+}
+
+void DrawOrderResolver::DrawOrderLayer::WriteCombinedDraws(
+    ElementRefs& destination,
+    size_t opaque_skip_count,
+    size_t translucent_skip_count) const {
+  FML_DCHECK(opaque_skip_count <= opaque_elements.size());
+  FML_DCHECK(translucent_skip_count <= dependent_elements.size());
+
+  destination.reserve(destination.size() +                          //
+                      opaque_elements.size() - opaque_skip_count +  //
+                      dependent_elements.size());
+
+  // Draw backdrop-independent elements first.
+  destination.insert(destination.end(), opaque_elements.rbegin(),
+                     opaque_elements.rend() - opaque_skip_count);
+  // Then, draw backdrop-dependent elements in their original order.
+  destination.insert(destination.end(),
+                     dependent_elements.begin() + translucent_skip_count,
+                     dependent_elements.end());
+}
+
+}  // namespace impeller

impeller/entity/draw_order_resolver.h

@@ -0,0 +1,85 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_IMPELLER_ENTITY_DRAW_ORDER_RESOLVER_H_
+#define FLUTTER_IMPELLER_ENTITY_DRAW_ORDER_RESOLVER_H_
+
+#include <vector>
+
+namespace impeller {
+
+/// Helper that records draw indices in painter's order and sorts the draws into
+/// an optimized order based on translucency and clips.
+class DrawOrderResolver {
+ public:
+  using ElementRefs = std::vector<size_t>;
+
+  DrawOrderResolver();
+
+  void AddElement(size_t element_index, bool is_opaque);
+
+  void PushClip(size_t element_index);
+
+  void PopClip();
+
+  //-------------------------------------------------------------------------
+  /// @brief      Returns the sorted draws for the current draw order layer.
+  ///             This should only be called after all recording has finished.
+  ///
+  /// @param[in]  opaque_skip_count       The number of opaque elements to skip
+  ///                                     when appending the combined elements.
+  ///                                     This is used for the "clear color"
+  ///                                     optimization.
+  /// @param[in]  translucent_skip_count  The number of translucent elements to
+  ///                                     skip when appending the combined
+  ///                                     elements. This is used for the
+  ///                                     "clear color" optimization.
+  ///
+  ElementRefs GetSortedDraws(size_t opaque_skip_count,
+                             size_t translucent_skip_count) const;
+
+ private:
+  /// A data structure for collecting sorted draws for a given "draw order
+  /// layer". Currently these layers just correspond to the local clip stack.
+  struct DrawOrderLayer {
+    /// The list of backdrop-independent elements (always just opaque). These
+    /// are order independent, and so we draw them optimally render these
+    /// elements in reverse painter's order so that they cull one another
+    ElementRefs opaque_elements;
+
+    /// The list of backdrop-dependent elements with respect to this draw
+    /// order layer. These elements are drawn after all of the independent
+    /// elements.
+    /// The elements of all child draw layers will be resolved to this list.
+    ElementRefs dependent_elements;
+
+    //-----------------------------------------------------------------------
+    /// @brief      Appends the combined opaque and transparent elements into
+    ///             a final destination buffer.
+    ///
+    /// @param[in]  destination             The buffer to append the combined
+    ///                                     elements to.
+    /// @param[in]  opaque_skip_count       The number of opaque elements to
+    ///                                     skip when appending the combined
+    ///                                     elements. This is used for the
+    ///                                     "clear color" optimization.
+    /// @param[in]  translucent_skip_count  The number of translucent elements
+    ///                                     to skip when appending the combined
+    ///                                     elements. This is used for the
+    ///                                     "clear color" optimization.
+    ///
+    void WriteCombinedDraws(ElementRefs& destination,
+                            size_t opaque_skip_count,
+                            size_t translucent_skip_count) const;
+  };
+  std::vector<DrawOrderLayer> draw_order_layers_;
+
+  DrawOrderResolver(const DrawOrderResolver&) = delete;
+
+  DrawOrderResolver& operator=(const DrawOrderResolver&) = delete;
+};
+
+}  // namespace impeller
+
+#endif  // FLUTTER_IMPELLER_ENTITY_DRAW_ORDER_RESOLVER_H_

impeller/entity/draw_order_resolver_unittests.cc

@@ -0,0 +1,115 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "flutter/testing/testing.h"
+#include "impeller/entity/draw_order_resolver.h"
+#include "third_party/googletest/googletest/include/gtest/gtest.h"
+
+namespace impeller {
+namespace testing {
+
+TEST(DrawOrderResolverTest, GetSortedDrawsReturnsCorrectOrderWithNoClips) {
+  DrawOrderResolver resolver;
+
+  // Opaque items.
+  resolver.AddElement(0, true);
+  resolver.AddElement(1, true);
+  // Translucent items.
+  resolver.AddElement(2, false);
+  resolver.AddElement(3, false);
+
+  auto sorted_elements = resolver.GetSortedDraws(0, 0);
+
+  EXPECT_EQ(sorted_elements.size(), 4u);
+  // First, the opaque items are drawn in reverse order.
+  EXPECT_EQ(sorted_elements[0], 1u);
+  EXPECT_EQ(sorted_elements[1], 0u);
+  // Then the translucent items are drawn.
+  EXPECT_EQ(sorted_elements[2], 2u);
+  EXPECT_EQ(sorted_elements[3], 3u);
+}
+
+TEST(DrawOrderResolverTest, GetSortedDrawsReturnsCorrectOrderWithClips) {
+  DrawOrderResolver resolver;
+
+  // Items before clip.
+  resolver.AddElement(0, false);
+  resolver.AddElement(1, true);
+  resolver.AddElement(2, false);
+  resolver.AddElement(3, true);
+
+  // Clip.
+  resolver.PushClip(4);
+  {
+    // Clipped items.
+    resolver.AddElement(5, false);
+    resolver.AddElement(6, false);
+    // Clipped translucent items.
+    resolver.AddElement(7, true);
+    resolver.AddElement(8, true);
+  }
+  resolver.PopClip();
+
+  // Items after clip.
+  resolver.AddElement(9, true);
+  resolver.AddElement(10, false);
+  resolver.AddElement(11, true);
+  resolver.AddElement(12, false);
+
+  auto sorted_elements = resolver.GetSortedDraws(0, 0);
+
+  EXPECT_EQ(sorted_elements.size(), 13u);
+  // First, all the non-clipped opaque items are drawn in reverse order.
+  EXPECT_EQ(sorted_elements[0], 11u);
+  EXPECT_EQ(sorted_elements[1], 9u);
+  EXPECT_EQ(sorted_elements[2], 3u);
+  EXPECT_EQ(sorted_elements[3], 1u);
+  // Then, non-clipped translucent items that came before the clip are drawn in
+  // their original order.
+  EXPECT_EQ(sorted_elements[4], 0u);
+  EXPECT_EQ(sorted_elements[5], 2u);
+
+  // Then, the clip and its sorted child items are drawn.
+  EXPECT_EQ(sorted_elements[6], 4u);
+  {
+    // Opaque clipped items are drawn in reverse order.
+    EXPECT_EQ(sorted_elements[7], 8u);
+    EXPECT_EQ(sorted_elements[8], 7u);
+    // Translucent clipped items are drawn.
+    EXPECT_EQ(sorted_elements[9], 5u);
+    EXPECT_EQ(sorted_elements[10], 6u);
+  }
+  // Finally, the non-clipped translucent items which came after the clip are
+  // drawn in their original order.
+  EXPECT_EQ(sorted_elements[11], 10u);
+  EXPECT_EQ(sorted_elements[12], 12u);
+}
+
+TEST(DrawOrderResolverTest, GetSortedDrawsRespectsSkipCounts) {
+  DrawOrderResolver resolver;
+
+  // These items will be skipped.
+  resolver.AddElement(0, false);
+  resolver.AddElement(1, true);
+  resolver.AddElement(2, false);
+  // These ones will be included in the final draw list.
+  resolver.AddElement(3, false);
+  resolver.AddElement(4, true);
+  resolver.AddElement(5, true);
+
+  // Form the draw list, skipping elements 0, 1, and 2.
+  // This emulates what happens when entitypass applies the clear color
+  // optimization.
+  auto sorted_elements = resolver.GetSortedDraws(1, 2);
+
+  EXPECT_EQ(sorted_elements.size(), 3u);
+  // First, opaque items are drawn in reverse order.
+  EXPECT_EQ(sorted_elements[0], 5u);
+  EXPECT_EQ(sorted_elements[1], 4u);
+  // Then, translucent items are drawn.
+  EXPECT_EQ(sorted_elements[2], 3u);
+}
+
+}  // namespace testing
+}  // namespace impeller