metal-text-pipeline

license	Apache-2.0
name	metal-text-pipeline
description	Decide HOW LOW to go for a bare-metal 2D/text rendering pipeline on Apple GPUs, and pay the right costs. Covers the layered choice — pure objc2-metal + hand-written MSL (own command queue, glyph atlas, frame pacing) vs wgpu (Metal under the hood, cross-platform) vs Vello-on-wgpu (compute vector renderer you don't have to write) — plus CAMetalLayer/CADisplayLink frame pacing, ProMotion 120Hz, the glyph-atlas / signed-distance-field text problem, CPU-GPU sync, and honest cost accounting of "pure Metal" vs standing on Linebender. Activate on: "objc2-metal", "objc2", "CAMetalLayer", "CADisplayLink", "Metal command queue", "glyph atlas", "SDF text", "ProMotion frame pacing", "bare-metal Rust rendering on macOS", "pure Metal vs wgpu", "MTLDrawable". NOT for: writing the MSL shaders themselves (use metal-shader-expert), the Vello/Parley high-level API (use vello-parley-rendering), 3D engines (use wgpu/bevy), or iOS UIKit drawing.
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
metadata	{"category":"Frontend & UI","tags":["metal","objc2","objc2-metal","rust","gpu","text-rendering","glyph-atlas","frame-pacing","promotion","apple"],"pairs-with":[{"skill":"vello-parley-rendering","reason":"The high-level path this skill decides whether to drop below."},{"skill":"metal-shader-expert","reason":"When you do go bare-metal, this is who writes the MSL."},{"skill":"rust-app-distribution","reason":"Signing/notarizing the resulting macOS binary."}],"provenance":{"kind":"first-party","owners":["port-daddy"]},"authorship":{"maintainers":["port-daddy"]}}

The Metal Text / Render Pipeline (how low to go on Apple GPUs)

There are three rungs on the ladder for a custom 2D + text surface on macOS, and the expensive mistake is picking the wrong rung. This skill is the decision and the cost accounting — not the MSL itself (metal-shader-expert) and not the Vello API (vello-parley-rendering).

Rung 3 (lowest):  objc2 + objc2-metal, hand-written MSL.
                  You own: CAMetalLayer, command queue, render passes, a glyph
                  atlas (rasterize glyphs -> texture -> quads), AA, frame pacing.
Rung 2 (middle):  wgpu. Metal under the hood on macOS; portable. You still write
                  pipelines/shaders, but no Obj-C, no CAMetalLayer plumbing.
Rung 1 (highest): Vello on wgpu. The compute vector renderer + Parley text are
                  written FOR you. You build a Scene; the GPU does the rest.

The honest headline, measured on this repo's core/pd-timeline-proto (Apple M4 Max, Metal): a full timeline frame — beziers, dozens of markers, shaped text — costs ~0.5–2 ms of GPU build+submit, vsync-bound otherwise. That performance came from Rung 1. You do not need Rung 3 to hit 120fps ProMotion for a 2D operator UI. Rung 3 is justified only by specific constraints below.

When To Use (this decision skill)

• You're choosing between pure objc2-metal and a higher-level renderer for a Rust macOS app and want the costs spelled out before you commit.
• You already went bare-metal and need the frame-pacing / glyph-atlas / CPU-GPU sync patterns done right.
• Someone proposed "let's write it in pure Metal for performance" and you need to pressure-test that against the measured ceiling.

NOT For

• Writing the actual MSL vertex/fragment/compute shaders → metal-shader-expert.
• The Vello + Parley high-level API and its gotchas → vello-parley-rendering.
• 3D engines / scene graphs → wgpu directly, bevy.
• iOS UIKit/CoreGraphics 2D drawing, or SwiftUI Canvas → those are different stacks (swiftui-data-flow-expert, etc.).

Decision Points

1. Which rung?

Do you need a CUSTOM 2D vector + text surface on macOS in Rust?
├─ Yes, and you want it shipped this quarter
│   └─ Rung 1: Vello + Parley on wgpu.  (default — proven 120fps for 2D UI)
├─ Yes, AND you have a HARD reason to control the metal directly:
│   ├─ Need a specific Metal feature wgpu doesn't expose
│   │   (e.g. tile shaders / imageblocks, MTLHeap aliasing tricks,
│   │    raster order groups, custom MSL compute you must hand-tune)
│   ├─ Must share one MTLCommandQueue with existing Obj-C/Swift Metal code
│   ├─ Sub-100µs frame budgets where even wgpu's abstraction is measurable
│   └─ then → Rung 3: objc2 + objc2-metal, and bring metal-shader-expert
└─ You also want portability (Vulkan/DX12/GL) or 3D
    └─ Rung 2: wgpu directly.