Skip to content

Refactor API status handling and add occlusion culling - #95

Draft
ZhuRuoLing wants to merge 11 commits into
Anvil-Dev:dev/26.1from
ZhuRuoLing:feat/occusion_culling
Draft

Refactor API status handling and add occlusion culling#95
ZhuRuoLing wants to merge 11 commits into
Anvil-Dev:dev/26.1from
ZhuRuoLing:feat/occusion_culling

Conversation

@ZhuRuoLing

@ZhuRuoLing ZhuRuoLing commented Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

This PR lays the first-stage foundation for occlusion culling in the rendering module and clarifies the visibility of selected internal APIs. It introduces the culler abstraction, GPU Query resources and draw path, and an OpenGL samples-query wrapper. The selectable Hi-Z and Query culling backends will be integrated in follow-up work.

Changes

  • Added OcclusionCuller, OcclusionKey, and OcclusionMethod to provide a common abstraction for rendering-feature submission, visibility decisions, and backend selection.
  • Added the occlusion-query render pipeline and its vertex and fragment shaders. Query geometry is rendered as a unit cube transformed to the feature AABB through FullTransformsUbo.
  • Extended the GPU device interface and the OpenGL implementation with samples-query creation and result retrieval, including the GlSamplesQuery lifecycle wrapper.
  • Added reusable GPU resource and ring-buffer foundations, with dedicated pools for Query objects and Query draw buffers to reduce allocation pressure across consecutive frames.
  • Added Query frame-state management: the current frame submits and executes queries, while the following frame reads their results to decide whether a feature should be drawn.
  • Changed compute-pass debug-group messages to lazy Supplier<String> values, avoiding unnecessary debug-text construction.
  • Updated ApiStatus.Internal annotations by removing them from mixin classes and explicitly marking rendering and sync classes, records, and extension interfaces that are internal implementations.

Impact and Compatibility

  • The occlusion-culling types currently provide the underlying infrastructure; runtime backend selection and the complete feature-culling flow are not wired in yet.
  • ALRComputePass.pushDebugGroup and its backend implementation now accept Supplier<String> instead of String; direct implementations and callers of this internal API must be updated accordingly.
  • The annotation changes clarify internal API boundaries and do not alter public feature behavior.

TODO

  • Add a Hierarchical Z based culling backend.
  • Add a Samples Query based culling backend.
  • Integrate occlusion culling with vanilla SubmitNodeStorage

@ZhuRuoLing
ZhuRuoLing marked this pull request as draft August 7, 2026 21:58
@Gugle2308

Gugle2308 commented Aug 7, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 5
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 5 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 10, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /opt/data/workspace/AnvilLib && grep -rn "debugLabels\|pushDebugGroup" module.rendering/src/main/java/dev/anvilcraft/lib/v2/rendering/mixins/blaze3d/gl/GlDebugLabelMixin.java | head; echo "===GlDeb...

Reason: script execution via -e/-c flag

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 10, 2026

Copy link
Copy Markdown

⏱️ Rate limited. Waiting 2.9s (attempt 2/3)...

@Gugle2308

Gugle2308 commented Aug 10, 2026

Copy link
Copy Markdown

⏱️ Rate limited. Waiting 4.9s (attempt 3/3)...

@Gugle2308

Gugle2308 commented Aug 10, 2026

Copy link
Copy Markdown

❌ Rate limited after 3 retries — Concurrency limit exceeded for user, please retry later

@Gugle2308

Gugle2308 commented Aug 10, 2026

Copy link
Copy Markdown

API call failed after 3 retries: Concurrency limit exceeded for user, please retry later

@Gugle2308

Gugle2308 commented Aug 11, 2026

Copy link
Copy Markdown

分析完成。以下是审查意见。

代码审查摘要 — PR #95

操作: synchronize
范围: 75 个文件 (70 Java, 29 新增, 0 删除) / 3249 行 diff
模块: module.rendering (主要) + module.sync (仅注解规范化) + module.test
分支: feat/occusion_culling → dev/26.1

🔴 关键（合并前需修复）

  • GlSamplesQuery.end() — GL46.glEndQuery(id) 传参错误（query/gl/GlSamplesQuery.java:34）
    LWJGL 的 glEndQuery(int target) 接收的是 target 枚举（GL_ANY_SAMPLES_PASSED），不是 query id。当前把 id 当 target 传入 → 每次 GL_INVALID_ENUM，query 永不结束；后续 glBeginQuery 会因同 target 已有活跃 query 而 GL_INVALID_OPERATION，所有查询全部失效。更严重的是 getValue() 用 GL_QUERY_RESULT 同步读取一个永不结束的 query 会永久阻塞渲染线程——一旦接入渲染管线就会整帧卡死。修复：GL46.glEndQuery(GL46.GL_ANY_SAMPLES_PASSED)。

  • GlSamplesQuery.getValue() — 4 字节分配 + 8 字节越界读（query/gl/GlSamplesQuery.java:52-55）
    stack.nmalloc(4) 只分配 4 字节（GL_ANY_SAMPLES_PASSED 结果是 GLuint），却用 MemoryAccess.getLong(buffer)（Unsafe.getLong）读 8 字节——高 32 位读到的是栈上残留垃圾。结果不确定：query 为 0（被遮挡）时若垃圾位非零，shouldDraw 会误判为可见（浪费填充率）；这是 OOB 读，属于未定义行为。修复：用 MemoryAccess.getInt 读 4 字节（或 nmalloc(8) + glGetQueryObjectui64v）。

这两处意味着 PR 声称已完成的 "[x] Samples Query backend" 实际不可用——虽然当前未接线不会立即崩溃，但接入即挂。建议合并前修复（都是两行改动）。

⚠️ 警告

  • ConvertDepthParamsUbo / IntSizeUbo — 宽高顺序与 GLSL 声明相反
    DEFINITION 顺序是 getHeight, getWidth，而对应 GLSL（depth_convert.csh 及 javadoc）声明为 uWidth; uHeight;。BufferObjectLayoutDefinition.writeInto 按条目顺序写入，第一个 4 字节 = Height 会落到 uWidth。Hi-Z 接入且深度纹理非正方形时边界检查会错。统一 getter 顺序或 GLSL 顺序其一即可。

  • fetchResults() 用 GL_QUERY_RESULT 同步读取 → 每帧全管线停顿
    FrameState.fetchResults() 对每个 key 做一次阻塞读，等于每帧强制 GPU 完成全部已提交工作——对以性能为目的的遮挡剔除是自毁。建议改 GL_QUERY_RESULT_AVAILABLE 轮询或延迟 2+ 帧读结果。另外注意：beginFrame() 中先 close()（把 query 归还池）再读新 previous frame 的结果，当前安全完全依赖 GL_QUERY_RESULT 的阻塞语义——若改成非阻塞读，归还顺序会变成悬垂复用风险，需一并调整。

  • 首帧/新 key 全部判不可见 → 闪烁风险
    GpuQueryOcclusionCuller.shouldDraw() 在 previousFrameState == null 时返回 false，新出现的 key 默认 0 也不画。culler 创建后第一帧全屏消失、新进入视野的物体延迟 1-2 帧才出现。惯例是"未知即画"（保守）避免 pop-in。

  • OcclusionMethod.GPU_QUERY 无能力检查 + 硬转 (ALRGpuDeviceExtension) device
    isSupported() 无条件返回 true，createInstance 直接强转——若 device mixin 未生效或 RenderSystem.getDevice() 为 null，直接 CCE/NPE。建议 instanceof 守卫。ALRHICapabilities.getInstance() 的强转同理（ALRComputeCapabilities.init() 从 GL.getCapabilities() 改为依赖 mixin，健壮性回退——时机本身安全，BloomPostEffect 在同一注入点已读 getDevice()）。

  • ALROptions.SPD_OPTION_WAVE_INTEROP_LDS 默认值 + define 映射反转
    getPropertyBoolean 未设置属性时默认 true，而 define 映射是 ? 0 : 1（代码里自己都注释了 "weird reverted"）→ 默认走 wave intrinsics 路径，shader #extension GL_KHR_shader_subgroup_quad : require + image2DArray[13]（超出 GL 最低保证的 8 个 image unit）。FFX_SPD pipeline 已在 ALRComputePipelines 注册，每次资源重载都会编译——不支持的 GPU 上会持续刷编译错误（好在外层降级为 INVALID 不崩溃）。建议默认映射到兼容路径并修正命名语义。

  • 新增 compute shader 用 Vulkan 风格 layout(set = 0, binding = N)
    桌面 GLSL 无 set 限定符，严格驱动会编译报错（depth_convert.csh 还用了 #version 460）。现有降级路径能兜住，但建议在目标驱动栈上验证。

💡 建议

  • BufferObjectLayoutEntry.Builder.forSetter(...) — setter 存进 Builder 但 build() 从未使用（record 只有 type+getter），且全 diff 无调用者 → 死 API，接线或删除。
  • FrameState.keys HashSet（含 import）— 声明后从未使用，删掉。
  • HierarchicalZOcculusionCuller — 类名/文件名拼写 "Occulusion" 与包名 occlusion 不一致；空实现 stub 建议在 createInstance 显式返回 null 即可（现状已如此），后续实现时注意。
  • GlSamplesQuery.getValue() 异常消息 "GlTimerQuery is closed" — 从计时 query 类复制粘贴的残留。
  • SPDConstantBuffer 缺少 @ApiStatus.Internal，同批 Hi-Z UBO（ConvertDepthParamsUbo/IntSizeUbo）都有 — 注解边界不一致。
  • FrameState.runQueries 里 // ChatGPT can make mistakes. Check important info. — 开发期注释，删除。
  • 每个 key 一个 createRenderPass，N 个 feature = N 个 pass；可在单个 pass 内连续 begin/draw/end 所有 query（buffer 已用 ring buffer 摊销，pass 是剩余的最大开销）。
  • ALROptimizations.occlusionCuller 静态懒加载无同步 — 目前仅渲染线程调用，安全；若将来多线程访问需 volatile/加锁。

🟢 看起来不错

  • 帧状态机设计正确：当前帧提交+执行、下一帧读结果；查询对象两帧后归还，配合阻塞读语义无复用竞态；池自动扩容处理 key 数增长。
  • 单位立方体 + FullTransformsUbo 方案很干净：288 字节顶点缓冲复用，每 key 只换 modelview；变换数学验证无误（translate(min) × scale(max-min) × viewRotation × -camPos）。
  • OCCLUSION_QUERY pipeline 配置正确：POSITION/QUADS、color WRITE_NONE、LEQUAL 深度测试且不写深度、6 个面全部 CCW 正面朝外配合 withCull(true)。
  • Supplier<String> 懒调试组重构在整条链（ALRComputePass → Backend → device extension → GlDebugLabel）一致完成，顺带删掉了 popDebugGroup 未使用的参数。
  • ApiStatus.Internal 重新分配（从 mixin 类移除、加到真实内部实现/UBO/record）符合描述意图，sync 模块 8 个文件规范化一致。

📋 声称验证表

声称 状态 对应文件
OcclusionCuller/OcclusionKey/OcclusionMethod 抽象 ✅ optimization/occlusion/*.java
查询渲染管线 + 顶点/片元着色器 + FullTransformsUbo ✅ ALRPipelines.OCCLUSION_QUERY, occlusion_query.vsh/.fsh
GPU 设备接口 + OpenGL samples-query（GlSamplesQuery 生命周期） ⚠️ GlSamplesQuery 存在但含 2 个 🔴 bug
可复用 GPU 资源 + ring buffer 基础（Query 池 / Query 缓冲池） ✅ GpuReusableResource(RingBuffer), LoopResetPool, SimpleResetPool, QueryBufferPack(RingBuffer)
Query 帧状态管理（当前帧提交执行、下帧读结果） ✅ FrameState, GpuQueryOcclusionCuller
compute-pass debug-group 懒 Supplier ✅ ALRComputePass(+Backend), GlComputePassBackend, GlDeviceMixin
ApiStatus.Internal 注解调整 ✅ 15 个 mixin 移除 + 内部实现类补注
[x] Samples Query backend ⚠️ 已实现但 glEndQuery/越界读使其实质不可用
[ ] Hi-Z backend ✅（按 TODO 未声称完成） 仅存 stub + depth_convert/ffx_spd shader + SPD pipeline 注册，未接线
[ ] 接入 vanilla SubmitNodeStorage ✅（未声称完成） 未实现，符合描述

结论: REQUEST_CHANGES — 基础设施和框架设计扎实，但 GlSamplesQuery 的两处错误（glEndQuery target 传参 + 4/8 字节越界读）会让已声称完成的 Samples Query 后端在接入时立即挂起渲染线程；修复后再合并。其余为 Hi-Z 接线前的潜在问题，建议顺手修正宽高顺序和默认 flag 映射。

由 Hermes Agent 审查

@Gugle2308

Gugle2308 commented Aug 11, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Skill 'rendering-gpu-pr-review' created.

@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

所有文件已审查完毕。汇总分析结果，输出审查意见：

代码审查摘要 — PR #95 (synchronize)

操作: synchronize
范围: 76 个文件（29 新增 / 47 修改 / 0 删除）/ 3358 行 diff
模块: module.rendering（occlusion culling 基础设施 + 注解整理）+ module.sync（纯注解规范化）

📋 声称验证表

声称 状态 对应文件
OcclusionCuller/Key/Method 抽象 ✅ optimization/occlusion/*
occlusion-query 管线 + 顶点/片元 shader ✅ ALRPipelines.OCCLUSION_QUERY, occlusion_query.{vsh,fsh}
GPU device 接口 + GL samples-query 扩展 ✅ ALRGpuDeviceExtension, GlDeviceMixin, GlSamplesQuery
GPU 资源池 / ring-buffer 基础 ✅ GpuReusableResourcePool, QueryInstancePool, DynamicUniformStorage
帧状态管理（本帧提交、下帧读结果） ✅ FrameState, GpuQueryOcclusionCuller
pushDebugGroup → Supplier<String> 惰性化 ✅ 5 处调用/实现全部迁移，无残留 String 调用
ApiStatus.Internal 注解调整 ✅ mixin 类移除（12 个）、内部实现类添加（sync 7 + rendering 若干）
Samples Query 后端 ✅ GpuQueryOcclusionCuller（已实现）
Hi-Z 后端 ✅（骨架） HierarchicalZOcculusionCuller 空壳 + OcclusionMethod.HIERARCHICAL_Z.createInstance 返回 null
与 vanilla SubmitNodeStorage 集成 ✅（未接线） ALROptimizations.getOcclusionCuller() 无任何调用者

🔴 关键（接入即错的 latent bug，建议合并前修）

  • IntSizeUbo / ConvertDepthParamsUbo 宽高互换 — BufferObjectLayoutDefinition.writeInto 按 entries 顺序写入（已在本地 dev/26.1 克隆验证），但 IntSizeUbo.DEFINITION 先 getHeight 后 getWidth，GLSL 声明却是 int uWidth; int uHeight;；ConvertDepthParamsUbo 同理。结果：depth_convert.csh 的边界检查 idx.x >= uWidth || idx.y >= uHeight 拿到互换后的值，宽图时右/下半区域被错误填充 uPadValue=1（深度 1.0=最远），Hi-Z 深度数据损坏。当前 Hi-Z 未接线所以不触发，但 UBO 定义就是错的，接上即坏——建议把两个 UBO 的 entry 顺序改为 getWidth, getHeight。
  • HierarchicalZOcculusionCuller.shouldDraw 返回 false（空壳） — 永不绘制。目前被 OcclusionMethod.HIERARCHICAL_Z.createInstance() → null 挡住，但任何人把该分支接通就会全屏消失。空壳至少应返回 true 或抛 UnsupportedOperationException，并加 @ApiStatus.Internal（或直接删除）。
  • OCCLUSION_QUERY pipeline withCull(true) — 相机位于 feature AABB 内部时（玩家走进大型结构/多方块建筑，很常见），单位立方体所有面都成背面被剔除 → 查询 0 samples → 下一帧 shouldDraw=false → 物体消失闪烁。遮挡查询的 box 应 cull(false)：深度 LEQUAL 下背面样本无害（背面深度 ≥ 正面，正面通过则结果一致），而剔除背面则盒内相机场景必然误判。

⚠️ 警告

  • ffx_spd_downsample_pass.csh 是 Vulkan GLSL 混用 + 无条件注册 — layout (set = 0, binding = N) 是 Vulkan 语法（OpenGL 严格驱动直接编译报错）；#extension GL_KHR_shader_subgroup_quad : require 使无 subgroup quad 的 GPU 编译失败；image2DArray rw_input_downsample_src_mips[13] 超出 GL 最低保证的 8 个 image unit。且该 pipeline 已在 ALRComputePipelines 注册（ALRComputeShaderManager 每次资源重载都会编译它），而 Hi-Z 未接线——为死代码付编译成本 + 兼容性风险双重问题。建议 Hi-Z 完成前不要注册。
  • ALRComputeCapabilities.init() 时机迁移的健壮性 — 从 ALRComputeShaderManager.apply（失败仅 log 降级）移到 MinecraftMixin.onCreateInstance（启动即崩路径）。ALRHICapabilities.getInstance() 硬转 (ALRGpuDeviceExtension) RenderSystem.getDevice()，mixin 未生效时 CCE。同注入点已有 ALRPostEffects.createPostEffects() 读 getDevice()（既有代码工作正常），大概率安全，但无回退。
  • OcclusionMethod.GPU_QUERY.isSupported() 无条件 true（假支持） — createInstance 中 (ALRGpuDeviceExtension) device 无 instanceof 守卫。由于 createInstance 优先走 Hi-Z 分支（恒 null）再落到 GPU_QUERY，任何 GPU 上都会创建 GPU_QUERY culler，isSupported 形同虚设。建议探测 device instanceof ALRGpuDeviceExtension。
  • GL_QUERY_RESULT 同步阻塞读与池复用时序绑定 — GlSamplesQuery.getValue() 每帧对 N 个 query 逐个同步读（高负载下 GPU 落后即管线停顿，与遮挡剔除的性能目标相悖）；更关键的是：FrameState.close() 释放 query 回池的安全性完全依赖阻塞读语义——当前时序（帧 N+1 读、帧 N+2 复用）恰好安全，但一旦改成 RESULT_AVAILABLE 非阻塞读，复用的 query id 可能仍在飞行中 → 悬垂复用。两者是一体的，请加注释锁定此依赖。
  • FFX_SPD_OPTION_WAVE_INTEROP_LDS define 反转 + 默认 true — ALROptions.getPropertyBoolean 对未设置属性返回 true（默认走 wave interop 路径），配合反转映射 ? 0 : 1（注释 "weird inverted"）和 shader 的 subgroup_quad : require，默认配置恰好导向兼容性最差的路径。建议默认改为纯 LDS 路径（define 1）。

💡 建议

  • MemoryAccess 用 sun.misc.Unsafe 反射 — Java 21 模块系统下 theUnsafe 的 setAccessible(true) 需要 jdk.unsupported 开放（launcher 的 --add-opens 不保证包含）；GlSamplesQuery 只需 4 字节读，直接用 LWJGL MemoryUtil.memGetInt 更稳。
  • ALROptimizations.getOcclusionCuller() — RenderSystem.getDevice() 可能在渲染线程外为 null → createInstance(null) 硬转 CCE，加 null 守卫。
  • QueryInstancePool(2) / GpuSampleQueryPool(16) 初始容量偏小 — 活跃 key 超过即触发 expand()（虽只建 CPU 侧对象，但 expand 后不缩容，峰值后池永久变大）。
  • BufferObjectLayoutEntry.Builder.forSetter 已加但 build() 未使用 — setter 字段被忽略，属半成品死代码。
  • BufferObject.createDynamicStorage 已 @Deprecated(forRemoval) 且无调用方 — 可直接删除。

🟢 看起来不错

  • GlSamplesQuery GL 调用全部正确：glBeginQuery(GL_ANY_SAMPLES_PASSED, id) 双参 / glEndQuery(GL_ANY_SAMPLES_PASSED) 单参（target 而非 id）/ nmalloc(4) + getInt 宽度匹配（4 字节结果 4 字节读）。
  • FullTransformsUbo getter 顺序 ↔ GLSL 声明顺序一致；QueryInstance 矩阵链 translate(min)·scale(size) 验证正确（单位立方体 → inflate(0.1) 后的 AABB）。
  • 未知 key 首帧语义保守（results.getOrDefault(key, 1) → 默认画，previousFrameState == null 时画）✅ 符合遮挡剔除惯例。
  • 单 renderPass 内连续 begin/draw/end 所有 query（无 N-pass 开销）✅。
  • 资源池复用逻辑（LoopResetPool 循环扫描 + fail 兜底 expand）正确，无 NPE 路径。
  • ApiStatus.Internal 注解调整彻底且风格与 chore(annotations): 添加 ApiStatus.Internal 注解到内部接口和类 #93/refactor(common): 优化代码导入 #96 一致；FFX SPD shader 附 AMD 官方 license 头；BufferObject.write 增加 SSBO 误用 guard。
  • sync 模块 7 个文件均为纯注解规范化（@org.jetbrains... → import 后 @ApiStatus.Internal），无行为变更。

结论: COMMENT — 基础设施质量高（GL 传参、矩阵数学、池复用均正确），PR 明确未接线所以当前不会影响运行；但 3 个关键项（UBO 宽高互换、Hi-Z 空壳 shouldDraw=false、cull(true) 盒内误判）都是「接入即挂」的确定性 latent bug，建议合并前至少修复 UBO 顺序，其余项记录为集成 Hi-Z/SubmitNodeStorage 前的必改清单。

由 Hermes Agent 审查

@ZhuRuoLing
ZhuRuoLing force-pushed the feat/occusion_culling branch from 3c58b50 to 4cdf68c Compare August 13, 2026 22:34
@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

unzip -l /tmp/nf26-sources.jar 2>/dev/null | head -5; echo "==="; python3 -c "
import zipfile
z = zipfile.ZipFile('/tmp/nf26-sources.jar')
names = [n for n in z.namelist() if 'DynamicUniformStorage' i...

Reason: script execution via -e/-c flag

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 6
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 6 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

All verification complete. I have a full picture of the PR. Writing the review:

代码审查摘要 — PR #95

操作: synchronize
范围: 75 个文件（29 新增）/ 3297 行 diff
主题: 遮挡剔除第一阶段基础设施 + API 状态注解整理

🔴 关键（接入前必须修复）

  • IntSizeUbo.java / hiz/ConvertDepthParamsUbo.java — 宽高互换（确定性 bug）
    Java 侧 DEFINITION 的 entry 顺序是 getHeight → getWidth，而 BufferObjectLayoutDefinition.writeInto 严格按 entry 顺序写入（已用本地克隆 dev/26.1 分支核实），第一个 entry 落在 GLSL 第一个声明字段。两个 UBO 的 javadoc GLSL 均为 int uWidth; int uHeight; → 实际写入是 height→uWidth, width→uHeight。一旦 Hi-Z 接线，depth_convert.csh 用 idx.x >= uWidth 判边界，互换后有效深度数据会落在错误区域、越界区反而被写入 pad 值 1.0。当前无调用方（latent），但这是接入即现的错误。修复：entry 顺序改为 getWidth, getHeight。

  • ALRPipelines.OCCLUSION_QUERY — withCull(true) + 相机在 AABB 内部时查询恒为 0
    查询几何是包围盒立方体，开启背面剔除后，当相机位于 feature 的 AABB 内部（玩家站在被剔除建筑里是常态），6 个面全部为背面 → 0 样本通过 → shouldDraw 返回 false → 下一帧整个 feature 消失（pop-in）。遮挡查询 pass 的三角形数量（36 索引 × N）远小于剔除收益，建议 withCull(false)，或至少加"相机在盒内强制绘制"守卫。

  • HierarchicalZOcculusionCuller.shouldDraw 恒返回 false
    占位桩的危险默认值：一旦 OcclusionMethod.HIERARCHICAL_Z.createInstance() 改为返回它（任务清单里 Hi-Z 是 next step），所有 feature 会被全部剔除。占位实现建议返回 true（保守画），与 Query 后端的语义保持一致。

⚠️ 警告

  • 硬转无 instanceof 守卫（latent CCE） — OcclusionCuller.createInstance 与 ALRHICapabilities.getInstance() 均直接 (ALRGpuDeviceExtension) RenderSystem.getDevice()。GpuDeviceMixin 未应用（mixin 冲突/插件禁用）→ CCE；早期调用时 getDevice() 可能为 null → NPE。且 OcclusionMethod.GPU_QUERY.isSupported() 无条件返回 true，是"假支持"探测——实际硬性前置只有 mixin 是否生效。建议 isSupported 里做 instanceof 检查或 try-catch。
  • ALRComputeCapabilities.init() 时机搬移引入 mixin 依赖 — 从资源重载（ALRComputeShaderManager）移到 MinecraftMixin 构造器 RETURN。与同注入点的 ALRPostEffects/CachedBlockEntityRenderingPipeline 一致，通常安全；但旧代码 GL.getCapabilities() 不依赖 mixin，新代码依赖注入接口 → mixin 失败从"重载时降级"变成"启动即崩"（AbstractMethodError/CCE）。可接受，但建议确认 mixin 应用的失败路径。
  • ComputeSupport.INSTANCE 现在可能为 null — module.test 中 GuiTestScreen / AnvilLibTestClient 均直接 ComputeSupport.INSTANCE.xxx 无空检查 → 非 compute GPU 上测试直接 NPE（行为变更）。建议测试入口加空值守卫或改为可空延迟初始化。
  • QueryInstance.CreationContext 静态 vertexBuffer — static GpuBuffer 跨所有 culler/设备共享：设备重建（context loss）后悬垂；QueryInstance.close() 是空实现，GpuQueryOcclusionCuller 也没有 destroy/close 路径 → query 池、commandEncoder 永不释放。接线前需要生命周期钩子（如 OcclusionCuller.close() + 资源重载重建）。
  • ALROptions.SPD_OPTION_WAVE_INTEROP_LDS 命名反转 — 属性默认 true → define 0（LDS-only 兼容路径），效果与属性名相反（作者注释 "weird inverted"）。且非默认路径启用 #extension GL_KHR_shader_subgroup_quad : require → 无 quad subgroup 的 GPU（GL < 4.6/旧硬件）编译失败；该 compute pipeline 已注册，每次资源重载都会编译并刷错误日志。建议反转映射或改名，并在 PR 描述中说明默认值语义。
  • 未接线状态的副作用 — ALROptimizations.getOcclusionCuller() 目前无任何调用者（AnvilLib 与 AnvilCraft 均 grep 不到），processFeatures 也无人调用 → query 从未 begin/end 时 fetchResults 读未使用 query（GL 结果实现定义，多数驱动返回 0）→ 全剔除。接线时必须同时接入 processFeatures 与 shouldDraw 的完整调用链，否则上述 latent 问题会全部同时爆发。

💡 建议

  • GlSamplesQuery.getValue() — 异常消息 "GlTimerQuery is closed" 是复制粘贴残留，应为 "GlSamplesQuery"。GL_QUERY_RESULT 阻塞读已通过"帧首读上一帧"缓解；若后续实测高负载帧停顿，可换 GL_QUERY_RESULT_AVAILABLE 轮询。
  • occlusion_query.fsh — pipeline 已 WRITE_NONE，fragColor 不会落屏，可用 discard 让意图更明确（可选）。
  • FrameState.runQueries — 单 RenderPass 内连续 begin/draw/end 全部 query，结构正确；getBuffer(6*6)（36 索引 = 6 面 QUADS）与 24 顶点 VB 匹配无误。
  • DynamicUniformStorage 512 容量 — MC 26.1 实现超限自动扩容（类内已有 resize 逻辑），无需担心。
  • BufferObject.createDynamicStorage 的 16 — 经核实是修复：构造器第三参是 initialCapacity（非 usage），旧代码误传 USAGE_UNIFORM | USAGE_COPY_DST（=18）当容量；新代码显式 16 + SSBO 守卫 + @Deprecated(forRemoval) 一致。建议在 PR 描述中注明此修复。

🟢 看起来不错

  • GL query API 传参全部正确 — glBeginQuery(target, id) 双参、glEndQuery(GL_ANY_SAMPLES_PASSED) 只传 target（未把 id 当 target 传）；nmalloc(4) 分配与 MemoryAccess.getInt 读取宽度一致（无越界读）。
  • 池复用时序安全 — 阻塞读发生在 release 之前、query 两帧后才归还池，无悬垂复用；FrameState.close() 与 beginFrame 的帧间交接（S(n-2) 归还 → S(n-1) 读取 → S(n) 新建）自洽。
  • 未知 key 语义保守 — shouldDraw 对无结果 key 默认 1、首帧 previousFrameState 为 null 时返回 true，符合"未知即画"惯例，无首帧全屏消失问题。
  • FullTransformsUbo 字段顺序正确 — getter 顺序（ProjMat → ModelViewMat）与 occlusion_query.vsh 的 GLSL 声明一致（对比之下更凸显另两个 UBO 的互换）。
  • OCCLUSION_QUERY 管线配置正确 — WRITE_NONE + depth write false + LESS_THAN_OR_EQUAL，查询 pass 不污染主颜色/深度目标，且在地形之后执行，遮挡语义正确。
  • Supplier<String> debug group 重构完整 — 接口（ALRGpuDeviceExtension/ALRGpuDeviceBackendExtension）、后端（GlDeviceMixin/GlComputePassBackend）、调用点（ALRComputePass）全链路一致，popDebugGroup 去参干净。
  • ApiStatus.Internal 注解清理与描述一致 — mixin 类（MinecraftMixin/GuiRendererMixin/GpuDeviceMixin 等 ~12 个）移除注解，内部实现类/扩展接口/sync 模块 ~20 处补标，sync 模块 8 个文件为纯注解变更。

📋 声称验证表

声称 状态 对应文件
OcclusionCuller / OcclusionKey / OcclusionMethod 抽象 ✅ 3 个新文件
occlusion-query 管线 + 顶点/片元着色器 ✅ ALRPipelines.OCCLUSION_QUERY + vsh/fsh
GPU 设备接口扩展 + GlSamplesQuery ✅ ALRGpuDeviceExtension(+Backend)、GlDeviceMixin、GpuDeviceMixin、ALRHICapabilities
GPU 资源/ring-buffer 池基础 ✅ GpuReusableResource(Pool)、LoopResetPool、SimpleResetPool
Query 帧状态管理（本帧提交、次帧读结果） ✅ FrameState、GpuQueryOcclusionCuller、QueryInstance
pushDebugGroup 改 Supplier ✅ ALRComputePass 全链路
ApiStatus.Internal 注解调整 ✅ 渲染 + sync 模块
Samples Query 后端 ⚠️ 已实现但未接线 GpuQueryOcclusionCuller；ALROptimizations.getOcclusionCuller() 无调用者
Hi-Z 后端 ⚠️ 仅骨架 HierarchicalZOcculusionCuller 空实现 + ffx_spd/depth_convert + UBOs；createInstance 返回 null
集成 vanilla SubmitNodeStorage ❌ TODO 无对应代码

🧪 测试建议

被测目标 推荐测试场景 优先级
FrameState.runQueries/fetchResults 连续多帧 key 增删：池无重复 acquire、结果延迟一帧生效、释放后复用安全 🔴
UBO 布局（接入后） IntSizeUbo/ConvertDepthParamsUbo 写入字节与 GLSL 声明逐字段对照 🔴
GpuQueryOcclusionCuller.shouldDraw 相机在 AABB 内部 / 包围盒部分可见 / 完全被地形遮挡三场景 🟡
GlSamplesQuery.getValue 查询未 begin/end 时读取、release 后结果重置、close 后抛异常 🟡

结论: REQUEST_CHANGES — 基础设施质量整体很高（GL 调用、池时序、帧状态设计都正确），但三个 🔴 均为确定性缺陷：两个 UBO 宽高互换是接入即现的错误、withCull(true) 在相机入盒场景会错误剔除、Hi-Z 占位桩默认返回 false 是隐患。三者修复成本都极低（各一行级别），建议修复后再合入，避免错误语义沉淀到后续接线 PR。ALROptimizations 的接线入口建议在本 PR 内补一个最小调用链（哪怕只在 debug 模式），让 latent 问题能在真实帧循环中提前暴露。

由 Hermes Agent 审查

@Gugle2308

Gugle2308 commented Aug 13, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 14, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 9
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 9 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 14, 2026

Copy link
Copy Markdown

审查完成，所有关键路径已交叉验证（本地克隆 AnvilLib@dev/26.1、MC 26.1 反编译产物、shader、GL 常量值）。以下是审查意见：

代码审查摘要 — PR #95

操作: synchronize
范围: 83 个文件（78 Java，35 新增，0 删除）/ 3932 行 diff

🔴 关键（确定性代码缺陷，接入即触发）

  • ALRComputePass.bindAll — 首轮调用必崩（ALRComputePass.java）
    新代码 bindingPoint += this.bind(bindingPoint, binding, elements.get(bindingPoint - 1)); 中 bindingPoint 初始为 0 → 第一轮即 elements.get(-1) → IndexOutOfBoundsException。旧代码是 bind(bindingPoint++, ..., elements.get(bindingPoint - 1))（先自增后取，等价 get(0)），语义在改签名时被破坏。应改为 elements.get(bindingPoint)。当前无调用者（已确认），但任何第一次 bindAll 调用都会崩。

  • QueryInstance.prepareMesh — x+ 面绕序反向（QueryInstance.java）
    x+ 面顶点 (1,0,0)→(1,0,1)→(1,1,1)→(1,1,0) 的叉积法线为 (-1,0,0)，与 outward +x 相反（其余 5 面均正确）。配合 OCCLUSION_QUERY 的 withCull(true)，从 +x 方向观察时正面被剔除，仅剩 4 个掠射面 → 大 AABB 正面直视时 samples 可能为 0 → 视野内的物体会被误剔除。修复：x+ 面改为 (1,y0,z1),(1,y0,z0),(1,y1,z0),(1,y1,z1) 或等价绕序。

  • ALRPipelines.OCCLUSION_QUERY 仍是 withCull(true) — 相机位于 feature AABB 内部（玩家走进大型结构）时立方体所有面均背面剔除 → 0 samples → shouldDraw=false → 物体消失/闪烁。遮挡查询盒应 cull(false)（深度 LEQUAL 下背面样本无害）。上轮已提出，本次未见修改。

  • IntSizeUbo — 宽高互换未修复（IntSizeUbo.java）
    DEFINITION 顺序 getHeight → getWidth，与自身 javadoc 的 GLSL 声明 uWidth; uHeight; 相反。同轮次 ConvertDepthParamsUbo 已改为 getWidth → getHeight ✅（与 depth_convert.csh 一致），唯独此类仍是反的。当前无调用者（dead code），但一旦用于任何尺寸参数即互换。

⚠️ 警告（latent，接入 Hi-Z / SubmitNodeStorage 时必踩）

  • FFX_SPD_DOWNSAMPLE_PASS 绑定布局与 shader 不一致
    shader 声明 binding=2 为 rw_internal_global_atomic（std430 coherent buffer），但 pipeline builder 只注册了 cbFSR1@0、texture@1、mid_mip@2、mips@3——缺少原子计数器绑定 → bindAll 连续分配时 mid_mip/mips 整体错位 1 个 binding 点，且原子计数器永远不会被绑定（dispatch 时读未绑定 SSBO = UB）。另外 ImageArrayBinding 未覆写 applyOrdered（默认返回 1，13 个 image 只推进 1），且 Preconditions.checkElementIndex(size, resource.size(), ...) 参数颠倒——合法输入（resource.size()==size）抛异常，非法输入不抛。三者都是接入时才爆。

  • GlSamplesQuery.getValue() 每 key 每帧一次 GL_QUERY_RESULT 阻塞读 — 对以性能为目的的剔除是自伤模式（N 个 key = N 次管线停顿）。一帧延迟部分缓解，但注意：query 池的 release→reacquire 复用安全完全依赖本次阻塞读语义（F1 查询结果在 F2 读、F3 才归还复用，时序自洽 ✅）——将来改非阻塞读时必须同步调整归还顺序，否则变成悬垂复用。

  • MemoryAccess 仍用 sun.misc.Unsafe 反射（Unsafe.theUnsafe + setAccessible(true)，123 行只为读 4 字节）——GlSamplesQuery 只需 4 字节读，MemoryUtil.memGetInt 足够；Java 21 模块系统下 jdk.unsupported 未 open 时类加载即崩。本次 4 字节读本身宽度匹配正确（nmalloc(4) + getInt ✅），问题在机制本身。

  • ALROptimizations.create() 时序 + 空守卫
    ① MinecraftMixin.onCreateInstance 中 ALROptimizations.create() 先于 ALRComputeCapabilities.init() 执行 → 启动时 HIERARCHICAL_Z.isSupported() 恒为 false → 后端选择永远是 GPU_QUERY，与 createInstance 内 HiZ 优先的意图矛盾；② getOcclusionCuller() 对 RenderSystem.getDevice() 无 null 守卫（渲染线程外调用 → 硬转链 NPE）；③ 创建的 culler 全库无人消费，静态持有 16 个 GL query + DynamicUniformStorage(512)（HiZ 路径则是 13 张纹理 + 3 个 buffer），纯浪费。

  • OcclusionCuller.createInstance 优先返回 HiZ 空壳 — compute 可用时选中 HierarchicalZOcclusionCuller（submit/process 均 no-op，shouldDraw=true ✅ 保守），实现完整的 Query 后端反而不被选中；该 stub 构造函数在未实现时已分配全部 GPU 资源，且无 close()/资源释放路径（deleteTextures 只关纹理，spdParamsBuffer/convertParamsBuffer/spdGlobalAtomicCounterBuffer 三个 GpuBuffer 泄漏）。

  • ffx_spd_downsample_pass.csh 兼容性 — ① 桌面 GLSL 450 使用 Vulkan 风格 layout(set=0, binding=N)：严格驱动编译报错，宽松驱动忽略（需在目标驱动栈验证）；② 默认配置（SPD_OPTION_WAVE_INTEROP_LDS=true → define 0，注释已承认 "weird inverted"）走 #extension GL_KHR_shader_subgroup_quad : require 路径——无 subgroup quad 的 GPU 编译失败；③ rw_input_downsample_src_mips[13] 超过 GL 最低保证的 8 个 image unit；④ 该 pipeline 已注册（资源重载即编译）但从未 dispatch，编译失败会持续刷日志。

  • MipLayer.getDefinition() 返回 null — 违反 BufferObject 基类契约，任何 size()/write() 调用即 NPE；作为纯数据 holder 不应继承 BufferObject。

  • BufferObjectLayoutEntry.Builder.forSetter 是死 API — setter 字段从未传给 build()（record 无 setter 组件）。

  • GpuReusableResourcePool.fail(false) 返回 pool[0] 不检查可用性 — 双 acquire 悬垂复用（SimpleResetPool.acquire(false) 同路径；当前无调用者，dormant）。

  • QueryInstance.CreationContext 静态 vertexBuffer — record 内 static 可变字段，永不释放；设备重建/资源重载后悬垂。

💡 建议

  • GlDeviceMixin 用魔数 usage & 16 判 cubemap——已核实 MC 26.1 USAGE_CUBEMAP_COMPATIBLE == 16 ✅ 功能正确，但建议改用 GpuTexture.USAGE_CUBEMAP_COMPATIBLE 常量。
  • tonemappers.glsl（159 行）新增但 diff 与基线中均无任何引用——dead include。
  • sync 模块多处重复 import org.jetbrains.annotations.ApiStatus（如 LazySyncBytecodeInjector）。
  • 5 个文件缺末尾换行：MemoryAccess.java、LoopResetPool.java、SimpleResetPool.java、depth_convert.csh、ExtendedTextureFormat.java。
  • 帧内 fetchResults 可先轮询 GL_QUERY_RESULT_AVAILABLE 减少无条件停顿。

🟢 看起来不错

  • glBeginQuery(target,id) / glEndQuery(target) / glGetQueryObjectuiv 传参全部正确（end 用 target 枚举 ✅），结果读取宽度匹配 ✅。
  • FullTransformsUbo（ProjMat→ModelViewMat）、ConvertDepthParamsUbo（width→height→padValue）、SPDConstantBuffer（mips→numWorkGroups→workGroupOffset→invInputSize）的 DEFINITION 顺序与各自 GLSL 声明逐字段一致（writeInto 按 entries 顺序写入已验证）✅。
  • 未知 key 首帧语义保守：shouldDraw 首帧返回 true、getOrDefault(key, 1) 默认画 ✅；HiZ stub shouldDraw=true ✅（上轮意见已采纳）。
  • 查询 pass 单 RenderPass 批量提交全部 query（非每 feature 一个 pass）✅；debug group 惰性 Supplier 改造完整（接口/GL 后端/mixin 全链路一致）✅。
  • FrameState 双缓冲时序自洽：F1 提交 → F2 读结果 → F3 归还复用，阻塞读语义下池复用安全。
  • @ApiStatus.Internal 从 15 个 mixin 类移除、标注内部实现类，与 PR 描述一致 ✅。

📋 声称验证表

声称 状态 对应文件
OcclusionCuller/Key/Method 抽象 ✅ optimization/occlusion/*
查询管线 + 顶点/片元 shader + FullTransformsUbo ✅（含 🔴 绕序/cull 问题） ALRPipelines, occlusion_query.*, FullTransformsUbo
GPU device 接口 + GL samples-query 封装 ✅ GlSamplesQuery, GpuQueryObject, GlDeviceMixin
资源池 + ring buffer 基础 ✅（含 ⚠️ fail(false) 隐患） GpuReusableResourcePool, LoopResetPool, SimpleResetPool
帧状态管理（本帧提交/次帧读取） ✅ FrameState, GpuQueryOcclusionCuller
compute debug-group 惰性 Supplier ✅ ALRComputePass, GlComputePassBackend
ApiStatus.Internal 注解调整 ✅ 15 个 mixin 移除 + 内部类标注
Hi-Z 后端 ⚠️ 仅 stub（TODO 未勾选，自认） HierarchicalZOcclusionCuller
Samples Query 后端 ⚠️ 已实现但未接线 GpuQueryOcclusionCuller
接入 vanilla SubmitNodeStorage ❌ TODO 未勾选（自认） 无

🧪 测试建议

被测目标 推荐场景 优先级
ALRComputePass.bindAll 首次调用即 IOOBE（当前必现） 🔴
ImageArrayBinding.apply resource.size() == size 与 > size 两分支（当前逻辑颠倒） 🔴
QueryInstance 立方体 从 +x/-x 各方向 + 相机在 AABB 内部观察（samples 是否 >0） 🔴
GpuSampleQueryPool 连续 3 帧 key 数 > 池容量，验证 expand 与 release 时序 🟡
ALROptimizations 启动顺序（create 先于 compute init）下的后端选择断言 🟡

结论: REQUEST_CHANGES — 基础设施方向正确、多数问题因未接线而处于 latent；但 bindAll 是对既有 API 的确定性回归、x+ 面绕序与 IntSizeUbo 宽高互换是确定的代码缺陷，建议合并前修复；其余 ⚠️ 项作为接入 Hi-Z/SubmitNodeStorage 时的必办清单保留在 PR 中跟踪。

由 Hermes Agent 审查

@Gugle2308

Gugle2308 commented Aug 14, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

# 检查 12 个 feature mixins 是否有统一的"过滤链"（filterVisibleFeatures 在 renderXxx 里过滤 submits）
# 关键：这些 mixin 修改的是"渲染时读取的 submits"，而 OcclusionSubmitNodeCollection.submitFeatureToCuller
# 在 submit 阶段收集 feature → c...

Reason: Security scan — [HIGH] Confusable Unicode characters in text: Content contains Unicode characters visually identical to ASCII (math alphanumerics, Cyrillic/Greek lookalikes) appearing near ASCII text, which may indicate a homoglyph attack

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

⚠️ Iteration budget exhausted (90/90) — asking model to summarise

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

I reached the maximum iterations (90) but couldn't summarize. Error:

<title>504 Gateway Time-out</title>

504 Gateway Time-out

openresty

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 9
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 9 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

# ALRHICapabilities.getInstance() 无 null 守卫硬转 RenderSystem.getDevice() → ALRGpuDeviceExtension
# 若 device 为 null（渲染线程外/未初始化）→ NPE/CCE。但调用点是 init()（Minecraft 构造器 RETURN 后）
# 关键：ALROptimizations.create(...

Reason: Security scan — [HIGH] Confusable Unicode characters in text: Content contains Unicode characters visually identical to ASCII (math alphanumerics, Cyrillic/Greek lookalikes) appearing near ASCII text, which may indicate a homoglyph attack

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

# 最后确认几个点：
# 1. GlSamplesQuery.getValue 缓存：result 初值 -1，release 重置 -1 —— acquire 后 getValue 重新读 GL ✓
#    但 close() 不重置 result —— close 后再次 getValue 抛 ISE ✓
# 2. GpuReusableResourcePool.fail(false) 返回...

Reason: Security scan — [HIGH] Confusable Unicode characters in text: Content contains Unicode characters visually identical to ASCII (math alphanumerics, Cyrillic/Greek lookalikes) appearing near ASCII text, which may indicate a homoglyph attack

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

gh 未认证（token 无效），无法用 gh pr edit 改标题，跳过标题修改，直接输出审查。

代码审查摘要 — PR #95

操作: synchronize
范围: 105 个文件（98 Java, 5 shader, 1 mixins.json, 1 build.gradle）/ 4959 行 diff
结构: 55 新增、0 删除、1 ghost（ComputeSupport.java 仅 2 行变更，非 ghost）

📋 声称验证表

声称 状态 对应文件
OcclusionCuller / OcclusionKey / OcclusionMethod 抽象 ✅ optimization/occlusion/ 3 文件
Occlusion query 渲染管线 + 顶点/片元着色器 ✅ ALRPipelines.OCCLUSION_QUERY、occlusion_query.vsh/fsh
GPU device 接口 + GL samples-query（含生命周期包装） ✅ ALRGpuDeviceExtension、GlDeviceMixin、GlSamplesQuery
可复用 GPU 资源 + 环形缓冲池（Query/Query 绘制缓冲） ✅ GpuReusableResourcePool、SimpleResetPool、LoopResetPool、GpuSampleQueryPool、QueryInstancePool
查询帧状态管理（当前帧提交、下帧读回） ✅ FrameState、GpuQueryOcclusionCuller
compute-pass debug 组消息改惰性 Supplier<String> ✅ ALRComputePass、ALRComputePassBackend、GlDeviceMixin
ApiStatus.Internal 标注调整 ✅ 15 处 mixin 移除 + 18 处 rendering/sync 类新增
[x] Samples Query backend ✅ GpuQueryOcclusionCuller + FrameState
[x] 集成 vanilla SubmitNodeStorage ⚠️ OcclusionSubmitNodeStorage/Collection 已实现，但无任何调用方（wrapSubmitNodeStorage / beginOcclusionRecord 无人调用）
[ ] Hi-Z backend ⚠️ HierarchicalZOcclusionCuller 为空壳：processFeatures() 空、shouldDraw() 恒 true；SPD/深度转换资源已建但从未 dispatch

🔴 关键

  • FrameState.runQueries 中 DynamicUniformStorage.writeUniforms(transforms) 的 null 数组元素 — FullTransformsUbo[] transforms 对 cameraInside 的 key 留 null，后续 writeUniforms 与 queries.get(i).uniform(slice[i]) 依赖 vanilla 实现是否容忍 null。若 vanilla 逐元素写入即 NPE。至少应只填充非 camera-inside 的 UBO，或显式跳过（cameraInside 分支本来就 continue，说明作者已意识到）。
  • Occlusion 集成路径整体未接线（dead infrastructure） — OcclusionSubmitNodeStorage.wrapSubmitNodeStorage()、beginOcclusionRecord/endOcclusionRecord 在 diff 中无任何调用方；12 个 feature-renderer mixin 已激活 filterVisibleFeatures 但 key 从不被提交。PR 描述称"未接线"，但渲染路径已经被 mixin 接上了——这两者状态不一致，容易误导后续工作以为渲染端已就绪。

⚠️ 警告

  • ALROptimizations.create() 在 Minecraft 构造期无条件创建 culler + 每帧无收益分配 — GPU_QUERY.isSupported() 恒 true，因此所有机器启动即创建 GpuQueryOcclusionCuller（16 个 GL query 对象 + command encoder + 512×128B UBO 存储）。此后 12 个 renderer mixin 每帧对每个特征列表 new ArrayList + addAll 拷贝（热路径逐帧分配），而 culling 未接线 → 纯开销零收益。建议：filterVisibleFeatures 在 culler 无已提交 key 时直接返回原列表（如加 hasPendingKeys 帧标记），或延迟 create() 到 wrapSubmitNodeStorage 真正被调用时。
  • Hi-Z culler 在 compute 机器上被优先创建且完全惰性 — createInstance 先检查 HIERARCHICAL_Z（compute 支持即建），构造时按当前渲染分辨率分配 13 张 R32F 纹理 + SPD/转换 buffer + atomic counter，但 processFeatures 空、shouldDraw 恒 true → 启动即占显存/内存，无任何功能。建议在创建前用 ALROptions 显式开关门控。
  • GlSamplesQuery.getValue() 同步阻塞读回 — GL_QUERY_RESULT 是阻塞调用，beginFrame() 每帧对全部 key 同步读回会引发 GPU stall；建议 GL_QUERY_RESULT_AVAILABLE 轮询 + 两帧延迟，或至少确认当前 Blaze3D 命令编码器提交语义下不会卡帧。
  • camera-inside 的 query 对象从未 begin/end 却被 fetchResults() 读取 — GL 规范下未启动 query 的结果未定义（实践中为 0，被 cameraInside.contains 掩蔽），但建议显式跳过或对未启动 query 直接记 1，避免依赖未定义行为。
  • QueryInstance.DEFAULT_VERTEX_BUFFER_SIZE 注释与代码不符 — 注释 ((3 float * 4) for each quad * 6) for cube * 1 实际是 288 字节 = 24 顶点 × 12B，与 drawIndexed(0,0,36,1)（36 索引 = 6 quad × 6）匹配，但注释里的 3*4*4*6 易误导（每 quad 4 顶点 3 float → 应为 24 顶点）。
  • SimpleResetPool.acquire() 游标语义 — cursor 线性推进，未命中可用对象时 fallback 到 fail()；LoopResetPool 覆盖后 OK，但 SimpleResetPool 本身在 releaseAll 前重复 acquire 会反复触发 fail()（本 PR 实际只走 LoopResetPool 路径，低风险，注明即可）。

💡 建议

  • FrameState 用 Reference2LongLinkedOpenHashMap/Reference2ObjectLinkedOpenHashMap + IdentityHashMap 混用，建议统一 fastutil reference 系列（与 keyAssociations 一致），避免 IdentityHashMap 与 Reference2LongMap 的 equals 语义差异坑。
  • GlDeviceMixin.alrhiCreateCapabilities() 缓存 alr$capabilities 非 volatile，但仅在渲染线程访问，可加注释说明线程约束。
  • OcclusionKey.defaultName() 每次调用生成新 "OcclusionKey" 字符串，可改常量。
  • MemoryAccess 用 sun.misc.Unsafe，Java 21+ 仍可用但建议注释说明 jdk.unsupported 依赖；getInt(buffer) 的 buffer 来自 stack.nmalloc，无 offset 计算问题，OK。

🟢 看起来不错

  • GpuReusableResourcePool/LoopResetPool 的环形复用设计清晰，release() 正确重置 result=-1 防陈旧结果。
  • OcclusionCuller.createInstance 的 forced-impl 回退逻辑健壮（非法值 → 继续回退默认）。
  • OcclusionSubmitNodeCollection 对 12 类 submit 的搬运覆盖完整（shadow/flame/text/leash/movingBlock/blockModel/multiLayer/breaking/item/particle/nameTag/model/modelPart/customGeometry），与 vanilla 存储结构对齐良好。
  • Supplier<String> 惰性化 debug 组消息改动彻底且一致（接口/GL 后端/调用方同步更新，popDebugGroup 顺手去掉了多余参数）。
  • ApiStatus.Internal 标注调整方向正确：mixin 类是内部实现但注解应在编译期类上，改标 UBO/扩展接口更合理。

🧪 测试建议

被测目标 推荐测试场景 优先级
GpuSampleQueryPool / QueryInstancePool 并发 acquire 耗尽 → fail(true) 扩容；release 后 isAcquired=false 可复用；close() 幂等 🔴
GlSamplesQuery.getValue() 未 begin/end 的 query 读回；result 缓存与 release() 重置 🔴
FrameState.runQueries camera-inside 与正常 key 混合；UBO 数组含 null；key 数 > 512（DynamicUniformStorage 容量） 🟡
OcclusionSubmitNodeCollection 空列表、单 key 多 feature、wasUsed=false 时 endOcclusionRecord 不提交 🟡
QueryInstance.prepareTransform AABB 边界（零尺寸、负尺寸、极大坐标）下的矩阵数学 🟡
OcclusionFeatureRendererHelper.filterVisibleFeatures culler==null / 无 key 提交时零分配短路 🟢

结论: COMMENT — 基础设施质量高、分层清晰，Supplier 迁移与标注调整彻底。但 occlusion 流程渲染端已接线、提交端未接线的状态不一致 + 无条件创建 culler 带来的热路径每帧分配，建议在合入前明确接线状态（至少让 filterVisibleFeatures 在无 key 时短路），Hi-Z 空壳可保留但建议加显式开关。GPU query 的同步读回与未启动 query 读值建议后续优化。

由 Hermes Agent 审查（gh 未认证，标题未修改）

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 9
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 9 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

gh 认证已失效（token 无效），无法用 gh pr edit 修改标题——这符合 webhook 约束（不 export token，避免卡死），所以保持 PR 标题不动，直接输出审查。以下是完整审查：

代码审查摘要 — AnvilLib PR #95

操作: edited（PR 描述/分支变更）
范围: 104 个文件（55 新增，0 删除）/ 4959 行 diff
说明: 本 PR 为遮挡剔除第一阶段基础设施。已对照 rendering-gpu-pr-review 技能中此前几轮审查沉淀的已知问题点逐一复核——大部分旧问题仍在（见下）。

🔴 关键（接入即崩 / 必现错误）

  • QueryInstance.prepareMesh — x+ 面绕序反了（仍未修）
    六面立方体只有 x+ 面 (1,0,0)(1,0,1)(1,1,1)(1,1,0) 叉积 = (-1,0,0)，与 +x outward normal 反向；x- 面 (0,0,0)(0,1,0)(0,1,1)(0,0,1) 叉积 = (1,0,0) 也与 -x 反向。两个面反绕（非单面）。配合 OCCLUSION_QUERY 的 withCull(true)，从 +x/-x 方向正面直视 AABB 时正面被剔除 → samples≈0 → 视野内物体被误剔除（比全剔更隐蔽，多数角度正常）。这是多轮审查反复标记的问题，应修复（调换每面第 2、4 个顶点）并把查询盒管线改为 withCull(false)（相机进入 AABB 内部时 6 面全背面剔除 → 全灭）。

  • ALRComputePass.bindAll — 重构引入 elements.get(-1) IOOBE（仍未修）
    bindingPoint += this.bind(bindingPoint, binding, elements.get(bindingPoint - 1))：Java 实参左到右求值，首轮 bindingPoint=0 → elements.get(-1) → IndexOutOfBoundsException。旧代码 bindingPoint++ 先自增再 get(0) 是对的。应改为 elements.get(bindingPoint)。当前无调用者（latent），但首次调用必崩。

  • ImageArrayBinding.apply — Preconditions.checkElementIndex(size, resource.size()) 参数传反（仍未修）
    checkElementIndex(index, size) 语义要求 0 <= index < size。传 (13, resource.size()) 意味着仅当 resource.size() >= 14 才通过，而注释声称「resource.size <= this.size is allowed」——完全相反。FFX_SPD 的 withImageArray(..., 13) 绑定 13 张纹理时 checkElementIndex(13,13) 必抛。应改为 checkElementIndex(resource.size(), size)（或 checkArgument）。

  • FFX_SPD_DOWNSAMPLE_PASS builder 链与 shader binding 错位 1 槽（仍未修）
    shader：binding 0=cbFSR1 UBO, 1=sampler2D input, 2=rw_internal_global_atomic(SSBO), 3=mid_mip image, 4=mips image2D[13]。builder 链：withUniformBlock(cbFSR1) → withTexture(input) → withReadWriteImage(mid_mip) → withImageArray(mips)——缺少 withShaderStorage/withAtomicCounter（binding 2）。bindAll 后 mid_mip 绑到 2、mips 从 3 开始（实际应为 3/4），atomic 计数器永不绑定 → dispatch 读未绑定 SSBO（UB）。虽 processFeatures 为空（Hi-Z 未接线）暂不触发，但注册即编译 + 资源重载后绑定必然错位。

  • MinecraftMixin.onCreateInstance — ALROptimizations.create() 在 ALRComputeCapabilities.init() 之前（顺序 bug）
    create() → OcclusionCuller.createInstance → HIERARCHICAL_Z.isSupported() 读静态 COMPUTE_SUPPORTED，但 init() 尚未执行（默认 false）→ Hi-Z 永远无法被选中，即使 GPU 支持 compute 也只会创建 GPU_QUERY。应交换两行顺序。

  • GpuReusableResourcePool.fail(false) — 返回 pool[0] 不查可用性（仍未修）
    acquire(false) 时直接 get(0) + acquire() → 若 pool[0] 已被占用则同一对象被双 acquire（悬垂复用）。当前无 acquire(false) 调用者（dormant），但作为基础池 API 是隐患。

⚠️ 警告

  • MemoryAccess — sun.misc.Unsafe 反射（仍未修）
    实测 getUnsafe() 用 Unsafe.class.getDeclaredField("theUnsafe") + setAccessible(true)，在 Java 21 模块系统下依赖 jdk.unsupported 开放，launcher 的 --add-opens 不保证覆盖。GlSamplesQuery 只需读 4 字节 int，用 MemoryUtil.memGetInt(addr) 即可。且本文件 \ No newline at end of file（缺 EOF 换行）。

  • GlSamplesQuery.getValue — 同步阻塞读（§4）
    GL_QUERY_RESULT 每帧每 key 一次同步回读 = 强制 GPU 完成已提交工作（管线停顿）。N 个 key = N 次停顿，对以性能为目的的遮挡剔除是自毁。应改用 GL_QUERY_RESULT_AVAILABLE 轮询 / 延迟 2+ 帧 / 部分缓冲异步回读。且 GpuQueryOcclusionCuller.beginFrame 中 previousFrameState.close() 先于 fetchResults()：query 释放回池后才读结果——时序上 fetchResults 读的是「未被重新 begin 的 query」结果（对象 id 未变，读值正确），但依赖「close 后、同帧 re-acquire 前」的窗口，较脆弱；建议先 fetch 再 close。

  • IntSizeUbo — getter 顺序 高度先宽度（仍未修）
    DEFINITION 先 getHeight 后 getWidth，GLSL javadoc 声明 uWidth; uHeight; → 宽高互换。同一 PR 的 ConvertDepthParamsUbo 已修（width 先），属逐文件漏改型——建议全库扫描同类 UBO。

  • MipLayer extends BufferObject 且 getDefinition() 返回 null
    违反基类契约（任何 write/size 调用即 NPE）。当前 BufferObject.write 对 SSBO 先抛 IllegalStateException，MipLayer usage=SSBO 恰好先触发 ISE 而非 NPE（凑巧不崩），但作为纯数据 holder 不应继承资源基类。建议改为普通 POJO。

  • ALRHICapabilities.getInstance() 无 null 守卫硬转
    (ALRGpuDeviceExtension) RenderSystem.getDevice() 在渲染线程外 / device 为 null 时 CCE/NPE。调用点 ALRComputeCapabilities.init() 在 Minecraft 构造器注入点执行，与已有 ALROptimizations.create() 同注入点——若 mixin 被禁用则启动即崩，建议加 null 兜底。

💡 建议

  • BufferObjectLayoutEntry.Builder.forSetter 死 API（新增但未使用）：build() 仍返回 new BufferObjectLayoutEntry<>(type, getter)，setter 字段被忽略。要么接入 record，要么删掉。
  • OcclusionSubmitNodeCollection 大量 @SuppressWarnings 缺失 + 硬转 accessor：(NameTagFeatureRendererStorageAccess) this.getNameTagSubmits() 等 4 处无 instanceof 守卫，mixin 未生效时 CCE。
  • 每 key 一个 renderPass.setPipeline/setUniform/setVertexBuffer/setIndexBuffer 循环：单个 pass 内连续 begin/draw/end 所有 query 即可（§6），当前每 query 一次状态切换开销较大。
  • ALROptions.SPD_OPTION_WAVE_INTEROP_LDS 默认 true 但 define 映射反转（? 0 : 1，「weird inverted」注释）——默认配置走 FFX_SPD_NO_WAVE_OPERATIONS 路径，无 subgroup quad 的 GPU 也能跑，但性能路径与直觉相反，建议确认默认值意图。
  • ComputeSupport.INSTANCE 改为可 null：所有引用点（AnvilLibTestClient / GuiTestScreen）都有 isComputeSupported() 守卫，安全；但 GuiTestScreen.dispatchComputeTest 中 ComputeSupport.INSTANCE.add 在 try 块内无守卫（有 try/catch 兜底）——建议统一守卫风格。

📋 声称验证表

声称 状态 说明
新增 OcclusionCuller/OcclusionKey/OcclusionMethod 抽象 ✅ 三者齐备，createInstance 有 fallback 链
occlusion-query 渲染管线 + 顶点/片元 shader ✅ OCCLUSION_QUERY + FullTransformsUbo + vsh/fsh
GPU 设备接口 + GL samples-query 封装 GlSamplesQuery ✅ alrCreateSamplesQuery / glBeginQuery/glEndQuery 参数正确（end 传 target 非 id）
GPU 资源池 / ring-buffer 基础 + Query 专用池 ✅ GpuReusableResourcePool/LoopResetPool/SimpleResetPool + QueryInstancePool/GpuSampleQueryPool
Query 帧状态管理（当前帧提交/执行，下帧读取） ✅ FrameState 两帧滑动窗口
pushDebugGroup 改 Supplier<String> 惰性求值 ✅ ALRComputePass/ALRComputePipeline/GlDeviceMixin 同步更新
ApiStatus.Internal 从 mixin 类移除、渲染/sync 类标注 ✅ 15 个 mixin 移除，18+ 处新增（UBO/扩展接口/内部类）
[x] Samples Query backend ✅ GpuQueryOcclusionCuller 完整
[x] 集成 vanilla SubmitNodeStorage ⚠️ OcclusionSubmitNodeStorage 已实现，但 12 个 feature mixin 过滤链 + wrapSubmitNodeStorage 未见调用者——SubmitNodeStorage 包装未被实际挂到渲染流程（latent）
[ ] Hi-Z backend ⚠️ HierarchicalZOcclusionCuller 骨架 + processFeatures 空实现 + shouldDraw 返回 true（保守 ✓）——可接受为后续工作

结论: REQUEST_CHANGES — 基础设施方向正确、GL 传参（glEndQuery target、4 字节读取宽度）本次已正确，但上一轮已标记的 5 个必现/回归级问题（x+ 面反绕、bindAll IOOBE、checkElementIndex 传反、FFX_SPD 缺 atomic binding、init 顺序）全部未修，且本 PR 已开始把 feature 过滤 mixin 接入（12 个 mixin 全部 @ModifyExpressionValue/ModifyReceiver），一旦接线完成这些 latent 问题会同时爆发。建议在合并前至少修复：查询盒绕序 + withCull(false)、bindAll 索引、checkElementIndex 参数、FFX_SPD atomic binding 注册、init() 顺序。

注：gh auth status 显示 token 已失效，无法执行 gh pr edit 更新标题（也未导出任何凭据）。标题 Refactor API status handling and add occlusion culling 基本准确，无需修改。

@Gugle2308

Gugle2308 commented Aug 28, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

echo "=== QueryInstance 网格绕序逐面叉积验证 ==="; python3 -c "
import numpy as np
def cross(v0,v1,v2):
    a=np.array(v1)-np.array(v0); b=np.array(v2)-np.array(v0)
    return np.cross(a,b)
faces={
 'z+':([0,0,...

Reason: script execution via -e/-c flag

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

echo "=== ImageArrayBinding.apply 中 checkElementIndex 语义：size 是声明上限、resource.size() 是实际数量 ==="; echo "checkElementIndex(index, size): index 必须 < size。此处 index=size(声明槽数=13), size=resource.size()(实际 mi...

Reason: Security scan — [HIGH] Confusable Unicode characters in text: Content contains Unicode characters visually identical to ASCII (math alphanumerics, Cyrillic/Greek lookalikes) appearing near ASCII text, which may indicate a homoglyph attack

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 10
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 10 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePassBackend.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

echo "=== 检查提交侧接线：TestOcclusionTESR 是唯一调用 beginOcclusionRecord 的路径 ==="; echo "=== 消费侧接线：12 个 FeatureRendererMixin 每帧调用 filterVisibleFeatures ==="; echo; echo "=== GpuQueryOcclusionCuller.beginFrame 每...

Reason: Security scan — [HIGH] Confusable Unicode characters in text: Content contains Unicode characters visually identical to ASCII (math alphanumerics, Cyrillic/Greek lookalikes) appearing near ASCII text, which may indicate a homoglyph attack

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

echo "=== 关键发现汇总（按严重级别）==="; echo; echo "🔴 1. FrameState.runQueries drawIndexed(0,0,6*6,1) + getBuffer(6*6)：36 索引 > 24 顶点 → 索引越界"; echo "🔴 2. ImageArrayBinding.checkElementIndex(size, resource.size())...

Reason: Security scan — [MEDIUM] Variation selector characters detected: Content contains Unicode variation selectors (VS1-256). These are commonly used in emoji sequences but may indicate steganographic encoding or obfuscation

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

gh 未认证（token invalid）→ 按 §20 规则跳过 gh pr edit，在审查末尾注明。

代码审查摘要 — PR #95 (synchronize)

操作: synchronize
范围: 121 文件（107 Java, 62 新增, 0 删除）/ 5410 行 diff
结论: REQUEST_CHANGES

基础设施阶段整体设计清晰（culler 抽象、双帧 query 状态机、ring pool、Supplier 化 debug group），但本同步轮仍遗留多个上一轮已标记的🔴问题，且绑定体系存在 3 个会直接导致 Hi-Z/FFX_SPD 首次 dispatch 崩溃或结果错位的缺陷。

🔴 关键（需修复后合并）

  1. FrameState.runQueries — 索引越界（新增发现）
    RenderSystem.getSequentialBuffer(QUADS).getBuffer(6*6) + drawIndexed(0, 0, 6*6, 1)：QUADS 模式 6 面 × 4 顶点 = 24 索引，mesh 也只有 24 顶点（DEFAULT_VERTEX_BUFFER_SIZE = 3*4*4*6 = 288B）。6*6=36 是按 TRIANGLES（6面×2tri×3vtx）算的——索引 24..35 引用不存在的顶点，GPU 端越界读，查询结果不确定/可能崩溃。应改为 getBuffer(6*4) + drawIndexed(0, 0, 6*4, 1)。

  2. ImageArrayBinding.apply — checkElementIndex 传反（未修复，上轮已标）
    Preconditions.checkElementIndex(size, resource.size(), ...)：index=声明槽数 13，size=实际数量 13 → 13 < 13 恒 false → 合法输入必抛 IOOBE，非法输入（超限）反而放行。应 checkElementIndex(resource.size(), size)。

  3. ImageArrayBinding 未覆写 applyOrdered（未修复）
    只覆写 apply()（内部 bindingPoint++），默认 applyOrdered 返回 1 → bindAll 中 13 个 image 绑定后 bindingPoint 只推进 1 槽，后续 binding 错位（§15/§18）。

  4. FFX_SPD pipeline 绑定 ↔ shader layout(binding=N) 错位（新增发现）
    shader：cbFSR1=0 / r_input=1 / atomic counter=2 / mid_mip=3 / mips[13]=4..16。
    Java builder：cbFSR1=0 / r_input=1 / mid_mip=2 / mips[13]=3..15 —— 完全缺失 AtomicCounterBinding（rw_internal_global_atomic），mid_mip/mips 整体错位 1 槽，atomic 永不绑定（dispatch 读未绑定 SSBO = UB）。需在 cbFSR1 之后插入 .withAtomicCounter("rw_internal_global_atomic")，并逐项核对。

  5. MinecraftMixin.onCreateInstance — 初始化顺序（§21，跨轮次未修复）
    ALROptimizations.create()（→ HIERARCHICAL_Z.isSupported() 读 COMPUTE_SUPPORTED）在 ALRComputeCapabilities.init() 之前执行 → 标志恒为默认 false → Hi-Z 永不选中，即使 GPU 支持 compute 也永远走 GPU_QUERY。把 init() 提到 create() 之前。

⚠️ 警告

  • IntSizeUbo 宽高互换（§3，跨轮次未修复）：DEFINITION 先写 getHeight 再 getWidth，GLSL 声明 uWidth; uHeight; → 值互换。ConvertDepthParamsUbo 上轮已修，本文件漏改。
  • GPU_QUERY.isSupported() 恒 true（§8/§18）：GL_SAMPLES_PASSED 虽是 GL 3.0 核心，但恒 true 不经能力探测仍是假探测；配合 OcclusionMethod.createInstance 硬转 (ALRGpuDeviceExtension) device，mixin 未生效即 CCE。
  • ALRHICapabilities.getInstance() 硬转无 instanceof / null 守卫（渲染线程外 RenderSystem.getDevice() 返回 null）。
  • GL_QUERY_RESULT 每帧 N 次阻塞读（§4）：fetchResults 同步读强制管线停顿，N 个 key = N 次停顿，对性能向特性是自毁。建议 RESULT_AVAILABLE 轮询 / 延迟 2+ 帧 / PBO。
  • sync 模块 8 个文件重复 import org.jetbrains.annotations.ApiStatus（如 LazySyncBytecodeInjector、SyncClassProcessor、SyncPayload 等，原 import 未删又加一个）——会编译告警。
  • MemoryAccess 反射 Unsafe（§2）：getUnsafe() 的 setAccessible(true) 在 Java 21 模块系统下依赖 jdk.unsupported 开放；4 字节读用 MemoryUtil.memGetInt 即可，不应引入整块 Unsafe 工具类。
  • GlDeviceMixin 中 debugLabels 方法 Shadow + 字段 Shadow 同名混用：新增 @Shadow @Final private GlDebugLabel debugLabels 与既有 public abstract GlDebugLabel debugLabels() 同名，风格冲突且 this.debugLabels.applyLabel(texture) 依赖该字段在目标类真实存在——建议统一走 debugLabels() 方法 + ALRDebugLabelExtension 访问器。

💡 建议

  • OcclusionSubmitNodeStorage 每帧新建：TestOcclusionTESR.submit 每次 wrapSubmitNodeStorage 都 new storage + order() 又 new collection（submitsPerOrder 每 storage 实例都是空的）→ 每帧每个 TESR 每 order 新建对象，GC 压力 + clear()/endFrame() 对新建 collection 无意义。缓存 storage 或按帧复用。
  • alrSetWasUsed(true) 篡改 original collection 的 wasUsed：vanilla 的 wasUsed 控制清理/复用语义，强制置 true 可能影响后续帧行为，需实机验证。
  • 提交/消费侧 feature 实例一致性：shouldDraw(feature) 用 currentFrameState.getKey(feature)，key 关联建立在 wrapped 收集的 feature 上；若渲染侧过滤的 original 列表与提交侧不是同一对象实例，getKey 返回 null → results.getOrDefault(null,1) 恒画（静默失效）。建议在测试环境加断言验证。
  • HiZ stub 构造器建 GPU 资源 + 每帧 clearAtomicCounter 建 encoder（§18）：processFeatures/shouldDraw 为空实现却建 3 个 buffer + mip 纹理链 + encoder——纯资源浪费，且 encoder 不显式 submit（帧末隐式执行）。骨架实现应延后建资源。
  • FFX_SPD/DEPTH_CONVERT 死注册（§12）：HiZ 未接线却注册两个 compute pipeline，资源重载即编译；layout(set=0,...) 是 Vulkan 语法（宽松驱动忽略，严格驱动报错）+ GL_KHR_shader_subgroup_quad : require 默认启用（SPD_OPTION_WAVE_INTEROP_LDS 默认 true → define 0）——无 subgroup quad 的 GPU 编译失败。接线与注册应同 PR 落地。
  • 查询盒绕序（§14）：x+ 与 x- 面反向（叉积 vs outward normal 均 -1）。OCCLUSION_QUERY 已改 withCull(false) 缓解，但绕序仍应修正（cull(false) 时背面样本无害，绕序错主要影响 cull(true) 场景）。
  • OcclusionFeatureRendererHelper.filterVisibleFeatures（§20）：culler 非 null 且 !isEmpty 时每帧对每个 feature list 全量 new ArrayList + addAll——提交侧真正接线前零收益纯开销。建议 culler 加「本帧有无已提交 key」短路。
  • 魔数 usage & 16 cubemap 判定：改用 GpuTexture.USAGE_CUBEMAP_COMPATIBLE 常量（§17）。
  • camera-inside 的 query 未 begin/end 却被 fetchResults 读：结果实现定义（多数驱动返回 0），当前被 cameraInside.contains(key) 掩蔽（§20），建议显式跳过或记 1，别依赖 UB。

🟢 看起来不错

  • 双帧状态机设计正确：未知 key 恒画（getOrDefault(key,1)>0）+ 退出 camera-inside 多画一帧 = 保守无 pop-in（§20 正向确认）。
  • bindAll 重构回归已修：elements.get(i++) 修正了上轮 get(-1) 的 IOOBE（§15）。
  • OCCLUSION_QUERY 管线 withCull(false) + DepthStencilState(LEQUAL, false) + WRITE_NONE 正确；FullTransformsUbo 写入顺序与 shader 一致；ConvertDepthParamsUbo 宽高已修。
  • GlSamplesQuery.getValue 分配 4 字节 + 读 4 字节宽度匹配；glEndQuery(GL_SAMPLES_PASSED) 参数正确（target 非 id）。
  • GlExtendedTextureConstants 格式映射（R32F→GL_RED/FLOAT 等）正确；alrCreateExtendedTexture 的 OOM 处理清晰。
  • 池抽象（LoopResetPool/SimpleResetPool/GpuReusableResourcePool）结构清晰，Query/Instance 双池分离合理。
  • ApiStatus.Internal 从 mixin 类移除、改为标注内部实现类/record/扩展接口——语义更准确。

📋 声称验证表

声称 状态 对应文件
OcclusionCuller/Key/Method 抽象 ✅ OcclusionCuller, OcclusionKey, OcclusionMethod
occlusion-query 渲染管线 + 顶点/片元着色器 ⚠️ ALRPipelines.OCCLUSION_QUERY, occlusion_query.vsh/fsh（drawIndexed 索引越界）
设备接口 + OpenGL samples-query 实现 ✅ ALRGpuDeviceExtension, GlDeviceMixin, GlSamplesQuery, GpuQueryObject
GPU 资源/ring-buffer 池化基础 ✅ GpuReusableResource(Pool), LoopResetPool, SimpleResetPool
Query 帧状态管理（双帧读回） ✅ FrameState, GpuQueryOcclusionCuller
pushDebugGroup 惰性 Supplier ✅ ALRComputePass, GlComputePassBackend, GlDebugLabelMixin
ApiStatus.Internal 注解调整 ⚠️ sync 模块 8 文件重复 import（无功能影响但需清理）
Samples Query 后端 ✅ GpuQueryOcclusionCuller + FrameState（已接线于 AnvilLibRendering + TestOcclusionTESR）
HiZ 后端 ⚠️ HierarchicalZOcclusionCuller（stub：processFeatures/shouldDraw 空实现，未接线）
SubmitNodeStorage 集成 ⚠️ OcclusionSubmitNodeStorage/Collection（提交侧仅 TestOcclusionTESR 接线，消费侧 12 mixins 已接线）

结论: REQUEST_CHANGES — 🔴 5 项需修复：drawIndexed 索引越界、checkElementIndex 传反、applyOrdered 未覆写、FFX_SPD atomic 绑定缺失、初始化顺序（Hi-Z 永不选中）。前 4 项是首次 dispatch 即崩/错位的硬缺陷，第 5 项是静默功能失效。上轮已标记的 IntSizeUbo 宽高互换、假能力探测、每帧阻塞读仍未修复。

由 Hermes Agent 审查（渲染专项 §1-21 清单核对）
注：gh 未认证（token invalid），按流程跳过标题修改。

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 10
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 10 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePassBackend.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /tmp && echo "=== 整理审查发现的关键问题 ===" && echo "" && echo "🔴 关键问题候选:" && echo "1. ImageArrayBinding.apply: Preconditions.checkElementIndex(size, resource.size()) 参数顺序反了 → 任何 size > resource.size() 抛异常,...

Reason: Security scan — [MEDIUM] Variation selector characters detected: Content contains Unicode variation selectors (VS1-256). These are commonly used in emoji sequences but may indicate steganographic encoding or obfuscation

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /tmp && echo "=== 最后检查: GpuQueryOcclusionCuller.shouldDraw 中 key 来自 currentFrameState.getKey(feature) ===" && echo "--- 但 previousFrameState.shouldDraw(key) 使用 previousFrameState.cameraInside + res...

Reason: Security scan — [MEDIUM] Variation selector characters detected: Content contains Unicode variation selectors (VS1-256). These are commonly used in emoji sequences but may indicate steganographic encoding or obfuscation

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /tmp && echo "=== 汇总最终审查发现 ===" && echo "" && echo "🔴 关键 (需修复):" && echo "1. ImageArrayBinding.apply: Preconditions.checkElementIndex(size, resource.size()) 参数反转 → 与注释矛盾, FFX_SPD mips array 绑定必抛异常"...

Reason: Security scan — [MEDIUM] Variation selector characters detected: Content contains Unicode variation selectors (VS1-256). These are commonly used in emoji sequences but may indicate steganographic encoding or obfuscation

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Iteration budget exhausted (90/90) — asking model to summarise

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

代码审查摘要 — PR #95

操作: synchronize
范围: 121 个文件 (107 Java, 62 新增, 0 删除) / 5418 行 diff
分支: feat/occusion_culling → dev/26.1（AnvilLib）

✅ API 迁移健康度（26.1）

指标 计数 状态
jspecify Nullable 17 ✅
Identifier 2 ✅（ResourceLocation = 0）
@ApiStatus.Internal 移除/新增 15-/18+ ✅
EOF 缺换行 9 ⚠️ 少量

🔴 关键

  • ImageArrayBinding.apply — Preconditions.checkElementIndex(size, resource.size()) 参数顺序反转（compute/pipeline/bindings/ImageArrayBinding.java）
    checkElementIndex(index, size) 要求 index < size。这里把 this.size（如 13）当 index、resource.size() 当 size 传入，导致任何 resource.size() <= size 的合法情况都抛 IndexOutOfBoundsException，与注释 `resource.size <= this.size` is allowed 完全相反。ALRComputePipelines.FFX_SPD_DOWNSAMPLE_PASS 用 .withImageArray(..., 13) 声明，后续 Hi-Z 集成绑定 13 个 mip 纹理时 checkElementIndex(13, 13) 必然抛异常。应改为 Preconditions.checkArgument(resource.size() <= size, ...)。

  • OcclusionCuller.createInstance 后端选择导致本 PR 的剔除集成在常规硬件上形同虚设
    createInstance() 优先选择 HIERARCHICAL_Z（只要 ALRComputeCapabilities.isComputeSupported()）。但 HierarchicalZOcclusionCuller.processFeatures() 是空实现、shouldDraw() 恒返回 true——也就是说在支持 compute shader 的典型 GPU 上，本 PR 接入的 12 个 feature-renderer 剔除 Mixin（OcclusionFeatureRendererHelper.filterVisibleFeatures）全部变成 no-op，且还要白白承担 Hi-Z 每帧的 SPD/depth-convert 资源开销。功能完整且有实际剔除效果的 GpuQueryOcclusionCuller 反而只在 Hi-Z 不可用时才被选中。建议当前阶段将 GPU_QUERY 设为默认首选，或至少在 Hi-Z 完成前不让它参与 createInstance 选择；否则 PR 声称的「integrate occlusion culling with vanilla SubmitNodeStorage」在大多数机器上不生效。

⚠️ 警告

  • ComputeSupport.INSTANCE 改为可 null，但既有调用方未判空（module.test/.../ComputeSupport.java）
    新代码 INSTANCE = ALRComputeCapabilities.isComputeSupported() ? new ComputeSupport() : null，但 AnvilLibTestClient.java（不在本 PR diff 中）第 52/57/86 行 ComputeSupport.INSTANCE.resize(...)、.computeBlur()、.add(...) 均无条件调用——在不支持 compute 的机器上测试模块会 NPE。测试模块影响面小，但至少应在 PR 内同步补齐判空或保留非 null 兜底。

  • GlSamplesQuery.getValue() 使用阻塞式 GL_QUERY_RESULT 读取（query/gl/GlSamplesQuery.java）
    读取时若 GPU 未完成会阻塞渲染线程。当前时序（fetchResults 在下一帧 RenderFrameEvent.Pre 读取，已隔一帧）大概率安全，但 GPU 繁忙时仍有 stall 风险，建议改用 GL_QUERY_RESULT_AVAILABLE 轮询。

  • ALRComputeCapabilities.init() 时机前移（mixins/MinecraftMixin.java）
    从 ALRComputeShaderManager.apply()（资源重载期）移到 MinecraftMixin.onCreateInstance（Minecraft 构造期）。init() 内部走 ALRHICapabilities.getInstance() → RenderSystem.getDevice()，若构造期设备尚未就绪会 NPE；同处新增的 ALROptimizations.create() 也有同样依赖。现有 ALRPostEffects.createPostEffects() 已在同点调用，可能没问题，但时序较脆弱，建议确认设备已初始化。

  • module.gradle 提交了调试用 JVM 参数
    -XX:+UnlockDiagnosticVMOptions、-XX:+DebugNonSafepoints、--renderDebugLabels 看起来是本地调试配置残留，不应合入主干。

  • TestOcclusionBlock.codec() 复制粘贴错误（test/block/TestOcclusionBlock.java）
    return simpleCodec(TestBloomBlock::new) 应为 TestOcclusionBlock::new——从 TestBloomBlock 复制时漏改，会导致方块状态反序列化构造错误的方块类型。

  • GpuQueryOcclusionCuller 构造时机：ALROptimizations.getOcclusionCuller() 是惰性初始化，首个 RenderFrameEvent.Pre 才构建 culler（创建 CommandEncoder、pool、DynamicUniformStorage）。若 RenderSystem.getDevice() 在该点前未被调用过，存在设备未就绪风险，建议在 ALROptimizations.create() 中显式处理 null。

💡 建议

  • 重复 import org.jetbrains.annotations.ApiStatus：ALRCommandEncoderBackendExtension.java 及 sync 模块 5 个文件（SyncClassProcessor、LazySyncBytecodeInjector、LazySyncTargetIndex、SyncBytecodeInjector、SyncTargetIndex）均新增了与既有 import 重复的 ApiStatus import——能编译但应清理。
  • GlExtendedTexture：super(TextureFormat.RGBA8) 与实际 GL 分配格式（R32F 等）不一致。注释解释为有意为之（仅作非 framebuffer 用途），但任何下游代码读取 format() 会得到 RGBA8 并算错内存尺寸，建议在类上注明约束。
  • depth_convert.csh、diamond_block.json、test lang 等 9 处 EOF 缺换行——数据生成器输出建议补齐。
  • QueryInstance.CreationContext.vertexBuffer 静态字段：进程级单例、永不释放（注释「should keep alive when game running」可接受），但窗口重建/分辨率热切换时应确认不泄漏。
  • MipLayer.getDefinition() 返回 null：当前只当数据 holder 用没问题，但一旦被 write()/upload() 误用即 NPE，建议加断言或改为非 BufferObject。
  • OcclusionSubmitNodeCollection.beginOcclusionRecord 每次 clear() + endFrame()：多 feature 场景有重复清理开销，可考虑一次批量处理。

🟢 看起来不错

  • 查询一帧延迟设计自洽：beginFrame 中「close 旧 → fetchResults → 建新」的顺序正确，旧 query 结果先读出再归还池，跨帧复用安全。
  • shouldDraw 的 null/缺失键降级：results.getOrDefault(key, 1) > 0 与 cameraInside.contains(null) 均安全，feature 未关联 key 时优雅回退为绘制，不会崩溃。
  • OcclusionKey 用 identity equals/hashCode + fastutil Reference2 系列映射，与「key 必须跨帧同一实例」契约严格一致，测试 BE 用字段持有 key 符合约定。
  • OCCLUSION_QUERY 管线 ColorTargetState WRITE_NONE + 深度测试 LEQUAL，只写深度采样不污染颜色缓冲，设计正确。
  • 25 个新 Mixin/Accessor 全部注册进 anvillib_rendering.mixins.json，无遗漏。
  • Index/vertex 缓冲匹配：36 索引（6 quad × 6 三角形展开）× 24 顶点（6 面 × 4）一致。
  • pushDebugGroup 改为 Supplier<String> 的调用方全部同步更新完毕（ALRComputePass、GlComputePassBackend、GlDeviceMixin、GpuDeviceMixin），仓库内无残留旧签名调用。
  • 池化基础设施（GpuReusableResourcePool / LoopResetPool / SimpleResetPool）fail(true) 的 expand 逻辑正确，LoopResetPool.acquire 线性扫描可复用元素，release 正确重置状态。

📋 声称验证表

声称 状态 对应文件
OcclusionCuller/Key/Method 抽象 ✅ optimization/occlusion/*
occlusion-query 管线 + shader ✅ ALRPipelines, occlusion_query.vsh/.fsh
samples-query 创建/结果读取 + GlSamplesQuery ✅ ALRGpuDeviceExtension, GlDeviceMixin, GlSamplesQuery
GPU Query 生命周期 + ring-buffer 池 ✅ GpuQueryObject, pools, FrameState
Query 帧状态管理（本帧提交/下帧判读） ✅ GpuQueryOcclusionCuller, FrameState
compute debug group 惰性 Supplier ✅ ALRComputePass, GlComputePassBackend
ApiStatus.Internal 标注整理 ✅ rendering + sync 模块 20+ 文件
Hi-Z 后端 ⚠️ 仅基础设施占位（processFeatures 空、shouldDraw 恒 true）
与 vanilla SubmitNodeStorage 集成 ⚠️ 已接入但被 Hi-Z 默认选中遮蔽，实际不剔除

结论: REQUEST_CHANGES
基础设施质量高、生命周期设计与池化逻辑自洽，但存在两处必须修复的问题：ImageArrayBinding 的 Preconditions 参数反转是明确的运行时 bug；后端选择顺序导致剔除集成在支持 compute 的常规机器上被无实现的 Hi-Z 后端接管而失效。另建议修复 TestOcclusionBlock codec 复制粘贴错误、清理调试 JVM 参数与重复 import。

由 Hermes Agent 审查

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'minecraft-mod-pr-review' (1 replacement).

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

🌿 Roseau API Breaking Change Report

Module Status Breaking Changes
codec ✅ Compatible 0
collision ✅ Compatible 0
config ✅ Compatible 0
integration ✅ Compatible 0
moveable-entity-block ✅ Compatible 0
network ✅ Compatible 0
rendering 🔴 BC detected 27
space-select ✅ Compatible 0
font ✅ Compatible 0
util ✅ Compatible 0
explosion ✅ Compatible 0
rpc ✅ Compatible 0
multiblock ✅ Compatible 0
recipe ✅ Compatible 0
registrum ✅ Compatible 0
sync ✅ Compatible 0
wheel ✅ Compatible 0
main ✅ Compatible 0

🔴 rendering — 27 breaking change(s)

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/ALRGpuDeviceExtension.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.ALRGpuDeviceExtension
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_ERASURE_CHANGED
✗ binary-breaking
✓ source-compatible

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:66

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.bind(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout<T>,T)
METHOD_RETURN_TYPE_CHANGED_INCOMPATIBLE
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:24

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.popDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePass.java:20

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/ALRComputePassBackend.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePassBackend.pushDebugGroup(java.lang.String)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/AtomicCounterBinding.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.AtomicCounterBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.AtomicCounterBinding
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/AtomicCounterBinding.java:17

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.AtomicCounterBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.AtomicCounterBinding.apply(int,com.mojang.blaze3d.buffers.GpuBufferSlice,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.AtomicCounterBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ImageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ImageBinding.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ImageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ImageBinding
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ImageBinding.java:26

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ImageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ImageBinding.apply(int,com.mojang.blaze3d.textures.GpuTexture,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ShaderStorageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ShaderStorageBinding.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ShaderStorageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ShaderStorageBinding
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ShaderStorageBinding.java:18

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ShaderStorageBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ShaderStorageBinding.apply(int,com.mojang.blaze3d.buffers.GpuBufferSlice,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/TextureBinding.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/TextureBinding.java:18

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding.apply(int,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.TextureBinding$SamplerAndTexture,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/ComputeBindingLayout.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.UniformBlockBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.ComputeBindingLayout.apply(int,T,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/UniformBlockBinding.java

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.UniformBlockBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.UniformBlockBinding
TYPE_NEW_ABSTRACT_METHOD
✓ binary-compatible
✗ source-breaking

dev/anvilcraft/lib/v2/rendering/extension/blaze3d/compute/pipeline/bindings/UniformBlockBinding.java:17

dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.UniformBlockBinding
dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.bindings.UniformBlockBinding.apply(int,com.mojang.blaze3d.buffers.GpuBufferSlice,dev.anvilcraft.lib.v2.rendering.extension.blaze3d.compute.pipeline.ALRComputePass)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /opt/data/workspace && head -c 200 nf-src.jar | xxd | head -5; echo "---try jar tf---"; jar tf nf-src.jar 2>/dev/null | head -5 || python3 -c "print('no jar tool')" 2>/dev/null; ls /opt/data/worksp...

Reason: script execution via -e/-c flag

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Dangerous command requires approval:

cd /opt/data/workspace && python3 -c "
import zipfile, re
z = zipfile.ZipFile('client261.jar')
data = z.read('net/minecraft/client/renderer/SubmitNodeCollection.class')
# crude string extraction
strin...

Reason: script execution via -e/-c flag

Reply /approve to execute, /approve session to approve this pattern for the session, /approve always to approve permanently, or /deny to cancel.

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

⚠️ Iteration budget exhausted (90/90) — asking model to summarise

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

I reached the maximum iterations (90) but couldn't summarize. Error:

<title>504 Gateway Time-out</title>

504 Gateway Time-out

openresty

@Gugle2308

Gugle2308 commented Aug 29, 2026

Copy link
Copy Markdown

💾 Self-improvement review: Patched SKILL.md in skill 'rendering-gpu-pr-review' (1 replacement). · Patched references/pr95-occlusion-culling-review-matrix.md in skill 'rendering-gpu-pr-review' (1 replacement). · Patched references/class-file-constant-extraction.md in skill 'rendering-gpu-pr-review' (1 replacement).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ZhuRuoLing @Gugle2308