refactor: clean architecture for TransformFeedbackPrimitive

GuoLei1990 · claude · GuoLei1990 · commit 2024ae178fa2 · 2026-03-17T17:30:08.000+08:00
- Move VAO management to GLTransformFeedbackPrimitive (RHI layer)
- Add IPlatformTransformFeedbackPrimitive interface
- Remove GL calls from core layer TransformFeedbackPrimitive
- Split draw into beginDraw/draw/endDraw (no array allocation)
- Use VertexElement/VertexBufferBinding directly (no intermediate types)
- Remove unused drawArrays/VAO methods from WebGLGraphicDevice
- Fix TF buffer residual binding causing GL conflict on VAO rebuild

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/core/src/graphic/TransformFeedbackPrimitive.ts b/packages/core/src/graphic/TransformFeedbackPrimitive.ts
@@ -1,141 +1,129 @@
 import { Engine } from "../Engine";
+import { IPlatformTransformFeedbackPrimitive } from "../renderingHardwareInterface";
 import { ShaderProgram } from "../shader/ShaderProgram";
 import { Buffer } from "./Buffer";
 import { BufferBindFlag } from "./enums/BufferBindFlag";
 import { BufferUsage } from "./enums/BufferUsage";
+import { MeshTopology } from "./enums/MeshTopology";
 import { TransformFeedback } from "./TransformFeedback";
 import { VertexBufferBinding } from "./VertexBufferBinding";
 import { VertexElement } from "./VertexElement";
-import { MeshTopology } from "./enums/MeshTopology";
 
 /**
  * @internal
- * A primitive that manages ping-pong buffers and VAOs for Transform Feedback rendering.
- * Handles buffer creation, VAO setup, TF draw with bindBufferRange, and ping-pong swap.
+ * Transform Feedback primitive that manages buffers, draw calls, and state for GPU-side data capture.
  */
 export class TransformFeedbackPrimitive {
+  /** @internal */
+  _platformPrimitive: IPlatformTransformFeedbackPrimitive;
+
   private _engine: Engine;
+  private _transformFeedback: TransformFeedback;
   private _readBuffer: Buffer;
   private _writeBuffer: Buffer;
-  private _transformFeedback: TransformFeedback;
-
-  // VAO pair for current program (one per ping-pong direction)
-  private _vaoA: WebGLVertexArrayObject;
-  private _vaoB: WebGLVertexArrayObject;
-  private _useA = true;
-  private _lastProgramId = -1;
-
   private _renderBufferBinding: VertexBufferBinding;
   private _byteStride: number;
-  private _vertexCount = 0;
-  private _initialized = false;
+  private _readIsFirst = true;
 
+  /**
+   * Buffer binding for the render pass (points to the latest TF output).
+   */
   get currentRenderBufferBinding(): VertexBufferBinding {
     return this._renderBufferBinding;
   }
 
+  /**
+   * The current read buffer (TF input / render source).
+   */
   get readBuffer(): Buffer {
     return this._readBuffer;
   }
 
+  /**
+   * The current write buffer (TF output target).
+   */
   get writeBuffer(): Buffer {
     return this._writeBuffer;
   }
 
-  get initialized(): boolean {
-    return this._initialized;
-  }
-
+  /**
+   * @param engine - Engine instance
+   * @param byteStride - Bytes per vertex in the TF buffer
+   */
   constructor(engine: Engine, byteStride: number) {
     this._engine = engine;
     this._byteStride = byteStride;
     this._transformFeedback = new TransformFeedback(engine);
     this._transformFeedback.isGCIgnored = true;
+    this._platformPrimitive = engine._hardwareRenderer.createPlatformTransformFeedbackPrimitive();
   }
 
   /**
-   * Resize ping-pong buffers for the given vertex count.
+   * Resize buffers.
+   * @param vertexCount - Number of vertices to allocate
    */
   resize(vertexCount: number): void {
-    if (vertexCount === this._vertexCount && this._initialized) return;
-
-    const engine = this._engine;
-    const byteLength = this._byteStride * vertexCount;
-
     this._readBuffer?.destroy();
     this._writeBuffer?.destroy();
 
-    const readBuffer = new Buffer(engine, BufferBindFlag.VertexBuffer, byteLength, BufferUsage.Dynamic, false);
+    const byteLength = this._byteStride * vertexCount;
+    const readBuffer = new Buffer(this._engine, BufferBindFlag.VertexBuffer, byteLength, BufferUsage.Dynamic, false);
     readBuffer.isGCIgnored = true;
-    const writeBuffer = new Buffer(engine, BufferBindFlag.VertexBuffer, byteLength, BufferUsage.Dynamic, false);
+    const writeBuffer = new Buffer(this._engine, BufferBindFlag.VertexBuffer, byteLength, BufferUsage.Dynamic, false);
     writeBuffer.isGCIgnored = true;
 
-    const floatStride = this._byteStride / 4;
-    const zeroData = new Float32Array(vertexCount * floatStride);
-    readBuffer.setData(zeroData);
-    writeBuffer.setData(zeroData);
-
     this._readBuffer = readBuffer;
     this._writeBuffer = writeBuffer;
-    this._renderBufferBinding = new VertexBufferBinding(this._readBuffer, this._byteStride);
-    this._vertexCount = vertexCount;
-    this._initialized = true;
-    // Force VAO rebuild on next updateVAOs
-    this._lastProgramId = -1;
+    this._renderBufferBinding = new VertexBufferBinding(readBuffer, this._byteStride);
   }
 
   /**
-   * Ensure VAOs are up-to-date. Automatically rebuilds when program or buffers change.
+   * Prepare for drawing. Updates attribute bindings if needed and binds state.
+   * @param program - The shader program
+   * @param feedbackElements - Vertex elements for the feedback buffer
+   * @param inputBinding - Input buffer binding (e.g., instance data)
+   * @param inputElements - Vertex elements for the input buffer
    */
-  updateVAOs(
+  beginDraw(
     program: ShaderProgram,
-    tfElements: VertexElement[],
-    extraBindings: { binding: VertexBufferBinding; elements: VertexElement[] }[]
+    feedbackElements: VertexElement[],
+    inputBinding: VertexBufferBinding,
+    inputElements: VertexElement[]
   ): void {
-    if (program.id === this._lastProgramId) return;
-
-    const gl = this._engine._hardwareRenderer.gl as WebGL2RenderingContext;
-
-    this._deleteVAOs(gl);
-
-    this._vaoA = this._createVAO(gl, program, this._readBuffer, tfElements, extraBindings);
-    this._vaoB = this._createVAO(gl, program, this._writeBuffer, tfElements, extraBindings);
-    this._lastProgramId = program.id;
-
-    gl.bindVertexArray(null);
+    this._platformPrimitive.update(
+      program,
+      this._readBuffer,
+      this._writeBuffer,
+      this._byteStride,
+      feedbackElements,
+      inputBinding,
+      inputElements
+    );
+    this._platformPrimitive.bind(this._readIsFirst);
   }
 
   /**
-   * Bind the current VAO for TF drawing.
+   * Execute a single TF draw call for a vertex range.
+   * @param mode - Primitive topology
+   * @param first - First vertex index
+   * @param count - Number of vertices to process
    */
-  bindVAO(): void {
-    const gl = this._engine._hardwareRenderer.gl as WebGL2RenderingContext;
-    gl.bindVertexArray(this._useA ? this._vaoA : this._vaoB);
+  draw(mode: MeshTopology, first: number, count: number): void {
+    const transformFeedback = this._transformFeedback;
+    transformFeedback.bind();
+    transformFeedback.bindBufferRange(0, this._writeBuffer, first * this._byteStride, count * this._byteStride);
+    transformFeedback.begin(mode);
+    this._platformPrimitive.draw(mode, first, count);
+    transformFeedback.end();
+    transformFeedback.unbindBuffer(0);
+    transformFeedback.unbind();
   }
 
   /**
-   * Unbind VAO after TF drawing.
+   * Finish drawing and unbind state.
    */
-  unbindVAO(): void {
-    const gl = this._engine._hardwareRenderer.gl as WebGL2RenderingContext;
-    gl.bindVertexArray(null);
-  }
-
-  /**
-   * Execute a TF draw call for a range of vertices.
-   */
-  draw(rhi: any, mode: MeshTopology, first: number, count: number): void {
-    const byteOffset = first * this._byteStride;
-    const byteSize = count * this._byteStride;
-    this._transformFeedback.bind();
-    this._transformFeedback.bindBufferRange(0, this._writeBuffer, byteOffset, byteSize);
-    this._transformFeedback.begin(mode);
-    rhi.drawArrays(mode, first, count);
-    this._transformFeedback.end();
-    // Unbind TF buffer from TRANSFORM_FEEDBACK_BUFFER target to avoid
-    // conflicts when the same buffer is bound as ARRAY_BUFFER in render pass.
-    this._transformFeedback.unbindBuffer(0);
-    this._transformFeedback.unbind();
+  endDraw(): void {
+    this._platformPrimitive.unbind();
   }
 
   /**
@@ -145,66 +133,14 @@ export class TransformFeedbackPrimitive {
     const temp = this._readBuffer;
     this._readBuffer = this._writeBuffer;
     this._writeBuffer = temp;
-    this._useA = !this._useA;
+    this._readIsFirst = !this._readIsFirst;
     this._renderBufferBinding = new VertexBufferBinding(this._readBuffer, this._byteStride);
   }
 
   destroy(): void {
-    const gl = this._engine._hardwareRenderer.gl as WebGL2RenderingContext;
-    this._deleteVAOs(gl);
+    this._platformPrimitive?.destroy();
     this._readBuffer?.destroy();
     this._writeBuffer?.destroy();
     this._transformFeedback?.destroy();
   }
-
-  private _deleteVAOs(gl: WebGL2RenderingContext): void {
-    if (this._vaoA) {
-      gl.deleteVertexArray(this._vaoA);
-      this._vaoA = null;
-    }
-    if (this._vaoB) {
-      gl.deleteVertexArray(this._vaoB);
-      this._vaoB = null;
-    }
-  }
-
-  private _createVAO(
-    gl: WebGL2RenderingContext,
-    program: ShaderProgram,
-    tfReadBuffer: Buffer,
-    tfElements: VertexElement[],
-    extraBindings: { binding: VertexBufferBinding; elements: VertexElement[] }[]
-  ): WebGLVertexArrayObject {
-    const vao = gl.createVertexArray();
-    gl.bindVertexArray(vao);
-
-    const attribs = program.attributeLocation;
-
-    tfReadBuffer.bind();
-    this._bindElements(gl, attribs, tfElements, this._byteStride);
-
-    for (const { binding, elements } of extraBindings) {
-      binding.buffer.bind();
-      this._bindElements(gl, attribs, elements, binding.stride);
-    }
-
-    gl.bindBuffer(gl.ARRAY_BUFFER, null);
-    return vao;
-  }
-
-  private _bindElements(
-    gl: WebGL2RenderingContext,
-    attribs: Record<string, number>,
-    elements: VertexElement[],
-    stride: number
-  ): void {
-    for (const element of elements) {
-      const loc = attribs[element.attribute];
-      if (loc !== undefined && loc !== -1) {
-        const info = element._formatMetaInfo;
-        gl.enableVertexAttribArray(loc);
-        gl.vertexAttribPointer(loc, info.size, info.type, info.normalized, stride, element.offset);
-      }
-    }
-  }
 }
diff --git a/packages/core/src/particle/ParticleTransformFeedbackSimulator.ts b/packages/core/src/particle/ParticleTransformFeedbackSimulator.ts
@@ -26,7 +26,7 @@ export class ParticleTransformFeedbackSimulator {
   private static readonly _deltaTimeProperty = ShaderProperty.getByName("renderer_DeltaTime");
 
   // TF read buffer vertex elements
-  private static readonly _tfElements: VertexElement[] = [
+  private static readonly _feedbackElements: VertexElement[] = [
     new VertexElement("a_TFPosition", 0, VertexElementFormat.Vector3, 0),
     new VertexElement("a_TFVelocity", 12, VertexElementFormat.Vector3, 0)
   ];
@@ -106,12 +106,6 @@ export class ParticleTransformFeedbackSimulator {
 
     if (!this._tfProgram || !this._tfProgram.isValid) return;
 
-    // Update VAOs (auto-rebuilds if program or buffers changed)
-    const instanceBinding = new VertexBufferBinding(instanceBuffer, ParticleBufferUtils.instanceVertexStride);
-    this._primitive.updateVAOs(this._tfProgram, ParticleTransformFeedbackSimulator._tfElements, [
-      { binding: instanceBinding, elements: ParticleTransformFeedbackSimulator._instanceElements }
-    ]);
-
     // --- TF pass ---
     this._tfProgram.bind();
     rhi.enableRasterizerDiscard();
@@ -121,20 +115,25 @@ export class ParticleTransformFeedbackSimulator {
     this._tfProgram.uploadUniforms(this._tfProgram.rendererUniformBlock, shaderData);
     this._tfProgram.uploadUniforms(this._tfProgram.otherUniformBlock, shaderData);
 
-    // Bind VAO and execute TF for alive particles
-    this._primitive.bindVAO();
+    // Draw alive particles (ring buffer may wrap into two segments)
+    const instanceBinding = new VertexBufferBinding(instanceBuffer, ParticleBufferUtils.instanceVertexStride);
+    this._primitive.beginDraw(
+      this._tfProgram,
+      ParticleTransformFeedbackSimulator._feedbackElements,
+      instanceBinding,
+      ParticleTransformFeedbackSimulator._instanceElements
+    );
 
-    const POINTS = MeshTopology.Points;
     if (firstActive < firstFree) {
-      this._primitive.draw(rhi, POINTS, firstActive, firstFree - firstActive);
+      this._primitive.draw(MeshTopology.Points, firstActive, firstFree - firstActive);
     } else {
-      this._primitive.draw(rhi, POINTS, firstActive, particleCount - firstActive);
+      this._primitive.draw(MeshTopology.Points, firstActive, particleCount - firstActive);
       if (firstFree > 0) {
-        this._primitive.draw(rhi, POINTS, 0, firstFree);
+        this._primitive.draw(MeshTopology.Points, 0, firstFree);
       }
     }
 
-    this._primitive.unbindVAO();
+    this._primitive.endDraw();
     rhi.disableRasterizerDiscard();
 
     // Swap ping-pong
diff --git a/packages/core/src/renderingHardwareInterface/IPlatformTransformFeedbackPrimitive.ts b/packages/core/src/renderingHardwareInterface/IPlatformTransformFeedbackPrimitive.ts
@@ -0,0 +1,48 @@
+/**
+ * Platform interface for Transform Feedback primitive operations.
+ * @internal
+ */
+export interface IPlatformTransformFeedbackPrimitive {
+  /**
+   * Update attribute bindings for the given program. Auto-rebuilds when program changes.
+   * @param program - Shader program (for attribute locations)
+   * @param readBuffer - Current read buffer (ping-pong A)
+   * @param writeBuffer - Current write buffer (ping-pong B)
+   * @param tfStride - TF buffer byte stride
+   * @param feedbackElements - Vertex elements for TF buffer
+   * @param inputBindings - Additional buffers with their vertex elements
+   */
+  update(
+    program: any,
+    readBuffer: any,
+    writeBuffer: any,
+    feedbackStride: number,
+    feedbackElements: any[],
+    inputBinding: any,
+    inputElements: any[]
+  ): void;
+
+  /**
+   * Bind attribute state for the given ping-pong direction.
+   * @param useA - Whether to bind direction A or B
+   */
+  bind(useA: boolean): void;
+
+  /**
+   * Unbind attribute state.
+   */
+  unbind(): void;
+
+  /**
+   * Issue a draw call.
+   * @param mode - Primitive topology
+   * @param first - First vertex index
+   * @param count - Number of vertices
+   */
+  draw(mode: number, first: number, count: number): void;
+
+  /**
+   * Destroy native resources.
+   */
+  destroy(): void;
+}
diff --git a/packages/core/src/renderingHardwareInterface/index.ts b/packages/core/src/renderingHardwareInterface/index.ts
@@ -5,3 +5,4 @@ export type { IPlatformTexture2D } from "./IPlatformTexture2D";
 export type { IPlatformTexture2DArray } from "./IPlatformTexture2DArray";
 export type { IPlatformTextureCube } from "./IPlatformTextureCube";
 export type { IPlatformTransformFeedback } from "./IPlatformTransformFeedback";
+export type { IPlatformTransformFeedbackPrimitive } from "./IPlatformTransformFeedbackPrimitive";
diff --git a/packages/rhi-webgl/src/GLTransformFeedbackPrimitive.ts b/packages/rhi-webgl/src/GLTransformFeedbackPrimitive.ts
diff --git a/packages/rhi-webgl/src/WebGLGraphicDevice.ts b/packages/rhi-webgl/src/WebGLGraphicDevice.ts
