Merge pull request #18 from Kitware/refactor-wasm-loader

feat: Refactor src directory

Author: jspanchu

src/core/blobURL.js

@@ -0,0 +1,18 @@
+/**
+ * Create a blob URL from provided buffer and mime type
+ * @param {ArrayBufferLike} buffer
+ * @param {string} mimeType 
+ * @returns {string} blob URL
+ */
+export function createBlobURL(buffer, mimeType) {
+  return URL.createObjectURL(new Blob([buffer], { type: mimeType }));
+}
+
+/**
+ * Dispose a blob URL
+ * @param {string} url 
+ */
+export function disposeBlobURL(url) {
+  // URL.revokeObjectURL is a no-op for non-blob URLs
+  URL.revokeObjectURL(url);
+}

src/core/configManager.js

@@ -0,0 +1,86 @@
+import { EXECUTION_MODES, MIME_TYPES, RENDERING_BACKENDS } from "./constants";
+import { createBlobURL } from "./blobURL";
+import { stripLeadingDotSlash } from "./stringOps";
+
+/**
+ * Validate provided config
+ * @param {object} config 
+ */
+export function validateConfig(config) {
+  const validRenderings = Object.values(RENDERING_BACKENDS);
+  const validExecModes = Object.values(EXECUTION_MODES);
+  if (config.rendering !== undefined && !validRenderings.includes(config.rendering)) {
+    throw new Error(`Invalid rendering backend: ${config.rendering}. Valid options are: ${validRenderings.join(', ')}`);
+  }
+  if (config.exec !== undefined && !validExecModes.includes(config.exec)) {
+    throw new Error(`Invalid execution mode: ${config.exec}. Valid options are: ${validExecModes.join(', ')}`);
+  }
+}
+
+/**
+ * Normalize provided config based on constraints. WebGPU requires async execution.
+ * @param {object} config 
+ * @returns {object}
+ */
+export function normalizeConfig(config) {
+  if (config?.rendering === RENDERING_BACKENDS.WEBGPU) {
+    if (config?.exec !== EXECUTION_MODES.ASYNC) {
+      console.warn('WebGPU rendering requires async execution mode. Switching exec to "async".');
+      return { ...config, exec: EXECUTION_MODES.ASYNC };
+    }
+  }
+  return config;
+}
+
+/**
+ * Check if two configs are the same. Only rendering and exec are compared.
+ * @param {object} config1 
+ * @param {object} config2 
+ * @returns {boolean}
+ */
+export function isSameConfig(config1, config2) {
+  return config1.rendering === config2.rendering && config1.exec === config2.exec;
+}
+
+/**
+ * Create Emscripten config from provided config
+ * @param {object} config 
+ * @param {{name: string, buffer: ArrayBufferLike}} wasmFile 
+ * @returns {object}
+ */
+export function createEmscriptenConfig(config, wasmFile) {
+  const emscriptenConfig = {};
+  let wasmURL = null;
+  if (wasmFile !== null && wasmFile !== undefined) {
+    emscriptenConfig.locateFile = (fileName) => {
+      const normalizedFileName = stripLeadingDotSlash(fileName);
+      const normalizedTargetName = stripLeadingDotSlash(wasmFile.name);
+      if (normalizedFileName === normalizedTargetName) {
+        wasmURL = createBlobURL(wasmFile.buffer, MIME_TYPES.WASM);
+        return wasmURL;
+      }
+      // Resolve other files relative to this module's URL, not the page URL.
+      return new URL(fileName, import.meta.url).href;
+    };
+  }
+  let userOnRuntimeInitialized = config?.onRuntimeInitialized;
+  emscriptenConfig.onRuntimeInitialized = () => {
+    if (typeof userOnRuntimeInitialized === 'function') {
+      userOnRuntimeInitialized();
+    }
+    // Free the object URL after runtime is initialized
+    if (wasmURL !== null) {
+      URL.revokeObjectURL(wasmURL);
+    }
+  };
+  if (config?.rendering === RENDERING_BACKENDS.WEBGPU) {
+    const userPreRun = Array.isArray(config?.preRun)
+      ? config.preRun
+      : (config?.preRun ? [config.preRun] : []);
+    emscriptenConfig.preRun = [(module) => {
+      module.ENV.VTK_GRAPHICS_BACKEND = 'WEBGPU';
+    },
+    ...userPreRun];
+  }
+  return emscriptenConfig;
+}

src/core/constants.js

@@ -0,0 +1,25 @@
+export const RENDERING_BACKENDS = Object.freeze({
+  WEBGL: 'webgl',
+  WEBGPU: 'webgpu',
+});
+
+export const EXECUTION_MODES = Object.freeze({
+  SYNC: 'sync',
+  ASYNC: 'async',
+});
+
+export const DEFAULT_WASM_BASE_NAME = 'vtk';
+
+export const DEFAULT_CONFIG = Object.freeze({
+  rendering: RENDERING_BACKENDS.WEBGL,
+  exec: EXECUTION_MODES.SYNC,
+});
+
+export const WASM_FILE_EXTENSION = '.wasm';
+
+export const MODULE_JS_FILE_EXTENSION = '.mjs';
+
+export const MIME_TYPES = Object.freeze({
+  WASM: 'application/wasm',
+  JAVASCRIPT: 'application/javascript',
+});

src/core/future.js

@@ -0,0 +1,12 @@
+/**
+ * Create a future that returns
+ * @returns { promise, resolve, reject }
+ */
+export function createFuture() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}

src/core/gzipBundle.js

@@ -0,0 +1,64 @@
+import untar from "js-untar";
+import { stripLeadingDotSlash } from "./stringOps.js";
+import { createFuture } from "./future.js";
+import { MODULE_JS_FILE_EXTENSION, WASM_FILE_EXTENSION } from "./constants.js";
+
+/**
+ * Check if provided URL points to a gzip bundle
+ * @param {string} url 
+ * @returns {boolean}
+ */
+export function isGzipBundle(url) {
+  return typeof url === "string" && url.endsWith(".gz");
+}
+
+/**
+ * Fetch gzip bundle from provided URL
+ * @param {string} url 
+ * @returns {Promise<ArrayBuffer>} The decompressed tar archive contents from the gzip bundle.
+ */
+export function fetchGzipBundle(url) {
+  const { promise, resolve, reject } = createFuture();
+  fetch(url).then((response) => {
+    if (response.ok) {
+      const decompressedStream = response.body.pipeThrough(new DecompressionStream('gzip'));
+      const decompressionResponse = new Response(decompressedStream);
+      decompressionResponse
+        .blob()
+        .then((blob) => blob.arrayBuffer())
+        .then(resolve)
+        .catch(reject);
+    }
+    else {
+      reject(new Error(`Could not fetch gzip bundle from ${url} - response status: ${response.status}`));
+    }
+  }).catch(reject);
+  return promise;
+}
+
+/**
+ * Extract the JavaScript and WebAssembly files from gzip bundle.
+ * @param {ArrayBuffer} contents 
+ * @param {object} config 
+ * @param {string} wasmBaseName 
+ * @returns {Promise<{js: {name: string, buffer: ArrayBufferLike}, wasm: {name: string, buffer: ArrayBufferLike}}>}
+ */
+export function extractFilesFromGzipBundle(contents, config, wasmBaseName) {
+  const { promise, resolve, reject } = createFuture();
+  untar(contents)
+    .then((files) => {
+      const execModeSuffix = config?.exec === "async" ? "Async" : "";
+      const jsFileMatch = `${wasmBaseName}WebAssembly${execModeSuffix}${MODULE_JS_FILE_EXTENSION}`;
+      const wasmFileMatch = `${wasmBaseName}WebAssembly${execModeSuffix}${WASM_FILE_EXTENSION}`;
+      const jsFile = files.find((file) => stripLeadingDotSlash(file.name) === jsFileMatch);
+      const wasmFile = files.find((file) => stripLeadingDotSlash(file.name) === wasmFileMatch);
+      if (jsFile === undefined || wasmFile === undefined) {
+        reject(new Error(`Could not find expected files ${jsFileMatch} and ${wasmFileMatch} in the gzip bundle`));
+      }
+      else {
+        resolve({ js: jsFile, wasm: wasmFile });
+      }
+    })
+    .catch(reject);
+  return promise;
+}

src/core/javaScriptCxxTranslators.js

@@ -0,0 +1,47 @@
+/**
+ * Converts a C++ style name (PascalCase) to a JavaScript style name (camelCase).
+ * @param {string} cxxName 
+ * @returns {string}
+ */
+export function toJsName(cxxName) {
+  const jsName = `${cxxName.charAt(0).toLowerCase()}${cxxName.slice(1)}`;
+  // console.log("c2j", cxxName, "=>", jsName);
+  return jsName;
+}
+
+/**
+ * Converts a JavaScript style name (camelCase) to a C++ style name (PascalCase).
+ * @param {string} jsName 
+ * @returns {string}
+ */
+export function toCxxName(jsName) {
+  const cxxName = `${jsName.charAt(0).toUpperCase()}${jsName.slice(1)}`;
+  // console.log("j2c", jsName, "=>", cxxName);
+  return cxxName;
+}
+
+/**
+ * Convert JS-style keyword arguments to C++-style keyword arguments.
+ * @param {object} kwArgs 
+ * @returns {object}
+ */
+export function toCxxKeys(kwArgs) {
+  const wrapped = {};
+  Object.entries(kwArgs).forEach(([k, v]) => {
+    wrapped[toCxxName(k)] = v;
+  });
+  return wrapped;
+}
+
+/**
+ * Convert C++-style keyword arguments to JS-style keyword arguments.
+ * @param {object} kwArgs 
+ * @returns {object}
+ */
+export function toJsKeys(kwArgs) {
+  const wrapped = {};
+  Object.entries(kwArgs).forEach(([k, v]) => {
+    wrapped[toJsName(k)] = v;
+  });
+  return wrapped;
+}