reze-engine 0.25.1 → 0.26.0

package/dist/shaders/passes/outline.js

@@ -1,11 +1,24 @@
-// MMD-style screen-space outline via normal-extrusion in clip space.
-// Aspect-compensated so pixel thickness stays stable across viewport sizes.
+// MMD-style inverted-hull outline, ported from babylon-mmd's mmdOutline shader
+// (the reference implementation whose output matches MMD):
+//   1. Extrude along the VIEW-SPACE normal's XY, normalized — a pure screen
+//      direction, so rims never smear toward the camera at grazing angles.
+//   2. Offset in clip space by edgeSize · 4/viewport · w. The ×w cancels the
+//      perspective divide → CONSTANT screen thickness of exactly
+//      2·edgeSize device pixels (babylon: `screenNormal / (viewport*0.25) *
+//      offset * projectedPosition.w`). PMX edgeSize ~0.3–1.0 ⇒ fine 0.6–2px
+//      rims, matching MMD instead of our former chunky constants.
+//   3. The FRAGMENT stage samples the material's own diffuse texture and
+//      MODULATES the rim's alpha by it (discarding only near-zero cut-out
+//      margins) — sheer fabric gets a proportional rim, never a solid black
+//      hull, without dropping the author's edge flag.
 export const OUTLINE_SHADER_WGSL = /* wgsl */ `
 struct CameraUniforms {
   view: mat4x4f,
   projection: mat4x4f,
   viewPos: vec3f,
-  _padding: f32,
+  // Render-target height in device pixels (engine writes it each frame);
+  // width is recovered via the projection matrix's aspect.
+  viewportHeight: f32,
 };
 
 struct MaterialUniforms {
@@ -17,16 +30,20 @@ struct MaterialUniforms {
 };
 
 @group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var edgeSampler: sampler;
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
 @group(2) @binding(0) var<uniform> material: MaterialUniforms;
+@group(2) @binding(1) var diffuseTexture: texture_2d<f32>;
 
 struct VertexOutput {
   @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
 };
 
 @vertex fn vs(
   @location(0) position: vec3f,
   @location(1) normal: vec3f,
+  @location(2) uv: vec2f,
   @location(3) joints0: vec4<u32>,
   @location(4) weights0: vec4<f32>
 ) -> VertexOutput {
@@ -50,33 +67,43 @@ struct VertexOutput {
   let worldPos = skinnedPos.xyz;
   let worldNormal = normalize(skinnedNrm);
 
-  // Screen-space outline extrusion — MMD-style pixel-stable edge line.
-  // 1. Project position and normal-as-direction to clip space.
-  // 2. Normalize the 2D clip-space normal, aspect-compensated so "one pixel horizontally"
-  //    matches "one pixel vertically" (otherwise wide viewports squash the outline in X).
-  // 3. Offset clip-space xy by (normal * edgeSize * edgeScale), then multiply by w
-  //    so the perspective divide cancels out → offset stays constant in NDC regardless
-  //    of depth, matching how MMD / babylon-mmd style outlines look identical when zooming.
-  // 4. edgeScale is in NDC-y units per PMX edgeSize. ≈ 0.006 gives ~3px at 1080p; it's
-  //    tied to viewport HEIGHT so resizing the window keeps pixel thickness stable.
-  let viewProj = camera.projection * camera.view;
-  let clipPos = viewProj * vec4f(worldPos, 1.0);
-  let clipNormal = (viewProj * vec4f(worldNormal, 0.0)).xy;
-  // projection is column-major: proj[0][0] = 1/(aspect·tan(fov/2)), proj[1][1] = 1/tan(fov/2).
-  // Ratio proj[1][1]/proj[0][0] recovers the viewport aspect (width/height).
+  let clipPos = camera.projection * camera.view * vec4f(worldPos, 1.0);
+
+  // babylon-mmd: screenNormal = normalize((view * worldNormal).xy)
+  let viewNormal = (camera.view * vec4f(worldNormal, 0.0)).xyz;
+  let snLen = length(viewNormal.xy);
+  let screenNormal = select(vec2f(0.0, 0.0), viewNormal.xy / snLen, snLen > 1e-5);
+
+  // Reference-height normalization (babylon-mmd ships this variant commented
+  // out as \`renderHeight = 1080\`): thickness is a constant FRACTION of the
+  // frame — 2·edgeSize px at 1080p — so retina DPR and 4K export don't thin
+  // the rims to sub-pixel. Width follows the projection aspect.
+  // projection[1][1]/projection[0][0] = width/height for a symmetric frustum.
   let aspect = camera.projection[1][1] / camera.projection[0][0];
-  let pixelDir = normalize(vec2f(clipNormal.x * aspect, clipNormal.y));
-  let ndcDir = vec2f(pixelDir.x / aspect, pixelDir.y);
-  let edgeScale = 0.0016;
-  let offset = ndcDir * material.edgeSize * edgeScale * clipPos.w;
+  let viewport = vec2f(1080.0 * aspect, 1080.0);
+
+  // NDC offset = edgeSize · 4/viewport, ×w so the perspective divide cancels:
+  // constant screen thickness at any distance (babylon-mmd parity).
+  let offset = screenNormal * (material.edgeSize * 4.0 / viewport) * clipPos.w;
   output.position = vec4f(clipPos.xy + offset, clipPos.z, clipPos.w);
+  output.uv = uv;
   return output;
 }
 
 struct FSOut { @location(0) color: vec4f, @location(1) mask: vec4f };
-@fragment fn fs() -> FSOut {
+@fragment fn fs(input: VertexOutput) -> FSOut {
+  // Rim alpha FOLLOWS the fabric's texture alpha instead of a hard alpha test:
+  // MMD draws blend-material edges solid (only cutout materials alpha-test), so
+  // a 0.4 discard erased the whole hull on semi-transparent cloth — stockinged
+  // legs crossing lost their outline entirely. Modulating instead keeps a
+  // proportional rim on sheer weave (never a solid black hull) and still
+  // discards true cut-out margins like hair-card borders.
+  let texA = textureSample(diffuseTexture, edgeSampler, input.uv).a;
+  if (texA < 0.05) {
+    discard;
+  }
   var out: FSOut;
-  out.color = material.edgeColor;
+  out.color = vec4f(material.edgeColor.rgb, material.edgeColor.a * texA);
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "reze-engine",
-    "version": "0.25.1",
+    "version": "0.26.0",
     "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -173,7 +173,7 @@ type GroupInstall = {
   renderClass: RenderClass
   alphaMode: AlphaMode
   pipeline: GPURenderPipeline
-  /** Depth-write-off twin, used when this group's material draws in the transparent bucket. */
+  /** Depth-write-off twin — dormant, kept for a future OIT path. */
   pipelineNoDepthWrite: GPURenderPipeline
   /** hair render-class only: the stencil-matched IS_OVER_EYES=true variant. */
   overEyesPipeline?: GPURenderPipeline
@@ -283,6 +283,34 @@ export const DEFAULT_VIEW_TRANSFORM: ViewTransformOptions = {
   look: "medium_high_contrast",
 }
 
+/** Color grading applied to the tonemapped scene (ASC CDL — see grade() in
+ *  composite.ts). The three tonal controls are expressed as COLORS with
+ *  mid-gray (0.5, 0.5, 0.5) as neutral: the direction from neutral is the hue
+ *  you push toward, and the distance from neutral is the amount — so no
+ *  separate strength slider is needed. Display-space sRGB, since grading runs
+ *  after the view transform. */
+export type ColorGradingOptions = {
+  /** Lifts/tints the dark end (CDL offset). */
+  shadows: Vec3
+  /** Bends the midtones (CDL power) — brighter above neutral, darker below. */
+  midtones: Vec3
+  /** Scales/tints the bright end (CDL slope). */
+  highlights: Vec3
+  /** Contrast about the 0.5 display pivot. 1 = neutral. */
+  contrast: number
+  /** 1 = neutral, 0 = grayscale, >1 = punchier. */
+  saturation: number
+}
+
+const NEUTRAL_GRADE_CHANNEL = 0.5
+export const DEFAULT_COLOR_GRADING: ColorGradingOptions = {
+  shadows: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  midtones: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  highlights: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+  contrast: 1,
+  saturation: 1,
+}
+
 export type GizmoDragKind = "rotate" | "translate"
 
 export interface GizmoDragEvent {
@@ -359,6 +387,10 @@ interface DrawCall {
   baseBindGroupEntries?: GPUBindGroupEntry[]
   /** Material draws only: false = excluded from the shadow map (fully sheer). */
   castsShadow?: boolean
+  /** Edge-flagged materials: interleaved inverted-hull outline drawn right after
+   *  this material with the outline pipeline. Shares this call's index range;
+   *  own bind group (edge uniforms + diffuse texture for the alpha test). */
+  outline?: { bindGroup: GPUBindGroup }
 }
 
 interface PickDrawCall {
@@ -456,14 +488,10 @@ function buildAlphaSampler(
 /** Texture-alpha statistics over ≤400 of the material's triangle centroids:
  *  `avg` (0..1) and `translucentFrac` — the fraction of samples that are
  *  neither fully opaque nor fully cut out (alpha in ~0.03..0.97). Together
- *  they classify two distinct things:
- *    sheer   (avg low)            — a veil: mostly see-through everywhere
- *    partial (translucentFrac up) — mostly-opaque cloth with sheer REGIONS,
- *                                   e.g. a lace skirt panel
- *  Both route to the transparent bucket; only `sheer` is excluded from the
- *  shadow map and outline pass. */
+ *   Bucketing itself is binary (babylon-mmd parity): ANY translucent coverage
+ *  routes to the alpha-blend bucket. `avg` below this threshold additionally
+ *  marks a material as fully sheer (a veil), which vetoes shadow casting. */
 const SHEER_ALPHA_THRESHOLD = 0.7
-const PARTIAL_TRANSLUCENT_FRAC = 0.15
 function materialAlphaStats(
   verts: Float32Array,
   indices: Uint32Array,
@@ -651,7 +679,7 @@ export class Engine {
   private compositeBindGroup!: GPUBindGroup
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  private readonly compositeUniformData = new Float32Array(28)
+  private readonly compositeUniformData = new Float32Array(40)
   /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
   private backgroundColor: Vec3 | null = null
   // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
@@ -861,6 +889,42 @@ export class Engine {
     return { exposure: v.exposure, gamma: v.gamma, look: v.look }
   }
 
+  private colorGrading: ColorGradingOptions = {
+    shadows: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    midtones: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    highlights: new Vec3(NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL, NEUTRAL_GRADE_CHANNEL),
+    contrast: DEFAULT_COLOR_GRADING.contrast,
+    saturation: DEFAULT_COLOR_GRADING.saturation,
+  }
+
+  /**
+   * Color-grade the tonemapped scene (ASC CDL slope/offset/power + saturation).
+   * The background layer is deliberately left ungraded — see the call site in
+   * composite.ts. Uniforms-only: no pipeline rebuild, safe to call per frame
+   * (e.g. from a slider drag).
+   */
+  setColorGrading(patch: Partial<ColorGradingOptions>): void {
+    const g = this.colorGrading
+    if (patch.shadows) g.shadows = new Vec3(patch.shadows.x, patch.shadows.y, patch.shadows.z)
+    if (patch.midtones) g.midtones = new Vec3(patch.midtones.x, patch.midtones.y, patch.midtones.z)
+    if (patch.highlights) g.highlights = new Vec3(patch.highlights.x, patch.highlights.y, patch.highlights.z)
+    if (patch.contrast !== undefined) g.contrast = patch.contrast
+    if (patch.saturation !== undefined) g.saturation = patch.saturation
+    if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
+  }
+
+  /** Current grade (for serialization into a scene descriptor). */
+  getColorGrading(): ColorGradingOptions {
+    const g = this.colorGrading
+    return {
+      shadows: new Vec3(g.shadows.x, g.shadows.y, g.shadows.z),
+      midtones: new Vec3(g.midtones.x, g.midtones.y, g.midtones.z),
+      highlights: new Vec3(g.highlights.x, g.highlights.y, g.highlights.z),
+      contrast: g.contrast,
+      saturation: g.saturation,
+    }
+  }
+
   setViewTransformOptions(patch: Partial<ViewTransformOptions>): void {
     const v = this.viewTransform
     if (patch.exposure !== undefined) v.exposure = patch.exposure
@@ -901,6 +965,32 @@ export class Engine {
     u[25] = this.backgroundEffect ? 1 : 0
     u[26] = this.canvas.width
     u[27] = this.canvas.height
+    // ── Grade (viewU[7..9]) ── The UI's three tonal COLORS map to ASC CDL here,
+    // on the CPU, so the shader only ever sees slope/offset/power. Mid-gray is
+    // neutral in all three; the signed distance from it is the amount.
+    const g = this.colorGrading
+    const off = (c: number) => (c - NEUTRAL_GRADE_CHANNEL) * 0.5 // ±0.25 lift
+    // power < 1 brightens, so midtones ABOVE neutral must lower the exponent.
+    const pow_ = (c: number) => Math.max(0.05, 1 - (c - NEUTRAL_GRADE_CHANNEL) * 1.5)
+    const slope = (c: number) => Math.max(0, 1 + (c - NEUTRAL_GRADE_CHANNEL) * 1.5)
+    u[28] = off(g.shadows.x)
+    u[29] = off(g.shadows.y)
+    u[30] = off(g.shadows.z)
+    u[31] = g.contrast
+    u[32] = pow_(g.midtones.x)
+    u[33] = pow_(g.midtones.y)
+    u[34] = pow_(g.midtones.z)
+    u[35] = g.saturation
+    u[36] = slope(g.highlights.x)
+    u[37] = slope(g.highlights.y)
+    u[38] = slope(g.highlights.z)
+    // Neutral grade → flag off, so the default pipeline pays nothing per pixel.
+    const neutral =
+      u[28] === 0 && u[29] === 0 && u[30] === 0 &&
+      u[32] === 1 && u[33] === 1 && u[34] === 1 &&
+      u[36] === 1 && u[37] === 1 && u[38] === 1 &&
+      g.contrast === 1 && g.saturation === 1
+    u[39] = neutral ? 0 : 1
     this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
   }
 
@@ -917,7 +1007,12 @@ export class Engine {
   }
 
   /** Debug/diagnostic: skip every inverted-hull outline draw. */
-  private outlineEnabled = true
+  // OFF by default — the product aesthetic. Modern high-detail models read
+  // better without hulls (babylon-mmd's own demos disable its outline renderer
+  // too), and no hull pass means no depth-tie edge cases against near-coplanar
+  // cloth. The full MMD-faithful machinery (interleaved per-material hulls,
+  // texture-alpha-modulated rims) stays in place behind setOutlineEnabled(true).
+  private outlineEnabled = false
   setOutlineEnabled(on: boolean): void {
     this.outlineEnabled = on
   }
@@ -1493,6 +1588,8 @@ export class Engine {
         attributes: [
           { shaderLocation: 0, offset: 0, format: "float32x3" as GPUVertexFormat },
           { shaderLocation: 1, offset: 3 * 4, format: "float32x3" as GPUVertexFormat },
+          // uv — the outline FS alpha-tests the diffuse texture (babylon-mmd parity)
+          { shaderLocation: 2, offset: 6 * 4, format: "float32x2" as GPUVertexFormat },
         ],
       },
       {
@@ -1758,6 +1855,7 @@ export class Engine {
       label: "outline per-frame bind group layout",
       entries: [
         { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
       ],
     })
     // Outline per-instance reuses mainPerInstanceBindGroupLayout (same skinMats binding)
@@ -1765,6 +1863,7 @@ export class Engine {
       label: "outline per-material bind group layout",
       entries: [
         { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
       ],
     })
 
@@ -1780,7 +1879,10 @@ export class Engine {
     this.outlinePerFrameBindGroup = this.device.createBindGroup({
       label: "outline per-frame bind group",
       layout: this.outlinePerFrameBindGroupLayout,
-      entries: [{ binding: 0, resource: { buffer: this.cameraUniformBuffer } }],
+      entries: [
+        { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+        { binding: 1, resource: this.materialSampler },
+      ],
     })
 
     const outlineShaderModule = this.device.createShaderModule({
@@ -1797,8 +1899,10 @@ export class Engine {
       cullMode: "back",
       depthStencil: {
         format: "depth24plus-stencil8",
-        // Don’t write outline into depth buffer — stops z-fighting / black cracks vs body (MMD-style; body depth stays authoritative)
-        depthWriteEnabled: false,
+        // babylon-mmd draws outlines WITH depth write (its _afterRenderingMesh
+        // forces setDepthWrite(true)); the constant bias below still makes
+        // hulls lose depth ties against their own near-coplanar geometry.
+        depthWriteEnabled: true,
         depthCompare: "less-equal",
         // CONFIRMED fix (bisected live via setOutlineEnabled): hull fragments
         // carry their surface's exact depth, so against this model's paired
@@ -1991,10 +2095,11 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      // 7 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // 10 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
-      // (time, _, canvas width, canvas height) for user background effects.
-      size: 112,
+      // (time, _, canvas width, canvas height) for user background effects ·
+      // three grade vectors (CDL offset+contrast, power+saturation, slope+flag).
+      size: 160,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.bgParamsDummyBuffer = this.device.createBuffer({
@@ -3555,28 +3660,26 @@ export class Engine {
       }
 
       const materialAlpha = mat.diffuse[3]
-      // Transparent bucket when the MATERIAL says so — or when the TEXTURE does
-      // (sheer cloth almost always ships with diffuse alpha 1.0 and carries its
-      // translucency in texture alpha). Transparent-bucket draws happen after
-      // the opaque bucket (and after the late-drawn hair render-class), so a
-      // veil composites over the hair behind it instead of depth-rejecting it;
-      // they are also excluded from the shadow map, so sheer cloth stops
-      // casting the solid shadow of an opaque sheet.
       const diffusePath = texLogicalPath(mat.diffuseTextureIndex)
       const alphaSampler = diffusePath ? this.textureAlphaCache.get(diffusePath) : null
       const stats = materialAlphaStats(meshVertices, meshIndices, currentIndexOffset, indexCount, alphaSampler)
+      // babylon-mmd parity (its default DepthWriteAlphaBlendingWithEvaluation
+      // method): the bucket decision is BINARY. A material with ANY translucent
+      // texels on its geometry is alpha-blend — drawn in PMX author order with
+      // depth write ON (forceDepthWrite); everything else is opaque. The old
+      // avg/frac tier system left mostly-opaque lace (translucentFrac 0.09) in
+      // the opaque bucket while its sibling panels went transparent, breaking
+      // the author's compositing order — the gray fold patches. The 2% floor
+      // only guards against centroid-sampling noise on genuinely solid cloth.
       const sheer = stats.avg < SHEER_ALPHA_THRESHOLD
-      const partial = !sheer && stats.translucentFrac > PARTIAL_TRANSLUCENT_FRAC
-      // Transparent bucket: drawn after the opaque bucket (and hair) with depth
-      // WRITE OFF, so a lace panel folded in front of itself blends both layers
-      // consistently instead of a triangle-order patchwork of single/double
-      // coverage. Partial-sheer cloth still casts shadows and keeps its outline;
-      // fully sheer cloth (veil) does neither.
-      const isTransparent = materialAlpha < 1.0 - 0.001 || sheer || partial
+      const isTransparent = materialAlpha < 1.0 - 0.001 || sheer || stats.translucentFrac > 0.02
+      // Shadow casting: the PMX author's own flag (bit 0x04, cast self-shadow),
+      // still vetoed for fully sheer cloth — a veil must not cast a solid sheet.
+      const castsShadow = (mat.edgeFlag & 0x04) !== 0 && !sheer
       // Load-time classification log — one line per material, cheap and
-      // invaluable when a model renders wrong (bucket/outline/sheer disputes).
+      // invaluable when a model renders wrong (bucket/outline/shadow disputes).
       console.info(
-        `[reze] ${mat.name}: alpha=${materialAlpha.toFixed(2)} avg=${stats.avg.toFixed(2)} sheerFrac=${stats.translucentFrac.toFixed(2)} ${sheer ? "SHEER" : partial ? "PARTIAL" : "opaque"} bucket=${isTransparent ? "transparent" : "opaque"} edge=${(mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 ? (sheer ? "skipped(sheer)" : "on") : "off"}`,
+        `[reze] ${mat.name}: alpha=${materialAlpha.toFixed(2)} avg=${stats.avg.toFixed(2)} translucentFrac=${stats.translucentFrac.toFixed(2)} bucket=${isTransparent ? "transparent" : "opaque"} castsShadow=${castsShadow} edge=${(mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 ? "on" : "off"}`,
       )
 
       // Sphere map (sph=1 multiply / spa=2 add). Mode 3 (sub-texture UV) is
@@ -3615,24 +3718,13 @@ export class Engine {
         this.zeroStyleBuffer,
       )
 
-      const type: DrawCallType = isTransparent ? "transparent" : "opaque"
-      inst.drawCalls.push({
-        type,
-        count: indexCount,
-        firstIndex: currentIndexOffset,
-        bindGroup,
-        materialName: mat.name,
-        groupId: null,
-        baseBindGroupEntries,
-        castsShadow: !sheer,
-      })
-
-      // No inverted-hull outline for SHEER materials: the outline shader draws a
-      // solid edgeColor silhouette (it never samples texture alpha), so a
-      // see-through veil dragged a near-black hull over the cloth behind it —
-      // broken black shapes that waved with physics and flickered with camera
-      // angle. A solid rim on see-through fabric is wrong in principle.
-      if ((mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0 && !sheer) {
+      // Inverted-hull outline for EVERY edge-flagged material (PMX bit 0x10) —
+      // the outline FS alpha-tests the diffuse texture, so sheer fabric masks
+      // its own hull where it is see-through instead of us skipping it here.
+      // Drawn interleaved right after this material's color draw (babylon-mmd's
+      // per-mesh afterRender outline stage) — see drawMaterials.
+      let outline: DrawCall["outline"]
+      if ((mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0) {
         const materialUniformData = new Float32Array([
           mat.edgeColor[0],
           mat.edgeColor[1],
@@ -3648,19 +3740,27 @@ export class Engine {
         const outlineBindGroup = this.device.createBindGroup({
           label: `${prefix}outline: ${mat.name}`,
           layout: this.outlinePerMaterialBindGroupLayout,
-          entries: [{ binding: 0, resource: { buffer: outlineUniformBuffer } }],
-        })
-        const outlineType: DrawCallType = isTransparent ? "transparent-outline" : "opaque-outline"
-        inst.drawCalls.push({
-          type: outlineType,
-          count: indexCount,
-          firstIndex: currentIndexOffset,
-          bindGroup: outlineBindGroup,
-          materialName: mat.name,
-          groupId: null,
+          entries: [
+            { binding: 0, resource: { buffer: outlineUniformBuffer } },
+            { binding: 1, resource: textureView },
+          ],
         })
+        outline = { bindGroup: outlineBindGroup }
       }
 
+      const type: DrawCallType = isTransparent ? "transparent" : "opaque"
+      inst.drawCalls.push({
+        type,
+        count: indexCount,
+        firstIndex: currentIndexOffset,
+        bindGroup,
+        materialName: mat.name,
+        groupId: null,
+        baseBindGroupEntries,
+        castsShadow,
+        outline,
+      })
+
       if (this.onRaycast) {
         const pickIdData = new Float32Array([modelId, materialId, 0, 0])
         const pickIdBuffer = this.createUniformBuffer(`${prefix}pick: ${mat.name}`, pickIdData)
@@ -4509,11 +4609,22 @@ export class Engine {
     }
 
     const pass = encoder.beginRenderPass(this.renderPassDescriptor)
+    // Phase order: opaque models → ground → transparent fabric.
+    // The ground shader is the most expensive full-coverage draw in the frame
+    // (9-tap PCF on the 4096² shadow map per pixel), so it draws AFTER the
+    // opaque phase to get early-z rejected behind the body — drawing it first
+    // shaded every covered pixel and measurably dropped Safari fps. It still
+    // draws BEFORE the transparent phase so sheer fabric blends over the floor
+    // instead of over the background with the floor depth-rejected behind it.
     if (hasModels)
       this.forEachInstance((inst) => {
-        if (inst.model.visible) this.renderOneModel(pass, inst)
+        if (inst.model.visible) this.renderModelOpaquePhase(pass, inst)
       })
     if (this.hasGround) this.renderGround(pass)
+    if (hasModels)
+      this.forEachInstance((inst) => {
+        if (inst.model.visible) this.renderModelTransparentPhase(pass, inst)
+      })
     pass.end()
 
     // Bloom pyramid (EEVEE 3.6):
@@ -4805,8 +4916,7 @@ export class Engine {
     let overEyesPipeline: GPURenderPipeline | undefined
     try {
       pipeline = await this.createRenderClassPipeline(renderClass, module, false)
-      // Transparent-bucket draws don't write depth (self-overlap must blend, not
-      // patchwork) — same shading, different depth state.
+      // Dormant OIT twin — kept for a future order-independent-transparency path.
       pipelineNoDepthWrite = await this.createRenderClassPipeline(renderClass, module, false, false)
       if (renderClass === "hair") overEyesPipeline = await this.createRenderClassPipeline(renderClass, module, true)
     } catch (e) {
@@ -4966,14 +5076,10 @@ export class Engine {
   }
 
   // Pipeline for a material draw call: its group's compiled pipeline when grouped, else
-  // the neutral base (ungrouped materials render the default graph).
+  // the neutral base (ungrouped materials render the default graph). Transparent-bucket
+  // draws use the SAME depth-write-on pipeline — babylon-mmd's forceDepthWrite
+  // blending (see renderModelTransparentPhase for the trade-off record).
   private pipelineForDrawCall(inst: ModelInstance, dc: DrawCall): GPURenderPipeline {
-    // Transparent draws WRITE depth — MMD semantics: PMX triangle/material order
-    // is the author's compositing order, and a fold HIDES its far side rather
-    // than blending it (the far side shades dark — light-averted — so letting it
-    // show through read as gray fold-shaped stains; depth-write-off made every
-    // fold do that). The no-write twins stay available for a future true-OIT
-    // path but are deliberately unused.
     if (dc.groupId) {
       const install = inst.styleGroups.get(dc.groupId)
       if (install) return install.pipeline
@@ -4983,9 +5089,10 @@ export class Engine {
 
   /**
    * Draw every material of a given type (`opaque` or `transparent`) using the main
-   * pipeline(s). Binds the per-frame and per-instance groups once at the top of the
-   * batch, then issues one draw per material. Early-outs if nothing to draw so we
-   * don't waste bindings when a model has no transparents, etc.
+   * pipeline(s), and — babylon-mmd's per-mesh outline stage — each edge-flagged
+   * material's inverted hull IMMEDIATELY after its color draw. Interleaving is what
+   * makes outlines compose like MMD: every material drawn later in the author's
+   * order covers earlier hulls, and each hull sits over everything drawn before it.
    */
   private drawMaterials(pass: GPURenderPassEncoder, inst: ModelInstance, type: "opaque" | "transparent"): void {
     let currentPipeline: GPURenderPipeline | null = null
@@ -5004,61 +5111,58 @@ export class Engine {
       }
       pass.setBindGroup(2, draw.bindGroup)
       pass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0)
-    }
-  }
-
-  /**
-   * Draw every outline of a given type (`opaque-outline` or `transparent-outline`).
-   * Uses its own pipeline layout (group 0 = camera-only, group 2 = edge uniforms), so
-   * every batch binds its own groups from scratch — the next drawMaterials call will
-   * rebind group 0/1 correctly if needed.
-   */
-  private drawOutlines(pass: GPURenderPassEncoder, inst: ModelInstance, type: DrawCallType): void {
-    if (!this.outlineEnabled) return
-    let bound = false
-    for (const draw of inst.drawCalls) {
-      if (draw.type !== type || !this.shouldRenderDrawCall(inst, draw)) continue
-      if (!bound) {
+      if (draw.outline && this.outlineEnabled) {
+        // Same index range; own pipeline + groups 0/2. Group 1 (skinMats) is
+        // layout-identical between the main and outline pipelines and stays
+        // bound. Restore group 0 afterwards and force a pipeline re-set.
         pass.setPipeline(this.outlinePipeline)
         pass.setBindGroup(0, this.outlinePerFrameBindGroup)
-        pass.setBindGroup(1, inst.mainPerInstanceBindGroup)
-        bound = true
+        pass.setBindGroup(2, draw.outline.bindGroup)
+        pass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0)
+        pass.setBindGroup(0, this.perFrameBindGroup)
+        currentPipeline = null
       }
-      pass.setBindGroup(2, draw.bindGroup)
-      pass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0)
     }
   }
 
   /**
-   * Main-pass render sequence for one model instance:
-   *   1) opaque bodies → 2) opaque outlines → 3) transparents → 4) transparent outlines.
-   * Each batch binds the groups it needs, so switching between main and outline
-   * pipelines is self-contained (no cross-batch dependencies).
+   * Main-pass render sequence for one model instance — babylon-mmd parity:
+   * opaque bucket, the hair-over-eyes stencil pass, then alpha-blend materials
+   * in PMX author order with depth write ON (forceDepthWrite). Outlines are not
+   * a separate phase: drawMaterials draws each edge-flagged material's hull
+   * right after the material itself, like MMD's per-mesh outline stage.
    */
-  private renderOneModel(pass: GPURenderPassEncoder, inst: ModelInstance): void {
+  private setModelDrawState(pass: GPURenderPassEncoder, inst: ModelInstance): void {
     pass.setVertexBuffer(0, inst.vertexBuffer)
     pass.setVertexBuffer(1, inst.jointsBuffer)
     pass.setVertexBuffer(2, inst.weightsBuffer)
     pass.setIndexBuffer(inst.indexBuffer, "uint32")
-
     // Single stencil-reference set covers eye (write), hair (read not-equal),
     // and hairOverEyes (read equal). Non-stencil pipelines ignore the value.
     pass.setStencilReference(Engine.STENCIL_EYE_VALUE)
+  }
 
-    // Order matters (the black-hull saga): transparent color draws don't write
-    // depth (self-overlap must double-blend, not patchwork), so ALL outlines
-    // draw after the transparent depth PREPASS has recorded the fabric's depth
-    // — otherwise every hull behind a sheer skirt shows straight through it.
+  private renderModelOpaquePhase(pass: GPURenderPassEncoder, inst: ModelInstance): void {
+    this.setModelDrawState(pass, inst)
     this.drawMaterials(pass, inst, "opaque")
     this.drawHairOverEyes(pass, inst)
+  }
+
+  private renderModelTransparentPhase(pass: GPURenderPassEncoder, inst: ModelInstance): void {
+    this.setModelDrawState(pass, inst)
+    // Transparent: babylon-mmd's forceDepthWrite blending — PMX author order
+    // with depth write ON. The accepted trade-off after trying every variant:
+    //   · depth-write ON (this): a fold hides its far side; rare view-dependent
+    //     double-blend seams at some angles. MMD's own known behavior.
+    //   · nearest-surface prepass: view-independent, but punched see-through
+    //     holes to whatever sat far behind a fold.
+    //   · depth-write OFF layering: every overlap visible everywhere — MORE
+    //     gray patches and texture artifacts in practice.
     this.drawMaterials(pass, inst, "transparent")
-    this.drawOutlines(pass, inst, "opaque-outline")
-    this.drawOutlines(pass, inst, "transparent-outline")
   }
 
   /** Depth-only re-draw of transparent-bucket materials (see depth-prepass.ts).
-   *  Unused while transparent draws write depth themselves (MMD parity) — kept
-   *  for the dormant no-write/OIT path. */
+   *  Dormant — kept for a future order-independent-transparency path. */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   protected drawTransparentDepthPrepass(pass: GPURenderPassEncoder, inst: ModelInstance): void {
     let bound = false
@@ -5119,6 +5223,10 @@ export class Engine {
     this.cameraMatrixData[32] = cameraPos.x
     this.cameraMatrixData[33] = cameraPos.y
     this.cameraMatrixData[34] = cameraPos.z
+    // Spare float after viewPos: render-target height in device px — the outline
+    // shader derives the full viewport (width via projection aspect) for its
+    // babylon-mmd constant-pixel edge extrusion.
+    this.cameraMatrixData[35] = this.canvas.height
     this.device.queue.writeBuffer(this.cameraUniformBuffer, 0, this.cameraMatrixData)
 
     // 360 backdrop: the composite reconstructs each pixel's view ray from the

package/src/index.ts

@@ -2,6 +2,8 @@ export {
   Engine,
   DEFAULT_BLOOM_OPTIONS,
   DEFAULT_VIEW_TRANSFORM,
+  DEFAULT_COLOR_GRADING,
+  type ColorGradingOptions,
   type EngineStats,
   type EngineOptions,
   type BloomOptions,