// 准备工作：确保目标纹理处于可写入状态
gpu_commands->issue_texture_barrier(probe_raytrace_radiance_texture,
                                    RESOURCE_STATE_UNORDERED_ACCESS, 0, 1);

// 绑定光线追踪管线和所需的资源
gpu_commands->bind_pipeline(probe_raytrace_pipeline);
gpu_commands->bind_descriptor_set(&probe_raytrace_descriptor_set, 1, nullptr, 0);

// 确定需要更新的探针数量
const u32 probe_count =
    offsets_calculations_count >= 0 ? get_total_probes() : per_frame_probe_updates;

// 发射光线：为每个探针（probe_count）发射指定数量（probe_rays）的光线
gpu_commands->trace_rays(probe_raytrace_pipeline, probe_rays, probe_count, 1);

// 计算完成后，再次设置屏障，以便后续阶段可以读取该纹理
gpu_commands->issue_texture_barrier(probe_raytrace_radiance_texture, RESOURCE_STATE_UNORDERED_ACCESS, 0, 1);

// layout(binding = X) uniform accelerationStructureEXT as;
// layout(binding = Y, set = 0, rgba32f) uniform image2D radiance_output_texture;
layout( location = 0 ) rayPayloadEXT RayPayload payload;

void main() {
    // gl_LaunchIDEXT 是内置变量，代表当前线程在网格中的二维索引
    // .x 是光线索引, .y 是探针索引
    const ivec2 pixel_coord = ivec2(gl_LaunchIDEXT.xy);
    const int probe_index = pixel_coord.y + probe_update_offset;
    const int ray_index = pixel_coord.x;

    // ... 省略探针状态检查 ...

    // 1. 计算光线起点 (Ray Origin)
    //    将一维的探针索引转换为三维网格坐标，再转换到世界空间位置
    ivec3 probe_grid_indices = probe_index_to_grid_indices(probe_index);
    vec3 ray_origin = grid_indices_to_world(probe_grid_indices, probe_index);

    // 2. 计算光线方向 (Ray Direction)
    //    使用球斐波那契晶格（Spherical Fibonacci）生成均匀分布在球面上的方向
    //    再通过一个随机旋转矩阵来抖动采样，避免时间上的条带瑕疵
    vec3 direction = normalize(mat3(random_rotation) * spherical_fibonacci(ray_index, probe_rays));

    // 3. 初始化光线负载 (Payload)
    //    Payload 是用于在着色器之间传递数据的结构体
    payload.radiance = vec3(0);
    payload.distance = 0;

    // 4. 发射光线
    //    调用内置函数，在场景加速结构（as）中追踪光线
    //    如果命中，将调用 Closest Hit Shader；否则调用 Miss Shader
    traceRayEXT(as, gl_RayFlagsOpaqueEXT, 0xff, 0, 0, 0, ray_origin, 0.0, direction, 100.0, 0);

    // 5. 存储结果
    //    光线追踪结束后，Payload 中已写入了命中点的辐射度和距离
    //    将结果写入输出纹理的对应位置
    imageStore(global_images_2d[radiance_output_index], ivec2(ray_index, probe_index), vec4(payload.radiance, payload.distance));
}

layout(buffer_reference, std430, buffer_reference_align = 2) buffer int_array_type {
    uint16_t v;
};

layout(buffer_reference, std430, buffer_reference_align = 4) buffer vec2_array_type {
    vec2 v;
};

layout(buffer_reference, std430, buffer_reference_align = 4) buffer float_array_type {
    float v;
};

layout( location = 0 ) rayPayloadInEXT RayPayload payload;
hitAttributeEXT vec2 barycentric_weights;

void main() {
    // 初始化输出变量
    vec3 radiance = vec3(0.0f);
    float distance = 0.0f;

    // --- 步骤 0: 处理背面命中 ---
    // 这是一个关键的健壮性处理。如果光线击中三角形的背面，
    // 通常意味着探针位于模型内部。我们不计算光照，
    // 而是将距离标记为负数，以在后续阶段识别并处理这种情况，防止漏光。
    if (gl_HitKindEXT == gl_HitKindBackFacingTriangleEXT) {
        distance = (gl_RayTminEXT + gl_HitTEXT) * -0.2f;
    } else {
        // --- 步骤 1: 获取命中几何体的数据 ---
        // 使用光追管线提供的内置变量，定位到具体的模型实例和三角形。
        uint mesh_index = mesh_instance_draws[gl_GeometryIndexEXT].mesh_draw_index;
        MeshDraw mesh = mesh_draws[mesh_index];

        // 从索引缓冲区获取构成该三角形的三个顶点的索引。
        int_array_type index_buffer = int_array_type(mesh.index_buffer);
        int i0 = index_buffer[gl_PrimitiveID * 3 + 0].v;
        int i1 = index_buffer[gl_PrimitiveID * 3 + 1].v;
        int i2 = index_buffer[gl_PrimitiveID * 3 + 2].v;


        // --- 步骤 2: 使用重心坐标插值顶点属性 ---
        // 硬件会提供命中点在三角形内的精确重心坐标。
        float b = barycentric_weights.x;
        float c = barycentric_weights.y;
        float a = 1.0f - b - c;

        // 从顶点缓冲区中获取三个顶点的局部坐标。
        float_array_type vertex_buffer = float_array_type(mesh.position_buffer);
        vec4 p0 = vec4(vertex_buffer[i0*3+0].v, vertex_buffer[i0*3+1].v, vertex_buffer[i0*3+2].v, 1.0);
        vec4 p1 = vec4(vertex_buffer[i1*3+0].v, vertex_buffer[i1*3+1].v, vertex_buffer[i1*3+2].v, 1.0);
        vec4 p2 = vec4(vertex_buffer[i2*3+0].v, vertex_buffer[i2*3+1].v, vertex_buffer[i2*3+2].v, 1.0);
        
        // 将顶点位置变换到世界空间。
        const mat4 transform = mesh_instance_draws[gl_GeometryIndexEXT].model;
        vec4 p0_world = transform * p0;
        vec4 p1_world = transform * p1;
        vec4 p2_world = transform * p2;

        // 插值计算出命中点的精确世界坐标。
        const vec3 world_position = a * p0_world.xyz + b * p1_world.xyz + c * p2_world.xyz;

        // 同理，插值计算出UV坐标。
        vec2_array_type uv_buffer = vec2_array_type(mesh.uv_buffer);
        vec2 uv0 = uv_buffer[i0].v;
        vec2 uv1 = uv_buffer[i1].v;
        vec2 uv2 = uv_buffer[i2].v;
        vec2 uv = (a * uv0 + b * uv1 + c * uv2);

        // 插值计算出平滑的顶点法线。
        float_array_type normals_buffer = float_array_type(mesh.normals_buffer);
        vec3 n0 = vec3(normals_buffer[i0*3+0].v, normals_buffer[i0*3+1].v, normals_buffer[i0*3+2].v);
        vec3 n1 = vec3(normals_buffer[i1*3+0].v, normals_buffer[i1*3+1].v, normals_buffer[i1*3+2].v);
        vec3 n2 = vec3(normals_buffer[i2*3+0].v, normals_buffer[i2*3+1].v, normals_buffer[i2*3+2].v);
        vec3 normal = a * n0 + b * n1 + c * n2;

        // 将法线变换到世界空间。
        const mat3 normal_transform = mat3(mesh_instance_draws[gl_GeometryIndexEXT].model_inverse);
        normal = normalize(normal_transform * normal);


        // --- 步骤 3: 获取表面材质属性 ---
        // 使用插值得到的UV坐标采样反照率（Albedo）贴图。
        // 指定一个较低的LOD层级可以提升性能，因为GI的精度要求不高。
        vec3 albedo = textureLod(global_textures[nonuniformEXT(mesh.textures.x)], uv, 3.0).rgb;


        // --- 步骤 4: 计算直接光照 ---
        // 这里实现了一个简单的 Lambertian 光照模型。
        Light light = lights[0]; // 假设场景中至少有一个光源。
        const vec3 position_to_light = light.world_position - world_position;
        const vec3 l = normalize(position_to_light);
        const float NoL = clamp(dot(normal, l), 0.0, 1.0);

        // 计算光照衰减。
        float attenuation = attenuation_square_falloff(position_to_light, 1.0f / light.radius);
        
        // 组合光照贡献。
        vec3 light_intensity = vec3(0.0f);
        if (attenuation > 0.001f && NoL > 0.001f) {
            light_intensity += (light.intensity * attenuation * NoL) * light.color;
        }

        vec3 diffuse = albedo * light_intensity;


        // --- 步骤 5: (可选) 计算间接光照（多轮反弹） ---
        // 这是DDGI实现无限反弹效果的核心。
        // 通过采样周围的探针数据来近似当前点的间接光照。
        if (use_infinite_bounces()) {
            diffuse += albedo * sample_irradiance(world_position, normal, camera_position.xyz) * infinite_bounces_multiplier;
        }

        // --- 步骤 6: 为正面命中设置最终输出 ---
        radiance = diffuse;
        distance = gl_RayTminEXT + gl_HitTEXT; // 距离是正值。
    }

    // --- 最终步骤: 将结果写回光线负载 (Payload) ---
    // 无论命中正面还是背面，都将计算出的 radiance 和 distance 返回。
    payload.radiance = radiance;
    payload.distance = distance;
}

layout( location = 0 ) rayPayloadInEXT RayPayload payload;

void main() {
    // 返回天空颜色作为辐射度
    payload.radiance = vec3(0.529, 0.807, 0.921);
    // 设置一个非常大的距离值，表示光线射向了无穷远
    payload.distance = 1000.0f;
}

/**
 * @brief 使用球面斐波那契算法在单位球面上生成一个均匀分布的3D方向向量。
 * @param i 当前样本的索引，范围 [0, n-1]。
 * @param n 总样本数。
 * @return 一个标准化的3D方向向量。
 */
vec3 spherical_fibonacci(float i, float n) {
    // 黄金比例常数，是构造斐波那契晶格的核心。
    const float PHI = 1.61803398875f; // (sqrt(5.0) + 1.0) / 2.0

    // 计算垂直分量（z轴），确保点在z轴上均匀分布。
    // (2.0 * i + 1.0) / n 会生成从 1/n 到 (2n-1)/n 的序列。
    // 1.0 - ... 将其映射到 [-1 + 1/n, 1 - 1/n] 的范围。
    float cos_theta = 1.0f - (2.0f * i + 1.0f) / n;
    float sin_theta = sqrt(clamp(1.0f - cos_theta * cos_theta, 0.0f, 1.0f));

    // 计算水平角度 phi，使用黄金比例的小数部分来确保每个点的旋转角度都有最大程度的无理性和不重复性，
    // 从而避免产生摩尔纹或排列成线的瑕疵。
    float phi = 2.0f * PI * (i * PHI - floor(i * PHI));

    // 从球坐标转换为笛卡尔坐标。
    return vec3(cos(phi) * sin_theta,
                sin(phi) * sin_theta,
                cos_theta);
}

// 编码：将3D单位向量投影到一个八面体上，然后展开成一个2D正方形([-1,1])。
vec2 oct_encode(in vec3 v) {
    // 将向量投影到z=0的平面，通过L1范数进行归一化。
    float l1norm = abs(v.x) + abs(v.y) + abs(v.z);
    vec2 result = v.xy / l1norm;

    // 如果向量在下半球 (v.z < 0)，则需要进行一次“翻折”操作，
    // 将下半球的八面体表面映射到2D正方形的外部区域。
    if (v.z < 0.0) {
        result = (1.0 - abs(result.yx)) * sign_not_zero(result.xy);
    }
    return result;
}

// 解码：将2D八面体坐标转换回3D单位向量。
vec3 oct_decode(vec2 o) {
    // 首先重构出上半球的向量。
    vec3 v = vec3(o.x, o.y, 1.0 - abs(o.x) - abs(o.y));
    
    // 如果z分量为负，说明原始向量来自下半球，需要执行与编码相反的翻折操作。
    if (v.z < 0.0) {
        v.xy = (1.0 - abs(v.yx)) * sign_not_zero(v.xy);
    }
    
    // 最后，将向量归一化以确保它是单位长度。
    return normalize(v);
}

// 辅助函数：返回一个数的符号，但0被视为正。
float sign_not_zero(in float k) {
    return (k >= 0.0) ? 1.0 : -1.0;
}

/**
 * @brief 将一维的探针线性索引转换为三维的网格坐标。
 */
ivec3 probe_index_to_grid_indices(int probe_index) {
    const int probe_x = probe_index % probe_counts.x;
    const int probe_counts_xy = probe_counts.x * probe_counts.y;
    const int probe_y = (probe_index % probe_counts_xy) / probe_counts.x;
    const int probe_z = probe_index / probe_counts_xy;
    return ivec3(probe_x, probe_y, probe_z);
}

/**
 * @brief 将三维的网格坐标转换回一维的线性索引。
 */
int probe_indices_to_index(in ivec3 probe_coords) {
    return int(probe_coords.x + probe_coords.y * probe_counts.x + probe_coords.z * probe_counts.x * probe_counts.y);
}

/**
 * @brief 将三维的网格坐标转换为世界坐标，可选地应用一个偏移量。
 * 这个偏移量是DDGI的一个重要特性，允许探针从其规则的网格位置移动，以更好地贴合场景几何体，减少漏光。
 */
vec3 grid_indices_to_world(ivec3 grid_indices, int probe_index) {
    // 计算基础的世界坐标
    vec3 base_world_pos = grid_indices * probe_spacing + probe_grid_position;
    
    // 从纹理中获取预计算的探针偏移量
    vec3 probe_offset = vec3(0);
    if (use_probe_offsetting()) {
        const int probe_counts_xy = probe_counts.x * probe_counts.y;
        ivec2 offset_coord = ivec2(probe_index % probe_counts_xy, probe_index / probe_counts_xy);
        probe_offset = texelFetch(global_textures[nonuniformEXT(probe_offset_texture_index)], offset_coord, 0).rgb;
    }

    return base_world_pos + probe_offset;
}

/**
 * @brief 将世界坐标转换为其所在的探针网格的三维坐标。
 */
ivec3 world_to_grid_indices(vec3 world_position) {
    vec3 grid_pos = (world_position - probe_grid_position) * reciprocal_probe_spacing;
    return clamp(ivec3(grid_pos), ivec3(0), probe_counts - ivec3(1));
}

/**
 * @brief 根据3D方向和探针索引，计算出在整个探针图集纹理中对应的UV坐标。
 */
vec2 get_probe_uv(vec3 direction, int probe_index, int full_texture_width, int full_texture_height, int probe_side_length) {
    // 1. 将3D方向编码为[-1, 1]范围的2D八面体坐标。
    const vec2 octahedral_coordinates = oct_encode(normalize(direction));
    
    const float probe_with_border_side = float(probe_side_length) + 2.0f;
    const int probes_per_row = full_texture_width / int(probe_with_border_side);
    
    // 2. 计算当前探针在图集中的网格索引 (0,0), (1,0), ...
    ivec2 probe_indices = ivec2(probe_index % probes_per_row, probe_index / probes_per_row);
    
    // 3. 计算该探针区域左上角的像素坐标。
    vec2 atlas_texels = vec2(probe_indices) * probe_with_border_side;
    
    // 4. 加上1像素的边界，进入探针的有效数据区域。
    atlas_texels += vec2(1.0f);
    
    // 5. 移动到探针区域的中心。
    atlas_texels += vec2(probe_side_length * 0.5f);
    
    // 6. 使用八面体坐标在探针区域内部进行偏移。
    atlas_texels += octahedral_coordinates * (probe_side_length * 0.5f);
    
    // 7. 将最终的像素坐标归一化为[0, 1]范围的UV坐标。
    return atlas_texels / vec2(float(full_texture_width), float(full_texture_height));
}

i32 irradiance_probe_size = 6;
const i32 octahedral_irradiance_size = irradiance_probe_size + 2;
irradiance_atlas_width = (octahedral_irradiance_size * probe_count_x * probe_count_y);
irradiance_atlas_height = (octahedral_irradiance_size * probe_count_z);

// --- 1. 更新辐照度图集 ---

// ... 绑定计算管线和资源 ...

gpu_commands->dispatch(hydra::ceilu32(irradiance_atlas_width / 8.f),
                       hydra::ceilu32(irradiance_atlas_height / 8.f), 1);


// --- 2. 更新可见性图集 ---

// ... 绑定计算管线和资源 ...

// 启动计算着色器，覆盖整个可见性图集纹理
gpu_commands->dispatch(hydra::ceilu32(visibility_atlas_width / 8.f),
                       hydra::ceilu32(visibility_atlas_height / 8.f), 1);

// 该着色器在一个 8x8 的线程组中执行
layout (local_size_x = 8, local_size_y = 8, local_size_z = 1) in;

void main() {
    ivec3 coords = ivec3(gl_GlobalInvocationID.xyz);
    // ... 省略变量初始化和边界检查 ...

    // 通过像素坐标反算出当前线程正在为哪个探针工作
    int probe_index = get_probe_index_from_pixels(coords.xy, ...);

    // --- 步骤1: 区分内部像素与边界像素 ---
    // 探针在图集中有1像素的边界，边界像素有特殊处理。
    bool border_pixel = ((gl_GlobalInvocationID.x % probe_with_border_side) == 0) || ... ;

    if (!border_pixel) {
        // --- 步骤2: 对所有射线进行加权积分 ---
        vec4 result = vec4(0);
        uint backfaces = 0; // 用于统计击中背面的射线数量
        
        // 循环遍历该探针在上一阶段发射的所有射线
        for (int ray_index = 0; ray_index < probe_rays; ++ray_index) {
            // 获取原始射线数据（辐射度和距离）
            ivec2 sample_position = ivec2(ray_index, probe_index);
            vec4 raw_data = texelFetch(global_textures[nonuniformEXT(radiance_output_index)], sample_position, 0);
            
            // a. 处理背面击中：如果距离为负，说明探针可能在几何体内，跳过此射线。
            //    如果背面射线过多，则认为此探针完全被遮挡，提前退出，结果为黑色。
            if (raw_data.w < 0.0f && use_backfacing_blending()) {
                if (++backfaces >= max_backfaces) return;
                continue;
            }

            // b. 计算权重：这是积分的核心。
            //    - texel_direction: 当前像素所代表的出射方向。
            //    - ray_direction:   当前循环中处理的原始射线的方向。
            //    - weight:          二者点积，即两个方向夹角的余弦值。
            vec3 ray_direction = normalize(mat3(random_rotation) * spherical_fibonacci(ray_index, probe_rays));
            vec3 texel_direction = oct_decode(normalized_oct_coord(coords.xy, probe_side_length));
            float weight = max(0.0, dot(texel_direction, ray_direction));

            if (weight < 0.0001f) continue;

            // c. 根据模式（辐照度/可见性）累加加权值
#if defined(COMPUTE_PROBE_UPDATE_IRRADIANCE)
            // 模式1: 辐照度。累加 (颜色 * 权重)，并将权重本身存入w分量。
            vec3 radiance = raw_data.rgb * 0.95; // 能量守恒
            result += vec4(radiance * weight, weight);
#else
            // 模式2: 可见性。累加 (距离, 距离^2, 0) * 权重。
            weight = pow(weight, 2.5f); // 权重调整
            float distance = min(abs(raw_data.w), probe_max_ray_distance);
            vec3 value = vec3(distance, distance * distance, 0);
            result += vec4(value * weight, weight);
#endif
        }

        // --- 步骤3: 归一化和时间混合 ---
        // a. 归一化：将累加结果除以总权重，得到加权平均值。
        if (result.w > 0.0001f) {
            result.xyz /= result.w;
        }

        // b. 时间滤波：与上一帧的结果进行混合（滞后滤波），以消除闪烁。
        //    hysteresis 是一个 [0, 1] 范围的混合因子。
#if defined(COMPUTE_PROBE_UPDATE_IRRADIANCE)
        // 是否启用感知编码。
        if (use_perceptual_encoding()) {
            // 对 result.rgb（一个线性的HDR颜色值）执行伽马编码。
            // pow(value, exponent) 是一个幂函数。
            // 这里的指数是 vec3(1.0f / 5.0f)，即对R, G, B三个分量都取0.2次幂。
            // 这等同于应用一个 gamma = 5.0 的伽马校正。
            // 其目的是将线性的光照强度非线性地映射到更符合人类视觉感知的空间，
            // 以便在低精度（如RGBA8）纹理中存储时，能更有效地利用数据位，
            // 减少在暗部区域的色带瑕疵。
            result.rgb = pow(result.rgb, vec3(1.0f / 5.0f));
        }
        vec4 previous_value = imageLoad(irradiance_image, coords.xy);
        result = mix(result, previous_value, hysteresis);
        imageStore(irradiance_image, coords.xy, result);
#else
        vec2 previous_value = imageLoad(visibility_image, coords.xy).rg;
        result.rg = mix(result.rg, previous_value, hysteresis);
        imageStore(visibility_image, coords.xy, vec4(result.rg, 0, 1));
#endif
        return; // 内部像素计算完成
    }

    // ... 边界像素处理 ...

    // ... 内部像素计算之后 ...

    // --- 步骤4: 同步线程并处理边界像素 ---
    // a. 内存屏障：确保所有内部像素都已计算并写入内存后，
    //    才开始进行边界像素的拷贝操作，避免读取到旧数据或未定义数据。
    groupMemoryBarrier();
    barrier();

    // b. 计算源像素坐标：根据当前边界像素的位置，计算出它应该从探针区域
    //    内部的哪个像素拷贝数据（通常是相对的另一侧）。
    //    例如，顶部边界拷贝底部内容，左侧边界拷贝右侧内容。
    ivec2 source_pixel_coordinate = coords.xy;

    // const int k_read_table[6] = {5, 3, 1, -1, -3, -5};
    if (corner_pixel) {
        // 角落像素的拷贝逻辑
        source_pixel_coordinate.x += (probe_pixel_x == 0) ? probe_side_length : -probe_side_length;
        source_pixel_coordinate.y += (probe_pixel_y == 0) ? probe_side_length : -probe_side_length;
    } else if (row_pixel) {
        // 水平边界像素的拷贝逻辑
        source_pixel_coordinate.x += k_read_table[probe_pixel_x - 1];
        source_pixel_coordinate.y += (probe_pixel_y > 0) ? -1 : 1;
    } else {
        // 垂直边界像素的拷贝逻辑
        source_pixel_coordinate.x += (probe_pixel_x > 0) ? -1 : 1;
        source_pixel_coordinate.y += k_read_table[probe_pixel_y - 1];
    }

    // c. 拷贝并写入数据
#if defined(COMPUTE_PROBE_UPDATE_IRRADIANCE)
    vec4 copied_data = imageLoad(irradiance_image, source_pixel_coordinate);
    imageStore(irradiance_image, coords.xy, copied_data);
#else
    vec4 copied_data = imageLoad(visibility_image, source_pixel_coordinate);
    imageStore(visibility_image, coords.xy, copied_data);
#endif
}

void sampleIrradianceProbes() {
    // 设置资源屏障：告诉GPU，我们将要以“无序访问”（写入）的方式使用 indirect_texture
    gpu_commands->issue_texture_barrier(indirect_texture, RESOURCE_STATE_UNORDERED_ACCESS, 0, 1);

    // 绑定用于采样Irradiance的计算管线
    gpu_commands->bind_pipeline(sample_irradiance_pipeline);

    // 绑定描述符集，其中包含了所有需要的纹理资源（深度图、法线图、探针数据等）
    gpu_commands->bind_descriptor_set(&sample_irradiance_descriptor_set, 1, nullptr, 0);

    // 通过Push Constants向Shader传递一个标记，告诉它是否启用半分辨率模式
    u32 half_resolution = render_scene->gi_use_half_resolution ? 1 : 0;
    gpu_commands->push_constants(sample_irradiance_pipeline, 0, 4, &half_resolution);

    // 计算需要启动的线程组数量
    // 如果启用半分辨率，宽高都减半
    const f32 resolution_divider = render_scene->gi_use_half_resolution ? 0.5f : 1.0f;
    const u32 group_dim_x = hydra::ceilu32(renderer->width * resolution_divider / 8.0f);
    const u32 group_dim_y = hydra::ceilu32(renderer->height * resolution_divider / 8.0f);

    // 派发计算任务！这将启动 group_dim_x * group_dim_y * 1 个线程组
    // 每个线程组包含 8x8x1 = 64 个线程，对应着色器中的 local_size
    gpu_commands->dispatch(group_dim_x, group_dim_y, 1);

    // 再次设置资源屏障：告诉GPU，计算已完成，indirect_texture 现在将作为“像素着色器资源”（读取）使用
    gpu_commands->issue_texture_barrier(indirect_texture, RESOURCE_STATE_PIXEL_SHADER_RESOURCE, 0, 1);
}

// =========================================================================
//                       
// 为给定的世界坐标点，通过采样周围的光照探针来计算其间接光照。
//
// @param world_position:    当前像素/着色点的世界坐标
// @param normal:            该点的法线向量
// @param camera_position:   摄像机的世界坐标
// @return:                  计算出的间接光 irradiance
// =========================================================================
vec3 sample_irradiance(vec3 world_position, vec3 normal, vec3 camera_position) {

    // Wo 是从着色点指向摄像机的向量
    const vec3 Wo = normalize(camera_position.xyz - world_position);
    
    // 【关键点1: 表面偏置】
    // 为了防止“自阴影”或光照泄漏，将采样点沿着法线和视线方向稍微偏移。
    // 这可以避免在物体表面上直接采样，从而提高稳定性。
    const float minimum_distance_between_probes = 1.0f; // 探针间的最小距离，用于缩放偏移量
    vec3 bias_vector = (normal * 0.2f + Wo * 0.8f) * (0.75f * minimum_distance_between_probes) * self_shadow_bias;
    vec3 biased_world_position = world_position + bias_vector;

    // --- 探针网格定位与插值准备 ---

    // 根据偏移后的世界坐标，找到其所在的探针网格单元的基准索引（单元的最小角）
    ivec3 base_grid_indices = world_to_grid_indices(biased_world_position);
    // 获取该基准探针的世界坐标
    vec3 base_probe_world_position = grid_indices_to_world_no_offsets(base_grid_indices);

    // alpha: 计算采样点在探针网格单元内的相对位置 [0, 1]，用于后续的三线性插值
    vec3 alpha = clamp((biased_world_position - base_probe_world_position), vec3(0.0f), vec3(1.0f));

    vec3  sum_irradiance = vec3(0.0f); // 加权辐照度总和
    float sum_weight = 0.0f;           // 权重总和

    // 遍历环绕采样点的8个探针（形成一个立方体“笼子”）
    for (int i = 0; i < 8; ++i) {
        // 计算当前探针的偏移量 (0或1)，i的二进制位分别代表x,y,z轴的偏移
        ivec3 offset = ivec3(i, i >> 1, i >> 2) & ivec3(1);
        // 计算探针的网格坐标，并确保它在有效范围内
        ivec3 probe_grid_coord = clamp(base_grid_indices + offset, ivec3(0), probe_counts - ivec3(1));
        // 将网格坐标转换为一维索引
        int probe_index = probe_indices_to_index(probe_grid_coord);

        // 获取探针的实际世界坐标
        vec3 probe_pos = grid_indices_to_world(probe_grid_coord, probe_index);

        // --- 计算各项权重 ---
        float weight = 1.0;

        // 【关键点2: 方向系数】
        // 我们只是使用探针进行插值，因此背面的探针也会考虑。
        if (use_smooth_backface()) {
            vec3 direction_to_probe = normalize(probe_pos - world_position);
            // 使用 "wrap shading" 的思想，将 dot(dir, n) 从 [-1, 1] 映射到 [0, 1]
            const float dir_dot_n = (dot(direction_to_probe, normal) + 1.0) * 0.5f;
            // 通过平方和平滑因子，实现一个柔和的权重衰减，避免硬边
            weight *= (dir_dot_n * dir_dot_n) + 0.2;
        }

        // 【关键点3: 可见性权重 (VSM + Chebyshev)】
        // 检查探针和着色点之间是否存在遮挡物。
        vec3 probe_to_biased_point_direction = biased_world_position - probe_pos;
        float distance_to_biased_point = length(probe_to_biased_point_direction);
        probe_to_biased_point_direction /= distance_to_biased_point;

        if (use_visibility()) {
            // 从可见性纹理（一个存储深度的纹理图集）中采样
            vec2 uv = get_probe_uv(probe_to_biased_point_direction, probe_index, visibility_texture_width, visibility_texture_height, visibility_side_length);
            // .rg 通道存储了深度的均值(E[d])和平方均值(E[d^2])
            vec2 visibility = textureLod(global_textures[nonuniformEXT(grid_visibility_texture_index)], uv, 0).rg;
            float mean_distance_to_occluder = visibility.x; // 均值 μ

            float chebyshev_weight = 1.0; // 默认完全可见
            // 如果着色点比平均遮挡物更远，则可能被遮挡
            if (distance_to_biased_point > mean_distance_to_occluder) {
                // 计算方差 σ^2 = E[d^2] - (E[d])^2
                float variance = abs((visibility.x * visibility.x) - visibility.y);
                const float distance_diff = distance_to_biased_point - mean_distance_to_occluder;
                // 应用切比雪夫不等式计算光照透过率（即权重）
                chebyshev_weight = variance / (variance + (distance_diff * distance_diff));
                // 增强对比度，使阴影更明显
                chebyshev_weight = max((chebyshev_weight * chebyshev_weight * chebyshev_weight), 0.0f);
            }
            // 保证权重不完全为0，避免在全黑区域出现问题
            weight *= max(0.05f, chebyshev_weight);
        }
        
        // --- 采样与混合 ---

        // 【关键点4: 三线性插值权重】
        // 根据之前计算的alpha值，计算当前探针的三线性插值权重。
        // mix(1-a, a, offset) 是一个简洁的实现方式。
        vec3 trilinear = mix(1.0 - alpha, alpha, vec3(offset));
        weight *= trilinear.x * trilinear.y * trilinear.z + 0.001f; // +0.001f 避免权重为0

        // 采样预计算好的Irradiance纹理图集
        vec2 uv = get_probe_uv(normal, probe_index, irradiance_texture_width, irradiance_texture_height, irradiance_side_length);
        vec3 probe_irradiance = textureLod(global_textures[nonuniformEXT(grid_irradiance_output_index)], uv, 0).rgb;

        // 如果使用了感知编码，需要解码
        if (use_perceptual_encoding()) {
            probe_irradiance = pow(probe_irradiance, vec3(0.5f * 5.0f));
        }

        // 累加加权后的irradiance和总权重
        sum_irradiance += weight * probe_irradiance;
        sum_weight += weight;
    }

    // --- Finalize ---
    // 通过总权重进行归一化，得到最终混合后的irradiance
    vec3 net_irradiance = sum_irradiance / sum_weight;

    // 如果使用了感知编码，需要重新编码
    if (use_perceptual_encoding()) {
        net_irradiance = net_irradiance * net_irradiance;
    }

    // 最后乘以 PI 和一个缩放因子，这是漫反射BRDF积分的一部分
    vec3 irradiance = 0.5f * PI * net_irradiance * 0.95f;

    return irradiance;
}

layout (local_size_x = 8, local_size_y = 8, local_size_z = 1) in;

void main() {
    // 获取当前线程处理的像素坐标
    ivec3 coords = ivec3(gl_GlobalInvocationID.xyz);

    // --- 半分辨率优化处理 ---
    int resolution_divider = output_resolution_half == 1 ? 2 : 1;
    vec2 screen_uv = uv_nearest(coords.xy, resolution / resolution_divider);
    
    float raw_depth = 1.0f;
    int chosen_hiresolution_sample_index = 0;
    // 如果启用半分辨率模式，从高分辨率深度图中采样4个点，选择最靠近摄像机的那个
    // 这是为了在升采样时，保留边缘（深度不连续处）的正确信息
    if (output_resolution_half == 1) {
        ivec2 pixel_offsets[] = ivec2[](ivec2(0,0), ivec2(0,1), ivec2(1,0), ivec2(1,1));
        float closer_depth = 1.f;
        for (int i = 0; i < 4; ++i) {
            float depth = texelFetch(global_textures[nonuniformEXT(depth_fullscreen_texture_index)], (coords.xy * 2) + pixel_offsets[i], 0).r;
            if (closer_depth > depth) {
                closer_depth = depth;
                chosen_hiresolution_sample_index = i;
            }
        }
        raw_depth = closer_depth;
    } else {
        // 全分辨率模式，直接采样
        raw_depth = texelFetch(global_textures[nonuniformEXT(depth_fullscreen_texture_index)], coords.xy, 0).r;
    }

    // 如果深度为1.0，说明是天空盒，直接输出黑色
    if (raw_depth == 1.0f) {
        imageStore(global_images_2d[indirect_output_index], coords.xy, vec4(0, 0, 0, 1));
        return;
    }

    // --- 重建表面属性 ---
    // 根据深度值重建世界坐标
    const vec3 pixel_world_position = world_position_from_depth(screen_uv, raw_depth, inverse_view_projection);
    
    // 获取对应像素的法线
    vec3 normal;
    if (output_resolution_half == 1) {
        // 半分辨率模式下，使用之前选定的高分辨率样本的法线
        vec2 encoded_normal = texelFetch(global_textures[nonuniformEXT(normal_texture_index)], (coords.xy * 2) + pixel_offsets[chosen_hiresolution_sample_index], 0).rg;
        normal = normalize(octahedral_decode(encoded_normal));
    } else {
        vec2 encoded_normal = texelFetch(global_textures[nonuniformEXT(normal_texture_index)], coords.xy, 0).rg;
        normal = octahedral_decode(encoded_normal);
    }
    
    // --- 调用核心函数计算并输出 ---
    vec3 irradiance = sample_irradiance(pixel_world_position, normal, camera_position.xyz);
    imageStore(global_images_2d[indirect_output_index], coords.xy, vec4(irradiance, 1));
}

void updateProbeOffsetsAndStatus() {
    // --- 探针偏移计算 ---
    // 这是一个渐进式更新过程，只在需要时（gi_recalculate_offsets为true）启动，并持续数帧（24帧）以达到稳定。
    static i32 offsets_calculations_count = 24;
    if (render_scene->gi_recalculate_offsets) {
        offsets_calculations_count = 24; // 重新开始24帧的计算周期
    }

    // 如果仍在计算周期内，则执行偏移计算
    if (offsets_calculations_count >= 0) {
        --offsets_calculations_count;

        // 绑定管线和资源，准备写入探针偏移纹理

        // 向Shader传递一个标记，告知是否为本轮计算的第一帧
        u32 first_frame = (offsets_calculations_count == 23) ? 1 : 0;
        gpu_commands->push_constants(calculate_probe_offset_pipeline, 0, 4, &first_frame);

        // 为每个探针启动一个线程
        gpu_commands->dispatch(hydra::ceilu32(probe_count / 32.f), 1, 1);
    }

    // --- 探针状态计算 ---
    // 这个过程通常每帧都运行，以快速响应场景变化。
    
    // 绑定管线和资源，准备更新探针状态

    // 为每个探针启动一个线程
    gpu_commands->dispatch(hydra::ceilu32(probe_count / 32.f), 1, 1);
}

// 每个线程负责一个光照探针
layout (local_size_x = 32, local_size_y = 1, local_size_z = 1) in;
void main() {
    int probe_index = int(gl_GlobalInvocationID.x);
    if (probe_index >= total_probes) return; // 越界检查

    // --- 1. 分析光线追踪结果 ---
    // 遍历该探针的所有预追踪光线，分析命中信息
    // 命中信息来自一个前置的光追Pass，其.w分量存储了距离。约定：w > 0 为正面，w < 0 为背面。
    int closest_backface_index = -1;      // 最近的背面光线索引
    float closest_backface_distance = 100000000.f; // 最近的背面距离
    int closest_frontface_index = -1;     // 最近的正面光线索引
    float closest_frontface_distance = 100000000.f; // 最近的正面距离
    int farthest_frontface_index = -1;    // 最远的正面光线索引
    float farthest_frontface_distance = 0; // 最远的正面距离
    int backfaces_count = 0;              // 背面命中总数

    for (int ray_index = 0; ray_index < probe_rays; ++ray_index) {
        ivec2 ray_tex_coord = ivec2(ray_index, probe_index);
        float ray_distance = texelFetch(global_textures[nonuniformEXT(radiance_output_index)], ray_tex_coord, 0).w;

        if (ray_distance <= 0.0f) { // 命中背面
            ++backfaces_count;
            float dist = -ray_distance;
            if (dist < closest_backface_distance) {
                closest_backface_distance = dist;
                closest_backface_index = ray_index;
            }
        } else { // 命中正面
            if (ray_distance < closest_frontface_distance) {
                closest_frontface_distance = ray_distance;
                closest_frontface_index = ray_index;
            }
            if (ray_distance > farthest_frontface_distance) { // 注意这里是 if 不是 else if
                farthest_frontface_distance = ray_distance;
                farthest_frontface_index = ray_index;
            }
        }
    }

    // --- 2. 基于启发式规则计算新偏移 ---
    vec3 full_offset = vec3(10000.f); // 初始设为无效值
    vec3 cell_offset_limit = max_probe_offset * probe_spacing; // 偏移不能超出探针单元格太多

    // 读取上一帧的偏移量，实现渐进式更新
    vec4 current_offset = vec4(0);
    if (first_frame == 0) {
        // ... (从纹理中读取 current_offset.rgb)
    }

    // 【启发式规则 1: 探针在墙内】
    // 如果超过1/4的光线击中背面，我们认为探针在几何体内。
    const bool inside_geometry = (float(backfaces_count) / float(probe_rays)) > 0.25f;
    if (inside_geometry && (closest_backface_index != -1)) {
        // 目标：将探针沿“最近的背面”的反方向推出。
        const vec3 closest_backface_direction = closest_backface_distance * normalize(mat3(random_rotation) * spherical_fibonacci(closest_backface_index, probe_rays));
        // ... (计算推出的距离因子 direction_scale_factor)
        // 新偏移 = 当前偏移 - 推出的向量 (减号代表反方向)
        full_offset = current_offset.xyz - closest_backface_direction * direction_scale_factor;
    }
    // 【启发式规则 2: 探针离墙太近】
    else if (closest_frontface_distance < 0.05f) {
        // 目标：将探针沿“最远的视线方向”移动，即推向更开阔的空间。
        const vec3 farthest_direction = min(0.2f, farthest_frontface_distance) * normalize(mat3(random_rotation) * spherical_fibonacci(farthest_frontface_index, probe_rays));
        const vec3 closest_direction = normalize(mat3(random_rotation) * spherical_fibonacci(closest_frontface_index, probe_rays));
        // 如果最远和最近方向大致相反（点积小），才进行移动，避免在角落里抖动
        if (dot(farthest_direction, closest_direction) < 0.5f) {
            full_offset = current_offset.xyz + farthest_direction;
        }
    } 

    // --- 3. 应用并写回新偏移 ---
    // 只有当计算出的新偏移在合理范围内时，才更新它
    if (all(lessThan(abs(full_offset), cell_offset_limit))) {
        current_offset.xyz = full_offset;
    }
    // 将最终偏移写回纹理
    imageStore(global_images_2d[probe_offset_texture_index], /* ... coords ... */, current_offset);
}

// 每个线程负责一个光照探针
layout (local_size_x = 32, local_size_y = 1, local_size_z = 1) in;
void main() {
    int probe_index = int(gl_GlobalInvocationID.x);
    // ... (越界检查)

    // --- 1. 分析光线追踪结果 (与上一个Shader类似) ---
    int backfaces_count = 0;
    float closest_frontface_distance = 100000000.f;
    // ... (省略类似的循环和变量来查找背面命中数和最近正面距离)
    for (int ray_index = 0; ray_index < probe_rays; ++ray_index) {
        // ...
    }

    // --- 2. 基于启发式规则判断状态 ---
    // 读取上一帧的状态
    uint flag = probe_status[probe_index]; 
    // 定义一个有效着色范围，如果命中点在此范围内，探针就应该激活
    vec3 outerBounds = normalize(probe_spacing) * (length(probe_spacing) + (2.0f * self_shadow_bias));

    // 重新检查所有正面命中
    for (int ray_index = 0; ray_index < probe_rays; ++ray_index) {
        float d_front = /* ... texelFetch ... */;
        if (d_front > 0.0f) {
            vec3 frontFaceDirection = d_front * normalize(mat3(random_rotation) * spherical_fibonacci(ray_index, probe_rays));
            // 【规则1: 激活】如果任何一个命中点在有效范围内，说明此探针能影响附近表面，激活它。
            if (all(lessThan(abs(frontFaceDirection), outerBounds))) {
                flag = PROBE_STATUS_ACTIVE;
            }
        }
    }

    // 【规则2: 关闭】如果探针在墙内，关闭它。
    if (closest_backface_index != -1 && (float(backfaces_count) / float(probe_rays)) > 0.25f) {
        flag = PROBE_STATUS_OFF;
    }
    // 【规则3: 关闭】如果探针什么正面都没看到（例如在天空或空旷区域），关闭它。
    else if (closest_frontface_index == -1) {
        flag = PROBE_STATUS_OFF;
    }
    // 【规则4: 激活】如果探针离某个表面非常近，激活它。
    else if (closest_frontface_distance < 0.05f) {
        flag = PROBE_STATUS_ACTIVE;
    } 

    // --- 3. 写回新状态 ---
    probe_status[probe_index] = flag;
}

/**
 * @brief  计算阴影可见性的方差（Variance）。
 *
 * @details 该计算着色器通过分析前四帧的阴影可见性历史数据，来计算每个像素的可见性方差。
 * 这个方差值实际上是一个简化的衡量标准（取最大值与最小值的差），用于表示阴影的“不稳定性”。
 * 结果将被存储到一个新的纹理中，供后续的采样数估算步骤使用。
 * 此过程在半分辨率下运行以提高性能。
 */

// 定义计算着色器的本地工作组大小为 8x8x1。
// 意味着每个工作组包含 64 个着色器调用（线程）。
layout (local_size_x = 8, local_size_y = 8, local_size_z = 1) in;

void main() {
    // --- 1. 计算当前处理的像素坐标 ---

    // 获取目标纹理的分辨率（半分辨率）。
    ivec2 iresolution = ivec2(resolution * 0.5);

    // 检查当前着色器调用（线程）是否在目标纹理的有效范围内。
    // 如果超出范围，则直接返回，不做任何处理。
    // gl_GlobalInvocationID 是当前线程在整个网格中的唯一ID。
    if (gl_GlobalInvocationID.x >= iresolution.x || gl_GlobalInvocationID.y >= iresolution.y) {
        return;
    }

    // 将全局调用ID转换为纹理坐标，用于读取和写入。
    ivec3 tex_coord = ivec3(gl_GlobalInvocationID.xyz);


    // --- 2. 读取历史可见性数据 ---

    // 从3D纹理（实际上用作2D纹理数组）中读取存储的前四帧的可见性数据。
    // texelFetch 用于精确获取指定整数坐标的纹素值，无需归一化。
    // `visibility_cache_texture_index` 是一个全局uniform变量，指向包含历史数据的纹理。
    // 返回的 vec4 中，每个分量（x, y, z, w）分别代表了过去某一帧的可见性值（0.0为完全阴影，1.0为完全照亮）。
    vec4 last_visibility_values = texelFetch(global_textures_3d[visibility_cache_texture_index], tex_coord, 0);


    // --- 3. 计算可见性方差 ---

    // 找到这四帧可见性中的最大值。
    float max_v = max(max(last_visibility_values.x, last_visibility_values.y), max(last_visibility_values.z, last_visibility_values.w));

    // 找到这四帧可见性中的最小值。
    float min_v = min(min(last_visibility_values.x, last_visibility_values.y), min(last_visibility_values.z, last_visibility_values.w));

    // 计算最大值与最小值之差。这个差值（delta）被用作方差的近似衡量。
    // 如果差值大，说明在过去几帧里，该像素的阴影状态变化剧烈（例如，从全亮到全黑）。
    // 如果差值小，说明阴影状态很稳定。
    float delta = max_v - min_v;


    // --- 4. 存储计算结果 ---

    // 将计算出的方差值（delta）写入到输出图像（Image）中。
    // imageStore 用于向指定整数坐标的图像写入数据。
    // `variation_texture_index` 指向用于存储方差结果的纹理。
    // 这里只使用了vec4的第一个分量（r通道）来存储delta。
    imageStore(global_images_3d[variation_texture_index], tex_coord, vec4(delta, 0.0, 0.0, 0.0));
}

/**
 * @brief  估算采样数、执行光追并更新历史缓存。
 *
 * @details
 * 该着色器是自适应光追阴影的核心。其主要工作包括：
 * 1. (空间滤波) 对上一阶段的方差图进行最大值滤波和帐篷滤波，以平滑和扩大不稳定的区域。
 * 2. (时间滤波) 将滤波后的方差与历史数据结合，进一步稳定信号。
 * 3. (采样数估算) 根据最终的稳定方差值，动态地增加或减少每个像素的阴影光线采样数。
 * 4. (光线追踪) 根据估算出的采样数，调用光线追踪函数，计算当前像素的原始阴影可见性。
 * 5. (更新缓存) 将本帧计算出的新数据（可见性、方差、采样数）写入历史缓存，供下一帧使用。
 */

// 定义工作组大小为 8x8
#define GROUP_SIZE 8
// 定义共享内存大小，需要比工作组大，以容纳邻域数据 (8 + 6*2 = 20)
#define LOCAL_DATA_SIZE (GROUP_SIZE + 6 * 2)

layout (local_size_x = GROUP_SIZE, local_size_y = GROUP_SIZE, local_size_z = 1) in;

// 声明共享内存，用于在工作组内高效地共享像素数据，避免重复读取全局内存
shared float local_image_data[LOCAL_DATA_SIZE][LOCAL_DATA_SIZE];
shared float local_max_image_data[LOCAL_DATA_SIZE][LOCAL_DATA_SIZE];

// [! 为了篇幅，此处省略 max_filter, read_variation_value, tent_kernel 的定义 !]
// [! 它们的功能将在下面的原理解析中详细说明 !]

void main() {
    // --- 准备工作：坐标计算与边界检查 ---
    ivec2 iresolution = ivec2(resolution * 0.5);
    if (gl_GlobalInvocationID.x >= iresolution.x || gl_GlobalInvocationID.y >= iresolution.y)
        return;

    ivec3 local_index = ivec3(gl_LocalInvocationID.xyz) + ivec3(6, 6, 0);
    ivec3 global_index = ivec3(gl_GlobalInvocationID.xyz);

    // --- 第 1 步：加载方差数据到共享内存 (优化) ---
    // 每个线程负责将自己的方差值读入共享内存。
    // 边界上的线程会额外加载邻域数据，供整个工作组使用。
    // ... 此处省略了复杂的邻域加载代码，其目的是将一个更大的区域(20x20)读入共享内存 ...
    // local_image_data[...][...] = texelFetch(variation_texture_index, ...);
    
    // 同步点：确保所有线程都已将数据写入共享内存，才能继续
    memoryBarrierShared();
    barrier();

    // --- 第 2 步：空间滤波 - 最大值滤波 (Max Filter) + 帐篷滤波 (Tent Filter) ---

    // 2.1 对原始方差图进行 5x5 最大值滤波。
    // 这会“扩张”不稳定的区域，确保阴影边缘得到充分处理。
    float max_filtered_value = max_filter(local_index);
    local_max_image_data[local_index.y][local_index.x] = max_filtered_value;
    
    // 同步点：确保最大值滤波完成
    memoryBarrierShared();
    barrier();

    // 2.2 对最大值滤波的结果再进行 13x13 帐篷滤波（加权平均）。
    // 这会进一步平滑和模糊方差信号，使其变化更平缓。
    // `tent_kernel` 是一个预计算的权重矩阵。
    float spatial_filtered_value = 0.0;
    // ... 此处省略了 tent filter 的循环代码，它将 local_max_image_data 与 tent_kernel 相乘求和 ...
    // spatial_filtered_value = a_sum_of(local_max_image_data * tent_kernel);

    // --- 第 3 步：时间滤波 ---
    // 读取上一帧的滤波后方差历史值
    vec4 last_variation_values = texelFetch(global_textures_3d[variation_cache_texture_index], global_index, 0);
    // 将当前帧的空间滤波结果与历史结果进行混合，得到一个更稳定的最终方差信号。
    float final_filtered_value = 0.5 * (spatial_filtered_value + 0.25 * (last_variation_values.x + last_variation_values.y + last_variation_values.z + last_variation_values.w));
    
    // 从G-Buffer读取运动矢量。-1.0 是一个标记，表示该像素没有有效的历史。
    float motion_vectors_value = texelFetch(global_textures[motion_vectors_texture_index], ...).r;

    // --- 第 4 步：采样数量估算 ---
    uint sample_count;

    // ===================================================================
    // 分支 1: 历史有效 (Temporal Reprojection is Successful)
    // ===================================================================
    if (motion_vectors_value.r != -1.0) {
        // 继承上一帧的采样数作为基础
        uvec4 sample_count_history = texelFetch(..., samples_count_cache_texture_index, ...);
        sample_count = sample_count_history.x;

        // 检查历史是否稳定
        bool stable_sample_count = (sample_count_history.x == sample_count_history.y) && ...;
        
        // 对天空盒等特殊情况做处理
        if (raw_depth == 1.0f) {
            sample_count = 0;
        } 
        // 应用带有“惯性”的调整逻辑 (Hysteresis)
        else {
            // 如果方差大，增加采样数
            if (filtered_value > delta && sample_count < MAX_SHADOW_VISIBILITY_SAMPLE_COUNT) {
                sample_count += 1;
            } 
            // 如果方差小且历史稳定，减少采样数
            else if (stable_sample_count && sample_count >= 1 && (filtered_value < delta)) {
                sample_count -= 1;
            }
            // 保证最少有1个采样
            sample_count = max(sample_count, 1u);
        }
    } 
    // ===================================================================
    // 分支 2: 历史无效 (Disocclusion Detected)
    // ===================================================================
    else {
        // 对于没有历史的“新”像素，我们无法预测其复杂度。
        // 采取保守策略：直接使用最大采样数，以保证第一次出现的质量，避免闪烁。
        sample_count = MAX_SHADOW_VISIBILITY_SAMPLE_COUNT;
    }

    // --- 第 5 步：执行光线追踪 ---
    float visibility = 0.0;
    if (sample_count > 0) {
        // 准备光追所需数据：世界坐标、法线等
        const vec3 pixel_world_position = ...;
        const vec3 normal = ...;
        
        // 根据灯光类型，调用不同的光追函数
        if (is_raytrace_shadow_point_light()) {
            visibility = get_point_light_visibility(..., sample_count, ...);
        } else {
            visibility = get_directional_light_visibility(..., sample_count, ...);
        }
    }

    // --- 第 6 步：更新所有历史缓存 ---
    // 更新可见性历史、方差历史和采样数历史，将当前帧的数据推入队列
    
    vec4 new_visibility_history;

    // ===================================================================
    // 分支 1: 历史有效
    // ===================================================================
    if (motion_vectors_value.r != -1.0) {
        // 读取旧的历史值
        new_visibility_history = texelFetch(..., visibility_cache_texture_index, ...);
        
        // 将历史数据像队列一样前移一位
        new_visibility_history.w = new_visibility_history.z;
        new_visibility_history.z = new_visibility_history.y;
        new_visibility_history.y = new_visibility_history.x;
    } 
    // ===================================================================
    // 分支 2: 历史无效
    // ===================================================================
    else {
        // 历史数据是错误的（属于上一个物体），必须被丢弃。
        // 直接用当前帧计算出的新可见性值，填满整个历史记录。
        // 这相当于重置(reset)了这个像素的时间滤波器，防止产生鬼影(ghosting)。
        new_visibility_history.w = visibility;
        new_visibility_history.z = visibility;
        new_visibility_history.y = visibility;
    }
    // 无论哪个分支，都把当前帧的新可见性值放到历史记录的第一位
    new_visibility_history.x = visibility;
    

    // ... 此处省略了繁琐的历史数据更新和 imageStore 写入代码 ...
    // imageStore(visibility_cache_texture_index, ..., new_visibility_history);
    // imageStore(filtered_variation_texture_index, ..., vec4(spatial_filtered_value, 0, 0, 0));
    // imageStore(variation_cache_texture_index, ..., new_variation_history);
    // imageStore(samples_count_cache_texture_index, ..., new_sample_count_history);
}

/**
 * @brief  计算屏幕空间的运动矢量。
 *
 * @details
 * 该计算着色器通过比较当前帧和上一帧的顶点位置，为每个像素生成运动矢量。
 * 它会输出两种运动矢量：
 * 1. 标准运动矢量：用于 TAA，精确计算了物体运动并移除了相机抖动(Jitter)的影响。
 * 2. 可见性运动矢量：用于阴影等需要历史有效性判断的场景，如果重投影不合法，
 * 则存入一个特殊标记(-1, -1)。
 */

// 输出目标：一个用于TAA的标准运动矢量纹理
layout(rg16f, set = MATERIAL_SET, binding = 51) uniform image2D motion_vectors;
// 输出目标：一个用于可见性/阴影缓冲区的运动矢量纹理
layout(rg16f, set = MATERIAL_SET, binding = 52) uniform image2D visibility_motion_vectors;

layout(set = MATERIAL_SET, binding = 53) uniform sampler2D normals_texture;

layout (local_size_x = 8, local_size_y = 8, local_size_z = 1) in;

void main() {
    ivec3 pos = ivec3(gl_GlobalInvocationID.xyz);

    // --- 第 1 步：重建当前像素的世界坐标 ---
    const float raw_depth = texelFetch(global_textures[nonuniformEXT(depth_texture_index)], pos.xy, 0).r;
    // 如果是天空盒或背景，则没有运动，直接返回。
    if (raw_depth == 1.0) {
        imageStore(motion_vectors, pos.xy, vec4(0));
        imageStore(visibility_motion_vectors, pos.xy, vec4(-1, -1, 0, 0)); // 标记为无效
        return;
    }
    const vec2 screen_uv = uv_nearest(pos.xy, resolution);
    const vec3 pixel_world_position = world_position_from_depth(screen_uv, raw_depth, inverse_view_projection);

    // --- 第 2 步：计算当前和历史的NDC坐标 ---
    // 计算当前像素在当前帧的NDC（归一化设备坐标，范围[-1, 1]）坐标。
    vec4 current_position_ndc = vec4(ndc_from_uv_raw_depth(screen_uv, raw_depth), 1.0f);
    // 将当前世界坐标用【上一帧】的视图投影矩阵进行变换，得到该点在【上一帧】的NDC坐标。
    vec4 previous_position_ndc = previous_view_projection * vec4(pixel_world_position, 1.0f);
    previous_position_ndc.xyz /= previous_position_ndc.w; // 执行透视除法

    // ===================================================================
    // 任务 A: 计算标准运动矢量 (用于 TAA)
    // ===================================================================
    // 2D运动矢量即为两帧NDC坐标的xy差值。
    vec2 velocity = current_position_ndc.xy - previous_position_ndc.xy;

    // 为了实现 TAA，每一帧的投影矩阵都会有一个亚像素级别的抖动(Jitter)。
    // 计算出的速度必须减去这个相机抖动带来的位移，以得到物体纯粹的运动。
    vec2 jitter_difference = (jitter_xy - previous_jitter_xy) * 0.5f;
    velocity -= jitter_difference;

    // 将最终的、经过抖动校正的运动矢量写入纹理。
    imageStore(motion_vectors, pos.xy, vec4(velocity, 0, 0));

    // ===================================================================
    // 任务 B: 计算可见性运动矢量 (用于阴影)
    // ===================================================================
    // 这是一个带有效性检查的运动矢量。
    // 首先，计算两帧之间归一化的深度差异。
    float depth_diff = abs(1.0 - (previous_position_ndc.z / current_position_ndc.z));

    // 然后，计算一个自适应的深度差异阈值 eps。
    // 这个阈值会根据表面法线与视线夹角（view_normal.z）动态变化。
    // 表面越是正对屏幕，eps越大，容差越高。
    vec3 normal = octahedral_decode(texelFetch(normals_texture, pos.xy, 0).rg);
    vec4 view_normal = world_to_camera * vec4(normal, 0.0);
    float c1 = 0.003, c2 = 0.017;
    float eps = c1 + c2 * abs(view_normal.z);

    // 如果深度差异在容差范围内，则认为重投影有效，存储原始的运动矢量。
    // 否则，认为发生了遮挡剔除 (disocclusion)，存入一个特殊标记值 (-1, -1)。
    vec2 visibility_motion = depth_diff < eps ? (current_position_ndc.xy - previous_position_ndc.xy) : vec2(-1, -1);
    
    imageStore(visibility_motion_vectors, pos.xy, vec4(visibility_motion, 0, 0));
}

/**
 * @brief  为点光源计算阴影可见性（软阴影）。
 * @param light_index       当前处理的点光源索引（未使用，但可能用于多光源场景）。
 * @param sample_count      根据方差估算出的，需要为此像素发射的光线数量。
 * @param world_position    当前像素在世界坐标系中的位置。
 * @param normal            当前像素表面的法线。
 * @param frame_index       当前帧的索引，用于在泊松盘采样中实现时间上的抖动。
 * @return float            最终的可见性（0.0为完全阴影，1.0为完全照亮）。
 */
float get_point_light_visibility(uint light_index, uint sample_count, vec3 world_position, vec3 normal, uint frame_index) {
    // --- 1. 计算基础光照几何信息 ---

    // 计算从像素表面指向光源的向量。
    const vec3 position_to_light = raytraced_shadow_light_position - world_position;
    // 归一化该向量，得到标准的光线方向 'l'。
    const vec3 l = normalize(position_to_light);
    // 计算法线与光线方向的点积 (N dot L)。如果小于0，说明表面背向光源。
    const float NoL = dot(normal, l);
    // 计算像素到光源的实际距离 'd'。
    const float distance_to_light = length(position_to_light);

    // --- 2. 构建采样所需的坐标系 ---

    // 为了在垂直于光线方向的平面上进行随机采样（模拟光源面积），
    // 我们需要构建一个局部坐标系。
    // 首先，通过与一个固定的'up'向量（这里用Y轴）进行叉乘，得到x轴。
    vec3 x_axis = normalize(cross(l, vec3(0.0f, 1.0f, 0.0f)));
    // 再次叉乘，得到与x轴和光线方向都垂直的y轴。
    vec3 y_axis = normalize(cross(x_axis, l));

    // --- 3. 初始化并进行光照剔除/衰减检查 ---

    float visibility = 0.0; // 初始化可见性累加器

    // 获取点光源的半径（影响范围）。
    const float light_radius = raytraced_shadow_light_radius;
    // 计算基于距离平方反比的光照衰减。
    float attenuation = attenuation_square_falloff(position_to_light, 1.0f / light_radius);

    // 为了模拟光源的体积，计算一个缩放因子。
    // 距离光源越近，光源看起来越大，因此软阴影的半影区域也应该越宽。
    // 这个因子用于调整随机采样点的偏移范围。
    const float scaled_distance = light_radius / distance_to_light;

    // *** 核心性能优化与有效性检查 ***
    // 只有同时满足以下所有条件，才进行昂贵的光线追踪计算：
    // 1. NoL > 0.001f:         表面必须朝向光源。
    // 2. distance_to_light <= light_radius: 像素必须在光源的影响半径之内。
    // 3. attenuation > 0.001f:  光照衰减后的强度足够大，值得计算。
    if ((NoL > 0.001f) && (distance_to_light <= light_radius) && (attenuation > 0.001f)) {
        
        // --- 4. 循环执行光线追踪 ---
        for (uint s = 0; s < sample_count; ++s) {

            // 从预计算的泊松盘采样表中获取一个2D随机点。
            // `(s * FRAME_HISTORY_COUNT + frame_index) % SAMPLE_NUM` 确保每一帧、每一次采样的随机点都不同。
            vec2 poisson_sample = POISSON_SAMPLES[(s * FRAME_HISTORY_COUNT + frame_index) % SAMPLE_NUM];
            
            // 将2D随机点映射到我们之前构建的3D坐标系上，并根据距离进行缩放，模拟光源的表观大小。
            // 这会产生一个指向光源虚拟面积上某个随机点的偏移向量。
            vec3 random_x = x_axis * poisson_sample.x * (scaled_distance) * 0.01; // 0.01是人为调整的缩放系数
            vec3 random_y = y_axis * poisson_sample.y * (scaled_distance) * 0.01;
            
            // 将原始光线方向与随机偏移结合，得到一条抖动后的新光线方向。
            vec3 random_dir = normalize(l + random_x + random_y);

            // 初始化光线查询
            rayQueryEXT rayQuery;
            rayQueryInitializeEXT(rayQuery, as, gl_RayFlagsOpaqueEXT | gl_RayFlagsTerminateOnFirstHitEXT,
                                  0xff,                // mask: 追踪所有不透明物体
                                  world_position,      // origin: 光线起点
                                  0.05,                // tMin:   最小距离，防止自相交
                                  random_dir,          // dir:    光线方向
                                  distance_to_light);  // tMax:   最大距离，光线只需追踪到光源位置即可
            
            // 执行光线追踪
            rayQueryProceedEXT(rayQuery);

            // 检查光线是否在到达光源前被遮挡
            if (rayQueryGetIntersectionTypeEXT(rayQuery, true) != gl_RayQueryCommittedIntersectionNoneEXT) {
                // 如果有交点，需要进一步判断交点是否真的在光源前面
                visibility += rayQueryGetIntersectionTEXT(rayQuery, true) < distance_to_light ? 0.0f : 1.0f;
            } else {
                // 如果没有命中任何物体，说明这条光路是通畅的
                visibility += 1.0f;
            }
        }
    }

    // --- 5. 返回最终结果 ---
    // 返回平均可见度。如果循环未执行，visibility为0，结果正确。
    return visibility / float(sample_count);
}