Webgpu browser tests

.github/workflows/build.yml

@@ -1,4 +1,5 @@
 on:
+  workflow_dispatch:
   release:
     types: [published]
   push:
@@ -35,7 +36,7 @@ jobs:
     name: Build on ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 1
@@ -90,6 +91,7 @@ jobs:
           ./LLGI_Test.exe test
 
       - name: Upload
+        if: matrix.name == 'windows_x64'
         uses: actions/upload-artifact@v4
         with:
           name: Test_Result_Windows

.gitignore

@@ -34,6 +34,9 @@
 /msvc/*.user
 **/Debug
 /build
+/build-webgpu-browser/
 /build_clangformat
+/thirdparty/dawn/
+/node_modules/
 
 .DS_Store

CMakeLists.txt

@@ -5,12 +5,26 @@ project(LLGI)
 
 include(GNUInstallDirs)
 include(ExternalProject)
+include(CTest)
 
 # linux flag
 if(UNIX AND NOT APPLE)
   set(LINUX TRUE)
 endif()
 
+option(BUILD_WEBGPU "build webgpu backend" OFF)
+option(BUILD_WEBGPU_BROWSER_TEST
+       "build a WebAssembly browser smoke test for the WebGPU backend" OFF)
+if(BUILD_WEBGPU_BROWSER_TEST AND NOT BUILD_WEBGPU)
+  message(FATAL_ERROR "BUILD_WEBGPU_BROWSER_TEST requires BUILD_WEBGPU=ON.")
+endif()
+set(WEBGPU_DAWN_SOURCE_DIR
+    ""
+    CACHE PATH "Path to a Dawn source checkout used when BUILD_WEBGPU is ON")
+option(WEBGPU_DAWN_BUILD_SAMPLES "Build Dawn sample executables" OFF)
+option(WEBGPU_DAWN_FORCE_SYSTEM_COMPONENT_LOAD
+       "Let Dawn load required Windows system components from System32"
+       ON)
 option(BUILD_VULKAN "build vulkan" OFF)
 option(BUILD_VULKAN_COMPILER "build vulkan compiler" OFF)
 option(BUILD_TEST "build test" OFF)
@@ -27,7 +41,7 @@ option(SPIRVCROSS_WITHOUT_INSTALL "Compile with spirv-cross without install"
        OFF)
 option(USE_CREATE_COMPILER_FUNCTION "Whether LLGI::CreateCompiler is used." ON)
 
-if(LINUX)
+if(LINUX AND NOT BUILD_WEBGPU)
   set(BUILD_VULKAN TRUE)
 endif()
 
@@ -246,13 +260,46 @@ if(BUILD_VULKAN)
   endif()
 endif()
 
+if(BUILD_WEBGPU AND NOT EMSCRIPTEN)
+  set(DAWN_FETCH_DEPENDENCIES
+      OFF
+      CACHE BOOL
+            "Dawn dependencies should be fetched before configuring LLGI"
+            FORCE)
+  set(DAWN_BUILD_SAMPLES ${WEBGPU_DAWN_BUILD_SAMPLES}
+      CACHE BOOL "Build Dawn samples" FORCE)
+  set(DAWN_FORCE_SYSTEM_COMPONENT_LOAD
+      ${WEBGPU_DAWN_FORCE_SYSTEM_COMPONENT_LOAD}
+      CACHE BOOL "Allow Dawn to load Windows system components from System32"
+      FORCE)
+  set(DAWN_BUILD_TESTS OFF CACHE BOOL "Build Dawn tests" FORCE)
+  set(DAWN_ENABLE_INSTALL OFF CACHE BOOL "Install Dawn targets" FORCE)
+
+  set(LLGI_DAWN_SOURCE_DIR "")
+  if(WEBGPU_DAWN_SOURCE_DIR)
+    set(LLGI_DAWN_SOURCE_DIR "${WEBGPU_DAWN_SOURCE_DIR}")
+  elseif(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/dawn/CMakeLists.txt")
+    set(LLGI_DAWN_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/dawn")
+  endif()
+
+  if(LLGI_DAWN_SOURCE_DIR)
+    add_subdirectory("${LLGI_DAWN_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/dawn"
+                     EXCLUDE_FROM_ALL)
+  else()
+    message(
+      FATAL_ERROR
+        "Dawn source was not found. Run `python scripts/fetch_dawn.py`, add thirdparty/dawn, or set WEBGPU_DAWN_SOURCE_DIR to a prepared Dawn checkout."
+    )
+  endif()
+endif()
+
 if(APPLE)
   add_compile_definitions(ENABLE_METAL)
 endif()
 
 add_subdirectory("src")
 
-if(BUILD_TEST)
+if(BUILD_TEST OR BUILD_WEBGPU_BROWSER_TEST)
   add_subdirectory("src_test")
 endif()
 

README.md

@@ -1,48 +1,230 @@
 # LLGI
 
-How to build
-----------
+LLGI is a cross-platform graphics abstraction library that provides a common
+API for DirectX 12, Metal, and Vulkan.
 
-### Windows
+This repository currently contains:
 
+- `LLGI`: the core static library
+- `LLGI_Test`: rendering and shader tests (`BUILD_TEST=ON`)
+- `example_glfw`, `example_imgui`, `example_GPUParticle`: sample applications
+  (`BUILD_EXAMPLE=ON`)
+- `ShaderTranspiler`: shader conversion tool (`BUILD_TOOL=ON`)
+
+## Backend and platform support
+
+| Platform | Default backend | Optional backends | Notes |
+| --- | --- | --- | --- |
+| Windows | DirectX 12 | Vulkan | CI builds both x86 and x64 configurations. |
+| macOS | Metal | - | CI builds with `CMAKE_OSX_DEPLOYMENT_TARGET=10.15`. |
+| iOS | Metal | - | CI includes an iOS build configuration. |
+| Linux | Vulkan | - | `BUILD_VULKAN` is forced to `ON` on Linux. |
+
+## Repository layout
+
+| Path | Description |
+| --- | --- |
+| `src/` | LLGI library sources and public headers |
+| `src_test/` | Test executable and shader test assets |
+| `examples/` | GLFW, Dear ImGui, and GPU particle samples |
+| `tools/` | Shader transpiler sources |
+| `scripts/transpile.py` | Helper script to batch-convert shader assets |
+| `thirdparty/` | Bundled third-party dependencies used by Vulkan compiler/tool builds |
+
+## Getting the source
+
+```bash
+git clone https://github.com/effekseer/LLGI.git
+cd LLGI
+git submodule update --init --recursive
 ```
-$ git clone https://github.com/altseed/LLGI.git
-$ cd LLGI
-$ git submodule update --init
-$ cmake -S . -B build -DBUILD_TEST=ON
-$ cmake --build build
+
+## Build requirements
+
+- CMake 3.15 or newer
+- A C++ toolchain for your platform (`Visual Studio`, `Xcode`, `clang`, or `gcc`)
+- On Linux, Vulkan and X11 development packages
+- When `BUILD_VULKAN_COMPILER` or `BUILD_TOOL` is enabled, the bundled
+  `glslang` and `SPIRV-Cross` submodules are used by default
+
+Linux packages used in CI:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  libx11-dev \
+  libxrandr-dev \
+  libxi-dev \
+  libxinerama-dev \
+  libxcursor-dev \
+  libudev-dev \
+  libx11-xcb-dev \
+  libglu1-mesa-dev \
+  mesa-common-dev \
+  libvulkan-dev
 ```
 
-### macOS
+## Common CMake options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `BUILD_TEST` | `OFF` | Build `LLGI_Test` |
+| `BUILD_EXAMPLE` | `OFF` | Build sample applications |
+| `BUILD_TOOL` | `OFF` | Build `ShaderTranspiler` |
+| `BUILD_WEBGPU` | `OFF` | Enable the experimental WebGPU backend. See [docs/WebGPU.md](docs/WebGPU.md). |
+| `BUILD_VULKAN` | `OFF` (`ON` on Linux) | Enable the Vulkan backend |
+| `BUILD_VULKAN_COMPILER` | `OFF` | Enable Vulkan shader compilation support in `LLGI::CreateCompiler` |
+| `USE_CREATE_COMPILER_FUNCTION` | `ON` | Keep `LLGI::CreateCompiler` enabled |
+| `USE_MSVC_RUNTIME_LIBRARY_DLL` | `ON` | Use the DLL MSVC runtime (`/MD`) |
+
+## Build
 
+### Windows (DirectX 12)
+
+```bash
+cmake -S . -B build -DBUILD_TEST=ON -DBUILD_EXAMPLE=ON
+cmake --build build --config Release
 ```
-$ git clone https://github.com/altseed/LLGI.git
-$ cd LLGI
-$ git submodule update --init
-$ cmake -S . -B build -G "Xcode" -DBUILD_TEST=ON
-$ cmake --build build
+
+For a 32-bit build:
+
+```bash
+cmake -S . -B build -A Win32 -DBUILD_TEST=ON
+cmake --build build --config Release
 ```
 
-### Vulkan(Window, Linux)
+### Windows (DirectX 12 + Vulkan tools)
 
+```bash
+cmake -S . -B build \
+  -DBUILD_TEST=ON \
+  -DBUILD_EXAMPLE=ON \
+  -DBUILD_TOOL=ON \
+  -DBUILD_VULKAN=ON \
+  -DBUILD_VULKAN_COMPILER=ON
+cmake --build build --config Release
 ```
-$ git clone https://github.com/altseed/LLGI.git
-$ cd LLGI
-$ git submodule update --init
-$ cmake -S . -B build -DBUILD_VULKAN=ON -DBUILD_TEST=ON
-$ cmake --build build
+
+### macOS
+
+```bash
+cmake -S . -B build -G Xcode \
+  -DCMAKE_OSX_DEPLOYMENT_TARGET=10.15 \
+  -DBUILD_TEST=ON \
+  -DBUILD_EXAMPLE=ON
+cmake --build build --config Release
 ```
 
-Test
-----------
+### iOS
+
+```bash
+cmake -S . -B build-ios -G Xcode \
+  -DCMAKE_SYSTEM_NAME=iOS \
+  -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
+  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
+cmake --build build-ios --config Release
+```
+
+### Linux (Vulkan)
+
+```bash
+cmake -S . -B build \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DBUILD_TEST=ON \
+  -DBUILD_EXAMPLE=ON \
+  -DBUILD_TOOL=ON \
+  -DBUILD_VULKAN_COMPILER=ON
+cmake --build build
+```
+
+On Linux, `BUILD_VULKAN` is enabled automatically by the top-level
+`CMakeLists.txt`.
+
+### WebGPU (experimental)
 
-Run with Vulkan
+The WebGPU backend uses Dawn and is still experimental. Build instructions,
+Dawn setup, test commands, shader notes, and current limitations are documented
+in [docs/WebGPU.md](docs/WebGPU.md).
+
+## Install
+
+```bash
+cmake --install build --prefix <install-prefix>
 ```
-./LLGI_Test --vulkan
+
+For multi-config generators such as Visual Studio or Xcode, add
+`--config Release`.
+
+The install step exports the `LLGI` static library, public headers, and CMake
+package files under `lib/cmake`.
+
+## Running tests
+
+`LLGI_Test` is available when `BUILD_TEST=ON`.
+
+Default device selection:
+
+- Windows: DirectX 12
+- macOS/iOS: Metal
+- Linux: Vulkan
+
+Examples:
+
+```bash
+# Linux / macOS
+./build/src_test/LLGI_Test
+./build/src_test/LLGI_Test --filter=SimpleRender.*
+
+# Windows
+build\src_test\Release\LLGI_Test.exe
+build\src_test\Release\LLGI_Test.exe --filter=Compile.*
+build\src_test\Release\LLGI_Test.exe --vulkan
+build\src_test\Release\LLGI_Test.exe --webgpu
 ```
 
-Run with single test
+If you want Vulkan shader compilation through
+`LLGI::CreateCompiler(DeviceType::Vulkan)` or the `Compile.*` tests on Vulkan,
+configure with `-DBUILD_VULKAN_COMPILER=ON`.
+
+## Examples
+
+When `BUILD_EXAMPLE=ON`, the following targets are built:
 
+- `example_glfw`: minimal clear/present flow using GLFW
+- `example_imgui`: Dear ImGui integration on top of LLGI and GLFW
+- `example_GPUParticle`: GPU particle sample
+
+The smallest end-to-end sample is in `examples/glfw/main.cpp`.
+
+## Shader tools
+
+When `BUILD_TOOL=ON`, the repository builds `ShaderTranspiler`.
+
+The helper script below uses the built tool to batch-convert shader assets:
+
+```bash
+python scripts/transpile.py src_test/Shaders/
+python scripts/transpile.py examples/GPUParticle/Shaders/
 ```
-./LLGI_Test --filter=<TestName*>
+
+Additional notes are available in [tools/README.md](tools/README.md).
+
+## Minimal usage
+
+```cpp
+auto window = std::unique_ptr<LLGI::Window>(LLGI::CreateWindow("LLGI", {1280, 720}));
+
+LLGI::PlatformParameter parameter;
+parameter.Device = LLGI::DeviceType::Default;
+
+auto platform = LLGI::CreateSharedPtr(LLGI::CreatePlatform(parameter, window.get()));
+auto graphics = LLGI::CreateSharedPtr(platform->CreateGraphics());
+auto memoryPool = LLGI::CreateSharedPtr(graphics->CreateSingleFrameMemoryPool(1024 * 1024, 128));
+auto commandList = LLGI::CreateSharedPtr(graphics->CreateCommandList(memoryPool.get()));
 ```
+
+For a complete runnable example, see `examples/glfw/main.cpp`.
+
+## License
+
+LLGI is distributed under the zlib license. See [LICENSE](LICENSE).