feat(core): GPU instancing auto-batching

[GuoLei1990]

Closes #194

Summary

• 为 MeshRenderer 引入自动 GPU Instancing，通过 UBO 打包 per-instance 数据驱动 instanced draw call
• InstanceBatch 将 renderer uniform（ModelMat、Layer 等）打包到共享的 std140 UBO 中
• ShaderFactory.injectInstanceUBO 自动扫描 shader 中的 renderer uniform，替换为 UBO 数组访问 + #define 重映射
• ModelMat 以 mat3x4 存储（仿射优化，48 字节 vs 64 字节），派生 uniform（MVMat/MVPMat/NormalMat）通过 #define 实时计算
• InstanceLayout 在 shader 编译时计算并缓存在 ShaderProgram 上，渲染时直接取用，无重复计算
• Per-pass 独立布局：不同 pass 按各自需要的 uniform 计算 struct 大小，ShadowCaster 等轻量 pass 可获得更高 instanceMaxCount
• MeshRenderer._canBatch/_batch 实现合批判定（相同 primitive + material + front-face）
• ShaderProgram._recordLocation 跳过 UBO 成员（location === null），避免无用 ShaderUniform 创建
• Opaque 排序策略改为按 material/primitive 排序（合批优先），移除距离排序

Performance

测试场景: 2500 glTF 模型（Avocado） + 2500 自定义 shader 立方体，全部动态旋转 + 缩放 + 颜色动画

设备	dev/2.0 (无 instancing)	feat/gpu-instancing	提升
iPhone 16 Pro Max	30 FPS	50 FPS	+67%

iPhone 实测截图（59 FPS / 21 Draw Calls / 5000 objects）：

Future Optimization

• ShaderLab 预编译元数据: 当前 injectInstanceUBO 通过正则扫描 GLSL 文本获取 renderer uniform 信息。如果 ShaderLab 预编译时提供 uniform 元数据（name, type, group），可以消除正则扫描，改为精确拼接，提升代码健壮性和可扩展性
• SubRenderElement 层级排序: Opaque 排序应下沉到 SubRenderElement 层级，避免多 submesh 物体打断合批连续性

Key Files

文件	职责
RenderPipeline/InstanceBatch.ts	UBO buffer 管理、per-instance 数据 upload
RenderPipeline/RenderQueue.ts	Instance-aware 渲染循环
shaderlib/ShaderFactory.ts	Uniform 扫描、std140 布局计算、UBO 代码生成注入
shader/ShaderPass.ts	Shader 编译入口，InstanceLayout 存储到 ShaderProgram
shader/ShaderProgram.ts	新增 _instanceLayout 字段，跳过 UBO 成员反射
mesh/MeshRenderer.ts	_canBatch/_batch 合批逻辑
shader/ShaderProgramMap.ts	多级位掩码 ShaderProgram 缓存

Test plan

• 多个共享 mesh + material 的 MeshRenderer 正确 instanced 渲染
• Shadow pass 与 instanced 物体配合正常
• 非 instancing renderer（SkinnedMeshRenderer、2D sprite）不受影响
• 无 renderer uniform 时（无 UBO layout）正常回退
• 性能验证：大量相同物体的 draw call 数量显著减少
• iPhone 16 Pro Max 实测 30 FPS → 50 FPS（+67%）

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds WebGL2 GPU instancing: instance UBO management, instance-aware shader compilation and caching, batching API/signature changes, render-queue instanced draw paths, device/GL helpers, examples and E2E tests, and supporting shader/uniform enhancements.

Changes

Cohort / File(s)	Summary
GPU Instancing Core packages/core/src/RenderPipeline/InstanceBatch.ts, packages/core/src/shader/ShaderBlockProperty.ts, packages/core/src/shader/enums/ConstantBufferBindingPoint.ts	New InstanceBatch class managing CPU packing and dynamic UBO allocation; ShaderBlockProperty for uniform block ids; ConstantBuffer binding enum for renderer-instance UBO.
Batching Parameter Refactoring packages/core/src/RenderPipeline/BatchUtils.ts, packages/core/src/2d/sprite/SpriteRenderer.ts, packages/core/src/2d/sprite/SpriteMask.ts, packages/core/src/2d/text/TextRenderer.ts, packages/core/src/Renderer.ts, packages/ui/src/component/UIRenderer.ts	Renamed batching parameters from (elementA, elementB) → (preSubElement, subElement) and adjusted nullability/optional semantics; updated BatchUtils to consume new parameter roles.
SubRenderElement & RenderPipeline packages/core/src/RenderPipeline/SubRenderElement.ts, packages/core/src/RenderPipeline/BasicRenderPipeline.ts, packages/core/src/RenderPipeline/RenderQueue.ts, packages/core/src/RenderPipeline/BatcherManager.ts	Replaced shaderPasses with subShader; added instancedRenderers on SubRenderElement; BasicRenderPipeline and RenderQueue updated to use SubShader and to perform instanced draw paths; BatcherManager exposes InstanceBatch and calls updated renderer batching signature.
Renderer & Mesh Changes packages/core/src/Renderer.ts, packages/core/src/mesh/MeshRenderer.ts, packages/core/src/mesh/SkinnedMeshRenderer.ts	Renderer shader-property fields visibility adjusted; batching hooks updated to new signatures; MeshRenderer supports collecting instanced renderers into SubRenderElement; SkinnedMeshRenderer disables batching.
Shader Program & Compilation packages/core/src/shader/ShaderPass.ts, packages/core/src/shader/ShaderProgram.ts, packages/core/src/shader/ShaderProgramMap.ts, packages/core/src/shader/ShaderBlockProperty.ts, packages/core/src/shaderlib/ShaderFactory.ts, packages/core/src/graphic/TransformFeedbackShader.ts	Switched from ShaderProgramPool → ShaderProgramMap cache; added _compileShaderProgram path that computes instance layouts and injects instance UBOs; ShaderProgram now records uniform block ids and supports bindUniformBlocks; ShaderFactory extended to generate instance-aware GLSL and return instance layout; related compile/cache call sites updated.
Shader Uniforms & Uploads packages/core/src/shader/ShaderUniform.ts	Added upload methods for Mat2/Mat3 and rectangular matrix types (WebGL2 variants).
Engine & Caching Fields packages/core/src/Engine.ts, packages/core/src/shader/ShaderProgramMap.ts	Replaced internal _shaderProgramPools with _shaderProgramMaps and adapted lazy accessors; ShaderProgramMap renamed/refactored with destroy() lifecycle.
RHI / WebGL2 Support packages/rhi-webgl/src/GLBuffer.ts, packages/rhi-webgl/src/WebGLGraphicDevice.ts, packages/core/src/graphic/enums/BufferBindFlag.ts	Added ConstantBuffer bind flag and mapped it to UNIFORM_BUFFER; WebGL device gains bindUniformBufferBase, bindUniformBlock, and getMaxUniformBlockSize helpers; GLBuffer target selection updated.
2D / UI Render Element Updates packages/core/src/2d/sprite/SpriteMask.ts, packages/ui/src/component/advanced/Image.ts, packages/ui/src/component/advanced/Text.ts	Overlay/2D sub-render elements now assign subShader instead of shaderPasses; small adjustments to subRenderElement setup to match SubShader change.
Examples, E2E & Tests examples/src/gpu-instancing-auto-batch.ts, examples/src/gpu-instancing-custom-data.ts, e2e/case/gpu-instancing-auto-batch.ts, e2e/case/gpu-instancing-custom-data.ts, e2e/config.ts, examples/package.json, tests/src/shader-lab/*	Added examples and E2E tests for instancing; registered new E2E config entries; examples add custom shaders and animated instanced entities; tests updated to call _compileShaderProgram and benchmark helpers adjusted.
Tooling / Packages package.json, examples/package.json	Dev tooling upgrades (ESLint, TypeScript ESLint parser/plugin, lint-staged) and added @galacean/engine-toolkit-stats dependency in examples.
Other Render Pipeline Adjustments packages/core/src/RenderPipeline/BasicRenderPipeline.ts, packages/core/src/RenderPipeline/BatchUtils.ts, packages/core/src/RenderPipeline/InstanceBatch.ts	pushRenderElement now consumes SubShader; BatchUtils.batchFor2D signature adjusted; InstanceBatch integrated into BatcherManager and RenderQueue flows for chunked uploads and instanced draw submission.

Sequence Diagram(s)

sequenceDiagram
    participant RenderQueue as RenderQueue
    participant BatcherManager as BatcherManager
    participant InstanceBatch as InstanceBatch
    participant GPUBuffer as GPU Constant Buffer
    participant ShaderProgram as ShaderProgram

    RenderQueue->>BatcherManager: request instanceBatch (lazy)
    BatcherManager->>InstanceBatch: setLayout(layout)
    InstanceBatch->>GPUBuffer: create/realloc UBO (if needed)
    loop per instanced chunk
        RenderQueue->>InstanceBatch: upload(renderers[], start, count)
        InstanceBatch->>InstanceBatch: pack per-instance fields into CPU buffer
        InstanceBatch->>GPUBuffer: setData(range, Discard)
    end
    RenderQueue->>ShaderProgram: bindUniformBlocks(bindingMap)
    ShaderProgram->>GPUBuffer: uniformBlockBinding(bindingPoint)
    RenderQueue->>RenderQueue: issue drawPrimitive with instanceCount

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I packed the fields in quiet rows,
UBOs hum where instance data flows,
Shaders peep and vary hue,
Batches leap — five thousand, who knew?
A tiny rabbit hops — render goes!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title "feat(core): GPU instancing auto-batching" directly and clearly summarizes the primary feature added in this changeset: GPU instancing with automatic batching for improved rendering performance.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/gpu-instancing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 44.31227% with 749 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.08%. Comparing base (a54642f) to head (06759e6).
⚠️ Report is 9 commits behind head on dev/2.0.

Files with missing lines	Patch %	Lines
packages/core/src/shaderlib/ShaderFactory.ts	43.50%	174 Missing ⚠️
examples/src/gpu-instancing-auto-batch.ts	0.00%	116 Missing and 1 partial ⚠️
examples/src/gpu-instancing-custom-data.ts	0.00%	82 Missing and 1 partial ⚠️
e2e/case/gpu-instancing-custom-data.ts	0.00%	45 Missing and 1 partial ⚠️
packages/core/src/RenderPipeline/InstanceBuffer.ts	46.51%	46 Missing ⚠️
e2e/case/gpu-instancing-auto-batch.ts	0.00%	42 Missing and 1 partial ⚠️
packages/core/src/RenderPipeline/RenderQueue.ts	52.23%	32 Missing ⚠️
packages/core/src/shader/ShaderProgram.ts	52.08%	23 Missing ⚠️
...ges/core/src/RenderPipeline/BasicRenderPipeline.ts	43.24%	21 Missing ⚠️
packages/core/src/RenderPipeline/BatchUtils.ts	20.00%	16 Missing ⚠️
... and 20 more

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/2.0    #2957      +/-   ##
===========================================
- Coverage    77.38%   77.08%   -0.30%     
===========================================
  Files          900      907       +7     
  Lines        98752    99807    +1055     
  Branches      9817     9866      +49     
===========================================
+ Hits         76415    76933     +518     
- Misses       22170    22703     +533     
- Partials       167      171       +4     

Flag	Coverage Δ
unittests	77.08% <44.31%> (-0.30%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[GuoLei1990]

补充 [P0] RenderElement.ts:dispose — instancedRenderers = null 导致对象池复用时 NPE

dispose() 中 this.instancedRenderers = null，但 set() 中执行 this.instancedRenderers.length = 0。当 RenderElement 被 ObjectPool 回收后再取出调用 set() 时，会在 null.length 上抛 TypeError。应改为 this.instancedRenderers.length = 0 保持数组引用存活，或在 set() 中重新创建数组。

 dispose(): void {
-    this.instancedRenderers = null;
+    this.instancedRenderers.length = 0;
 }

（来自深度 review 补充，上一条 review 中遗漏）

[zhuxudong]

Bug: _scanInstanceUniforms 不感知 #ifdef，导致特定场景下 GPU Instancing 编译报错

复现条件

场景中 同时存在 SkinnedMeshRenderer 和可合批的 MeshRenderer（相同 mesh + 相同 material）。

报错信息

GPU Instancing does not support array uniform "renderer_JointMatrix[ RENDERER_JOINTS_NUM ]"

根因分析

ShaderFactory._scanInstanceUniforms 用正则扫描 GLSL 源码中的 renderer 组 uniform，将其收入 instancing UBO。但扫描发生在 compilePlatformSource 路径中，该路径只 prepend #define，不展开 #ifdef 块：

parseIncludes()          → 展开 #include
parseCustomMacros()      → 生成 #define 行，prepend 到源码
injectInstanceUBO()      → _scanInstanceUniforms() 正则逐行匹配 ← #ifdef 块仍在源码中

内置 PBR vertex shader（common_vert.glsl）中：

#ifdef RENDERER_HAS_SKIN
    // ...
    #else
        uniform mat4 renderer_JointMatrix[ RENDERER_JOINTS_NUM ];  // ← 正则命中
    #endif
#endif

对于 MeshRenderer，RENDERER_HAS_SKIN 未定义，这行 uniform 不会参与编译，但正则不理解 #ifdef 语义，仍然匹配到并报错。

为什么大部分场景不触发

_scanInstanceUniforms 有一个前置判断：

if (isDerived === undefined
    && ShaderProperty._getShaderPropertyGroup(name) !== ShaderDataGroup.Renderer)
    return match; // 跳过

ShaderProperty._group 是延迟赋值的（ShaderData.ts:657-658），只在首次 shaderData.setXxx(property, value) 时绑定 group。

• 无 SkinnedMeshRenderer 的场景（如 CarParking）：renderer_JointMatrix._group === undefined → _getShaderPropertyGroup 返回 undefined → 判定为非 renderer uniform → 跳过，不报错
• 有 SkinnedMeshRenderer 的场景：SkinnedMeshRenderer 执行 shaderData.setFloatArray(_jointMatrixProperty, skinMatrices) → _group 被写为 ShaderDataGroup.Renderer → 正则命中后走到 array 检查 → 报错

这是一个时序相关的隐蔽 bug——同一份代码，有无骨骼模型决定了是否报错。

影响范围

任何使用内置 PBR shader 的 MeshRenderer，在场景中同时存在 SkinnedMeshRenderer 时，合批编译就会触发。不限于自定义 shader。

[GuoLei1990]

增量审查 (2026-04-23)

基于最新 commit 29567302c（fix(shader): scan instance uniforms with macro awareness for raw GLSL）和完整代码状态进行增量审查。

已关闭问题清单

#	问题	状态
1	_canBatch 缺少 renderer-level state	✅ 已修复（macroCollection.isEqual + frontFace）
2	renderer_LocalMat/renderer_MVInvMat 未删除	✅ 已修复
3	NormalMat per-vertex inverse()	✅ 已关闭（GPU ALU 换 UBO 空间，后续优化）
4	Opaque 距离排序移除	✅ 已关闭（TBDR 架构 batch-first 是正确方向）
5	WebGL2 guard	✅ 已关闭（_canBatch 上游保证）
6	SpriteMask 交互	✅ 已关闭（与 MeshRenderer instancing 无关）
7	mat3x4 仿射假设	✅ 已关闭（架构保证）
8	ShaderProgramMap constructor	✅ 已修复
9	array uniform 检测	✅ 已修复（报错 + 保留原声明）
10	_scanInstanceUniforms 不感知 #ifdef	✅ 已修复（本次 commit）
11	bindUniformBlock 死代码	✅ 已清理
12	正则匹配注释中 uniform 声明	✅ 已关闭（后续 ShaderLab 元数据替代）
13	renderer_LocalMat 移除 breaking change	✅ 已关闭（dev/2.0 scope）
14	_std140TypeInfoMap 缺 bool	✅ 已关闭（极罕见，触发时类型静默跳过不导致编译失败）

本次 commit 分析

_scanInstanceUniformsWithMacros — 宏感知预处理扫描器

修复了 @zhuxudong 报告的 bug：SkinnedMeshRenderer 和 MeshRenderer 共存时，renderer_JointMatrix 在 #ifdef RENDERER_HAS_SKIN 块内但被正则命中导致报错。

实现方案审查：

逐行解析 + branchStack 状态机，支持 #ifdef / #ifndef / #else / #endif 嵌套。方案简洁有效。关键逻辑验证：

1. 嵌套 #ifdef + #else：以 common_vert.glsl 的实际结构验证——

   #ifdef RENDERER_HAS_SKIN           // MeshRenderer: SKIN 未定义 → push false
     #ifdef RENDERER_USE_JOINT_TEXTURE // parent inactive → push false
       uniform sampler2D ...           // top=false → skip ✓
     #else                             // parentActive=false, !current=true → false ✓
       uniform mat4 renderer_JointMatrix...  // top=false → skip ✓
     #endif
   #endif
   

   嵌套 #else 在 parent inactive 下正确传播不可达性。✓

2. _scanInstanceUniforms 单行调用兼容性：_uboUniformRegex 有 gm flag，String.prototype.replace() 在每次调用时重置 lastIndex，单行调用安全。✓

3. #if 表达式不支持：注释已标注 #if with expressions treated as always-active。这是保守正确的——多扫描只浪费 UBO 空间，不影响渲染正确性。✓

4. array uniform 从 return "" 改为 return match：不支持的 array uniform 保留原声明而非删除。正确修复——之前删除会导致编译失败。✓

5. activeMacros 构建：在 compilePlatformSource 中从 shaderMacroList 构建 Set<string>，包含 renderer macro + material macro + engine macro。完整覆盖了编译时宏集合。✓

设计选择：dual path（activeMacros ? WithMacros : plain）

injectInstanceUBO 保留了 activeMacros?: Set<string> 可选参数，无 macro 时走原始正则路径。这是为 ShaderLab 路径保留的——ShaderLab 在编译前已展开 #ifdef，不需要宏感知扫描。分离两条路径是正确的，避免对已展开的源码做不必要的逐行解析。✓

问题

• [P2] RenderElement.dispose() 将 instancedRenderers 设为 null — 与 set() 的非 null 假设矛盾

  // dispose() line 48
  this.instancedRenderers = null;
  
  // set() line 38
  this.instancedRenderers.length = 0;  // NPE if instancedRenderers is null

  当前 ClearableObjectPool.garbageCollection() 调用 dispose() 后执行 elements.length = 0（清空数组），所以 disposed 元素不会被 get() 返回。在现有 pool 实现下是安全的。

  但这是一个契约不一致：dispose() 破坏了 set() 的前置条件。如果未来 pool 实现变化（如 shrink-to-fit GC 只 dispose 尾部多余元素），立刻 NPE。修复成本为零：

  this.instancedRenderers.length = 0;  // 而非 = null

  保持数组实例存活，释放内部引用，与 dispose() 中其他数组字段（如未来可能的）保持一致语义。

简化建议

1. dispose() 中 this.shaderData && (this.shaderData = null) 和 this.texture && (this.texture = null) 的 && 短路检查不必要——直接赋 null 即可。对 already-null 字段赋 null 没有副作用或性能开销。

2. _scanInstanceUniformsWithMacros 中 branchStack.length >= 2 ? branchStack[branchStack.length - 2] : true 的 fallback（true）处理了 #else 出现在栈深度为 1 时的边界情况（即 #else 无对应 #ifdef）。这是防御性编程，GLSL 编译器会先报错，实际不可能触发——可以简化为 branchStack[branchStack.length - 2]，但保留也无碍。

总评

本次 commit 精准修复了 @zhuxudong 报告的时序依赖 bug。实现方案（逐行 #ifdef 状态机）简洁且正确，嵌套分支处理经验证无误。dual-path 设计为 ShaderLab 路径保留了零开销的原始路径。array uniform 的 return match 修复是正确的伴随修复。

整个 PR 经多轮迭代后质量很高。唯一遗留的 P2（dispose() NPE）是防御性修复，不阻塞合入但建议顺手改掉。

LGTM 👍