[shader("raygeneration")]
void RayGen()
{
    // 1. 获取当前像素坐标
    uint2 pixelPos = DispatchRaysIndex().xy;

    // 2. 初始化工作上下文 (WorkingContext)
    PathTracer::WorkingContext workingContext = getWorkingContext( pixelPos );

    // 根据不同的路径追踪模式进行初始化
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_REFERENCE
    // 对于非参考模式，启动稳定平面相关的路径追踪过程
    workingContext.stablePlanes.StartPathTracingPass();
#endif

#if PATH_TRACER_MODE!=PATH_TRACER_MODE_FILL_STABLE_PLANES
    // 对于非填充稳定平面模式，重置调试信息
    workingContext.debug.Reset(0); 
#endif

    // 子采样索引，这里固定为0，注释表明是为了降噪引导缓冲区的稳定性
    uint subSampleIndex = 0; 

    // PathState 用于存储和管理一条光路的所有状态信息
    PathState path;

    // 3. 初始化路径状态并设置主光线
    //    - EmptyPathInitialize: 初始化路径的基本状态 (如像素ID，相机像素锥角等)
    //    - computeCameraRay: 根据像素位置计算相机光线
    //    - SetupPathPrimaryRay: 将计算出的相机光线设置到path状态中
    path = PathTracer::EmptyPathInitialize(pixelPos, g_Const.ptConsts.camera.PixelConeSpreadAngle);
    PathTracer::SetupPathPrimaryRay(path, Bridge::computeCameraRay(pixelPos, /*subSampleIndex*/0));

    // 4. 【可选】根据稳定平面模式处理首次命中
#if PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES
    // 如果是 PATH_TRACER_MODE_FILL_STABLE_PLANES 模式，
    // 光线的首次命中信息会从预计算的“基础稳定平面”(base stable plane, index 0)加载，
    // 而不是实际追踪主光线。这是一种优化手段，可以复用之前计算的结果。
    firstHitFromBasePlane(path, 0, workingContext);
    // lastOrigin = path.origin; // 记录光线起点，这里被注释掉了
#endif

    // 初始化用于构建稳定平面的次表面位置法线信息 (如果处于该模式)
#if PATH_TRACER_MODE_BUILD_STABLE_PLANES==1
    u_SecondarySurfacePositionNormal[pixelPos] = 0;
#endif

    // 5. 主路径追踪循环
    //    只要光线路径仍然有效 (isActive)，就继续调用 nextHit 进行下一次弹射处理
    while (path.isActive())
        nextHit(path, workingContext, false); // false 参数表示不跳过稳定平面探索
    
    // 6. 数据清理：处理 NaN 或 无穷大值
    //    防止计算过程中出现非法数值导致最终结果异常
    SanitizeNaNs(path, workingContext);
        
    // 7. 【可选】根据稳定平面模式提交降噪器相关的光照信息
#if PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES
    workingContext.stablePlanes.CommitDenoiserRadiance(path.getStablePlaneIndex(), path.denoiserSampleHitTFromPlane,
        path.denoiserDiffRadianceHitDist, path.denoiserSpecRadianceHitDist,
        path.secondaryL, path.hasFlag(PathFlags::stablePlaneBaseScatterDiff),
        path.hasFlag(PathFlags::stablePlaneOnDeltaBranch),
        path.hasFlag(PathFlags::stablePlaneOnDominantBranch));
#endif    

    // 8. 根据不同的路径追踪模式，计算最终的路径光照贡献
    float3 pathRadiance;
#if PATH_TRACER_MODE==PATH_TRACER_MODE_REFERENCE
    // 参考模式：直接使用路径累计的光照 (path.L)
    pathRadiance = path.L;
#elif PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES
    // 构建稳定平面模式：完成稳定平面的构建过程，并返回相应光照
    pathRadiance = workingContext.stablePlanes.CompletePathTracingBuild(path.L);
#elif PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES
    // 填充稳定平面模式：使用稳定平面数据完成光照计算
    pathRadiance = workingContext.stablePlanes.CompletePathTracingFill(g_Const.ptConsts.denoisingEnabled);
#endif
        
    // 调试相关的可视化功能 (如果启用)
#if PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES && ENABLE_DEBUG_DELTA_TREE_VIZUALISATION
    DeltaTreeVizExplorePixel(workingContext, 0);
    return; // 调试可视化时可能直接返回
#endif

    // 9. 输出最终颜色
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_BUILD_STABLE_PLANES
    // 如果不是构建稳定平面模式，则将计算得到的 pathRadiance 写入输出纹理 u_Output
    // alpha 设置为 1 对截图很重要
    u_Output[pixelPos] = float4( pathRadiance, 1 );    
#endif

    // 下面是一些调试打印的示例代码，已被注释
    // ...
}

void nextHit(inout PathState path, const PathTracer::WorkingContext workingContext, uniform bool skipStablePlaneExploration)
{
// Conditionally use Hit Object Extension (RayQuery) or standard TraceRay
#if USE_HIT_OBJECT_EXTENSION
    RayDesc ray; RayQuery<RAY_FLAG_NONE> rayQuery;
    PackedHitInfo packedHitInfo; uint SERSortKey;

    // 1. 准备并追踪散射光线
    // Bridge::traceScatterRay 会从 PathState 中获取上一 bounces 的散射光线信息，
    // 初始化 ray 和 rayQuery，并执行 TraceRayInline。
    // 如果有命中，ray.TMax 会被更新为实际的命中距离。
    Bridge::traceScatterRay(path, ray, rayQuery, packedHitInfo, SERSortKey, workingContext.debug);

    NvHitObject hit; // NVAPI Hit Object
    if (rayQuery.CommittedStatus() != COMMITTED_TRIANGLE_HIT)
    {
        // 2a. 未命中 (Miss)
        // 如果 RayQuery 没有命中三角形，则内联调用 HandleMiss 处理。
        PathTracer::HandleMiss(path, ray.Origin, ray.Direction, ray.TMax, workingContext );
    }
    else
    {
        // 2b. 命中 (Hit)
        // 构建内置的三角形交叉属性
        BuiltInTriangleIntersectionAttributes attrib;
        attrib.barycentrics = rayQuery.CommittedTriangleBarycentrics();

        // 使用 NvMakeHitWithRecordIndex 创建一个 HitObject。
        // 这个 HitObject 封装了命中信息，并将用于调用正确的 ClosestHit 着色器。
        // RecordIndex 用于 Shader Binding Table (SBT) 索引。
        NvMakeHitWithRecordIndex( rayQuery.CommittedInstanceContributionToHitGroupIndex()+rayQuery.CommittedGeometryIndex(), SceneBVH, rayQuery.CommittedInstanceIndex(), rayQuery.CommittedGeometryIndex(), rayQuery.CommittedPrimitiveIndex(), 0, ray, attrib, hit );
        
        uint vertexIndex = path.getVertexIndex();
        PathPayload payload = PathPayload::pack(path); // 将 PathState 打包到 payload

        // Shader Execution Reordering (SER) - 可选的着色器执行重排序优化
#if SER_USE_SORTING
        if (workingContext.ptConsts.enableShaderExecutionReordering)
#if SER_USE_MANUAL_SORT_KEY
            NvReorderThread(SERSortKey, 16); // 使用手动生成的排序键
#else
            NvReorderThread(hit, 0, 0);      // 使用基于命中属性的启发式排序键
#endif
#endif // SER_USE_SORTING

        // 调用 HitObject 对应的 ClosestHit 着色器
        NvInvokeHitObject(SceneBVH, hit, payload);
        path = PathPayload::unpack(payload, PACKED_HIT_INFO_ZERO); // 从 payload 解包更新后的 PathState
    }
#else // Fallback to standard TraceRay if Hit Object Extension is not used
    // 1. 获取散射光线
    RayDesc ray = path.getScatterRay().toRayDesc(); // 从 PathState 获取要追踪的光线
    PathPayload payload = PathPayload::pack(path);   // 打包 PathState

    // 2. 执行标准 TraceRay
    // 这会调用 DXR 管线中的 ClosestHit 或 Miss 着色器
    TraceRay( SceneBVH, RAY_FLAG_NONE, 0xff, 0, 1, 0, ray, payload );
    
    // 3. 解包 PathState
    path = PathPayload::unpack(payload, PACKED_HIT_INFO_ZERO);
#endif

// --- 稳定平面探索 (Stable Plane Exploration) ---
// (仅在 PATH_TRACER_MODE_BUILD_STABLE_PLANES 模式下)
#if PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES 
    int nextPlaneToExplore;
    // 如果当前路径已经终止 (isActive() == false) 并且还有稳定平面需要探索
    if (!path.isActive() && (nextPlaneToExplore=workingContext.stablePlanes.FindNextToExplore(path.getStablePlaneIndex()+1))!=-1 )
    {
        // 保存当前累积的非噪声光照
        float3 prevL = path.L; 
        PathPayload payloadForNewExploration;
        // 开始探索新的稳定平面，这会重置或初始化一个新的 PathState 到 payloadForNewExploration
        workingContext.stablePlanes.ExplorationStart(nextPlaneToExplore, payloadForNewExploration.packed);
        path = PathPayload::unpack(payloadForNewExploration, PACKED_HIT_INFO_ZERO);
        path.L = prevL; // 恢复之前累积的非噪声光照，继续在其上累加
        
        // 调试代码示例，用于可视化特定稳定平面的内容
		// #if 0 
        // if (path.getStablePlaneIndex()==1)
        //     workingContext.debug.DrawDebugViz( float4( DbgShowNormalSRGB(path.dir), 1 ) );
        // #endif
    }
#endif
}

#if PATH_TRACER_MODE!=PATH_TRACER_MODE_REFERENCE // 这个函数在非参考模式下才可能被定义和使用
void firstHitFromBasePlane(inout PathState path, const uint basePlaneIndex, const PathTracer::WorkingContext workingContext)
{
    // 1. 从稳定平面加载数据
    //    这些数据包括：打包的命中信息(packedHitInfo)、光线方向(rayDir)、场景长度(sceneLength)即命中距离、
    //    吞吐量(thp)等。这些都是之前在构建稳定平面阶段计算并存储的。
    PackedHitInfo packedHitInfo; float3 rayDir; uint vertexIndex; uint SERSortKey; uint stableBranchID; float sceneLength; float3 thp; float3 motionVectors;
    workingContext.stablePlanes.LoadStablePlane(workingContext.pixelPos, basePlaneIndex, vertexIndex, packedHitInfo, SERSortKey, stableBranchID, rayDir, sceneLength, thp, motionVectors);

    // 2. 重建光线描述 (RayDesc)
    RayDesc ray;
    ray.Direction = rayDir; // 使用加载的方向
    // Origin 仍然使用 path 中由 SetupPathPrimaryRay 初始化的相机位置。
    // 注释警告：对于非主光线的弹射，这个 origin 是不正确的，但这里是处理主光线替换。
    ray.Origin    = path.origin; 
    ray.TMin      = 0;
    ray.TMax      = sceneLength; // 使用加载的命中距离作为 TMax

    // 路径顶点索引调整，因为我们将直接处理这次命中
    path.setVertexIndex(vertexIndex-1); 

    // 3. 更新 PathState 以反映这是基于稳定平面的命中
    path.setFlag(PathFlags::stablePlaneOnPlane , true);
    path.setFlag(PathFlags::stablePlaneOnBranch, true);
    path.setStablePlaneIndex(basePlaneIndex);
    path.stableBranchID = stableBranchID;
    path.thp = thp; // 设置加载的吞吐量

#if PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES
    // 加载主导稳定平面索引，并设置相应标志位
    const uint dominantSPIndex = workingContext.stablePlanes.LoadDominantIndexCenter();
    path.setFlag(PathFlags::stablePlaneOnDominantBranch, dominantSPIndex == basePlaneIndex );
    // 重置从稳定平面开始的弹射计数器和降噪器相关数据
    path.setCounter(PackedCounters::BouncesFromStablePlane, 0);
    path.denoiserSampleHitTFromPlane = 0.0;
    path.denoiserDiffRadianceHitDist = lpfloat4(0,0,0,0);
    path.denoiserSpecRadianceHitDist = lpfloat4(0,0,0,0);
#endif

    // 4. 处理加载的命中信息
    if (!IsValid(packedHitInfo)) // IsValid 是一个辅助宏或函数，检查 packedHitInfo 是否有效
    {
        // 4a. 无效命中 (视为 Miss)
        // 直接内联调用 HandleMiss，使用重建的光线信息。
        PathTracer::HandleMiss(path, ray.Origin, ray.Direction, ray.TMax, workingContext);
    }
    else
    {
        // 4b. 有效命中 (Hit)
#if USE_HIT_OBJECT_EXTENSION
        // 使用 Hit Object 扩展
        NvHitObject hit;
        // (IsValid(packedHitInfo) 已在上层 if 确认)
        const TriangleHit triangleHit = TriangleHit::make(packedHitInfo); // 解包为 TriangleHit
        const uint instanceIndex    = triangleHit.instanceID.getInstanceIndex();
        const uint geometryIndex    = triangleHit.instanceID.getGeometryIndex();
        const uint primitiveIndex   = triangleHit.primitiveIndex;
    
        BuiltInTriangleIntersectionAttributes attrib;
        attrib.barycentrics = triangleHit.barycentrics;
        // 创建 HitObject
        NvMakeHit( SceneBVH, instanceIndex, geometryIndex, primitiveIndex, 0, 0, 1, ray, attrib, hit );

        // 可选的 Shader Execution Reordering (SER)
        // 注释提到：首次弹射的排序通常对性能帮助不大，因为光线此时还比较相干。
#if 0 && SER_USE_SORTING 
        if (workingContext.ptConsts.enableShaderExecutionReordering) 
#if SER_USE_MANUAL_SORT_KEY
            NvReorderThread(SERSortKey, 16);    
#else
            NvReorderThread(hit, 0, 0);
#endif
#endif // SER_USE_SORTING

        PathPayload payload = PathPayload::pack(path);
        // 调用 HitObject 对应的 ClosestHit 着色器
        NvInvokeHitObject(SceneBVH, hit, payload);
        path = PathPayload::unpack(payload, PACKED_HIT_INFO_ZERO);
#else
        // 不使用 Hit Object 扩展时的兼容性“hack”
        // 目的是重新投射一条极短的光线，以确保能正确触发 DXR 管线中的 ClosestHit 着色器。
        float3 surfaceHitPosW; float3 surfaceHitFaceNormW;    
        // 加载表面位置和法线
        Bridge::loadSurfacePosNormOnly(surfaceHitPosW, surfaceHitFaceNormW, TriangleHit::make(packedHitInfo), workingContext.debug);    
        bool frontFacing = dot( -ray.Direction, surfaceHitFaceNormW ) >= 0.0;

        // 计算一个新的光线起点，稍微偏离表面，确保能再次命中同一三角形
        float3 newOrigin = ComputeRayOrigin(surfaceHitPosW, (frontFacing)?(surfaceHitFaceNormW):(-surfaceHitFaceNormW)) - ray.Direction * 8e-5;

        // 更新路径已行进的距离，因为我们“跳过”了从相机到 newOrigin 的这段距离
        PathTracer::UpdatePathTravelled(path, ray.Origin, ray.Direction, length(newOrigin-ray.Origin), workingContext, false, false); 

        ray.Origin = newOrigin; // 更新光线起点为这个微调后的位置
        // ray.TMax 保持不变 (sceneLength)，因为我们知道命中点在此距离内。
    
        PathPayload payload = PathPayload::pack(path);
        // 用这条极短的光线调用 TraceRay
        TraceRay( SceneBVH, RAY_FLAG_NONE, 0xff, 0, 1, 0, ray, payload );
        path = PathPayload::unpack(payload, PACKED_HIT_INFO_ZERO);
#endif // USE_HIT_OBJECT_EXTENSION
    }
}
#endif

// 定义 ClosestHit 着色器变体的宏
// name: 着色器名称后缀
// NoTextures: 是否忽略纹理采样的提示
// NoTransmission: 是否忽略透射计算的提示
// OnlyDeltaLobes: 是否只处理理想镜面/透射（Delta lobes）的提示
#define CLOSEST_HIT_VARIANT( name, NoTextures, NoTransmission, OnlyDeltaLobes )      \
[shader("closesthit")] void ClosestHit##name(inout PathPayload payload : SV_RayPayload, in BuiltInTriangleIntersectionAttributes attrib) \
{ \
    /* 从每个实例的附加数据中提取预计算的 SERSortKey (Shader Execution Reordering Sort Key) */ \
    uint SERSortKey = t_SubInstanceData[InstanceID()+GeometryIndex()].FlagsAndSERSortKey & 0xFFFF; \
    /* 调用核心的 HandleHit 函数，并传入优化提示和打包的命中信息 */ \
    HandleHit( PathTracer::OptimizationHints::make( NoTextures, NoTransmission, OnlyDeltaLobes, SERSortKey ), TriangleHit::make( InstanceIndex(), GeometryIndex(), PrimitiveIndex(), attrib.barycentrics ).pack(), payload); \
}

// 根据不同的优化组合生成8个 ClosestHit 着色器变体
// 例如，ClosestHit000, ClosestHit001, ..., ClosestHit111
#if 1 // 3bit 8-variant version
CLOSEST_HIT_VARIANT( 000, false, false, false ); // 无优化提示
CLOSEST_HIT_VARIANT( 001, false, false, true  ); // 只处理Delta Lobes
CLOSEST_HIT_VARIANT( 010, false, true,  false ); // 忽略透射
// ... 等等
CLOSEST_HIT_VARIANT( 111, true,  true,  true  ); // 忽略纹理、忽略透射、只处理Delta Lobes
#endif

// 被 ClosestHit 着色器直接调用的版本
void HandleHit(const uniform PathTracer::OptimizationHints optimizationHints, const PackedHitInfo packedHitInfo, inout PathPayload payload)
{
    PathState path = PathPayload::unpack(payload, packedHitInfo); // 解包 PathState，并将当前命中信息设置进去
    PathTracer::WorkingContext workingContext = getWorkingContext(PathIDToPixel(path.id)); // 获取工作上下文
    // 调用另一个 HandleHitUnpacked，传入解包后的参数和 DXR 系统变量
    HandleHitUnpacked(optimizationHints, packedHitInfo, path, WorldRayOrigin(), WorldRayDirection(), RayTCurrent(), workingContext);
    payload = PathPayload::pack( path ); // 将可能已更新的 PathState 重新打包回 payload
}

// 进一步解包，并最终调用 PathTracer 命名空间内的核心 HandleHit
void HandleHitUnpacked(const uniform PathTracer::OptimizationHints optimizationHints, const PackedHitInfo packedHitInfo, inout PathState path, float3 worldRayOrigin, float3 worldRayDirection, float rayT, const PathTracer::WorkingContext workingContext)
{
    // 重新设置 path 中的 origin 和 dir，因为 PathPayload 为了减少寄存器压力可能没有携带它们。
    // 这些值从 DXR 的 WorldRayOrigin() 和 WorldRayDirection() 获取，代表了当前 TraceRay 指令的光线。
    path.origin = worldRayOrigin;
    path.dir = worldRayDirection;
    path.setHitPacked( packedHitInfo ); // 再次确认命中信息
    PathTracer::HandleHit(optimizationHints, path, worldRayOrigin, worldRayDirection, rayT, workingContext); // 调用 PathTracer.hlsli 中的核心 HandleHit
}

// PathTracer/PathTracer.hlsli
namespace PathTracer
{
    // ... (其他函数) ...

    // 目前只支持 TriangleHit；未来需要时会添加更多类型
    inline void HandleHit(const uniform OptimizationHints optimizationHints, inout PathState path, const float3 rayOrigin, const float3 rayDir, const float rayTCurrent, const WorkingContext workingContext)
    {
        // 1. 更新路径已行进的距离和相关状态 (如光线锥)
        UpdatePathTravelled(path, rayOrigin, rayDir, rayTCurrent, workingContext);
        
        const uint2 pixelPos = PathIDToPixel(path.id);
        // 初始化当前路径顶点的随机数生成器种子
        const SampleGeneratorVertexBase sampleGeneratorVertexBase = SampleGeneratorVertexBase::make(pixelPos, path.getVertexIndex(), Bridge::getSampleIndex() );
        
#if ENABLE_DEBUG_VIZUALISATION
        const bool debugPath = workingContext.debug.IsDebugPixel();
#else
        const bool debugPath = false;
#endif

        // ----- 命中时的主要步骤概述 -----
        // - 加载顶点/材质数据
        // - 如果 path.getVertexIndex() > 1 (非首次命中) 且命中自发光表面，计算 MIS 权重
        // - 累加自发光辐射亮度
        // - 使用阴影光线采样光源 (直接光照)
        // - 采样散射光线或终止路径

        // (关于如何判断“首次命中”在有 Primary Surface Replacement 时的讨论注释)

        // 2. 加载表面和材质数据
        const TriangleHit triangleHit = TriangleHit::make(path.hitPacked); // 从 path 中解包命中信息
        // Bridge::loadSurface 是一个非常关键的调用：
        // 它会根据 triangleHit 加载所有必要的表面属性，如位置、法线、切线、UV坐标。
        // 同时，它会加载材质属性（反照率、粗糙度、金属度、自发光、折射率等），
        // 并根据材质类型（如漫反射、镜面、玻璃等）构建一个 ActiveBSDF 对象。
        // optimizationHints (来自 ClosestHit 变体) 和 path.rayCone (光线锥信息，可用于纹理LOD) 会被传入。
        SurfaceData bridgedData = Bridge::loadSurface(optimizationHints, triangleHit, rayDir, path.rayCone, path.getVertexIndex(), pixelPos, workingContext.debug);

        // (调试 RayCone 数据的示例代码)

        // 3. 处理体积吸收 (Volume Absorption)
        float volumeAbsorption = 0; // 用于统计
        if (!path.interiorList.isEmpty()) // 如果光线当前在某个体积内部
        {
            const uint materialID = path.interiorList.getTopMaterialID(); // 获取最内层体积的材质ID
            const HomogeneousVolumeData hvd = Bridge::loadHomogeneousVolumeData(materialID); // 加载均匀体积数据
            const float3 transmittance = HomogeneousVolumeSampler::evalTransmittance(hvd, rayTCurrent); // 计算这段距离的透射率
            volumeAbsorption = 1 - luminance(transmittance);
            UpdatePathThroughput(path, transmittance); // 根据透射率衰减路径的吞吐量 (throughput)
        }

        // 4. 处理嵌套电介质 (Nested Dielectrics)
        // HandleNestedDielectrics 对于正确渲染具有多个界面的透明对象（如玻璃杯中的水）至关重要。
        // 它会更新 path.interiorList (当光线进入/离开体积时推入/弹出材质ID)。
        // 它可以拒绝“假命中”：例如，由于薄壁近似或接口逻辑，某些命中应被忽略，光线应视为穿过。
        // 还会根据当前介质更新 bridgedData.shadingData.IoR (外部折射率)。
        bool rejectedFalseHit = !HandleNestedDielectrics(bridgedData, path, workingContext);

        // (Delta Tree 可视化调试相关的代码块，如果命中被拒绝则返回)
#if PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES && ENABLE_DEBUG_DELTA_TREE_VIZUALISATION
        if (path.hasFlag(PathFlags::deltaTreeExplorer))
        {
            DeltaTreeVizHandleHit(path, rayOrigin, rayDir, rayTCurrent, bridgedData, rejectedFalseHit, HasFinishedSurfaceBounces(path), volumeAbsorption, workingContext);
            return;
        }
#endif
        if (rejectedFalseHit) // 如果是假命中，则忽略此次交互，光线实质上继续传播
            return;

        // 获取着色数据和BSDF的快捷方式
        const ShadingData shadingData = bridgedData.shadingData;
        const ActiveBSDF bsdf = bridgedData.bsdf;

        // (更多调试可视化代码：切线空间、光线锥足迹等)

        // 获取BSDF属性，如漫反射/镜面反射率、自发光等
        BSDFProperties bsdfProperties = bsdf.getProperties(shadingData);

        // 5. 累加自发光表面辐射 (Emissive Surface Handling)
        float3 surfaceEmission = 0.0;
        // 解包之前NEE步骤中存储的MIS信息 (如果上一 bounces 做了NEE且恰好采样到了当前这个自发光面)
        NEEBSDFMISInfo misInfo = NEEBSDFMISInfo::Unpack16bit(path.packedMISInfo);

        // 检查是否应该忽略此三角形的自发光，以及它是否有自发光
        if ( !(misInfo.SkipEmissiveBRDF && !path.wasScatterTransmission()) && (any(bsdfProperties.emission>0)) )
        {
            float misWeight = 1.0f; // 多重重要性采样 (MIS) 权重
            // 如果启用了光源采样 (NEE) 并且当前是通过BSDF采样命中的 (path.bsdfScatterPdf != 0)
            if( misInfo.LightSamplingEnabled && path.bsdfScatterPdf != 0 )
            {
                // 创建光源采样器
                // this is the NEE light sampler configured same as it was at previous vertex (previous vertex's "next event estimation" matches this light "event")
                LightSampler lightSampler = Bridge::CreateLightSampler( workingContext.pixelPos, misInfo.LightSamplingIsIndirect, workingContext.debug.IsDebugPixel() );
                // 计算 BSDF 路径命中自发光体的 MIS 权重
                misWeight = lightSampler.ComputeBSDFMISForEmissiveTriangle(bridgedData.neeLightIndex, path.bsdfScatterPdf, path.origin, shadingData.posW, misInfo.NarrowNEESamples, misInfo.TotalSamples);
                
                // (向光源采样器提供反馈，用于自适应光源采样)
                float simpleRandom = Hash32ToFloat( Hash32Combine( Hash32Combine(Hash32(path.getVertexIndex() + 0x0367C2C7), path.id), Bridge::getSampleIndex() ) );
                lightSampler.InsertFeedbackFromBSDF(bridgedData.neeLightIndex, average(path.thp*bsdfProperties.emission), misWeight, simpleRandom ); // 注意这里用 bsdfProperties.emission 更合理
            }

            surfaceEmission = bsdfProperties.emission * misWeight; // 应用MIS权重
            if( workingContext.ptConsts.fireflyFilterThreshold != 0 ) // 飞火过滤
                surfaceEmission = FireflyFilter(surfaceEmission, workingContext.ptConsts.fireflyFilterThreshold, path.fireflyFilterK);
            surfaceEmission *= Bridge::getNoisyRadianceAttenuation(); // 应用噪声衰减 (可能用于多重采样抗锯齿)

            // 如果不是填充稳定平面模式，将自发光贡献累加到路径光照 L
#if PATH_TRACER_MODE != PATH_TRACER_MODE_FILL_STABLE_PLANES 
            if (any(surfaceEmission>0))
                path.L += max( 0.xxx, path.thp*surfaceEmission ); 
#endif
        }
        
        // 6. 路径终止判断 (第一部分：最大深度和稳定平面逻辑)
        bool pathStopping = HasFinishedSurfaceBounces(path); // 检查是否达到最大表面弹射次数
        
        // 如果不是参考模式，调用稳定平面命中处理逻辑
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_REFERENCE
        // StablePlanesHandleHit 是稳定平面优化方案的关键部分。
        // 它可以更新稳定平面数据，将当前光照贡献给稳定平面，
        // 甚至根据稳定平面的状态终止或重定向当前路径。
        // pathStopping 可能会被此函数更新。
        StablePlanesHandleHit(path, rayOrigin, rayDir, rayTCurrent, optimizationHints.SERSortKey, workingContext, bridgedData, volumeAbsorption, surfaceEmission, pathStopping);
#endif

        // 7. 路径终止判断 (第二部分：俄罗斯轮盘赌 Russian Roulette)
        // 如果不是构建稳定平面模式（该模式下路径终止可能已由 StablePlanesHandleHit 处理）
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_BUILD_STABLE_PLANES 
        // HandleRussianRoulette 根据路径吞吐量进行俄罗斯轮盘赌。
        // 如果随机数超过吞吐量，路径终止；否则，吞吐量被放大以补偿。
        // 注意：此函数会更新 path.thp!
        pathStopping |= HandleRussianRoulette(path, sampleGeneratorVertexBase, workingContext); 
#endif

        if (pathStopping) // 如果决定终止路径
        {
            path.terminate(); // 设置路径为非激活状态
            return;           // 结束 HandleHit
        }

        // 如果是构建稳定平面模式，在此处提前返回。
        // 注释说明：在该模式下，自发光已被处理，路径也由 StablePlanesHandleHit 更新或终止，
        // 因此跳过后续的BSDF采样和NEE。
#if PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES    
        return;
#endif    
        
        // 保存散射前的路径状态，主要用于NEE计算时的吞吐量
        const PathState preScatterPath = path; 

        // 8. 生成散射光线 (BSDF Sampling)
        // GenerateScatterRay 是材质交互的核心：
        // - 根据表面材质的 BSDF (双向散射分布函数) 采样一个新的散射方向。
        // - 计算该采样方向的概率密度函数 (PDF)。
        // - 更新路径的起点 (path.origin = shadingData.posW) 和方向 (path.dir = newDir)。
        // - 更新路径吞吐量 (path.thp *= bsdf_color * cos_theta / pdf)。
        // - 返回 ScatterResult，包含是否有效及PDF。
        ScatterResult scatterResult = GenerateScatterRay(shadingData, bsdf, path, sampleGeneratorVertexBase, workingContext);
        
        // 9. 执行下一事件估计 (Next Event Estimation - NEE) / 直接光照采样
#if defined(RTXPT_COMPILE_WITH_NEE) && RTXPT_COMPILE_WITH_NEE!=0
        // HandleNEE 执行直接光照采样：
        // - 选择一个或多个光源。
        // - 从当前命中点向选定的光源投射阴影光线 (shadow ray)。
        // - 如果阴影光线未被遮挡，计算直接光照贡献。
        // - 计算并返回 MIS 相关信息 (neeResult.BSDFMISInfo)，这个信息会被打包到 path.packedMISInfo，
        //   用于下一 bounces 如果恰好通过BSDF采样命中了这个被NEE采样到的光源时，进行MIS加权。
        NEEResult neeResult = HandleNEE(optimizationHints, preScatterPath, shadingData, bsdf, sampleGeneratorVertexBase, workingContext);    
#else
        NEEResult neeResult = NEEResult::empty(); // 如果未编译NEE，则结果为空
#endif
        
        // 存储NEE的MIS信息和BSDF散射的PDF，供下一次弹射使用
        path.packedMISInfo  = (lpuint)neeResult.BSDFMISInfo.Pack16bit();
        path.bsdfScatterPdf = (lpfloat)scatterResult.Pdf;

        lpfloat3 neeDiffuseRadiance, neeSpecularRadiance;
        neeResult.GetRadiances(neeDiffuseRadiance, neeSpecularRadiance); // 获取NEE计算出的漫反射和镜面反射光照
    
        if ( any( (neeDiffuseRadiance+neeSpecularRadiance) > 0 ) ) // 如果NEE有贡献
        {
            neeDiffuseRadiance *= (lpfloat3)Bridge::getNoisyRadianceAttenuation();
            neeSpecularRadiance *= (lpfloat3)Bridge::getNoisyRadianceAttenuation();

#if PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES // 填充稳定平面模式
            // StablePlanesHandleNEE 可能会将NEE的结果与稳定平面数据结合或存储。
            StablePlanesHandleNEE(preScatterPath, path, neeDiffuseRadiance, neeSpecularRadiance, neeResult.RadianceSourceDistance, workingContext);
#else
            // 其他模式下，直接将NEE贡献累加到路径光照 L
            float3 neeContribution = neeDiffuseRadiance + neeSpecularRadiance;
            path.L += max(0.xxx, preScatterPath.thp * neeContribution); 
#endif
        }
        
        // 10. 最终路径终止判断 (基于BSDF散射结果)
        if (!scatterResult.Valid) // 如果BSDF散射无效 (例如，被纯黑材质吸收)
        {
            path.terminate(); // 终止路径
        }
    } // end of PathTracer::HandleHit
} // end of namespace PathTracer

// PathTracer/PathTracerNEE.hlsli
namespace PathTracer
{
    // ... (其他函数) ...
    inline NEEResult HandleNEE(const uniform OptimizationHints optimizationHints, const PathState preScatterPath,
                            const ShadingData shadingData, const ActiveBSDF bsdf, const SampleGeneratorVertexBase sgBase, const WorkingContext workingContext)
    {
        // 1. 判断 BSDF 是否有非 Delta 分布 (例如，漫反射或光泽反射/折射)
        // Delta 分布 (理想镜面/折射) 通常由 BSDF 采样完美处理，不需要 NEE。
        const uint lobes = bsdf.getLobes(shadingData);
        const bool hasNonDeltaLobes = ((lobes & (uint) LobeType::NonDelta) != 0) && (!optimizationHints.OnlyDeltaLobes);

        // (一些性能相关的注释和标志位)
        const bool onDominantBranch = preScatterPath.hasFlag(PathFlags::stablePlaneOnDominantBranch);
        const bool onStablePlane = preScatterPath.hasFlag(PathFlags::stablePlaneOnPlane);

        // 2. 决定是否应用 NEE
        // 条件：全局启用 NEE、优化提示未要求只处理 Delta Lobes、且 BSDF 确实有非 Delta 分布
        const bool applyNEE = (workingContext.ptConsts.NEEEnabled && !optimizationHints.OnlyDeltaLobes) && hasNonDeltaLobes;

        NEEResult result = NEEResult::empty(); // 初始化 NEE 结果为空
        
        if (!applyNEE) // 如果不满足 NEE 条件，直接返回空结果
            return result;
        
        // 3. 检查是否应由 ReSTIR DI (Reservoir-based Spatiotemporal Importance Resampling for Direct Illumination) 处理直接光照
        // ReSTIR DI 是一种更高级的直接光照采样技术，如果启用并适用，可能会取代传统的 NEE。
    #if PATH_TRACER_MODE==PATH_TRACER_MODE_FILL_STABLE_PLANES
        // 在填充稳定平面模式下，如果启用了 ReSTIR DI，并且当前BSDF有非Delta分量，
        // 且位于主导稳定平面上，则应用ReSTIR DI。
        const bool applyReSTIRDI = workingContext.ptConsts.useReSTIRDI && hasNonDeltaLobes && onDominantBranch && onStablePlane;
    #else
        const bool applyReSTIRDI = false;
    #endif
        
        // 如果 ReSTIR DI 负责光照，则跳过此处的 NEE。
        // 当前 RTXDI 主要处理反射；对于首次弹射的透射，由于复杂性，仍不尝试使用NEE，
        // 也考虑到未来 ReSTIR DI 可能支持透射。
        if (applyReSTIRDI)
        {
            // 设置标志位，告知自发光处理部分不要重复计算（因为ReSTIR DI已处理）
            result.BSDFMISInfo.SkipEmissiveBRDF = true; 
            return result; // 返回，不执行后续的NEE
        }

        // 4. 调用核心的多重采样NEE处理函数
        // (onDominantBranch && onStablePlane) ? workingContext.ptConsts.NEEBoostSamplingOnDominantPlane : 0
        // 这个三元操作符为在“主导稳定平面”上的点增加了NEE的采样数量 (sampleCountBoost)
        HandleNEE_MultipleSamples(result, preScatterPath, shadingData, bsdf, sgBase, workingContext, (onDominantBranch&&onStablePlane)?(workingContext.ptConsts.NEEBoostSamplingOnDominantPlane):(0));
        
        // 5. 调试选项：抑制在主表面上的 NEE
        // 如果路径在主导稳定平面上，并且ptConsts中设置了suppressPrimaryNEE，则清零NEE贡献。
        // 这主要用于调试或效果对比，保持MIS信息有效但光照贡献为0。
        const bool suppressNEE = preScatterPath.hasFlag(PathFlags::stablePlaneOnDominantBranch) && preScatterPath.hasFlag(PathFlags::stablePlaneOnPlane) && workingContext.ptConsts.suppressPrimaryNEE;
        if (suppressNEE) 
            result.SetRadiances(0,0); // 清零漫反射和镜面反射光照贡献
        
        return result; // 返回包含直接光照贡献和MIS信息的 NEEResult
    }
}

// PathTracer/PathTracerNEE.hlsli
// 'inoutResult' 参数期望已被初始化为 'NEEResult::empty()'
inline void HandleNEE_MultipleSamples(inout NEEResult inoutResult, const PathState preScatterPath, const ShadingData shadingData, const ActiveBSDF bsdf,    
                                      const SampleGeneratorVertexBase sgBase, const WorkingContext workingContext, int sampleCountBoost)
{
    // 1. 创建光源采样器 (LightSampler)
    // Bridge::CreateLightSampler 根据当前像素位置、光线锥展角与场景长度之比（可能影响采样策略）等创建光源采样器。
    // 光源采样器负责选择光源并生成光源上的采样点。
    LightSampler lightSampler = Bridge::CreateLightSampler( workingContext.pixelPos, preScatterPath.rayCone.getWidth() / preScatterPath.sceneLength, workingContext.debug.IsDebugPixel() );

    // 确定总采样数
    // sampleCountBoost 来自 HandleNEE，可能在主导稳定平面上增加采样。
    // workingContext.ptConsts.NEEFullSamples 是基础采样数。
    // 如果光源采样器为空 (场景中无光源)，则总采样数为0。
    const uint totalSamples = min(RTXPT_LIGHTING_NEEAT_MAX_TOTAL_SAMPLE_COUNT, (!lightSampler.IsEmpty()) ? (sampleCountBoost + workingContext.ptConsts.NEEFullSamples)     : (0));
    if (totalSamples == 0) // 如果没有样本可采，直接返回
        return;

    bool useLowDiscrepancyGen = true; // 是否使用低差异序列生成器 (如 Halton, Sobol)

    // 2. 初始化多个随机数生成器，用于NEE的不同阶段
    SampleGenerator sampleGenerator           = SampleGenerator::make( sgBase, SampleGeneratorEffectSeed::NextEventEstimation ); // 通用随机数
    // NEECandidateSamples 可能用于从多个候选光源中选择一个
    SampleGenerator sampleGeneratorLightSampler = SampleGenerator::make( sgBase, SampleGeneratorEffectSeed::NextEventEstimationLightSampler, useLowDiscrepancyGen, totalSamples * workingContext.ptConsts.NEECandidateSamples ); // 光源采样专用
    SampleGenerator sampleGeneratorFeedback = SampleGenerator::make( sgBase, SampleGeneratorEffectSeed::NextEventEstimationFeedback ); // 反馈机制专用

    // 3. 初始化光源反馈机制 (用于 NEE-AT: Next Event Estimation with Adaptive Training)
    LightFeedbackReservoir feedbackReservoir; // 存储光源反馈信息的Reservoir
    bool useFeedback = false; // 是否启用反馈
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_BUILD_STABLE_PLANES // 构建稳定平面模式下通常不使用时序反馈
    if( lightSampler.IsTemporalFeedbackRequired() ) // 如果光源采样器需要时序反馈
    {
        feedbackReservoir = lightSampler.LoadFeedback(); // 加载上一帧或之前存储的反馈信息
        useFeedback = true;
    }
#endif
    // 计算“窄域”NEE样本数，可能指针对特定区域或更重要光源的采样
    const uint narrowNEESamples      = lightSampler.ComputeNarrowSampleCount(totalSamples);

    // 4. 设置传递给下一 bounces 的 BSDFMISInfo
    // 这些信息用于在BSDF路径恰好命中光源时进行正确的MIS加权。
    inoutResult.BSDFMISInfo.LightSamplingEnabled    = true;       // 标记已执行光源采样
    inoutResult.BSDFMISInfo.LightSamplingIsIndirect = lightSampler.IsIndirect; // 标记是否为间接光路径上的NEE
    inoutResult.BSDFMISInfo.NarrowNEESamples        = narrowNEESamples; // “窄域”样本数
    inoutResult.BSDFMISInfo.TotalSamples            = totalSamples;     // 总样本数

    // 初始化累加器
    inoutResult.RadianceSourceDistance = 0; // 用于降噪器的加权平均光源距离
    float luminanceSum = 0.0;               // 用于加权平均的亮度总和
    
    int narrowNEESamplesRemaining = narrowNEESamples;
    
    // 5. 主采样循环：采集 totalSamples 个光源样本
    for (uint sampleIndex = 0; sampleIndex < totalSamples; sampleIndex++)
    {
        bool sampleIsNarrow = narrowNEESamplesRemaining > 0; // 判断当前是否为“窄域”样本
        narrowNEESamplesRemaining--;

        // 5a. 生成一个光源样本 (PathLightSample)
        // GenerateLightSample (具体实现未在此代码段中) 会调用 lightSampler 来：
        //  - 选择一个光源。
        //  - 在该光源上选择一个点。
        //  - 返回包含光源辐射亮度(Li)、到光源方向、距离、采样PDF等信息的 PathLightSample 结构。
        // workingContext.ptConsts.NEECandidateSamples 可能用于从多个候选光源中进行选择。
        PathLightSample lightSample = GenerateLightSample(workingContext, shadingData, bsdf, workingContext.ptConsts.NEECandidateSamples, sampleGeneratorLightSampler, sampleGenerator, lightSampler, sampleIsNarrow);

        // 5b. 处理这个光源样本
        // ProcessLightSample 会投射阴影光线，如果可见，则计算BSDF、MIS权重并累加贡献。
        ProcessLightSample(inoutResult, luminanceSum, lightSample, sampleIsNarrow, narrowNEESamples, totalSamples, shadingData, bsdf, preScatterPath, lightSampler, useFeedback, feedbackReservoir, sampleGeneratorFeedback, workingContext);
    }

    // 6. 存储反馈信息 (如果启用)
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_BUILD_STABLE_PLANES
    if( useFeedback )
        lightSampler.StoreFeedback( feedbackReservoir, true ); // 将更新后的反馈水塘存储起来
#endif

    // 7. 计算最终的加权平均光源距离
    FinalizeLightSample(inoutResult, luminanceSum);
}

// PathTracer/PathTracerNEE.hlsli
// 该函数投射光线，如果光源可见，则正确累积辐射亮度，包括进行加权和。
void ProcessLightSample(inout NEEResult accum, inout float luminanceSum, PathLightSample lightSample, bool sampleIsNarrow, uint narrowNEESamples, uint totalSamples,
                        const ShadingData shadingData, const ActiveBSDF bsdf, const PathState preScatterPath, LightSampler lightSampler,
                        const bool useFeedback, inout LightFeedbackReservoir feedbackReservoir, inout SampleGenerator sampleGeneratorFeedback, const WorkingContext workingContext)
{
    if (!lightSample.Valid()) // 如果光源样本无效，则跳过
        return;

    // 1. 计算阴影光线 (Visibility Ray)
    const RayDesc ray = lightSample.ComputeVisibilityRay(shadingData).toRayDesc();
        
    // 2. 追踪阴影光线以判断可见性
    // Bridge::traceVisibilityRay 会投射这条光线，并返回光源是否可见。
    // preScatterPath.rayCone 和 preScatterPath.getVertexIndex() 可能用于优化。
    bool visible = Bridge::traceVisibilityRay(ray, preScatterPath.rayCone, preScatterPath.getVertexIndex(), workingContext.debug);

    // (调试代码：画出阴影光线，颜色表示是否可见)

    if (visible) // 只有当光源可见时，才计算其贡献
    {
        // 3. 计算掠射角衰减 (Grazing Angle Fadeout)
        // ComputeLowGrazingAngleFalloff 用于在光线与表面法线夹角过大（掠射角）时减少贡献，
        // 以避免法线贴图等造成的边缘高光或锯齿。
        float fadeOut = (shadingData.shadowNoLFadeout>0)?(ComputeLowGrazingAngleFalloff( ray.Direction, shadingData.vertexN, shadingData.shadowNoLFadeout, 2.0 * shadingData.shadowNoLFadeout )):(1.0);

        // 4. 计算多重重要性采样 (MIS) 权重
        // scatterPdfForDir: 计算使用BSDF采样得到当前光线方向(lightSample.Direction)的PDF。
        // 这是与NEE进行MIS加权的“另一个采样策略”的PDF。
        float scatterPdfForDir = bsdf.evalPdf(shadingData, lightSample.Direction, kUseBSDFSampling);
        // lightSampler.ComputeInternalMIS 使用NEE采样PDF和BSDF采样PDF来计算MIS权重 (通常是1 / (pdf_nee + pdf_bsdf) * pdf_nee 或 Balance Heuristic)。
        // sampleIsNarrow, narrowNEESamples, totalSamples 可能影响MIS权重的计算方式，
        // 例如，针对不同采样策略（窄域/全局）使用不同的PDF组合。
        float misWeight = lightSampler.ComputeInternalMIS(shadingData.posW, lightSample, sampleIsNarrow, narrowNEESamples, totalSamples, scatterPdfForDir);

        fadeOut *= misWeight; // 将MIS权重乘入衰减因子

        // 5. 计算BSDF在该方向的吞吐量 (BRDF * cos_theta)
        float3 bsdfThpDiff, bsdfThpSpec; // 漫反射和镜面反射的BSDF吞吐量
        bsdf.eval(shadingData, lightSample.Direction, bsdfThpDiff, bsdfThpSpec);

        // 6. Firefly Filter - 可选
        // 对于贡献过大且概率较低的样本（可能导致噪点/飞火），进行过滤。
#if 1 
        if( workingContext.ptConsts.fireflyFilterThreshold != 0 )
        {
            const float pdf = lightSample.SelectionPdf * lightSample.SolidAnglePdf; // NEE采样总PDF
            float neeFireflyFilterK = ComputeNewScatterFireflyFilterK(preScatterPath.fireflyFilterK, pdf, 1.0); // 计算过滤参数K
            // FireflyFilterShort 根据阈值和K值对潜在的飞火进行衰减
            fadeOut *= FireflyFilterShort(average(lightSample.Li*(bsdfThpDiff+bsdfThpSpec))*misWeight, workingContext.ptConsts.fireflyFilterThreshold, neeFireflyFilterK); // 注意这里 misWeight 已乘入 fadeOut，避免重复
        }
#endif
        
        // 7. 将衰减因子应用到光源的辐射亮度 Li 上
        lightSample.Li *= fadeOut;

        // 8. 计算最终的漫反射和镜面反射贡献
        float3 diffRadiance = bsdfThpDiff * lightSample.Li;
        float3 specRadiance = bsdfThpSpec * lightSample.Li;

        float3 combinedContribution = diffRadiance + specRadiance;
        float combinedContributionAvg = average(combinedContribution); // 平均贡献亮度

        // 9. 累加光照贡献到 NEEResult
        lpfloat3 neeDiffuseRadiance, neeSpecularRadiance;
        accum.GetRadiances(neeDiffuseRadiance, neeSpecularRadiance);
        neeDiffuseRadiance = lpfloat3( min(neeDiffuseRadiance + diffRadiance, HLF_MAX.xxx ) ); // 使用低精度浮点累加
        neeSpecularRadiance = lpfloat3( min(neeSpecularRadiance + specRadiance, HLF_MAX.xxx ) );
        accum.SetRadiances(neeDiffuseRadiance, neeSpecularRadiance);

        // 10. 累加加权光源距离 (用于降噪器)
        // RadianceSourceDistance 是一个按光照贡献加权的平均距离
        accum.RadianceSourceDistance = lpfloat( min( accum.RadianceSourceDistance + lightSample.Distance * combinedContributionAvg, HLF_MAX ) );
        luminanceSum += combinedContributionAvg; // 累加总贡献亮度，用于后续归一化
        
        // 11. 光源采样反馈 (NEE-AT)
        if( useFeedback && lightSample.LightIndex != 0xFFFFFFFF ) // 如果启用反馈且光源索引有效
        {
            // 计算反馈权重：考虑路径吞吐量和当前样本的贡献
            float feedbackWeight = average(preScatterPath.thp) * combinedContributionAvg;

            // (注释掉的代码：根据光源被全局采样器采样的PDF来调整反馈权重，但效果不确定，默认禁用)
            // feedbackWeight /= sqrt(lightSampler.SampleGlobalPDF(lightSample.LightIndex));

            // 将反馈信息（光源索引、权重、随机数）插入到反馈水塘中
            lightSampler.InsertFeedbackFromNEE(feedbackReservoir, lightSample.LightIndex, feedbackWeight, sampleNext1D(sampleGeneratorFeedback) );
        }
    }
}

// PathTracer/PathTracerNEE.hlsli
void FinalizeLightSample( inout NEEResult accum, const float luminanceSum )
{
    // 将累积的加权光源距离除以总贡献亮度，得到最终的平均光源距离。
    // luminanceSum + 1e-30 是为了防止除以零。
    accum.RadianceSourceDistance = lpfloat( min( accum.RadianceSourceDistance / (luminanceSum + 1e-30), HLF_MAX ) );
}

// PathTracer/Lighting/LightSampler.hlsli
float ComputeInternalMIS(const float3 surfacePosW, const PathTracer::PathLightSample lightSample, bool isNarrow, const uint narrowSamples, const uint totalSamples, float bsdfPdf)
{
    float thisCount;  // 当前NEE策略的样本数
    float otherCount; // 另一种NEE策略的样本数
    float thisPdf = lightSample.SelectionPdf; // 当前NEE策略选择此光源的PDF
    float otherPdf;   // 另一种NEE策略选择此光源的PDF

    // 根据当前NEE样本是“窄域”还是“全局”来设置样本数和对应PDF
    [branch]if ( isNarrow ) // 如果当前是窄域NEE样本
    {
        thisCount  = narrowSamples;
        otherCount = totalSamples - narrowSamples; // 全局样本数
        // 获取用“全局”策略采样到这个特定光源的PDF
        otherPdf   = SampleGlobalPDF(lightSample.LightIndex); 
    }
    else // 如果当前是全局NEE样本
    {
        thisCount  = totalSamples - narrowSamples; // 全局样本数
        otherCount = narrowSamples;
        [branch]if( narrowSamples != 0 )
            // 获取用“窄域”策略采样到这个特定光源的PDF
            otherPdf   = SampleNarrowPDF(lightSample.LightIndex);
        else
            otherPdf   = 0;
    }

    // 光源表面点采样PDF（已转换为立体角PDF）。
    // 对于同一个光源上的同一点，无论是窄域还是全局策略选中它，这个立体角PDF都一样。
    float solidAnglePdf = lightSample.SolidAnglePdf; 
    // 裁剪bsdfPdf，主要为了数值稳定性，特别是与其他地方可能用fp16打包的情况匹配。
    bsdfPdf = clamp(bsdfPdf, 0, HLF_MAX); 

    // 调试宏，可以强制覆盖PDF值
#if defined(RTXPT_NEEAT_MIS_OVERRIDE_BSDF_PDF)
    bsdfPdf = RTXPT_NEEAT_MIS_OVERRIDE_BSDF_PDF;
#endif
#if defined(RTXPT_NEEAT_MIS_OVERRIDE_SOLID_ANGLE_PDF)
    solidAnglePdf = RTXPT_NEEAT_MIS_OVERRIDE_SOLID_ANGLE_PDF;
#endif

    // LightSamplingMISBoost() 是一个调整因子，可以用来提升或降低光源采样在MIS中的相对权重。
    solidAnglePdf *= LightSamplingMISBoost(); 

    // 调用EvalMIS计算MIS权重。RTXPT_NEE_MIS_HEURISTIC 很可能指向平衡启发式。
    // EvalMIS的参数大致对应 (启发式, n1, p1, n2, p2, n3, p3, ...)，其中pi是完整PDF。
    // 技巧1: 当前NEE策略 (thisCount, thisPdf * solidAnglePdf)
    // 技巧2: 另一种NEE策略 (otherCount, otherPdf * solidAnglePdf)
    // 技巧3: BSDF采样 (1个样本, bsdfPdf)。仅当 lightSample.LightSampleableByBSDF 为真时才考虑BSDF PDF。
    float thisMIS = EvalMIS(RTXPT_NEE_MIS_HEURISTIC, 
                            thisCount, thisPdf*solidAnglePdf, 
                            otherCount, otherPdf*solidAnglePdf, 
                            1, lightSample.LightSampleableByBSDF ? bsdfPdf : 0); 

    // (solidAnglePdf 验证的调试代码块)
    // ...

    // TODO: 注释指出 "/ thisCount" 严格来说不是MIS的一部分。
    // 这表明返回的是一个平均化的MIS权重，或者说，是已将1/N项部分折叠进去的权重。
    return thisMIS / thisCount; 
}

// PathTracer/Lighting/LightSampler.hlsli
float ComputeBSDFMIS(const uint lightIndex, lpfloat bsdfPdf, float solidAnglePdf, const uint narrowSamples, const uint totalSamples)
{
    const uint globalSamples = totalSamples - narrowSamples; // 全局NEE样本数

    // 获取窄域和全局NEE策略采样到这个特定光源(lightIndex)的“选择光源”PDF
    float globPdf = SampleGlobalPDF(lightIndex);
    float narrPdf = SampleNarrowPDF(lightIndex);

    // 调试宏，可以强制覆盖PDF值
#if defined(RTXPT_NEEAT_MIS_OVERRIDE_BSDF_PDF)
    bsdfPdf = RTXPT_NEEAT_MIS_OVERRIDE_BSDF_PDF;
#endif
#if defined(RTXPT_NEEAT_MIS_OVERRIDE_SOLID_ANGLE_PDF)
    solidAnglePdf = RTXPT_NEEAT_MIS_OVERRIDE_SOLID_ANGLE_PDF;
#endif

    solidAnglePdf *= LightSamplingMISBoost(); // 应用同样的MIS调整因子

    // 调用EvalMIS计算MIS权重
    // 技巧1: BSDF采样 (1个样本, bsdfPdf)
    // 技巧2: 全局NEE策略 (globalSamples, globPdf * solidAnglePdf)
    // 技巧3: 窄域NEE策略 (narrowSamples, narrPdf * solidAnglePdf)
    return EvalMIS(RTXPT_NEE_MIS_HEURISTIC, 
                   1, bsdfPdf, 
                   globalSamples, globPdf*solidAnglePdf, 
                   narrowSamples, narrPdf*solidAnglePdf); 
}

// PathTracer/Lighting/LightSampler.hlsli
float ComputeBSDFMISForEmissiveTriangle(const uint emissiveTriangleLightIndex, lpfloat bsdfPdf, const float3 viewerPosition, const float3 lightSamplePosition, const uint narrowSamples, const uint totalSamples)
{
    // 如果bsdfPdf为0，通常表示Delta分布（如完美镜面）。
    // 这种情况下，NEE几乎不可能采样到这个精确路径，BSDF采样是唯一途径，所以MIS权重为1。
    if( bsdfPdf == 0 ) 
        return 1;

    // 加载三角形光源信息
    PolymorphicLightInfoFull lightInfo = LoadLight(emissiveTriangleLightIndex);
    TriangleLight triangleLight = TriangleLight::Create(lightInfo);

    // 计算光源在该方向发射的立体角PDF
    // viewerPosition是当前着色点，lightSamplePosition是光源上被命中的点。
    float solidAnglePdf = triangleLight.CalcSolidAnglePdfForMIS(viewerPosition, lightSamplePosition);
    
    // 调用通用的ComputeBSDFMIS函数
    return ComputeBSDFMIS(emissiveTriangleLightIndex, bsdfPdf, solidAnglePdf, narrowSamples, totalSamples);
}

// PathTracer/Lighting/LightSampler.hlsli
float ComputeBSDFMISForEnvironmentQuad(const uint environmentQuadLightIndex, lpfloat bsdfPdf, const uint narrowSamples, const uint totalSamples)
{
#if POLYLIGHT_QT_ENV_ENABLE // 仅当启用环境四边形光源时编译
    if( bsdfPdf == 0 ) 
        return 1;

    PolymorphicLightInfoFull lightInfo = LoadLight(environmentQuadLightIndex);
    EnvironmentQuadLight eqLight = EnvironmentQuadLight::Create(lightInfo);
    // 计算环境四边形光源的立体角PDF。参数(0,0)可能表示其PDF不依赖于具体观察点和光源点，
    // 或者是这些信息已封装在eqLight对象中，或这是一个简化的计算。
    float solidAnglePdf = eqLight.CalcSolidAnglePdfForMIS(0, 0); 
    return ComputeBSDFMIS(environmentQuadLightIndex, bsdfPdf, solidAnglePdf, narrowSamples, totalSamples);
#else
    return 1.0; // 如果未启用，则返回1
#endif
}

// PathTracer/PathTracer.hlsli
namespace PathTracer
{
    // ... (其他函数) ...

    // Miss shader
    inline void HandleMiss(inout PathState path, const float3 rayOrigin, const float3 rayDir, const float rayTCurrent, const WorkingContext workingContext)
    {
        // 1. 更新路径已行进的距离和相关状态
        // rayTCurrent 在这里通常是 TraceRay 时设置的 TMax，表示光线行进了这么远仍未命中。
        UpdatePathTravelled(path, rayOrigin, rayDir, rayTCurrent, workingContext);

        // (Delta Tree 可视化调试相关的代码块)
#if PATH_TRACER_MODE==PATH_TRACER_MODE_BUILD_STABLE_PLANES && ENABLE_DEBUG_DELTA_TREE_VIZUALISATION
        if (path.hasFlag(PathFlags::deltaTreeExplorer))
        {
            DeltaTreeVizHandleMiss(path, rayOrigin, rayDir, rayTCurrent, workingContext);
            return;
        }
#endif

        float3 environmentEmission = 0.f; // 初始化环境光贡献

        // 2. 解包 MIS (多重重要性采样) 信息
        // misInfo 来自上一路径顶点的NEE计算，用于判断是否需要对环境光进行MIS。
        NEEBSDFMISInfo misInfo = NEEBSDFMISInfo::Unpack16bit(path.packedMISInfo);

        // 3. 判断是否需要计算环境光贡献 (考虑与NEE/ReSTIR DI的配合)
        // !(A && B) 等价于 !A || !B
        // misInfo.SkipEmissiveBRDF: 如果为true (例如ReSTIR DI已处理直接光)，则可能跳过自发光/环境光。
        // !path.wasScatterTransmission(): 如果上一次散射是透射，即使SkipEmissiveBRDF为true，可能仍需评估环境光。
        // 总体逻辑：除非(明确指示跳过自发光/环境光 并且 上一次不是透射)，否则就计算环境光。
        if ( !(misInfo.SkipEmissiveBRDF && !path.wasScatterTransmission()) )
        {
            // 3a. 获取环境贴图对象
            EnvMap envMap = Bridge::CreateEnvMap(); 

            // 3b. 根据漫反射弹射次数选择环境贴图的MIP级别
            // 多次漫反射后，使用较低的MIP级别可以减少高频环境贴图带来的噪声和计算成本。
            float mipLevel = (path.getCounter(PackedCounters::DiffuseBounces)>1)?(Bridge::DiffuseEnvironmentMapMIPOffset()):(0); 

            // 3c. 将光线方向转换为环境贴图的本地坐标系 (环境贴图可能自带旋转)
            float3 localDir = envMap.ToLocal(path.dir);      
            // 3d. 从环境贴图采样，获取辐射亮度 Le
            float3 Le = envMap.EvalLocal(localDir, mipLevel);

            // 3e. 计算 MIS 权重
            // 目的是平衡“BSDF采样方向恰好指向环境的这个部分”与“NEE从前一顶点显式采样环境光的这个部分”
            float misWeight = 1.0f;
            // 条件：前一顶点启用了光源采样(NEE)，且当前未命中路径是由BSDF采样产生的(PDF非零)
            if( misInfo.LightSamplingEnabled && path.bsdfScatterPdf != 0 )
            {
                // 创建与前一顶点配置相同的光源采样器
                LightSampler lightSampler = Bridge::CreateLightSampler( workingContext.pixelPos, misInfo.LightSamplingIsIndirect, workingContext.debug.IsDebugPixel() );
                // 根据当前未命中的方向，查找对应的环境光源索引（环境贴图常被视为一个或多个光源）
                // LookupEnvLightByDirection 是关键，它将一个方向映射到一个“光源实体”以便获取NEE的PDF。
                uint environmentQuadLightIndex = lightSampler.LookupEnvLightByDirection( localDir ); 
                // 计算BSDF路径命中此环境区域的MIS权重，与NEE采样此区域的可能性进行平衡。
                misWeight = lightSampler.ComputeBSDFMISForEnvironmentQuad(environmentQuadLightIndex, path.bsdfScatterPdf, misInfo.NarrowNEESamples, misInfo.TotalSamples);

                // (向光源采样器提供反馈，用于自适应光源采样)
                float simpleRandom = Hash32ToFloat( Hash32Combine( Hash32Combine(Hash32(path.getVertexIndex() + 0x0366FE2F), path.id), Bridge::getSampleIndex() ) );
                lightSampler.InsertFeedbackFromBSDF(environmentQuadLightIndex, average(path.thp*Le), misWeight, simpleRandom );
            }

            environmentEmission = misWeight * Le; // 应用MIS权重到环境光亮度
        }

        // 4. 对计算出的环境光贡献进行后处理
        if( workingContext.ptConsts.fireflyFilterThreshold != 0 ) // 飞火过滤
            environmentEmission = FireflyFilter( environmentEmission, workingContext.ptConsts.fireflyFilterThreshold, path.fireflyFilterK );
        environmentEmission *= Bridge::getNoisyRadianceAttenuation(); // 应用噪声衰减（例如用于多重采样抗锯齿）
        
        // 5. 更新路径状态：清除命中信息并终止路径
        path.clearHit();  // 清除任何可能残留的命中信息
        path.terminate(); // 标记路径为非激活，因为它不会再继续传播

        // 6. 【可选】稳定平面系统处理未命中情况
#if PATH_TRACER_MODE!=PATH_TRACER_MODE_REFERENCE
        // StablePlanesHandleMiss 允许稳定平面系统记录或使用这条未命中路径的环境光贡献。
        // 如果它返回false，可能表示路径已被稳定平面系统完全处理，可以提前返回。
        if( !StablePlanesHandleMiss(path, environmentEmission, rayOrigin, rayDir, rayTCurrent, 0, workingContext) )
            return;
#endif

        // 7. 将环境光贡献累加到路径总光照 L
        // (在特定模式下，例如填充稳定平面模式，可能不直接累加到 L，而是输出到特定缓冲区)
#if PATH_TRACER_MODE != PATH_TRACER_MODE_FILL_STABLE_PLANES 
        if (any(environmentEmission>0))
            path.L += max( 0.xxx, path.thp*environmentEmission ); // 确保贡献非负
#endif
    } // end of HandleMiss
} // end of namespace PathTracer