@geastack/native-webgl-angle 0.1.11 → 0.1.13

package/src/inflate.ts

@@ -0,0 +1,252 @@
+// Raw DEFLATE (RFC 1951) decoder for data baked into a native binary -- glyph
+// atlases, an app's mesh blobs. Baked data ships as base64 string literals,
+// and compressing it first is what keeps a font or a model kit inside a
+// microcontroller's app partition: zlib's deflate packs a 512 KB alpha atlas to
+// ~40 KB and mesh blobs (flat shading triples every vertex) to a third.
+// Encoders are zlib's own (node:zlib deflateRawSync, Python zlib with wbits=-15).
+
+const lengthBase = new Uint16Array([3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258])
+const lengthExtra = new Uint8Array([0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0])
+const distanceBase = new Uint16Array([
+  1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385,
+  24577
+])
+const distanceExtra = new Uint8Array([0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13])
+const codeLengthOrder = new Uint8Array([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15])
+
+// The decoder is plain functions over locals and typed arrays, no class: a
+// native build narrows a function's integer locals to machine integers, but a
+// class's number fields stay doubles, and on a core without a double FPU (the
+// ESP32-S31) every bit read through a field was several soft-float calls --
+// inflating a game's asset kit at boot took over 80 seconds.
+
+/** Decoder state: read position, bit buffer, bits held, bytes written. */
+const position = 0
+const bitBuffer = 1
+const bitCount = 2
+const written = 3
+
+function bits(state: Int32Array, source: Uint8Array, count: number): number {
+  let buffer = state[bitBuffer]
+  let have = state[bitCount]
+  let at = state[position]
+  while (have < count) {
+    buffer |= source[at] << have
+    at += 1
+    have += 8
+  }
+  state[position] = at
+  state[bitBuffer] = buffer >>> count
+  state[bitCount] = have - count
+  return buffer & ((1 << count) - 1)
+}
+
+/**
+ * A canonical Huffman code as puff.c keeps it: `counts` (codes per length,
+ * 16 entries) and `symbols` (in code order) built from code lengths.
+ */
+function buildHuffman(counts: Uint16Array, symbols: Uint16Array, lengths: Uint8Array, start: number, count: number): void {
+  counts.fill(0)
+  for (let i = 0; i < count; i++) counts[lengths[start + i]] += 1
+  counts[0] = 0
+  const offsets = new Uint16Array(16)
+  for (let length = 1; length < 15; length++) offsets[length + 1] = offsets[length] + counts[length]
+  for (let i = 0; i < count; i++) {
+    const length = lengths[start + i]
+    if (length !== 0) {
+      symbols[offsets[length]] = i
+      offsets[length] += 1
+    }
+  }
+}
+
+function decode(state: Int32Array, source: Uint8Array, counts: Uint16Array, symbols: Uint16Array): number {
+  let code = 0
+  let first = 0
+  let index = 0
+  for (let length = 1; length < 16; length++) {
+    code |= bits(state, source, 1)
+    const count = counts[length]
+    if (code - first < count) return symbols[index + code - first]
+    index += count
+    first = (first + count) << 1
+    code <<= 1
+  }
+  throw new Error('inflate: invalid Huffman code')
+}
+
+function stored(state: Int32Array, source: Uint8Array, output: Uint8Array): void {
+  state[bitBuffer] = 0
+  state[bitCount] = 0
+  let at = state[position]
+  let out = state[written]
+  const length = source[at] | (source[at + 1] << 8)
+  at += 4
+  for (let i = 0; i < length; i++) {
+    output[out] = source[at]
+    out += 1
+    at += 1
+  }
+  state[position] = at
+  state[written] = out
+}
+
+function fixedCodes(literalCounts: Uint16Array, literals: Uint16Array, distanceCounts: Uint16Array, distances: Uint16Array): void {
+  const lengths = new Uint8Array(320)
+  for (let i = 0; i < 144; i++) lengths[i] = 8
+  for (let i = 144; i < 256; i++) lengths[i] = 9
+  for (let i = 256; i < 280; i++) lengths[i] = 7
+  for (let i = 280; i < 288; i++) lengths[i] = 8
+  for (let i = 288; i < 320; i++) lengths[i] = 5
+  buildHuffman(literalCounts, literals, lengths, 0, 288)
+  buildHuffman(distanceCounts, distances, lengths, 288, 30)
+}
+
+function dynamicCodes(
+  state: Int32Array,
+  source: Uint8Array,
+  literalCounts: Uint16Array,
+  literals: Uint16Array,
+  distanceCounts: Uint16Array,
+  distances: Uint16Array
+): void {
+  const literalCount = bits(state, source, 5) + 257
+  const distanceCount = bits(state, source, 5) + 1
+  const codeLengthCount = bits(state, source, 4) + 4
+  const lengths = new Uint8Array(320)
+  for (let i = 0; i < codeLengthCount; i++) lengths[codeLengthOrder[i]] = bits(state, source, 3)
+  buildHuffman(literalCounts, literals, lengths, 0, 19)
+  lengths.fill(0)
+  let index = 0
+  while (index < literalCount + distanceCount) {
+    const symbol = decode(state, source, literalCounts, literals)
+    if (symbol < 16) {
+      lengths[index] = symbol
+      index += 1
+      continue
+    }
+    let value = 0
+    let repeat = 0
+    if (symbol === 16) {
+      value = lengths[index - 1]
+      repeat = 3 + bits(state, source, 2)
+    } else if (symbol === 17) {
+      repeat = 3 + bits(state, source, 3)
+    } else {
+      repeat = 11 + bits(state, source, 7)
+    }
+    for (let i = 0; i < repeat; i++) {
+      lengths[index] = value
+      index += 1
+    }
+  }
+  buildHuffman(literalCounts, literals, lengths, 0, literalCount)
+  buildHuffman(distanceCounts, distances, lengths, literalCount, distanceCount)
+}
+
+function codes(
+  state: Int32Array,
+  source: Uint8Array,
+  output: Uint8Array,
+  literalCounts: Uint16Array,
+  literals: Uint16Array,
+  distanceCounts: Uint16Array,
+  distances: Uint16Array
+): void {
+  for (;;) {
+    const symbol = decode(state, source, literalCounts, literals)
+    if (symbol < 256) {
+      const out = state[written]
+      output[out] = symbol
+      state[written] = out + 1
+      continue
+    }
+    if (symbol === 256) return
+    const lengthSymbol = symbol - 257
+    const length = lengthBase[lengthSymbol] + bits(state, source, lengthExtra[lengthSymbol])
+    const distanceSymbol = decode(state, source, distanceCounts, distances)
+    const distance = distanceBase[distanceSymbol] + bits(state, source, distanceExtra[distanceSymbol])
+    // A match may overlap its own output, so it copies byte by byte.
+    let out = state[written]
+    let from = out - distance
+    for (let i = 0; i < length; i++) {
+      output[out] = output[from]
+      out += 1
+      from += 1
+    }
+    state[written] = out
+  }
+}
+
+/** Inflates a raw DEFLATE stream into exactly `length` bytes. */
+export function inflateRaw(source: Uint8Array, length: number): Uint8Array {
+  const output = new Uint8Array(length)
+  const state = new Int32Array(4)
+  const literalCounts = new Uint16Array(16)
+  const literals = new Uint16Array(288)
+  const distanceCounts = new Uint16Array(16)
+  const distances = new Uint16Array(288)
+  let last = 0
+  while (last === 0) {
+    last = bits(state, source, 1)
+    const type = bits(state, source, 2)
+    if (type === 0) stored(state, source, output)
+    else if (type === 1) {
+      fixedCodes(literalCounts, literals, distanceCounts, distances)
+      codes(state, source, output, literalCounts, literals, distanceCounts, distances)
+    } else if (type === 2) {
+      dynamicCodes(state, source, literalCounts, literals, distanceCounts, distances)
+      codes(state, source, output, literalCounts, literals, distanceCounts, distances)
+    } else throw new Error('inflate: invalid block type')
+  }
+  if (state[written] !== length) throw new Error('inflate: stream length does not match')
+  return output
+}
+
+function base64Value(code: number): number {
+  if (code >= 65 && code <= 90) return code - 65
+  if (code >= 97 && code <= 122) return code - 71
+  if (code >= 48 && code <= 57) return code + 4
+  if (code === 43) return 62
+  if (code === 47) return 63
+  return 0
+}
+
+/**
+ * The bytes base64 string chunks spell. Not atob: the native runtime stores
+ * strings as UTF-8, so atob's "binary string" would read bytes >= 0x80 back as
+ * Unicode through charCodeAt. Every chunk but the last is a multiple of 4.
+ */
+export function base64Bytes(chunks: string[]): Uint8Array {
+  let length = 0
+  for (let c = 0; c < chunks.length; c++) {
+    const chunk = chunks[c]
+    length += (chunk.length / 4) * 3
+    if (chunk.length > 0 && chunk.charCodeAt(chunk.length - 1) === 61) length -= 1
+    if (chunk.length > 1 && chunk.charCodeAt(chunk.length - 2) === 61) length -= 1
+  }
+  const bytes = new Uint8Array(length)
+  let out = 0
+  for (let c = 0; c < chunks.length; c++) {
+    const chunk = chunks[c]
+    for (let i = 0; i < chunk.length; i += 4) {
+      const code2 = chunk.charCodeAt(i + 2)
+      const code3 = chunk.charCodeAt(i + 3)
+      const v0 = base64Value(chunk.charCodeAt(i))
+      const v1 = base64Value(chunk.charCodeAt(i + 1))
+      const v2 = base64Value(code2)
+      const v3 = base64Value(code3)
+      bytes[out] = (v0 << 2) | (v1 >> 4)
+      out += 1
+      if (code2 !== 61) {
+        bytes[out] = ((v1 & 15) << 4) | (v2 >> 2)
+        out += 1
+      }
+      if (code3 !== 61) {
+        bytes[out] = ((v2 & 3) << 6) | v3
+        out += 1
+      }
+    }
+  }
+  return bytes
+}

package/src/nativeWebGL.ts

@@ -1,3 +1,7 @@
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLCopyTexImage2D(target:number,level:number,internalFormat:number,x:number,y:number,width:number,height:number,border:number):void;
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLCopyTexSubImage2D(target:number,level:number,xoffset:number,yoffset:number,x:number,y:number,width:number,height:number):void;
 /// <reference path="./gea-native-types.d.ts" />
 
 import {
@@ -91,6 +95,7 @@ type NativeHandleKind =
   | 'program'
   | 'renderbuffer'
   | 'shader'
+  | 'sync'
   | 'texture'
   | 'uniform'
   | 'vertexArray'
@@ -198,6 +203,27 @@ function typedArrayKind(value: BufferSourceLike): number {
   return 1
 }
 
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLBlitFramebuffer(sx0:number, sy0:number, sx1:number, sy1:number, dx0:number, dy0:number, dx1:number, dy1:number, mask:number, filter:number): void
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLRenderbufferStorageMultisample(target:number, samples:number, format:number, width:number, height:number): void
+type ReadPixelsDestination = Uint8Array | Uint16Array | Float32Array | Uint32Array | Int32Array | Int16Array | Int8Array
+// Mutates the destination view; deliberately not marked host-inert.
+/** @gea-host-typed-array-element-writes Stores pixels into the destination typed array's elements only; no other property of any object, no callbacks. */
+declare function threeWebGLReadPixels(x: number, y: number, width: number, height: number, format: number, type: number, destination: ReadPixelsDestination, offset: number): void
+// WebGL2 asynchronous readback: into the bound PIXEL_PACK_BUFFER, fenced, then read through getBufferSubData.
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLReadPixelsPack(x: number, y: number, width: number, height: number, format: number, type: number, offset: number): void
+/** @gea-host-inert Creates a GL sync object; never calls back into script. */
+declare function threeWebGLFenceSync(): number
+/** @gea-host-inert Reads scalar arguments, waits on GL state only; never calls back into script. */
+declare function threeWebGLClientWaitSync(sync: number, flags: number, timeout: number): number
+/** @gea-host-inert Reads scalar arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLDeleteSync(sync: number): void
+// Mutates the destination view; deliberately not marked host-inert.
+/** @gea-host-typed-array-element-writes Stores buffer bytes into the destination typed array's elements only; no other property of any object, no callbacks. */
+declare function threeWebGLGetBufferSubData(target: number, srcByteOffset: number, destination: ReadPixelsDestination, dstOffset: number, length: number): void
+
 function zeroF32Array(length: number): f32[] {
   const out: f32[] = []
   for (let index = 0; index < length; index++) out.push(0 as f32)
@@ -246,6 +272,14 @@ declare function threeWebGLTexImage2D(target: number, level: number, internalFor
 declare function threeWebGLTexSubImage2D(target: number, level: number, xoffset: number, yoffset: number, width: number, height: number, format: number, type: number, values: BufferSourceLike): void
 /** @gea-host-inert Reads its arguments, writes GL state only; never calls back into script. */
 declare function threeWebGLTexStorage2D(target: number, levels: number, internalFormat: number, width: number, height: number): void
+/** @gea-host-inert Reads its arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLTexImage3D(target: number, level: number, internalFormat: number, width: number, height: number, depth: number, format: number, type: number, values: BufferSourceLike): void
+/** @gea-host-inert Reads its arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLTexSubImage3D(target: number, level: number, xoffset: number, yoffset: number, zoffset: number, width: number, height: number, depth: number, format: number, type: number, values: BufferSourceLike): void
+/** @gea-host-inert Reads its arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLTexStorage3D(target: number, levels: number, internalFormat: number, width: number, height: number, depth: number): void
+/** @gea-host-inert Reads its arguments, writes GL state only; never calls back into script. */
+declare function threeWebGLFramebufferTextureLayer(target: number, attachment: number, texture: number, level: number, layer: number): void
 
 // Shader source keyed by the stable native GL handle. A NativeShader instance
 // can be value-copied when it round-trips through a function-return / gcv
@@ -303,6 +337,9 @@ export interface NativeWebGLContextAttributes {
   failIfMajorPerformanceCaveat: boolean
 }
 
+// Decoded image boundary. A native host never pretends DOM images have pixels.
+export interface NativeTextureImage { width: number; height: number; data: BufferSourceLike }
+
 export class NativeWebGLCanvas {
   width: number
   height: number
@@ -652,6 +689,10 @@ export class NativeWebGL2RenderingContext {
   readonly TIMEOUT_EXPIRED = 0x911B
   readonly CONDITION_SATISFIED = 0x911C
   readonly WAIT_FAILED = 0x911D
+  readonly SYNC_GPU_COMMANDS_COMPLETE = 0x9117
+  readonly PIXEL_PACK_BUFFER = 0x88EB
+  readonly PIXEL_PACK_BUFFER_BINDING = 0x88ED
+  readonly STREAM_READ = 0x88E1
   readonly COLOR = 0x1800
   readonly DEPTH_COMPONENT = 0x1902
   readonly ALPHA = 0x1906
@@ -924,11 +965,14 @@ export class NativeWebGL2RenderingContext {
     if (name === this.MAX_RENDERBUFFER_SIZE || name === this.MAX_3D_TEXTURE_SIZE) return 16384
     if (name === this.MAX_ARRAY_TEXTURE_LAYERS) return 2048
     if (name === this.MAX_VERTEX_ATTRIBS) return 16
-    if (name === this.MAX_TEXTURE_IMAGE_UNITS || name === this.MAX_VERTEX_TEXTURE_IMAGE_UNITS) return 16
+    // threejs-rendozer binds up to 32 textures per program (both stages); three checks a program's total against this.
+    if (name === this.MAX_TEXTURE_IMAGE_UNITS || name === this.MAX_VERTEX_TEXTURE_IMAGE_UNITS) return 32
     if (name === this.MAX_COMBINED_TEXTURE_IMAGE_UNITS) return 32
     if (name === this.MAX_VERTEX_UNIFORM_VECTORS || name === this.MAX_FRAGMENT_UNIFORM_VECTORS) return 1024
     if (name === this.MAX_VARYING_VECTORS) return 32
-    if (name === this.MAX_SAMPLES || name === this.SAMPLES) return 4
+    // threejs-rendozer reports 8 when every multisampled renderbuffer format supports it (and steps down per format).
+    if (name === this.MAX_SAMPLES) return 8
+    if (name === this.SAMPLES) return 4
     if (name === this.MAX_UNIFORM_BUFFER_BINDINGS) return 24
     if (name === this.DEPTH_BITS) return 24
     if (name === this.STENCIL_BITS) return 8
@@ -1092,9 +1136,13 @@ export class NativeWebGL2RenderingContext {
   texParameterf(target: number, pname: number, param: number): void { nativeWebGLTexParameteri(target, pname, param) }
   pixelStorei(pname: number, param: number | boolean): void { nativeWebGLPixelStorei(pname, param === true ? 1 : param === false ? 0 : param) }
   generateMipmap(target: number): void { nativeWebGLGenerateMipmap(target) }
-  texImage2D(target: number, level: number, internalFormat: number, widthOrFormat: number, heightOrType: number, borderOrSource?: number | TexImageSource | null, format?: number, type?: number, pixels?: BufferSourceLike | TexImageSource | null): void {
+  texImage2D(target: number, level: number, internalFormat: number, widthOrFormat: number, heightOrType: number, borderOrSource?: number | NativeTextureImage | null, format?: number, type?: number, pixels?: BufferSourceLike | null): void {
     if (typeof borderOrSource === 'number' && typeof format === 'number' && typeof type === 'number') {
-      threeWebGLTexImage2D(target, level, internalFormat, widthOrFormat, heightOrType, format, type, pixels as BufferSourceLike)
+      threeWebGLTexImage2D(target, level, internalFormat, widthOrFormat, heightOrType, format, type, pixels ?? new Uint8Array(0))
+    } else if (borderOrSource !== null && borderOrSource !== undefined && typeof borderOrSource !== 'number') {
+      threeWebGLTexImage2D(target, level, internalFormat, borderOrSource.width, borderOrSource.height, widthOrFormat, heightOrType, borderOrSource.data)
+    } else {
+      throw new Error(`Native texImage2D requires dimensions and typed pixels, or a decoded NativeTextureImage (target ${target}, level ${level}, internal format ${internalFormat}, source ${borderOrSource === null ? 'null' : typeof borderOrSource})`)
     }
   }
   texSubImage2D(target: number, level: number, xoffset: number, yoffset: number, width: number, height: number, format: number, type: number, pixels: BufferSourceLike): void {
@@ -1110,9 +1158,15 @@ export class NativeWebGL2RenderingContext {
   // Three uploads 3D and array textures only from typed `image.data` /
   // `mipmap.data` (or `null` to allocate), the same carrier the 2D uploads
   // take; no TexImageSource ever reaches these entry points.
-  texImage3D(_target: number, _level: number, _internalFormat: number, _width: number, _height: number, _depth: number, _border: number, _format: number, _type: number, _source: BufferSourceLike | null): void {}
-  texSubImage3D(_target: number, _level: number, _xoffset: number, _yoffset: number, _zoffset: number, _width: number, _height: number, _depth: number, _format: number, _type: number, _source: BufferSourceLike): void {}
-  texStorage3D(_target: number, _levels: number, _internalFormat: number, _width: number, _height: number, _depth: number): void {}
+  texImage3D(target: number, level: number, internalFormat: number, width: number, height: number, depth: number, _border: number, format: number, type: number, source: BufferSourceLike | null): void {
+    threeWebGLTexImage3D(target, level, internalFormat, width, height, depth, format, type, source ?? new Uint8Array(0))
+  }
+  texSubImage3D(target: number, level: number, xoffset: number, yoffset: number, zoffset: number, width: number, height: number, depth: number, format: number, type: number, source: BufferSourceLike): void {
+    threeWebGLTexSubImage3D(target, level, xoffset, yoffset, zoffset, width, height, depth, format, type, source)
+  }
+  texStorage3D(target: number, levels: number, internalFormat: number, width: number, height: number, depth: number): void {
+    threeWebGLTexStorage3D(target, levels, internalFormat, width, height, depth)
+  }
 
   createVertexArray(): NativeHandle { return createHandle('vertexArray', nativeWebGLCreateVertexArray()) }
   bindVertexArray(vertexArray: NativeHandle | null): void { nativeWebGLBindVertexArray(nullableNativeHandle(vertexArray)) }
@@ -1130,12 +1184,14 @@ export class NativeWebGL2RenderingContext {
   deleteRenderbuffer(renderbuffer: NativeHandle | null): void { nativeWebGLDeleteRenderbuffer(nullableNativeHandle(renderbuffer)) }
   renderbufferStorage(target: number, internalFormat: number, width: number, height: number): void { nativeWebGLRenderbufferStorage(target, internalFormat, width, height) }
   renderbufferStorageMultisample(target: number, samples: number, internalFormat: number, width: number, height: number): void {
-    this.renderbufferStorage(target, internalFormat, width, height)
+    threeWebGLRenderbufferStorageMultisample(target, samples, internalFormat, width, height)
   }
   framebufferRenderbuffer(target: number, attachment: number, renderbuffertarget: number, renderbuffer: NativeHandle | null): void {
     nativeWebGLFramebufferRenderbuffer(target, attachment, renderbuffertarget, nullableNativeHandle(renderbuffer))
   }
-  framebufferTextureLayer(_target: number, _attachment: number, _texture: NativeHandle | null, _level: number, _layer: number): void {}
+  framebufferTextureLayer(target: number, attachment: number, texture: NativeHandle | null, level: number, layer: number): void {
+    threeWebGLFramebufferTextureLayer(target, attachment, nullableNativeHandle(texture), level, layer)
+  }
   drawBuffers(buffers: number[]): void { nativeWebGLDrawBuffers(buffers[0] ?? this.COLOR_ATTACHMENT0) }
 
   clearColor(r: number, g: number, b: number, a: number): void { nativeWebGLClearColor(r, g, b, a) }
@@ -1176,16 +1232,26 @@ export class NativeWebGL2RenderingContext {
   flush(): void {}
   hint(_target: number, _mode: number): void {}
   invalidateFramebuffer(_target: number, _attachments: BufferSourceLike): void {}
-  blitFramebuffer(_srcX0: number, _srcY0: number, _srcX1: number, _srcY1: number, _dstX0: number, _dstY0: number, _dstX1: number, _dstY1: number, _mask: number, _filter: number): void {}
+  blitFramebuffer(sx0:number, sy0:number, sx1:number, sy1:number, dx0:number, dy0:number, dx1:number, dy1:number, mask:number, filter:number): void { threeWebGLBlitFramebuffer(sx0,sy0,sx1,sy1,dx0,dy0,dx1,dy1,mask,filter) }
   readBuffer(_src: number): void {}
-  readPixels(_x: number, _y: number, _width: number, _height: number, _format: number, _type: number, _destination: unknown): void {}
-  copyTexImage2D(_target: number, _level: number, _internalFormat: number, _x: number, _y: number, _width: number, _height: number, _border: number): void {}
-  copyTexSubImage2D(_target: number, _level: number, _xoffset: number, _yoffset: number, _x: number, _y: number, _width: number, _height: number): void {}
+  // WebGL2 also reads into the bound PIXEL_PACK_BUFFER at a byte offset (three's
+  // readRenderTargetPixelsAsync): the GPU copy is recorded without waiting for the GPU.
+  readPixels(x: number, y: number, width: number, height: number, format: number, type: number, destination: ReadPixelsDestination | number, offset = 0): void {
+    if (typeof destination === 'number') {
+      threeWebGLReadPixelsPack(x, y, width, height, format, type, destination)
+      return
+    }
+    threeWebGLReadPixels(x, y, width, height, format, type, destination, offset)
+  }
+  copyTexImage2D(target: number, level: number, internalFormat: number, x: number, y: number, width: number, height: number, border: number): void {threeWebGLCopyTexImage2D(target,level,internalFormat,x,y,width,height,border);}
+  copyTexSubImage2D(target: number, level: number, xoffset: number, yoffset: number, x: number, y: number, width: number, height: number): void {threeWebGLCopyTexSubImage2D(target,level,xoffset,yoffset,x,y,width,height);}
   copyTexSubImage3D(_target: number, _level: number, _xoffset: number, _yoffset: number, _zoffset: number, _x: number, _y: number, _width: number, _height: number): void {}
   clearBufferiv(_buffer: number, _drawbuffer: number, _values: BufferSourceLike): void {}
   clearBufferuiv(_buffer: number, _drawbuffer: number, _values: BufferSourceLike): void {}
   getBufferParameter(_target: number, _pname: number): number { return 0 }
-  getBufferSubData(_target: number, _srcByteOffset: number, _destination: unknown): void {}
+  getBufferSubData(target: number, srcByteOffset: number, destination: ReadPixelsDestination, dstOffset = 0, length = 0): void {
+    threeWebGLGetBufferSubData(target, srcByteOffset, destination, dstOffset, length)
+  }
   getFramebufferAttachmentParameter(_target: number, _attachment: number, _pname: number): number { return 0 }
   getRenderbufferParameter(_target: number, _pname: number): number { return 0 }
   getTexParameter(_target: number, _pname: number): number { return 0 }
@@ -1196,9 +1262,14 @@ export class NativeWebGL2RenderingContext {
   uniformBlockBinding(_program: NativeProgram | null, _uniformBlockIndex: number, _uniformBlockBinding: number): void {}
   bindBufferBase(_target: number, _index: number, _buffer: NativeHandle | null): void {}
   bindBufferRange(_target: number, _index: number, _buffer: NativeHandle | null, _offset: number, _size: number): void {}
-  fenceSync(_condition: number, _flags: number): null { return null }
-  clientWaitSync(_sync: NativeHandle | null, _flags: number, _timeout: number): number { return 0 }
-  deleteSync(_sync: NativeHandle | null): void {}
+  fenceSync(_condition: number, _flags: number): NativeHandle | null {
+    const sync = threeWebGLFenceSync()
+    return sync ? createHandle('sync', sync) : null
+  }
+  clientWaitSync(sync: NativeHandle | null, flags: number, timeout: number): number {
+    return sync ? threeWebGLClientWaitSync(nativeHandle(sync), flags, timeout) : this.WAIT_FAILED
+  }
+  deleteSync(sync: NativeHandle | null): void { if (sync) threeWebGLDeleteSync(nativeHandle(sync)) }
   isBuffer(_buffer: NativeHandle | null): boolean { return true }
   isFramebuffer(_framebuffer: NativeHandle | null): boolean { return true }
   isProgram(_program: NativeProgram | null): boolean { return true }

package/src/nativeWebGLHost.ts

@@ -35,6 +35,25 @@ export function nativeWebGLSwap(): void {
   threeWebGLSwap()
 }
 
+// GPU time-elapsed timers (GL_EXT_disjoint_timer_query): begin returns a timer id (0 when
+// unsupported), end closes the open timer, and result is the elapsed nanoseconds, or -1 while the
+// GPU has not finished it. A timer is released once its result has been read.
+export function nativeWebGLTimerBegin(): number {
+  return threeWebGLTimerBegin()
+}
+export function nativeWebGLTimerEnd(): void {
+  threeWebGLTimerEnd()
+}
+export function nativeWebGLTimerResult(timer: number): number {
+  return threeWebGLTimerResult(timer)
+}
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLTimerBegin(): number
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLTimerEnd(): void
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLTimerResult(timer: number): number
+
 export function logNativeWebGL(message: string): void {
   threeAngleSmokeLog(message)
 }
@@ -148,9 +167,16 @@ export function nativeWebGLDrawElements(mode: number, count: number, type: numbe
 export function nativeWebGLDrawArrays(mode: number, first: number, count: number): void { threeWebGLDrawArrays(mode, first, count) }
 export function nativeWebGLGetError(): number { return threeWebGLGetError() }
 
-/** Lifecycle entry: retains/uses the host view and installs native monitors; not an inert call. */
+/**
+ * Lifecycle entry: retains/uses the host view and installs native monitors; not an inert call.
+ * It writes no property on any script object, which is the narrower contract.
+ * @gea-host-no-property-writes
+ */
 declare function threeWebGLAttach(view: NSView, width: number, height: number, devicePixelRatio: number): boolean
-/** Lifecycle entry: synchronizes host layout and viewport state; keep outside the inert contract. */
+/**
+ * Lifecycle entry: synchronizes host layout and viewport state; keep outside the inert contract.
+ * @gea-host-no-property-writes
+ */
 declare function threeWebGLSyncSize(fallbackAspect: number): number
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLWidth(): number