Skip to content

Latest commit

 

History

History
129 lines (80 loc) · 5.16 KB

README.md

File metadata and controls

129 lines (80 loc) · 5.16 KB

Certainly! Below is an example of documentation for the code you provided, explaining the functionality, usage, and structure.

2D Graphics Application with wgpu, winit, and vger

This Rust application demonstrates how to create a basic 2D graphics application using the wgpu library (for GPU rendering), the winit library (for window management and event handling), and the custom vger library (for high-level 2D graphics rendering). The application renders a simple red circle and some sample text to the window.

Features

  • Initializes a window with winit.
  • Sets up GPU rendering with wgpu and renders graphics with vger.
  • Supports window resizing and automatic content scaling.
  • Displays a red circle and some text on the screen.
  • Works in both native environments (e.g., Windows, macOS, Linux) and WebAssembly (WASM).

Modules and Dependencies

wgpu

wgpu is a safe, modern WebGPU implementation for Rust. It provides access to the GPU for graphics and compute tasks. In this application, wgpu is used to:

  • Create and configure the GPU device.
  • Manage the surface (the window) to which graphics will be rendered.
  • Submit rendering commands.

winit

winit is a cross-platform window creation and event handling library. It is used to:

  • Create a window for rendering.
  • Handle window events, such as resizing, close requests, and redraw requests.
  • Ensure cross-platform compatibility (including support for WebAssembly in browsers).

vger

vger is a custom high-level graphics library used for 2D drawing. It simplifies drawing shapes, text, and other graphics on the screen using wgpu. In this example, it is used to:

  • Draw shapes (e.g., circles).
  • Render text.
  • Provide a higher-level abstraction for GPU rendering.

Application Structure

DrawContext

The DrawContext structure holds the state necessary for rendering:

  • surface: The window surface that is rendered to.
  • device: The GPU device used to interact with the hardware.
  • config: The surface configuration, including window size, format, and other parameters.
  • vger: The Vger instance used to perform high-level 2D drawing.

setup (Async)

This function is responsible for setting up the rendering context. It performs the following tasks:

  • Initializes the wgpu instance and selects a GPU adapter.
  • Creates the surface (i.e., the window) for rendering.
  • Configures the GPU device and queue.
  • Sets up the vger library for rendering.

render

The render function is responsible for drawing content to the screen using vger. It performs the following tasks:

  • Saving and restoring drawing state.
  • Translates the drawing context.
  • Draws a red circle at the center of the window.
  • Renders sample text.

App

The App struct represents the application and holds the window and rendering context. It implements the ApplicationHandler trait from winit to manage window events and the application lifecycle.

  • window: An Option containing the window (if it exists).
  • context: An Option containing the DrawContext (if the context has been initialized).

ApplicationHandler Implementation

The App struct implements the ApplicationHandler trait, which provides methods for handling various events:

  • resumed: Initializes the window and rendering context when the application is resumed. This is where the setup function is called.
  • window_event: Handles window events, including:
    • CloseRequested: Exits the event loop when the user closes the window.
    • Resized: Updates the surface configuration when the window is resized, and triggers a redraw.
    • RedrawRequested: Handles the actual rendering. It updates the rendering context, clears the frame, and presents the rendered content to the screen.

Usage

Building and Running

To build and run the application, follow these steps:

  1. If you're targeting a native platform (Windows, macOS, Linux):

    • Build and run the project as a regular Rust application: 
      cargo run -p basic

  2. Once the application is running, a window will appear, and the red circle and text will be rendered to the screen. Resize the window, and the graphics will adjust accordingly.

Customization

  • Text Rendering: To render custom text, modify the string passed to the vger.text() function in the render function.
  • Shapes: Add more shapes (e.g., rectangles, lines) using the vger API to customize what is drawn to the screen.
  • Window Size: The window's size is automatically adjusted when resized by the user, and the application will reconfigure the GPU surface accordingly.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Notes

  • WebAssembly (WASM): When targeting WebAssembly, the canvas is directly added to the HTML body. This is handled by the winit library in the setup function under the #[cfg(target_arch = "wasm32")] section.
  • vger Library: The vger library is a higher-level abstraction built on top of wgpu, designed for easy drawing of 2D graphics. You can extend it to create more complex drawings.