feat: 2d UI revamp (#223)

* feat: Add renderling-ui crate with SDF-based 2D/UI renderer

Introduces a dedicated lightweight 2D rendering pipeline separate from
the 3D PBR pipeline. Uses SlabAllocator for GPU memory management with
Hybrid<UiDrawCallDescriptor> wrapper types (UiRect, UiCircle, UiEllipse)
following the Camera pattern for live GPU updates via set_*/with_* methods.

- SDF-based shape rendering (rect, rounded rect, circle, ellipse)
- Gradient fills (linear, radial), borders, anti-aliased edges
- 3 GPU bindings and 32-byte vertices (vs 13 bindings / ~160 bytes for 3D)
- Instanced quads with per-pixel SDF evaluation in fragment shader
- 6 visual regression tests with baseline images

* feat: Add atlas-based image rendering and fix viewport slab ordering

Add UiImage element type with atlas texture support, enabling
texture/image rendering in the 2D UI pipeline. Fix critical bug
where Atlas::new() was allocated before UiViewport on the slab,
causing the shader (which reads viewport at offset 0) to read
garbage data and render blank white output.

- Add UiImage wrapper with set/with builders for position, size,
  tint, opacity, z-depth
- Replace dummy atlas with real Atlas integration (512x512x2)
- Add atlas_size field to UiViewport for correct UV mapping
- Fix shader to use viewport.atlas_size instead of viewport.size
  for AtlasTextureDescriptor::uv() calls
- Add AtlasImage, AtlasTexture, UiImage to public re-exports
- Recompile shaders with updated UiViewport layout
- Add 2 image rendering tests (checkerboard + tint)
- Regenerate baseline images with correct rendering
- 8 renderling-ui tests + 101 renderling tests pass

* feat: Add text rendering via glyph_brush to renderling-ui

Port text rendering from the old UI module to the new lightweight
2D pipeline. Glyph rasterization uses glyph_brush to produce a
Luma8 cache image, which is converted to RGBA (white + alpha) and
uploaded to the atlas. Each visible glyph gets its own
AtlasTextureDescriptor pointing to its sub-region in the cache,
and a UiDrawCallDescriptor with element_type TextGlyph. The
existing fragment shader samples glyph coverage from the atlas
alpha channel and multiplies by fill_color.

- Add GlyphCache wrapping GlyphBrush with Luma8 cache image
- Add UiText handle type with set_z/set_opacity methods
- Add add_font(), add_text(), remove_text() to UiRenderer
- Add image as optional dep behind 'text' feature
- Re-export FontArc, FontId, Section, Text, UiText
- Add 2 text tests (plain text + text overlaid on a rounded rect)
- 10 renderling-ui tests + 101 renderling tests pass, 0 clippy warnings

* feat: Add lyon-based vector path rendering to renderling-ui

Port path/vector rendering from the old UI module to the new
lightweight 2D pipeline. Uses lyon for tessellation (fill and
stroke), de-indexes the triangle mesh, and writes UiVertex arrays
to the slab. The existing vertex shader's Path branch reads
pre-tessellated vertices from the slab, and the fragment shader
passes through the interpolated vertex color.

- Add UiPathBuilder with lyon path commands (begin, line_to,
  quadratic/cubic bezier, add_rectangle, add_circle, etc.)
- Add fill() and stroke() methods for tessellation
- Add StrokeConfig (line width, cap, join) configuration
- Add UiPath handle type with z-depth and opacity setters
- Add path_builder() and remove_path() to UiRenderer
- Re-export StrokeConfig, UiPath, UiPathBuilder behind 'path' feature
- Add 3 path tests (filled triangle, stroked circle, mixed shapes)
- 13 renderling-ui tests + 101 renderling tests pass, 0 clippy warnings

* Remove old ui module from renderling, migrate example crate to renderling-ui

Delete the old renderling::ui module (cpu.rs, sdf.rs, text.rs, path.rs) and
its test baselines, remove the 'ui' feature flag and its optional deps
(glyph_brush, lyon, loading-bytes). Move loading-bytes to dev-dependencies
since it's still needed by wasm tests. Update the example crate to use
renderling-ui's UiRenderer, UiRect, UiText, and Section APIs instead of
the removed Ui type.

* Add image-filled paths, enable 4x MSAA by default, use typed slab Ids

Add UiPathBuilder::with_fill_image() for filling tessellated paths with
atlas textures. The shader samples the atlas when atlas_texture_id is set
on Path elements, using bounding-box-derived UVs. Add UiRenderer::upload_image()
to load images without creating a draw call.

Enable 4x MSAA by default (matching the old Ui behavior) and expose
with_msaa_sample_count() for configuration.

Replace raw u32 fields in UiDrawCallDescriptor with typed Ids:
atlas_texture_id becomes Id<AtlasTextureDescriptor> and
atlas_descriptor_id becomes Id<AtlasDescriptor>, using Id::NONE
as the unset sentinel. Update shader and CPU code accordingly.

* Add compositor for UI overlay, property getters for all element types

Add a Compositor to the renderling crate (compositor_vertex +
compositor_fragment shaders) that alpha-blends a source texture onto a
target framebuffer via a fullscreen quad. This fixes the black screen
when overlaying the UI renderer on a 3D stage with MSAA enabled: the UI
now renders to an intermediate texture, resolves MSAA there, and the
compositor blends it onto the final view preserving the scene beneath.

Add property getters to all UI element types (UiRect, UiCircle,
UiEllipse, UiImage, UiPath, UiText) so current values can be read back
— a prerequisite for the upcoming tweening/animation system.

Fix the example app's UI renderer clearing the 3D scene by removing the
erroneous .with_background_color(Vec4::ZERO) call, which was causing a
LoadOp::Clear that wiped the stage output.

* Fix alpha blending, entry points, and doc comments (PR review)

Address all 5 Copilot review comments from PR #223:

- Switch entire UI pipeline and compositor to premultiplied-alpha
  blending. The fragment shader now premultiplies RGB by final alpha
  before output, and both the UI pipeline and compositor use
  PREMULTIPLIED_ALPHA_BLENDING. This fixes edge darkening on borders
  and correct compositing of MSAA-resolved overlay textures.

- Fix border coverage in the fragment shader: compute straight-alpha
  weighted blend of border and fill colors, then premultiply at the
  end, avoiding the previous double-application of alpha at AA edges.

- Use explicit entry points (Some(linkage.entry_point)) in the UI
  render pipeline for consistency with the rest of the codebase.

- Update clip_rect doc to note it is reserved for future use (not
  currently enforced by the shader or renderer).

- Fix ui_vertex doc comment to only mention Path elements reading
  from the slab (TextGlyph uses the standard quad generation path).

Author: schell

.github/workflows/push.yaml

@@ -17,7 +17,7 @@ jobs:
   install-cargo-gpu:
     strategy:
       matrix: 
-        os: [ubuntu-latest, ubuntu-24.04, macos-latest]
+        os: [ubuntu-24.04, macos-latest]
     runs-on: ${{ matrix.os }}
     defaults:
       run: 
@@ -35,8 +35,10 @@ jobs:
         with:
           path: ~/.cargo
           # THIS KEY MUST MATCH BELOW
-          key: cargo-cache-${{ env.CARGO_GPU_COMMITSH }}-${{ matrix.os }}
+          key: cargo-cache-2-${{ env.CARGO_GPU_COMMITSH }}-${{ matrix.os }}
       - uses: moonrepo/setup-rust@v1
+        with:
+          cache: false
       - run: rustup default stable 
       - run: rustup update
       - run: | 
@@ -56,7 +58,7 @@ jobs:
       matrix: 
         # temporarily skip windows, revisit after a fix for this error is found:
         # https://github.com/rust-lang/cc-rs/issues/1331
-        os: [ubuntu-latest, ubuntu-24.04, macos-latest] #, windows-latest]
+        os: [ubuntu-24.04, macos-latest] #, windows-latest]
     runs-on: ${{ matrix.os }}
     defaults:
       run: 
@@ -65,22 +67,23 @@ jobs:
       RUST_LOG: debug
     steps:
       - uses: actions/checkout@v2
-      # Run moonrepo/setup-rust BEFORE restoring ~/.cargo cache, because
-      # moonrepo restores its own ~/.cargo cache which would overwrite
-      # the cargo-gpu binary installed by the install-cargo-gpu job.
+      # Disable moonrepo's built-in cache so it doesn't overwrite ~/.cargo
+      # (which contains the cargo-gpu binary from the install-cargo-gpu job).
       - uses: moonrepo/setup-rust@v1
+        with:
+          cache: false
       - uses: actions/cache@v4
         with:
           path: ~/.cargo
           # THIS KEY MUST MATCH ABOVE
-          key: cargo-cache-${{ env.CARGO_GPU_COMMITSH }}-${{ matrix.os }}
+          key: cargo-cache-2-${{ env.CARGO_GPU_COMMITSH }}-${{ matrix.os }}
       - uses: actions/cache@v4
         with:
           path: | 
               ${{ needs.install-cargo-gpu.outputs.cachepath-macOS }}
               ${{ needs.install-cargo-gpu.outputs.cachepath-Linux }}
               ${{ needs.install-cargo-gpu.outputs.cachepath-Windows }}
-          key: rust-gpu-cache-0-${{ matrix.os }}
+          key: rust-gpu-cache-1-${{ matrix.os }}
       - run: rustup install nightly
       - run: rustup component add --toolchain nightly rustfmt
       - run: cargo gpu show commitsh
@@ -99,7 +102,7 @@ jobs:
         with:
           path: ~/.cargo
           # THIS KEY MUST MATCH ABOVE
-          key: cargo-cache-${{ env.CARGO_GPU_COMMITSH }}-ubuntu-latest
+          key: renderling-fmt-${{ env.CARGO_GPU_COMMITSH }}-ubuntu-24.04
       - run: mkdir -p $HOME/.cargo/bin
       - uses: moonrepo/setup-rust@v1
       - run: rustup install nightly

Cargo.lock

@@ -7,6 +7,7 @@ members = [
     "crates/loading-bytes",
     "crates/renderling", 
     "crates/renderling-build",
+    "crates/renderling-ui",
     "crates/wire-types",
     # "crates/sandbox",
     "crates/xtask"

Cargo.toml

@@ -22,6 +22,7 @@ lazy_static = "1.4.0"
 loading-bytes = { path = "../loading-bytes" }
 log = { workspace = true }
 renderling = { path = "../renderling" }
+renderling-ui = { path = "../renderling-ui", features = ["text", "path"] }
 wasm-bindgen = { workspace = true }
 wasm-bindgen-futures = "^0.4"
 web-sys = { workspace = true, features = ["Performance", "Window"] }

crates/example/Cargo.toml

@@ -18,8 +18,8 @@ use renderling::{
     primitive::Primitive,
     skybox::Skybox,
     stage::Stage,
-    ui::{FontArc, Section, Text, Ui, UiPath, UiText},
 };
+use renderling_ui::{FontArc, Section, Text, UiRect, UiRenderer, UiText};
 
 pub mod camera;
 use camera::{
@@ -75,38 +75,45 @@ fn now() -> f64 {
 }
 
 struct AppUi {
-    ui: Ui,
+    ui: UiRenderer,
     fps_text: UiText,
     fps_counter: FPSCounter,
-    fps_background: UiPath,
+    fps_background: UiRect,
     last_fps_display: f64,
 }
 
 impl AppUi {
-    fn make_fps_widget(fps_counter: &FPSCounter, ui: &Ui) -> (UiText, UiPath) {
-        let translation = Vec2::new(2.0, 2.0);
+    fn make_fps_widget(fps_counter: &FPSCounter, ui: &mut UiRenderer) -> (UiText, UiRect) {
+        let offset = Vec2::new(2.0, 2.0);
         let text = format!("{}fps", fps_counter.current_fps_string());
-        let fps_text = ui
-            .text_builder()
-            .with_color(Vec3::ZERO.extend(1.0))
-            .with_section(Section::new().add_text(Text::new(&text).with_scale(32.0)))
-            .build();
-        fps_text.transform().set_translation(translation);
+        let fps_text = ui.add_text(
+            Section::default()
+                .add_text(
+                    Text::new(&text)
+                        .with_scale(32.0)
+                        .with_color([0.0, 0.0, 0.0, 1.0]),
+                )
+                .with_screen_position((offset.x, offset.y)),
+        );
+        let (min, max) = fps_text.bounds();
+        let size = max - min;
         let background = ui
-            .path_builder()
+            .add_rect()
+            .with_position(min)
+            .with_size(size)
             .with_fill_color(Vec4::ONE)
-            .with_rectangle(fps_text.bounds().0, fps_text.bounds().1)
-            .fill();
-        background.transform.set_translation(translation);
-        background.transform.set_z(-0.9);
+            .with_z(-0.9);
         (fps_text, background)
     }
 
     fn tick(&mut self) {
         self.fps_counter.next_frame();
         let now = now();
         if now - self.last_fps_display >= 1.0 {
-            let (fps_text, background) = Self::make_fps_widget(&self.fps_counter, &self.ui);
+            // Remove old text and background before recreating.
+            self.ui.remove_text(&self.fps_text);
+            self.ui.remove_rect(&self.fps_background);
+            let (fps_text, background) = Self::make_fps_widget(&self.fps_counter, &mut self.ui);
             self.fps_text = fps_text;
             self.fps_background = background;
             self.last_fps_display = now;
@@ -160,10 +167,10 @@ impl App {
             })
             .unwrap();
 
-        let ui = Ui::new(ctx).with_background_color(Vec4::ZERO);
+        let mut ui = UiRenderer::new(ctx);
         let _ = ui.add_font(FontArc::try_from_slice(FONT_BYTES).unwrap());
         let fps_counter = FPSCounter::default();
-        let (fps_text, fps_background) = AppUi::make_fps_widget(&fps_counter, &ui);
+        let (fps_text, fps_background) = AppUi::make_fps_widget(&fps_counter, &mut ui);
 
         Self {
             ui: AppUi {
@@ -199,7 +206,7 @@ impl App {
         self.ui.tick();
     }
 
-    pub fn render(&self, ctx: &Context) {
+    pub fn render(&mut self, ctx: &Context) {
         log::info!("render");
         let frame = ctx.get_next_frame().unwrap();
         self.stage.render(&frame.view());
@@ -223,6 +230,24 @@ impl App {
         self.stage.use_ibl(&ibl);
     }
 
+    fn set_model(&mut self, model: Model) {
+        match std::mem::replace(&mut self.model, model) {
+            Model::Gltf(gltf_document) => {
+                // Remove all the things that was loaded by the document
+                for prim in gltf_document.primitives.values().flatten() {
+                    self.stage.remove_primitive(prim);
+                }
+                for light in gltf_document.lights.iter() {
+                    self.stage.remove_light(light);
+                }
+            }
+            Model::Default(primitive) => {
+                self.stage.remove_primitive(&primitive);
+            }
+            Model::None => {}
+        }
+    }
+
     pub fn load_default_model(&mut self) {
         log::info!("loading default model");
         let mut min = Vec3::splat(f32::INFINITY);
@@ -249,7 +274,8 @@ impl App {
                 BoundingSphere::from((min, max))
             });
 
-        self.model = Model::Default(primitive);
+        self.set_model(Model::Default(primitive));
+
         self.camera_controller.reset(Aabb::new(min, max));
         self.camera_controller
             .update_camera(self.stage.get_size(), &self.camera);
@@ -260,7 +286,6 @@ impl App {
         self.camera_controller
             .reset(Aabb::new(Vec3::NEG_ONE, Vec3::ONE));
         self.stage.clear_images().unwrap();
-        self.model = Model::None;
         let doc = match self.stage.load_gltf_document_from_bytes(bytes) {
             Err(e) => {
                 log::error!("gltf loading error: {e}");
@@ -365,7 +390,7 @@ impl App {
         // dir.clone();     }
         // }
 
-        self.model = Model::Gltf(Box::new(doc));
+        self.set_model(Model::Gltf(Box::new(doc)));
     }
 
     pub fn tick_loads(&mut self) {

crates/example/src/lib.rs

@@ -0,0 +1,39 @@
+[package]
+name = "renderling-ui"
+version = "0.1.0"
+edition = "2021"
+description = "Lightweight 2D/UI renderer for renderling."
+repository = "https://github.com/schell/renderling"
+license = "MIT OR Apache-2.0"
+
+[features]
+default = ["text", "path"]
+text = ["dep:glyph_brush", "dep:image", "dep:loading-bytes"]
+path = ["dep:lyon"]
+test-utils = ["renderling/test-utils"]
+
+[dependencies]
+bytemuck = { workspace = true }
+craballoc = { workspace = true }
+crabslab = { workspace = true, features = ["default"] }
+glam = { workspace = true, features = ["std"] }
+glyph_brush = { workspace = true, optional = true }
+image = { workspace = true, optional = true }
+loading-bytes = { workspace = true, optional = true }
+log = { workspace = true }
+lyon = { workspace = true, optional = true }
+renderling = { path = "../renderling", default-features = false }
+rustc-hash = { workspace = true }
+snafu = { workspace = true }
+wgpu = { workspace = true, features = ["spirv"] }
+
+[dev-dependencies]
+env_logger = { workspace = true }
+futures-lite = { workspace = true }
+img-diff = { path = "../img-diff" }
+image = { workspace = true }
+renderling = { path = "../renderling", features = ["test-utils"] }
+renderling_build = { path = "../renderling-build" }
+
+[lints]
+workspace = true

crates/renderling-ui/Cargo.toml

@@ -0,0 +1,59 @@
+//! Lightweight 2D/UI renderer for renderling.
+//!
+//! This crate provides a dedicated 2D rendering pipeline that is separate
+//! from renderling's 3D PBR pipeline. It features:
+//!
+//! - SDF-based shape rendering (rectangles, rounded rectangles, circles,
+//!   ellipses) with anti-aliased edges
+//! - Gradient fills (linear and radial)
+//! - Texture/image rendering via the renderling atlas system
+//! - Text rendering via `glyph_brush` (behind the `text` feature)
+//! - Vector path rendering via `lyon` tessellation (behind the `path` feature)
+//! - A lightweight vertex format (32 bytes vs ~160 bytes for 3D)
+//! - Minimal GPU bindings (3 vs 13 for 3D)
+//!
+//! # Quick Start
+//!
+//! ```ignore
+//! use renderling::context::Context;
+//! use renderling_ui::UiRenderer;
+//!
+//! let ctx = futures_lite::future::block_on(Context::headless(800, 600));
+//! let mut ui = UiRenderer::new(&ctx);
+//!
+//! // Add a rounded rectangle
+//! let _rect = ui.add_rect()
+//!     .with_position(glam::Vec2::new(10.0, 10.0))
+//!     .with_size(glam::Vec2::new(200.0, 100.0))
+//!     .with_corner_radii(glam::Vec4::splat(8.0))
+//!     .with_fill_color(glam::Vec4::new(0.2, 0.3, 0.8, 1.0));
+//!
+//! let frame = ctx.get_next_frame().unwrap();
+//! ui.render(&frame.view());
+//! frame.present();
+//! ```
+
+mod renderer;
+#[cfg(test)]
+mod test;
+
+// Re-export key types from renderling that users will need.
+pub use renderling::{
+    atlas::{AtlasImage, AtlasTexture},
+    context::Context,
+    glam,
+    ui_slab::{
+        GradientDescriptor, GradientType, UiDrawCallDescriptor, UiElementType, UiVertex, UiViewport,
+    },
+};
+
+// Re-export our own types.
+pub use renderer::{UiCircle, UiEllipse, UiImage, UiRect, UiRenderer};
+
+// Re-export text types (behind "text" feature).
+#[cfg(feature = "text")]
+pub use renderer::{FontArc, FontId, Section, Text, UiText};
+
+// Re-export path types (behind "path" feature).
+#[cfg(feature = "path")]
+pub use renderer::{StrokeConfig, UiPath, UiPathBuilder};