Renderling

What is renderling?

renderling is a GPU-driven renderer written in Rust. It is designed for high-performance graphics rendering, specifically targeting indie game developers and researchers.

Key Features:

• GPU-Driven: Leverages GPU capabilities for most rendering operations to handle complex scenes efficiently.
• GLTF Support: Optimized for working with GLTF files.
• Modern Rendering Techniques: Supports Forward+ rendering and Physically Based Shading (PBR) for advanced lighting and material effects.
• Scalability: Designed to handle large-scale scenes.

The Stage acts as a factory for scene resources. Most Stage::new_* functions return resources that follow the builder pattern. This allows you to chain configuration methods immediately after creation to customize the resource.

Example: Stage::new_camera(...).with_default_perspective().

Renderling supports three distinct lighting models depending on your scene requirements:

1. Unlit: No lighting is applied to the stage. This is useful for debugging or specific stylized effects.
2. Analytical lights: Specific, mathematically defined light sources created by the programmer. Supported types include:
   • directional
   • point
   • spot
3. Image based lighting (IBL): Lighting derived from 3D environment maps (e.g., HDR images) used in a skybox.

The Context is the entry point for any renderling program. It manages the underlying wgpu runtime, including the instance, adapter, and queue. It is also responsible for setting up the RenderTarget based on how the Context was initialized.

There are two primary ways to create a Context:

1. Headless Context: Renders to a texture. Use Context::headless or Context::try_new_headless (depending on your error handling preference).
2. Surface Context: Renders to a window (e.g., via winit) or a web canvas (via web-sys).

To render images, you must follow a lifecycle of acquiring and presenting frames:

1. Acquire a frame from the Context using Context::get_next_frame.
2. Present the frame using Frame::present.

Platform-specific behavior for Frame::present:

• Native: Presents the frame to the configured RenderTarget.
• WASM (Browser): Frame::present is a no-op. However, it is recommended to keep the call in your code to maintain cross-platform compatibility.

When you load a GLTF file into renderling, the engine automatically stages a collection of GPU resources including Camera, Vertices, Material, Primitive, and Transform.

Depending on your target platform, use one of the following methods on the Stage object:

• Desktop/Filesystem access: Use Stage::load_gltf_document_from_path to load from a file path.
• WASM/No filesystem: Use Stage::load_gltf_document_from_bytes to load from a byte buffer.

Both methods return a GltfDocument if successful. To optimize memory usage by unloading mesh geometry from the CPU after it has been uploaded to the GPU, call GltfDocument::into_gpu_only.

// Loading from a path
let gltf_document = stage.load_gltf_document_from_path("path/to/model.gltf")?;

// Unloading geometry from CPU to save memory
gltf_document.into_gpu_only();

Because renderling uses Rust-GPU for its shaders, you must patch the spirv-std crate in your Cargo.toml. This is a required workaround due to the current state of Rust-GPU releases. Add the following section to your Cargo.toml file:

[patch.crates-io]
spirv-std = { git = "https://github.com/rust-gpu/rust-gpu.git", rev = "05b34493ce661dccd6694cf58afc13e3c8f7a7e0" }

You can combine global image-based lighting (Ibl) with analytical lights (such as point lights) to create a rich lighting environment. This allows you to capture both the subtle nuances of ambient light from the environment map and the dramatic effects of direct illumination from specific light sources.

// Example pattern for mixing IBL and analytical lights:
// 1. Setup Stage
// 2. Add Ibl via stage.use_ibl(...)
// 3. Add analytical lights (e.g., PointLight)

The Stage is the central type in renderling, responsible for staging scene data on the GPU, linking effects, and performing the final render. You create a Stage using Context::new_stage.

Note that Context creation is asynchronous, which is one of the two exceptions to the otherwise synchronous renderling API (the other being reading data back from the GPU). You can set the background color of the stage using a Vec4 during or after creation.

// Stage creation via Context
let context = Context::new_stage(background_color).await;