@es3d/es3d 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es3d/es3d",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "ES3D (Extensible Scalable 3D): a declarative, SVG-inspired 3D scene format with a WebGPU/WebGL2 reference renderer, editor and converter.",
   "type": "module",
   "license": "Apache-2.0",

package/src/render/geometry-pool.js

@@ -7,26 +7,93 @@
 // vertex. That keeps the WebGL2 and WebGPU paths the same.
 //
 // The pool is CPU-side; backends upload the ranges appended since their last
-// sync (or everything after a reallocation).
+// sync. The CPU copy is kept so a lost GPU context can be rebuilt.
+//
+// Growing and resetting are different events:
+// - Growing keeps every byte and adds room. The CPU side adds a chunk (old
+//   chunks are never copied), and backends grow their buffers with a GPU-side
+//   copy of what they already hold, then upload only what is new. Vertex and
+//   index storage grow independently.
+// - Resetting (reset(), a repack) throws the content away. It bumps
+//   `generation`, and backends reallocate and upload from zero.
 
 export const VERTEX_FLOATS = 8; // position xyz, normal xyz, uv
 export const VERTEX_BYTES = VERTEX_FLOATS * 4;
 
+/**
+ * A growable typed array stored as chunks. Element `i` of the whole array is
+ * in the chunk whose `start <= i < start + length`. Growing appends a chunk
+ * and never moves existing data.
+ */
+class ChunkedArray {
+  constructor(Type, stride, capacity) {
+    this.Type = Type;
+    this.stride = stride; // array entries per element (8 floats per vertex, 1 per index)
+    this.chunks = [{ start: 0, length: capacity, data: new Type(capacity * stride) }];
+    this.capacity = capacity; // elements
+  }
+
+  /** Make room for `count` elements in total. Returns true when it grew. */
+  reserve(count) {
+    if (count <= this.capacity) return false;
+    let cap = Math.max(1, this.capacity); // a zero capacity would never double
+    while (cap < count) cap *= 2;
+    const length = cap - this.capacity;
+    this.chunks.push({ start: this.capacity, length, data: new this.Type(length * this.stride) });
+    this.capacity = cap;
+    return true;
+  }
+
+  /**
+   * Visit the parts of elements [start, end) chunk by chunk:
+   * fn(firstElement, view), where view is the chunk's typed array restricted
+   * to that part.
+   */
+  forEach(start, end, fn) {
+    const s = this.stride;
+    for (const c of this.chunks) {
+      const a = Math.max(start, c.start);
+      const b = Math.min(end, c.start + c.length);
+      if (a < b) fn(a, c.data.subarray((a - c.start) * s, (b - c.start) * s));
+    }
+  }
+}
+
 export class GeometryPool {
   constructor(vertexCapacity = 1 << 16, indexCapacity = 1 << 17) {
-    this.vertices = new Float32Array(vertexCapacity * VERTEX_FLOATS);
-    this.indices = new Uint32Array(indexCapacity);
+    this.vertexStore = new ChunkedArray(Float32Array, VERTEX_FLOATS, vertexCapacity);
+    this.indexStore = new ChunkedArray(Uint32Array, 1, indexCapacity);
     this.vertexCount = 0;
     this.indexCount = 0;
     this.ranges = new Map(); // key object -> {firstIndex, indexCount}
     this.edgeRanges = new Map();
     this.normalRanges = new Map();
     // dirty tracking for incremental uploads
-    this.generation = 0; // bumps on reallocation
+    this.generation = 0; // bumps when the content is thrown away (reset, repack); NOT on growth
     this.uploadedVertices = 0;
     this.uploadedIndices = 0;
   }
 
+  /** Vertex capacity in vertices. Backends size their vertex buffer to at least this. */
+  get vertexCapacity() {
+    return this.vertexStore.capacity;
+  }
+
+  /** Index capacity in indices. */
+  get indexCapacity() {
+    return this.indexStore.capacity;
+  }
+
+  /** Capacity in bytes of the vertex storage. */
+  get vertexCapacityBytes() {
+    return this.vertexStore.capacity * VERTEX_BYTES;
+  }
+
+  /** Capacity in bytes of the index storage. */
+  get indexCapacityBytes() {
+    return this.indexStore.capacity * 4;
+  }
+
   reset() {
     this.vertexCount = 0;
     this.indexCount = 0;
@@ -42,60 +109,55 @@ export class GeometryPool {
     return this.vertexCount * VERTEX_BYTES + this.indexCount * 4;
   }
 
+  /** Make room for more vertices and indices. Growing keeps what is stored and uploaded. */
   ensure(extraV, extraI) {
-    let grew = false;
-    if ((this.vertexCount + extraV) * VERTEX_FLOATS > this.vertices.length) {
-      let cap = this.vertices.length / VERTEX_FLOATS;
-      while (cap < this.vertexCount + extraV) cap *= 2;
-      const v = new Float32Array(cap * VERTEX_FLOATS);
-      v.set(this.vertices.subarray(0, this.vertexCount * VERTEX_FLOATS));
-      this.vertices = v;
-      grew = true;
-    }
-    if (this.indexCount + extraI > this.indices.length) {
-      let cap = this.indices.length;
-      while (cap < this.indexCount + extraI) cap *= 2;
-      const i = new Uint32Array(cap);
-      i.set(this.indices.subarray(0, this.indexCount));
-      this.indices = i;
-      grew = true;
-    }
-    if (grew) {
-      this.generation++;
-      this.uploadedVertices = 0;
-      this.uploadedIndices = 0;
-    }
+    this.vertexStore.reserve(this.vertexCount + extraV);
+    this.indexStore.reserve(this.indexCount + extraI);
   }
 
   appendVertices(mesh) {
     const n = mesh.vertexCount;
     const base = this.vertexCount;
-    const v = this.vertices;
     const p = mesh.positions, nr = mesh.normals, t = mesh.uvs;
-    let o = base * VERTEX_FLOATS;
-    for (let i = 0; i < n; i++) {
-      v[o] = p[i * 3];
-      v[o + 1] = p[i * 3 + 1];
-      v[o + 2] = p[i * 3 + 2];
-      v[o + 3] = nr[i * 3];
-      v[o + 4] = nr[i * 3 + 1];
-      v[o + 5] = nr[i * 3 + 2];
-      v[o + 6] = t[i * 2];
-      v[o + 7] = t[i * 2 + 1];
-      o += VERTEX_FLOATS;
-    }
+    this.vertexStore.forEach(base, base + n, (first, v) => {
+      const count = v.length / VERTEX_FLOATS;
+      let o = 0;
+      for (let i = first - base, end = i + count; i < end; i++) {
+        v[o] = p[i * 3];
+        v[o + 1] = p[i * 3 + 1];
+        v[o + 2] = p[i * 3 + 2];
+        v[o + 3] = nr[i * 3];
+        v[o + 4] = nr[i * 3 + 1];
+        v[o + 5] = nr[i * 3 + 2];
+        v[o + 6] = t[i * 2];
+        v[o + 7] = t[i * 2 + 1];
+        o += VERTEX_FLOATS;
+      }
+    });
     this.vertexCount += n;
     return base;
   }
 
   appendIndices(src, base) {
     const first = this.indexCount;
-    const dst = this.indices;
-    for (let i = 0; i < src.length; i++) dst[first + i] = src[i] + base;
+    this.indexStore.forEach(first, first + src.length, (at, dst) => {
+      const off = at - first;
+      for (let i = 0; i < dst.length; i++) dst[i] = src[off + i] + base;
+    });
     this.indexCount += src.length;
     return first;
   }
 
+  /** Visit stored vertices [start, end) chunk by chunk: fn(firstVertex, Float32Array). */
+  forEachVertices(start, end, fn) {
+    this.vertexStore.forEach(start, end, fn);
+  }
+
+  /** Visit stored indices [start, end) chunk by chunk: fn(firstIndex, Uint32Array). */
+  forEachIndices(start, end, fn) {
+    this.indexStore.forEach(start, end, fn);
+  }
+
   /** Range of a mesh's primitives (triangles or lines). */
   meshRange(mesh) {
     let r = this.ranges.get(mesh);

package/src/render/webgl2/webgl2-backend.js

@@ -171,12 +171,8 @@ export class WebGL2Backend {
     this.vao = gl.createVertexArray();
     gl.bindVertexArray(this.vao);
     gl.bindBuffer(gl.ARRAY_BUFFER, this.vertexBuffer);
-    gl.enableVertexAttribArray(0);
-    gl.vertexAttribPointer(0, 3, gl.FLOAT, false, VERTEX_BYTES, 0);
-    gl.enableVertexAttribArray(1);
-    gl.vertexAttribPointer(1, 3, gl.FLOAT, false, VERTEX_BYTES, 12);
-    gl.enableVertexAttribArray(2);
-    gl.vertexAttribPointer(2, 2, gl.FLOAT, false, VERTEX_BYTES, 24);
+    for (let k = 0; k < 3; k++) gl.enableVertexAttribArray(k);
+    this.bindVertexAttributes();
     gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
     for (let k = 0; k < 4; k++) {
       gl.enableVertexAttribArray(3 + k);
@@ -215,14 +211,28 @@ export class WebGL2Backend {
     this.gl.deleteTexture(t);
   }
 
-  /** Upload geometry appended to the pool since the last sync. */
+  /** Point the VAO's vertex attributes at the vertex buffer bound to ARRAY_BUFFER. */
+  bindVertexAttributes() {
+    const gl = this.gl;
+    gl.vertexAttribPointer(0, 3, gl.FLOAT, false, VERTEX_BYTES, 0);
+    gl.vertexAttribPointer(1, 3, gl.FLOAT, false, VERTEX_BYTES, 12);
+    gl.vertexAttribPointer(2, 2, gl.FLOAT, false, VERTEX_BYTES, 24);
+  }
+
+  /**
+   * Upload geometry appended to the pool since the last sync.
+   *
+   * A new pool generation (reset, repack, rebuilt context) reallocates both
+   * buffers and uploads everything. A pool that only grew keeps its content:
+   * the buffer that ran out of room is replaced by a larger one, the bytes
+   * already uploaded are copied on the GPU, and only new data is sent.
+   */
   syncPool(pool) {
     const gl = this.gl;
-    const vBytes = pool.vertices.byteLength;
-    const iBytes = pool.indices.byteLength;
-    const realloc = pool.generation !== this.poolGeneration || vBytes !== this.vertexCapacity || iBytes !== this.indexCapacity;
+    const vBytes = pool.vertexCapacityBytes;
+    const iBytes = pool.indexCapacityBytes;
     let uploaded = 0;
-    if (realloc) {
+    if (pool.generation !== this.poolGeneration) {
       gl.bindBuffer(gl.ARRAY_BUFFER, this.vertexBuffer);
       gl.bufferData(gl.ARRAY_BUFFER, vBytes, gl.STATIC_DRAW);
       gl.bindVertexArray(this.vao);
@@ -234,25 +244,67 @@ export class WebGL2Backend {
       this.poolGeneration = pool.generation;
       pool.uploadedVertices = 0;
       pool.uploadedIndices = 0;
+    } else {
+      if (vBytes > this.vertexCapacity) {
+        const old = this.vertexBuffer;
+        const next = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, next);
+        gl.bufferData(gl.ARRAY_BUFFER, vBytes, gl.STATIC_DRAW);
+        gl.bindVertexArray(this.vao);
+        this.bindVertexAttributes();
+        gl.bindVertexArray(null);
+        this.copyBuffer(old, next, pool.uploadedVertices * VERTEX_BYTES);
+        gl.deleteBuffer(old);
+        this.vertexBuffer = next;
+        this.vertexCapacity = vBytes;
+      }
+      if (iBytes > this.indexCapacity) {
+        // An index buffer must first be bound as ELEMENT_ARRAY_BUFFER (WebGL2
+        // types buffers on first bind); bind it through the VAO, which keeps it.
+        const old = this.indexBuffer;
+        const next = gl.createBuffer();
+        gl.bindVertexArray(this.vao);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, next);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, iBytes, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+        this.copyBuffer(old, next, pool.uploadedIndices * 4);
+        gl.deleteBuffer(old);
+        this.indexBuffer = next;
+        this.indexCapacity = iBytes;
+      }
     }
     const p = pool.pending();
     if (p.vertexEnd > p.vertexStart) {
       gl.bindBuffer(gl.ARRAY_BUFFER, this.vertexBuffer);
-      const f = 8;
-      gl.bufferSubData(gl.ARRAY_BUFFER, p.vertexStart * VERTEX_BYTES, pool.vertices.subarray(p.vertexStart * f, p.vertexEnd * f));
-      uploaded += (p.vertexEnd - p.vertexStart) * VERTEX_BYTES;
+      pool.forEachVertices(p.vertexStart, p.vertexEnd, (first, data) => {
+        gl.bufferSubData(gl.ARRAY_BUFFER, first * VERTEX_BYTES, data);
+        uploaded += data.byteLength;
+      });
     }
     if (p.indexEnd > p.indexStart) {
       gl.bindVertexArray(this.vao);
       gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
-      gl.bufferSubData(gl.ELEMENT_ARRAY_BUFFER, p.indexStart * 4, pool.indices.subarray(p.indexStart, p.indexEnd));
+      pool.forEachIndices(p.indexStart, p.indexEnd, (first, data) => {
+        gl.bufferSubData(gl.ELEMENT_ARRAY_BUFFER, first * 4, data);
+        uploaded += data.byteLength;
+      });
       gl.bindVertexArray(null);
-      uploaded += (p.indexEnd - p.indexStart) * 4;
     }
     pool.markUploaded();
     return uploaded;
   }
 
+  /** Copy the first `bytes` of one buffer into another, on the GPU. */
+  copyBuffer(from, to, bytes) {
+    if (bytes <= 0) return;
+    const gl = this.gl;
+    gl.bindBuffer(gl.COPY_READ_BUFFER, from);
+    gl.bindBuffer(gl.COPY_WRITE_BUFFER, to);
+    gl.copyBufferSubData(gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, 0, 0, bytes);
+    gl.bindBuffer(gl.COPY_READ_BUFFER, null);
+    gl.bindBuffer(gl.COPY_WRITE_BUFFER, null);
+  }
+
   uploadInstances(data, count) {
     const gl = this.gl;
     const bytes = count * 64;

package/src/render/webgpu/webgpu-backend.js

@@ -254,30 +254,61 @@ export class WebGPUBackend {
     });
   }
 
+  /**
+   * Upload geometry appended to the pool since the last sync.
+   *
+   * A new pool generation (reset, repack) reallocates both buffers and uploads
+   * everything. A pool that only grew keeps its content: the buffer that ran
+   * out of room is replaced by a larger one, the bytes already uploaded are
+   * copied on the GPU, and only new data is sent.
+   */
   syncPool(pool) {
     const d = this.device;
-    const vBytes = pool.vertices.byteLength;
-    const iBytes = pool.indices.byteLength;
+    const vBytes = pool.vertexCapacityBytes;
+    const iBytes = pool.indexCapacityBytes;
+    const vUsage = GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+    const iUsage = GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
     let uploaded = 0;
-    if (pool.generation !== this.poolGeneration || !this.vertexBuffer || this.vertexBuffer.size < vBytes || this.indexBuffer.size < iBytes) {
+    if (pool.generation !== this.poolGeneration || !this.vertexBuffer) {
       if (this.vertexBuffer) this.vertexBuffer.destroy();
       if (this.indexBuffer) this.indexBuffer.destroy();
-      this.vertexBuffer = d.createBuffer({ size: pow2(vBytes, 1 << 16), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
-      this.indexBuffer = d.createBuffer({ size: pow2(iBytes, 1 << 16), usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST });
+      this.vertexBuffer = d.createBuffer({ size: pow2(vBytes, 1 << 16), usage: vUsage });
+      this.indexBuffer = d.createBuffer({ size: pow2(iBytes, 1 << 16), usage: iUsage });
       this.poolGeneration = pool.generation;
       pool.uploadedVertices = 0;
       pool.uploadedIndices = 0;
+    } else {
+      let encoder = null;
+      const grow = (old, bytes, usage, keep) => {
+        const next = d.createBuffer({ size: pow2(bytes, 1 << 16), usage });
+        if (keep > 0) {
+          encoder ||= d.createCommandEncoder();
+          encoder.copyBufferToBuffer(old, 0, next, 0, keep);
+        }
+        return next;
+      };
+      const oldV = this.vertexBuffer.size < vBytes ? this.vertexBuffer : null;
+      const oldI = this.indexBuffer.size < iBytes ? this.indexBuffer : null;
+      if (oldV) this.vertexBuffer = grow(oldV, vBytes, vUsage, pool.uploadedVertices * VERTEX_BYTES);
+      if (oldI) this.indexBuffer = grow(oldI, iBytes, iUsage, pool.uploadedIndices * 4);
+      // the copy is queued before the writes below, so the new data lands after it;
+      // destroying a buffer waits for submitted work that reads it
+      if (encoder) d.queue.submit([encoder.finish()]);
+      if (oldV) oldV.destroy();
+      if (oldI) oldI.destroy();
     }
     const p = pool.pending();
     if (p.vertexEnd > p.vertexStart) {
-      const src = pool.vertices.subarray(p.vertexStart * 8, p.vertexEnd * 8);
-      d.queue.writeBuffer(this.vertexBuffer, p.vertexStart * VERTEX_BYTES, src.buffer, src.byteOffset, src.byteLength);
-      uploaded += src.byteLength;
+      pool.forEachVertices(p.vertexStart, p.vertexEnd, (first, src) => {
+        d.queue.writeBuffer(this.vertexBuffer, first * VERTEX_BYTES, src.buffer, src.byteOffset, src.byteLength);
+        uploaded += src.byteLength;
+      });
     }
     if (p.indexEnd > p.indexStart) {
-      const src = pool.indices.subarray(p.indexStart, p.indexEnd);
-      d.queue.writeBuffer(this.indexBuffer, p.indexStart * 4, src.buffer, src.byteOffset, src.byteLength);
-      uploaded += src.byteLength;
+      pool.forEachIndices(p.indexStart, p.indexEnd, (first, src) => {
+        d.queue.writeBuffer(this.indexBuffer, first * 4, src.buffer, src.byteOffset, src.byteLength);
+        uploaded += src.byteLength;
+      });
     }
     pool.markUploaded();
     return uploaded;