@geastack/native-webgl-angle 0.1.11 → 0.1.12

package/geatsc-plugin-readback.mjs

@@ -0,0 +1,25 @@
+// Writable typed views must reach GLES in place. Upload snapshots are not valid
+// here: copying into a temporary would discard readPixels' observable result.
+export const nativeReadbackFunctions = [[
+  'threeWebGLReadPixels', 'gea_three_webgl_read_pixels_native', 'void', `
+#include <variant>
+extern "C" void gea_three_webgl_read_pixels_bytes(double x, double y, double width, double height,
+  double format, double type, void* bytes, double byteLength, double elementType);
+template <typename T> inline void gea_three_webgl_read_pixels_native(double x, double y, double width, double height,
+  double format, double type, const gea::Ref<gea::TypedArray<T>>& destination, double offset) {
+  constexpr int elementType = std::is_same_v<T, float> ? 0x1406 : std::is_same_v<T, std::uint16_t> ? 0x1403 :
+    std::is_same_v<T, std::uint8_t> ? 0x1401 : std::is_same_v<T, std::uint32_t> ? 0x1405 :
+    std::is_same_v<T, std::int32_t> ? 0x1404 : std::is_same_v<T, std::int16_t> ? 0x1402 : 0x1400;
+  if (!destination || !std::isfinite(offset) || offset < 0 || std::floor(offset) != offset || offset > destination->size()) {
+    gea_three_webgl_read_pixels_bytes(x,y,width,height,format,type,nullptr,-1,elementType); return;
+  }
+  const auto start = static_cast<std::size_t>(offset);
+  auto* data = destination->data();
+  gea_three_webgl_read_pixels_bytes(x,y,width,height,format,type,data ? data + start : nullptr,
+    static_cast<double>((destination->size()-start)*sizeof(T)), elementType);
+}
+template <typename... T> inline void gea_three_webgl_read_pixels_native(double x, double y, double width, double height,
+  double format, double type, const std::variant<T...>& destination, double offset) {
+  std::visit([&](const auto& view) { gea_three_webgl_read_pixels_native(x,y,width,height,format,type,view,offset); }, destination);
+}`
+]];

package/geatsc-plugin.mjs

@@ -3,6 +3,7 @@ import {
   transformCanonicalInstanceHooks,
 } from "./geatsc-plugin-instancing.mjs";
 import fs from "node:fs";
+import { nativeReadbackFunctions } from "./geatsc-plugin-readback.mjs";
 import { nativeUploadFunctions } from "./geatsc-plugin-uploads.mjs";
 import { fileURLToPath } from "node:url";
 
@@ -74,6 +75,8 @@ function nativeVoidMemberCallContract(
 }
 
 const hostFunctions = [
+ ['threeWebGLCopyTexImage2D','gea_three_webgl_copy_tex_image_2d','void','extern "C" void gea_three_webgl_copy_tex_image_2d(double,double,double,double,double,double,double,double);'],
+ ['threeWebGLCopyTexSubImage2D','gea_three_webgl_copy_tex_sub_image_2d','void','extern "C" void gea_three_webgl_copy_tex_sub_image_2d(double,double,double,double,double,double,double,double);'],
   [
     "threeWebGLVertexAttribDivisor",
     "gea_three_webgl_vertex_attrib_divisor",
@@ -93,6 +96,9 @@ const hostFunctions = [
     'extern "C" void gea_three_webgl_draw_arrays_instanced(double mode, double first, double count, double instanceCount);',
   ],
   ...nativeUploadFunctions,
+  ...nativeReadbackFunctions,
+  ['threeWebGLBlitFramebuffer','gea_three_webgl_blit_framebuffer','void','extern "C" void gea_three_webgl_blit_framebuffer(double,double,double,double,double,double,double,double,double,double);'],
+  ['threeWebGLRenderbufferStorageMultisample','gea_three_webgl_renderbuffer_storage_multisample','void','extern "C" void gea_three_webgl_renderbuffer_storage_multisample(double,double,double,double,double);'],
   [
     "threeNativeProfilePhase",
     "gea_three_native_profile_phase",
@@ -10468,7 +10474,7 @@ export default {
         embeddedHostNoThrowFunctions,
         hostNativeArrayFunctions: hostFunctions
           .filter(([, , , declaration]) =>
-            declaration.includes("HostNumericArgument<"),
+            declaration.includes("HostNumericArgument<") || declaration.includes("void* bytes"),
           )
           .map(([, cppName]) => cppName),
         hostArraySnapshotFunctions: hostFunctions

package/native/angle_webgl_host.mm

@@ -1,8 +1,12 @@
+#include "webgl_readback.h"
 #if defined(_WIN32)
 #ifndef NOMINMAX
 #define NOMINMAX
 #endif
 #include <windows.h>
+// Legacy Win16 macros are not C++ identifiers and must not leak into the runtime.
+#undef near
+#undef far
 #else
 #include "gea/apple/native_bridge.h"
 
@@ -439,7 +443,15 @@ using PFNGLVERTEXATTRIBDIVISORPROC = void (*)(GLuint, GLuint);
 using PFNGLVERTEXATTRIBPOINTERPROC = void (*)(GLuint, GLint, GLenum, GLboolean, GLsizei, const void *);
 using PFNGLVIEWPORTPROC = void (*)(GLint, GLint, GLsizei, GLsizei);
 
+using PFNGLCOPYTEXIMAGE2DPROC=void(*)(GLenum,GLint,GLenum,GLint,GLint,GLsizei,GLsizei,GLint);
+using PFNGLCOPYTEXSUBIMAGE2DPROC=void(*)(GLenum,GLint,GLint,GLint,GLint,GLint,GLsizei,GLsizei);
+using PFNGLBLITFRAMEBUFFERPROC = void (*)(GLint,GLint,GLint,GLint,GLint,GLint,GLint,GLint,GLbitfield,GLenum);
+using PFNGLRENDERBUFFERSTORAGEMULTISAMPLEPROC = void (*)(GLenum,GLsizei,GLenum,GLsizei,GLsizei);
 struct AngleWebGLState {
+  PFNGLCOPYTEXIMAGE2DPROC glCopyTexImage2D=nullptr;
+  PFNGLCOPYTEXSUBIMAGE2DPROC glCopyTexSubImage2D=nullptr;
+  PFNGLBLITFRAMEBUFFERPROC glBlitFramebuffer = nullptr;
+  PFNGLRENDERBUFFERSTORAGEMULTISAMPLEPROC glRenderbufferStorageMultisample = nullptr;
   void *egl = nullptr;
   void *gles = nullptr;
   EGLDisplay display = EGL_NO_DISPLAY;
@@ -580,6 +592,7 @@ struct AngleWebGLState {
 };
 
 static AngleWebGLState gWebGL;
+static GLenum hostReadbackError = 0;
 static std::chrono::steady_clock::time_point gProfileSizeSync;
 static bool gProfileSizeSyncPending = false;
 static bool nativeFrameProfileEnabled() {
@@ -1016,6 +1029,10 @@ static bool loadGlSymbols() {
   LOAD_GL(glPixelStorei, PFNGLPIXELSTOREIPROC)
   LOAD_GL(glPolygonOffset, PFNGLPOLYGONOFFSETPROC)
   LOAD_GL(glReadPixels, PFNGLREADPIXELSPROC)
+  LOAD_GL(glCopyTexImage2D,PFNGLCOPYTEXIMAGE2DPROC)
+  LOAD_GL(glCopyTexSubImage2D,PFNGLCOPYTEXSUBIMAGE2DPROC)
+  LOAD_GL(glBlitFramebuffer, PFNGLBLITFRAMEBUFFERPROC)
+  LOAD_GL(glRenderbufferStorageMultisample, PFNGLRENDERBUFFERSTORAGEMULTISAMPLEPROC)
   LOAD_GL(glRenderbufferStorage, PFNGLRENDERBUFFERSTORAGEPROC)
   LOAD_GL(glScissor, PFNGLSCISSORPROC)
   LOAD_GL(glShaderSource, PFNGLSHADERSOURCEPROC)
@@ -2259,7 +2276,7 @@ extern "C" void gea_three_webgl_draw_arrays_instanced(double mode, double first,
   geaTrapCheck("gea_three_webgl_draw_arrays_instanced"); GEA_WEBGL_VOID("drawArraysInstanced");
   gWebGL.glDrawArraysInstanced(asGLenum(mode), asGLint(first), asGLsizei(count), asGLsizei(instanceCount)); }
 extern "C" double gea_three_webgl_get_error() {
-  geaTrapCheck("gea_three_webgl_get_error"); GEA_WEBGL_DOUBLE("getError"); return gWebGL.glGetError(); }
+  geaTrapCheck("gea_three_webgl_get_error"); GEA_WEBGL_DOUBLE("getError"); if (hostReadbackError) { const GLenum e = hostReadbackError; hostReadbackError = 0; return e; } return gWebGL.glGetError(); }
 
 extern "C" double gea_three_webgl_call(
   double opValue,
@@ -2771,3 +2788,35 @@ extern "C" double gea_three_webgl_call_f32(
   }
   return 0.0;
 }
+
+extern "C" void gea_three_webgl_read_pixels_bytes(double x, double y, double width, double height,
+    double format, double type, void* bytes, double byteLength, double elementType) {
+  GEA_WEBGL_VOID("readPixels");
+  GLint alignment = 4, rowLength = 0, skipRows = 0, skipPixels = 0, packBuffer = 0;
+  gWebGL.glGetIntegerv(0x0D05, &alignment);
+  gWebGL.glGetIntegerv(0x0D02, &rowLength);
+  gWebGL.glGetIntegerv(0x0D03, &skipRows);
+  gWebGL.glGetIntegerv(0x0D04, &skipPixels);
+  gWebGL.glGetIntegerv(0x88ED, &packBuffer);
+  GLenum error = gea_webgl::validateReadPixels(width,height,format,type,byteLength,elementType,alignment,rowLength,skipRows,skipPixels);
+  if (packBuffer || (!bytes && width > 0 && height > 0)) error = 0x0502;
+  if (!std::isfinite(x) || !std::isfinite(y) || x < INT32_MIN || x > INT32_MAX || y < INT32_MIN || y > INT32_MAX) error = 0x0501;
+  if (error) { if (!hostReadbackError) hostReadbackError = error; return; }
+  gWebGL.glReadPixels(asGLint(x),asGLint(y),asGLsizei(width),asGLsizei(height),asGLenum(format),asGLenum(type),bytes);
+}
+
+extern "C" void gea_three_webgl_blit_framebuffer(double sx0,double sy0,double sx1,double sy1,double dx0,double dy0,double dx1,double dy1,double mask,double filter) {
+  GEA_WEBGL_VOID("blitFramebuffer");
+  gWebGL.glBlitFramebuffer(asGLint(sx0),asGLint(sy0),asGLint(sx1),asGLint(sy1),asGLint(dx0),asGLint(dy0),asGLint(dx1),asGLint(dy1),asGLenum(mask),asGLenum(filter));
+}
+extern "C" void gea_three_webgl_renderbuffer_storage_multisample(double target,double samples,double format,double width,double height) {
+  GEA_WEBGL_VOID("renderbufferStorageMultisample");
+  gWebGL.glRenderbufferStorageMultisample(asGLenum(target),asGLsizei(samples),asGLenum(format),asGLsizei(width),asGLsizei(height));
+}
+
+extern "C" void gea_three_webgl_copy_tex_image_2d(double target,double level,double format,double x,double y,double w,double h,double border){
+ GEA_WEBGL_VOID("copyTexImage2D");gWebGL.glCopyTexImage2D(asGLenum(target),asGLint(level),asGLenum(format),asGLint(x),asGLint(y),asGLsizei(w),asGLsizei(h),asGLint(border));
+}
+extern "C" void gea_three_webgl_copy_tex_sub_image_2d(double target,double level,double xo,double yo,double x,double y,double w,double h){
+ GEA_WEBGL_VOID("copyTexSubImage2D");gWebGL.glCopyTexSubImage2D(asGLenum(target),asGLint(level),asGLint(xo),asGLint(yo),asGLint(x),asGLint(y),asGLsizei(w),asGLsizei(h));
+}

package/native/webgl_readback.h

@@ -0,0 +1,29 @@
+#pragma once
+#include <cmath>
+#include <cstdint>
+#include <limits>
+
+namespace gea_webgl {
+// Calculate the complete destination window, including WebGL2 pack layout.
+// Return a GL error before the driver can touch an undersized typed array.
+inline unsigned validateReadPixels(double width, double height, double format, double type,
+    double bytes, double elementType, int alignment, int rowLength, int skipRows, int skipPixels) {
+  if (!std::isfinite(width) || !std::isfinite(height) || width < 0 || height < 0 ||
+      width > INT32_MAX || height > INT32_MAX || std::floor(width) != width || std::floor(height) != height) return 0x0501;
+  if (format != 0x1908 || (type != 0x1401 && type != 0x1406 && type != 0x140B)) return 0x0502;
+  if (elementType != type && !(type == 0x140B && elementType == 0x1403)) return 0x0502;
+  if (bytes < 0 || !std::isfinite(bytes)) return 0x0501;
+  if (width == 0 || height == 0) return 0;
+  if (alignment != 1 && alignment != 2 && alignment != 4 && alignment != 8) return 0x0502;
+  if (rowLength < 0 || skipRows < 0 || skipPixels < 0) return 0x0502;
+  const uint64_t pixel = type == 0x1406 ? 16 : type == 0x140B ? 8 : 4;
+  const uint64_t row = rowLength ? rowLength : static_cast<uint64_t>(width);
+  if (row < static_cast<uint64_t>(width) + skipPixels) return 0x0502;
+  const uint64_t pitch = (row*pixel + alignment-1)/alignment*alignment;
+  const uint64_t rows = static_cast<uint64_t>(height)-1+skipRows;
+  if (rows && pitch > UINT64_MAX/rows) return 0x0502;
+  const uint64_t tail = (static_cast<uint64_t>(skipPixels)+static_cast<uint64_t>(width))*pixel;
+  if (rows*pitch > UINT64_MAX-tail) return 0x0502;
+  return static_cast<long double>(rows*pitch+tail) <= bytes ? 0 : 0x0502;
+}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {
@@ -20,6 +20,7 @@
     "./nativeThreeUtils": "./src/nativeThreeUtils.ts",
     "./nativeWebXRManager": "./src/nativeWebXRManager.ts",
     "./troika-three-text": "./src/troika-three-text.ts",
+    "./inflate": "./src/inflate.ts",
     "./geatsc-plugin": "./geatsc-plugin.mjs",
     "./native/*": "./native/*",
     "./package.json": "./package.json",
@@ -38,7 +39,8 @@
     "geatsc-plugin-instancing.mjs",
     "geatsc-plugin-batched-probe.mjs",
     "test/batched-render-scene.ts",
-    "test/auto-instanced-render-scene.ts"
+    "test/auto-instanced-render-scene.ts",
+    "geatsc-plugin-readback.mjs"
   ],
   "publishConfig": {
     "access": "public",
@@ -53,16 +55,16 @@
     "test:package": "node --experimental-vm-modules test/package.test.mjs"
   },
   "dependencies": {
-    "@geastack/apple": "^0.2.14"
+    "@geastack/apple": "^0.2.15"
   },
   "peerDependencies": {
     "three": "^0.185.0",
-    "@geastack/compiler": "^1.0.22"
+    "@geastack/compiler": "^1.0.29"
   },
   "devDependencies": {
-    "@geastack/compiler": "^1.0.22",
-    "@geastack/core": "^0.1.37",
-    "@geastack/engine": "^0.1.13",
+    "@geastack/compiler": "^1.0.29",
+    "@geastack/core": "^0.1.40",
+    "@geastack/engine": "^0.1.16",
     "@types/three": "^0.185.0",
     "three": "^0.185.0",
     "troika-three-text": "^0.52.4",

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 skytail's 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,5 @@
+declare function threeWebGLCopyTexImage2D(target:number,level:number,internalFormat:number,x:number,y:number,width:number,height:number,border:number):void;
+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 {
@@ -198,6 +200,12 @@ function typedArrayKind(value: BufferSourceLike): number {
   return 1
 }
 
+declare function threeWebGLBlitFramebuffer(sx0:number, sy0:number, sx1:number, sy1:number, dx0:number, dy0:number, dx1:number, dy1:number, mask:number, filter:number): void
+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.
+declare function threeWebGLReadPixels(x: number, y: number, width: number, height: number, format: number, type: number, destination: ReadPixelsDestination, offset: number): void
+
 function zeroF32Array(length: number): f32[] {
   const out: f32[] = []
   for (let index = 0; index < length; index++) out.push(0 as f32)
@@ -303,6 +311,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
@@ -1092,9 +1103,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 && 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')
     }
   }
   texSubImage2D(target: number, level: number, xoffset: number, yoffset: number, width: number, height: number, format: number, type: number, pixels: BufferSourceLike): void {
@@ -1130,7 +1145,7 @@ 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))
@@ -1176,11 +1191,13 @@ 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 {}
+  readPixels(x: number, y: number, width: number, height: number, format: number, type: number, destination: ReadPixelsDestination, offset = 0): void {
+    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 {}

package/src/nativeWebGLHost.ts

@@ -148,9 +148,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