Expose layered PBR material descriptor

Author: proggeramlug

docs/layered-pbr.md

@@ -251,3 +251,35 @@ layered ABI and do not allocate the LUT.
 The CPU scene tracer and GPU path tracer still require an explicit reviewed
 migration to these named equations. Iridescence is the next lobe package;
 public authoring/debug surfaces and transport parity follow it.
+
+## Public authoring API
+
+`setSceneNodeMaterial(node, descriptor)` is the single public authoring entry
+point for base, emissive, clearcoat, specular/IOR, sheen, anisotropy, and
+iridescence factors. Every field is optional. An empty descriptor restores the
+same base defaults as a new scene node, while an omitted layered lobe is absent
+from the native lobe mask and keeps the allocation-free base-material path.
+
+```ts
+setSceneNodeMaterial(node, {
+  color: [210, 68, 32],
+  roughness: 0.22,
+  metalness: 0,
+  layered: {
+    clearcoat: { factor: 0.8, roughness: 0.1 },
+    iridescence: {
+      factor: 0.65,
+      ior: 1.3,
+      thicknessMinimum: 120,
+      thicknessMaximum: 380,
+    },
+  },
+});
+```
+
+Base color follows Bloom's engine-wide 0–255 convention. Layered colors are
+linear factors, anisotropy rotation is in radians, and iridescence thickness is
+in nanometres. Unsafe scalar input is bounded before it reaches a shader, and
+reapplying an unchanged descriptor does not rebuild the material. Layer
+textures and texture transforms remain glTF-authored in this first API version;
+the importer continues to preserve and render their full UV contract.

examples/renderer-test/main.ts

@@ -55,7 +55,7 @@ import {
 import {
   createSceneNode, setSceneNodeTransform,
   updateSceneNodeGeometry,
-  setSceneNodeColor, setSceneNodePbr,
+  setSceneNodeColor, setSceneNodePbr, setSceneNodeMaterial,
   setSceneNodeCastShadow, setSceneNodeReceiveShadow,
   enableShadows, dumpShadowMap,
   addDirectionalLight, addPointLight,
@@ -242,8 +242,11 @@ function placeSphere(
   roughness: number, metalness: number,
 ): number {
   const node = placeNode(sphereHandle, 0, px, py, pz, scale, scale, scale);
-  setSceneNodeColor(node, cr * 255, cg * 255, cb * 255);
-  setSceneNodePbr(node, roughness, metalness);
+  setSceneNodeMaterial(node, {
+    color: [cr * 255, cg * 255, cb * 255],
+    roughness,
+    metalness,
+  });
   return node;
 }
 
@@ -254,8 +257,11 @@ function placeCube(
   roughness: number, metalness: number,
 ): number {
   const node = placeNode(cubeHandle, 0, px, py, pz, sx, sy, sz);
-  setSceneNodeColor(node, cr * 255, cg * 255, cb * 255);
-  setSceneNodePbr(node, roughness, metalness);
+  setSceneNodeMaterial(node, {
+    color: [cr * 255, cg * 255, cb * 255],
+    roughness,
+    metalness,
+  });
   // Thin horizontal slabs (floors) should receive but not cast
   // shadows — otherwise they fill the shadow map with their own
   // depth and everything reads as "in shadow of the ground".

native/shared/src/ffi_core/scene.rs

@@ -343,6 +343,73 @@ macro_rules! __bloom_ffi_scene {
             })
         }
 
+        // bloom_scene_set_material_emissive  [source: macos]
+        #[no_mangle]
+        pub extern "C" fn bloom_scene_set_material_emissive(handle: f64, r: f64, g: f64, b: f64) {
+            $crate::ffi::guard("bloom_scene_set_material_emissive", move || {
+                let finite_non_negative = |value: f64| {
+                    if value.is_finite() {
+                        (value as f32).max(0.0)
+                    } else {
+                        0.0
+                    }
+                };
+                engine().scene.set_material_emissive_factor(
+                    handle,
+                    finite_non_negative(r),
+                    finite_non_negative(g),
+                    finite_non_negative(b),
+                );
+            })
+        }
+
+        // bloom_scene_set_material_layered_pbr  [source: macos]
+        #[no_mangle]
+        #[allow(clippy::too_many_arguments)]
+        pub extern "C" fn bloom_scene_set_material_layered_pbr(
+            handle: f64,
+            lobe_mask: f64,
+            clearcoat_factor: f64,
+            clearcoat_roughness: f64,
+            clearcoat_normal_scale: f64,
+            specular_factor: f64,
+            specular_r: f64,
+            specular_g: f64,
+            specular_b: f64,
+            ior: f64,
+            sheen_r: f64,
+            sheen_g: f64,
+            sheen_b: f64,
+            sheen_roughness: f64,
+            anisotropy_strength: f64,
+            anisotropy_rotation: f64,
+            iridescence_factor: f64,
+            iridescence_ior: f64,
+            iridescence_thickness_minimum: f64,
+            iridescence_thickness_maximum: f64,
+        ) {
+            $crate::ffi::guard("bloom_scene_set_material_layered_pbr", move || {
+                let layered = $crate::models::MaterialLayeredPbr::from_authoring_factors(
+                    lobe_mask as u32,
+                    clearcoat_factor as f32,
+                    clearcoat_roughness as f32,
+                    clearcoat_normal_scale as f32,
+                    specular_factor as f32,
+                    [specular_r as f32, specular_g as f32, specular_b as f32],
+                    ior as f32,
+                    [sheen_r as f32, sheen_g as f32, sheen_b as f32],
+                    sheen_roughness as f32,
+                    anisotropy_strength as f32,
+                    anisotropy_rotation as f32,
+                    iridescence_factor as f32,
+                    iridescence_ior as f32,
+                    iridescence_thickness_minimum as f32,
+                    iridescence_thickness_maximum as f32,
+                );
+                engine().scene.set_material_layered_pbr(handle, layered);
+            })
+        }
+
         // bloom_scene_set_material_texture  [source: macos]
         #[no_mangle]
         pub extern "C" fn bloom_scene_set_material_texture(handle: f64, texture_idx: f64) {

native/shared/src/models.rs

@@ -132,6 +132,93 @@ impl Default for MaterialLayeredPbr {
 }
 
 impl MaterialLayeredPbr {
+    pub const CLEARCOAT_LOBE: u32 = 1 << 0;
+    pub const SHEEN_LOBE: u32 = 1 << 1;
+    pub const ANISOTROPY_LOBE: u32 = 1 << 2;
+    pub const IRIDESCENCE_LOBE: u32 = 1 << 3;
+    pub const SPECULAR_IOR_LOBE: u32 = 1 << 4;
+
+    /// Build the texture-free layered material used by the public authoring
+    /// API. The lobe mask is authoritative: values belonging to an absent
+    /// lobe are ignored so an omitted descriptor always restores glTF
+    /// defaults and the allocation-free base-material path.
+    #[doc(hidden)]
+    #[allow(clippy::too_many_arguments)]
+    pub fn from_authoring_factors(
+        lobe_mask: u32,
+        clearcoat_factor: f32,
+        clearcoat_roughness: f32,
+        clearcoat_normal_scale: f32,
+        specular_factor: f32,
+        specular_color: [f32; 3],
+        ior: f32,
+        sheen_color: [f32; 3],
+        sheen_roughness: f32,
+        anisotropy_strength: f32,
+        anisotropy_rotation: f32,
+        iridescence_factor: f32,
+        iridescence_ior: f32,
+        iridescence_thickness_minimum: f32,
+        iridescence_thickness_maximum: f32,
+    ) -> Self {
+        fn finite_or(value: f32, fallback: f32) -> f32 {
+            if value.is_finite() {
+                value
+            } else {
+                fallback
+            }
+        }
+        fn unit(value: f32, fallback: f32) -> f32 {
+            finite_or(value, fallback).clamp(0.0, 1.0)
+        }
+        fn non_negative(value: f32, fallback: f32) -> f32 {
+            finite_or(value, fallback).max(0.0)
+        }
+        fn material_ior(value: f32) -> f32 {
+            let value = finite_or(value, 1.5);
+            if value == 0.0 {
+                0.0
+            } else {
+                value.max(1.0)
+            }
+        }
+
+        let mut material = Self::default();
+        if lobe_mask & Self::CLEARCOAT_LOBE != 0 {
+            material.clearcoat_authored = true;
+            material.clearcoat_factor = unit(clearcoat_factor, 0.0);
+            material.clearcoat_roughness_factor = unit(clearcoat_roughness, 0.0);
+            material.clearcoat_normal_scale = finite_or(clearcoat_normal_scale, 1.0);
+        }
+        if lobe_mask & Self::SPECULAR_IOR_LOBE != 0 {
+            material.specular_authored = true;
+            material.specular_factor = unit(specular_factor, 1.0);
+            material.specular_color_factor = specular_color.map(|value| non_negative(value, 1.0));
+            material.ior_authored = true;
+            material.ior = material_ior(ior);
+        }
+        if lobe_mask & Self::SHEEN_LOBE != 0 {
+            material.sheen_authored = true;
+            material.sheen_color_factor = sheen_color.map(|value| unit(value, 0.0));
+            material.sheen_roughness_factor = unit(sheen_roughness, 0.0);
+        }
+        if lobe_mask & Self::ANISOTROPY_LOBE != 0 {
+            material.anisotropy_authored = true;
+            material.anisotropy_strength = unit(anisotropy_strength, 0.0);
+            material.anisotropy_rotation = finite_or(anisotropy_rotation, 0.0);
+        }
+        if lobe_mask & Self::IRIDESCENCE_LOBE != 0 {
+            material.iridescence_authored = true;
+            material.iridescence_factor = unit(iridescence_factor, 0.0);
+            material.iridescence_ior = finite_or(iridescence_ior, 1.3).max(1.0);
+            material.iridescence_thickness_minimum =
+                non_negative(iridescence_thickness_minimum, 100.0);
+            material.iridescence_thickness_maximum =
+                non_negative(iridescence_thickness_maximum, 400.0);
+        }
+        material
+    }
+
     pub(crate) fn is_active(self) -> bool {
         self.has_clearcoat()
             || self.has_specular_ior()
@@ -241,6 +328,75 @@ impl MaterialLayeredPbr {
     }
 }
 
+#[cfg(test)]
+mod layered_pbr_authoring_tests {
+    use super::MaterialLayeredPbr;
+
+    #[test]
+    fn omitted_lobes_restore_exact_defaults() {
+        let material = MaterialLayeredPbr::from_authoring_factors(
+            0,
+            1.0,
+            1.0,
+            2.0,
+            0.0,
+            [3.0, 2.0, 1.0],
+            1.1,
+            [1.0; 3],
+            1.0,
+            1.0,
+            2.0,
+            1.0,
+            1.8,
+            20.0,
+            80.0,
+        );
+        assert_eq!(material, MaterialLayeredPbr::default());
+        assert!(!material.is_active());
+    }
+
+    #[test]
+    fn authoring_factors_are_finite_and_range_safe() {
+        let mask = MaterialLayeredPbr::CLEARCOAT_LOBE
+            | MaterialLayeredPbr::SPECULAR_IOR_LOBE
+            | MaterialLayeredPbr::SHEEN_LOBE
+            | MaterialLayeredPbr::ANISOTROPY_LOBE
+            | MaterialLayeredPbr::IRIDESCENCE_LOBE;
+        let material = MaterialLayeredPbr::from_authoring_factors(
+            mask,
+            2.0,
+            -1.0,
+            f32::NAN,
+            -2.0,
+            [-1.0, 2.0, f32::INFINITY],
+            0.5,
+            [-1.0, 0.5, 2.0],
+            f32::NAN,
+            4.0,
+            f32::INFINITY,
+            3.0,
+            0.2,
+            -10.0,
+            f32::NAN,
+        );
+        assert_eq!(material.clearcoat_factor, 1.0);
+        assert_eq!(material.clearcoat_roughness_factor, 0.0);
+        assert_eq!(material.clearcoat_normal_scale, 1.0);
+        assert_eq!(material.specular_factor, 0.0);
+        assert_eq!(material.specular_color_factor, [0.0, 2.0, 1.0]);
+        assert_eq!(material.ior, 1.0);
+        assert_eq!(material.sheen_color_factor, [0.0, 0.5, 1.0]);
+        assert_eq!(material.sheen_roughness_factor, 0.0);
+        assert_eq!(material.anisotropy_strength, 1.0);
+        assert_eq!(material.anisotropy_rotation, 0.0);
+        assert_eq!(material.iridescence_factor, 1.0);
+        assert_eq!(material.iridescence_ior, 1.0);
+        assert_eq!(material.iridescence_thickness_minimum, 0.0);
+        assert_eq!(material.iridescence_thickness_maximum, 400.0);
+        assert!(material.is_active());
+    }
+}
+
 pub(crate) fn effective_material_ior(ior: f32) -> f32 {
     if ior == 0.0 {
         1_000_000.0

native/shared/src/scene.rs

@@ -1037,6 +1037,9 @@ impl SceneGraph {
 
     pub fn set_material_texture(&mut self, handle: f64, texture_idx: u32) {
         if let Some(node) = self.nodes.get_mut(handle) {
+            if node.material.texture_idx == texture_idx {
+                return;
+            }
             node.material.texture_idx = texture_idx;
             node.mat_dirty = true;
         }
@@ -1065,7 +1068,11 @@ impl SceneGraph {
 
     pub fn set_material_emissive_factor(&mut self, handle: f64, r: f32, g: f32, b: f32) {
         if let Some(node) = self.nodes.get_mut(handle) {
-            node.material.emissive = [r, g, b];
+            let emissive = [r, g, b];
+            if node.material.emissive == emissive {
+                return;
+            }
+            node.material.emissive = emissive;
             node.mat_dirty = true;
         }
     }
@@ -2835,6 +2842,12 @@ mod gpu_driven_cache_tests {
             !scene.nodes.get(node).unwrap().mat_dirty,
             "identical PBR factors must remain allocation-free"
         );
+        scene.set_material_emissive_factor(node, 0.0, 0.0, 0.0);
+        scene.set_material_texture(node, 0);
+        assert!(
+            !scene.nodes.get(node).unwrap().mat_dirty,
+            "default descriptor fields must not rebuild an unchanged material"
+        );
     }
 
     #[test]

native/watchos/src/ffi_stubs.rs

@@ -500,6 +500,10 @@
 }
 #[no_mangle] pub extern "C" fn bloom_scene_attach_model_lod(_p0: f64, _p1: f64, _p2: f64, _p3: f64, _p4: f64) {
 }
+#[no_mangle] pub extern "C" fn bloom_scene_set_material_emissive(_p0: f64, _p1: f64, _p2: f64, _p3: f64) {
+}
+#[no_mangle] pub extern "C" fn bloom_scene_set_material_layered_pbr(_p0: f64, _p1: f64, _p2: f64, _p3: f64, _p4: f64, _p5: f64, _p6: f64, _p7: f64, _p8: f64, _p9: f64, _p10: f64, _p11: f64, _p12: f64, _p13: f64, _p14: f64, _p15: f64, _p16: f64, _p17: f64, _p18: f64, _p19: f64) {
+}
 #[no_mangle] pub extern "C" fn bloom_scene_node_vertex_count(_p0: f64) -> f64 {
     0.0
 }