@geastack/native-webgl-angle 0.1.13 → 0.1.14

package/README.md

@@ -50,9 +50,36 @@ native/angle_webgl_host.mm
 
 ## Native sources in apps
 
-Gea app manifests currently accept only app-relative `nativeSources`. Until
-that resolver can consume package native sources directly, app consumers keep a
-small app-local `.mm` wrapper that includes this package's native implementation.
+Apple apps name the host in `gea.nativeSources`, either app-relative or by
+package path (`@geastack/native-webgl-angle/native/angle_webgl_host.mm`).
+
+The Windows desktop target needs nothing in the app: `gea-native.json`
+declares the host (`native/angle_webgl_host.mm` and `native/audio_host.mm`,
+compiled as C++) and `native/win32_webgl_surface.cpp`, a host extension that
+gives the program a child window filling the main window's content area,
+attaches the WebGL context to it before the program's top level runs, makes
+the context current around initialization and each frame, hands frame pacing
+to the presentation, and reports keys (as macOS virtual key codes, with a
+release held until a frame has seen the key down) and the pointer (in CSS
+pixels).
+
+The package requires a `gles` provider: an EGL and OpenGL ES 3
+implementation. The app configures it, for example
+
+```json
+"gea": { "targets": { "windows": { "providers": {
+  "gles": { "directory": "build/renderer", "files": { "egl": "GL.dll", "gles": "GL.dll" }, "runtimeFiles": ["d3d12/D3D12Core.dll"] }
+} } } }
+```
+
+or `"gles": "path/to/angle"` for a directory holding ANGLE's `libEGL.dll` and
+`libGLESv2.dll`. The build stages those files beside the executable and
+compiles their names in (`GEA_WEBGL_EGL_LIBRARY`, `GEA_WEBGL_GLES_LIBRARY`);
+the host loads them from the executable's directory. `GEA_ANGLE_EGL_DYLIB` and
+`GEA_ANGLE_GLES_DYLIB` still override the paths at run time. Without a
+provider the build stops and says so. Audio files resolve from
+`GEA_THREE_AUDIO_DIR`, else `Resources\Sounds` beside the executable, unless
+the app names a directory with `gea_three_audio_set_directory_uwp`.
 
 The bridge implementation itself lives here.
 

package/gea-native.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "What a GeaStack native target needs in order to build this package into an app. Paths are relative to the package root.",
+  "windows": {
+    "sources": ["native/angle_webgl_host.mm", "native/audio_host.mm", "native/win32_webgl_surface.cpp"],
+    "includeDirs": ["native"],
+    "requires": {
+      "gles": {
+        "description": "an EGL and OpenGL ES 3 implementation (ANGLE's libEGL.dll and libGLESv2.dll, or one DLL exporting both)",
+        "files": {
+          "egl": { "define": "GEA_WEBGL_EGL_LIBRARY", "default": "libEGL.dll" },
+          "gles": { "define": "GEA_WEBGL_GLES_LIBRARY", "default": "libGLESv2.dll" }
+        }
+      }
+    }
+  }
+}

package/native/angle_webgl_host.mm

@@ -1,4 +1,13 @@
 #include "webgl_readback.h"
+#if defined(_WIN32)
+// The EGL and OpenGL ES libraries the Windows host loads beside the executable.
+#ifndef GEA_WEBGL_EGL_LIBRARY
+#define GEA_WEBGL_EGL_LIBRARY "libEGL.dll"
+#endif
+#ifndef GEA_WEBGL_GLES_LIBRARY
+#define GEA_WEBGL_GLES_LIBRARY "libGLESv2.dll"
+#endif
+#endif
 // 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)
@@ -1151,22 +1160,42 @@ extern "C" bool gea_three_webgl_attach(
   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 {
+  // An override path from the environment first, then the packaged library of
+  // a UWP app, then the file beside the executable. The file names default to
+  // ANGLE's; a build that stages another EGL/GLES implementation names its
+  // files through GEA_WEBGL_EGL_LIBRARY / GEA_WEBGL_GLES_LIBRARY (paths
+  // relative to the executable's directory; one DLL may implement both).
+  auto openWin32 = [](const wchar_t *overrideEnv, const char *name) -> HMODULE {
     wchar_t overridePath[MAX_PATH];
     const DWORD n = GetEnvironmentVariableW(overrideEnv, overridePath, MAX_PATH);
     if (n > 0 && n < MAX_PATH) {
       if (HMODULE m = LoadLibraryW(overridePath)) return m;
+      smokeLog("[native-webgl-angle] %ls names a library that does not load (error %lu)", overrideEnv, GetLastError());
     }
+    std::wstring file;
+    for (const char *c = name; *c; ++c) file.push_back(*c == '/' ? L'\\' : static_cast<wchar_t>(static_cast<unsigned char>(*c)));
 #if defined(WINAPI_FAMILY) && WINAPI_FAMILY == WINAPI_FAMILY_APP
-    return LoadPackagedLibrary(name, 0);
+    return LoadPackagedLibrary(file.c_str(), 0);
 #else
-    return LoadLibraryW(name);
+    wchar_t module[MAX_PATH] = {};
+    const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+    std::wstring beside(module, length < MAX_PATH ? length : 0);
+    const size_t slash = beside.find_last_of(L"\\/");
+    if (slash != std::wstring::npos) {
+      beside.resize(slash + 1);
+      beside += file;
+      // Altered search path: the library's own dependencies resolve from its directory.
+      if (HMODULE m = LoadLibraryExW(beside.c_str(), nullptr, LOAD_WITH_ALTERED_SEARCH_PATH)) return m;
+    }
+    return LoadLibraryW(file.c_str());
 #endif
   };
-  gWebGL.egl = openWin32(L"GEA_ANGLE_EGL_DYLIB", L"libEGL.dll");
-  gWebGL.gles = openWin32(L"GEA_ANGLE_GLES_DYLIB", L"libGLESv2.dll");
+  gWebGL.egl = openWin32(L"GEA_ANGLE_EGL_DYLIB", GEA_WEBGL_EGL_LIBRARY);
+  gWebGL.gles = openWin32(L"GEA_ANGLE_GLES_DYLIB", GEA_WEBGL_GLES_LIBRARY);
+  if (!gWebGL.egl || !gWebGL.gles) {
+    smokeLog("[native-webgl-angle] EGL/GLES implementation not found: %s and %s beside the executable "
+             "(GEA_ANGLE_EGL_DYLIB / GEA_ANGLE_GLES_DYLIB override them)", GEA_WEBGL_EGL_LIBRARY, GEA_WEBGL_GLES_LIBRARY);
+  }
 #elif defined(__APPLE__)
   static const char *const eglPaths[] = {
     "/Applications/Visual Studio Code.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Libraries/libEGL.dylib",

package/native/audio_host.mm

@@ -21,6 +21,9 @@
 #if defined(_WIN32)
 #define _USE_MATH_DEFINES
 #include "audio_uwp.h"
+// Legacy Win16 macros are not C++ identifiers and must not leak into the runtime.
+#undef near
+#undef far
 #else
 #import <AVFoundation/AVFoundation.h>
 #import <Foundation/Foundation.h>
@@ -44,8 +47,30 @@
 
 #if defined(_WIN32)
 static std::wstring geaAudioAssetDirectory;
+static bool geaAudioAssetDirectorySet = false;
 extern "C" void gea_three_audio_set_directory_uwp(const wchar_t *path) {
   geaAudioAssetDirectory = path ? path : L"";
+  geaAudioAssetDirectorySet = true;
+}
+// Without a driver naming the directory: GEA_THREE_AUDIO_DIR, else the
+// Resources\Sounds folder beside the executable (where the desktop target
+// stages an app's sounds), matching the macOS host's bundle lookup.
+static const std::wstring &geaAudioDirectory() {
+  if (!geaAudioAssetDirectorySet) {
+    geaAudioAssetDirectorySet = true;
+    wchar_t value[MAX_PATH] = {};
+    const DWORD n = GetEnvironmentVariableW(L"GEA_THREE_AUDIO_DIR", value, MAX_PATH);
+    if (n > 0 && n < MAX_PATH) {
+      geaAudioAssetDirectory = value;
+    } else {
+      wchar_t module[MAX_PATH] = {};
+      const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+      std::wstring directory(module, length < MAX_PATH ? length : 0);
+      const size_t slash = directory.find_last_of(L"\\/");
+      if (slash != std::wstring::npos) geaAudioAssetDirectory = directory.substr(0, slash) + L"\\Resources\\Sounds";
+    }
+  }
+  return geaAudioAssetDirectory;
 }
 #endif
 
@@ -427,7 +452,7 @@ struct GeaAudioEngine {
   long loadBufferFile(const std::string &name) {
     if (name.empty() || name.find('/') != std::string::npos || name.find("..") != std::string::npos) return 0;
 #if defined(_WIN32)
-    if (name.find('\\') != std::string::npos || geaAudioAssetDirectory.empty()) return 0;
+    if (name.find('\\') != std::string::npos || geaAudioDirectory().empty()) return 0;
     const int length = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), nullptr, 0);
     if (length <= 0) return 0;
     std::wstring base(static_cast<size_t>(length), L'\0');

package/native/win32_webgl_surface.cpp

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: Apache-2.0
+// The WebGL surface of a Windows desktop build: a child window filling the
+// main window's content area, which the native WebGL host renders into, and
+// the input the host reports to the program.
+//
+// It plugs into the Windows target as a host extension (gea_win32_host.h):
+// the target attaches it before the program's top level runs -- the program
+// creates its WebGL context while it initializes -- and brackets the
+// initialization and every frame with begin/end, which is when the host's
+// EGL context is current. Keys reach the host as macOS virtual key codes, the
+// code space the program's key polling uses on every platform; pointer
+// positions are in CSS pixels of the surface.
+#include "gea_win32_host.h"
+
+#include <windowsx.h>
+
+#include <algorithm>
+#include <cstdio>
+#include <cstdlib>
+
+extern "C" bool gea_three_webgl_attach_uwp(void *nativeWindow, double width, double height, double devicePixelRatio);
+extern "C" void gea_three_webgl_update_size_uwp(double width, double height, double devicePixelRatio);
+extern "C" bool gea_three_webgl_begin_frame_uwp();
+extern "C" void gea_three_webgl_end_frame_uwp();
+extern "C" void gea_three_set_key_state(int code, bool down);
+extern "C" void gea_three_set_pointer_state(double x, double y, double width, double height, bool down);
+
+namespace {
+
+HWND gSurface = nullptr;
+HWND gMainWindow = nullptr;
+double gScale = 1.0;
+bool gPointerDown = false;
+// The program polls key state once per frame, so a tap whose key-down and
+// key-up both arrive between two frames would never be seen. A release waits
+// here until a frame has run with the key down.
+bool gReleasePending[256] = {};
+
+// macOS virtual key codes (Carbon kVK_*), for the keys a game typically polls.
+int macKeyCode(WPARAM vk)
+{
+	switch (vk) {
+	case VK_LEFT: return 123;
+	case VK_RIGHT: return 124;
+	case VK_DOWN: return 125;
+	case VK_UP: return 126;
+	case VK_SPACE: return 49;
+	case VK_RETURN: return 36;
+	case VK_ESCAPE: return 53;
+	case VK_TAB: return 48;
+	case VK_BACK: return 51;
+	case VK_DELETE: return 117;
+	case VK_HOME: return 115;
+	case VK_END: return 119;
+	case VK_PRIOR: return 116;
+	case VK_NEXT: return 121;
+	case VK_SHIFT: case VK_LSHIFT: return 56;
+	case VK_RSHIFT: return 60;
+	case VK_CONTROL: case VK_LCONTROL: return 59;
+	case VK_RCONTROL: return 62;
+	case VK_MENU: case VK_LMENU: return 58;
+	case VK_RMENU: return 61;
+	case VK_OEM_MINUS: return 27;
+	case VK_OEM_PLUS: return 24;
+	case VK_OEM_COMMA: return 43;
+	case VK_OEM_PERIOD: return 47;
+	case VK_OEM_1: return 41;   // ;
+	case VK_OEM_2: return 44;   // /
+	case VK_OEM_3: return 50;   // `
+	case VK_OEM_4: return 33;   // [
+	case VK_OEM_5: return 42;   // backslash
+	case VK_OEM_6: return 30;   // ]
+	case VK_OEM_7: return 39;   // '
+	default: break;
+	}
+	static const int letters[26] = {0, 11, 8, 2, 14, 3, 5, 4, 34, 38, 40, 37, 46, 45, 31, 35, 12, 15, 1, 17, 32, 9, 13, 7, 16, 6};
+	if (vk >= 'A' && vk <= 'Z') return letters[vk - 'A'];
+	static const int digits[10] = {29, 18, 19, 20, 21, 23, 22, 26, 28, 25};
+	if (vk >= '0' && vk <= '9') return digits[vk - '0'];
+	static const int functions[12] = {122, 120, 99, 118, 96, 97, 98, 100, 101, 109, 103, 111};
+	if (vk >= VK_F1 && vk <= VK_F12) return functions[vk - VK_F1];
+	return -1;
+}
+
+void releaseAllKeys()
+{
+	for (int code = 0; code < 256; ++code) {
+		gReleasePending[code] = false;
+		gea_three_set_key_state(code, false);
+	}
+}
+
+void reportPointer(LPARAM lParam)
+{
+	RECT client{};
+	GetClientRect(gSurface, &client);
+	gea_three_set_pointer_state(GET_X_LPARAM(lParam) / gScale, GET_Y_LPARAM(lParam) / gScale, std::max<LONG>(1, client.right) / gScale,
+	                            std::max<LONG>(1, client.bottom) / gScale, gPointerDown);
+}
+
+LRESULT CALLBACK surfaceProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
+{
+	switch (message) {
+	case WM_KEYDOWN:
+	case WM_SYSKEYDOWN:
+		if (message == WM_SYSKEYDOWN && wParam == VK_F4) break;  // Alt+F4 closes the window
+		if (const int code = macKeyCode(wParam); code >= 0) {
+			gReleasePending[code] = false;
+			gea_three_set_key_state(code, true);
+		}
+		return 0;  // no menu activation on Alt or F10
+	case WM_KEYUP:
+	case WM_SYSKEYUP:
+		if (const int code = macKeyCode(wParam); code >= 0) gReleasePending[code] = true;
+		return 0;
+	case WM_SYSCHAR:
+		return 0;  // no beep for Alt+key
+	case WM_KILLFOCUS:
+		gPointerDown = false;
+		ReleaseCapture();
+		releaseAllKeys();
+		return 0;
+	case WM_LBUTTONDOWN:
+		SetFocus(hwnd);
+		gPointerDown = true;
+		SetCapture(hwnd);
+		reportPointer(lParam);
+		return 0;
+	case WM_LBUTTONUP:
+		gPointerDown = false;
+		ReleaseCapture();
+		reportPointer(lParam);
+		return 0;
+	case WM_MOUSEMOVE:
+		reportPointer(lParam);
+		return 0;
+	case WM_ERASEBKGND:
+		return 1;  // the swap chain owns every pixel
+	case WM_PAINT:
+		ValidateRect(hwnd, nullptr);
+		return 0;
+	default:
+		break;
+	}
+	return DefWindowProcW(hwnd, message, wParam, lParam);
+}
+
+int attach(HWND window, RECT area, double scale)
+{
+	gMainWindow = window;
+	gScale = scale > 0 ? scale : 1.0;
+	HINSTANCE instance = GetModuleHandleW(nullptr);
+	WNDCLASSEXW cls{};
+	cls.cbSize = sizeof(cls);
+	cls.style = CS_OWNDC | CS_DBLCLKS;
+	cls.lpfnWndProc = surfaceProc;
+	cls.hInstance = instance;
+	cls.hCursor = LoadCursorW(nullptr, IDC_ARROW);
+	cls.lpszClassName = L"GeaWebGLSurface";
+	RegisterClassExW(&cls);
+	// The main window must not paint over its swap-chain child.
+	SetWindowLongPtrW(window, GWL_STYLE, GetWindowLongPtrW(window, GWL_STYLE) | WS_CLIPCHILDREN);
+	const int width = std::max<int>(1, area.right - area.left);
+	const int height = std::max<int>(1, area.bottom - area.top);
+	gSurface = CreateWindowExW(0, cls.lpszClassName, L"", WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS, area.left, area.top, width, height, window, nullptr,
+	                           instance, nullptr);
+	if (!gSurface) {
+		std::fprintf(stderr, "[native-webgl-angle] could not create the surface window (error %lu)\n", GetLastError());
+		return 0;
+	}
+	SetWindowPos(gSurface, HWND_TOP, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
+	// Present with vsync unless the environment says otherwise.
+	if (!std::getenv("GEA_ANGLE_SWAP_INTERVAL")) _putenv_s("GEA_ANGLE_SWAP_INTERVAL", "1");
+	if (!gea_three_webgl_attach_uwp(gSurface, width, height, gScale)) {
+		std::fprintf(stderr, "[native-webgl-angle] the WebGL surface could not start: no usable EGL/OpenGL ES implementation\n");
+		return 0;
+	}
+	// eglSwapBuffers paces the loop: it waits for the refresh with vsync on and
+	// renders unthrottled with it off (GEA_ANGLE_SWAP_INTERVAL=0).
+	gea_win32_set_frame_pacing(GEA_WIN32_FRAME_PACING_PRESENT);
+	SetFocus(gSurface);
+	return 1;
+}
+
+void layout(RECT area, double scale)
+{
+	if (!gSurface) return;
+	gScale = scale > 0 ? scale : 1.0;
+	const int width = std::max<int>(1, area.right - area.left);
+	const int height = std::max<int>(1, area.bottom - area.top);
+	SetWindowPos(gSurface, nullptr, area.left, area.top, width, height, SWP_NOZORDER | SWP_NOACTIVATE);
+	gea_three_webgl_update_size_uwp(width, height, gScale);
+}
+
+int beginFrame() { return gea_three_webgl_begin_frame_uwp() ? 1 : 0; }
+
+void endFrame()
+{
+	gea_three_webgl_end_frame_uwp();
+	for (int code = 0; code < 256; ++code) {
+		if (!gReleasePending[code]) continue;
+		gReleasePending[code] = false;
+		gea_three_set_key_state(code, false);
+	}
+}
+
+int windowMessage(HWND, UINT message, WPARAM, LPARAM, LRESULT *result)
+{
+	// Activating the main window gives it the keyboard focus; the surface is
+	// where keys are read.
+	if (message == WM_SETFOCUS && gSurface) {
+		SetFocus(gSurface);
+		*result = 0;
+		return 1;
+	}
+	return 0;
+}
+
+void detach()
+{
+	if (gSurface) DestroyWindow(gSurface);
+	gSurface = nullptr;
+}
+
+const gea_win32_host_extension kSurfaceExtension = {
+	GEA_WIN32_HOST_EXTENSION_VERSION, "The WebGL surface", attach, layout, beginFrame, endFrame, windowMessage, detach,
+};
+const bool kRegistered = (gea_win32_register_host_extension(&kSurfaceExtension), true);
+
+}  // namespace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,8 @@
     "./text/native-text-types": "./src/text/native-text-types.ts",
     "./geatsc-plugin-batched-probe": "./geatsc-plugin-batched-probe.mjs",
     "./test/batched-render-scene": "./test/batched-render-scene.ts",
-    "./test/auto-instanced-render-scene": "./test/auto-instanced-render-scene.ts"
+    "./test/auto-instanced-render-scene": "./test/auto-instanced-render-scene.ts",
+    "./gea-native.json": "./gea-native.json"
   },
   "files": [
     "src",
@@ -40,7 +41,8 @@
     "geatsc-plugin-batched-probe.mjs",
     "test/batched-render-scene.ts",
     "test/auto-instanced-render-scene.ts",
-    "geatsc-plugin-readback.mjs"
+    "geatsc-plugin-readback.mjs",
+    "gea-native.json"
   ],
   "publishConfig": {
     "access": "public",
@@ -51,7 +53,7 @@
     "test:host-effects": "node test/native-host-effects-contract.test.mjs",
     "test:allocation-contracts": "node test/render-sort-contract.test.mjs && node test/upload-array-contract.test.mjs && node test/draw-dispatch-contract.test.mjs && node test/native-upload-transport.test.mjs && node test/fixed-uniform-contract.test.mjs && node test/uniform-binding-contract.test.mjs && node test/buffer-streaming-contract.test.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs",
+    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs && node test/gea-native-declaration.test.mjs",
     "test:package": "node --experimental-vm-modules test/package.test.mjs"
   },
   "dependencies": {