feat(gpui): Add transform group support for pan/zoom camera views

[0xErwin1]

feat(gpui): Add transform group support for pan/zoom camera views

Pre-flight Checks

• I have searched existing issues and this is not a duplicate
• I understand this issue needs status:approved before a PR can be opened

Problem Description

Building interactive views that require a pan/zoom camera (e.g., entity-relationship diagrams, node graphs, canvas-based editors, schema visualizers) is not possible in GPUUI without resorting to manual coordinate transformation in canvas() paint callbacks.

Concrete use case: A database schema visualization tool that needs to:

1. Render a graph of ~50-100 nodes (each a div with text, icons, column lists)
2. Apply a uniform zoom (0.25x–4x) centered on the cursor
3. Pan the viewport by dragging
4. Maintain full interactivity on every node (hover, click, drag)
5. Support drag-to-reposition individual nodes within the transformed space

Current workaround and its limitations

The only workaround is to manually transform world coordinates to screen coordinates for each element:

// Inside a canvas() paint callback — the ONLY place in GPUUI where
// true camera transforms are possible
canvas()
    .paint(|bounds, window, cx| {
        for node in &self.nodes {
            let screen_pos = Point {
                x: node.world_x * self.zoom + self.pan_x,
                y: node.world_y * self.zoom + self.pan_y,
            };
            let screen_bounds = Bounds::new(screen_pos, screen_pos + node.size * self.zoom);
            window.paint_quad(Quad { bounds: screen_bounds, ... });
            window.paint_path(node.text_path(screen_bounds), ...);
        }
    })

Limitations of this workaround:

1. Content must be drawn with primitives (paint_quad, paint_path, paint_svg). Standard GPUUI elements like div, text, h_stack, v_stack cannot be used inside a canvas paint callback.
2. No composability: You cannot mix transformed canvas content with normal GPUUI elements in the same transformed space.
3. No hitbox transformation: Mouse hit-testing must also be manually transformed — window.layout_bounds() and element hitboxes remain in screen space.
4. Tedious: Every visual element requires manual coordinate transformation, defeating the purpose of GPUUI's layout system.

What exists but cannot be used

TransformationMatrix (in scene.rs) is a general 2D affine transform struct with translate, rotate, scale, and compose methods. However, it is only wired into two scene primitives: MonochromeSprite and SubpixelSprite (both used for SVG rendering). It is not available for:

• Quad (used by div)
• Path (used by SVG paths, canvas drawing)
• Shadow, Underline

Additionally, paint_layer only does clipping (push_layer/pop_layer on the scene's z-stack), not transformation.

The svg element has a with_transformation() API, but the documentation notes: "won't effect the hitbox or layout of the element, only the rendering".

Proposed Solution

Add a TransformGroup element that applies a TransformationMatrix to its entire subtree, affecting both rendering and hitboxes.

API Proposal

// Option A: Fluent API on div
div()
    .with_transform(|t| {
        t.scale(self.zoom)
         .translate(self.pan_x, self.pan_y)
    })
    .children(...)

// Option B: Explicit transform_group element
transform_group(zoom, pan, || {
    // All children are rendered with the transform active
    // Hitboxes are also correctly transformed
    div().children(...)
})

// Option C: canvas with transform wrapper (lower effort, limited use)
canvas()
    .transform(scale, translate)
    .paint(|bounds, window, cx| {
        // All paint_* calls inside here are automatically transformed
        // No manual coordinate math needed
        window.paint_quad(...); // coordinates in world space, not screen space
    })

Technical Approach (Option B / C hybrid)

The implementation would build on the existing infrastructure:

1. scene.rs: Add a transform_stack: Vec<TransformationMatrix> to Scene with push_transform() / pop_transform() methods. insert_primitive() applies the active transform to primitive bounds before submitting to the platform backend.

2. canvas element: Accept an optional TransformationMatrix in its paint() method. When set, push_transform/pop_transform wraps the user paint callback.

3. div element (full Option A): Requires changes to the Element trait's paint() signature to thread a TransformationMatrix through. This is the higher-effort path but enables full composability with existing GPUUI elements.

Affected Area

area:gpui — core GPUUI framework

Alternatives Considered

1. Doing nothing — external tools like DBFlux work around this with canvas + manual coordinate math, but cannot use standard GPUUI elements in transformed spaces.

2. CSS-style transform-only visual — Apply TransformationMatrix only at paint time (like current SVG with_transformation). Hitboxes remain in screen space. This solves rendering but breaks hover/click on transformed content.

3. Per-element .scale() and .translate() methods — Adding individual transform methods to each element is architecturally messier than a group-based approach.

Additional Context

What TransformationMatrix looks like today

// scene.rs
#[derive(Debug, Clone, Copy, PartialEq)]
#[repr(C)]
pub struct TransformationMatrix {
    pub rotation_scale: [[f32; 2]; 2],  // 2x2: rotation + scale
    pub translation: [f32; 2],          // 2D translation
}

impl TransformationMatrix {
    pub fn unit() -> Self { ... }
    pub fn translate(point: Point<f32>) -> Self { ... }
    pub fn rotate(angle: Radians) -> Self { ... }
    pub fn scale(size: Size<f32>) -> Self { ... }
    pub fn compose(other: Self) -> Self { ... }  // apply other first, then self
    pub fn apply(point: Point<f32>) -> Point<f32> { ... }
}

Already general-purpose, just not exposed beyond SVG sprite rendering.

Pipeline where this would fit

View::render()
  → Element::request_layout()   // Taffy computes layout in LOCAL space
  → Element::prepaint()         // Hitboxes in LOCAL space (needs transform here too!)
  → Element::paint()            // Primitives submitted to Scene
        → Scene::insert_primitive()  // ← Transform applied HERE currently for sprites
        → Platform Backend          // GPU draws transformed sprites

For a TransformGroup element, both prepaint (hitboxes) and paint (primitives) would need to apply the active transform.

---

I am willing to implement this. I have a detailed analysis of the required changes across scene.rs, window.rs, canvas.rs, and the Element trait, with estimates for both the minimal (canvas-only) and full (TransformGroup) approaches.

[MSIsunny]

I would be delighted to see this proposal implemented. In a recent program I developed using GPUI, I needed to create a complex chart supporting drag and zoom functionality, which I accomplished with Canvas by employing the manual calculation method you described.

Separately, I also had a requirement for vertical text layout. To achieve this, I had no alternative but to modify certain internal code within GPUI. In my view, implementing general-purpose component transformation would represent a crucial milestone for GPUI to evolve into a robust UI framework.

I believe many developers share similar needs, and I sincerely hope the GPUI team will take this proposal into consideration.

[bowenxuuu]

I want to develop an image viewer using GPUI, and translate, rotate, and scale are essential features for this application. However, GPUI does not support general-purpose component transformation, which has prevented me from starting development.
I sincerely hope that GPUI will implement general component transformation functionality.

[bowenxuuu]

@0xErwin1

I suggest adding an origin field to the TransformationMatrix struct.

pub struct TransformationMatrix {
    pub rotation_scale: [[f32; 2]; 2],  // 2x2: rotation + scale
    pub translation: [f32; 2],          // 2D translation
    pub origin: Point,        // This field represents a point with x and y coordinate. The origin to rotate and scale around. 
                              // Default to the center of the element.
}