@geastack/native-webgl-angle 0.1.12 → 0.1.13

package/native/angle_webgl_host.mm

@@ -1,4 +1,6 @@
 #include "webgl_readback.h"
+// GEA_WEBGL_STATIC_GLES: EGL/GLES are statically linked into the program, so
+// nothing is loaded and entry points resolve through eglGetProcAddress.
 #if defined(_WIN32)
 #ifndef NOMINMAX
 #define NOMINMAX
@@ -7,13 +9,14 @@
 // Legacy Win16 macros are not C++ identifiers and must not leak into the runtime.
 #undef near
 #undef far
-#else
+#elif defined(__APPLE__)
 #include "gea/apple/native_bridge.h"
 
 #import <AppKit/AppKit.h>
 #import <QuartzCore/QuartzCore.h>
 #import <dispatch/dispatch.h>
-
+#endif
+#if !defined(_WIN32) && !defined(GEA_WEBGL_STATIC_GLES)
 #include <dlfcn.h>
 #endif
 // Typed uniform arguments use the compiler runtime on both native platforms.
@@ -172,7 +175,7 @@ extern "C" bool gea_three_key_pressed(double code) {
   return gGeaKeyState[c];
 }
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
 // The Win32 window procedure owns input on Windows; it reports into the same
 // tables the AppKit host view fills on macOS (keys as macOS virtual key codes).
 extern "C" void gea_three_set_key_state(int code, bool down) {
@@ -189,7 +192,7 @@ extern "C" void gea_three_set_pointer_state(double x, double y, double width, do
 }
 #endif
 
-#if !defined(_WIN32)
+#if defined(__APPLE__)
 @interface GeaAngleWebGLHostView : NSView
 @end
 
@@ -410,6 +413,10 @@ using PFNGLTEXIMAGE2DPROC = void (*)(GLenum, GLint, GLint, GLsizei, GLsizei, GLi
 using PFNGLTEXPARAMETERFPROC = void (*)(GLenum, GLenum, GLfloat);
 using PFNGLTEXPARAMETERIPROC = void (*)(GLenum, GLenum, GLint);
 using PFNGLTEXSUBIMAGE2DPROC = void (*)(GLenum, GLint, GLint, GLint, GLsizei, GLsizei, GLenum, GLenum, const void *);
+using PFNGLTEXIMAGE3DPROC = void (*)(GLenum, GLint, GLint, GLsizei, GLsizei, GLsizei, GLint, GLenum, GLenum, const void *);
+using PFNGLTEXSUBIMAGE3DPROC = void (*)(GLenum, GLint, GLint, GLint, GLint, GLsizei, GLsizei, GLsizei, GLenum, GLenum, const void *);
+using PFNGLTEXSTORAGE3DPROC = void (*)(GLenum, GLsizei, GLenum, GLsizei, GLsizei, GLsizei);
+using PFNGLFRAMEBUFFERTEXTURELAYERPROC = void (*)(GLenum, GLenum, GLuint, GLint, GLint);
 using PFNGLTEXSTORAGE2DPROC = void (*)(GLenum, GLsizei, GLenum, GLsizei, GLsizei);
 using PFNGLUNIFORM1FPROC = void (*)(GLint, GLfloat);
 using PFNGLUNIFORM1FVPROC = void (*)(GLint, GLsizei, const GLfloat *);
@@ -447,6 +454,13 @@ using PFNGLCOPYTEXIMAGE2DPROC=void(*)(GLenum,GLint,GLenum,GLint,GLint,GLsizei,GL
 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);
+using GLuint64 = std::uint64_t;
+using GLsync = struct __GLsync *;
+using PFNGLMAPBUFFERRANGEPROC = void *(*)(GLenum, GLintptr, GLsizeiptr, GLbitfield);
+using PFNGLUNMAPBUFFERPROC = GLboolean (*)(GLenum);
+using PFNGLFENCESYNCPROC = GLsync (*)(GLenum, GLbitfield);
+using PFNGLCLIENTWAITSYNCPROC = GLenum (*)(GLsync, GLbitfield, GLuint64);
+using PFNGLDELETESYNCPROC = void (*)(GLsync);
 struct AngleWebGLState {
   PFNGLCOPYTEXIMAGE2DPROC glCopyTexImage2D=nullptr;
   PFNGLCOPYTEXSUBIMAGE2DPROC glCopyTexSubImage2D=nullptr;
@@ -533,6 +547,12 @@ struct AngleWebGLState {
   PFNGLPIXELSTOREIPROC glPixelStorei = nullptr;
   PFNGLPOLYGONOFFSETPROC glPolygonOffset = nullptr;
   PFNGLREADPIXELSPROC glReadPixels = nullptr;
+  // WebGL2 asynchronous readback: PIXEL_PACK_BUFFER reads, sync objects and read-mapping.
+  PFNGLMAPBUFFERRANGEPROC glMapBufferRange = nullptr;
+  PFNGLUNMAPBUFFERPROC glUnmapBuffer = nullptr;
+  PFNGLFENCESYNCPROC glFenceSync = nullptr;
+  PFNGLCLIENTWAITSYNCPROC glClientWaitSync = nullptr;
+  PFNGLDELETESYNCPROC glDeleteSync = nullptr;
   PFNGLRENDERBUFFERSTORAGEPROC glRenderbufferStorage = nullptr;
   PFNGLSCISSORPROC glScissor = nullptr;
   PFNGLSHADERSOURCEPROC glShaderSource = nullptr;
@@ -547,6 +567,12 @@ struct AngleWebGLState {
   PFNGLTEXPARAMETERIPROC glTexParameteri = nullptr;
   PFNGLTEXSUBIMAGE2DPROC glTexSubImage2D = nullptr;
   PFNGLTEXSTORAGE2DPROC glTexStorage2D = nullptr;
+  // Array/3D entry points are optional: a GLES without them still starts,
+  // and uploads to those targets report GL_INVALID_OPERATION in the log.
+  PFNGLTEXIMAGE3DPROC glTexImage3D = nullptr;
+  PFNGLTEXSUBIMAGE3DPROC glTexSubImage3D = nullptr;
+  PFNGLTEXSTORAGE3DPROC glTexStorage3D = nullptr;
+  PFNGLFRAMEBUFFERTEXTURELAYERPROC glFramebufferTextureLayer = nullptr;
   PFNGLUNIFORM1FPROC glUniform1f = nullptr;
   PFNGLUNIFORM1FVPROC glUniform1fv = nullptr;
   PFNGLUNIFORM1IPROC glUniform1i = nullptr;
@@ -579,7 +605,7 @@ struct AngleWebGLState {
   PFNGLVERTEXATTRIBPOINTERPROC glVertexAttribPointer = nullptr;
   PFNGLVIEWPORTPROC glViewport = nullptr;
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
   void *nativeWindow = nullptr;
 #else
   NSView *hostView = nil;
@@ -617,7 +643,7 @@ static bool nativeShadowColorAuditEnabled() {
 }
 
 static void smokeLog(const char *format, ...) {
-  char message[1024] = {};
+  char message[16384] = {};
   va_list args;
   va_start(args, format);
   std::vsnprintf(message, sizeof(message), format, args);
@@ -631,8 +657,13 @@ static void smokeLog(const char *format, ...) {
     std::fprintf(stderr, "%s\n", message);
     return;
   }
-#else
+#elif defined(__APPLE__)
   if (!path || path[0] == '\0') path = "/tmp/three-angle-metal-smoke.log";
+#else
+  if (!path || path[0] == '\0') {
+    std::fprintf(stderr, "%s\n", message);
+    return;
+  }
 #endif
   if (FILE *file = std::fopen(path, "a")) {
     std::fprintf(file, "%s\n", message);
@@ -653,7 +684,7 @@ extern "C" void gea_three_angle_smoke_log(std::string message) {
 // handler records the position in the host view's coordinate space with the
 // same top-left-origin flip the per-view path used. Returning the event
 // unmodified keeps normal dispatch (clicks, first responder) intact.
-#if !defined(_WIN32)
+#if defined(__APPLE__)
 static id gGeaPointerMonitor = nil;
 static void geaInstallPointerMonitor(void) {
   if (gGeaPointerMonitor) return;
@@ -696,9 +727,16 @@ static void *openFirst(const char *envName, const char *const *paths) {
 
 #endif
 
+#if defined(GEA_WEBGL_STATIC_GLES)
+extern "C" void *eglGetProcAddress(const char *name);
+#endif
 template <typename Fn>
 static Fn loadSymbol(void *library, const char *name) {
-#if defined(_WIN32)
+#if defined(GEA_WEBGL_STATIC_GLES)
+  (void)library;
+  if (std::strcmp(name, "eglGetProcAddress") == 0) return reinterpret_cast<Fn>(&eglGetProcAddress);
+  return reinterpret_cast<Fn>(eglGetProcAddress(name));
+#elif defined(_WIN32)
   return reinterpret_cast<Fn>(GetProcAddress(static_cast<HMODULE>(library), name));
 #else
   return reinterpret_cast<Fn>(dlsym(library, name));
@@ -797,7 +835,7 @@ static void logEglFailure(const char *step) {
   std::fprintf(stderr, "[three-angle-metal] %s failed, EGL error 0x%04x\n", step, lastEglError());
 }
 
-#if !defined(_WIN32)
+#if defined(__APPLE__)
 static CGFloat backingScaleForHostView(NSView *nativeView) {
   CGFloat scale = nativeView.window ? nativeView.window.backingScaleFactor : 0.0;
   if (scale <= 0.0 && nativeView.window.screen) scale = nativeView.window.screen.backingScaleFactor;
@@ -870,13 +908,13 @@ extern "C" void gea_three_webgl_update_size_uwp(double width, double height, dou
 }
 #endif
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
 // The UWP frame driver owns its EGL context exclusively until it returns to
 // CoreWindow event dispatch. Other hosts retain per-call binding semantics.
 static thread_local bool gUwpFrameContextCurrent = false;
 #endif
 static bool makeCurrent(const char *label) {
-#if defined(_WIN32)
+#if !defined(__APPLE__)
   if (gUwpFrameContextCurrent) return true;
 #endif
   if (!gWebGL.ready && gWebGL.context == EGL_NO_CONTEXT) return false;
@@ -907,7 +945,7 @@ static bool makeCurrent(const char *label) {
   return true;
 }
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
 extern "C" bool gea_three_webgl_begin_frame_uwp() {
   // Always rebind after the dispatcher, where arbitrary platform callbacks
   // may have used a different context. No such callbacks run within the frame.
@@ -921,7 +959,7 @@ extern "C" void gea_three_webgl_end_frame_uwp() {
 }
 #endif
 
-#if !defined(_WIN32)
+#if defined(__APPLE__)
 static bool rebuildWindowSurface(const char *label) {
   if (!gWebGL.eglCreateWindowSurface || !gWebGL.eglDestroySurface || !gWebGL.eglMakeCurrent ||
       !gWebGL.metalLayer || !gWebGL.config || gWebGL.context == EGL_NO_CONTEXT) {
@@ -1029,6 +1067,11 @@ static bool loadGlSymbols() {
   LOAD_GL(glPixelStorei, PFNGLPIXELSTOREIPROC)
   LOAD_GL(glPolygonOffset, PFNGLPOLYGONOFFSETPROC)
   LOAD_GL(glReadPixels, PFNGLREADPIXELSPROC)
+  LOAD_GL(glMapBufferRange, PFNGLMAPBUFFERRANGEPROC)
+  LOAD_GL(glUnmapBuffer, PFNGLUNMAPBUFFERPROC)
+  LOAD_GL(glFenceSync, PFNGLFENCESYNCPROC)
+  LOAD_GL(glClientWaitSync, PFNGLCLIENTWAITSYNCPROC)
+  LOAD_GL(glDeleteSync, PFNGLDELETESYNCPROC)
   LOAD_GL(glCopyTexImage2D,PFNGLCOPYTEXIMAGE2DPROC)
   LOAD_GL(glCopyTexSubImage2D,PFNGLCOPYTEXSUBIMAGE2DPROC)
   LOAD_GL(glBlitFramebuffer, PFNGLBLITFRAMEBUFFERPROC)
@@ -1047,6 +1090,10 @@ static bool loadGlSymbols() {
   LOAD_GL(glTexParameteri, PFNGLTEXPARAMETERIPROC)
   LOAD_GL(glTexSubImage2D, PFNGLTEXSUBIMAGE2DPROC)
   LOAD_GL(glTexStorage2D, PFNGLTEXSTORAGE2DPROC)
+  gWebGL.glTexImage3D = loadGl<PFNGLTEXIMAGE3DPROC>("glTexImage3D");
+  gWebGL.glTexSubImage3D = loadGl<PFNGLTEXSUBIMAGE3DPROC>("glTexSubImage3D");
+  gWebGL.glTexStorage3D = loadGl<PFNGLTEXSTORAGE3DPROC>("glTexStorage3D");
+  gWebGL.glFramebufferTextureLayer = loadGl<PFNGLFRAMEBUFFERTEXTURELAYERPROC>("glFramebufferTextureLayer");
   LOAD_GL(glUniform1f, PFNGLUNIFORM1FPROC)
   LOAD_GL(glUniform1fv, PFNGLUNIFORM1FVPROC)
   LOAD_GL(glUniform1i, PFNGLUNIFORM1IPROC)
@@ -1082,7 +1129,7 @@ static bool loadGlSymbols() {
   return true;
 }
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
 extern "C" bool gea_three_webgl_attach_uwp(
   void *nativeWindow,
 #else
@@ -1097,7 +1144,13 @@ extern "C" bool gea_three_webgl_attach(
   smokeLog("[three-angle-metal] WebGL host attach requested");
   if (gWebGL.ready) return true;
 
-#if defined(_WIN32)
+#if defined(GEA_WEBGL_STATIC_GLES)
+  // Linked into the program: nothing to load; loadSymbol resolves through
+  // eglGetProcAddress. The handles only need to be non-null.
+  static int staticGles;
+  gWebGL.egl = &staticGles;
+  gWebGL.gles = &staticGles;
+#elif defined(_WIN32)
   // An override (e.g. threejs-rendozer's GeaRendozerGLES.dll) first, then the
   // packaged ANGLE of a UWP app, then a plain desktop load next to the exe.
   auto openWin32 = [](const wchar_t *overrideEnv, const wchar_t *name) -> HMODULE {
@@ -1114,7 +1167,7 @@ extern "C" bool gea_three_webgl_attach(
   };
   gWebGL.egl = openWin32(L"GEA_ANGLE_EGL_DYLIB", L"libEGL.dll");
   gWebGL.gles = openWin32(L"GEA_ANGLE_GLES_DYLIB", L"libGLESv2.dll");
-#else
+#elif defined(__APPLE__)
   static const char *const eglPaths[] = {
     "/Applications/Visual Studio Code.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Libraries/libEGL.dylib",
     "/Applications/Cursor.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Libraries/libEGL.dylib",
@@ -1132,6 +1185,8 @@ extern "C" bool gea_three_webgl_attach(
 
   gWebGL.egl = openFirst("GEA_ANGLE_EGL_DYLIB", eglPaths);
   gWebGL.gles = openFirst("GEA_ANGLE_GLES_DYLIB", glesPaths);
+#else
+#error "load libEGL/libGLESv2 for this platform, or build with GEA_WEBGL_STATIC_GLES"
 #endif
   if (!gWebGL.egl || !gWebGL.gles) {
     smokeLog("[three-angle-metal] ANGLE libEGL/libGLESv2 were not found");
@@ -1209,7 +1264,7 @@ extern "C" bool gea_three_webgl_attach(
   }
   gWebGL.config = config;
 
-#if defined(_WIN32)
+#if !defined(__APPLE__)
   gWebGL.nativeWindow = nativeWindow;
   gea_three_webgl_update_size_uwp(width, height, devicePixelRatio);
   if (gWebGL.eglCreateWindowSurface) {
@@ -1275,7 +1330,7 @@ extern "C" bool gea_three_webgl_attach(
 
   gWebGL.ready = true;
   gWebGL.glViewport(0, 0, gWebGL.widthPx, gWebGL.heightPx);
-#if !defined(_WIN32)
+#if defined(__APPLE__)
   dispatch_async(dispatch_get_main_queue(), ^{
     if (gWebGL.ready && rebuildWindowSurface("eglCreateWindowSurface(deferred)")) {
       smokeLog("[three-angle-metal] WebGL EGL surface rebound at %dx%d", gWebGL.widthPx, gWebGL.heightPx);
@@ -1391,7 +1446,7 @@ extern "C" void gea_three_webgl_swap() {
   // TEMP-DIAG: GEA_THREE_VIEW_DUMP=1 — at frame 60, log the window's full
   // subview tree and a hit-test grid so overlay views that would swallow
   // mouse events are visible without Accessibility permission.
-#if !defined(_WIN32)
+#if defined(__APPLE__)
   if (std::getenv("GEA_THREE_VIEW_DUMP")) {
     static int viewDumpCount = 0;
     if (++viewDumpCount == 60) {
@@ -1424,6 +1479,16 @@ extern "C" void gea_three_webgl_swap() {
     }
   }
 #endif
+  // The debug dump and recording read the window into client memory. A PIXEL_PACK_BUFFER the app left
+  // bound (WebGL2 asynchronous readback) would make the pointer a buffer offset instead, so the read
+  // runs with it unbound and the binding is restored afterwards.
+  const auto readWindowRgba = [](int w, int h, unsigned char *rgba) {
+    GLint packBuffer = 0;
+    if (gWebGL.glGetIntegerv) gWebGL.glGetIntegerv(0x88ED /* PIXEL_PACK_BUFFER_BINDING */, &packBuffer);
+    if (packBuffer) gWebGL.glBindBuffer(0x88EB /* PIXEL_PACK_BUFFER */, 0);
+    gWebGL.glReadPixels(0, 0, w, h, GL_RGBA_VALUE, GL_UNSIGNED_BYTE, rgba);
+    if (packBuffer) gWebGL.glBindBuffer(0x88EB, static_cast<GLuint>(packBuffer));
+  };
   // Debug frame dump: GEA_WEBGL_DUMP_FRAME=<path-prefix> writes the full
   // framebuffer of frames 90/180/300 as PPM (P6) — visual ground truth for
   // native-vs-browser comparisons without needing a window screenshot.
@@ -1434,7 +1499,7 @@ extern "C" void gea_three_webgl_swap() {
       const int w = gWebGL.widthPx;
       const int h = gWebGL.heightPx;
       std::vector<unsigned char> rgba(static_cast<size_t>(w) * h * 4);
-      gWebGL.glReadPixels(0, 0, w, h, GL_RGBA_VALUE, GL_UNSIGNED_BYTE, rgba.data());
+      readWindowRgba(w, h, rgba.data());
       char path[512];
       std::snprintf(path, sizeof path, "%s-f%d.ppm", dumpPrefix, dumpCount);
       if (FILE *file = std::fopen(path, "wb")) {
@@ -1483,7 +1548,7 @@ extern "C" void gea_three_webgl_swap() {
       if (due > recordWritten && gWebGL.widthPx == recordW && gWebGL.heightPx == recordH) {
         std::vector<unsigned char> rgba(static_cast<size_t>(recordW) * recordH * 4);
         std::vector<unsigned char> rgb(static_cast<size_t>(recordW) * recordH * 3);
-        gWebGL.glReadPixels(0, 0, recordW, recordH, GL_RGBA_VALUE, GL_UNSIGNED_BYTE, rgba.data());
+        readWindowRgba(recordW, recordH, rgba.data());
         for (int y = 0; y < recordH; ++y) {
           const unsigned char *src = rgba.data() + static_cast<size_t>(recordH - 1 - y) * recordW * 4;
           unsigned char *dst = rgb.data() + static_cast<size_t>(y) * recordW * 3;
@@ -2498,6 +2563,36 @@ extern "C" void gea_three_webgl_tex_image_2d_bytes(double target, double level,
   gWebGL.glTexImage2D(asGLenum(target), asGLint(level), asGLint(internalFormat), asGLsizei(width), asGLsizei(height), 0, asGLenum(format), asGLenum(type), bytes);
 }
 
+static bool requireGl(const void *fn, const char *name) {
+  if (fn) return true;
+  smokeLog("[native-webgl] %s is not provided by this GLES; the call is dropped", name);
+  return false;
+}
+
+extern "C" void gea_three_webgl_tex_image_3d_bytes(double target, double level, double internalFormat, double width, double height, double depth, double format, double type, const void* bytes, double) {
+  GEA_WEBGL_VOID("texImage3DBytes");
+  if (!requireGl(reinterpret_cast<const void *>(gWebGL.glTexImage3D), "glTexImage3D")) return;
+  gWebGL.glTexImage3D(asGLenum(target), asGLint(level), asGLint(internalFormat), asGLsizei(width), asGLsizei(height), asGLsizei(depth), 0, asGLenum(format), asGLenum(type), bytes);
+}
+
+extern "C" void gea_three_webgl_tex_sub_image_3d_bytes(double target, double level, double xoffset, double yoffset, double zoffset, double width, double height, double depth, double format, double type, const void* bytes, double) {
+  GEA_WEBGL_VOID("texSubImage3DBytes");
+  if (!requireGl(reinterpret_cast<const void *>(gWebGL.glTexSubImage3D), "glTexSubImage3D")) return;
+  gWebGL.glTexSubImage3D(asGLenum(target), asGLint(level), asGLint(xoffset), asGLint(yoffset), asGLint(zoffset), asGLsizei(width), asGLsizei(height), asGLsizei(depth), asGLenum(format), asGLenum(type), bytes);
+}
+
+extern "C" void gea_three_webgl_tex_storage_3d(double target, double levels, double internalFormat, double width, double height, double depth) {
+  GEA_WEBGL_VOID("texStorage3D");
+  if (!requireGl(reinterpret_cast<const void *>(gWebGL.glTexStorage3D), "glTexStorage3D")) return;
+  gWebGL.glTexStorage3D(asGLenum(target), asGLsizei(std::max(1.0, levels)), asGLenum(internalFormat), asGLsizei(width), asGLsizei(height), asGLsizei(depth));
+}
+
+extern "C" void gea_three_webgl_framebuffer_texture_layer(double target, double attachment, double texture, double level, double layer) {
+  GEA_WEBGL_VOID("framebufferTextureLayer");
+  if (!requireGl(reinterpret_cast<const void *>(gWebGL.glFramebufferTextureLayer), "glFramebufferTextureLayer")) return;
+  gWebGL.glFramebufferTextureLayer(asGLenum(target), asGLenum(attachment), asGLuint(texture), asGLint(level), asGLint(layer));
+}
+
 extern "C" void gea_three_webgl_tex_sub_image_2d_bytes(double target, double level, double xoffset, double yoffset, double width, double height, double format, double type, const void* bytes, double) {
   GEA_WEBGL_VOID("texSubImage2DBytes");
   gWebGL.glTexSubImage2D(asGLenum(target), asGLint(level), asGLint(xoffset), asGLint(yoffset), asGLsizei(width), asGLsizei(height), asGLenum(format), asGLenum(type), bytes);
@@ -2805,6 +2900,106 @@ extern "C" void gea_three_webgl_read_pixels_bytes(double x, double y, double wid
   gWebGL.glReadPixels(asGLint(x),asGLint(y),asGLsizei(width),asGLsizei(height),asGLenum(format),asGLenum(type),bytes);
 }
 
+// WebGL2 asynchronous readback (three's readRenderTargetPixelsAsync): readPixels into the bound
+// PIXEL_PACK_BUFFER at a byte offset, a fence, polling, then getBufferSubData through a read mapping.
+extern "C" void gea_three_webgl_read_pixels_pack(double x, double y, double width, double height, double format, double type, double offset) {
+  GEA_WEBGL_VOID("readPixels");
+  GLint packBuffer = 0;
+  gWebGL.glGetIntegerv(0x88ED, &packBuffer);
+  if (!packBuffer || !std::isfinite(offset) || offset < 0 || std::floor(offset) != offset) { if (!hostReadbackError) hostReadbackError = 0x0502; return; }
+  gWebGL.glReadPixels(asGLint(x), asGLint(y), asGLsizei(width), asGLsizei(height), asGLenum(format), asGLenum(type),
+                      reinterpret_cast<void *>(static_cast<std::uintptr_t>(offset)));
+}
+static std::unordered_map<std::uint32_t, GLsync> gWebGLSyncs;
+static std::uint32_t gWebGLNextSync = 1;
+extern "C" double gea_three_webgl_fence_sync() {
+  GEA_WEBGL_DOUBLE("fenceSync");
+  GLsync sync = gWebGL.glFenceSync(0x9117 /* SYNC_GPU_COMMANDS_COMPLETE */, 0);
+  if (!sync) return 0.0;
+  const std::uint32_t id = gWebGLNextSync++;
+  gWebGLSyncs[id] = sync;
+  return static_cast<double>(id);
+}
+extern "C" double gea_three_webgl_client_wait_sync(double sync, double flags, double timeout) {
+  GEA_WEBGL_DOUBLE("clientWaitSync");
+  auto it = gWebGLSyncs.find(static_cast<std::uint32_t>(sync));
+  if (it == gWebGLSyncs.end()) return 0x911D; // WAIT_FAILED
+  return static_cast<double>(gWebGL.glClientWaitSync(it->second, static_cast<GLbitfield>(flags), static_cast<GLuint64>(std::max(0.0, timeout))));
+}
+extern "C" void gea_three_webgl_delete_sync(double sync) {
+  GEA_WEBGL_VOID("deleteSync");
+  auto it = gWebGLSyncs.find(static_cast<std::uint32_t>(sync));
+  if (it == gWebGLSyncs.end()) return;
+  gWebGL.glDeleteSync(it->second);
+  gWebGLSyncs.erase(it);
+}
+// GPU timers for the app's frame profiler, on GL_EXT_disjoint_timer_query.
+struct HostGpuTimers {
+  bool initialized = false, supported = false;
+  void (*gen)(GLsizei, GLuint *) = nullptr;
+  void (*remove)(GLsizei, const GLuint *) = nullptr;
+  void (*begin)(GLenum, GLuint) = nullptr;
+  void (*end)(GLenum) = nullptr;
+  void (*available)(GLuint, GLenum, GLuint *) = nullptr;
+  void (*result)(GLuint, GLenum, std::uint64_t *) = nullptr;
+  bool open = false;
+  bool ensure() {
+    if (initialized) return supported;
+    initialized = true;
+    const auto extensions = reinterpret_cast<const char *>(gWebGL.glGetString(0x1F03));
+    const std::string list = " " + std::string(extensions ? extensions : "") + " ";
+    if (list.find(" GL_EXT_disjoint_timer_query ") == std::string::npos) return false;
+    gen = loadGl<decltype(gen)>("glGenQueriesEXT");
+    remove = loadGl<decltype(remove)>("glDeleteQueriesEXT");
+    begin = loadGl<decltype(begin)>("glBeginQueryEXT");
+    end = loadGl<decltype(end)>("glEndQueryEXT");
+    available = loadGl<decltype(available)>("glGetQueryObjectuivEXT");
+    result = loadGl<decltype(result)>("glGetQueryObjectui64vEXT");
+    supported = gen && remove && begin && end && available && result;
+    return supported;
+  }
+};
+static HostGpuTimers gHostGpuTimers;
+extern "C" double gea_three_webgl_timer_begin() {
+  GEA_WEBGL_DOUBLE("timerBegin");
+  auto &t = gHostGpuTimers;
+  if (!t.ensure() || t.open) return 0.0;
+  GLuint query = 0;
+  t.gen(1, &query);
+  if (!query) return 0.0;
+  t.begin(0x88BF /* TIME_ELAPSED_EXT */, query);
+  t.open = true;
+  return static_cast<double>(query);
+}
+extern "C" void gea_three_webgl_timer_end() {
+  GEA_WEBGL_VOID("timerEnd");
+  auto &t = gHostGpuTimers;
+  if (!t.supported || !t.open) return;
+  t.end(0x88BF);
+  t.open = false;
+}
+extern "C" double gea_three_webgl_timer_result(double timer) {
+  GEA_WEBGL_DOUBLE("timerResult");
+  auto &t = gHostGpuTimers;
+  const GLuint query = static_cast<GLuint>(timer);
+  if (!t.supported || !query) return 0.0;
+  GLuint ready = 0;
+  t.available(query, 0x8867 /* QUERY_RESULT_AVAILABLE */, &ready);
+  if (!ready) return -1.0;
+  std::uint64_t ns = 0;
+  t.result(query, 0x8866 /* QUERY_RESULT */, &ns);
+  t.remove(1, &query);
+  return static_cast<double>(ns);
+}
+extern "C" void gea_three_webgl_get_buffer_sub_data_bytes(double target, double srcOffset, void *bytes, double byteLength) {
+  GEA_WEBGL_VOID("getBufferSubData");
+  if (!bytes || !(byteLength > 0) || !(srcOffset >= 0)) { if (!hostReadbackError) hostReadbackError = 0x0501; return; }
+  void *mapped = gWebGL.glMapBufferRange(asGLenum(target), static_cast<GLintptr>(srcOffset), static_cast<GLsizeiptr>(byteLength), 0x0001 /* MAP_READ_BIT */);
+  if (!mapped) { if (!hostReadbackError) hostReadbackError = 0x0502; return; }
+  std::memcpy(bytes, mapped, static_cast<std::size_t>(byteLength));
+  gWebGL.glUnmapBuffer(asGLenum(target));
+}
+
 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {

package/src/inflate.ts

@@ -18,7 +18,7 @@ const codeLengthOrder = new Uint8Array([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4,
 // 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.
+// 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

package/src/nativeWebGL.ts

@@ -1,4 +1,6 @@
+/** @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" />
 
@@ -93,6 +95,7 @@ type NativeHandleKind =
   | 'program'
   | 'renderbuffer'
   | 'shader'
+  | 'sync'
   | 'texture'
   | 'uniform'
   | 'vertexArray'
@@ -200,11 +203,26 @@ 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[] = []
@@ -254,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
@@ -663,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
@@ -935,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
@@ -1106,10 +1139,10 @@ export class NativeWebGL2RenderingContext {
   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 ?? new Uint8Array(0))
-    } else if (borderOrSource && typeof borderOrSource !== 'number') {
+    } 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')
+      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 {
@@ -1125,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)) }
@@ -1150,7 +1189,9 @@ export class NativeWebGL2RenderingContext {
   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) }
@@ -1193,7 +1234,13 @@ export class NativeWebGL2RenderingContext {
   invalidateFramebuffer(_target: number, _attachments: BufferSourceLike): 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: ReadPixelsDestination, offset = 0): 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);}
@@ -1202,7 +1249,9 @@ export class NativeWebGL2RenderingContext {
   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 }
@@ -1213,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 }