127 lines
4.1 KiB
Markdown
Executable File
127 lines
4.1 KiB
Markdown
Executable File
# onBeforeCompile 注入 GLSL 的陷阱
|
||
|
||
## 场景
|
||
|
||
使用 `MeshPhysicalMaterial` 的 `transmission` 功能但需要增强效果时（如 drei 的 MeshTransmissionMaterial），
|
||
通过 `material.onBeforeCompile` 注入自定义 GLSL 代码。
|
||
|
||
## 常见陷阱
|
||
|
||
### 1. 函数签名版本差异
|
||
|
||
Three.js 不同版本的内置函数签名不同：
|
||
|
||
```glsl
|
||
// r166 及之前
|
||
vec4 getIBLVolumeRefraction(n, v, roughness, diffuseColor, specularColor, specularF90,
|
||
pos, modelMatrix, viewMatrix, projectionMatrix, ior, thickness,
|
||
attenuationColor, attenuationDistance)
|
||
|
||
// r167+ 新增 dispersion 参数
|
||
vec4 getIBLVolumeRefraction(n, v, roughness, diffuseColor, specularColor, specularF90,
|
||
pos, modelMatrix, viewMatrix, projectionMatrix, dispersion, ior, thickness,
|
||
attenuationColor, attenuationDistance)
|
||
```
|
||
|
||
**必须检查目标版本的实际签名**：
|
||
```bash
|
||
curl -s "https://cdn.jsdelivr.net/npm/three@0.167.0/src/renderers/shaders/ShaderChunk/transmission_pars_fragment.glsl.js" \
|
||
| tr '\n' ' ' | grep -oE 'vec4 getIBLVolumeRefraction\([^)]+\)'
|
||
```
|
||
|
||
### 2. GLSL 不允许嵌套函数定义
|
||
|
||
```glsl
|
||
// 错误！GLSL 不支持函数内定义函数
|
||
void main() {
|
||
float myRand(vec2 co) { return fract(sin(...)); } // 编译失败
|
||
}
|
||
|
||
// 正确：函数必须在全局作用域
|
||
float myRand(vec2 co) { return fract(sin(...)); }
|
||
void main() {
|
||
float r = myRand(uv);
|
||
}
|
||
```
|
||
|
||
### 3. 条件编译宏保护
|
||
|
||
某些变量只在特定宏下可用：
|
||
- `vWorldPosition` → 需要 `USE_TRANSMISSION` 启用
|
||
- `vTransmissionMapUv` → 需要 `USE_TRANSMISSIONMAP` 启用
|
||
- `roughnessFactor` → 在 `lights_physical_fragment` 之后可用
|
||
|
||
```glsl
|
||
// 在替换 #include <transmission_fragment> 时
|
||
// 原始代码自带 #ifdef USE_TRANSMISSION，替换代码也必须包含
|
||
#ifdef USE_TRANSMISSION
|
||
// ... 你的代码
|
||
#endif
|
||
```
|
||
|
||
### 4. 变量名冲突
|
||
|
||
注入的全局函数/变量可能与 Three.js 内部冲突：
|
||
- 避免使用 `hash`, `random`, `noise` 等通用名
|
||
- 自定义函数加前缀：`snoise` → OK，`random` → 可能冲突
|
||
- uniform 名称加前缀 `u`：`uDistortion`, `uNoiseTime`
|
||
|
||
## 推荐模式
|
||
|
||
### 安全注入：修改 normal 而不替换整个 chunk
|
||
|
||
```javascript
|
||
material.onBeforeCompile = (shader) => {
|
||
shader.uniforms.uDistortion = { value: 0 };
|
||
shader.uniforms.uNoiseTime = { value: 0 };
|
||
|
||
// 在 fragment shader 最前面加 uniform 声明 + 工具函数
|
||
shader.fragmentShader = `
|
||
uniform float uDistortion;
|
||
uniform float uNoiseTime;
|
||
${noiseGLSL}
|
||
` + shader.fragmentShader;
|
||
|
||
// 在 transmission_fragment 之前插入法线扰动
|
||
shader.fragmentShader = shader.fragmentShader.replace(
|
||
'#include <transmission_fragment>',
|
||
`
|
||
#ifdef USE_TRANSMISSION
|
||
{
|
||
// 扰动 normal 影响折射方向
|
||
if (uDistortion > 0.0) {
|
||
normal = normalize(normal + uDistortion * vec3(
|
||
snoiseFractal(vWorldPosition * 0.08 + vec3(uNoiseTime)),
|
||
snoiseFractal(vWorldPosition.zxy * 0.08 - vec3(uNoiseTime)),
|
||
snoiseFractal(vWorldPosition.yxz * 0.08)
|
||
));
|
||
}
|
||
}
|
||
#endif
|
||
#include <transmission_fragment>
|
||
`
|
||
);
|
||
};
|
||
```
|
||
|
||
### 完整替换：需要随机多采样 + 色差时
|
||
|
||
当需要 MeshTransmissionMaterial 的颗粒感（随机采样噪声）和色差效果时，
|
||
必须完整替换 `#include <transmission_fragment>`。关键点：
|
||
|
||
1. 保留 `#ifdef USE_TRANSMISSION` / `#endif` 包裹
|
||
2. 保留 transmissionMap 和 thicknessMap 的 `#ifdef` 块
|
||
3. 使用正确版本的 `getIBLVolumeRefraction` 签名
|
||
4. 自己处理色差时，传 `dispersion = 0.0`，用不同 IOR 采样 R/G/B
|
||
5. 低采样数（6）+ 每像素随机偏移 → 产生可见的胶片颗粒感
|
||
|
||
## 视觉效果来源速查
|
||
|
||
| 效果 | 来源 | 实现方式 |
|
||
|------|------|----------|
|
||
| 玻璃折射 | MeshPhysicalMaterial `transmission` | Three.js 内置 |
|
||
| 色差 (chromatic aberration) | 不同 IOR 采样 R/G/B | 替换 transmission_fragment |
|
||
| 胶片颗粒感 | 低采样数 + 每像素随机方向 | 替换 transmission_fragment |
|
||
| 有机扭曲 | simplex noise 扰动法线/折射方向 | onBeforeCompile 注入 |
|
||
| 颜色偏移 | `dispersion` 属性 (r167+) | MeshPhysicalMaterial 内置 |
|