refactor(layers): document render entries + drop deprecated renderMulPass (stage-4 4.1)

P4 阶段 4 第一刀（4.1）。渲染管线入口边界 JSDoc 文档化

（render 单 pass / renderMultiPass multipass / renderModels 共享执行器

/ renderLayers 重渲信号 / prerender 帧前钩子），运行时零行为变化。

移除 renderMulPass：非 ILayer 接口、无内部调用方、0.2 已 @deprecated

并预告收口，能力已被 renderMultiPass 内联覆盖（minor 弃用移除）。

验证：layers father build 279 files、非 GL jest 25 suites/158 passed。

Author: lzxue

.changeset/refactor-layers-render-entries.md

@@ -0,0 +1,33 @@
+---
+'@antv/l7-layers': minor
+---
+
+refactor(layers): document render entries + drop deprecated renderMulPass (stage-4 4.1)
+
+P4 阶段 4 第一刀（4.1，layers 侧，minor）。
+
+渲染管线 6 入口边界厘清 + 文档化（运行时零行为变化）：
+
+- `render()`：单 pass 渲染入口（`LayerService` 在未启用
+  `enableMultiPassRenderer` 时调用）。瓦片图层短路委托
+  `tileLayer.render()`；否则 `beforeRenderData` 通知 + 空数据早退
+  （避免数据纹理空数据导致 texture 超限），最后委托 `renderModels`。
+  multipass 路径由 `LayerService` 直接调用 `renderMultiPass`，不经此方法。
+- `renderMultiPass()`：multipass 渲染入口（`LayerService` 在启用
+  `enableMultiPassRenderer` 时调用）；有 `multiPassRenderer` 且
+  `getRenderFlag()` 为真时委托其编排，否则回退 `renderModels`。
+- `renderModels()`：单 pass 共享 `model.draw` 执行器（`beforeRender` +
+  逐 model draw，uniforms/blend/stencil/textures 取自 `layerModel`），
+  被 `render` 与 `renderMultiPass` 复用。
+- `renderLayers()`：触发 `layerService.reRender()` 批量重渲信号，前后
+  标记 `rendering` 防重入。
+- `prerender()`：每帧渲染前钩子，默认空体，子类可 override。
+
+同时移除 `renderMulPass(multiPassRenderer)` —— 该方法不在 `ILayer`
+公共接口、无任何内部调用方、阶段 0.2 已 `@deprecated` 并预告「将在
+渲染管线收敛（阶段 4）时并入 `renderMultiPass`」。其能力已被
+`renderMultiPass()` 内联的 `await this.multiPassRenderer.render()`
+覆盖。属预公告的弃用移除（minor）。
+
+验证：layers eslint 0 error、prettier 通过、layers father build 279
+files（d.ts OK）、非 GL jest 子集 25 suites / 158 passed 与基线一致。

docs/refactoring/layers/PLAN.md

@@ -98,7 +98,7 @@ citybuilding/ geometry/ — 12 个具体图层 extends BaseLayer（各自只 ove
 
 ### 阶段 4 — 渲染管线收敛
 
-- 4.1 厘清 6 入口：`render()`（总入口，分流 tile/multipass/single）→ `renderModels()`（single-pass model.draw）+ `renderMultiPass()`（multipass 编排）；`renderMulPass`（阶段 0.2 已改名/降级）收为 `renderMultiPass` 内部助手；`renderLayers()`/`prerender()` 边界文档化。
+- 4.1 ✅ 厘清入口：`render()`（单 pass 入口，tile 短路 + 空数据早退 + `renderModels`）与 `renderMultiPass()`（multipass 入口，`LayerService` 按 `enableMultiPassRenderer` 分流）边界 JSDoc 文档化；`renderModels()` 共享 `model.draw` 执行器、`renderLayers()` 重渲信号、`prerender()` 帧前钩子文档化；移除无调用方/非 `ILayer` 的 `@deprecated` `renderMulPass`（0.2 预告收口）。
 - 4.2 `multiPassRenderer/postProcessingPassFactory/normalPassFactory` 初始化收敛到 `LayerModelManager`（阶段 1.2），消除 `init()` 与 `setMultiPass()` 两处分散初始化。
 - 4.3 `renderModels` 的 `encodeDataLength <= 0 && !forceRender` 空数据早退逻辑（1277）下沉到 manager 并加 spec（当前仅 TODO 注释保护 texture 超限）。
 

packages/layers/src/core/BaseLayer.ts

@@ -689,7 +689,8 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
   }
 
   /**
-   * 渲染所有的图层
+   * 触发 `layerService.reRender()` 批量重渲信号（非即时逐帧绘制），
+   * 前后标记 `rendering` 防重入。供外部/插件请求重绘时使用。
    */
   public renderLayers(): void {
     this.rendering = true;
@@ -704,6 +705,13 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
    */
   prerender() {}
 
+  /**
+   * 单 pass 渲染入口（`LayerService` 在未启用 `enableMultiPassRenderer`
+   * 时调用）。分流顺序：瓦片图层短路委托 `tileLayer.render()`；否则经
+   * `beforeRenderData` 通知 + 空数据早退（避免数据纹理空数据导致 texture
+   * 超限），最后委托 {@link renderModels} 执行 `model.draw`。multipass
+   * 路径由 `LayerService` 直接调用 {@link renderMultiPass}，不经此方法。
+   */
   public render(options: Partial<IRenderOptions> = {}): ILayer {
     if (this.tileLayer) {
       // 瓦片图层执行单独的 render 渲染队列
@@ -720,9 +728,10 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
   }
 
   /**
-   * multipass 图层的公共渲染入口：有 multiPassRenderer 时委托其编排渲染，
-   * 否则回退到 {@link renderModels} 单 pass 渲染。与已废弃的
-   * {@link renderMulPass}（单个 renderer 的薄封装）区分。
+   * multipass 图层的公共渲染入口（`LayerService` 在启用
+   * `enableMultiPassRenderer` 时调用）：有 `multiPassRenderer` 且其
+   * `getRenderFlag()` 为真时委托其编排多 pass 渲染，否则回退到
+   * {@link renderModels} 单 pass 渲染。空数据同样早退。
    */
   public async renderMultiPass() {
     if (this.encodeDataLength <= 0 && !this.forceRender) {
@@ -1076,14 +1085,11 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
   }
 
   /**
-   * @deprecated 该方法不在 `ILayer` 公共接口中，且无内部调用方，仅为单个
-   * multipass renderer 的薄封装。新代码请使用 {@link renderMultiPass}（整图层
-   * 多 pass 渲染入口）。将在渲染管线收敛（阶段 4）时并入 `renderMultiPass`。
+   * 单 pass 渲染的共享 `model.draw` 执行器：空数据早退并 `clearModels()`
+   * 释放（同 texture 超限保护），否则触发 `hooks.beforeRender` 后逐
+   * `model.draw`（uniforms/blend/stencil/textures 取自 `layerModel`）。
+   * 被 {@link render}（单 pass）与 {@link renderMultiPass}（回退）复用。
    */
-  public async renderMulPass(multiPassRenderer: IMultiPassRenderer) {
-    await multiPassRenderer.render();
-  }
-
   public renderModels(options: Partial<IRenderOptions> = {}) {
     // TODO: this.getEncodedData().length > 0 这个判断是为了解决在 2.5.x 引入数据纹理后产生的 空数据渲染导致 texture 超出上限问题
     if (this.encodeDataLength <= 0 && !this.forceRender) {