LibWeb+WebContent: Move display list rasterization off the main thread

The display list is an immutable data structure, so once it's created,
rasterization can be moved to a separate thread. This allows more room
for performing other tasks between processing HTML rendering tasks.

This change makes PaintingSurface, ImmutableBitmap, and GlyphRun atomic
ref-counted, as they are shared between the main and rendering threads
by being included in the display list.

Libraries/LibGfx/ImmutableBitmap.h

@@ -1,14 +1,14 @@
 /*
- * Copyright (c) 2023-2024, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
+ * Copyright (c) 2023-2025, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
  *
  * SPDX-License-Identifier: BSD-2-Clause
  */
 
 #pragma once
 
+#include <AK/AtomicRefCounted.h>
 #include <AK/Forward.h>
 #include <AK/NonnullOwnPtr.h>
-#include <AK/RefCounted.h>
 #include <LibGfx/Bitmap.h>
 #include <LibGfx/ColorSpace.h>
 #include <LibGfx/Forward.h>
@@ -20,7 +20,7 @@ namespace Gfx {
 
 struct ImmutableBitmapImpl;
 
-class ImmutableBitmap final : public RefCounted<ImmutableBitmap> {
+class ImmutableBitmap final : public AtomicRefCounted<ImmutableBitmap> {
 public:
     static NonnullRefPtr<ImmutableBitmap> create(NonnullRefPtr<Bitmap> bitmap, ColorSpace color_space = {});
     static NonnullRefPtr<ImmutableBitmap> create(NonnullRefPtr<Bitmap> bitmap, AlphaType, ColorSpace color_space = {});

Libraries/LibGfx/PaintingSurface.h

@@ -1,14 +1,14 @@
 /*
- * Copyright (c) 2024, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
+ * Copyright (c) 2024-2025, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
  *
  * SPDX-License-Identifier: BSD-2-Clause
  */
 
 #pragma once
 
+#include <AK/AtomicRefCounted.h>
 #include <AK/Function.h>
 #include <AK/NonnullOwnPtr.h>
-#include <AK/RefCounted.h>
 #include <AK/RefPtr.h>
 #include <LibGfx/Color.h>
 #include <LibGfx/Size.h>
@@ -23,7 +23,7 @@ class SkSurface;
 
 namespace Gfx {
 
-class PaintingSurface : public RefCounted<PaintingSurface> {
+class PaintingSurface : public AtomicRefCounted<PaintingSurface> {
 public:
     enum class Origin {
         TopLeft,

Libraries/LibGfx/TextLayout.h

@@ -7,6 +7,7 @@
 
 #pragma once
 
+#include <AK/AtomicRefCounted.h>
 #include <AK/Forward.h>
 #include <AK/Utf8View.h>
 #include <AK/Vector.h>
@@ -33,7 +34,7 @@ typedef struct ShapeFeature {
 
 using ShapeFeatures = Vector<ShapeFeature, 4>;
 
-class GlyphRun : public RefCounted<GlyphRun> {
+class GlyphRun : public AtomicRefCounted<GlyphRun> {
 public:
     enum class TextType {
         Common,

Libraries/LibWeb/CMakeLists.txt

@@ -484,6 +484,7 @@ set(SOURCES
     HTML/PotentialCORSRequest.cpp
     HTML/PromiseRejectionEvent.cpp
     HTML/RadioNodeList.cpp
+    HTML/RenderingThread.cpp
     HTML/Scripting/Agent.cpp
     HTML/Scripting/ClassicScript.cpp
     HTML/Scripting/Environments.cpp
@@ -973,7 +974,7 @@ set(GENERATED_SOURCES
 
 serenity_lib(LibWeb web)
 
-target_link_libraries(LibWeb PRIVATE LibCore LibCompress LibCrypto LibJS LibHTTP LibGfx LibIPC LibRegex LibSyntax LibTextCodec LibUnicode LibMedia LibWasm LibXML LibIDL LibURL LibTLS LibRequests LibGC skia)
+target_link_libraries(LibWeb PRIVATE LibCore LibCompress LibCrypto LibJS LibHTTP LibGfx LibIPC LibRegex LibSyntax LibTextCodec LibUnicode LibMedia LibWasm LibXML LibIDL LibURL LibTLS LibRequests LibGC LibThreading skia)
 
 if (APPLE)
     target_link_libraries(LibWeb PRIVATE unofficial::angle::libEGL unofficial::angle::libGLESv2)

Libraries/LibWeb/HTML/RenderingThread.cpp

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <LibCore/EventLoop.h>
+#include <LibWeb/HTML/RenderingThread.h>
+
+namespace Web::HTML {
+
+RenderingThread::RenderingThread()
+    : m_main_thread_event_loop(Core::EventLoop::current())
+{
+}
+
+RenderingThread::~RenderingThread()
+{
+    m_exit = true;
+    m_rendering_task_ready_wake_condition.signal();
+    (void)m_thread->join();
+}
+
+void RenderingThread::start()
+{
+    VERIFY(m_skia_player);
+    m_thread = Threading::Thread::construct([this] {
+        rendering_thread_loop();
+        return static_cast<intptr_t>(0);
+    });
+    m_thread->start();
+}
+
+void RenderingThread::rendering_thread_loop()
+{
+    while (true) {
+        auto task = [this]() -> Optional<Task> {
+            Threading::MutexLocker const locker { m_rendering_task_mutex };
+            while (m_rendering_tasks.is_empty() && !m_exit) {
+                m_rendering_task_ready_wake_condition.wait();
+            }
+            if (m_exit)
+                return {};
+            return m_rendering_tasks.dequeue();
+        }();
+
+        if (!task.has_value()) {
+            VERIFY(m_exit);
+            break;
+        }
+
+        m_skia_player->set_surface(task->painting_surface);
+        m_skia_player->execute(*task->display_list);
+        m_main_thread_event_loop.deferred_invoke([callback = move(task->callback)] {
+            callback();
+        });
+    }
+}
+
+void RenderingThread::enqueue_rendering_task(RefPtr<Painting::DisplayList> display_list, NonnullRefPtr<Gfx::PaintingSurface> painting_surface, Function<void()>&& callback)
+{
+    Threading::MutexLocker const locker { m_rendering_task_mutex };
+    m_rendering_tasks.enqueue(Task { move(display_list), move(painting_surface), move(callback) });
+    m_rendering_task_ready_wake_condition.signal();
+}
+
+}

Libraries/LibWeb/HTML/RenderingThread.h

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025, Aliaksandr Kalenik <kalenik.aliaksandr@gmail.com>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/Noncopyable.h>
+#include <AK/Queue.h>
+#include <LibThreading/ConditionVariable.h>
+#include <LibThreading/Mutex.h>
+#include <LibThreading/Thread.h>
+#include <LibWeb/Painting/DisplayListPlayerSkia.h>
+
+namespace Web::HTML {
+
+class RenderingThread {
+    AK_MAKE_NONCOPYABLE(RenderingThread);
+    AK_MAKE_NONMOVABLE(RenderingThread);
+
+public:
+    RenderingThread();
+    ~RenderingThread();
+
+    void start();
+    void set_skia_player(OwnPtr<Painting::DisplayListPlayerSkia>&& player) { m_skia_player = move(player); }
+    void enqueue_rendering_task(RefPtr<Painting::DisplayList>, NonnullRefPtr<Gfx::PaintingSurface>, Function<void()>&& callback);
+
+private:
+    void rendering_thread_loop();
+
+    Core::EventLoop& m_main_thread_event_loop;
+
+    OwnPtr<Painting::DisplayListPlayerSkia> m_skia_player;
+
+    RefPtr<Threading::Thread> m_thread;
+    Atomic<bool> m_exit { false };
+
+    struct Task {
+        RefPtr<Painting::DisplayList> display_list;
+        NonnullRefPtr<Gfx::PaintingSurface> painting_surface;
+        Function<void()> callback;
+    };
+    // NOTE: Queue will only contain multiple items in case tasks were scheduled by screenshot requests.
+    //       Otherwise, it will contain only one item at a time.
+    Queue<Task> m_rendering_tasks;
+    Threading::Mutex m_rendering_task_mutex;
+    Threading::ConditionVariable m_rendering_task_ready_wake_condition { m_rendering_task_mutex };
+};
+
+}

Libraries/LibWeb/HTML/TraversableNavigable.cpp

@@ -53,12 +53,16 @@ TraversableNavigable::TraversableNavigable(GC::Ref<Page> page)
     , m_session_history_traversal_queue(vm().heap().allocate<SessionHistoryTraversalQueue>())
 {
     auto display_list_player_type = page->client().display_list_player_type();
+    OwnPtr<Painting::DisplayListPlayerSkia> skia_player;
     if (display_list_player_type == DisplayListPlayerType::SkiaGPUIfAvailable) {
         m_skia_backend_context = get_skia_backend_context();
-        m_skia_player = make<Painting::DisplayListPlayerSkia>(m_skia_backend_context);
+        skia_player = make<Painting::DisplayListPlayerSkia>(m_skia_backend_context);
     } else {
-        m_skia_player = make<Painting::DisplayListPlayerSkia>();
+        skia_player = make<Painting::DisplayListPlayerSkia>();
     }
+
+    m_rendering_thread.set_skia_player(move(skia_player));
+    m_rendering_thread.start();
 }
 
 TraversableNavigable::~TraversableNavigable() = default;
@@ -1429,13 +1433,13 @@ NonnullRefPtr<Gfx::PaintingSurface> TraversableNavigable::painting_surface_for_b
     return *new_surface;
 }
 
-void TraversableNavigable::paint(DevicePixelRect const& content_rect, Painting::BackingStore& target, PaintOptions paint_options)
+RefPtr<Painting::DisplayList> TraversableNavigable::record_display_list(DevicePixelRect const& content_rect, PaintOptions paint_options)
 {
     m_needs_repaint = false;
 
     auto document = active_document();
     if (!document)
-        return;
+        return {};
 
     for (auto& navigable : all_navigables()) {
         if (auto active_document = navigable->active_document(); active_document && active_document->paintable())
@@ -1447,13 +1451,12 @@ void TraversableNavigable::paint(DevicePixelRect const& content_rect, Painting::
     paint_config.should_show_line_box_borders = paint_options.should_show_line_box_borders;
     paint_config.has_focus = paint_options.has_focus;
     paint_config.canvas_fill_rect = Gfx::IntRect { {}, content_rect.size() };
-    auto display_list = document->record_display_list(paint_config);
-    if (!display_list)
-        return;
+    return document->record_display_list(paint_config);
+}
 
-    auto painting_surface = painting_surface_for_backing_store(target);
-    m_skia_player->set_surface(painting_surface);
-    m_skia_player->execute(*display_list);
+void TraversableNavigable::start_display_list_rendering(RefPtr<Painting::DisplayList> display_list, NonnullRefPtr<Gfx::PaintingSurface> painting_surface, Function<void()>&& callback)
+{
+    m_rendering_thread.enqueue_rendering_task(move(display_list), move(painting_surface), move(callback));
 }
 
 }

Libraries/LibWeb/HTML/TraversableNavigable.h

@@ -9,12 +9,12 @@
 #include <AK/Vector.h>
 #include <LibWeb/HTML/Navigable.h>
 #include <LibWeb/HTML/NavigationType.h>
+#include <LibWeb/HTML/RenderingThread.h>
 #include <LibWeb/HTML/SessionHistoryTraversalQueue.h>
 #include <LibWeb/HTML/VisibilityState.h>
 #include <LibWeb/Page/Page.h>
 #include <LibWeb/Painting/DisplayListPlayerSkia.h>
 #include <LibWeb/StorageAPI/StorageShed.h>
-#include <WebContent/BackingStoreManager.h>
 
 #ifdef AK_OS_MACOS
 #    include <LibGfx/MetalContext.h>
@@ -97,7 +97,8 @@ public:
 
     [[nodiscard]] GC::Ptr<DOM::Node> currently_focused_area();
 
-    void paint(Web::DevicePixelRect const&, Painting::BackingStore&, Web::PaintOptions);
+    RefPtr<Painting::DisplayList> record_display_list(DevicePixelRect const&, PaintOptions);
+    void start_display_list_rendering(RefPtr<Painting::DisplayList> display_list, NonnullRefPtr<Gfx::PaintingSurface> painting_surface, Function<void()>&& callback);
 
     enum class CheckIfUnloadingIsCanceledResult {
         CanceledByBeforeUnload,
@@ -116,6 +117,8 @@ public:
     bool needs_repaint() const { return m_needs_repaint; }
     void set_needs_repaint() { m_needs_repaint = true; }
 
+    NonnullRefPtr<Gfx::PaintingSurface> painting_surface_for_backing_store(Painting::BackingStore&);
+
 private:
     TraversableNavigable(GC::Ref<Page>);
 
@@ -137,8 +140,6 @@ private:
 
     [[nodiscard]] bool can_go_forward() const;
 
-    NonnullRefPtr<Gfx::PaintingSurface> painting_surface_for_backing_store(Painting::BackingStore&);
-
     // https://html.spec.whatwg.org/multipage/document-sequences.html#tn-current-session-history-step
     int m_current_session_history_step { 0 };
 
@@ -162,10 +163,11 @@ private:
     String m_window_handle;
 
     RefPtr<Gfx::SkiaBackendContext> m_skia_backend_context;
-    OwnPtr<Painting::DisplayListPlayerSkia> m_skia_player;
     HashMap<Gfx::Bitmap*, NonnullRefPtr<Gfx::PaintingSurface>> m_bitmap_to_surface;
 
     bool m_needs_repaint { true };
+
+    RenderingThread m_rendering_thread;
 };
 
 struct BrowsingContextAndDocument {

Libraries/LibWeb/Page/Page.h

@@ -324,7 +324,7 @@ public:
     virtual CSS::PreferredMotion preferred_motion() const = 0;
     virtual void paint_next_frame() = 0;
     virtual void process_screenshot_requests() = 0;
-    virtual void paint(DevicePixelRect const&, Painting::BackingStore&, PaintOptions = {}) = 0;
+    virtual void start_display_list_rendering(DevicePixelRect const&, Painting::BackingStore&, PaintOptions, Function<void()>&& callback) = 0;
     virtual Queue<QueuedInputEvent>& input_event_queue() = 0;
     virtual void report_finished_handling_input_event(u64 page_id, EventResult event_was_handled) = 0;
     virtual void page_did_change_title(ByteString const&) { }

Libraries/LibWeb/Painting/DisplayList.h

@@ -76,7 +76,7 @@ private:
     RefPtr<Gfx::PaintingSurface> m_surface;
 };
 
-class DisplayList : public RefCounted<DisplayList> {
+class DisplayList : public AtomicRefCounted<DisplayList> {
 public:
     static NonnullRefPtr<DisplayList> create()
     {

Libraries/LibWeb/SVG/SVGDecodedImageData.h

@@ -78,7 +78,7 @@ public:
     virtual void request_file(FileRequest) override { }
     virtual void paint_next_frame() override { }
     virtual void process_screenshot_requests() override { }
-    virtual void paint(DevicePixelRect const&, Painting::BackingStore&, Web::PaintOptions = {}) override { }
+    virtual void start_display_list_rendering(DevicePixelRect const&, Painting::BackingStore&, PaintOptions, Function<void()>&&) override { }
     virtual bool is_ready_to_paint() const override { return true; }
     virtual Queue<QueuedInputEvent>& input_event_queue() override { VERIFY_NOT_REACHED(); }
     virtual void report_finished_handling_input_event([[maybe_unused]] u64 page_id, [[maybe_unused]] EventResult event_was_handled) override { }

Libraries/LibWeb/WebDriver/Screenshot.cpp

@@ -57,7 +57,14 @@ ErrorOr<GC::Ref<HTML::HTMLCanvasElement>, WebDriver::Error> draw_bounding_box_fr
 
     auto bitmap = MUST(Gfx::Bitmap::create(Gfx::BitmapFormat::BGRA8888, Gfx::AlphaType::Premultiplied, canvas.surface()->size()));
     auto backing_store = Web::Painting::BitmapBackingStore(bitmap);
-    browsing_context.page().client().paint(paint_rect.to_type<Web::DevicePixels>(), backing_store);
+    IGNORE_USE_IN_ESCAPING_LAMBDA bool did_paint = false;
+    browsing_context.page().client().start_display_list_rendering(paint_rect.to_type<Web::DevicePixels>(), backing_store, {}, [&did_paint] {
+        did_paint = true;
+    });
+    HTML::main_thread_event_loop().spin_until(GC::create_function(HTML::main_thread_event_loop().heap(), [&] {
+        return did_paint;
+    }));
+
     canvas.surface()->write_from_bitmap(*bitmap);
 
     // 7. Return success with canvas.

Services/WebContent/PageClient.cpp

@@ -206,14 +206,16 @@ void PageClient::process_screenshot_requests()
             auto rect = page().enclosing_device_rect(dom_node->paintable_box()->absolute_border_box_rect());
             auto bitmap = Gfx::Bitmap::create(Gfx::BitmapFormat::BGRA8888, rect.size().to_type<int>()).release_value_but_fixme_should_propagate_errors();
             auto backing_store = Web::Painting::BitmapBackingStore(*bitmap);
-            paint(rect, backing_store, { .paint_overlay = Web::PaintOptions::PaintOverlay::No });
-            client().async_did_take_screenshot(m_id, bitmap->to_shareable_bitmap());
+            start_display_list_rendering(rect, backing_store, { .paint_overlay = Web::PaintOptions::PaintOverlay::No }, [this, bitmap] {
+                client().async_did_take_screenshot(m_id, bitmap->to_shareable_bitmap());
+            });
         } else {
             Web::DevicePixelRect rect { { 0, 0 }, content_size() };
             auto bitmap = Gfx::Bitmap::create(Gfx::BitmapFormat::BGRA8888, rect.size().to_type<int>()).release_value_but_fixme_should_propagate_errors();
             auto backing_store = Web::Painting::BitmapBackingStore(*bitmap);
-            paint(rect, backing_store);
-            client().async_did_take_screenshot(m_id, bitmap->to_shareable_bitmap());
+            start_display_list_rendering(rect, backing_store, {}, [this, bitmap] {
+                client().async_did_take_screenshot(m_id, bitmap->to_shareable_bitmap());
+            });
         }
     }
 }
@@ -224,20 +226,23 @@ void PageClient::paint_next_frame()
     if (!back_store)
         return;
 
-    auto viewport_rect = page().css_to_device_rect(page().top_level_traversable()->viewport_rect());
-    paint(viewport_rect, *back_store);
-
-    m_backing_store_manager.swap_back_and_front();
-
     m_paint_state = PaintState::WaitingForClient;
-    client().async_did_paint(m_id, viewport_rect.to_type<int>(), m_backing_store_manager.front_id());
+
+    auto viewport_rect = page().css_to_device_rect(page().top_level_traversable()->viewport_rect());
+    start_display_list_rendering(viewport_rect, *back_store, {}, [this, viewport_rect]() {
+        m_backing_store_manager.swap_back_and_front();
+        client().async_did_paint(m_id, viewport_rect.to_type<int>(), m_backing_store_manager.front_id());
+    });
 }
 
-void PageClient::paint(Web::DevicePixelRect const& content_rect, Web::Painting::BackingStore& target, Web::PaintOptions paint_options)
+void PageClient::start_display_list_rendering(Web::DevicePixelRect const& content_rect, Web::Painting::BackingStore& target, Web::PaintOptions paint_options, Function<void()>&& callback)
 {
     paint_options.should_show_line_box_borders = m_should_show_line_box_borders;
     paint_options.has_focus = m_has_focus;
-    page().top_level_traversable()->paint(content_rect, target, paint_options);
+    auto& traversable = *page().top_level_traversable();
+    auto display_list = traversable.record_display_list(content_rect, paint_options);
+    auto painting_surface = traversable.painting_surface_for_backing_store(target);
+    traversable.start_display_list_rendering(display_list, painting_surface, move(callback));
 }
 
 Queue<Web::QueuedInputEvent>& PageClient::input_event_queue()

Services/WebContent/PageClient.h

@@ -48,7 +48,7 @@ public:
 
     virtual void paint_next_frame() override;
     virtual void process_screenshot_requests() override;
-    virtual void paint(Web::DevicePixelRect const& content_rect, Web::Painting::BackingStore&, Web::PaintOptions = {}) override;
+    virtual void start_display_list_rendering(Web::DevicePixelRect const& content_rect, Web::Painting::BackingStore&, Web::PaintOptions, Function<void()>&& callback) override;
 
     virtual Queue<Web::QueuedInputEvent>& input_event_queue() override;
     virtual void report_finished_handling_input_event(u64 page_id, Web::EventResult event_was_handled) override;

Services/WebWorker/PageHost.cpp

@@ -77,7 +77,7 @@ Web::CSS::PreferredMotion PageHost::preferred_motion() const
     return Web::CSS::PreferredMotion::Auto;
 }
 
-void PageHost::paint(Web::DevicePixelRect const&, Web::Painting::BackingStore&, Web::PaintOptions)
+void PageHost::start_display_list_rendering(Web::DevicePixelRect const&, Web::Painting::BackingStore&, Web::PaintOptions, Function<void()>&&)
 {
 }
 

Services/WebWorker/PageHost.h

@@ -33,7 +33,7 @@ public:
     virtual Web::CSS::PreferredMotion preferred_motion() const override;
     virtual void paint_next_frame() override { }
     virtual void process_screenshot_requests() override { }
-    virtual void paint(Web::DevicePixelRect const&, Web::Painting::BackingStore&, Web::PaintOptions = {}) override;
+    virtual void start_display_list_rendering(Web::DevicePixelRect const&, Web::Painting::BackingStore&, Web::PaintOptions, Function<void()>&& callback) override;
     virtual void request_file(Web::FileRequest) override;
     virtual bool is_ready_to_paint() const override { return true; }
     virtual Web::DisplayListPlayerType display_list_player_type() const override { VERIFY_NOT_REACHED(); }