Add option to enable 64-bit and threads with emscripten

CMake/vtkCompilerPlatformFlags.cmake

@@ -17,6 +17,27 @@ if(CMAKE_SYSTEM MATCHES "SunOS.*")
   endif()
 endif()
 
+if (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+  if (VTK_WEBASSEMBLY_THREADS)
+    # Remove after https://github.com/WebAssembly/design/issues/1271 is closed
+    # Set Wno flag globally because even though the flag is added in vtkCopmilerWarningFlags.cmake,
+    # wrapping tools do not link with `vtkbuild`
+    set(VTK_REQUIRED_CXX_FLAGS "${VTK_REQUIRED_CXX_FLAGS} -pthread -Wno-pthreads-mem-growth")
+    set(VTK_REQUIRED_C_FLAGS "${VTK_REQUIRED_C_FLAGS} -pthread -Wno-pthreads-mem-growth")
+    set(VTK_REQUIRED_EXE_LINKER_FLAGS "${VTK_REQUIRED_EXE_LINKER_FLAGS} -pthread")
+    set(VTK_REQUIRED_SHARED_LINKER_FLAGS "${VTK_REQUIRED_SHARED_LINKER_FLAGS} -pthread")
+    set(VTK_REQUIRED_MODULE_LINKER_FLAGS "${VTK_REQUIRED_MODULE_LINKER_FLAGS} -pthread")
+  endif ()
+  if (VTK_WEBASSEMBLY_64_BIT)
+    # Remove after wasm64 is no longer experimental in clang.
+    set(VTK_REQUIRED_CXX_FLAGS "${VTK_REQUIRED_CXX_FLAGS} -sMEMORY64=1 -Wno-experimental")
+    set(VTK_REQUIRED_C_FLAGS "${VTK_REQUIRED_C_FLAGS} -sMEMORY64=1 -Wno-experimental")
+    set(VTK_REQUIRED_EXE_LINKER_FLAGS "${VTK_REQUIRED_EXE_LINKER_FLAGS} -sMEMORY64=1")
+    set(VTK_REQUIRED_SHARED_LINKER_FLAGS "${VTK_REQUIRED_SHARED_LINKER_FLAGS} -sMEMORY64=1")
+    set(VTK_REQUIRED_MODULE_LINKER_FLAGS "${VTK_REQUIRED_MODULE_LINKER_FLAGS} -sMEMORY64=1")
+  endif ()
+endif ()
+
 # A GCC compiler.
 if(CMAKE_COMPILER_IS_GNUCXX)
   if(VTK_USE_X)

CMake/vtkCompilerWarningFlags.cmake

@@ -77,6 +77,17 @@ if (VTK_ENABLE_EXTRA_BUILD_WARNINGS_EVERYTHING)
   vtk_add_flag(-Wno-vla-extension ${langs})
   vtk_add_flag(-Wno-unsafe-buffer-usage ${langs})
 
+  if (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+    if (VTK_WEBASSEMBLY_THREADS)
+      # Remove after https://github.com/WebAssembly/design/issues/1271 is closed
+      vtk_add_flag(-Wno-pthreads-mem-growth ${langs})
+    endif ()
+    if (VTK_WEBASSEMBLY_64_BIT)
+      # Remove after wasm64 is no longer experimental in clang.
+      vtk_add_flag(-Wno-experimental ${langs})
+    endif ()
+  endif ()
+
   set(langs CXX)
   vtk_add_flag(-Wno-c++98-compat-pedantic ${langs})
   vtk_add_flag(-Wno-inconsistent-missing-override ${langs})

CMake/vtkEmscripten.cmake

+# Emscripten.cmake automatically enables 64-bit when the shell defines CMAKE_C_FLAGS="-sMEMORY64=1".
+# This exposes a proper CMake option to switch b/w 32 and 64 bit.
+option(VTK_WEBASSEMBLY_64_BIT "Enable support for 64-bit memory in wasm. Adds -sMEMORY64=1 compile and link flags." OFF)
+if (VTK_WEBASSEMBLY_64_BIT)
+  # stick to what Emscripten.cmake does.
+  set(CMAKE_CROSSCOMPILING_EMULATOR "${CMAKE_CROSSCOMPILING_EMULATOR}" "--experimental-wasm-memory64")
+  set(CMAKE_LIBRARY_ARCHITECTURE "wasm64-emscripten")
+  set(CMAKE_SIZEOF_VOID_P 8)
+  set(CMAKE_C_SIZEOF_DATA_PTR 8)
+  set(CMAKE_CXX_SIZEOF_DATA_PTR 8)
+else ()
+  # stick to what Emscripten.cmake does.
+  set(CMAKE_LIBRARY_ARCHITECTURE "wasm32-emscripten")
+  set(CMAKE_SIZEOF_VOID_P 4)
+  set(CMAKE_C_SIZEOF_DATA_PTR 4)
+  set(CMAKE_CXX_SIZEOF_DATA_PTR 4)
+endif ()
+
+set (default_wasm_threads OFF)
+include(vtkTesting)
+if (VTK_BUILD_TESTING)
+  # Tests want to use synchronous XHR in order to access data and image files from the host filesystem outside of the wasm sandbox.
+  # Since synchronous XHR is deprecated outside of a web worker, VTK cannot have a test wait for data loading on the main browser thread.
+  # By enabling pthreads support, emscripten will be asked to run `main(argc, argv)` on a web worker and proxy function calls relating to the
+  # DOM, FS API over to the main UI thread.
+  # https://emscripten.org/docs/porting/pthreads.html#additional-flags
+  set (default_wasm_threads ON)
+endif ()
+option(VTK_WEBASSEMBLY_THREADS "Enable threading support in wasm. Adds -pthread compile and link flags." ${default_wasm_threads})

CMakeLists.txt

@@ -17,6 +17,10 @@ if (APPLE)
   include(vtkApple)
 endif ()
 
+if (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+  include(vtkEmscripten)
+endif ()
+
 # must be before the following iOS / Android
 find_package(Git QUIET)
 include(VTKDetermineVersion)

Documentation/docs/advanced/build_wasm_emscripten.md

@@ -100,3 +100,39 @@ The binaries are now installed and you may use `-DVTK_DIR=/work/install/lib/cmak
 If everything went well then it should now be possible to compile and run the one of the C++ examples.
 Head over to [Examples/Emscripten/Cxx/Cone/README.md](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Examples/Emscripten/Cxx/Cone/README.md)
 and test the simple Cone example.
+
+## Multithreading
+
+Multithreading can be enabled in VTK wasm by turning on the CMake setting `VTK_WEBASSEMBLY_THREADS`.
+This option simply adds the compile and link flags necessary for emscripten to use WebWorker for a `pthread` and by extension,
+`std::thread`. Please refer to [Emscripten/Pthreads](https://emscripten.org/docs/porting/pthreads.html) for details.
+
+You generally want to run your C++ `int main(int, char**)` function in a WebWorker. Doing so keeps the
+browser responsive and gives your users a chance to at the very least refresh/close the tab when a long
+running VTK algorithm is processing data. You can set this up with the `-sPROXY_TO_PTHREAD=1` linker flag.
+
+If rendering is also part of your main program, please pass `-sPROXY_TO_PTHREAD=1`, `-sOFFSCREENCANVAS_SUPPORT=1`.
+These flags will proxy rendering calls to the main browser thread. Since DOM events like mouse, keyboard inputs are
+received on the main browser thread, emscripten takes care of queuing the execution of the event callback in the WebWorker
+running the VTK application.
+You can learn more at [settings_reference/proxy-to-pthread](https://emscripten.org/docs/tools_reference/settings_reference.html#proxy-to-pthread)
+and [settings_reference/offscreencanvas-support](https://emscripten.org/docs/tools_reference/settings_reference.html#offscreencanvas-support)
+
+**Tip:**
+
+  If you plan to use a custom DOM `id` for the canvases, please also make sure to pass those as a comma separated list.
+  Ex: `-sOFFSCREENCANVASES_TO_PTHREAD=#canvas1,#canvas2`
+
+## 64-bit
+
+*This feature is experimental.*
+
+VTK, by default compiles for the `wasm32-emscripten` architecture. When a 32-bit VTK wasm application
+loads and renders very large datasets, it can report out-of-memory errors because the maximum
+addressable memory is 4GB. You can overcome this problem by turning on the CMake setting `VTK_WEBASSEMBLY_64_BIT`.
+This option compiles VTK for the `wasm64-emscripten` architecture and the maximum addressable memory is 16GB.
+
+In order to execute VTK wasm64 applications, additional flags are required for:
+1. chrome/edge: `--js-flags=--experimental-wasm-memory64`.
+2. firefox: no flag, use nightly/beta.
+3. nodejs: `--experimental-wasm-memory64`.

Documentation/docs/build_instructions/build_settings.md

@@ -39,6 +39,15 @@ Less common, but variables which may be of interest to some:
     backend has his option `VTK_SMP_ENABLE_<backend_name>` set to `ON`.
   * `VTK_ENABLE_CATALYST` (default `OFF`): Enable catalyst-dependent modules
     including the VTK catalyst implementation. Depends on an external Catalyst.
+  * `VTK_WEBASSEMBLY_64_BIT` (default `OFF`):
+    This option is applicable only when building with Emscripten toolchain.
+    Adds -sMEMORY64 compiler and linker flags.
+  * `VTK_WEBASSEMBLY_THREADS` (default `OFF`):
+    This option is applicable only when building with Emscripten toolchain.
+    Adds -pthread compiler and linker flags. When `VTK_BUILD_TESTING` is `ON`,
+    this also runs unit tests in web workers, which is the only way for the tests
+    to reliably load data files without having to embed entire datasets inside
+    the test binaries.
 
 OpenGL-related options:
 

Documentation/release/dev/add-support-for-wasm-pthreads.md

+# Add support for using threads in vtk.wasm
+
+You can now enable multithreading in VTK wasm build by turning on the
+`VTK_WEBASSEMBLY_THREADS` option during CMake configuration.

Documentation/release/dev/add-support-for-wasm64.md

+# Add support for 64-bit in vtk.wasm
+
+You can now enable 64-bit in VTK wasm build by turning on the
+`VTK_WEBASSEMBLY_64_BIT` option during CMake configuration.