threejs-ambient-contact-shading

环境接触阴影

AO 是间接光照的可见度。它可以衰减间接漫反射和环境／镜面反射响应。不要用 AO 乘以直接光、发光、UI 或已经过色调映射的帧。最终图像会通过间接光照发生变化；应在固定曝光下，使用独立的场景线性项测试直接光／发光的不变性，而不是要求最终 RGB 保持不变。

$threejs-choose-skills 是可选的多系统协调器。当 AO 与深度、法线、速度、历史记录或最终输出所有权共享时，请使用 $threejs-image-pipeline。

1. 选择环境可见度分支

使用第一个满足条件的分支：

条件	分支	结果
所需遮蔽是静态／局部的，且可在资源中创作	材质 aoMap / aoNode	一次前向渲染；没有动态物体间接触。
需要动态屏幕接触，且渲染器能单独提供间接光照	将 GTAO 可见度应用于该项	仍可能只需一次几何体遍历。
Stock forward NodeMaterial 需要动态接触，且完整边际成本符合要求	深度／法线通道 -> GTAO -> 可选重建 -> 使用 builtinAOContext() 的第二次光照通道	正确的应用位置需要两次场景遍历。
前面的分支都不满足质量和成本要求	不使用屏幕空间 AO	保留材质、直接阴影和轮廓可读性。

r185 GTAONode 需要先有当前深度／法线，AO 才能生成，而光照过程中必须存在 builtinAOContext()。除非有通过一致性验证的纯深度／法线通道取代，否则应将第一次通道视为完整的材质／变形／Alpha 测试场景通道。

**完成条件：**所选分支明确指出间接光照的所有者，并且计入所有新增通道／附件的成本，或记录省略了屏幕空间 AO。

2. 固定输入契约

• 初始化渲染器，并要求在创建图之前使用 WebGPU 后端。默认的 r185 图要求使用透视、非对数标准深度。正交、对数、反向深度和子视口适配器必须验证所有深度／法线重建、视线方向、天空和排序规则。
• 定义不透明遮挡物、不透明接收面、Alpha 覆盖，并选择一种透明策略：不使用屏幕空间 AO、使用创作好的材质 AO，或使用经过验证的自定义光照模型。Stock builtinAOContext() 会跳过透明材质。
• 将 AO 绑定到活动视图的 screenUV、绘制缓冲区尺寸和投影。每个独立视图都使用单独的有状态节点。宽度和高度分别处理，允许正数取整后的目标尺寸；零尺寸视图应暂停，而不是发布无效 AO。
• 仅当边缘测试场景和目标耗时均通过时，才为低分辨率原始 AO 选择深度重建法线。当 MRT 法线可共享、重建开销已落实、平滑／薄几何体未通过测试，或实测附件增量成本更低时，选择 MRT 法线。
• 使用世界单位表示物理接触半径： radiusRender = radiusMeters * renderUnitsPerMeter，有量纲的厚度和偏差也使用相同的换算。创作外观分支则声明仅使用场景单位的控件，并在资源／世界缩放后重新验证。

当其他系统提供缩放、运动或资源时，在使用这些输入前，先绑定单位、坐标系、当前／先前呈现时间、权威来源、版本、资源代次、有效性和重置条件。

**完成条件：**明确深度约定、屏幕坐标、法线来源、透明度、缩放含义以及每个外部生产方，并确保它们在量纲上兼容。

3. 实现标量可见性

按以下顺序构建选定的屏幕空间分支：

shared-or-AO-owned depth + optional normal/velocity
  -> GTAO scalar visibility
  -> optional materialized edge-aware reconstruction
  -> indirect-light application
  -> optional temporal resolve over the matching admitted layers
  -> excluded-layer composition only when those layers were separated
  -> one tone-map/output-transform owner

• 复用共享场景通道；不要为 AO 创建第二个 G-buffer。
• 原始降分辨率 AO 使用普通纹理过滤，而非双边重建。边缘效果不佳时，使用经过验证并已物化的重建结果一次，然后通过 screenUV 采样。已安装的降噪器需要应用参考实现中的索引／旋转校正；仅使用标准构造并不足以通过验证。原始／全分辨率 AO 或省略 AO 仍是可选方案。
• 在网格材质图中，使用 screenUV 显式采样原始和重建后的可见性；隐式纹理坐标会解析为网格 UV。
• 在非时序光照通道中保留标准透明／透射渲染；builtinAOContext() 已跳过透明材质。只有在进行时序解析或已有自有外部合成器时，才使用仅包含不透明物体的光照通道加独立图层合成。计算其全部成本；当合成器由多个用途共享时，AO 只计入边际成本。
• 标量可见性保持单通道。禁用 AO 时替换输出图并将 RenderPipeline 标记为脏，确保非活动工作不可达。保留所有自有噪声、重建目标和材质句柄；基类节点的释放不会递归进行，标准 AO 的释放也不会清除其噪声。

实现 GTAO 或选择重建方式时，请阅读 r185 GTAO 管线 和其重建权衡。

**完成条件：**活动图只有一个深度／法线所有者，可见性在屏幕空间中采样，AO 只影响间接光照，且关闭 AO 后会移除所有 AO 通道和依赖项。

4. 仅在历史记录有效时启用时序滤波

GTAONode.useTemporalFiltering 会旋转采样，但不会创建或重投影历史记录。只有在存在运行中的 TRAA／自定义解析、有效的相机和物体运动（包括变形／实例化／Alpha 覆盖）、匹配的美术／深度／速度尺寸和图层成员资格，以及拒绝和重置行为时，才启用该功能。只解析那些由深度和速度信号表示的图层。之后再合成排除的透明或折射图层；只有在证明它们具有匹配的深度、运动、覆盖和拒绝行为后，才将其纳入解析。

在相机／投影切换、未补偿的重定位、几何或覆盖不连续、AO 参数／比例／分辨率变更以及质量迁移时，重置或重新播种。r185 TRAANode 没有公开的相机切换重置接口：需重新构建并释放该节点、替换输出图，并将管线标记为脏。

选择时序 AO 时，构建历史记录之前请阅读 时序契约。

**完成条件：**美术、深度和速度覆盖相同的纳入图层；任何排除的透明／折射图层都在解析后合成；移动遮挡物、显露区域、相机切换、调整大小和 AO 参数变更测试用例均通过明确的拒绝／重置测试，否则禁用时序 AO。

5. 仅在标量 AO 通过后添加弯折法线

弯折法线是按可见性加权的未遮挡方向均值。只有在标量 AO 已通过、方向性环境响应清晰可见且确有需要，并且单墙测试用例证明方向指向受阻半球的反方向时，才添加此分支。

选择弯折法线时，请阅读 弯折法线契约，了解基底、滤波、归一化、存储和符号检查。

**完成条件：**标量可见性仍可独立使用，方向恰好变换一次，且单墙测试用例通过；否则保持禁用方向性用途。

6. 验证完成后的图形

对于启用的屏幕空间分支，捕获原始深度、选定的法线输入、准入时的原始／重建 AO、间接光照贡献、直接光照／自发光残差、存在时的速度／历史拒绝，以及关闭 AO 的情况。测试 UV 不变性、细薄轮廓、透明交叉、平滑曲线、屏幕边缘、非对称投影、存在时的运动、调整大小，以及释放／重新创建。

对于作者指定的材质 AO，则验证指定的 UV 集、资产／世界缩放，以及仅作用于间接光照的位置。对于省略屏幕空间 AO 的情况，记录不存在可访问的屏幕空间 AO 通道、附件、历史或依赖项。

**完成条件：**直接光照和自发光保持不变；所选分支的每个测试场景均通过；启用的屏幕空间分支没有非预期的随 UV 变化、跨边缘光晕、抖动或拖影；关闭 AO 或省略 AO 时，屏幕空间 AO 工作量为零；目标设备上的额外耗时和资源使用符合要求；重新创建后资源计数恢复至基线。

归属

此技能负责标量 GTAO、重建方式、间接光照放置、时序处理资格、弯曲法线和 AO 诊断。图像管线负责人负责共享 MRT、全局通道顺序、历史基础设施、色调映射、输出转换和自适应分辨率。