Web

[amerkoleci]

Hi,
As you can notice I'm working on game engine in C# and would like to know how the wasm C# part works?
I took look at the code and it's difficult for me to understand which part is browser and which one is desktop, would be possible for you to tell me how it works?

Thanks in advance for your time,
Amer

[Refsa]

Hey @amerkoleci,

I've seen and used a few of your projects, cool to see you here. It was a bit of a journey to get it going, so what could be described as platform code is a mess, sorry about that.

I havent managed to get net9.0-browser to work just yet, but I can give a small writeup of how the net8.0-browser is working.

WebGPU

net8.0-browser uses Emscripten 3.1.34, which the WGPU bindings from Silk.NET doesnt fully overlap with. This version of WGPU doesnt have a concept of SurfaceTexture, and still uses the SwapChain structure as seen here.
Second problem with Silk.NET bindings is that the pinvokes wont compile correctly and I ended up wrapping the webgpu.h file from emscripten here. Most of it still points to the data types from Silk.NET, but there were a couple types that were different:

• WGPULimits_Browser
• WGPURequiredLimits_Browser
• WGPUDeviceDescriptor_Browser

These were the main differences to get WebGPU to work, but WGPU native and WebGPU still doesnt fully agree on strictness and might have some things that doesnt work in browser.

WebGPU reference in Emscripten:
https://github.com/emscripten-core/emscripten/blob/3.1.34/src/library_webgpu.js
https://github.com/emscripten-core/emscripten/blob/3.1.34/system/include/webgpu/webgpu.h

Initializing

emscripten provides the main loop, which is the emscripten_set_main_loop pinvoke here. net8.0-browser doesnt support async callbacks so the initialization of WebGPU is a bit of a mess.

In BrowserApplication I'm currently running a graphics setup loop before the game engine loop starts. The entire 'RunInternal' method is ran from emscripten_set_main_loop callback to ensure the browser can progress.

The rest of the graphics setup is done in WGPUContextBrowser, the instance is created in WGPUInstance first, but that is the same for desktop and browser. Its a messy state machine that ensure each async callback is received before it runs the next step. CreateDevice and CreateAdapter are both dependent on callback methods that runs async in the browser, and needs the main loop to run to progress.

In the CreateSurface method you can see how it selects the HTMLCanvas to use. In order for this to work correctly I also had to add a delay in main.js before the dotnet.run() call.

There are a few missing things in the WebGPU version in emscripten 3.1.34, SurfaceGetCurrentTexture is one, SurfaceGetPreferredFormat is another and there are probably a few more I'm missing. The format of the SwapChain is currently hardcoded because of this.

Surface Texture

As mentioned browser uses SwapChain for the drawable surface. I'm setting this up each frame in GPUSurfaceTexture.Setup with a call to SwapChainGetCurrentTextureView. This TextureView needs to be disposed each frame. After getting the TextureView it can be used as normal with WGPU.

Running dotnet

browser-wasm is the runtime identifier, which requires the wasm-tools workload.
<RunAOTCompilation>true</RunAOTCompilation>, setting this to false might make it easier to debug.

A few important bits from the Pollus.Examples.csproj file:

The following will include all the js bootstrap

  <ItemGroup Condition=" '$(TargetFramework)' == 'net8.0-browser' or '$(TargetFramework)' == 'net9.0-browser' ">
    <WasmExtraFilesToDeploy Include="www/index.html" />
    <WasmExtraFilesToDeploy Include="www/main.js" />
    <WasmExtraFilesToDeploy Include="www/*.js" />
    <WasmExtraFilesToDeploy Include="www/*.css" />
  </ItemGroup>

Only -sUSE_WEBGPU=1 should be required here to get WebGPU working.

<PropertyGroup Condition=" '$(TargetFramework)' == 'net8.0-browser' or '$(TargetFramework)' == 'net9.0-browser' ">
  <EmccExtraLDFlags>-sUSE_WEBGPU=1 -sALLOW_MEMORY_GROWTH -lSDL -sUSE_SDL=2 -sUSE_OGG=1 -lopenal -sTOTAL_MEMORY=67108864</EmccExtraLDFlags>
</PropertyGroup>

The following ensures that pinvokes are forwarded to runtime identification in emscripten.

  <Target Condition=" '$(TargetFramework)' == 'net8.0-browser' " Name="AddBrowserDeps" BeforeTargets="_GenerateManagedToNative" DependsOnTargets="_PrepareForWasmBuildNative">
    <ItemGroup>
      <_WasmPInvokeModules Include="__Internal_emscripten" />
      <_WasmPInvokeModules Include="OpenAL" />
      <_WasmPInvokeModules Include="SDL" />
      <_WasmPInvokeModules Include="cimgui" />
    </ItemGroup>
  </Target>

The following I found in this article. Something about the cache needing a static location.

<PropertyGroup Condition=" '$(TargetFramework)' == 'net8.0-browser' or '$(TargetFramework)' == 'net9.0-browser' ">
    <WasmCachePath>$([System.IO.Path]::GetFullPath('$(BaseIntermediateOutputPath)/$(TargetFramework)/wasm-cache'))</WasmCachePath>
  </PropertyGroup>

<Target Condition=" '$(TargetFramework)' == 'net8.0-browser' " Name="UnfreezeCache" DependsOnTargets="AddBrowserDeps"  BeforeTargets="_WasmCompileNativeFiles;_WasmCompileAssemblyBitCodeFilesForAOT;_WasmCalculateInitialHeapSize;_WasmLinkDotNet;_CheckEmccIsExpectedVersion">
    <ItemGroup>
      <EmscriptenEnvVars Remove="EM_FROZEN_CACHE=True" />
      <EmscriptenEnvVars Include="EM_FROZEN_CACHE=0" />
      <EmscriptenEnvVars Include="FROZEN_CACHE=0" />
    </ItemGroup>
  </Target>

Building

Builds with dotnet publish --framework net8.0-browser.

JS bootstrapping

The final output ends up in \bin\Release\net8.0-browser\browser-wasm\AppBundle
In the main.js file it bootstraps and runs the dotnet project. It runs the same was as a regular console application, but it wont be blocking the browser or ran in the background. await dotnet.run() is expected to return and rely on emscripten_set_main_loop. Other interop can also be configured in main.js, but I haven't tried it out.

Example

The simplest example is probably DrwTriangleExample. It doesnt rely on any of my engine logic to run other that the setup code in BrowserApplication.

Hope this helps, let me know if theres anything that I need to explain more or in a better way.

[amerkoleci]

Oh thanks,
Thats a well explained and detailed stuff.

Thanks again!