Basic Steps To Create Your Wasm Project
This section describes the basic steps to integrate your TypeScript/JavaScript with C/C++ WebAssembly code.
Overview of WebAssembly Project
Your C/C++ WebAssembly project will consist of HTML (and related JavaScript or TypeScript) and C or C++ source files that are compiled into a ".wasm
" binary file that is loaded as a WebAssembly module by your JavaScript.
JavaScript/TypeScript Part of Wasm Project
On the JavaScript side of your WebAssembly project you will use the twr-wasm JavaScript/TypeScript class twrWasmModule
or twrWasmModuleAsync
to load the .wasm
module, and then call C functions in it using callC
(more details are in the TypeScript/Javascript API section).
C/C++ Part of Wasm Project
You will call C functions (or C++ with ' extern "C" ' linkage) in the .wasm
module from your JavaScript. You can also call JavaScript functions from your C/C++ code, but this is less common.
There is no direct equivalent to a C "main". Instead, a Wasm module provides exported C functions that you can call from JavaScript/TypeScript. A Wasm module is more like a runtime loaded dynamic library.
You're C/C++ code can be non-blocking or blocking. Blocking means that it "takes a long time" to return. For example, if you want to send mouse events to C code, have the code process them then return, this would be non-blocking. Alternately, if your C code is a big loop that never returns, that would be very blocking. You can use the twr-wasm class twrWasmModuleAsync
to execute blocking code from JavaScript. The example maze demonstrates both non-blocking and blocking C calls.
Here are some examples of different types of C/C++ code:
- If you're C/C++ code does not have any direct user interface built in, it can do its calculations and return. The FFT is an example of this.
- If your C/C++ code uses a classic C "UI", where it gets keys from stdin and sends the results to stdout, you can direct stdin and stdout to a
<div>
or<canvas>
tag. This is explained in the stdio section. - Your C/C++ code could be sent events from JavaScript (such mouse, key, timer, or other). This is done by simply calling a C function with the events as arguments. The C/C++ code could then generate no output, could render to a
<div>
or<canvas>
using stdio type C/C++ functions, or it could render to a<canvas>
using 2D drawing APIs that correspond to JavaScript canvas 2D draw operations. (Balls) is an example.
Steps to integrate C code with JavaScript code
Here are the general steps to integrate your C with your JavaScript:
- Compile your C code with clang and link with wasm-ld to create the
.wasm
file. - On the JavaScript side you:
- Access twr-wasm "ES" modules in the normal way with
import
. - Add a
<div id=twr_iodiv>
or<canvas id=twr_iocanvas>
to your HTML (see stdio) - Use
new twrWasmModule()
, followed by a call toloadWasm()
, then one or morecallC()
. - Alternately, use
twrWasmModuleAsync()
-- which is interchangeable with twrWasmModule, but proxies through a worker thread, and adds blocking support, including blocking char input. - For more details, see the remainder of this documentation, or see the hello world or other exampes.
- Access twr-wasm "ES" modules in the normal way with