diff --git a/crates/automation/src/headless.rs b/crates/automation/src/headless.rs index d026596..27823ca 100644 --- a/crates/automation/src/headless.rs +++ b/crates/automation/src/headless.rs @@ -279,6 +279,7 @@ impl Headless { tiling, exposure: v.exposure, env_rotation: v.env_rotation, + normal_y_flip: v.normal_y_flip, show_env: false, supersample: 2, transparency: v.transparency, diff --git a/crates/automation/tests/normal_maps.rs b/crates/automation/tests/normal_maps.rs new file mode 100644 index 0000000..41e2854 --- /dev/null +++ b/crates/automation/tests/normal_maps.rs @@ -0,0 +1,46 @@ +use materialcraft_automation::headless::{Filesystem, Headless, RenderOptions}; +use materialcraft_engine::{ + execute, + image::{Image, Kind}, + new_session, + nodes::atomic::height_to_normal, +}; +use materialcraft_render::{Lighting, Maps, Scene, Settings, render}; +use serde_json::json; + +#[test] +fn generated_normal_conventions_produce_the_same_surface_when_matched() { + let height = Image::gray(32, 32, |x, y| ((x as f32 * 0.15).sin() + (y as f32 * 0.25).sin()) * 0.25 + 0.5); + let gl = height_to_normal(&height, 8.0, false, false, false); + let dx = height_to_normal(&height, 8.0, true, false, false); + let normal_node = materialcraft_engine::nodes::find("normal").unwrap(); + assert_eq!(normal_node.param("format").unwrap().default.as_i32(), Some(0)); + let maps = |normal| Maps { normal: Some(normal), base_color: Some(Image::filled(4, 4, Kind::Color, [0.5, 0.5, 0.5, 1.0])), ..Maps::default() }; + let (scene, light) = (Scene::builtin("sphere"), Lighting::new("studio")); + let settings = Settings::default(); + assert!(!settings.normal_y_flip); + let expected = render(&scene, &maps(gl), &light, &settings, 64, 48); + let flipped = maps(dx); + let matched = render(&scene, &flipped, &light, &Settings { normal_y_flip: true, ..settings }, 64, 48); + assert!(expected.iter().zip(&matched).all(|(a, b)| a.abs_diff(*b) <= 1)); + let wrong = render(&scene, &flipped, &light, &settings, 64, 48); + assert!(expected.iter().zip(&wrong).filter(|(a, b)| a.abs_diff(**b) > 2).count() > 20); +} + +#[test] +fn headless_render_honors_the_normal_y_command() { + let mut s = new_session(); + s.preview_size = Some(64); + let node = execute(&mut s, "graph.node.add", &json!({"def": "uniform", "params": {"color": [0.5, 0.75, 1.0, 1.0]}})).unwrap()["id"].as_u64().unwrap(); + execute(&mut s, "graph.node.add", &json!({"def": "output", "connectFrom": {"node": node}, "params": {"usage": 1}})).unwrap(); + let mut h = Headless::new(s, Filesystem::Denied); + let options = RenderOptions { width: Some(64), height: Some(48), ..RenderOptions::default() }; + let gl = h.render_png(&options).unwrap().png; + execute(&mut h.session, "view.3d", &json!({"normalYFlip": true})).unwrap(); + let wrong = h.render_png(&options).unwrap().png; + assert_ne!(gl, wrong); + execute(&mut h.session, "graph.node.param", &json!({"id": node, "param": "color", "value": [0.5, 0.25, 1.0, 1.0]})).unwrap(); + assert_eq!(gl, h.render_png(&options).unwrap().png); + execute(&mut h.session, "view.3d.reset", &json!({})).unwrap(); + assert_eq!(wrong, h.render_png(&options).unwrap().png); +} diff --git a/crates/engine/src/session.rs b/crates/engine/src/session.rs index d61f659..2d11b39 100644 --- a/crates/engine/src/session.rs +++ b/crates/engine/src/session.rs @@ -36,6 +36,8 @@ pub struct View3d { pub height_scale: f32, /// The height (0..1) that stays on the surface: 0 = the relief rises out of the mesh, 0.5 = centered on it. pub height_level: f32, + /// Flip green when reading DirectX normal maps; false matches the Normal node's OpenGL default. + pub normal_y_flip: bool, pub show_axis: bool, pub show_grid: bool, /// See through the mesh where the material's alpha (opacity output, else base color alpha) @@ -59,6 +61,7 @@ impl Default for View3d { exposure: 0.0, height_scale: 0.04, height_level: 0.0, + normal_y_flip: false, show_axis: false, show_grid: false, transparency: true, diff --git a/crates/engine/src/view_cmds.rs b/crates/engine/src/view_cmds.rs index d1beb70..8196d88 100644 --- a/crates/engine/src/view_cmds.rs +++ b/crates/engine/src/view_cmds.rs @@ -29,7 +29,7 @@ pub(crate) fn specs() -> Vec { "3D view settings", [], None, - "{scene? (cube|cylinder|plane|sphere|material_ball|rounded_cube|torus), tiling?, yaw?, pitch?, distance?, target? ([x, y, z] orbit point in mesh radii from its center, within the pan limit preference), environment? (studio|sunset|overcast|night), envRotation?, exposure?, heightScale? (displacement depth in mesh radii, 0..0.5), heightLevel? (height that stays on the surface, 0..1; 0 = rises out), axis?, grid?, transparency? (see through where alpha < 1), alphaView? (show the alpha channel)}", + "{scene? (cube|cylinder|plane|sphere|material_ball|rounded_cube|torus), tiling?, yaw?, pitch?, distance?, target? ([x, y, z] orbit point in mesh radii from its center, within the pan limit preference), environment? (studio|sunset|overcast|night), envRotation?, exposure?, heightScale? (displacement depth in mesh radii, 0..0.5), heightLevel? (height that stays on the surface, 0..1; 0 = rises out), normalYFlip? (DirectX normal maps; default false/OpenGL), axis?, grid?, transparency? (see through where alpha < 1), alphaView? (show the alpha channel)}", always, view3d ), @@ -141,6 +141,9 @@ fn view3d(s: &mut Session, p: &J) -> Result { if let Some(t) = f32p(p, "heightLevel") { v.height_level = t.clamp(0.0, 1.0); } + if let Some(flip) = boolp(p, "normalYFlip") { + v.normal_y_flip = flip; + } if let Some(b) = boolp(p, "axis") { v.show_axis = b; } diff --git a/crates/engine/tests/normal_maps.rs b/crates/engine/tests/normal_maps.rs new file mode 100644 index 0000000..c4c863f --- /dev/null +++ b/crates/engine/tests/normal_maps.rs @@ -0,0 +1,17 @@ +use materialcraft_engine::{View3d, execute, new_session}; +use serde_json::json; + +#[test] +fn normal_map_convention_is_inspectable_and_resets_to_opengl() { + let mut s = new_session(); + assert!(!s.view3d.normal_y_flip); + assert_eq!(materialcraft_engine::nodes::find("normal").unwrap().param("format").unwrap().default.as_i32(), Some(0)); + execute(&mut s, "view.3d", &json!({"normalYFlip": true})).unwrap(); + let inspection = execute(&mut s, "session.inspect", &json!({})).unwrap(); + assert_eq!(inspection["view3d"]["normalYFlip"], true); + let saved = serde_json::to_value(&s.view3d).unwrap(); + assert!(serde_json::from_value::(saved).unwrap().normal_y_flip); + assert!(!serde_json::from_value::(json!({"scene": "sphere"})).unwrap().normal_y_flip); + execute(&mut s, "view.3d.reset", &json!({})).unwrap(); + assert!(!s.view3d.normal_y_flip); +} diff --git a/crates/render/src/preview.rs b/crates/render/src/preview.rs index 06e494f..84b40c9 100644 --- a/crates/render/src/preview.rs +++ b/crates/render/src/preview.rs @@ -233,6 +233,8 @@ pub struct Settings { pub exposure: f32, /// Degrees. pub env_rotation: f32, + /// Interpret the green channel as DirectX (-Y) instead of OpenGL (+Y). + pub normal_y_flip: bool, /// Show the (blurred) environment behind the mesh instead of the flat backdrop. pub show_env: bool, /// 1 = one ray per pixel, 2 = 2×2 supersampling. @@ -259,6 +261,7 @@ impl Default for Settings { tiling: 1.0, exposure: 0.0, env_rotation: 0.0, + normal_y_flip: false, show_env: false, supersample: 1, ao_rays: 0, @@ -417,7 +420,10 @@ fn shade(scene: &Scene, maps: &Maps, light: &Lighting, s: &Settings, origin: Vec let ao = tex_gray(&maps.ao, uv, 1.0).clamp(0.0, 1.0); let n = match tex(&maps.normal, uv) { Some(c) => { - let t = Vec3::new(c[0] * 2.0 - 1.0, c[1] * 2.0 - 1.0, c[2] * 2.0 - 1.0); + let mut t = Vec3::new(c[0] * 2.0 - 1.0, c[1] * 2.0 - 1.0, c[2] * 2.0 - 1.0); + if s.normal_y_flip { + t.y = -t.y; + } // OpenGL convention: green points along +v in texture space, which is -bitangent // with top-left UVs. (tan * t.x - bit * t.y + nrm * t.z.max(0.05)).normalize_or_zero() diff --git a/crates/ui-egui/src/view3d.rs b/crates/ui-egui/src/view3d.rs index 4ac0c50..3b24f75 100644 --- a/crates/ui-egui/src/view3d.rs +++ b/crates/ui-egui/src/view3d.rs @@ -159,6 +159,11 @@ fn menus(app: &mut MaterialCraftApp, ui: &mut Ui) { ui.menu_button(tr("Display"), |ui| { crate::view2d::resolution_menu(app, ui); ui.separator(); + let mut flip = app.session.view3d.normal_y_flip; + if ui.checkbox(&mut flip, tr("Flip normal map Y (DirectX)")).changed() { + app.run("view.3d", json!({"normalYFlip": flip})); + } + ui.separator(); ui.checkbox(&mut app.view3d.show_env, tr("Environment background")); ui.separator(); let mut t = app.session.view3d.transparency; @@ -300,6 +305,7 @@ fn content_key(app: &MaterialCraftApp, w: u32, h: u32, show_env: bool, relief_sh let mut hs = DefaultHasher::new(); let v = &app.session.view3d; (w, h, show_env, &v.scene, &v.environment, app.session.custom_mesh.as_ref().map(|(n, _)| n), v.transparency, v.alpha_view, relief_shown).hash(&mut hs); + v.normal_y_flip.hash(&mut hs); for f in [v.yaw, v.pitch, v.distance, v.target[0], v.target[1], v.target[2], v.tiling, v.exposure, v.env_rotation, v.height_scale, v.height_level] { f.to_bits().hash(&mut hs); } @@ -475,6 +481,7 @@ fn inputs(app: &mut MaterialCraftApp, supersample: u32) -> Option<(Arc, A tiling: v.tiling, exposure: v.exposure, env_rotation: v.env_rotation, + normal_y_flip: v.normal_y_flip, show_env: app.view3d.show_env, supersample, transparency: v.transparency, diff --git a/crates/ui-egui/tests/normal_maps.rs b/crates/ui-egui/tests/normal_maps.rs new file mode 100644 index 0000000..dcdd225 --- /dev/null +++ b/crates/ui-egui/tests/normal_maps.rs @@ -0,0 +1,79 @@ +use egui::vec2; +use egui_kittest::{Harness, kittest::Queryable}; +use materialcraft_ui_egui::{MaterialCraftApp, UiState}; +use serde_json::json; +use std::time::Duration; + +fn app() -> MaterialCraftApp { + let mut app = MaterialCraftApp::headless(materialcraft_engine::new_session(), UiState::default()); + let node = app.run("graph.node.add", json!({"def": "uniform", "params": {"color": [0.5, 0.75, 1.0, 1.0]}})).unwrap()["id"].as_u64().unwrap(); + app.run("graph.node.add", json!({"def": "output", "connectFrom": {"node": node}, "params": {"usage": 1}})).unwrap(); + app +} + +fn settle(h: &mut Harness<'static, MaterialCraftApp>, after: u64) { + for _ in 0..300 { + h.step(); + let app = h.state(); + if app.view3d.renders > after && !app.session.dirty && !app.cooker.busy() && !app.view3d.busy() { + return; + } + std::thread::sleep(Duration::from_millis(10)); + } + panic!("the normal-map preview did not finish rendering"); +} + +fn toggle(h: &mut Harness<'static, MaterialCraftApp>) { + h.get_by_label("Display").click(); + h.run_steps(4); + h.get_by_label("Flip normal map Y (DirectX)").click(); + h.run_steps(4); +} + +#[test] +fn display_toggle_updates_the_session_and_rerenders_the_normal_map() { + let mut h = Harness::builder().with_size(vec2(1400.0, 860.0)).build_ui_state( + |ui, app: &mut MaterialCraftApp| { + app.step(&ui.ctx().clone()); + app.draw(ui); + }, + app(), + ); + settle(&mut h, 0); + let before = h.state().view3d.shown.clone().unwrap(); + let rendered = h.state().view3d.renders; + toggle(&mut h); + assert!(h.state().session.view3d.normal_y_flip); + settle(&mut h, rendered); + assert_ne!(before.2, h.state().view3d.shown.as_ref().unwrap().2); + // Close the open menu, then restore the OpenGL setting through the same pointer gesture. + h.key_press(egui::Key::Escape); + h.run_steps(4); + let rendered = h.state().view3d.renders; + toggle(&mut h); + assert!(!h.state().session.view3d.normal_y_flip); + settle(&mut h, rendered); + assert_eq!(before.2, h.state().view3d.shown.as_ref().unwrap().2); +} + +#[test] +#[ignore = "requires an offscreen GPU; run explicitly with --ignored"] +fn normal_convention_snapshot() { + let mut h = Harness::builder().with_size(vec2(1400.0, 860.0)).wgpu().build_ui_state( + |ui, app: &mut MaterialCraftApp| { + app.step(&ui.ctx().clone()); + app.draw(ui); + }, + app(), + ); + settle(&mut h, 0); + let rendered = h.state().view3d.renders; + toggle(&mut h); + settle(&mut h, rendered); + h.get_by_label("Display").click(); + h.run_steps(4); + assert!(h.state().session.view3d.normal_y_flip); + let dir = std::path::PathBuf::from(std::env::var_os("MC_SNAPSHOT_DIR").expect("MC_SNAPSHOT_DIR")); + std::fs::create_dir_all(&dir).unwrap(); + h.render().unwrap().save(dir.join("normal-convention.png")).unwrap(); +} diff --git a/docs/control-protocol.md b/docs/control-protocol.md index d21edaa..a6b5ed4 100644 --- a/docs/control-protocol.md +++ b/docs/control-protocol.md @@ -80,7 +80,7 @@ Types: `move`, `down`, `up`, `click`, `doubleClick`, `drag`, `scroll`, `key` (eg | `graph.node.function` | `{id?, param, function}` drives a parameter by a function graph of the graph's inputs (dynamic parameter); `{id?, param, remove: true}` removes it | | `graph.preset.save` / `.apply` / `.delete` | `{name}`: store, restore or remove the current input values | | `graph.createFromSelection` | `{name?, ids?}`: move nodes into a sub-graph and replace them with an instance | -| `view.2d` / `view.3d` | which node the 2D view shows, channel, tiling, histogram; scene, environment, camera, tiling, `heightScale` (how far the height output raises the mesh, in mesh radii) and `heightLevel` (the height that stays on the surface; 0 = the relief rises out of it), `transparency` (see through where the alpha is below one: the opacity output, else the base color's alpha), `alphaView` (show the alpha channel) | +| `view.2d` / `view.3d` | which node the 2D view shows, channel, tiling, histogram; scene, environment, camera, tiling, `heightScale` (how far the height output raises the mesh, in mesh radii) and `heightLevel` (the height that stays on the surface; 0 = the relief rises out of it), `normalYFlip` (interpret DirectX normal maps; default false/OpenGL), `transparency` (see through where the alpha is below one: the opacity output, else the base color's alpha), `alphaView` (show the alpha channel) | | `view.3d.loadMesh` | `{path}` shows an OBJ, glTF or GLB mesh (scene `custom`) | | `library.list` | `{filter?, category?}`: every node with ports and parameters | diff --git a/docs/wires-and-alpha.md b/docs/wires-and-alpha.md index 00a3fdc..693c409 100644 --- a/docs/wires-and-alpha.md +++ b/docs/wires-and-alpha.md @@ -89,6 +89,12 @@ session. ## Alpha in the 3D view +The 3D view reads OpenGL normal maps by default, matching the Normal node's default format. +For a DirectX normal map, enable **Display ▸ Flip normal map Y (DirectX)**, or run +`view.3d {"normalYFlip": true}`. Choose the corresponding format in the Normal node's properties. +The setting affects both the interactive view and headless renders, appears as `view3d.normalYFlip` +in `session.inspect`, and returns to OpenGL when the scene is reset. +

The same sphere in the alpha channel view: the opaque grid lines are white and the clear gaps black
The alpha channel view: white is opaque, black is clear