A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): hair casts and receives its own shadow, with a cascade fitted to it and a density along the light
yhh93e85e975ad4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d09aafcf8..813c90f27 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **Hair shadows and diffuse.** A hair material draws the sun's shadow of hair as hair. The Hair shader gains u_hairShadow, how much light a layer of strands takes per world unit along it (declared with the new `#pragma hairshadow`), and while it is above zero the frame adds a cascade fitted to the hair alone as the first in the sun's list: cards a few millimetres apart fell inside one texel of a cascade spread over the view, so the layers could not shadow each other, and the face under a fringe is now shadowed at the hair's resolution too. The light left after a depth of hair falls off with that depth, from the nearest card to this one, as a deep shadow map reads it, with a card's own surface left out so it does not shadow itself. A hair material imported from a glTF is set to a density of 400. The Hair shader has u_strandDiffuse, how much of the diffuse is the strand's own Kajiya-Kay term against a surface's N dot L, and a hair material imported from a glTF sets it to 0. At the old 0.6 a card turned edge-on to the light still took a third of it, so every lock was lit to one tone and the gaps between locks never went dark; with the Principled shader's diffuse they do. With the lamp highlight at a tenth and the tinted second lobe at half what they were, the top of the hair comes out within about six percent of Blender's render of the same frame on both backends, where it was half again as bright.- **Hair drawn as locks.** The Hair shader can draw a card's strands as locks: u_clumpCount sets how many across its width, u_clumpTone how much lighter or darker one is than the next, u_clumpShift how far each lock's highlight is pushed along the strand so it breaks from lock to lock, and u_clumpGap how dark the seam between locks is; 0 leaves the card as authored. A hair material imported from a glTF is set to seven locks, so cards cut from one strand texture no longer read as a combed plate. Against Blender's render of the same frame the top of the hair comes out within about ten percent in every channel, where it was half again as bright.- **Hair that reads as hair.** The Hair shader has a lobe gain, u_lobeGain, for how much of the strand highlight a lamp draws apart from the reflection of the environment, and an imported hair material now sets it with the rest from what the source states: the specular factor as the environment's Fresnel, the roughness factor, a quarter of the lamp highlight, and a third of the shader's own strand shift and second highlight so the cards read as locks of hair and not plates. Against Blender's render of the same frame the hair comes out with a sheen on each lock and dark gaps between them, where it was a flat red plate.- **Character materials shade like the source.** A model imported with Character Materials now shades like the Principled shader it was authored against: a glTF carries no subsurface scattering and no second strand highlight, so the Skin shader's scattering, wrap and fuzz and the Hair shader's second highlight, translucency and root darkening are written as off, and a hair material's specular factor is scaled to the strand highlight's own units. Measured against Blender's render of the same frame, a character's hair comes out about 15 percent brighter than the reference where it was two to three times too bright, and the skin no longer glows in the shadows.diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdxindex a63e14b08..252db19e6 100644--- a/docs/astro/src/content/docs/graphics/materials.mdx+++ b/docs/astro/src/content/docs/graphics/materials.mdx@@ -71,7 +71,7 @@ texture), the diffuse light is Kajiya-Kay (a strand is lit by how far the lighthighlights along the strand, shifted against each other by `u_shiftMap` (`u_shiftAmount`, `u_shiftTile`): a white one near the surface and a colouredone under it (`u_secondaryTint`). `u_roughness` sets how tight the lines are, and `u_lobeGain` how much of the highlight a lamp draws apart from the reflection of the environment (`u_specular`). `u_clumpCount` draws a card's strands as that many locks across its width, each lighter or darker than the next (`u_clumpTone`), with its own break in the highlight (`u_clumpShift`) and a shadowed seam (`u_clumpGap`); 0 leaves the card as authored. Light comes through the strands from behind (`u_translucency`),`u_sharpen` keeps the fine strands a card is covered in from washing out at a slant, and `u_rootDark` darkens the roots by the occlusion map.-`u_alphaCutoff` cuts a card out by its texture's alpha, feathered by alpha-to-coverage under MSAA, and the card then casts its own shape into shadow maps. `u_tipSoftness` adds the soft outer band: where the alpha falls from the cutoff down by that much, a second blended pass draws the strand's tip fading out, sorted with the other blended draws, so tips do not stair-step under coverage (0 leaves it out). The card's own shape goes into shadow maps too, not the rectangle it is drawn on. A hair model is usually cards or ribbons, not strands; this shader gives the shading of a strand to what the geometry gives it.+`u_strandDiffuse` is how much of the diffuse is that strand diffuse against a surface's N dot L (0 is the Principled shader's, which goes dark where a card turns from the light). `u_hairShadow` is how much light a layer of strands takes, per world unit along the light: above zero the frame fits a shadow cascade to the hair alone, the first in the sun's list, so cards a few millimetres apart are told apart, and the light left after a depth of hair falls off with that depth, as a deep shadow map reads it. `u_alphaCutoff` cuts a card out by its texture's alpha, feathered by alpha-to-coverage under MSAA, and the card then casts its own shape into shadow maps. `u_tipSoftness` adds the soft outer band: where the alpha falls from the cutoff down by that much, a second blended pass draws the strand's tip fading out, sorted with the other blended draws, so tips do not stair-step under coverage (0 leaves it out). The card's own shape goes into shadow maps too, not the rectangle it is drawn on. A hair model is usually cards or ribbons, not strands; this shader gives the shading of a strand to what the geometry gives it.**Eye** (`builtin:eye`) builds an eye from two maps and a few numbers. `u_depthMap` is white over the iris and the dome of the cornea, and `u_irisNormalMap` holds that dome's normals (import both with sRGB off). The view ray is bent into the cornea (`u_ior`) and carried down to the iris (`u_irisDepth`), so the iris moves behind the surface as the eye turns. The iris itself is drawn from `u_irisColor` to `u_irisColor2` with fibres, a dark limbal ring (`u_limbal`) and a pupil (`u_pupilSize`), against the white (`u_scleraColor`), which is lit with light that wraps past the terminator (`u_scleraWrap`). The cornea is a near-mirror (`u_corneaRoughness`, `u_specular`), so every light and the sky show as a catchlight. The lids shade the eye: `u_lidMap` is an authored occlusion map (white where the eye is open), and `u_lidShadow` darkens, and fades the cornea's reflections, where the surface faces up (from `u_lidStart`, a dot with the world's up, to straight up), which is the upper lid on an upright head. A painted eye texture on the mesh multiplies the result.@@ -167,6 +167,7 @@ One file holds every stage plus its metadata, separated by pragmas:| `#pragma switch NAME [default(on)]` | Material-facing static permutation toggle (a `#define`). || `#pragma feature NAME` | Engine-chosen compile-time variant keyword. || `#pragma coverage PARAM` | While the float param `PARAM` is above zero, the shader's output alpha is coverage — a cutout's alpha sharpened to about a texel around the cutoff. An opaque draw into a multisampled target then turns it into multisample coverage, so the cutout's edge is antialiased instead of stair-stepped. The built-in Model shader declares `u_alphaCutoff`. |+| `#pragma hairshadow PARAM` | While the float param `PARAM` is above zero, meshes drawn with the material are hair for shadows: the sun's cascades gain one fitted to them alone, and a shader that sets `g_hairShadow` before it lights reads the shadow as a density along the light instead of a hard compare. The value is the density. The built-in Hair shader declares `u_hairShadow`. || `#pragma gbuffer` | A `PostProcess` shader reads the scene's surface record (see [the G-buffer](/docs/graphics/post-processing/#the-g-buffer)) at `u_gbuffer`. Declaring it is what makes the frame draw one; a chain whose shaders do not never pays for it. || `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage bodies. **The vertex block is optional for 2D domains** — the engine injects the canonical stage. || `#include "path"` | Textual include (resolved by the host). |diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxindex c95c00ab5..21c643b60 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx@@ -51,7 +51,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一**皮肤**(`builtin:skin`)不模糊画面。光进入皮肤又在不远处出来,会让弯曲表面的受光一侧变软,这里按颜色分开做:漫反射光取自比表面自己的法线更软的法线,红色最软(`u_blurRed`、`u_blurGreen`,是法线贴图的 mip 层级),所以毛孔和高光保持清晰。明暗交界线被染暖(`u_sssColor`、`u_sssWrap`),薄的或曲率大的地方会透光(`u_translucency`、`u_thinness`:耳朵、鼻翼、手指),高光是两层(`u_specular`、`u_lobe2`、`u_lobe2Roughness`),另有一层很淡的绒毛光照亮边缘(`u_fuzz`)。打开 `u_subsurface` 还会把它标记给[次表面散射](/docs/zh-cn/graphics/post-processing/#次表面散射)特效,在更大的尺度上扩散剩下的光,代价是会模糊画面。`u_preIntegrate` 让明暗交界线之后的环绕光按颜色分开(红色最远),并在表面急转的地方变宽,所以鼻翼和耳朵边缘会透出光,而平坦的脸颊保持清晰;`u_curvature` 是每个世界单位内多快的转折算作急转。`u_detailMap` 是平铺在表面上的第二张细法线图(`u_detailTile`),用来补烘焙贴图没有足够像素表现的毛孔和皮纹:它按 `u_detailStrength`(0 表示不用)叠在高光读取的锐利法线上,不叠在柔和的漫反射法线上。导入时关闭 sRGB,并把环绕方式设为重复。它对每个像素做三次光照计算,所以适合镜头里的角色皮肤,不适合一群人。-**头发**(`builtin:hair`)把发丝当发丝来打光。`u_lobeGain` 决定灯光画出多少发丝高光(环境反射则只由 `u_specular` 决定)。`u_clumpCount` 把一张发片的发丝画成横向若干束:束与束明暗不同(`u_clumpTone`)、高光各自错开(`u_clumpShift`)、束间有一道阴影缝(`u_clumpGap`);0 表示保持贴图原样。`u_flowMap` 说明发丝朝哪个方向(红、绿是贴图上的一个方向),漫反射是 Kajiya-Kay(发丝被光照亮的程度取决于光离它的走向有多远),高光是两条沿发丝的窄高光,由 `u_shiftMap` 把它们错开(`u_shiftAmount`、`u_shiftTile`):一条白的靠近表面,一条带颜色的在下面(`u_secondaryTint`)。`u_roughness` 决定线条有多紧。光会从发丝背面透过来(`u_translucency`),`u_sharpen` 让发片上密布的细发丝在斜着看时不被冲淡,`u_rootDark` 按遮蔽图把发根压暗。`u_alphaCutoff` 按贴图的 alpha 把发片抠出形状,在 MSAA 下由 alpha-to-coverage 柔化边缘,`u_tipSoftness` 增加柔和的外缘:alpha 从裁剪值往下降这么多的范围内,由第二遍混合绘制把发丝尖端渐隐地画出来,和其他混合绘制一起排序,所以发梢不会在覆盖率下出现阶梯(0 表示不用)。发片投进阴影图里的也是这个形状,而不是它所在的矩形。头发模型通常是发片或发带而不是真正的发丝;这个着色器把发丝的明暗给了几何本身给不了的部分。+**头发**(`builtin:hair`)把发丝当发丝来打光。`u_lobeGain` 决定灯光画出多少发丝高光(环境反射则只由 `u_specular` 决定)。`u_strandDiffuse` 决定漫反射里发丝自己的那部分占多少(0 就是 Principled 着色器的漫反射,发片背向光时会变暗)。`u_hairShadow` 是光沿着射线穿过一层发丝被吸收的密度:大于 0 时,帧会给头发单独拟合一个阴影级联(排在太阳级联的最前面),相隔几毫米的发片才分得开,穿过的头发越厚透过的光越少,和深度阴影图的读法一样。`u_clumpCount` 把一张发片的发丝画成横向若干束:束与束明暗不同(`u_clumpTone`)、高光各自错开(`u_clumpShift`)、束间有一道阴影缝(`u_clumpGap`);0 表示保持贴图原样。`u_flowMap` 说明发丝朝哪个方向(红、绿是贴图上的一个方向),漫反射是 Kajiya-Kay(发丝被光照亮的程度取决于光离它的走向有多远),高光是两条沿发丝的窄高光,由 `u_shiftMap` 把它们错开(`u_shiftAmount`、`u_shiftTile`):一条白的靠近表面,一条带颜色的在下面(`u_secondaryTint`)。`u_roughness` 决定线条有多紧。光会从发丝背面透过来(`u_translucency`),`u_sharpen` 让发片上密布的细发丝在斜着看时不被冲淡,`u_rootDark` 按遮蔽图把发根压暗。`u_alphaCutoff` 按贴图的 alpha 把发片抠出形状,在 MSAA 下由 alpha-to-coverage 柔化边缘,`u_tipSoftness` 增加柔和的外缘:alpha 从裁剪值往下降这么多的范围内,由第二遍混合绘制把发丝尖端渐隐地画出来,和其他混合绘制一起排序,所以发梢不会在覆盖率下出现阶梯(0 表示不用)。发片投进阴影图里的也是这个形状,而不是它所在的矩形。头发模型通常是发片或发带而不是真正的发丝;这个着色器把发丝的明暗给了几何本身给不了的部分。**眼睛**(`builtin:eye`)用两张贴图和几个数值做出一只眼睛。`u_depthMap` 在虹膜和角膜穹顶上为白色,`u_irisNormalMap` 是这个穹顶的法线(两张都要以关闭 sRGB 的方式导入)。视线在角膜处折射(`u_ior`)再下行到虹膜(`u_irisDepth`),所以眼球转动时虹膜在表面后面移动。虹膜本身由 `u_irisColor` 到 `u_irisColor2` 绘制,带纤维纹理、深色角膜缘(`u_limbal`)和瞳孔(`u_pupilSize`),衬在眼白(`u_scleraColor`)上,眼白的光会绕过明暗交界线(`u_scleraWrap`)。角膜近似镜面(`u_corneaRoughness`、`u_specular`),所以每盏灯和天空都会变成一个眼神光。眼睑会给眼睛投下阴影:`u_lidMap` 是手绘的遮蔽图(眼睛睁开处为白色),`u_lidShadow` 会在表面朝上的地方(从 `u_lidStart` 即与世界上方向的点积起,到正上方)变暗并淡化角膜的反射,在头部直立时这就是上眼睑。网格上画的眼睛贴图会与结果相乘。@@ -137,6 +137,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一| `#pragma switch NAME [default(on)]` | 材质可控的静态排列开关(一个 `#define`)。 || `#pragma coverage PARAM` | 浮点参数 `PARAM` 大于零时,着色器输出的 alpha 就是覆盖率——镂空的 alpha 在阈值附近锐化到约一个纹素宽。不透明物体画进多重采样目标时,它会转成多重采样覆盖率,镂空边缘就有抗锯齿而不是台阶。内置 Model 着色器声明了 `u_alphaCutoff`。 || `#pragma feature NAME` | 引擎选择的编译期变体关键字。 |+| `#pragma hairshadow PARAM` | 浮点参数 `PARAM` 大于零时,用这个材质画的网格就是阴影意义上的头发:太阳的级联多出一个只拟合它们的级联,并且着色器在打光前设置 `g_hairShadow` 的话,阴影就按沿光线的密度读,而不是硬比较。参数值就是密度。内置 Hair 着色器声明了 `u_hairShadow`。 || `#pragma gbuffer` | `PostProcess` 着色器要读取场景的表面记录(见[G-buffer](/docs/zh-cn/graphics/post-processing/#g-buffer)),在 `u_gbuffer` 处。声明它才会让这一帧画出一份;着色器里没有它的链路永远不付这笔钱。 || `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage 代码体。**2D 域的顶点段可省略**——引擎注入规范顶点段。 || `#include "path"` | 文本 include(由宿主解析)。 |diff --git a/pipeline/src/assets/modelImport.ts b/pipeline/src/assets/modelImport.tsindex 03f28b386..c511b1f6c 100644--- a/pipeline/src/assets/modelImport.ts+++ b/pipeline/src/assets/modelImport.ts@@ -709,8 +709,9 @@ function hasProduct(material: ImportedMaterial, refs: ProductRefs): boolean {* half the light, so under a lamp it is far too bright unless it is turned down on its own. Measured against Blender's Principled at roughness* 0.43 and a specular level of 0.3 (tools/render-align in the star-neighbors game).*/-const HAIR_LOBE_GAIN = 0.28;+const HAIR_LOBE_GAIN = 0.1;const HAIR_ENV_GAIN = 0.65;+const HAIR_SHADOW_DENSITY = 400;/*** What the character shaders read, from what the source says: the maps they share, and the cutout hair needs. What a glTF does not say it@@ -735,13 +736,16 @@ function characterProperties(shading: CharacterShading, material: ImportedMateri// A little of the shader's own strand character is kept (a per-strand shift of the highlight and a tinted second lobe, at a third of their// strength): without it the cards read as plates, not locks of hair.properties.u_translucency = 0; properties.u_shiftAmount = 0.3; properties.u_rootDark = 0;- properties.u_secondaryTint = { r: 0.25, g: 0.15, b: 0.08, a: 1 };+ properties.u_secondaryTint = { r: 0.12, g: 0.07, b: 0.04, a: 1 };// The Hair shader has no use for the packed roughness (a strand's width is its own), so the factor is the whole answer.if (rough !== undefined) properties.u_roughness = rough;// Principled reflects F0 = 0.04 x the factor; the Hair shader's F0 is 0.046, so u_specular is the ratio, and its reflection of the environment at// this roughness comes out about half as bright again as Blender's, which HAIR_ENV_GAIN takes back.properties.u_specular = ((material.specular ?? 1) * 0.04 / 0.046) * HAIR_ENV_GAIN;properties.u_lobeGain = HAIR_LOBE_GAIN;+ // The Principled shader's diffuse, which goes dark where a card turns from the light (the strand's own diffuse keeps it lit edge-on and flattens the locks), and+ // a density of hair for the light to pass through, with the cascade the frame fits to it: what Blender gets from tracing the layers.+ properties.u_strandDiffuse = 0; properties.u_hairShadow = HAIR_SHADOW_DENSITY;// Cards cut from one strand texture read as combed plates; drawing them as a few locks, each a little lighter or darker with its own break in the highlight// and a shadowed seam, gives the layers the depth Blender gets from hundreds of overlapping cards.properties.u_clumpCount = 7; properties.u_clumpTone = 0.4; properties.u_clumpShift = 0.5; properties.u_clumpGap = 0.55;diff --git a/sdk/src/character/characterShaders.ts b/sdk/src/character/characterShaders.tsindex dadf3e979..b760970e5 100644--- a/sdk/src/character/characterShaders.ts+++ b/sdk/src/character/characterShaders.ts@@ -35,6 +35,9 @@ const HAIR = `#pragma shader "Hair"#pragma param u_secondaryTint color default(0.75,0.45,0.25,1)// Light that comes through the strands from behind.#pragma param u_translucency float default(0.4) range(0,1) ui(slider)+// How much of the diffuse is the strand's own (Kajiya-Kay: how far the light is from along the strand, with a soft wrap) against a surface's N dot L: 0 is the Principled+// shader's diffuse, which goes dark where a card turns from the light; more keeps a card lit edge-on, which flattens locks into one tone.+#pragma param u_strandDiffuse float default(0.6) range(0,1) ui(slider)// A negative bias on the colour's mip level keeps the fine strands a hair card is covered in from washing out at a slant, which they do at once.#pragma param u_sharpen float default(-0.8) range(-3,1) ui(slider)// How much darker the roots are than the tips: the occlusion map's red, pushed.@@ -52,6 +55,11 @@ const HAIR = `#pragma shader "Hair"#pragma param u_clumpTone float default(0.25) range(0,0.6) ui(slider)#pragma param u_clumpShift float default(0.3) range(0,1) ui(slider)#pragma param u_clumpGap float default(0.3) range(0,1) ui(slider)+// How much of the light a layer of strands takes, per world unit along it (an opacity density; 0 shades like any surface, with a hard shadow). Above zero+// the frame also gives the hair a shadow cascade fitted to it alone, so the layers of cards a few millimetres apart are told apart, and the light left+// after them falls off with the depth of hair it passed through.+#pragma param u_hairShadow float default(0) range(0,2000) ui(slider)+#pragma hairshadow u_hairShadow#pragma fragmentprecision highp float;@@ -127,9 +135,11 @@ void main() {SurfaceExt ext = surfaceExtNone(N);ext.aniso = vec4(T, 0.0);ext.misc = vec4(0.046, max(u_lobeGain, 0.001), u_shiftPrimary + noise, u_shiftSecondary + noise);+ ext.strand = vec4(u_strandDiffuse, 0.0, 0.0, 0.0);ext.scatter = vec4(base.rgb * u_secondaryTint.rgb * 1.6, 0.35);ext.trans = vec4(u_translucency, 0.25, 0.0, 0.0);vec3 viewDir = viewDirection(P);+ g_hairShadow = u_hairShadow;vec3 lit = applyLightingSurface(base.rgb, N, P, viewDir, 0.0, u_roughness, u_specular, ao, ext);fragColor = vec4(lit, alpha);#ifdef ES_GBUFFER@@ -216,9 +226,11 @@ fn packNormal(n : vec3f) -> vec2f {var ext = surfaceExtNone(N);ext.aniso = vec4f(T, 0.0);ext.misc = vec4f(0.046, max(mc.u_lobeGain, 0.001), mc.u_shiftPrimary + noise, mc.u_shiftSecondary + noise);+ ext.strand = vec4f(mc.u_strandDiffuse, 0.0, 0.0, 0.0);ext.scatter = vec4f(base.rgb * mc.u_secondaryTint.rgb * 1.6, 0.35);ext.trans = vec4f(mc.u_translucency, 0.25, 0.0, 0.0);let viewDir = viewDirection(P);+ g_hairShadow = mc.u_hairShadow;let lit = applyLightingSurface(base.rgb, N, P, viewDir, 0.0, mc.u_roughness, mc.u_specular, ao, ext);#ifdef ES_GBUFFERvar frag : FragOut;diff --git a/sdk/tests/hair-shader-shadow.test.ts b/sdk/tests/hair-shader-shadow.test.tsnew file mode 100644index 000000000..82cc641fa--- /dev/null+++ b/sdk/tests/hair-shader-shadow.test.ts@@ -0,0 +1,39 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The Hair shader names its shadow density to the frame and hands it to the lighting, in both languages.+ *+ * The density param is what makes the frame fit a cascade to the hair, and the global the shader sets is what the+ * shadow lookup reads: if either side drops out the hair shadows like any surface again, with nothing to say so.+ */+import { describe, it, expect } from 'vitest';+import { builtinShaderTemplate } from '../src/render/builtinShaders';+import { CHARACTER_SHADER_TEMPLATES } from '../src/character/characterShaders';++const hair = CHARACTER_SHADER_TEMPLATES.find(t => t.id === 'hair')!;+const source = hair.source;+const split = source.indexOf('#pragma fragment wgsl');+const [glsl, wgsl] = [source.slice(0, split), source.slice(split)];++describe('the Hair shader and its shadow', () => {+ it('declares the density param and makes it the hair-shadow param', () => {+ expect(source).toMatch(/#pragma param u_hairShadow float default\(0\)/);+ expect(source).toMatch(/#pragma hairshadow u_hairShadow/);+ });++ it('sets the lighting global from the param, before it lights, in each language', () => {+ expect(glsl.indexOf('g_hairShadow = u_hairShadow;')).toBeGreaterThan(0);+ expect(glsl.indexOf('g_hairShadow = u_hairShadow;')).toBeLessThan(glsl.indexOf('applyLightingSurface('));+ expect(wgsl.indexOf('g_hairShadow = mc.u_hairShadow;')).toBeGreaterThan(0);+ expect(wgsl.indexOf('g_hairShadow = mc.u_hairShadow;')).toBeLessThan(wgsl.indexOf('applyLightingSurface('));+ });++ it('hands the strand diffuse weight to the lighting', () => {+ expect(glsl).toMatch(/ext\.strand = vec4\(u_strandDiffuse/);+ expect(wgsl).toMatch(/ext\.strand = vec4f\(mc\.u_strandDiffuse/);+ });++ it('is not a pragma any other built-in shader uses', () => {+ for (const id of ['model', 'skin']) expect(builtinShaderTemplate(id)?.source ?? '').not.toMatch(/#pragma hairshadow/);+ });+});diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cppindex 3a6f262c6..a6130408e 100644--- a/src/esengine/bindings/MaterialBindings.cpp+++ b/src/esengine/bindings/MaterialBindings.cpp@@ -48,6 +48,7 @@ static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& playout.blockSize = parsed.materialBlockSize;layout.coverageParam = parsed.coverageParam;layout.tipParam = parsed.tipParam;+ layout.hairShadowParam = parsed.hairShadowParam;layout.usesGBuffer = parsed.usesGBuffer;layout.usesLights = parsed.usesLights;layout.highPrecision = parsed.highPrecision;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex b699e1007..cc4d8353d 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1800,6 +1800,27 @@ bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glreturn any;}+bool RenderFrame::hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax) {+ auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();+ bool any = false;+ for (auto entity : meshes) {+ const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);+ if (!mesh.enabled || !mesh.mesh.isValid() || mesh.material == 0) continue;+ if (context_.materials().hairShadowDensity(mesh.material) <= 0.0f) continue;+ const Mesh* resident = resource_manager_.getMesh(mesh.mesh);+ if (!resident) continue;+ auto& transform = meshes.get<ecs::Transform>(entity);+ transform.ensureDecomposed();+ glm::vec3 centre(0.0f), half(0.0f);+ orientedWorldAabb(transform.worldPosition, transform.worldRotation, transform.worldScale,+ resident->localMin, resident->localMax, centre, half);+ outMin = any ? glm::min(outMin, centre - half) : centre - half;+ outMax = any ? glm::max(outMax, centre + half) : centre + half;+ any = true;+ }+ return any;+}+/// The camera frustum's eight world corners, near plane first (GL clip z in [-1,1],/// which both backends' shared projection helpers write).static void frustumCorners(const glm::mat4& invVP, glm::vec3 out[8]) {@@ -1915,6 +1936,11 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {frustumCorners(invVP, corners);glm::vec3 boundsMin(0.0f), boundsMax(0.0f);const bool haveBounds = meshWorldBounds(registry, boundsMin, boundsMax);+ // Hair is layers of cards a few millimetres apart, which a cascade spread over the view cannot tell apart: its texel is as wide as the gap.+ // So a perspective sun with cascades of its own also gets one fitted to the hair alone, first in its list (the nearest tile covering a+ // fragment wins), and everything that falls inside it, the face under a fringe included, is shadowed at that resolution.+ glm::vec3 hairMin(0.0f), hairMax(0.0f);+ const bool haveHair = perspective && hairWorldBounds(registry, hairMin, hairMax);f32 nearDist = 0.0f, farDist = 1.0f;if (perspective) {@@ -1975,7 +2001,8 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {if (caster.shape != ShadowShape::Box) continue;// A fixed reach is the author saying what the map covers; splitting it would// hand the rest of the atlas to slices they never asked for.- const u32 want = (perspective && caster.extent <= 0.0f) ? shadow_cascades_ : 1;+ const bool focus = haveHair && caster.extent <= 0.0f;+ const u32 want = (perspective && caster.extent <= 0.0f) ? shadow_cascades_ + (focus ? 1u : 0u) : 1;i32 at = -1;const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want,kShadowCascadeCells, at);@@ -2003,6 +2030,9 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {const TilePlan mine = plan[ci];if (mine.count == 0) continue;u32 plannedTiles = 0;+ // The first tile of a perspective sun with cascades is the hair's, when there is hair; the cascades follow it.+ const bool hasFocus = haveHair && caster.shape == ShadowShape::Box && caster.extent <= 0.0f && mine.count > 1;+ const u32 cascadeCount = mine.count - (hasFocus ? 1u : 0u);for (u32 c = 0; c < mine.count; ++c) {const u32 tileIndex = mine.first + c;@@ -2036,11 +2066,23 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {radius = caster.extent > 0.0f ? caster.extent : std::max(fitted, 1.0f);centre = haveBounds ? (boundsMin + boundsMax) * 0.5f: glm::vec3(view.center.x, view.center.y, 0.0f);+ } else if (hasFocus && c == 0) {+ // The hair, as a sphere a little wider than its box so the face under it is inside, its radius stepped by quarter octaves+ // so the texel does not change every frame, and the centre snapped to the map's grid so the edges do not crawl.+ centre = (hairMin + hairMax) * 0.5f;+ const f32 wanted = std::max(0.5f * glm::length(hairMax - hairMin) * 1.25f, 0.02f);+ radius = std::exp2(std::ceil(std::log2(wanted) * 4.0f) / 4.0f);+ const f32 texel = (radius * 2.0f) / static_cast<f32>(tile.size);+ glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(centre, 1.0f));+ inLight.x = std::floor(inLight.x / texel) * texel;+ inLight.y = std::floor(inLight.y / texel) * texel;+ centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));} else {// This slice of the view, as a sphere: a box would grow and shrink as// the light turns, and the texel density with it.- const f32 t0 = splitFraction(c, mine.count, nearDist, farDist);- const f32 t1 = splitFraction(c + 1, mine.count, nearDist, farDist);+ const u32 slot = hasFocus ? c - 1 : c;+ const f32 t0 = splitFraction(slot, cascadeCount, nearDist, farDist);+ const f32 t1 = splitFraction(slot + 1, cascadeCount, nearDist, farDist);glm::vec3 slice[8];for (u32 i = 0; i < 4; ++i) {const glm::vec3 ray = corners[i + 4] - corners[i];diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex f0e2e2666..cc9c72ec3 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -810,6 +810,9 @@ private:/// The world box the resident meshes occupy — what a shadow map must cover./// False when nothing 3D is in the scene.bool meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax);+ /// The box the meshes drawn with a hair-shadow material occupy (MaterialStore::hairShadowDensity above zero), or false when there are none:+ /// what the sun's focus cascade is fitted to.+ bool hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax);/// Opens the frame's own target with @p clear's load-op, for begin() to bind it/// eagerly. Every other pass of the frame is the graph's to open.void openPass(const PassClear& clear, RenderTargetManager::Handle target);diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hppindex 58df15723..ffb6dd9f7 100644--- a/src/esengine/renderer/store/MaterialStore.hpp+++ b/src/esengine/renderer/store/MaterialStore.hpp@@ -94,6 +94,8 @@ struct MaterialUniformLayout {std::string coverageParam;/// The float param that turns the shader's blended tip pass on (see ParsedShader::tipParam).std::string tipParam;+ /// The float param that makes the shader's meshes hair for shadows (see ParsedShader::hairShadowParam).+ std::string hairShadowParam;/// The shader reads the scene's surface record (ParsedShader::usesGBuffer).bool usesGBuffer = false;/// The shader reads the frame's light block and shadow atlas (ParsedShader::usesLights).@@ -375,6 +377,18 @@ public:return value > 0.0f;}+ /// The hair shadow density @p materialId holds (see ParsedShader::hairShadowParam), 0 when its shader has none or it is off.+ f32 hairShadowDensity(u32 materialId) const {+ const MaterialRecord* m = find(materialId);+ const MaterialUniformLayout* layout = m ? layoutFor(m->shaderRef) : nullptr;+ if (!layout || layout->hairShadowParam.empty()) return 0.0f;+ const MaterialParamSlot* slot = layout->find(layout->hairShadowParam);+ if (!slot || slot->offset + sizeof(f32) > m->uboBytes.size()) return 0.0f;+ f32 value = 0.0f;+ std::memcpy(&value, m->uboBytes.data() + slot->offset, sizeof(f32));+ return value > 0.0f ? value : 0.0f;+ }+/// The registered #pragma-param layout for a shader program, or nullptr./// The post-process pipeline reads it to pack pass params through the same/// reflected MaterialConstants block a material would use.diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 18c88ba85..316c95e60 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -732,6 +732,11 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeRcontinue;}+ if (directive == "hairshadow") {+ result.hairShadowParam = argument;+ continue;+ }+if (directive == "gbuffer") {result.usesGBuffer = true;continue;@@ -1259,6 +1264,8 @@ struct PlanarConstants { planarProjection : mat4x4f, planarParams : vec4f };// varying, so the entry point hands it over — the GLSL twin reads the varying// straight, which is the one place the two stages differ in shape.var<private> g_probeSlot : f32 = 0.0;+// Set by a hair shader before it lights: how much of the light a layer of strands takes, per world unit along it (0 = a surface, a hard compare).+var<private> g_hairShadow : f32 = 0.0;// The GLSL twin's v_lightmap, handed over by the entry point like the slot above.var<private> g_lightmap : vec3f = vec3f(0.0);// The mesh's own tangent frame, handed over by the entry point like the slot above; zero where the shader never sets it, which@@ -1357,6 +1364,25 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,// the tangent of the angle it subtends where its w is 1 everywhere.let hasEye = length(vec3f(m[0].w, m[1].w, m[2].w)) > 0.5;let src = select(source.y, source.x, hasEye);+ // Hair: layers of strand cards a few millimetres apart are not a wall. The light left after a depth of them falls off with that depth, from the+ // nearest card (what the map holds) to this one, the way a deep shadow map reads it. A blocker within a couple of texels toward the light is+ // this card's own surface and does not count.+ if (g_hairShadow > 0.0) {+ let reachHair = shadowDepth(m, worldPos + L * stepFor(texel, slope, 2.0));+ var sumHair = 0.0;+ var hitsHair = 0.0;+ for (var i = 0; i < 8; i++) {+ let at = clamp(at0 + diskTap(i, 8, 2.0) * lc.u_shadowParams.y, lo, hi);+ let d = unpackDepth(textureSampleLevel(t2, s2, at, 0.0).rgb);+ if (d < reachHair) { sumHair += d; hitsHair += 1.0; }+ }+ if (hitsHair < 0.5) { return 1.0; }+ let Ah = length(vec3f(m[0].z, m[1].z, m[2].z));+ let zbh = 2.0 * (sumHair / hitsHair) - 1.0;+ var spanHair = (proj.z - zbh) / max(Ah, 1e-9);+ if (hasEye) { spanHair = lcp.w - lcp.w * (Ah - proj.z) / max(Ah - zbh, 1e-6); }+ return mix(1.0, exp(-g_hairShadow * max(spanHair, 0.0)), hitsHair * 0.125);+ }// A source with no size throws one edge: a tent over the 3x3 texels around the// point, weighted by where it falls among them. Equal weights step at every// texel and the map's grid shows along the edge; a 2x2 still stair-steps it.@@ -1683,10 +1709,10 @@ fn distanceFalloff(dist : f32, reach : f32, fo : vec4f) -> f32 {})"// Split again for the same reason: the surface layers and the lighting that reads them.-R"(struct SurfaceExt { coat : vec4f, coatN : vec4f, sheen : vec4f, aniso : vec4f, scatter : vec4f, trans : vec4f, film : vec4f, misc : vec4f };+R"(struct SurfaceExt { coat : vec4f, coatN : vec4f, sheen : vec4f, aniso : vec4f, scatter : vec4f, trans : vec4f, film : vec4f, misc : vec4f, strand : vec4f };fn surfaceExtNone(N : vec3f) -> SurfaceExt {return SurfaceExt(vec4f(0.0), vec4f(N, 0.0), vec4f(0.0), vec4f(0.0), vec4f(0.0), vec4f(0.0), vec4f(0.0),- vec4f(0.04, 0.0, 0.0, 0.0));+ vec4f(0.04, 0.0, 0.0, 0.0), vec4f(0.6, 0.0, 0.0, 0.0));}fn distributionCharlie(NdotH : f32, a : f32) -> f32 {let invA = 1.0 / max(a, 1e-3);@@ -1836,7 +1862,7 @@ fn shadeLight(pd : vec4f, col : vec4f, sp : vec4f, sh : vec4f, sm : vec4f, fo :// Hair (misc.y above zero; aniso.xyz is the strand): Kajiya-Kay diffuse, which lights a strand by how far light is from along it.if (ext.misc.y > 0.0) {let along = dot(ext.aniso.xyz, L);- ndotl = mix(ndotl, sqrt(max(1.0 - along * along, 0.0)) * clamp(dot(N, L) * 0.5 + 0.65, 0.0, 1.0), 0.6);+ ndotl = mix(ndotl, sqrt(max(1.0 - along * along, 0.0)) * clamp(dot(N, L) * 0.5 + 0.65, 0.0, 1.0), ext.strand.x);}let radiance = col.rgb * (col.a * ndotl * atten);lit += radiance;@@ -2361,6 +2387,8 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// sit further apart than the texels they average, and a penumbra bands rather// than blurs. It bounds the search too, which can find no wider an edge."const highp float kShadowDisc = 8.0;\n"+ // Set by a hair shader before it lights: how much of the light a layer of strands takes, per world unit along it.+ "highp float g_hairShadow = 0.0;\n"// A spiral, not a table: the golden angle spreads any number of taps evenly// over a disc, so the pattern follows the count instead of sitting beside it."highp vec2 diskTap(in int i, in int n, in highp float radius) {\n"@@ -2420,6 +2448,24 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// the tangent of the angle it subtends where its w is 1 everywhere." bool hasEye = length(vec3(m[0][3], m[1][3], m[2][3])) > 0.5;\n"" highp float src = hasEye ? source.x : source.y;\n"+ // Hair: the light left after a depth of strand layers falls off with that depth, from the nearest card (what the map holds) to this one.+ // A blocker within a couple of texels toward the light is this card's own surface and does not count.+ " if (g_hairShadow > 0.0) {\n"+ " highp float reachHair = shadowDepth(m, worldPos + L * stepFor(texel, slope, 2.0));\n"+ " highp float sumHair = 0.0;\n"+ " highp float hitsHair = 0.0;\n"+ " for (int i = 0; i < 8; ++i) {\n"+ " highp vec2 at = clamp(at0 + diskTap(i, 8, 2.0) * u_shadowParams.y, lo, hi);\n"+ " highp float d = unpackDepth(texture(u_shadowMap, at).rgb);\n"+ " if (d < reachHair) { sumHair += d; hitsHair += 1.0; }\n"+ " }\n"+ " if (hitsHair < 0.5) return 1.0;\n"+ " highp float Ah = length(vec3(m[0][2], m[1][2], m[2][2]));\n"+ " highp float zbh = 2.0 * (sumHair / hitsHair) - 1.0;\n"+ " highp float spanHair = (proj.z - zbh) / max(Ah, 1e-9);\n"+ " if (hasEye) spanHair = lc.w - lc.w * (Ah - proj.z) / max(Ah - zbh, 1e-6);\n"+ " return mix(1.0, exp(-g_hairShadow * max(spanHair, 0.0)), hitsHair * 0.125);\n"+ " }\n"// A source with no size throws one edge: a tent over the 3x3 texels around the// point, weighted by where it falls among them. Equal weights step at every// texel and the map's grid shows along the edge; a 2x2 still stair-steps it.@@ -2792,10 +2838,11 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" highp vec4 trans;\n"" highp vec4 film;\n"" highp vec4 misc;\n"+ " highp vec4 strand;\n""};\n""SurfaceExt surfaceExtNone(in highp vec3 N) {\n"" return SurfaceExt(vec4(0.0), vec4(N, 0.0), vec4(0.0), vec4(0.0), vec4(0.0), vec4(0.0), vec4(0.0),\n"- " vec4(0.04, 0.0, 0.0, 0.0));\n"+ " vec4(0.04, 0.0, 0.0, 0.0), vec4(0.6, 0.0, 0.0, 0.0));\n""}\n""highp float distributionCharlie(in highp float NdotH, in highp float a) {\n"" highp float invA = 1.0 / max(a, 1e-3);\n"@@ -2964,7 +3011,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// Hair (misc.y above zero; aniso.xyz is the strand): Kajiya-Kay diffuse, which lights a strand by how far light is from along it." if (ext.misc.y > 0.0) {\n"" highp float along = dot(ext.aniso.xyz, L);\n"- " ndotl = mix(ndotl, sqrt(max(1.0 - along * along, 0.0)) * clamp(dot(N, L) * 0.5 + 0.65, 0.0, 1.0), 0.6);\n"+ " ndotl = mix(ndotl, sqrt(max(1.0 - along * along, 0.0)) * clamp(dot(N, L) * 0.5 + 0.65, 0.0, 1.0), ext.strand.x);\n"" }\n"" highp vec3 radiance = col.rgb * (col.a * ndotl * atten);\n"" lit += radiance;\n"diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hppindex 5c90b5eb4..59f350ca2 100644--- a/src/esengine/resource/ShaderParser.hpp+++ b/src/esengine/resource/ShaderParser.hpp@@ -156,6 +156,11 @@ struct ParsedShader {/// pass (compiled with ES_TIP_PASS) over the opaque one: the soft outer band of a cutout that/// coverage alone would stair-step.std::string tipParam;+ /// `#pragma hairshadow <param>`: while that float param is above zero, meshes drawn with the material are hair —+ /// the frame fits a shadow cascade to them alone (so their layers are not lost in a texel of the view's own+ /// cascades), and the shader reads the shadow as a density along the light (a strand layer lets part of the+ /// light through) in place of a hard compare. The value is the density, in opacity per world unit.+ std::string hairShadowParam;/// `#pragma gbuffer`: a post-process shader reads the scene's surface record (normal, roughness,/// metalness) at unit kGBufferUnit, so the frame must draw one for it.bool usesGBuffer = false;diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 63acdf5d9..9091cd4d2 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -64,6 +64,8 @@ export const NOTED = {{"note":"The Hair shader has a lobe gain, u_lobeGain, for how much of the strand highlight a lamp draws apart from the reflection of the environment, and an imported hair material now sets it with the rest from what the source states: the specular factor as the environment's Fresnel, the roughness factor, a quarter of the lamp highlight, and a third of the shader's own strand shift and second highlight so the cards read as locks of hair and not plates. Against Blender's render of the same frame the hair comes out with a sheen on each lock and dark gaps between them, where it was a flat red plate."},'feat(character): hair shader draws a card as locks, with a tone, a highlight break and a seam for each':{"note":"The Hair shader can draw a card's strands as locks: u_clumpCount sets how many across its width, u_clumpTone how much lighter or darker one is than the next, u_clumpShift how far each lock's highlight is pushed along the strand so it breaks from lock to lock, and u_clumpGap how dark the seam between locks is; 0 leaves the card as authored. A hair material imported from a glTF is set to seven locks, so cards cut from one strand texture no longer read as a combed plate. Against Blender's render of the same frame the top of the hair comes out within about ten percent in every channel, where it was half again as bright."},+ 'feat(render): hair casts and receives its own shadow, with a cascade fitted to it and a density along the light':+ {"note":"A hair material draws the sun's shadow of hair as hair. The Hair shader gains u_hairShadow, how much light a layer of strands takes per world unit along it (declared with the new `#pragma hairshadow`), and while it is above zero the frame adds a cascade fitted to the hair alone as the first in the sun's list: cards a few millimetres apart fell inside one texel of a cascade spread over the view, so the layers could not shadow each other, and the face under a fringe is now shadowed at the hair's resolution too. The light left after a depth of hair falls off with that depth, from the nearest card to this one, as a deep shadow map reads it, with a card's own surface left out so it does not shadow itself. A hair material imported from a glTF is set to a density of 400. The Hair shader has u_strandDiffuse, how much of the diffuse is the strand's own Kajiya-Kay term against a surface's N dot L, and a hair material imported from a glTF sets it to 0. At the old 0.6 a card turned edge-on to the light still took a third of it, so every lock was lit to one tone and the gaps between locks never went dark; with the Principled shader's diffuse they do. With the lamp highlight at a tenth and the tinted second lobe at half what they were, the top of the hair comes out within about six percent of Blender's render of the same frame on both backends, where it was half again as bright."},'fix: serialize binaryen optimization on windows': { internal: 'Uses one optimizer worker after wider builds reproduced heap corruption with four; release optimization flags stay unchanged.' },'feat: add budgeted 2d and 3d particle scene collisions': { note: 'Budgeted particle scene collisions.' },'feat(editor): add particle collision authoring and diagnostics': { note: 'Budgeted particle scene collisions.' },