### Complete Rendering Loop Example

Source: https://context7.com/schell/renderling/llms.txt

A full example demonstrating a typical rendering setup with models, lighting, and skybox. Initializes context, camera, loads GLTF, sets up skybox and IBL, adds lighting, renders, and saves the output.

```rust
use renderling::{
    camera::Camera,
    context::Context,
    glam::{Mat4, Vec3, Vec4},
    gltf::GltfDocument,
    light::Candela,
    pbr::ibl::Ibl,
    stage::Stage,
    types::GpuOnlyArray,
};

#[tokio::main]
async fn main() {
    // Initialize context and stage
    let ctx = Context::headless(512, 512).await;
    let stage: Stage = ctx
        .new_stage()
        .with_background_color(Vec4::new(0.1, 0.1, 0.1, 1.0));

    // Set up camera
    let _camera: Camera = stage
        .new_camera()
        .with_projection_and_view(
            Mat4::perspective_rh(std::f32::consts::PI / 4.0, 1.0, 0.1, 100.0),
            Mat4::look_at_rh(
                Vec3::new(2.0, 2.0, 2.0),
                Vec3::ZERO,
                Vec3::Y
            )
        );

    // Load GLTF model
    let _model: GltfDocument<GpuOnlyArray> = stage
        .load_gltf_document_from_path("model.glb")
        .unwrap()
        .into_gpu_only();

    // Add skybox and IBL
    let skybox = stage.new_skybox_from_path("environment.hdr").unwrap();
    stage.use_skybox(&skybox);
    let ibl = stage.new_ibl(&skybox);
    stage.use_ibl(&ibl);

    // Add accent lighting
    let _light = stage
        .new_point_light()
        .with_position(Vec3::new(1.0, 2.0, 1.0))
        .with_color(Vec4::ONE)
        .with_intensity(Candela(50.0));

    // Render and save
    let frame = ctx.get_next_frame().unwrap();
    stage.render(&frame.view());
    let img = frame.read_image().await.unwrap();
    img.save("rendered_scene.png").unwrap();
    frame.present();
}
```

--------------------------------

### Setup for Skybox Example

Source: https://github.com/schell/renderling/blob/main/manual/src/skybox.md

This code sets up the initial scene, likely loading a GLTF model, which serves as the base for adding a skybox. Ensure you have the necessary dependencies for GLTF loading.

```rust
use renderling::prelude::*;

fn main() {
    let mut app = App::new();

    app.add_plugins(DefaultPlugins)
        .add_systems(Startup, setup_scene)
        .add_systems(Update, rotate_camera);

    app.run();
}

fn setup_scene(mut commands: Commands, asset_server: Res<AssetServer>) {
    // camera
    commands.spawn(Camera3dBundle {
        transform: Transform::from_xyz(0.0, 0.0, 5.0),
        ..default()
    });

    // light
    commands.spawn(PointLightBundle {
        point_light: PointLight {
            intensity: 1500.0,
            shadows_enabled: true,
            ..default()
        },
        transform: Transform::from_xyz(4.0, 8.0, 4.0),
        ..default()
    });

    // load the scene
    commands.spawn(SceneBundle {
        scene: asset_server.load("models/scene.gltf#Scene0"),
        ..default()
    });
}

fn rotate_camera(mut query: Query<&mut Transform, With<Camera3d>>,
    time: Res<Time>,
) {
    for mut transform in query.iter_mut() {
        transform.rotate_y(time.delta_seconds() / 2.0);
    }
}
```

--------------------------------

### Setup Scene for Rendering

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting.md

This snippet shows the initial setup for a Renderling scene, including context creation, stage setup with lighting disabled, camera configuration, and loading a GLTF model. Use this for basic scene initialization before adding lighting.

```rust
let (mut ctx, mut stage) = (Context::new(), Stage::new());
let mut camera = Camera::new(&ctx);

stage.set_background_color(0x00000000);

// Disable lighting for unlit rendering
stage.with_lighting(false);

let bust = load_gltf(&ctx, "assets/scene.gltf").unwrap();
stage.add_object(bust);

let skybox = load_hdr_image(&ctx, "assets/skybox.hdr").unwrap();
stage.set_skybox(skybox);

ctx.render(&stage, &camera);
```

--------------------------------

### Initialize Image Based Lighting Setup

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/ibl.md

This snippet shows the initial setup for Image Based Lighting (IBL) in a scene. It assumes a prior skybox setup.

```rust
let mut ibl_setup = IblSetup::new();
let helipad = Skybox::from_file("helipad.basis").unwrap();
ibl_setup.set_skybox(helipad);
let ibl = Ibl::new(ibl_setup);
stage.add_global_light(ibl);
```

--------------------------------

### Setup Context, Stage, and Camera

Source: https://github.com/schell/renderling/blob/main/manual/src/gltf.md

Initializes the necessary components for rendering, including the Context, Stage, and Camera. This is a prerequisite for loading and displaying models.

```rust
use renderling::prelude::*;

let mut context = Context::new().unwrap();
let mut stage = Stage::new(&mut context);
let mut camera = Camera::new(&mut context, &stage.output_size); 
```

--------------------------------

### Build Renderling Project

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Use this command to build the renderling project. Ensure you have Rust and Cargo installed.

```bash
cargo build -p renderling
```

--------------------------------

### Install cargo-gpu

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Installs the cargo-gpu tool, which is necessary for working with shaders.

```bash
cargo install --git https://github.com/rust-gpu/cargo-gpu cargo-gpu
```

--------------------------------

### Create a Material Resource

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Stages a new material. This example creates a material that allows vertex colors to show through.

```rust
let material = stage.new_material(Material::default());
```

--------------------------------

### Windowed Application Setup with winit

Source: https://context7.com/schell/renderling/llms.txt

Create a native windowed application with interactive rendering using winit. Handles window creation, context initialization, resizing, and rendering requests.

```rust
use std::sync::Arc;
use renderling::{
    context::Context,
    glam::{Mat4, UVec2, Vec3, Vec4},
    stage::Stage,
};
use winit::{
    application::ApplicationHandler,
    event::WindowEvent,
    window::WindowAttributes,
};

struct App {
    ctx: Context,
    stage: Stage,
}

impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &winit::event_loop::ActiveEventLoop) {
        // Create window and context
        let window = Arc::new(event_loop.create_window(
            WindowAttributes::default()
                .with_title("Renderling App")
                .with_inner_size(winit::dpi::LogicalSize::new(800, 600))
        ).unwrap());

        self.ctx = futures_lite::future::block_on(
            Context::from_winit_window(None, window)
        );
        self.stage = self.ctx.new_stage();

        // Set up scene...
    }

    fn window_event(&mut self, event_loop: &_, _window_id: _, event: WindowEvent) {
        match event {
            WindowEvent::Resized(size) => {
                let size = UVec2::new(size.width, size.height);
                self.ctx.set_size(size);
                self.stage.set_size(size);
            }
            WindowEvent::RedrawRequested => {
                let frame = self.ctx.get_next_frame().unwrap();
                self.stage.render(&frame.view());
                frame.present();
            }
            WindowEvent::CloseRequested => event_loop.exit(),
            _ => {}
        }
    }
}
```

--------------------------------

### Install cargo-nextest

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Installs the cargo-nextest tool for enhanced testing capabilities.

```bash
cargo install cargo-nextest
```

--------------------------------

### Image-Based Lighting (IBL) Setup

Source: https://context7.com/schell/renderling/llms.txt

Sets up Image-Based Lighting (IBL) using an HDR environment map for realistic ambient lighting and reflections. Combines IBL with analytical lights for rendering.

```rust
use renderling::pbr::ibl::Ibl;

// First, create a skybox from an HDR image
let skybox = stage
    .new_skybox_from_path("helipad.hdr")
    .unwrap();
stage.use_skybox(&skybox);

// Create IBL from the skybox for realistic lighting
let ibl: Ibl = stage.new_ibl(&skybox);
stage.use_ibl(&ibl);

// IBL can be combined with analytical lights
let _point = stage
    .new_point_light()
    .with_position(Vec3::new(1.0, 2.0, 0.5))
    .with_color(css_srgb_color_to_linear(250, 198, 104))
    .with_intensity(Candela(100.0));

// Render with combined IBL and analytical lighting
let frame = ctx.get_next_frame().unwrap();
stage.render(&frame.view());
let img = frame.read_image().await.unwrap();
img.save("ibl_with_analytical.png").unwrap();
frame.present();
```

--------------------------------

### Acquire and Present a Frame

Source: https://github.com/schell/renderling/blob/main/manual/src/context.md

Shows how to get the next available frame from the Context and present it. On WASM, `Frame::present` is a no-op but should still be called for consistency.

```rust
let frame = context.get_next_frame().await;

// Render to the frame here

frame.present();
```

--------------------------------

### Get Committed GPU Size

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Use this snippet to check the number of bytes committed to the GPU through the stage. This is useful for understanding memory usage before and after operations.

```rust
let committed_size_bytes = stage.committed_size_bytes();
println!("Committed bytes: {}", committed_size_bytes);
```

--------------------------------

### Get Global Transform Descriptor

Source: https://context7.com/schell/renderling/llms.txt

Retrieve the world-space transformation matrix for a nested transform node. This is useful for debugging or when interacting with systems that require global coordinates.

```rust
// Get the global (world-space) transformation
let global_transform = grandchild_node.global_descriptor();
```

--------------------------------

### Build on WASM

Source: https://github.com/schell/renderling/blob/main/README.md

Compile the project for WebAssembly and serve it locally. This command uses `trunk` for building and `basic-http-server` for serving the compiled application.

```bash
RUSTFLAGS=--cfg=web_sys_unstable_apis trunk build crates/example-wasm/index.html && basic-http-server -a 127.0.0.1:8080 crates/example-wasm/dist
```

--------------------------------

### Create and Configure Renderling Stage

Source: https://context7.com/schell/renderling/llms.txt

Create a Stage to manage scene data on the GPU, including geometry, materials, and lights. Configure background color and enable features like lighting and bloom.

```rust
use renderling::{context::Context, glam::Vec4, stage::Stage};

let ctx = Context::headless(256, 256).await;

// Create a stage with configuration
let stage: Stage = ctx
    .new_stage()
    .with_background_color(Vec4::new(0.5, 0.5, 0.5, 1.0))
    .with_lighting(true)   // Enable lighting (default)
    .with_bloom(true);     // Enable bloom effect (default)

// Render the staged scene to a frame
let frame = ctx.get_next_frame().unwrap();
stage.render(&frame.view());
frame.present();

// Check GPU memory usage
let bytes_used = stage.used_gpu_buffer_byte_size();
println!("GPU memory used: {} bytes", bytes_used);
```

--------------------------------

### Create a Camera Resource

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Creates a new camera using the Stage. The first camera created is automatically used for rendering. Uses the builder pattern for configuration.

```rust
let camera = stage.new_camera(Camera::with_default_perspective());
```

--------------------------------

### Create and Use an Ibl Light

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/ibl.md

Demonstrates how to create an `Ibl` instance and add it to the stage for global illumination. This follows the builder pattern and uses a `use_*` function on the `Stage`.

```rust
let ibl = Ibl::new(IblSetup::from_file("helipad.basis").unwrap());
stage.add_global_light(ibl);
```

--------------------------------

### Create PBR Material with Texture

Source: https://context7.com/schell/renderling/llms.txt

Set up a physically based rendering (PBR) material using a texture. This involves loading an image, staging it, and then applying it to the material. Lighting must be enabled for PBR.

```rust
// Create a PBR material with textures
let texture_image = AtlasImage::from_path("texture.png").unwrap();
let entries = stage.set_images([texture_image]).unwrap();

let pbr_material = stage
    .new_material()
    .with_albedo_texture(&entries[0])
    .with_metallic_factor(0.0)
    .with_roughness_factor(0.5)
    .with_has_lighting(true);
```

--------------------------------

### Set Up Renderling Cameras

Source: https://context7.com/schell/renderling/llms.txt

Define cameras for scene viewing using perspective or orthographic projections. The first camera created is the default. You can switch cameras during rendering.

```rust
use renderling::{
    camera::Camera,
    glam::{Mat4, Vec3},
    stage::Stage,
};

// Create a camera with custom perspective projection
let camera: Camera = stage
    .new_camera()
    .with_projection_and_view(
        Mat4::perspective_rh(
            std::f32::consts::PI / 4.0,  // fovy: 45 degrees
            1.0,                          // aspect ratio
            0.1,                          // near plane
            100.0                         // far plane
        ),
        Mat4::look_at_rh(
            Vec3::new(0.5, 0.5, 0.8),     // eye position
            Vec3::new(0.0, 0.3, 0.0),     // look-at target
            Vec3::Y                        // up vector
        )
    );

// Or use a default perspective setup
let camera = stage
    .new_camera()
    .with_default_perspective(width, height);

// Or use orthographic projection for 2D rendering
let camera = stage
    .new_camera()
    .with_default_ortho2d(100.0, 100.0);

// Switch to a different camera during rendering
stage.use_camera(&camera);
```

--------------------------------

### Create Renderling Context

Source: https://context7.com/schell/renderling/llms.txt

Initialize a headless context for off-screen rendering or a surface context for native windows/canvases. The context manages the wgpu runtime. Use `.await` for context creation.

```rust
use renderling::context::Context;

// Create a headless context for off-screen rendering (async)
let ctx = Context::headless(512, 512).await;

// Or create from a winit window for native applications
use std::sync::Arc;
use winit::window::Window;
let window: Arc<Window> = /* ... */;
let ctx = Context::from_winit_window(None, window).await;

// Get the next frame for rendering
let frame = ctx.get_next_frame().unwrap();

// After rendering, capture the frame as an image
let image = frame.read_image().await.unwrap();
image.save("output.png").unwrap();

// Present the frame to display
frame.present();
```

--------------------------------

### Create a Renderling Stage

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Creates a new Stage with an optional background color. Context creation is asynchronous.

```rust
let stage = context.new_stage(Some(Vec4::new(0.1, 0.1, 0.1, 1.0)))
    .await
    .expect("Failed to create stage");
```

--------------------------------

### Create Renderling Context

Source: https://github.com/schell/renderling/blob/main/manual/src/context.md

Demonstrates the creation of a renderling Context. Use `headless` for rendering to a texture or a surface context for window/canvas integration.

```rust
let context = Context::headless(100, 100).await;
let frame = context.get_next_frame().await;

// Use frame here

frame.present();
```

--------------------------------

### Create a Spot Light in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Emit a cone of light from a point with a specified direction and angle. Useful for highlighting specific areas. Requires position, direction, and cutoff values.

```rust
stage.add_light(renderling::Light::Spot { position: camera.position(), direction: camera.direction(), color: vec3(1.0, 1.0, 1.0), inner_cutoff: PI / 4.0, outer_cutoff: PI / 3.0 });
```

--------------------------------

### Create Spot Light

Source: https://context7.com/schell/renderling/llms.txt

Creates a spotlight emitting a cone of light from a position in a direction, with configurable inner and outer cone angles. Supports removal.

```rust
use renderling::
    glam::Vec3,
    light::{AnalyticalLight, Candela, SpotLight},
};

// Create a spotlight pointing at a target
let camera_eye = Vec3::new(0.5, 0.5, 0.8);
let camera_target = Vec3::new(0.0, 0.3, 0.0);

let spot: AnalyticalLight<SpotLight> = stage
    .new_spot_light()
    .with_position(camera_eye)
    .with_direction(camera_target - camera_eye)  // Direction to target
    .with_inner_cutoff(0.15)   // Inner cone angle (radians, full intensity)
    .with_outer_cutoff(0.2)    // Outer cone angle (radians, falloff)
    .with_color(css_srgb_color_to_linear(250, 198, 104))
    .with_intensity(Candela(12_000.0));

stage.remove_light(&spot);
```

--------------------------------

### Lint Project with Clippy

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Run Clippy to check for lints and potential code style issues.

```bash
cargo clippy
```

--------------------------------

### Mix Image Based Lighting with Analytical Lights

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/ibl.md

Shows how to combine global image-based lighting with a traditional analytical light, such as a point light, for richer scene illumination.

```rust
let ibl = Ibl::new(IblSetup::from_file("helipad.basis").unwrap());
let point_light = PointLight::new(Vec3::new(0.0, 1.0, 0.0), 1.0, Color::WHITE);
stage.add_global_light(ibl);
stage.add_light(point_light);
```

--------------------------------

### Compile and Generate Shaders

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Commands for compiling shaders and generating WGSL code.

```bash
cargo shaders
```

```bash
cargo linkage
```

--------------------------------

### Create a Point Light in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Emit light equally in all directions from a single point, simulating a light bulb. Intensity diminishes with distance.

```rust
stage.add_light(renderling::Light::Point { position: vec3(0.0, 1.0, 0.0), color: vec3(1.0, 1.0, 1.0), radius: 10.0 });
```

--------------------------------

### Enable Lighting in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Turn on lighting for the stage to render scene elements with light. This is a prerequisite for any lighting effects.

```rust
stage.set_lighting_on(true);
```

--------------------------------

### Create and Use Skybox

Source: https://context7.com/schell/renderling/llms.txt

Creates a skybox from an HDR environment map and activates it for rendering. Renders the scene with the skybox background and saves the output.

```rust
use renderling::skybox::Skybox;

// Load a skybox from an HDR image file
let skybox = stage
    .new_skybox_from_path("environment.hdr")
    .unwrap();

// Activate the skybox for rendering
stage.use_skybox(&skybox);

// Render the scene with the skybox background
let frame = ctx.get_next_frame().unwrap();
stage.render(&frame.view());
let image = frame.read_image().await.unwrap();
image.save("scene_with_skybox.png").unwrap();
frame.present();
```

--------------------------------

### Generate WGPU Linkage

Source: https://github.com/schell/renderling/blob/main/README.md

Explicitly re-generate the wgpu linkage for shaders. While typically handled by the build.rs script, this command can be run manually if needed.

```bash
cargo linkage
```

--------------------------------

### Create Colored Triangle Vertices

Source: https://context7.com/schell/renderling/llms.txt

Define vertices with position and color for a simple triangle. Ensure the `stage` object is initialized before creating vertices.

```rust
use renderling::{
    geometry::{Vertex, Vertices},
    glam::{Vec3, Vec4},
    types::GpuOnlyArray,
};

// Create vertices for a colored triangle
let vertices: Vertices = stage.new_vertices([
    Vertex::default()
        .with_position([0.0, 0.0, 0.0])
        .with_color([0.0, 1.0, 1.0, 1.0]),  // Cyan
    Vertex::default()
        .with_position([0.0, 100.0, 0.0])
        .with_color([1.0, 1.0, 0.0, 1.0]),  // Yellow
    Vertex::default()
        .with_position([100.0, 0.0, 0.0])
        .with_color([1.0, 0.0, 1.0, 1.0]),  // Magenta
]);
```

--------------------------------

### Create Primitive with Material and Transform

Source: https://context7.com/schell/renderling/llms.txt

Assemble a primitive with specified vertices, a material, and a transformation matrix. This defines the object's appearance, position, rotation, and scale.

```rust
// Create a primitive with material and transform
let cube = stage
    .new_primitive()
    .with_vertices(&cube_vertices)
    .with_material(&material)
    .with_transform(
        stage
            .new_transform()
            .with_translation(Vec3::new(0.0, 1.0, 0.0))
            .with_rotation(Quat::from_axis_angle(Vec3::Y, std::f32::consts::FRAC_PI_4))
            .with_scale(Vec3::splat(2.0))
    );
```

--------------------------------

### Load GLTF Model from Path

Source: https://context7.com/schell/renderling/llms.txt

Loads a GLTF model from a file path and unloads CPU memory. Retrieves the model's bounding volume for camera positioning.

```rust
use renderling::
    gltf::GltfDocument,
    types::GpuOnlyArray,
};

// Load a GLTF file from disk
let model: GltfDocument<GpuOnlyArray> = stage
    .load_gltf_document_from_path("model.glb")
    .unwrap()
    .into_gpu_only();  // Unload CPU memory

// Get the model's bounding volume for camera positioning
if let Some(bounds) = model.bounding_volume() {
    println!("Model bounds: min={:?}, max={:?}", bounds.min, bounds.max);
}
```

--------------------------------

### Format Code

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Always format your code using the nightly version of Cargo fmt.

```bash
cargo +nightly fmt
```

--------------------------------

### Create a Primitive Resource

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Creates a primitive by combining vertices and a material using the builder pattern.

```rust
let primitive = stage.new_primitive(vertices, material);
```

--------------------------------

### Create Point Light

Source: https://context7.com/schell/renderling/llms.txt

Creates a point light emitting light equally in all directions from a specific position. Intensity diminishes with distance. Supports removal when not needed.

```rust
use renderling::
    glam::{Vec3, Vec4},
    light::{AnalyticalLight, Candela, PointLight},
};

// Create a point light at a specific position
let point: AnalyticalLight<PointLight> = stage
    .new_point_light()
    .with_position(Vec3::new(2.0, 3.0, 1.0))
    .with_color(Vec4::new(1.0, 0.9, 0.8, 1.0))  // Warm white
    .with_intensity(Candela(100.0));  // 100 candela (~100W bulb)

// Candela reference values:
// - Candela(12.0): small candle
// - Candela(100.0): ~100W incandescent bulb
// - Candela(1000.0): bright LED spotlight

// Remove the light
stage.remove_light(&point);
```

--------------------------------

### Run Standard Tests

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Executes all tests using the standard cargo test runner.

```bash
cargo test
```

--------------------------------

### Run All Tests

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Execute all tests in the project using Cargo Nextest for parallel execution or standard Cargo test.

```bash
cargo nextest run -j 1
```

```bash
cargo test
```

--------------------------------

### Create Primitive with Vertices

Source: https://context7.com/schell/renderling/llms.txt

Construct a renderable primitive using a set of vertices. The `stage` object is needed to create new primitives, and the `vertices` must be pre-defined.

```rust
use renderling::{
    geometry::Vertices,
    glam::{Quat, Vec3},
    primitive::Primitive,
};

// Create a simple primitive with vertices
let triangle = stage
    .new_primitive()
    .with_vertices(vertices);
```

--------------------------------

### Compile and Link Shaders

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Compiles and links shaders, a necessary step when modifying shader code.

```bash
cargo shaders && cargo linkage
```

--------------------------------

### Load GLTF Document from Path

Source: https://github.com/schell/renderling/blob/main/manual/src/gltf.md

Loads a GLTF file from a specified file path using Stage::load_gltf_document_from_path. This method returns a GltfDocument upon successful parsing and resource staging. Consider using `into_gpu_only` to unload mesh geometry from the CPU.

```rust
let gltf_document = stage.load_gltf_document_from_path("path/to/your/model.gltf").unwrap();
let gltf_document = gltf_document.into_gpu_only();
```

--------------------------------

### Render Scene with Lighting Enabled

Source: https://github.com/schell/renderling/blob/main/manual/src/gltf.md

Renders the current scene with lighting enabled. This is a standard rendering step after setting up the scene and loading models.

```rust
stage.render(&mut context, &mut camera);
```

--------------------------------

### Create a Directional Light in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Simulate light from a specific direction, affecting all scene objects equally. Ideal for large-scale lighting like sunlight.

```rust
stage.add_light(renderling::Light::Directional { direction: vec3(1.0, -1.0, -1.0), color: vec3(1.0, 1.0, 1.0) });
```

--------------------------------

### Khronos Sample Viewer PBR Fragment Shader

Source: https://github.com/schell/renderling/blob/main/NOTES.md

Fragment shader code for PBR rendering used in the Khronos Sample Viewer. This is a reference implementation for PBR.

```glsl
// Fragment shader code for PBR rendering
// (Content not provided in the source text, only link)
```

--------------------------------

### Run Single Test

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

To run a specific test, provide its name to Cargo Nextest or Cargo test.

```bash
cargo test <test_name>
```

```bash
cargo nextest run <test_name>
```

--------------------------------

### Run Tests with cargo-nextest

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Executes all tests using cargo-nextest, utilizing multiple threads for faster execution.

```bash
cargo nextest run -j 1
```

--------------------------------

### Khronos Sample Viewer PBR Vertex Shader

Source: https://github.com/schell/renderling/blob/main/NOTES.md

Vertex shader code for PBR rendering used in the Khronos Sample Viewer. This is a reference implementation for PBR.

```glsl
// Vertex shader code for PBR rendering
// (Content not provided in the source text, only link)
```

--------------------------------

### Create Cube Vertices with Normals and UVs

Source: https://context7.com/schell/renderling/llms.txt

Generate vertices for a unit cube, including position, normal, and UV coordinates. This is useful for textured or lit surfaces. The `stage` object must be available.

```rust
// Create vertices with positions, normals, and UV coordinates
let cube_vertices: Vertices = stage.new_vertices(
    renderling::math::unit_cube()
        .into_iter()
        .map(|(position, normal)| {
            Vertex::default()
                .with_position(position)
                .with_normal(normal)
                .with_uv0([0.0, 0.0])
        })
);
```

--------------------------------

### Rust-GPU Cargo.toml Configuration

Source: https://github.com/schell/renderling/blob/main/NOTES.md

This configuration is problematic for library-only shader crates in rust-gpu, leading to 'Undefined symbols' errors. Ensure your shader crate has entry points if using these types.

```toml
crate-type = ["rlib", "dylib"]
```

--------------------------------

### Fix wgpu Vulkan Backend Selection on macOS

Source: https://github.com/schell/renderling/blob/main/NOTES.md

Fixes for wgpu's Vulkan backend selection on macOS. These relate to specific GitHub Pull Requests.

```shell
# https://github.com/gfx-rs/wgpu/pull/3958
```

```shell
# https://github.com/gfx-rs/wgpu/pull/3962
```

--------------------------------

### Build Shaders

Source: https://github.com/schell/renderling/blob/main/README.md

Regenerate shader files for the project. This command is used when shader code needs to be updated or recompiled.

```bash
cargo shaders
```

--------------------------------

### Create Directional Light

Source: https://context7.com/schell/renderling/llms.txt

Creates a directional light simulating sunlight with specified direction, color, and intensity. The light can be removed when no longer needed.

```rust
use renderling::
    color::css_srgb_color_to_linear,
    glam::Vec3,
    light::{AnalyticalLight, DirectionalLight, Lux},
};

// Create a directional light (like sunlight)
let sunlight_color = css_srgb_color_to_linear(250, 198, 104);  // Warm amber

let directional: AnalyticalLight<DirectionalLight> = stage
    .new_directional_light()
    .with_direction(Vec3::new(-0.5, -0.5, 0.0))  // Direction light points
    .with_color(sunlight_color)
    .with_intensity(Lux::OUTDOOR_OVERCAST_HIGH);  // ~10,000 lux

// Lux constants for realistic lighting:
// - Lux::OUTDOOR_DIRECT_SUNLIGHT_HIGH: ~100,000 lux
// - Lux::OUTDOOR_FULL_DAYLIGHT_LOW: ~10,000 lux
// - Lux::OUTDOOR_OVERCAST_HIGH: ~10,000 lux
// - Lux::OUTDOOR_FOXS_WEDDING: ~1,000 lux

// Remove the light when no longer needed
stage.remove_light(&directional);
```

--------------------------------

### Render the Scene

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Renders the staged scene into a frame, including reading the frame data back from the GPU.

```rust
let frame = stage.render().await.expect("Failed to render frame");
let image = frame.read_image().await.expect("Failed to read image");
```

--------------------------------

### Stage Unit Cube Vertices

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Stages the vertices for a unit cube on the GPU using a convenience function from the renderling::math module.

```rust
let vertices = stage.new_vertices(unit_cube_vertices());
```

--------------------------------

### Create Unlit Material with Solid Color

Source: https://context7.com/schell/renderling/llms.txt

Define a material that does not use lighting and has a single solid color. The `stage` object is required to create new materials.

```rust
use renderling::{
    atlas::AtlasImage,
    glam::Vec4,
    material::Material,
};

// Create an unlit material with a solid color
let material = stage
    .new_material()
    .with_albedo_factor(Vec4::new(1.0, 0.0, 0.0, 1.0))  // Red
    .with_has_lighting(false);
```

--------------------------------

### Remove Primitive and Render

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

This snippet demonstrates how to remove a primitive from the stage using `Stage::remove_primitive`, drop other resources, and then re-render. This is the standard procedure for completely removing a primitive.

```rust
// Remove the cube primitive
stage.remove_primitive(cube_primitive);

// Drop other resources
// ...

// Render again
renderer.render(&stage, &mut frame);
println!("Committed bytes: {}", stage.committed_size_bytes());
```

--------------------------------

### Add Renderling Dependency

Source: https://github.com/schell/renderling/blob/main/manual/src/setup.md

Add Renderling as a dependency to your Rust project using Cargo. This command fetches the library directly from its Git repository.

```bash
cargo add --git https://github.com/schell/renderling.git --branch main
```

--------------------------------

### Add Atomics to Naga SPV Frontend

Source: https://github.com/schell/renderling/blob/main/NOTES.md

Proposal to add atomics to naga's spv frontend. This relates to a specific GitHub Pull Request.

```shell
# roughly to complete this PR https://github.com/gfx-rs/naga/pull/2304
```

--------------------------------

### Check for Diffs

Source: https://github.com/schell/renderling/blob/main/CONTRIBUTING.md

Compares the current working directory with the last commit to identify any uncommitted changes.

```bash
git diff
```

--------------------------------

### Load and Manage Textures with Atlas

Source: https://context7.com/schell/renderling/llms.txt

Load images into the texture atlas system and use them in materials. Supports loading from paths and image buffers. Textures can be changed at runtime.

```rust
use renderling::atlas::AtlasImage;

// Load images into the texture atlas
let sandstone = AtlasImage::from_path("sandstone.png").unwrap();
let dirt = AtlasImage::from_path("dirt.jpg").unwrap();
let grass = AtlasImage::from(image::open("grass.png").unwrap());
```

```rust
// Stage multiple images at once
let entries = stage.set_images([sandstone, dirt, grass]).unwrap();
```

```rust
// Use textures in materials
let material = stage
    .new_material()
    .with_albedo_texture(&entries[0])    // sandstone
    .with_has_lighting(true);
```

```rust
// Change texture at runtime
material.set_albedo_texture(&entries[1]);  // Switch to dirt
```

--------------------------------

### Error Handling with Snafu

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Use the `snafu` crate for error handling. Derive `Debug` and `Snafu` for your error types.

```rust
#[derive(Debug, Snafu)]
```

--------------------------------

### Create Simple Transform

Source: https://context7.com/schell/renderling/llms.txt

Define a basic transformation including translation, rotation, and scale. This transform can be applied to primitives or other scene graph nodes.

```rust
use renderling::{
    glam::{Quat, Vec3},
    transform::{NestedTransform, Transform},
};

// Create a simple transform
let transform = stage
    .new_transform()
    .with_translation(Vec3::new(10.0, 0.0, 0.0))
    .with_rotation(Quat::from_axis_angle(Vec3::Y, 0.5))
    .with_scale(Vec3::splat(2.0));
```

--------------------------------

### Minimal CSS Reset

Source: https://github.com/schell/renderling/blob/main/crates/example-wasm/index.html

A basic CSS reset to normalize styles across browsers. Apply this at the beginning of your stylesheet.

```css
/* A sane CSS reset from * https://www.digitalocean.com/community/tutorials/css-minimal-css-reset */
html { box-sizing: border-box; font-size: 16px; }
*, 
*:before, 
*:after { box-sizing: inherit; }
body, h1, h2, h3, h4, h5, h6, p, ol, ul { margin: 0; padding: 0; font-weight: normal; }
ol, ul { list-style: none; }
img { max-width: 100%; height: auto; }
```

--------------------------------

### Patch crates.io for Rust-GPU

Source: https://github.com/schell/renderling/blob/main/manual/src/setup.md

Configure your Cargo.toml file to patch the `spirv-std` crate. This is a temporary workaround for Rust-GPU's release cycle, ensuring compatibility with shaders written in Rust.

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

--------------------------------

### Remove a Point Light in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Remove a previously added point light from the stage to reclaim resources. This is optional but good practice.

```rust
stage.remove_light(renderling::Light::Point { position: vec3(0.0, 1.0, 0.0), color: vec3(1.0, 1.0, 1.0), radius: 10.0 });
```

--------------------------------

### Dynamically Update Material Color

Source: https://context7.com/schell/renderling/llms.txt

Modify the albedo color of an existing material after it has been created. This allows for dynamic visual changes in the scene.

```rust
// Update material properties dynamically
material.set_albedo_factor(Vec4::new(0.0, 1.0, 0.0, 1.0));  // Change to green
```

--------------------------------

### Load GLTF Model from Bytes

Source: https://context7.com/schell/renderling/llms.txt

Loads a GLTF model from a byte vector, useful for embedded or network-loaded assets. Unloads CPU memory after loading.

```rust
let gltf_bytes: Vec<u8> = /* loaded from network or embedded */;
let model = stage
    .load_gltf_document_from_bytes(&gltf_bytes)
    .unwrap()
    .into_gpu_only();
```

--------------------------------

### Vulkan Debugging Command

Source: https://github.com/schell/renderling/blob/main/NOTES.md

A command to enable Vulkan validation layers and debug printfs for debugging Vulkan applications. This helps in identifying issues during runtime.

```bash
VK_LOADER_LAYERS_ENABLE='*validation' VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT DEBUG_PRINTF_TO_STDOUT=1
```

--------------------------------

### Rendering the Scene with Skybox

Source: https://github.com/schell/renderling/blob/main/manual/src/skybox.md

This code is responsible for rendering the scene, including the previously added skybox. It's typically called within the main update loop or a dedicated rendering system.

```rust
fn render_skybox(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.insert_resource(AmbientLight {
        color: Color::rgba_u8(255, 255, 255, 0),
        brightness: 0.5,
    });
    commands.spawn(Skybox::new(SkyboxMaterial {
        image: asset_server.load("textures/helipad.jpg"),
    }));
}
```

--------------------------------

### Rust Test Module Structure

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Place inline tests within modules using `#[cfg(test)] mod test { ... }`.

```rust
#[cfg(test)] mod test { ... }
```

--------------------------------

### Create Nested Transform Hierarchy

Source: https://context7.com/schell/renderling/llms.txt

Build a hierarchical scene graph using nested transforms. Children inherit transformations from their parents, allowing for complex articulated objects or scene structures.

```rust
// Create nested transforms for hierarchical scenes
let root_node = stage
    .new_nested_transform()
    .with_local_scale(Vec3::new(25.0, 25.0, 1.0));

let child_node = stage
    .new_nested_transform()
    .with_local_translation(Vec3::new(1.0, 1.0, 0.0));

let grandchild_node = stage
    .new_nested_transform()
    .with_local_rotation(Quat::from_axis_angle(Vec3::Z, 0.5));

// Build the hierarchy
root_node.add_child(&child_node);
child_node.add_child(&grandchild_node);
```

--------------------------------

### Toggle Scene Lighting

Source: https://context7.com/schell/renderling/llms.txt

Control whether the scene uses lighting calculations or renders unlit. Can be set during stage creation or toggled at runtime.

```rust
let stage = ctx
    .new_stage()
    .with_lighting(false);
```

```rust
stage.set_has_lighting(true);   // Enable lighting
stage.set_has_lighting(false);  // Disable lighting (unlit rendering)
```

--------------------------------

### Main Layout Styles

Source: https://github.com/schell/renderling/blob/main/crates/example-wasm/index.html

Styles for the main content area and the canvas element within it. Ensures the canvas covers the entire viewport.

```css
main { margin: 0; width: 100%; height: 100%; background-color: #7f7f7f; }
main canvas { margin: 0; padding: 0; position: absolute; left: 0; right: 0; top: 0; bottom: 0; background-color: #ffffff; }
```

--------------------------------

### Render Scene with Lighting Disabled

Source: https://github.com/schell/renderling/blob/main/manual/src/gltf.md

Renders the scene with lighting turned off. This is useful for debugging or when a specific unlit appearance is desired. Use Stage::set_has_lighting to control this behavior.

```rust
stage.set_has_lighting(false);
stage.render(&mut context, &mut camera);
```

--------------------------------

### Fieldset Styling

Source: https://github.com/schell/renderling/blob/main/crates/example-wasm/index.html

Basic styling for fieldset elements, used for grouping form controls. Adjust margins as needed.

```css
section fieldset { margin: 0 0.25em 0.5em 0.25em; }
```

--------------------------------

### Adding Skybox to Scene

Source: https://github.com/schell/renderling/blob/main/manual/src/skybox.md

This snippet adds a skybox to the renderling scene using an HDR image. Ensure the HDR image is correctly placed in your assets and the path is accurate.

```rust
commands.insert_resource(AmbientLight {
    color: Color::rgba_u8(255, 255, 255, 0),
    brightness: 0.5,
});
commands.spawn(Skybox::new(SkyboxMaterial {
    image: asset_server.load("textures/helipad.jpg"),
}));
```

--------------------------------

### Unload CPU Memory for Vertices

Source: https://context7.com/schell/renderling/llms.txt

After staging vertices to the GPU, you can optionally unload their CPU memory to save resources, while retaining the GPU data. This requires the `GpuOnlyArray` type.

```rust
// Optionally unload CPU memory after staging (keeps GPU data)
let vertices: Vertices<GpuOnlyArray> = vertices.into_gpu_only();
```

--------------------------------

### Remove a Directional Light in Renderling

Source: https://github.com/schell/renderling/blob/main/manual/src/lighting/analytical.md

Remove a previously added directional light from the stage to reclaim resources. This is optional but good practice.

```rust
stage.remove_light(renderling::Light::Directional { direction: vec3(1.0, -1.0, -1.0), color: vec3(1.0, 1.0, 1.0) });
```

--------------------------------

### Conditional Compilation for CPU Code

Source: https://github.com/schell/renderling/blob/main/AGENTS.md

Wrap CPU-specific code with the `#[cfg(cpu)]` attribute to ensure it's only compiled on CPU targets.

```rust
#[cfg(cpu)]
```

--------------------------------

### Toggle Primitive Visibility

Source: https://context7.com/schell/renderling/llms.txt

Control whether a primitive is rendered without removing it from the scene. Call `set_visible(false)` to hide and `set_visible(true)` to show.

```rust
// Toggle visibility without removing the primitive
cube.set_visible(false);
cube.set_visible(true);
```

--------------------------------

### Rust-GPU Array to Slice Error

Source: https://github.com/schell/renderling/blob/main/NOTES.md

Illustrates a common error in rust-gpu where an array cannot be directly cast to a slice. This is due to pointer type casting limitations.

```rust
error: cannot cast between pointer types
       from `*[u32; 3]`
         to `*[u32]`
```

--------------------------------

### Attach Transform to Primitive

Source: https://context7.com/schell/renderling/llms.txt

Apply a transform (or a nested transform node) to a primitive. This determines the primitive's position, orientation, and scale in the world.

```rust
// Attach transforms to primitives
let prim = stage
    .new_primitive()
    .with_vertices(&vertices)
    .with_transform(&grandchild_node);
```

--------------------------------

### Update Primitive Vertices Dynamically

Source: https://context7.com/schell/renderling/llms.txt

Change the vertex data of an existing primitive. This is useful for animations or dynamic mesh updates. Ensure new vertices are created using `stage.new_vertices()`.

```rust
// Update vertices dynamically
let new_vertices = stage.new_vertices(/* new vertex data */);
cube.set_vertices(new_vertices);
```

--------------------------------

### Unload Vertices from CPU

Source: https://github.com/schell/renderling/blob/main/manual/src/stage.md

Frees up CPU memory after vertices have been staged on the GPU. This is optional if you intend to modify vertices directly on the CPU.

```rust
vertices.unload_cpu_data();
```

--------------------------------

### Remove Primitive from Rendering

Source: https://context7.com/schell/renderling/llms.txt

Remove a primitive from the rendering pipeline. Resources associated with the primitive will be released when the primitive object is dropped.

```rust
// Remove primitive from rendering (resources released when dropped)
stage.remove_primitive(&cube);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.