/makepad-2.0-performance

name: makepad-2.0-performance
description: |
  CRITICAL: Use for Makepad 2.0 performance optimization and debugging. Triggers on:
  makepad performance, makepad debug, makepad profiling, makepad gc,
  new_batch, texture_caching, render optimization, draw batching,
  mod.gc, garbage collection, memory, debug logging, troubleshoot,
  ViewOptimize, PortalList, CachedView, render tree,
  invisible text, text disappears, UI freezes, scroll stuttering,
  性能, 调试, 优化, 垃圾回收, 渲染, 批处理, 日志

Makepad 2.0 Performance & Debugging Skill

1. Overview

Makepad 2.0 uses a unique rendering pipeline combined with the Splash script VM. Performance depends on understanding three critical subsystems:

1. **Draw Batching** - How Makepad groups GPU draw calls and why `new_batch: true` matters 2. **Garbage Collection** - The Splash VM's mark-sweep GC with per-type-bucket thresholds 3. **Render Triggers** - The `on_render` / `.render()` system that controls when sub-trees rebuild

Unlike traditional retained-mode UI frameworks, Makepad uses an immediate-mode-inspired draw pipeline where widgets emit draw commands into a sorted batch list. Understanding this pipeline is essential for diagnosing invisible text, flickering, and performance regressions.

---

2. Draw Batching System

How It Works

Makepad automatically batches consecutive draw calls that use the **same shader** into a single GPU draw call. This is a major performance optimization, but it has a critical side effect: draw order can be surprising.

Draw pipeline (simplified):

Widget tree:          GPU batches (default):

  View (bg shader)      Batch 1: all bg shaders
    Label (text)   -->  Batch 2: all text shaders
  View (bg shader)
    Label (text)        Result: ALL backgrounds draw first,
                                then ALL text draws second

When a View has `show_bg: true` AND contains text children, the text can end up **behind** the background because both text draws get batched together into a single draw call that executes before (or after) the background draw calls.

`new_batch: true`

Setting `new_batch: true` on a View forces Makepad to start a **new draw batch** at that point. This creates a `ViewOptimize::DrawList` internally, which ensures proper draw ordering within that View's subtree.

// PROBLEM: Label text is invisible - batched behind the background
RoundedView{
    width: Fill height: Fit
    draw_bg.color: #1e1e2e
    Label{text: "This text is INVISIBLE"}
}

// FIX: new_batch ensures background draws before text
RoundedView{
    width: Fill height: Fit
    new_batch: true
    draw_bg.color: #1e1e2e
    Label{text: "This text is VISIBLE"}
}

When `new_batch: true` Is Required

| Scenario | Required? | Why | |----------|-----------|-----| | View with `show_bg: true` containing Labels | YES | Text batches behind background | | View with hover animator + text children | YES | Hover bg covers text on activation | | Container of repeated items with backgrounds | YES | Each item and the container need it | | Transparent View (no `show_bg`) with Labels | NO | No background to overlap | | View with only non-text children (e.g., icons) | NO | Same shader type - no overlap issue | | Deeply nested Views each with backgrounds | YES on each | Each background layer needs its own batch |

Hover Effects and `new_batch`

This is the **number one mistake** with hoverable list items. When a View has `show_bg: true` with a hover animator that transitions from transparent (`#0000`) to opaque on hover, the text disappears on hover because the newly-opaque background covers the batched text.

// CORRECT: Hoverable item with new_batch
let HoverItem = View{
    width: Fill height: Fit
    new_batch: true
    show_bg: true
    draw_bg +: {
        color: uniform(#0000)
        color_hover: uniform(#fff2)
        hover: instance(0.0)
    }
    animator: Animator{
        hover: {
            default: {
                from: {all: Forward{duration: 0.1}}
                apply: {draw_bg: {hover: 0.0}}
            }
            on: {
                from: {all: Forward{duration: 0.1}}
                apply: {draw_bg: {hover: 1.0}}
            }
        }
    }
    label := Label{text: "item" draw_text.color: #fff}
}

// Parent container of hover items also needs new_batch
RoundedView{
    flow: Down height: Fit new_batch: true
    draw_bg.color: #2a2a3d
    draw_bg.border_radius: 8.0
    HoverItem{label.text: "First item"}
    HoverItem{label.text: "Second item"}
}

ViewOptimize Internals

The `new_batch` and `texture_caching` properties map to a `ViewOptimize` enum:

ViewOptimize::None      - Default. No special draw ordering.
ViewOptimize::DrawList  - Created by new_batch: true. Starts a new DrawList2d.
ViewOptimize::Texture   - Created by texture_caching: true. Renders to offscreen texture.

Priority: `texture_caching` takes precedence over `new_batch` if both are set.

---

3. Texture Caching

How It Works

Setting `texture_caching: true` on a View renders its entire child sub-tree to an offscreen GPU texture. On subsequent frames, if nothing in the sub-tree has changed, Makepad can skip re-rendering the children and just blit the cached texture.

// Cache a complex but rarely-changing sidebar
sidebar := View{
    width: 280 height: Fill
    texture_caching: true
    flow: Down spacing: 4
    // ... many child widgets ...
}

Pre-Built Cached Views

Makepad provides pre-styled cached views:

| Widget | Description | |--------|-------------| | `CachedView` | Texture-cached rectangle container | | `CachedRoundedView` | Texture-cached rounded rectangle |

When to Use Texture Caching

**Good candidates:**

• Complex static sidebars or toolbars that rarely change
• Large widget sub-trees with many nested backgrounds and text
• Decorative panels with shader effects

**Bad candidates:**

• Frequently updating views (e.g., animation targets, live data)
• Small simple views