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.
This commit is contained in:
selune authored and GitHub committed 2026-10-23 23:06:31 +02:00
1 parent ac08c3f106
commit ee5ca2430b
4 files changed
+618

No files matched your search

+294
View File
@@ -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,
//! <https://jcgt.org/published/0007/04/01/>. 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<SurfaceError> 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<T> = std::result::Result<T, AnisotropicError>;
/// 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<Self> {
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<Vec3> {
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<Self> {
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<f64> {
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<f64> {
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<Vec3> {
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<Option<(Vec3, Vec3, Vec3)>> {
let geometric = frame.geometric(geometric)?;
let view = unit_direction(view)?;
let light = unit_direction(light)?;
let (v, l) = (frame.local(view), frame.local(light));
if v.z <= 0.0 || l.z <= 0.0 || geometric.dot(view) <= 0.0 || geometric.dot(light) <= 0.0 {
return Ok(None);
}
let h = unit_direction(view + light)?;
Ok(Some((v, l, frame.local(h))))
}
fn specular_local(self, v: Vec3, l: Vec3, h: Vec3) -> Result<Vec3> {
finite_rgb(self.fresnel(v.dot(h)) * (self.distribution_local(h) * 0.25 * self.visibility(v) * self.visibility(l)))
}
/// Specular component only, with independent geometric hemisphere rejection.
/// All input directions point away from the surface.
pub fn specular_brdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<Vec3> {
let Some((v, l, h)) = self.directions(frame, geometric, view, light)? else { return Ok(Vec3::ZERO) };
self.specular_local(v, l, h)
}
/// Full opaque BRDF, including the same symmetric attenuated Lambert term as
/// [`OpaqueSurface`]. No radiance, cosine, exposure or display transform included.
/// Equal roughness axes delegate to the existing isotropic numerical contract.
pub fn brdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<Vec3> {
let Some((v, l, h)) = self.directions(frame, geometric, view, light)? else { return Ok(Vec3::ZERO) };
if self.base.roughness() == self.roughness_y {
return Ok(self.base.brdf(frame.normal, view, light)?);
}
let specular = self.specular_local(v, l, h)?;
let fv = self.fresnel(v.z);
let fl = self.fresnel(l.z);
let diffuse = self.base.base_color() * ((1.0 - self.base.metallic()) / PI);
finite_rgb(
specular
+ Vec3::new(
(1.0 - fv.x) * (1.0 - fl.x) * diffuse.x,
(1.0 - fv.y) * (1.0 - fl.y) * diffuse.y,
(1.0 - fv.z) * (1.0 - fl.z) * diffuse.z,
),
)
}
/// Unconditional reflected-direction density for the specular NDF sampler.
/// Integrates to the acceptance probability, not necessarily one: invalid
/// microfacets and below-geometric/shading-hemisphere reflections are null events.
/// A mixture with a diffuse or environment sampler must use its own mixture PDF.
pub fn reflection_pdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<f64> {
let Some((v, _, h)) = self.directions(frame, geometric, view, light)? else { return Ok(0.0) };
finite_scalar(self.distribution_local(h) * h.z.max(0.0) / (4.0 * v.dot(h).max(0.0)))
}
/// One specular NDF attempt. `None` is a zero-contribution event and must
/// still count towards the consumer's sample denominator. Never retry until
/// success. Ray origins/visibility use the consumer's original geometric data.
pub fn sample_reflection(self, frame: VisualFrame, geometric: Vec3, view: Vec3, variates: [f64; 2]) -> Result<Option<ReflectionSample>> {
let geometric = frame.geometric(geometric)?;
let view = unit_direction(view)?;
let half = self.sample_normal(frame, variates)?;
let v = frame.local(view);
if v.z <= 0.0 || geometric.dot(view) <= 0.0 {
return Ok(None);
}
let vh = view.dot(half);
if vh <= 0.0 {
return Ok(None);
}
let light = unit_direction(half * (2.0 * vh) - view)?;
let l = frame.local(light);
if l.z <= 0.0 || geometric.dot(light) <= 0.0 {
return Ok(None);
}
let h = frame.local(half);
let pdf = self.reflection_pdf(frame, geometric, view, light)?;
if pdf <= 0.0 {
return Err(AnisotropicError::Arithmetic);
}
// Cancel D algebraically in f_spec * cos / pdf. No tiny-cosine division.
let weight = finite_rgb(self.fresnel(vh) * (self.visibility(v) * (self.visibility(l) * l.z) * vh / h.z))?;
Ok(Some(ReflectionSample { direction: light, pdf, weight }))
}
}
fn finite_scalar(value: f64) -> Result<f64> {
if value.is_finite() && value >= 0.0 { Ok(value) } else { Err(AnisotropicError::Arithmetic) }
}
fn finite_rgb(value: Vec3) -> Result<Vec3> {
if value.is_finite() && [value.x, value.y, value.z].into_iter().all(|c| c >= 0.0) { Ok(value) } else { Err(AnisotropicError::Arithmetic) }
}
#[cfg(test)]
#[path = "anisotropic_surface_tests.rs"]
mod tests;
@@ -0,0 +1,277 @@
use super::*;
fn frame() -> VisualFrame {
VisualFrame::new(Vec3::Z, Vec3::X).unwrap()
}
fn surface(rx: f64, ry: f64) -> AnisotropicSurface {
AnisotropicSurface::new(Vec3::new(0.8, 0.5, 0.2), 1.0, rx, ry, 1.5).unwrap()
}
fn close(a: f64, b: f64, tolerance: f64) {
assert!((a - b).abs() <= tolerance * (1.0 + a.abs().max(b.abs())), "{a} != {b}");
}
fn close_rgb(a: Vec3, b: Vec3, tolerance: f64) {
close(a.x, b.x, tolerance);
close(a.y, b.y, tolerance);
close(a.z, b.z, tolerance);
}
fn hemisphere(mu: f64, phi: f64) -> Vec3 {
let radius = (1.0 - mu * mu).sqrt();
Vec3::new(radius * phi.cos(), radius * phi.sin(), mu)
}
#[test]
fn constructor_rejects_hostile_parameters_on_both_axes() {
for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, 0.0, MIN_ROUGHNESS.next_down(), 1.01] {
assert!(AnisotropicSurface::new(Vec3::X, 1.0, bad, 0.5, 1.5).is_err());
assert!(AnisotropicSurface::new(Vec3::X, 1.0, 0.5, bad, 1.5).is_err());
}
for bad in [f64::NAN, f64::INFINITY, -0.1, 1.1] {
assert!(AnisotropicSurface::new(Vec3::new(bad, 0.0, 0.0), 1.0, 0.5, 0.8, 1.5).is_err());
assert!(AnisotropicSurface::new(Vec3::X, bad, 0.5, 0.8, 1.5).is_err());
}
for bad in [f64::NAN, 0.99, 3.01] {
assert!(AnisotropicSurface::new(Vec3::X, 1.0, 0.5, 0.8, bad).is_err());
}
assert_eq!(surface(MIN_ROUGHNESS, 1.0).roughness(), [MIN_ROUGHNESS, 1.0]);
}
#[test]
fn frame_is_right_handed_and_requires_an_explicit_orthogonal_axis() {
let f = VisualFrame::new(Vec3::new(0.0, 0.0, 1e308), Vec3::new(1e-300, 0.0, 0.0)).unwrap();
assert_eq!(f.normal(), Vec3::Z);
assert_eq!(f.tangent(), Vec3::X);
assert_eq!(f.bitangent(), Vec3::Y);
for (n, t) in [(Vec3::ZERO, Vec3::X), (Vec3::Z, Vec3::Z), (Vec3::Z, Vec3::X + Vec3::Z), (Vec3::Z, Vec3::new(f64::NAN, 0.0, 0.0))] {
assert!(VisualFrame::new(n, t).is_err());
}
let tilted = VisualFrame::new(Vec3::new(0.3, 0.4, 1.0), Vec3::new(0.8, -0.6, 0.0)).unwrap();
close(tilted.tangent().dot(tilted.normal()), 0.0, 1e-14);
close_rgb(tilted.tangent().cross(tilted.bitangent()), tilted.normal(), 1e-14);
}
#[test]
fn normal_incidence_matches_independent_ggx_peak() {
let s = surface(0.3, 0.7);
let d = 1.0 / (PI * 0.3_f64.powi(2) * 0.7_f64.powi(2));
close(s.distribution(frame(), Vec3::Z).unwrap(), d, 1e-14);
close(s.normal_pdf(frame(), Vec3::Z).unwrap(), d, 1e-14);
close_rgb(s.brdf(frame(), Vec3::Z, Vec3::Z, Vec3::Z).unwrap(), Vec3::new(0.8, 0.5, 0.2) * (d / 4.0), 1e-14);
}
#[test]
fn isotropic_limit_matches_existing_opaque_contract() {
for r in [MIN_ROUGHNESS, 0.3, 0.7, 1.0] {
for metallic in [0.0, 0.5, 1.0] {
let color = Vec3::new(0.8, 0.5, 0.2);
let a = AnisotropicSurface::new(color, metallic, r, r, 1.5).unwrap();
let opaque = OpaqueSurface::new(color, metallic, r, 1.5).unwrap();
for (v, l) in [(Vec3::Z, Vec3::Z), (Vec3::new(0.4, 0.2, 0.8), Vec3::new(-0.2, 0.7, 0.6))] {
assert_eq!(a.brdf(frame(), Vec3::Z, v, l).unwrap(), opaque.brdf(Vec3::Z, v, l).unwrap());
if metallic == 1.0 {
close_rgb(a.specular_brdf(frame(), Vec3::Z, v, l).unwrap(), opaque.brdf(Vec3::Z, v, l).unwrap(), 1e-10);
}
}
}
}
}
#[test]
fn reciprocal_for_unequal_axes_and_mixed_metal_fraction() {
for metallic in [0.0, 0.4, 1.0] {
let s = AnisotropicSurface::new(Vec3::new(0.8, 0.5, 0.2), metallic, 0.2, 0.9, 2.0).unwrap();
for (v, l) in [(Vec3::new(0.4, 0.1, 1.0), Vec3::new(-0.3, 0.2, 0.8)), (Vec3::new(1.0, 0.0, 1e-300), Vec3::new(-1.0, 0.0, 1e-300))] {
close_rgb(s.brdf(frame(), Vec3::Z, v, l).unwrap(), s.brdf(frame(), Vec3::Z, l, v).unwrap(), 1e-12);
}
}
}
#[test]
fn ninety_degree_visual_rotation_swaps_the_brushed_response() {
let s = surface(0.25, 0.8);
let swapped = surface(0.8, 0.25);
let rotated = VisualFrame::new(Vec3::Z, Vec3::Y).unwrap();
let light = Vec3::new(0.6, 0.0, 0.8);
let initial = s.brdf(frame(), Vec3::Z, Vec3::Z, light).unwrap();
let turned = s.brdf(rotated, Vec3::Z, Vec3::Z, light).unwrap();
assert!((initial - turned).len() > 0.01);
close_rgb(turned, swapped.brdf(frame(), Vec3::Z, Vec3::Z, light).unwrap(), 1e-13);
let h = s.sample_normal(frame(), [0.3, 0.2]).unwrap();
let rotated_h = s.sample_normal(rotated, [0.3, 0.2]).unwrap();
close_rgb(rotated_h, Vec3::new(-h.y, h.x, h.z), 1e-14);
}
#[test]
fn geometric_and_shading_hemispheres_are_independent() {
let shading = VisualFrame::new(Vec3::new(0.8, 0.0, 0.6), Vec3::Y).unwrap();
let light = Vec3::new(0.99, 0.0, -0.1);
let s = surface(0.5, 0.8);
assert!(shading.normal().dot(light) > 0.0);
assert_eq!(s.brdf(shading, Vec3::Z, Vec3::Z, light).unwrap(), Vec3::ZERO);
assert_eq!(s.reflection_pdf(shading, Vec3::Z, Vec3::Z, light).unwrap(), 0.0);
assert!(s.brdf(frame(), -Vec3::Z, Vec3::Z, Vec3::Z).is_err());
assert_eq!(s.brdf(frame(), Vec3::Z, Vec3::Z, Vec3::X).unwrap(), Vec3::ZERO);
assert_eq!(s.brdf(frame(), Vec3::Z, -Vec3::Z, Vec3::Z).unwrap(), Vec3::ZERO);
}
#[test]
fn grazing_and_extreme_finite_direction_magnitudes_remain_finite() {
for (rx, ry) in [(MIN_ROUGHNESS, 1.0), (1.0, MIN_ROUGHNESS), (MIN_ROUGHNESS, MIN_ROUGHNESS)] {
let s = surface(rx, ry);
for (v, l) in [(Vec3::new(1.0, 0.0, 1e-300), Vec3::new(-1.0, 0.0, 1e-300)), (Vec3::new(1e308, 1e308, 1e308), Vec3::new(-1e-300, 0.0, 1e-300))]
{
let b = s.brdf(frame(), Vec3::Z, v, l).unwrap();
assert!(b.is_finite() && b.x >= 0.0 && b.y >= 0.0 && b.z >= 0.0);
}
for u in [0.0, f64::from_bits(1), 0.5, 1.0_f64.next_down()] {
let h = s.sample_normal(frame(), [u, 0.5]).unwrap();
assert!(h.is_finite() && h.z > 0.0);
assert!(s.normal_pdf(frame(), h).unwrap().is_finite());
}
let view = Vec3::new(1.0, 0.0, 1e-300);
let sample = s.sample_reflection(frame(), Vec3::Z, view, [0.0, 0.0]).unwrap().unwrap();
assert!(sample.pdf.is_finite() && sample.pdf > 0.0 && sample.weight.is_finite());
// A mathematical density beyond f64 is a typed refusal, never clamped.
assert_eq!(s.sample_reflection(frame(), Vec3::Z, Vec3::new(1.0, 0.0, f64::from_bits(1)), [0.0, 0.0]), Err(AnisotropicError::Arithmetic));
}
}
#[test]
fn malformed_directions_and_variates_fail_without_clamping() {
let s = surface(0.5, 0.8);
for bad in [Vec3::ZERO, Vec3::new(f64::NAN, 0.0, 1.0), Vec3::new(f64::INFINITY, 0.0, 1.0)] {
assert!(s.brdf(frame(), Vec3::Z, bad, Vec3::Z).is_err());
assert!(s.brdf(frame(), bad, Vec3::Z, Vec3::Z).is_err());
assert!(s.brdf(frame(), Vec3::Z, Vec3::Z, bad).is_err());
assert!(s.normal_pdf(frame(), bad).is_err());
}
for bad in [-0.1, 1.0, f64::NAN, f64::INFINITY] {
assert!(s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [bad, 0.5]).is_err());
assert!(s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [0.5, bad]).is_err());
}
}
#[test]
fn sampled_slopes_follow_the_independent_inverse_radial_cdf() {
let s = surface(0.3, 0.7);
for u in [0.0, 0.01, 0.3, 0.8, 0.9999] {
for azimuth in [0.0, 0.2, 0.5, 0.8] {
let h = s.sample_normal(frame(), [u, azimuth]).unwrap();
let sx = h.x / (0.3_f64.powi(2) * h.z);
let sy = h.y / (0.7_f64.powi(2) * h.z);
let radius2 = sx * sx + sy * sy;
close(radius2 / (1.0 + radius2), u, 1e-13);
close_rgb(h, s.sample_normal(frame(), [u, azimuth]).unwrap(), 0.0);
}
}
}
#[test]
fn reflection_samples_match_pdf_and_specular_throughput() {
let s = surface(0.4, 0.8);
let view = unit_direction(Vec3::new(0.2, 0.3, 1.0)).unwrap();
let mut accepted = 0;
let mut null = 0;
for i in 0..32 {
for j in 0..32 {
let uv = [(i as f64 + 0.5) / 32.0, (j as f64 + 0.5) / 32.0];
match s.sample_reflection(frame(), Vec3::Z, view, uv).unwrap() {
Some(sample) => {
accepted += 1;
close(sample.pdf, s.reflection_pdf(frame(), Vec3::Z, view, sample.direction).unwrap(), 1e-13);
let expected = s.specular_brdf(frame(), Vec3::Z, view, sample.direction).unwrap() * (sample.direction.z / sample.pdf);
close_rgb(sample.weight, expected, 1e-10);
}
None => null += 1,
}
}
}
assert!(accepted > 0 && null > 0);
assert_eq!(accepted + null, 1024);
}
#[test]
fn unit_roughness_normal_view_has_half_null_mass_and_uniform_reflection_pdf() {
let s = surface(1.0, 1.0);
assert!(s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [0.75, 0.3]).unwrap().is_none());
let sample = s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [0.25, 0.3]).unwrap().unwrap();
close(sample.pdf, 1.0 / (4.0 * PI), 1e-14);
let mut accepted = 0;
for i in 0..1024 {
accepted += usize::from(s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [(i as f64 + 0.5) / 1024.0, 0.3]).unwrap().is_some());
}
assert_eq!(accepted, 512);
// p(l)=1/(4*pi) over the upper hemisphere: valid mass exactly1/2.
close(s.reflection_pdf(frame(), Vec3::Z, Vec3::Z, Vec3::Z).unwrap() * (2.0 * PI), 0.5, 1e-14);
assert_eq!(s.reflection_pdf(frame(), Vec3::Z, Vec3::Z, -Vec3::Z).unwrap(), 0.0);
}
#[test]
fn invisible_microfacets_are_null_and_weights_exclude_the_diffuse_substrate() {
let s = AnisotropicSurface::new(Vec3::new(0.8, 0.5, 0.2), 0.0, 1.0, 1.0, 1.5).unwrap();
let view = unit_direction(Vec3::new(0.99, 0.0, 0.1)).unwrap();
assert!(s.sample_reflection(frame(), Vec3::Z, view, [0.9, 0.5]).unwrap().is_none());
let sample = s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [0.1, 0.2]).unwrap().unwrap();
let scale = sample.direction.z / sample.pdf;
let specular = s.specular_brdf(frame(), Vec3::Z, Vec3::Z, sample.direction).unwrap() * scale;
let total = s.brdf(frame(), Vec3::Z, Vec3::Z, sample.direction).unwrap() * scale;
close_rgb(sample.weight, specular, 1e-13);
assert!(total.x > sample.weight.x + 0.1);
assert_eq!(s.normal_pdf(frame(), -Vec3::Z).unwrap(), 0.0);
assert_eq!(s.normal_pdf(frame(), Vec3::X).unwrap(), 0.0);
}
#[test]
fn quadrature_distinguishes_normal_pdf_mass_from_valid_reflection_mass() {
// Finite midpoint grids resolve these broad lobes only. Narrowest admitted
// roughness is tested analytically and with inverse-CDF samples elsewhere.
const N: usize = 256;
for (rx, ry) in [(1.0, 1.0), (0.6, 0.9)] {
let s = surface(rx, ry);
let mut normal_mass = 0.0;
let mut valid_mass = 0.0;
let mut accepted = 0;
for i in 0..N {
for j in 0..N {
let u = (i as f64 + 0.5) / N as f64;
let azimuth = (j as f64 + 0.5) / N as f64;
let l = hemisphere(u, TAU * azimuth);
normal_mass += s.normal_pdf(frame(), l).unwrap();
valid_mass += s.reflection_pdf(frame(), Vec3::Z, Vec3::Z, l).unwrap();
accepted += usize::from(s.sample_reflection(frame(), Vec3::Z, Vec3::Z, [u, azimuth]).unwrap().is_some());
}
}
let domega = TAU / (N * N) as f64;
close(normal_mass * domega, 1.0, 0.001);
close(valid_mass * domega, accepted as f64 / (N * N) as f64, 0.003);
assert!(valid_mass * domega < 1.0);
}
}
#[test]
fn broad_lobe_importance_estimate_agrees_with_integrated_energy() {
// White metal, normal view, deterministic256² grids. A scoped consistency
// check, not universal energy certification or a variance/convergence claim.
const N: usize = 256;
let s = AnisotropicSurface::new(Vec3::new(1.0, 1.0, 1.0), 1.0, 0.6, 0.9, 1.5).unwrap();
let mut integrated = Vec3::ZERO;
let mut sampled = Vec3::ZERO;
for i in 0..N {
for j in 0..N {
let uv = [(i as f64 + 0.5) / N as f64, (j as f64 + 0.5) / N as f64];
let light = hemisphere(uv[0], TAU * uv[1]);
integrated += s.specular_brdf(frame(), Vec3::Z, Vec3::Z, light).unwrap() * light.z;
if let Some(sample) = s.sample_reflection(frame(), Vec3::Z, Vec3::Z, uv).unwrap() {
sampled += sample.weight;
}
}
}
integrated = integrated * (TAU / (N * N) as f64);
sampled = sampled / (N * N) as f64; // Includes ALL null attempts.
assert!(integrated.x > 0.0 && integrated.x <= 1.001);
assert!(sampled.x > 0.0 && sampled.x <= 1.001);
close_rgb(integrated, sampled, 0.003);
}
+1
View File
@@ -5,6 +5,7 @@
#![forbid(unsafe_code)]
mod analysis;
pub mod anisotropic_surface;
mod backend;
mod camera;
pub mod clear_coat;
+46
View File
@@ -0,0 +1,46 @@
# Anisotropic GGX numerical core
`render::anisotropic_surface` supplies the independent optical core tracked in
#1694/#1699. This constituent extracts the original source and analytic tests
already published in #1698 at `463a3e0daaa6b84f169ba5f8f215fba4642c194a`.
It adds no renderer registration, saved field, command, device dependency or
engineering-material assignment. Runtime consumers remain separate work.
## Contract
`VisualFrame::new` admits finite, nonzero, perpendicular normal/tangent inputs,
normalizes them, and constructs a right-handed visual frame. This is not a physical
material-axis assignment. An original geometric normal is supplied separately;
response and reflected samples reject either hemisphere when appropriate.
Both perceptual roughness axes use the opaque surface range `[0.045, 1]`; alpha is
roughness squared. Linear-sRGB reflectance, metal fraction and dielectric IOR use
the existing `OpaqueSurface` admission. Invalid data is refused, not clamped.
Equal roughness axes preserve the isotropic opaque BRDF contract exactly.
Sampling uses the projected **normal distribution (NDF)**, not a visible-normal
sampler. `normal_pdf` is `D(h) * n.h`; the unconditional reflected-direction PDF
includes the `1 / (4 * v.h)` Jacobian. A rejected microfacet is a null event that
must remain in the sample denominator. Never retry until a sample succeeds.
Reflection weights contain the specular component only. Diffuse/environment
mixtures, visibility, ray spawning, image budgets and multiple scattering belong
to the consumer; this module does not claim to implement them.
The implementation is original Rust using elementary GGX/Smith/Schlick equations.
The public mathematical reference is Heitz, JCGT 7(4), 2018, equations 1 and 2:
https://jcgt.org/published/0007/04/01/. No external implementation was adapted.
## Reproduce the focused checks
```sh
cargo test --profile ci -p solidcraft-render --lib anisotropic_surface
cargo clippy --profile ci -p solidcraft-render --all-targets -- -D warnings
cargo check --target wasm32-unknown-unknown -p solidcraft-render
```
Analytic and deterministic quadrature tests cover hostile inputs, orthonormality,
normal-incidence peaks, isotropic equivalence, reciprocity, 90-degree visual-axis
rotation, geometric/shading hemisphere separation, grazing directions, inverse-CDF
sampling, PDF/throughput agreement and retained null-event mass. Broad-lobe energy
checks are scoped consistency tests, not universal energy certification, measured
material data or evidence of an integrated rendered image.