work on docs and the manual

Author: schell

Cargo.lock

@@ -1,8 +1,9 @@
 [workspace]
 members = [ 
-    "crates/example", 
-    "crates/example-culling",
-    "crates/example-wasm",
+    # "crates/example", 
+    "crates/examples",
+    #"crates/example-culling",
+    #"crates/example-wasm",
     "crates/loading-bytes",
     "crates/renderling", 
     "crates/renderling-build",
@@ -50,8 +51,8 @@ serde_json = "1.0.117"
 send_wrapper = "0.6.0"
 similarity = "0.2.0"
 snafu = "0.8"
-spirv-std = { git = "https://github.com/LegNeato/rust-gpu.git", rev = "425328a" }
-spirv-std-macros = { git = "https://github.com/LegNeato/rust-gpu.git", rev = "425328a" }
+spirv-std = { git = "https://github.com/rust-gpu/rust-gpu.git", rev = "425328a" }
+spirv-std-macros = { git = "https://github.com/rust-gpu/rust-gpu.git", rev = "425328a" }
 syn = { version = "2.0.49", features = ["full", "extra-traits", "parsing"] }
 tokio = "1.47.1"
 tracing = "0.1.41"
@@ -74,6 +75,4 @@ opt-level = 3
 opt-level = 3
 
 [patch.crates-io]
-spirv-std = { git = "https://github.com/LegNeato/rust-gpu.git", rev = "425328a" }
-crabslab = { path = "../crabslab/crates/crabslab" }
-craballoc = { path = "../crabslab/crates/craballoc" }
+spirv-std = { git = "https://github.com/rust-gpu/rust-gpu.git", rev = "425328a" }

Cargo.toml

@@ -1,9 +1,11 @@
 //! Camera control.
 use std::str::FromStr;
 
-use renderling::bvol::Aabb;
-use renderling::camera::Camera;
-use renderling::prelude::glam::{Mat4, Quat, UVec2, Vec2, Vec3};
+use renderling::{
+    bvol::Aabb,
+    camera::Camera,
+    glam::{Mat4, Quat, UVec2, Vec2, Vec3},
+};
 use winit::{event::KeyEvent, keyboard::Key};
 
 const RADIUS_SCROLL_DAMPENING: f32 = 0.001;
@@ -183,12 +185,8 @@ impl CameraController for WasdMouseCameraController {
     }
 
     fn update_camera(&self, UVec2 { x: w, y: h }: UVec2, camera: &Camera) {
-        let camera_rotation = Quat::from_euler(
-            renderling::prelude::glam::EulerRot::XYZ,
-            self.phi,
-            self.theta,
-            0.0,
-        );
+        let camera_rotation =
+            Quat::from_euler(renderling::glam::EulerRot::XYZ, self.phi, self.theta, 0.0);
         let projection =
             Mat4::perspective_infinite_rh(std::f32::consts::FRAC_PI_4, w as f32 / h as f32, 0.01);
         let view = Mat4::from_quat(camera_rotation) * Mat4::from_translation(-self.position);

crates/example/src/camera.rs

@@ -10,15 +10,15 @@ use renderling::{
     atlas::AtlasImage,
     bvol::{Aabb, BoundingSphere},
     camera::Camera,
+    context::Context,
     geometry::Vertex,
+    glam,
     gltf::{Animator, GltfDocument},
     light::AnalyticalLight,
-    prelude::*,
     primitive::Primitive,
     skybox::Skybox,
     stage::Stage,
     ui::{FontArc, Section, Text, Ui, UiPath, UiText},
-    Context,
 };
 
 pub mod camera;

crates/example/src/lib.rs

@@ -4,8 +4,8 @@ use std::sync::Arc;
 use clap::Parser;
 use example::{camera::CameraControl, App};
 use renderling::{
-    prelude::glam::{UVec2, Vec2},
-    Context,
+    context::Context,
+    glam::{UVec2, Vec2},
 };
 use winit::{application::ApplicationHandler, event::WindowEvent, window::WindowAttributes};
 

crates/example/src/main.rs

@@ -2,7 +2,7 @@
 
 use std::sync::Arc;
 
-use renderling::Context;
+use renderling::context::Context;
 use winit::monitor::MonitorHandle;
 
 pub trait TestAppHandler: winit::application::ApplicationHandler {

crates/example/src/utils.rs

@@ -0,0 +1,10 @@
+[package]
+name = "examples"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+doc-comment = "0.3"
+futures-lite.workspace = true
+renderling = { path = "../renderling" }
+tokio = { workspace = true, features = ["full"] }

crates/examples/Cargo.toml

@@ -0,0 +1,19 @@
+//! Context manual page.
+
+#[tokio::test]
+async fn context_page() {
+    // ANCHOR: create
+    use renderling::context::Context;
+
+    let ctx = Context::headless(256, 256).await;
+    // ANCHOR_END: create
+
+    // ANCHOR: frame
+    let frame = ctx.get_next_frame().unwrap();
+    // ...do some rendering
+    //
+    // Then capture the frame into an image, if you like
+    let _image_capture = frame.read_image().await.unwrap();
+    frame.present();
+    // ANCHOR_END: frame
+}

crates/examples/src/context.rs

@@ -0,0 +1,66 @@
+//! GLTF manual page.
+
+use crate::workspace_dir;
+
+#[tokio::test]
+async fn manual_gltf() {
+    // ANCHOR: setup
+    use renderling::{
+        camera::Camera,
+        context::Context,
+        glam::Vec4,
+        glam::{Mat4, Vec3},
+        stage::Stage,
+    };
+
+    let ctx = Context::headless(256, 256).await;
+    let stage: Stage = ctx
+        .new_stage()
+        .with_background_color(Vec4::new(0.5, 0.5, 0.5, 1.0));
+
+    let _camera: Camera = {
+        let aspect = 1.0;
+        let fovy = core::f32::consts::PI / 4.0;
+        let znear = 0.1;
+        let zfar = 1000.0;
+        let projection = Mat4::perspective_rh(fovy, aspect, znear, zfar);
+        let y = 50.0;
+        let eye = Vec3::new(120.0, y, 120.0);
+        let target = Vec3::new(0.0, y, 0.0);
+        let up = Vec3::Y;
+        let view = Mat4::look_at_rh(eye, target, up);
+
+        stage
+            .new_camera()
+            .with_projection_and_view(projection, view)
+    };
+    // ANCHOR_END: setup
+
+    // ANCHOR: load
+    use renderling::{gltf::GltfDocument, types::GpuOnlyArray};
+    let _model: GltfDocument<GpuOnlyArray> = stage
+        .load_gltf_document_from_path(workspace_dir().join("gltf/Fox.glb"))
+        .unwrap()
+        .into_gpu_only();
+    // ANCHOR_END: load
+
+    super::cwd_to_manual_assets_dir();
+
+    // ANCHOR: render_1
+    let frame = ctx.get_next_frame().unwrap();
+    stage.render(&frame.view());
+    let img = frame.read_image().await.unwrap();
+    img.save("gltf-example-shadow.png").unwrap();
+    frame.present();
+    // ANCHOR_END: render_1
+
+    // ANCHOR: no_lights
+    stage.set_has_lighting(false);
+    // ANCHOR_END: no_lights
+
+    let frame = ctx.get_next_frame().unwrap();
+    stage.render(&frame.view());
+    let img = frame.read_image().await.unwrap();
+    img.save("gltf-example-unlit.png").unwrap();
+    frame.present();
+}

crates/examples/src/gltf.rs

@@ -0,0 +1,44 @@
+//! # Examples for the manual
+//!
+//! This crate contains examples and snippets that get pulled into the manual
+//! via mdbook links. It also contains tests.
+
+#[cfg(test)]
+mod context;
+
+#[cfg(test)]
+mod stage;
+
+#[cfg(test)]
+mod gltf;
+
+#[cfg(test)]
+mod skybox;
+
+pub fn cwd_to_manual_assets_dir() -> std::path::PathBuf {
+    let current_dir =
+        std::path::PathBuf::from(std::env!("CARGO_WORKSPACE_DIR")).join("manual/src/assets");
+    let current_dir = current_dir.canonicalize().unwrap();
+    std::env::set_current_dir(&current_dir).unwrap();
+    println!("current dir: {:?}", std::env::current_dir());
+    current_dir
+}
+
+pub fn workspace_dir() -> std::path::PathBuf {
+    let current_dir = std::path::PathBuf::from(std::env!("CARGO_WORKSPACE_DIR"));
+    current_dir.canonicalize().unwrap()
+}
+
+pub fn cwd_to_cargo_workspace() -> std::path::PathBuf {
+    let current_dir = workspace_dir();
+    std::env::set_current_dir(&current_dir).unwrap();
+    println!("current dir: {:?}", std::env::current_dir());
+    current_dir
+}
+
+doc_comment::doctest!("../../../manual/src/stage.md", stage_md);
+
+#[test]
+fn can_test() {
+    assert_eq!(1, 1);
+}