Rugui

Description

rugui is a Rust library for building graphical user interfaces (GUIs) with a focus on real-time frame updates and high-performance rendering. Designed and optimized for applications requiring smooth and responsive interfaces, such as games and interactive simulations, rugui leverages modern GPU-accelerated rendering through the wgpu library.

By providing a flexible and efficient framework for creating dynamic and interactive UIs, rugui enables developers to build visually rich and high-performance applications with minimal overhead. Its declarative approach to UI development, coupled with support for advanced styling and responsive layouts, makes it ideal for applications where real-time updates and fluid interactions are critical.

Features

• GPU-Accelerated Rendering: Utilizes wgpu for efficient, hardware-accelerated rendering, providing smooth and high-performance graphics.
• Declarative UI: Supports a declarative approach to UI development, allowing developers to describe layouts and styles in a straightforward and intuitive manner.
• Flexible Styling: Offers extensive styling options, including colors, gradients, textures, and transformations, to create visually appealing and customizable interfaces.
• Responsive Layouts: Provides support for flexible and responsive layouts, including rows, columns, and custom arrangements, to adapt to different screen sizes and resolutions.
• Event Handling: Includes a robust event handling system for user interactions, such as mouse movements and clicks, allowing for interactive and dynamic UIs.
• Element Management: Allows easy addition, modification, and removal of UI elements, making it simple to build and update complex user interfaces.
• Dynamic Updates: Supports real-time updates to the UI, ensuring that changes are reflected immediately and efficiently.
• Integration with winit: Seamlessly integrates with the winit library for window management and event handling, streamlining the process of setting up and managing application windows.

With rugui, you can build sophisticated and performant GUIs for your Rust applications, taking advantage of modern GPU capabilities while keeping your codebase clean and maintainable.

Getting Started

Creating a rugui application involves several key steps, from initializing the GUI to adding and styling elements, handling events, and properly displaying frames. This guide will walk you through these steps, assuming you have already set up the necessary wgpu resources.

1. Initialize the Rugui GUI

Before you can initialize the Gui object, you'll need to have your wgpu setup ready, including a device, queue, and surface configuration. If you haven't set this up yet, you can refer to the wgpu guide for detailed instructions.

Once your wgpu setup is ready, you can initialize the Gui object as follows:

use rugui::Gui;

// Assume `device` and `queue` are already created, and you have the window size available
let mut gui: Gui<()> = Gui::new((window_width, window_height), &device, &queue);

2. Add and Style Elements

After initializing the Gui, you can add UI elements such as rows and columns and apply styles to them. Here's an example:

use rugui::{Element, Color, LinearGradient, ColorPoint, Position, Size};

let mut row1 = Element::new().with_label("Row 1");
row1.text_str("Hello, world!");
row1.styles.text_mut().color = Color::GREEN;

let mut column1 = Element::new().with_label("Column 1");
column1.styles.set_bg_lin_gradient(Some(LinearGradient {
    p1: ColorPoint {
        position: Position::Top,
        color: Color::RED.with_alpha(0.3),
    },
    p2: ColorPoint {
        position: Position::Center,
        color: Color::TRANSPARENT,
    },
}));

// Add more elements as needed...

3. Set an Entry Point

To display your UI, set an entry point for the Gui. This entry point defines the root of your GUI layout:`

let entry = gui.add_element(row1);
gui.set_entry(Some(entry));

4. Handle Resize Events

Handling window resizing is important for creating a responsive application. Here’s how you can handle resizing:

fn handle_resize(gui: &mut Gui<()>, new_size: (u32, u32)) {
    if new_size.0 > 0 && new_size.1 > 0 {
        gui.resize(new_size, &queue);
    }
}

// Use this in your event loop

5. Properly Display a Frame

To render the GUI correctly, you must update the GUI state, prepare it for rendering, and then draw it:

fn render_frame(gui: &mut Gui<()>) {
    // Update the GUI state
    gui.update();

    // Prepare the GUI for rendering
    gui.prepare(&device, &queue);

    // Assume the necessary `wgpu` resources like `output`, `view`, and `encoder` are set up
    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
        label: Some("Render Pass"),
        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
            view: &view,
            resolve_target: None,
            ops: wgpu::Operations {
                load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
                store: wgpu::StoreOp::Store,
            },
        })],
        depth_stencil_attachment: None,
    });

    gui.render(&mut pass);
    queue.submit(std::iter::once(encoder.finish()));
    output.present();
}

Running Examples

To get a hands-on understanding of how rugui works, you can explore the example files included in the repository. Two particularly useful examples are hello.rs and full.rs.

• hello.rs: A simple example that demonstrates the basic setup and a minimal UI.
• full.rs: A more comprehensive example that showcases the full capabilities of rugui, including complex layouts and event handling.

To run these examples, it's recommended to run them in release mode, as some of the calculations may not perform optimally in debug mode. Use the following command:

cargo run --release --example hello

Some examples may require additional features. For example, the full.rs example uses the winit feature, which can be enabled as follows:

cargo run --release --example full --features winit

Running in release mode ensures smoother performance, especially for more complex examples.

Troubleshooting

1. GUI Not Rendering Properly

• Ensure that your wgpu setup is correct and the device, queue, and surface configuration are properly initialized.
• Check if the Gui object has been correctly prepared and updated before rendering.

2. Resize Events Not Handled

• Verify that you are calling the handle_resize function correctly in your event loop and that the gui.resize method is being invoked with the updated window size.

3. Performance Issues

• Make sure you are running examples in release mode for optimal performance. Use cargo run --release to avoid debug mode overhead.
• Check for any unnecessary computations or excessive updates in your event handling and rendering code.

For more detailed troubleshooting, please refer to the rugui GitHub Issues page or the discussion forum.