PR #1710: replace cube_texture_polyfill.js with native CubeTexture polyfill

bkaradzic-microsoft · Copilot · bkaradzic-microsoft · commit 3278638d5805 · 2026-06-08T16:59:41.000-07:00
Per review: this polyfill should be available to every Babylon Native
consumer using Chakra, not just the Playground app. Move it from a
Playground-only LoadScript() of cube_texture_polyfill.js into a proper
C++ polyfill library under Polyfills/ that any embedder can link.

The polyfill patches BABYLON.NativeEngine.prototype.createCubeTexture
to transparently retry single-URL .dds / .ktx / .ktx2 cubemap loads
(which BN does not currently handle) as their .env counterpart that
Babylon's CDN co-hosts at the same path. On 404 it falls through to
the original (which throws), preserving existing error semantics.

Implementation pattern follows the existing ErrorCause / StringTrim
native polyfills:

- New Polyfills/CubeTexture/ library.
- Public header Babylon/Polyfills/CubeTexture.h declares
  void BABYLON_API Initialize(Napi::Env env).
- Source/CubeTexture.cpp embeds the polyfill IIFE verbatim from the
  prior cube_texture_polyfill.js (same semantics, same idempotency
  marker __cubeTexturePolyfillInstalled) and dispatches it via the
  free function Napi::Eval(env, source, url). Napi::Eval is declared
  by every engine-specific &lt;napi/env.h&gt; across both N-API trees
  (Chakra / V8 / JavaScriptCore in Core/Node-API/Include/Engine/&lt;X&gt;/
  and JSI in Core/Node-API-JSI/Include/napi/) so the same source
  builds uniformly across all backends; no __has_include switch
  needed for this entry point.

Wiring:
- Top-level CMakeLists.txt: add BABYLON_NATIVE_POLYFILL_CUBETEXTURE
  option (default ON).
- Polyfills/CMakeLists.txt: guarded add_subdirectory(CubeTexture).
- Apps/Playground/CMakeLists.txt and
  Apps/Playground/Android/BabylonNative/CMakeLists.txt: PRIVATE link
  CubeTexture into the Playground / BabylonNativeJNI executables so
  AppContext.cpp can use the published header on every platform.
- Apps/Playground/Shared/AppContext.cpp: include the new header and
  replace
    LoadScript("app:///Scripts/cube_texture_polyfill.js");
  with
    Dispatch([](Napi::Env env) {
        Babylon::Polyfills::CubeTexture::Initialize(env);
    });
  scheduled right after LoadScript("babylon.max.js"). ScriptLoader's
  Dispatch and LoadScript queue onto the same ordered task chain
  (see jsruntimehost ScriptLoader::Impl), so Initialize is guaranteed
  to run after babylon.max.js finishes evaluating - same timing the
  prior LoadScript provided.

Delete Apps/Playground/Scripts/cube_texture_polyfill.js (no longer
shipped).

Verified locally on Chakra build (build/win32 RelWithDebInfo,
headless) - all 7 cubemap-affected tests re-enabled by this PR pass:

  Clear Coat                       diff=519 px
  PBR                              diff=482 px (12 sub-tests skipped, expected)
  Anisotropic                      diff=308 px
  PBRMetallicRoughnessMaterial     diff=482 px
  NMEGLTF                          diff=631 px
  PBRSpecularGlossinessMaterial    diff=522 px

Console log confirms the polyfill ran:
  [CubeTexture polyfill] NativeEngine.createCubeTexture patched with .env fallback

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/Apps/Playground/Android/BabylonNative/CMakeLists.txt b/Apps/Playground/Android/BabylonNative/CMakeLists.txt
@@ -30,6 +30,7 @@ target_link_libraries(BabylonNativeJNI
     PRIVATE Blob
     PRIVATE Canvas
     PRIVATE Console
+    PRIVATE CubeTexture
     PRIVATE File
     PRIVATE GraphicsDevice
     PRIVATE NativeCamera
diff --git a/Apps/Playground/CMakeLists.txt b/Apps/Playground/CMakeLists.txt
@@ -13,7 +13,6 @@ set(DEPENDENCIES
     "../Dependencies/recast.js")
 
 set(SCRIPTS
-    "Scripts/cube_texture_polyfill.js"
     "Scripts/experience.js"
     "Scripts/playground_runner.js"
     "Scripts/validation_native.js"
@@ -140,6 +139,7 @@ target_link_libraries(Playground
     PRIVATE bx
     PRIVATE Canvas
     PRIVATE Console
+    PRIVATE CubeTexture
     PRIVATE ExternalTexture
     PRIVATE File
     PRIVATE GraphicsDevice
diff --git a/Apps/Playground/Shared/AppContext.cpp b/Apps/Playground/Shared/AppContext.cpp
@@ -20,6 +20,7 @@
 #include <Babylon/Polyfills/Blob.h>
 #include <Babylon/Polyfills/Canvas.h>
 #include <Babylon/Polyfills/Console.h>
+#include <Babylon/Polyfills/CubeTexture.h>
 #include <Babylon/Polyfills/File.h>
 #include <Babylon/Polyfills/Performance.h>
 #include <Babylon/Polyfills/TextDecoder.h>
@@ -217,7 +218,13 @@ AppContext::AppContext(
     // Commenting out recast.js for now because v8jsi is incompatible with asm.js.
     // m_scriptLoader->LoadScript("app:///Scripts/recast.js");
     m_scriptLoader->LoadScript("app:///Scripts/babylon.max.js");
-    m_scriptLoader->LoadScript("app:///Scripts/cube_texture_polyfill.js");
+    // CubeTexture polyfill must run AFTER babylon.max.js is evaluated because
+    // it patches BABYLON.NativeEngine.prototype.createCubeTexture. The
+    // ScriptLoader's Dispatch is ordered against LoadScript on the same task
+    // chain, so this is guaranteed to run after babylon.max.js completes.
+    m_scriptLoader->Dispatch([](Napi::Env env) {
+        Babylon::Polyfills::CubeTexture::Initialize(env);
+    });
     m_scriptLoader->LoadScript("app:///Scripts/babylonjs.loaders.js");
     m_scriptLoader->LoadScript("app:///Scripts/babylonjs.materials.js");
     m_scriptLoader->LoadScript("app:///Scripts/babylon.gui.js");
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -142,6 +142,7 @@ option(BABYLON_NATIVE_PLUGIN_TESTUTILS "Include Babylon Native Plugin TestUtils.
 # Polyfills
 option(BABYLON_NATIVE_POLYFILL_WINDOW "Include Babylon Native Polyfill Window." ON)
 option(BABYLON_NATIVE_POLYFILL_CANVAS "Include Babylon Native Polyfill Canvas." ON)
+option(BABYLON_NATIVE_POLYFILL_CUBETEXTURE "Include Babylon Native Polyfill CubeTexture (.dds/.ktx/.ktx2 -> .env fallback for NativeEngine.createCubeTexture)." ON)
 
 # Sanitizers
 option(ENABLE_SANITIZERS "Enable AddressSanitizer and UBSan" OFF)
diff --git a/Polyfills/CMakeLists.txt b/Polyfills/CMakeLists.txt
@@ -5,3 +5,7 @@ endif()
 if(BABYLON_NATIVE_POLYFILL_CANVAS)
     add_subdirectory(Canvas)
 endif()
+
+if(BABYLON_NATIVE_POLYFILL_CUBETEXTURE)
+    add_subdirectory(CubeTexture)
+endif()
diff --git a/Polyfills/CubeTexture/CMakeLists.txt b/Polyfills/CubeTexture/CMakeLists.txt
@@ -0,0 +1,16 @@
+set(SOURCES
+    "Include/Babylon/Polyfills/CubeTexture.h"
+    "Source/CubeTexture.cpp")
+
+add_library(CubeTexture ${SOURCES})
+warnings_as_errors(CubeTexture)
+
+target_include_directories(CubeTexture
+    PUBLIC "Include")
+
+target_link_libraries(CubeTexture
+    PUBLIC napi
+    PUBLIC Foundation)
+
+set_property(TARGET CubeTexture PROPERTY FOLDER Polyfills)
+source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${SOURCES})
diff --git a/Polyfills/CubeTexture/Include/Babylon/Polyfills/CubeTexture.h b/Polyfills/CubeTexture/Include/Babylon/Polyfills/CubeTexture.h
@@ -0,0 +1,31 @@
+#pragma once
+
+#include <napi/env.h>
+#include <Babylon/Api.h>
+
+namespace Babylon::Polyfills::CubeTexture
+{
+    // Patches BABYLON.NativeEngine.prototype.createCubeTexture to transparently
+    // retry .dds / .ktx / .ktx2 single-URL cubemap loads as .env (a format BN
+    // does support). Babylon's CDN co-hosts both, so the swap is invisible to
+    // consumer JS. Falls back to the original (which throws "Cannot load
+    // cubemap because 6 files were not defined") on 404 - preserving existing
+    // error semantics.
+    //
+    // Call Initialize AFTER babylon.max.js has been evaluated; the patch
+    // requires BABYLON.NativeEngine.prototype to exist. When using the
+    // jsruntimehost ScriptLoader, the simplest pattern is:
+    //
+    //   scriptLoader.LoadScript("app:///Scripts/babylon.max.js");
+    //   scriptLoader.Dispatch([](Napi::Env env) {
+    //       Babylon::Polyfills::CubeTexture::Initialize(env);
+    //   });
+    //
+    // The Dispatch queues onto the same ordered task chain as LoadScript, so
+    // Initialize is guaranteed to run after babylon.max.js finishes evaluating.
+    //
+    // This is a tactical bridge until Plugins/NativeEngine wires a proper
+    // loader registry path for cubemap formats. Safe to call multiple times;
+    // the patch is idempotent.
+    void BABYLON_API Initialize(Napi::Env env);
+}
diff --git a/Polyfills/CubeTexture/Source/CubeTexture.cpp b/Polyfills/CubeTexture/Source/CubeTexture.cpp
@@ -1,17 +1,22 @@
-// Cube texture fallback for BN's NativeEngine.
-//
-// BN's NativeEngine.createCubeTexture only natively handles .env single-file
-// cubemaps and 6-file face arrays. Snippets that load .dds (or .ktx) cubemaps
-// without an explicit forcedExtension or 6-file array throw "Cannot load
-// cubemap because 6 files were not defined".
-//
-// Babylon's standard environment cubemaps are hosted both as <name>.dds and
-// <name>.env at the same path on assets.babylonjs.com and
-// playground.babylonjs.com. This polyfill detects the failure pre-condition
-// and transparently retries with the .env URL. If the .env counterpart 404s,
-// it falls through to the original (which throws), preserving existing
-// behavior.
-
+#include <Babylon/Polyfills/CubeTexture.h>
+
+#include <napi/env.h>
+
+namespace Babylon::Polyfills::CubeTexture
+{
+    namespace
+    {
+        // Embedded polyfill source. Kept verbatim from the original Playground
+        // cube_texture_polyfill.js (PR #1710 v0) so behaviour stays identical:
+        //   - Patches BABYLON.NativeEngine.prototype.createCubeTexture.
+        //   - Triggers only when the URL ends in .dds / .ktx / .ktx2 and no
+        //     forcedExtension, 6-file array, or raw buffer was supplied.
+        //   - Retries via NativeEngine._loadFile to fetch the .env counterpart;
+        //     on 404 falls back to the original (which throws), preserving the
+        //     existing failure mode.
+        //   - Idempotent via the __cubeTexturePolyfillInstalled marker on the
+        //     prototype.
+        constexpr const char* JS_SOURCE = R"javascript(
 (function () {
     "use strict";
 
@@ -92,7 +97,7 @@
             });
         };
 
-        var onEnvFailed = function (request, exception) {
+        var onEnvFailed = function (/* request, exception */) {
             settle(function () {
                 original.call(self, rootUrl, scene, files, noMipmap, onLoad, onError, format, forcedExtension, createPolynomials, lodScale, lodOffset, texture, loaderOptions, useSRGBBuffer, buffer);
             });
@@ -108,6 +113,22 @@
     };
 
     if (typeof console !== "undefined" && console.log) {
-        console.log("[cube_texture_polyfill] NativeEngine.createCubeTexture patched with .env fallback");
+        console.log("[CubeTexture polyfill] NativeEngine.createCubeTexture patched with .env fallback");
     }
 })();
+)javascript";
+
+        constexpr const char* JS_SOURCE_URL = "babylon-native://polyfills/CubeTexture.js";
+    }
+
+    void Initialize(Napi::Env env)
+    {
+        // The free function Napi::Eval(env, source, url) is declared by every
+        // engine-specific <napi/env.h> across both N-API trees (Chakra, V8,
+        // JavaScriptCore in Core/Node-API/Include/Engine/<X>/, and JSI in
+        // Core/Node-API-JSI/Include/napi/). Using it uniformly avoids the
+        // Shared-only env.RunScript() which is missing from the JSI tree.
+        Napi::HandleScope scope{env};
+        Napi::Eval(env, JS_SOURCE, JS_SOURCE_URL);
+    }
+}
