From ee5ca2430b406fa72b2809a44ec9b0acab4a55fb Mon Sep 17 00:00:00 2001
From: selune <35337584+0xlillith@users.noreply.github.com>
Date: Fri, 23 Oct 2026 23:06:31 +0200
Subject: [PATCH] feat(render): expose independent anisotropic GGX core (#1694)
(#1699)
Extract the original numerical source and analytic tests from published #1698 at 463a3e0d into its existing #1699 constituent. Keep current GPU/shared jobs, format and kernel untouched. Add scoped numerical-contract documentation. Full render library 158 passed, strict scoped Clippy and wasm pass, as do assets/layers/lists/format; source tree pinned in the acceptance record. No runtime consumer or final combined renderer acceptance is claimed.
---
crates/render/src/anisotropic_surface.rs | 294 ++++++++++++++++++
.../render/src/anisotropic_surface_tests.rs | 277 +++++++++++++++++
crates/render/src/lib.rs | 1 +
docs/render-anisotropic-ggx.md | 46 +++
4 files changed, 618 insertions(+)
create mode 100644 crates/render/src/anisotropic_surface.rs
create mode 100644 crates/render/src/anisotropic_surface_tests.rs
create mode 100644 docs/render-anisotropic-ggx.md
diff --git a/crates/render/src/anisotropic_surface.rs b/crates/render/src/anisotropic_surface.rs
new file mode 100644
index 000000000..d2f696605
--- /dev/null
+++ b/crates/render/src/anisotropic_surface.rs
@@ -0,0 +1,294 @@
+//! Original anisotropic GGX reflection with separable Smith masking and Schlick Fresnel.
+//!
+//! Mathematics: Heitz, JCGT 7(4), 2018, equations 1 and 2,
+//! . No external implementation adapted.
+//! Sampling here uses the **NDF**, not Heitz's visible-normal (VNDF) sampler:
+//! `p(h) = D(h) * n.h`, then `p(l) = p(h) / (4 * v.h)`.
+//! Rejected reflections are null events, never resampled or renormalized.
+//!
+//! This numerical module does not install a renderer, persist a material or alter
+//! engineering axes. The visual frame's normal may be a shading normal, but the
+//! original geometric normal is required separately to reject below-surface rays.
+//! Consumers retain geometric normals for ray spawning and optical boundaries.
+//! No shading-normal energy correction, multiple scattering or transmission is modeled.
+
+use std::f64::consts::{PI, TAU};
+
+use solidcraft_geom::Vec3;
+
+use crate::surface::{MIN_ROUGHNESS, OpaqueSurface, SurfaceError, unit_direction};
+
+/// Admission or finite-arithmetic failure in the anisotropic numerical contract.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AnisotropicError {
+ /// An existing opaque-surface parameter or direction was invalid.
+ Surface(SurfaceError),
+ /// A visual frame was not orthogonal, or opposed its geometric normal.
+ Frame,
+ /// A variate was not finite in the half-open interval [0, 1).
+ Variates,
+ /// A computed density, response or sample weight was not finite/nonnegative.
+ Arithmetic,
+}
+
+impl From for AnisotropicError {
+ fn from(value: SurfaceError) -> Self {
+ Self::Surface(value)
+ }
+}
+
+impl std::fmt::Display for AnisotropicError {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Self::Surface(e) => std::fmt::Display::fmt(e, f),
+ Self::Frame => f.write_str("visual frame must be orthogonal and face the geometric normal"),
+ Self::Variates => f.write_str("anisotropic variates must be finite in [0, 1)"),
+ Self::Arithmetic => f.write_str("anisotropic result must be finite and nonnegative"),
+ }
+ }
+}
+impl std::error::Error for AnisotropicError {}
+
+type Result = std::result::Result;
+
+/// Right-handed orthonormal visual axes; independent of engineering material axes.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct VisualFrame {
+ normal: Vec3,
+ tangent: Vec3,
+ bitangent: Vec3,
+}
+
+impl VisualFrame {
+ /// Normalize finite nonzero orthogonal inputs. An arbitrary oblique tangent is
+ /// refused rather than silently choosing a different brushed direction.
+ /// Roundoff within 1e-10 of perpendicular is removed by orthogonalization.
+ pub fn new(normal: Vec3, tangent: Vec3) -> Result {
+ let normal = unit_direction(normal)?;
+ let tangent = unit_direction(tangent)?;
+ let dot = normal.dot(tangent);
+ if dot.abs() > 1e-10 {
+ return Err(AnisotropicError::Frame);
+ }
+ let tangent = unit_direction(tangent - normal * dot)?;
+ let bitangent = unit_direction(normal.cross(tangent))?;
+ Ok(Self { normal, tangent, bitangent })
+ }
+
+ /// Shading normal, never a replacement for an original geometric normal.
+ pub fn normal(self) -> Vec3 {
+ self.normal
+ }
+
+ /// Visual X axis, associated with the first roughness.
+ pub fn tangent(self) -> Vec3 {
+ self.tangent
+ }
+
+ /// Visual Y axis, associated with the second roughness.
+ pub fn bitangent(self) -> Vec3 {
+ self.bitangent
+ }
+
+ fn local(self, direction: Vec3) -> Vec3 {
+ Vec3::new(self.tangent.dot(direction), self.bitangent.dot(direction), self.normal.dot(direction))
+ }
+
+ fn world(self, local: Vec3) -> Vec3 {
+ self.tangent * local.x + self.bitangent * local.y + self.normal * local.z
+ }
+
+ fn geometric(self, normal: Vec3) -> Result {
+ let normal = unit_direction(normal)?;
+ if normal.dot(self.normal) <= 0.0 {
+ return Err(AnisotropicError::Frame);
+ }
+ Ok(normal)
+ }
+}
+
+/// A bounded opaque response with two perceptual roughness axes in [0.045, 1].
+/// Alpha is roughness squared, matching [`OpaqueSurface`].
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct AnisotropicSurface {
+ base: OpaqueSurface,
+ roughness_y: f64,
+}
+
+/// One reflected **specular-only** NDF sample. Fields are in world coordinates.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct ReflectionSample {
+ /// Outgoing direction, pointing away from the surface.
+ pub direction: Vec3,
+ /// Unconditional density per steradian, without renormalizing null events.
+ pub pdf: f64,
+ /// `specular_brdf * shading_cosine / pdf`, in linear RGB.
+ /// Diffuse response is excluded; its sampling strategy belongs to the consumer.
+ pub weight: Vec3,
+}
+
+impl AnisotropicSurface {
+ /// Linear-sRGB reflectance, metal fraction and IOR use the opaque contract.
+ /// Perfect delta mirrors and out-of-range roughness are refused, not clamped.
+ pub fn new(base_color: Vec3, metallic: f64, roughness_x: f64, roughness_y: f64, dielectric_ior: f64) -> Result {
+ let base = OpaqueSurface::new(base_color, metallic, roughness_x, dielectric_ior)?;
+ if !roughness_y.is_finite() || !(MIN_ROUGHNESS..=1.0).contains(&roughness_y) {
+ return Err(SurfaceError::Roughness.into());
+ }
+ Ok(Self { base, roughness_y })
+ }
+
+ /// Admitted perceptual roughness along visual X and Y.
+ pub fn roughness(self) -> [f64; 2] {
+ [self.base.roughness(), self.roughness_y]
+ }
+
+ fn alpha(self) -> [f64; 2] {
+ [self.base.roughness().powi(2), self.roughness_y.powi(2)]
+ }
+
+ fn fresnel(self, cosine: f64) -> Vec3 {
+ let f0 = self.base.normal_reflectance();
+ f0 + (Vec3::new(1.0, 1.0, 1.0) - f0) * (1.0 - cosine.clamp(0.0, 1.0)).powi(5)
+ }
+
+ fn distribution_local(self, h: Vec3) -> f64 {
+ if h.z <= 0.0 {
+ return 0.0;
+ }
+ let [ax, ay] = self.alpha();
+ let q = (h.x / ax).powi(2) + (h.y / ay).powi(2) + h.z * h.z;
+ 1.0 / (PI * ax * ay * q * q)
+ }
+
+ // Smith G1 / cosine, avoiding division by tiny cosines and tan(theta).
+ fn visibility(self, w: Vec3) -> f64 {
+ let [ax, ay] = self.alpha();
+ 2.0 / (w.z + (w.z * w.z + (ax * w.x).powi(2) + (ay * w.y).powi(2)).sqrt())
+ }
+
+ /// GGX normal distribution D, per steradian of microfacet normal.
+ /// This is not a normalized probability density: [`Self::normal_pdf`] is.
+ pub fn distribution(self, frame: VisualFrame, half: Vec3) -> Result {
+ finite_scalar(self.distribution_local(frame.local(unit_direction(half)?)))
+ }
+
+ /// Projected NDF density `D(h) * n.h` on the upper shading hemisphere.
+ /// Its integral over that hemisphere is one.
+ pub fn normal_pdf(self, frame: VisualFrame, half: Vec3) -> Result {
+ let h = frame.local(unit_direction(half)?);
+ finite_scalar(self.distribution_local(h) * h.z.max(0.0))
+ }
+
+ /// Sample the projected NDF by stretching a radial GGX slope distribution.
+ /// The inverse radial CDF is `r = sqrt(u/(1-u))`; homogeneous coordinates
+ /// `(alpha_x*sqrt(u)*cos(phi), alpha_y*sqrt(u)*sin(phi), sqrt(1-u))`
+ /// avoid a large intermediate radius. No heap, rejection loop or RNG is used.
+ pub fn sample_normal(self, frame: VisualFrame, variates: [f64; 2]) -> Result {
+ let [u, azimuth] = variates;
+ if !variates.into_iter().all(|v| v.is_finite() && (0.0..1.0).contains(&v)) {
+ return Err(AnisotropicError::Variates);
+ }
+ let [ax, ay] = self.alpha();
+ let phi = TAU * azimuth;
+ let radial = u.sqrt();
+ let h = unit_direction(Vec3::new(ax * radial * phi.cos(), ay * radial * phi.sin(), (1.0 - u).sqrt()))?;
+ Ok(unit_direction(frame.world(h))?)
+ }
+
+ fn directions(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result