Struct UiSystem 

pub struct UiSystem { /* private fields */ }

Main UI system managing tree, layout, rendering, and events.

This wraps UiCore and adds rendering capabilities.

Implementations

impl UiSystem

pub fn new(context: Arc<GraphicsContext>) -> Self

Create a new UI system with default configuration (no depth testing).

Warning: This creates a renderer without depth testing. If your render pass has a depth attachment, use from_window instead to ensure pipeline-renderpass compatibility.

Example

// For simple use without depth testing
let graphics = GraphicsContext::new_owned_sync().expect("Failed to create graphics context");
let ui = UiSystem::new(graphics);

pub fn from_window(context: Arc<GraphicsContext>, window: &RenderWindow) -> Self

Create a new UI system configured for a specific window.

This is the recommended constructor as it ensures the renderer’s pipelines are compatible with the window’s render pass configuration (surface format and depth format).

Example

let graphics = GraphicsContext::new_owned_sync().expect("Failed to create graphics context");

// Create window with depth buffer
let window = RenderWindowBuilder::new()
    .with_depth_default()
    .build(winit_window, graphics.clone())
    .expect("Failed to create window");

// UI automatically uses matching formats
let ui = UiSystem::from_window(graphics, &window);

pub fn with_descriptor( context: Arc<GraphicsContext>, descriptor: UiRendererDescriptor, ) -> Self

Create a new UI system with explicit configuration.

Use this when you need full control over the renderer configuration, or when the target is not a RenderWindow.

Example

let graphics = GraphicsContext::new_owned_sync().expect("Failed to create graphics context");

let desc = UiRendererDescriptor {
    name: "Game HUD".to_string(),
    surface_format: wgpu::TextureFormat::Bgra8UnormSrgb,
    depth_format: Some(wgpu::TextureFormat::Depth32Float),
};

let ui = UiSystem::with_descriptor(graphics, desc);

pub fn build<F>(&mut self, build_fn: F)

where F: FnOnce(&mut UiBuilder<'_>),

Build the UI tree using a declarative builder API.

Note: This does a full rebuild. For incremental updates, use update methods.

pub fn update(&mut self, delta_time: f32)

Update UI state (animations, hover, etc.).

Note: This no longer marks the entire tree dirty - only changed widgets are marked.

pub fn set_viewport(&mut self, viewport: Viewport)

Set the viewport size for layout calculations.

pub fn handle_events(&mut self, events: &mut EventBatch)

Handle events from the event batch.

pub fn compute_layout(&mut self)

Compute layout for all widgets.

pub fn get_node_id(&self, widget_id: WidgetId) -> Option<NodeId>

Get the node ID for a widget ID.

pub fn register_widget(&mut self, widget_id: WidgetId, node_id: NodeId)

Register a widget ID to node ID mapping.

pub fn update_text( &mut self, widget_id: WidgetId, new_content: impl Into<String>, ) -> bool

Update text content of a Text widget by ID with automatic dirty marking.

This is much faster than rebuilding the entire UI tree. Returns true if the content changed.

Example

let counter_id = WidgetId::new("counter");
ui.update_text(counter_id, "Count: 42");

pub fn text_cache_stats(&self) -> String

Get text cache statistics from the renderer.

pub fn text_cache_hit_rate(&self) -> f32

Get text cache hit rate.

pub fn log_text_cache_stats(&self)

Log text cache statistics.

pub fn update_button_label( &mut self, widget_id: WidgetId, new_label: impl Into<String>, ) -> bool

Update button label by ID with automatic dirty marking.

Returns true if the label changed.

pub fn update_text_input( &mut self, widget_id: WidgetId, new_value: impl Into<String>, ) -> bool

Update text input value by ID with automatic dirty marking.

Returns true if the value changed.

pub fn update_color(&mut self, widget_id: WidgetId, color: Color) -> bool

Update widget color by ID with automatic dirty marking.

Returns true if the color changed.

pub fn update_opacity(&mut self, widget_id: WidgetId, opacity: f32) -> bool

Update widget opacity by ID with automatic dirty marking.

pub fn update_translate(&mut self, widget_id: WidgetId, translate: Vec2) -> bool

Update widget visual translation by ID.

pub fn update_translate_x(&mut self, widget_id: WidgetId, x: f32) -> bool

Update widget visual X translation by ID.

pub fn update_translate_y(&mut self, widget_id: WidgetId, y: f32) -> bool

Update widget visual Y translation by ID.

pub fn update_scale(&mut self, widget_id: WidgetId, scale: Vec2) -> bool

Update widget visual scale by ID.

pub fn update_scale_x(&mut self, widget_id: WidgetId, x: f32) -> bool

Update widget visual X scale by ID.

pub fn update_scale_y(&mut self, widget_id: WidgetId, y: f32) -> bool

Update widget visual Y scale by ID.

pub fn set_visible(&mut self, widget_id: WidgetId, visible: bool) -> bool

Set widget visibility by ID.

pub fn toggle_visible(&mut self, widget_id: WidgetId) -> bool

Toggle widget visibility by ID.

pub fn render(&mut self, render_pass: &mut RenderPass<'_>)

Render the UI using retained mode instanced rendering.

This is the high-performance path that only updates dirty nodes and uses GPU instancing for efficient rendering.

Note: This automatically computes layout. If you need to control layout computation separately (e.g., for middleware freeze functionality), use compute_layout() + render_without_layout() instead.

pub fn render_without_layout( &mut self, render_pass: &mut RenderPass<'_>, clear_dirty_flags: bool, )

Render the UI without computing layout.

Use this when you want to manually control layout computation, for example when implementing layout freeze functionality with middleware.

Parameters

• render_pass: The WGPU render pass to render into
• clear_dirty_flags: Whether to clear dirty flags after rendering. Set to false when layout is frozen to preserve dirty state for inspection.

Typical usage:

// Check if middleware wants to freeze layout
let skip_layout = middlewares.pre_layout(&ctx);
if !skip_layout {
    ui.compute_layout();
}
// Don't clear flags when frozen so inspector can keep showing them
ui.render_without_layout(render_pass, !skip_layout);

pub fn core_mut(&mut self) -> &mut UiCore

Get mutable access to the core for advanced usage.

pub fn core(&self) -> &UiCore

Get reference to the core.

pub fn tree_mut(&mut self) -> &mut UiTree

Get mutable access to the tree for advanced usage.

pub fn tree(&self) -> &UiTree

Get reference to the tree.

pub fn event_system_mut(&mut self) -> &mut UiEventSystem

Get mutable access to the event system.

pub fn font_renderer(&self) -> &FontRenderer

Get reference to the font renderer.

pub fn set_theme(&mut self, theme: Theme)

Set the theme, marking all widget colors dirty.

pub fn theme(&self) -> &Theme

Get a reference to the current theme.

pub fn docking_style(&self) -> &DockingStyle

Get a reference to the docking style.

pub fn set_docking_style(&mut self, style: DockingStyle)

Replace the docking style.

pub fn add_plugin<P: UiPlugin>(&mut self, plugin: P) -> PluginHandle<P>

Add a plugin to the UI system and return a handle for typed access.

The plugin’s widget types are registered immediately.

Panics

Panics if a plugin of the same concrete type is already registered.

pub fn plugin_handle<P: UiPlugin>(&self) -> Option<PluginHandle<P>>

Get a handle for an already-registered plugin.

Returns Some(PluginHandle) if the plugin is registered, None otherwise. Useful for obtaining handles to auto-registered plugins.

pub fn plugin<P: UiPlugin>(&self, handle: &PluginHandle<P>) -> &P

Get a reference to a registered plugin by type, using a handle as proof.

pub fn plugin_mut<P: UiPlugin>(&mut self, handle: &PluginHandle<P>) -> &mut P

Get a mutable reference to a registered plugin by type, using a handle as proof.

pub fn plugin_manager(&self) -> &PluginManager

Get a reference to the plugin manager.

pub fn renderer_descriptor(&self) -> &UiRendererDescriptor

Get the current renderer configuration.

Returns the descriptor used to create the renderer, including surface format and depth format settings.

Example

let desc = ui.renderer_descriptor();
println!("Surface format: {:?}", desc.surface_format);

pub fn reconfigure(&mut self, descriptor: UiRendererDescriptor)

Reconfigure the renderer with new format settings.

Call this when the target surface format changes (e.g., window moved to a different monitor).

Example

// Window moved to different monitor - surface format may have changed
ui.reconfigure(UiRendererDescriptor::from_window(window));

pub fn reconfigure_from_window(&mut self, window: &RenderWindow)

Reconfigure from a window, inheriting its format configuration.

Convenience method for updating the renderer when a window’s surface format changes (e.g., when moved to a different monitor).

Example

// Handle surface format change after window moved
ui.reconfigure_from_window(window);