diff --git a/azure/docsite/api/api-c-con/index.html b/azure/docsite/api/api-c-con/index.html index 38e55747..50deba43 100644 --- a/azure/docsite/api/api-c-con/index.html +++ b/azure/docsite/api/api-c-con/index.html @@ -186,7 +186,7 @@
-

Console API for Web Assembly (Streamed and Windowed)

+

Console C API for Web Assembly (Streamed and Windowed)

This section describes twr-wasm's method of providing and abstracting console I/O in Web Assembly Modules.

C character based input/output is abstracted by struct IoConsole.

Consoles can be "tty" aka "streamed", or they can be "windowed" (aka a "terminal").

diff --git a/azure/docsite/api/api-c-d2d/index.html b/azure/docsite/api/api-c-d2d/index.html index a176324f..724e0a29 100644 --- a/azure/docsite/api/api-c-d2d/index.html +++ b/azure/docsite/api/api-c-d2d/index.html @@ -138,7 +138,7 @@
-

2D Draw API for Web Assembly

+

2D Draw C API for Web Assembly

This section describes twr-wasm's C D2D API, which allows your Web Assembly module to call many of the JavaScript Canvas APIs. There is also a C++ canvas wrapper class in the balls example.

Examples

diff --git a/azure/docsite/api/api-c-general/index.html b/azure/docsite/api/api-c-general/index.html index c1259aa4..fd0c99de 100644 --- a/azure/docsite/api/api-c-general/index.html +++ b/azure/docsite/api/api-c-general/index.html @@ -356,7 +356,8 @@

twr_utf8_char_len

int twr_utf8_char_len(const char *str);

twr_utf32_to_code_page

-

Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page.

+

Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page. The buffer is 0 terminated.

+

Also see c32rtomb and c16rtomb.

For example:

char strbuf[6];             // max size of utf-8 is 4+terminating zero.  Max size of ASCII or windows 1252 is 1 + terminating zero
 setlocale(LC_ALL, "");  // set to default locale, which will be UTF-8 encoding with local language/region
diff --git a/azure/docsite/api/api-libc++/index.html b/azure/docsite/api/api-libc++/index.html
index ea410afe..06da09a4 100644
--- a/azure/docsite/api/api-libc++/index.html
+++ b/azure/docsite/api/api-libc++/index.html
@@ -135,29 +135,26 @@
                 
libc++ for Web Assembly

 
This section describes twr-wasm's support for using the standard c++ library libc++ with Web Assembly.

 
twr-wasm includes libc++ built for Web Assembly and included in the twr-wasm/lib-c folder.

-
You can build twr-wasm projects in C++ with or without libc++.

+
For C++ the use of libc++ is optional.  That is you can build twr-wasm projects in C++ with or without libc++.

 
See the examples tests-libcxx and tests-user for examples of using libc++.

 
See the balls example for how to create a C++ Web Assembly program without the standard C++ library.  The primary advantage to this approach is a bit smaller code size.  You don't need to staticly link libc++.

-
twr-wasm's libc++ for Web Assembly was built with these build options:

-
LIBCXX_ENABLE_LOCALIZATION=ON
-LIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON
-LIBCXXABI_ENABLE_STATIC_UNWINDER=ON
-LIBCXXABI_ENABLE_STATIC=ON
+
Some of the key options twr-wasm's libc++ for Web Assembly was built with are these:

+
DLIBCXX_ENABLE_LOCALIZATION=ON 
+DLIBCXX_ENABLE_UNICODE=ON 
+DLIBCXX_ENABLE_RTTI=ON 
+DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON 
 
-LIBCXX_ENABLE_FILESYSTEM=OFF
-LIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF
-LIBCXX_ENABLE_MONOTONIC_CLOCK=OFF
-LIBCXX_ENABLE_RANDOM_DEVICE=OFF
-LIBCXX_ENABLE_UNICODE=OFF
-LIBCXX_ENABLE_WIDE_CHARACTERS=OFF 
-LIBCXX_ENABLE_EXCEPTIONS=OFF
-LIBCXXABI_ENABLE_EXCEPTIONS=OFF
-LIBCXX_ENABLE_RTTI=OFF
-LIBCXX_ENABLE_THREADS=OFF
-LIBCXXABI_ENABLE_THREADS=OFF
-LIBCXXABI_HAS_PTHREAD_API=OFF
-LIBCXX_ENABLE_SHARED=OFF
-LIBCXXABI_ENABLE_SHARED=OFF 
+DCMAKE_BUILD_TYPE=Release       
+DCMAKE_CXX_STANDARD=20 
+
+DLIBCXX_ENABLE_EXCEPTIONS=OFF 
+DLIBCXX_ENABLE_THREADS=OFF 
+DLIBCXX_ENABLE_SHARED=OFF 
+DLIBCXX_ENABLE_WIDE_CHARACTERS=OFF 
+DLIBCXX_ENABLE_FILESYSTEM=OFF 
+DLIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF 
+DLIBCXX_ENABLE_MONOTONIC_CLOCK=OFF 
+DLIBCXX_ENABLE_RANDOM_DEVICE=OFF
 

               
             
diff --git a/azure/docsite/gettingstarted/compiler-opts/index.html b/azure/docsite/gettingstarted/compiler-opts/index.html
index 4caea295..aeb6a7c4 100644
--- a/azure/docsite/gettingstarted/compiler-opts/index.html
+++ b/azure/docsite/gettingstarted/compiler-opts/index.html
@@ -55,13 +55,13 @@
                   
                   
  • Compiler, Linker, Memory
     
                   
    • 
@@ -143,20 +143,20 @@
                 
    Compiling, Linking, and Memory Options
    
 
    This section described how to use clang to compile C/C++ code for Web Assembly, and how to link your files into a .wasm module.
    
 
    twr-wasm lets you use clang directly, without a wrapper.  This section describes the needed clang compile options and the wasm-ld link options.  You can also take a look at the example makefiles.
    
-
    clang with C
    
+
    C clang Compiler Options Targeting WASM
    
 
    When compiling C code with clang for use with wasm and twr-wasm, use these clang options:
    
 
     --target=wasm32 -nostdinc -nostdlib -isystem  ../../include
 
    
 
    -isystem should point to the folder twr-wasm/include.  The option line above uses a relative link to include that works if your project is a sub folder in the examples folder.
    
 
    If you installed using npm, then includes are at node_modules/twr-wasm/include (see the installation note on npm).
    
 
    You will also need to link to twr.a (explained in the linking section below).
    
-
    clang with C++
    
+
    C++ clang Compiler Options Targeting WASM
    
 
    When compiling C++ code with clang for use with wasm and twr-wasm, use these clang options:
    
 
     --target=wasm32 -fno-exceptions -fno-rtti -nostdlibinc -nostdinc -nostdlib -isystem  ../../include
 
    
 
    You will also need to link to twr.a and libc++.a (explained in the linking section below).
    
 
    Be sure to adjust the path to twr.a, libc++.a, and the include folder as needed (see above note in the C section).
    
-
    linking
    
+
    wasm-ld Linker Options
    
 
    Use the wasm-ld linker directly with twr-wasm.
    
 
    All of the twr-wasm functions are staticly linked from the library lib-c/twr.a.  There is also a version ( lib-c/twrd.a ) of twr-wasm library available with debug symbols.  One of these two static libraries should be added to the list of files to link (normally this is twr.a).  Both versions are built with asserts enabled.  twr.a is built with -O3.  twrd.a is built with -g -O0.
    
 
    To use libc++, link to libc++.a (see the tests-libcxx example makefile).
    
@@ -169,7 +169,7 @@ 
    linking
    
 
    If Using twrWasmModuleAsync:
    
 
    --no-entry --shared-memory --no-check-features --initial-memory=<size> --max-memory=<size>
 
    
-
    Memory
    
+
    Memory Options for Web Assembly
    
 
    You set the memory size for your module (WebAssembly.Memory) using wasm-ld options as follows (this examples sets your wasm memory to 1MB).  The memory size should be a multiple of 64*1024 (64K) chunks.
    
 
    if using twrWasmModule:
    
 
    --initial-memory=1048576 --max-memory=1048576
diff --git a/azure/docsite/index.html b/azure/docsite/index.html
index c99a6721..1fe81955 100644
--- a/azure/docsite/index.html
+++ b/azure/docsite/index.html
@@ -54,9 +54,9 @@
     
     
  • On Github
     
    • 
-    
  • Version 2.0 vs. 1.0
+    
  • Version 2 vs. 1
     
    • 
-    
  • Version 2.0.0 Limitations
+    
  • Version 2 Limitations
     
    • 
     
  • Post Feedback
     
    • 
@@ -150,7 +150,7 @@
             
    
               
                 
    twr-wasm - Easy C/C++ Web Assembly Modules
    
-
    Documentation for twr-wasm Version 2.0.6
    
+
    Documentation for twr-wasm Version 2.1.0
    
 
    twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web Assembly code directly with clang. It solves some common use cases with less work than the more feature rich emscripten. 
    
 
    twr-wasm is easy to understand, and has some cool features. You can input and print streaming character i/o to a <div> tag, use a <canvas> element as an ANSI terminal, or use a C/C++ 2D drawing api (that is compatible with JavaScript Canvas APIs) to draw to a <canvas> element. You can run blocking C/C++. 
    
 
    twr-wasm allows you to run C/C++ code in a web browser. Legacy code, libraries, full applications, or single functions can be integrated with JavaScript and Typescript.
    
@@ -235,17 +235,17 @@ 
    View Live Web Assembly Demos

    On Github

    https://github.com/twiddlingbits/twr-wasm

    -

    Version 2.0 vs. 1.0

    +

    Version 2 vs. 1

      -
    • libc++ for wasm/clang is now available
      • +
    • libc++ built for Web Assembly is included
    • most of the standard C library is now implemented
      • -
    • instructions for source level debugging
      • +
    • instructions for Web Assembly C/C++ source level debugging
    • version of library with debug symbols provided
    • locale, UTF-8, and windows-1252 support
    -

    Version 2.0.0 Limitations

    +

    Version 2 Limitations

      -
    • libc++ not built with threads, rtti, exceptions, unicode, or wide char support
      • +
    • libc++ not built with exceptions enabled
    • some standard C library functions are not 100% implemented
    • Designed to work with a browser. Not tested with or designed to work with node.js
    • Not all of compile-rt is ported (but most bits you need are)
      • @@ -310,5 +310,5 @@

      Post Feedback

      diff --git a/azure/docsite/more/debugging/index.html b/azure/docsite/more/debugging/index.html index 5c17cec0..1765347c 100644 --- a/azure/docsite/more/debugging/index.html +++ b/azure/docsite/more/debugging/index.html @@ -130,12 +130,12 @@
      -

      Debugging

      +

      Debugging Web Assembly

      This section describes some tips for debugging your Web Assembly (asm) program.

      -

      Debug & Release libs

      +

      Debug and Release libraries

      There are release (twr.a) and debug (twrd.a) versions of the twr-wasm C library. See the examples for use of both. The "debug" version has debug symbols enabled and is built with -O0. The "release" version has no debug symbols and optimization is set to -O3. Both have asserts enabled. In general, you should use the "release" version unless you wish to step through the twr-wasm source -- in which case use the "debug" version.

      libc++.a is not built with debug symbols.

      -

      C/C++ Source Level Debugging

      +

      Source Level Debugging Web Assembly C/C++

      In order to enable C/C++ source debugging with wasm and clang, do the following:

      1. Use Chrome
        2. @@ -148,7 +148,7 @@

        C/C++ Source Level Debugging

      2. you need to ensure that the web server/browser can find the source code
      3. also see Example Readme
      -

      Useful Functions

      +

      Useful twr-wasm Debug Functions

      Use twr_conlog to print 'printf' style to the JavaScript console from C (reference is elsewhere in this doc.)

      #include "twr-wasm.h"
@@ -156,7 +156,7 @@ 
      Useful Functions
      
 twr_conlog("hello 99 in hex: %x",99);

      Use twrWasmModule.divLog() to print to a div inside JavaScript code (reference is elsewhere in this doc.)

      -

      Testing Without a Web Server

      +

      Testing Web Assembly Without a Web Server

      Note: If you use this technique, you will not be able to get the c/C++ DevTool chrome extension to run, and so source level debugging won't work.

      You can execute and debug JavaScript with wasm from local files without an HTTP server. It might be helpful to download the twr-wasm source code from github when you do this (so you can step through the twr-wasm typescript code as needed).

      diff --git a/azure/docsite/search/search_index.json b/azure/docsite/search/search_index.json index d6abf6db..334e01cb 100644 --- a/azure/docsite/search/search_index.json +++ b/azure/docsite/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"twr-wasm - Easy C/C++ Web Assembly Modules Documentation for twr-wasm Version 2.0.6 twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web Assembly code directly with clang. It solves some common use cases with less work than the more feature rich emscripten. twr-wasm is easy to understand, and has some cool features. You can input and print streaming character i/o to a
      tag, use a element as an ANSI terminal, or use a C/C++ 2D drawing api (that is compatible with JavaScript Canvas APIs) to draw to a element. You can run blocking C/C++. twr-wasm allows you to run C/C++ code in a web browser. Legacy code, libraries, full applications, or single functions can be integrated with JavaScript and Typescript. twr-wasm is designed to be used with the standard llvm clang compiler and tools. twr-wasm was previously named tiny-wasm-runtime. View C++ Web Assembly Bouncing Ball Demo View bouncing balls here Key Features compile and link C/C++ for use with web assembly using clang directly standard C library, libc++. and purpose built APIs available from C/C++ TypeScrpt/JavaScript classes to load WASM modules and call C/C++ functions localization support, UTF-8, and windows-1252 support in C/C++, print and get characters to/from
      tags in your HTML page in C/C++, print and get characters to/from a based \"terminal\" in C/C++ use 2D drawing API compatible with JavaScript Canvas in C/C++, use the \"blocking loop\" pattern and integrate with Javascript's asynchronous event loop Why? WASM Runtime Limitations section explains why a library like twr-wasm is needed to use Web Assembly. Hello World Here is the simplest twr-wasm example. C code: #include void hello() { printf(\"hello world\\n\"); } index.html: Hello World
      View Live Web Assembly Demos Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze Source for maze Input from
      View square demo Source Mini-Terminal (hello world using ) View demo Source Mini-Terminal (\"cli\" using libc++ and ) View console Source On Github https://github.com/twiddlingbits/twr-wasm Version 2.0 vs. 1.0 libc++ for wasm/clang is now available most of the standard C library is now implemented instructions for source level debugging version of library with debug symbols provided locale, UTF-8, and windows-1252 support Version 2.0.0 Limitations libc++ not built with threads, rtti, exceptions, unicode, or wide char support some standard C library functions are not 100% implemented Designed to work with a browser. Not tested with or designed to work with node.js Not all of compile-rt is ported (but most bits you need are) The following non-compatible changes since 1.0 (relatively minor) there is no longer 'twr_' prefixed std c lib functions (use the normal std c lib names) most 'twr_wasm_' prefixed functions have been shortened to 'twr_'. some functions were renamed or changed slightly to be more consistent, but no functionality is lost. Post Feedback Please post feedback (it worked for you, didn't work, requests, questions, etc) at https://github.com/twiddlingbits/twr-wasm/","title":"Home"},{"location":"#twr-wasm-easy-cc-web-assembly-modules","text":"Documentation for twr-wasm Version 2.0.6 twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web Assembly code directly with clang. It solves some common use cases with less work than the more feature rich emscripten. twr-wasm is easy to understand, and has some cool features. You can input and print streaming character i/o to a
      tag, use a element as an ANSI terminal, or use a C/C++ 2D drawing api (that is compatible with JavaScript Canvas APIs) to draw to a element. You can run blocking C/C++. twr-wasm allows you to run C/C++ code in a web browser. Legacy code, libraries, full applications, or single functions can be integrated with JavaScript and Typescript. twr-wasm is designed to be used with the standard llvm clang compiler and tools. twr-wasm was previously named tiny-wasm-runtime.","title":"twr-wasm - Easy C/C++ Web Assembly Modules"},{"location":"#view-c-web-assembly-bouncing-ball-demo","text":"View bouncing balls here","title":"View C++ Web Assembly Bouncing Ball Demo"},{"location":"#key-features","text":"compile and link C/C++ for use with web assembly using clang directly standard C library, libc++. and purpose built APIs available from C/C++ TypeScrpt/JavaScript classes to load WASM modules and call C/C++ functions localization support, UTF-8, and windows-1252 support in C/C++, print and get characters to/from
      tags in your HTML page in C/C++, print and get characters to/from a based \"terminal\" in C/C++ use 2D drawing API compatible with JavaScript Canvas in C/C++, use the \"blocking loop\" pattern and integrate with Javascript's asynchronous event loop","title":"Key Features"},{"location":"#why","text":"WASM Runtime Limitations section explains why a library like twr-wasm is needed to use Web Assembly.","title":"Why?"},{"location":"#hello-world","text":"Here is the simplest twr-wasm example. C code: #include void hello() { printf(\"hello world\\n\"); } index.html: Hello World
      ","title":"Hello World"},{"location":"#view-live-web-assembly-demos","text":"Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze Source for maze Input from
      View square demo Source Mini-Terminal (hello world using ) View demo Source Mini-Terminal (\"cli\" using libc++ and ) View console Source","title":"View Live Web Assembly Demos"},{"location":"#on-github","text":"https://github.com/twiddlingbits/twr-wasm","title":"On Github"},{"location":"#version-20-vs-10","text":"libc++ for wasm/clang is now available most of the standard C library is now implemented instructions for source level debugging version of library with debug symbols provided locale, UTF-8, and windows-1252 support","title":"Version 2.0 vs. 1.0"},{"location":"#version-200-limitations","text":"libc++ not built with threads, rtti, exceptions, unicode, or wide char support some standard C library functions are not 100% implemented Designed to work with a browser. Not tested with or designed to work with node.js Not all of compile-rt is ported (but most bits you need are) The following non-compatible changes since 1.0 (relatively minor) there is no longer 'twr_' prefixed std c lib functions (use the normal std c lib names) most 'twr_wasm_' prefixed functions have been shortened to 'twr_'. some functions were renamed or changed slightly to be more consistent, but no functionality is lost.","title":"Version 2.0.0 Limitations"},{"location":"#post-feedback","text":"Please post feedback (it worked for you, didn't work, requests, questions, etc) at https://github.com/twiddlingbits/twr-wasm/","title":"Post Feedback"},{"location":"api/api-c-con/","text":"Console API for Web Assembly (Streamed and Windowed) This section describes twr-wasm's method of providing and abstracting console I/O in Web Assembly Modules. C character based input/output is abstracted by struct IoConsole . Consoles can be \"tty\" aka \"streamed\", or they can be \"windowed\" (aka a \"terminal\"). Also see stdio Examples Name View Live Link Source Link \"terminal\" in/out with a View mini-term demo Source Getting stderr,stdin, stdout stdio.h defines stdin , stdout , stderr as explained here: stdio stdio.h also defines FILE like this: typedef struct IoConsole FILE; from : #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) Getting a new console stdin and stdout are set as explaind here . However, in unusual cases you might want to access the various consoles directly, regardless of how stdin, stdout, or stderr are set. You can do so like this: io_nullcon Returns an IoConsole that goes to the bit bucket. io_getc32 will return 0. #include \"twr-io.h\" struct IoConsole* io_nullcon(void); twr_debugcon Returns an IoConsole that goes to the browser's debug console. #include \"twr-crt.h\" struct IoConsole* twr_debugcon(void); twr_divcon Returns an IoConsole that goes to
      , if it exists. #include \"twr-crt.h\" struct IoConsole* twr_divcon(void); twr_windowcon Returns an IoConsole that goes to , if it exists. NOTE: Only one call can be made to this function, and it is usually made by the twr-wasm C runtime, so you likely won't call this function. #include \"twr-crt.h\" struct IoConsole* twr_windowcon(void); IO Console Functions io_putc Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_putc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_putc once for each byte of the multi-byte UTF-8 character). Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. #include \"twr-io.h\" void io_putc(struct IoConsole* io, unsigned char c); io_putstr Calls io_putc for each byte in the passed string. #include \"twr-io.h\" void io_putstr(struct IoConsole* io, const char* s); io_printf Identical to fprintf , however io_printf will call io_begin_draw and io_end_draw around its drawing activities -- resulting in snapper performance. For example: #include \"twr-io.h\" io_printf(twr_debugcon(), \"hello over there in browser debug console land\\n\"); or #include #include io_printf(stdout, \"hello world\\n\"); #include void io_printf(struct IoConsole *io, const char *format, ...); io_getc32 Waits for the user to enter and then returns a unicode code point. Currently only really works with an IoConsole that is stdin. To return characters encoded with the current locale, see io_mbgetc #include int io_getc32(struct IoConsole* io); io_mbgetc io_mbgetc will get a character from stdin and encode it using the character encoding of the LC_CTYPE category of the current locale. \"C\" will use ASCII. UTF-8 and windows-1252 are also supported. #include void io_mbgetc(struct IoConsole* io, char* strout); io_mbgets Gets a string from an IoConsole (which needs to be stdin). Returns when the user presses \"Enter\". Displays a cursor character and echos the inputted characters, at the current cursor position. Uses character encoding of LC_TYPE of current locale. #include char *io_mbgets(struct IoConsole* io, char *buffer ); io_get_cursor Returns an integer of the current cursor position. The cursor is where the next io_putc is going to go. For windowed consoles, the cursor position ranges from [0, width*height-1], inclusive. #include int io_get_cursor(struct IoConsole* io); io_set_colors For windowed consoles only. Sets a 24 bit RGB default color for the foreground and background. The prior default colors are changed (lost). For example, if you set the default colors when you created the window (see stdio ), the defaults will no longer be active. Use io_get_colors to save existing colors for later restoration using io_set_colors . A call to io_set_colors doesn't actually cause any on screen changes. Instead, these new default colors are used in future draw and text calls. A foreground and background color is set for each cell in the console window. The cell's colors are set to these default foreground/background colors when a call to io_setc , io_setreset , etc is made. #include void io_set_colors(struct IoConsole* io, unsigned long foreground, unsigned long background); io_get_colors For windowed consoles only. Gets the current default colors. #include void io_get_colors(struct IoConsole* io, unsigned long *foreground, unsigned long *background); io_cls For windowed consoles only. Clears the screen. That is, all character cells in the window are set to a space, their colors are reset to the current default colors (see io_set_colors ). #include void io_cls(struct IoConsoleWindow* iow); io_setc For windowed consoles only. Sets a window cell to a character. Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_setc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_setc once for each byte of the multi-byte UTF-8 character). #include bool io_setc(struct IoConsoleWindow* iow, int location, unsigned char c); io_setc32 For windowed consoles only. Sets a window cell to a unicode code point. The colors are set to the defaults (see io_set_colors ). #include void io_setc32(struct IoConsoleWindow* iow, int location, int c); io_setreset For windowed consoles only. Sets or resets (clears) a chunky graphics \"pixel\". Each character cell can also be a 2x3 grid of graphic \"pixels\". In other words, the terminal window has pixel dimensions of width 2 x height 3. The color will be set to the defaults if the impacted cell is not a graphics cell. If it is an existing graphics cell, the colors don't change. See the stdio-canvas example. #include bool io_setreset(struct IoConsoleWindow* iow, int x, int y, bool isset); io_point For windowed consoles only. Checks if a chunky graphics \"pixel\" is set or clear. See io_setreset . #include bool io_point(struct IoConsoleWindow* iow, int x, int y); io_set_cursor Moves the cursor. See io_get_cursor . #include void io_set_cursor(struct IoConsoleWindow* iow, int loc); io_begin_draw For windowed consoles only. This call (and its matching io_end_draw) are not required. But if you bracket any call sequence that draws to the terminal window with an io_begin_draw and io_end_draw , the updates will be batched into one update. io_begin_draw can be nested. This will increase performance and usually prevents the user from seeing partial updates. See the terminal-window io_canvas example. #include void io_begin_draw(struct IoConsole* io); io_end_draw For windowed consoles only. See io_begin_draw . #include void io_end_draw(struct IoConsole* io);","title":"C Console I/O"},{"location":"api/api-c-con/#console-api-for-web-assembly-streamed-and-windowed","text":"This section describes twr-wasm's method of providing and abstracting console I/O in Web Assembly Modules. C character based input/output is abstracted by struct IoConsole . Consoles can be \"tty\" aka \"streamed\", or they can be \"windowed\" (aka a \"terminal\"). Also see stdio","title":"Console API for Web Assembly (Streamed and Windowed)"},{"location":"api/api-c-con/#examples","text":"Name View Live Link Source Link \"terminal\" in/out with a View mini-term demo Source","title":"Examples"},{"location":"api/api-c-con/#getting-stderrstdin-stdout","text":"stdio.h defines stdin , stdout , stderr as explained here: stdio stdio.h also defines FILE like this: typedef struct IoConsole FILE; from : #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con())","title":"Getting stderr,stdin, stdout"},{"location":"api/api-c-con/#getting-a-new-console","text":"stdin and stdout are set as explaind here . However, in unusual cases you might want to access the various consoles directly, regardless of how stdin, stdout, or stderr are set. You can do so like this:","title":"Getting a new console"},{"location":"api/api-c-con/#io_nullcon","text":"Returns an IoConsole that goes to the bit bucket. io_getc32 will return 0. #include \"twr-io.h\" struct IoConsole* io_nullcon(void);","title":"io_nullcon"},{"location":"api/api-c-con/#twr_debugcon","text":"Returns an IoConsole that goes to the browser's debug console. #include \"twr-crt.h\" struct IoConsole* twr_debugcon(void);","title":"twr_debugcon"},{"location":"api/api-c-con/#twr_divcon","text":"Returns an IoConsole that goes to
      , if it exists. #include \"twr-crt.h\" struct IoConsole* twr_divcon(void);","title":"twr_divcon"},{"location":"api/api-c-con/#twr_windowcon","text":"Returns an IoConsole that goes to , if it exists. NOTE: Only one call can be made to this function, and it is usually made by the twr-wasm C runtime, so you likely won't call this function. #include \"twr-crt.h\" struct IoConsole* twr_windowcon(void);","title":"twr_windowcon"},{"location":"api/api-c-con/#io-console-functions","text":"","title":"IO Console Functions"},{"location":"api/api-c-con/#io_putc","text":"Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_putc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_putc once for each byte of the multi-byte UTF-8 character). Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. #include \"twr-io.h\" void io_putc(struct IoConsole* io, unsigned char c);","title":"io_putc"},{"location":"api/api-c-con/#io_putstr","text":"Calls io_putc for each byte in the passed string. #include \"twr-io.h\" void io_putstr(struct IoConsole* io, const char* s);","title":"io_putstr"},{"location":"api/api-c-con/#io_printf","text":"Identical to fprintf , however io_printf will call io_begin_draw and io_end_draw around its drawing activities -- resulting in snapper performance. For example: #include \"twr-io.h\" io_printf(twr_debugcon(), \"hello over there in browser debug console land\\n\"); or #include #include io_printf(stdout, \"hello world\\n\"); #include void io_printf(struct IoConsole *io, const char *format, ...);","title":"io_printf"},{"location":"api/api-c-con/#io_getc32","text":"Waits for the user to enter and then returns a unicode code point. Currently only really works with an IoConsole that is stdin. To return characters encoded with the current locale, see io_mbgetc #include int io_getc32(struct IoConsole* io);","title":"io_getc32"},{"location":"api/api-c-con/#io_mbgetc","text":"io_mbgetc will get a character from stdin and encode it using the character encoding of the LC_CTYPE category of the current locale. \"C\" will use ASCII. UTF-8 and windows-1252 are also supported. #include void io_mbgetc(struct IoConsole* io, char* strout);","title":"io_mbgetc"},{"location":"api/api-c-con/#io_mbgets","text":"Gets a string from an IoConsole (which needs to be stdin). Returns when the user presses \"Enter\". Displays a cursor character and echos the inputted characters, at the current cursor position. Uses character encoding of LC_TYPE of current locale. #include char *io_mbgets(struct IoConsole* io, char *buffer );","title":"io_mbgets"},{"location":"api/api-c-con/#io_get_cursor","text":"Returns an integer of the current cursor position. The cursor is where the next io_putc is going to go. For windowed consoles, the cursor position ranges from [0, width*height-1], inclusive. #include int io_get_cursor(struct IoConsole* io);","title":"io_get_cursor"},{"location":"api/api-c-con/#io_set_colors","text":"For windowed consoles only. Sets a 24 bit RGB default color for the foreground and background. The prior default colors are changed (lost). For example, if you set the default colors when you created the window (see stdio ), the defaults will no longer be active. Use io_get_colors to save existing colors for later restoration using io_set_colors . A call to io_set_colors doesn't actually cause any on screen changes. Instead, these new default colors are used in future draw and text calls. A foreground and background color is set for each cell in the console window. The cell's colors are set to these default foreground/background colors when a call to io_setc , io_setreset , etc is made. #include void io_set_colors(struct IoConsole* io, unsigned long foreground, unsigned long background);","title":"io_set_colors"},{"location":"api/api-c-con/#io_get_colors","text":"For windowed consoles only. Gets the current default colors. #include void io_get_colors(struct IoConsole* io, unsigned long *foreground, unsigned long *background);","title":"io_get_colors"},{"location":"api/api-c-con/#io_cls","text":"For windowed consoles only. Clears the screen. That is, all character cells in the window are set to a space, their colors are reset to the current default colors (see io_set_colors ). #include void io_cls(struct IoConsoleWindow* iow);","title":"io_cls"},{"location":"api/api-c-con/#io_setc","text":"For windowed consoles only. Sets a window cell to a character. Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_setc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_setc once for each byte of the multi-byte UTF-8 character). #include bool io_setc(struct IoConsoleWindow* iow, int location, unsigned char c);","title":"io_setc"},{"location":"api/api-c-con/#io_setc32","text":"For windowed consoles only. Sets a window cell to a unicode code point. The colors are set to the defaults (see io_set_colors ). #include void io_setc32(struct IoConsoleWindow* iow, int location, int c);","title":"io_setc32"},{"location":"api/api-c-con/#io_setreset","text":"For windowed consoles only. Sets or resets (clears) a chunky graphics \"pixel\". Each character cell can also be a 2x3 grid of graphic \"pixels\". In other words, the terminal window has pixel dimensions of width 2 x height 3. The color will be set to the defaults if the impacted cell is not a graphics cell. If it is an existing graphics cell, the colors don't change. See the stdio-canvas example. #include bool io_setreset(struct IoConsoleWindow* iow, int x, int y, bool isset);","title":"io_setreset"},{"location":"api/api-c-con/#io_point","text":"For windowed consoles only. Checks if a chunky graphics \"pixel\" is set or clear. See io_setreset . #include bool io_point(struct IoConsoleWindow* iow, int x, int y);","title":"io_point"},{"location":"api/api-c-con/#io_set_cursor","text":"Moves the cursor. See io_get_cursor . #include void io_set_cursor(struct IoConsoleWindow* iow, int loc);","title":"io_set_cursor"},{"location":"api/api-c-con/#io_begin_draw","text":"For windowed consoles only. This call (and its matching io_end_draw) are not required. But if you bracket any call sequence that draws to the terminal window with an io_begin_draw and io_end_draw , the updates will be batched into one update. io_begin_draw can be nested. This will increase performance and usually prevents the user from seeing partial updates. See the terminal-window io_canvas example. #include void io_begin_draw(struct IoConsole* io);","title":"io_begin_draw"},{"location":"api/api-c-con/#io_end_draw","text":"For windowed consoles only. See io_begin_draw . #include void io_end_draw(struct IoConsole* io);","title":"io_end_draw"},{"location":"api/api-c-d2d/","text":"2D Draw API for Web Assembly This section describes twr-wasm's C D2D API, which allows your Web Assembly module to call many of the JavaScript Canvas APIs. There is also a C++ canvas wrapper class in the balls example. Examples Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze here Source for maze Overview Add a canvas tag to your HTML named twr_d2dcanvas like this example (you can use any width/height you like): To draw using the C API: - call d2d_start_draw_sequence() - call draw commands, like d2d_fillrect() - call d2d_end_draw_sequence() Commands are queued until flush'd, which will take the batch of queued draw cmds, and execute them. In the case of twrWasmModuleAsync, the batch of commands is sent over to the JavaScript main thread for execution. By batching the calls, performance is improved. Flush() waits for the commands to finish execution before returning. Flush() is called automatically by d2d_end_draw_sequence(). You pass an argument to d2d_start_draw_sequence() specifying how many instructions will trigger an automatic flush. You can make this larger for efficiency, or smaller if you want to see the render progress with more frequently. There is no limit on the size of the queue, except memory used in the wasm module. There is a flush() function that you can manually call, but it is not normally needed, unless you would like to ensure a sequence renders before d2d_end_draw_sequence() is called, or before the count passed d2d_start_draw_sequence() is met. If you are using twrWasmModuleAsync, or if you are re-rendering the entire frame for each animation update, you should ensure that all of your draws for a single complete frame are made without a call to flush() in the middle of the draw operations, as this may cause flashing. Functions These are the Canvas APIs currently available in C: struct d2d_draw_seq* d2d_start_draw_sequence(int flush_at_ins_count); void d2d_end_draw_sequence(struct d2d_draw_seq* ds); void d2d_flush(struct d2d_draw_seq* ds); int d2d_get_canvas_prop(const char* prop); void d2d_fillrect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_strokerect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_filltext(struct d2d_draw_seq* ds, const char* str, double x, double y); void d2d_fillcodepoint(struct d2d_draw_seq* ds, char c, double x, double y); void d2d_measuretext(struct d2d_draw_seq* ds, const char* str, struct d2d_text_metrics *tm); void d2d_save(struct d2d_draw_seq* ds); void d2d_restore(struct d2d_draw_seq* ds); void d2d_setlinewidth(struct d2d_draw_seq* ds, double width); void d2d_setfillstylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setstrokestylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setfillstyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setstrokestyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setfont(struct d2d_draw_seq* ds, const char* font); void d2d_createlineargradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double x1, double y1); void d2d_createradialgradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double radius0, double x1, double y1, double radius1); void d2d_addcolorstop(struct d2d_draw_seq* ds, long gradID, long position, const char* csscolor); void d2d_setfillstylegradient(struct d2d_draw_seq* ds, long gradID); void d2d_releaseid(struct d2d_draw_seq* ds, long id); void d2d_beginpath(struct d2d_draw_seq* ds); void d2d_fill(struct d2d_draw_seq* ds); void d2d_stroke(struct d2d_draw_seq* ds); void d2d_moveto(struct d2d_draw_seq* ds, double x, double y); void d2d_lineto(struct d2d_draw_seq* ds, double x, double y); void d2d_arc(struct d2d_draw_seq* ds, double x, double y, double radius, double start_angle, double end_angle, bool counterclockwise); void d2d_bezierto(struct d2d_draw_seq* ds, double cp1x, double cp1y, double cp2x, double cp2y, double x, double y); void d2d_imagedata(struct d2d_draw_seq* ds, long id, void* mem, unsigned long length, unsigned long width, unsigned long height); void d2d_putimagedata(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy); void d2d_putimagedatadirty(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy, unsigned long dirtyX, unsigned long dirtyY, unsigned long dirtyWidth, unsigned long dirtyHeight); d2d_measuretext() returns this structure: struct d2d_text_metrics { double actualBoundingBoxAscent; double actualBoundingBoxDescent; double actualBoundingBoxLeft; double actualBoundingBoxRight; double fontBoundingBoxAscent; double fontBoundingBoxDescent; double width; }; d2d_get_canvas_prop() returns a value of: export interface ICanvasProps { charWidth: number, charHeight: number, foreColor: number, backColor: number, widthInChars: number, heightInChars: number, canvasWidth:number, canvasHeight:number }","title":"C Draw 2D"},{"location":"api/api-c-d2d/#2d-draw-api-for-web-assembly","text":"This section describes twr-wasm's C D2D API, which allows your Web Assembly module to call many of the JavaScript Canvas APIs. There is also a C++ canvas wrapper class in the balls example.","title":"2D Draw API for Web Assembly"},{"location":"api/api-c-d2d/#examples","text":"Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze here Source for maze","title":"Examples"},{"location":"api/api-c-d2d/#overview","text":"Add a canvas tag to your HTML named twr_d2dcanvas like this example (you can use any width/height you like): To draw using the C API: - call d2d_start_draw_sequence() - call draw commands, like d2d_fillrect() - call d2d_end_draw_sequence() Commands are queued until flush'd, which will take the batch of queued draw cmds, and execute them. In the case of twrWasmModuleAsync, the batch of commands is sent over to the JavaScript main thread for execution. By batching the calls, performance is improved. Flush() waits for the commands to finish execution before returning. Flush() is called automatically by d2d_end_draw_sequence(). You pass an argument to d2d_start_draw_sequence() specifying how many instructions will trigger an automatic flush. You can make this larger for efficiency, or smaller if you want to see the render progress with more frequently. There is no limit on the size of the queue, except memory used in the wasm module. There is a flush() function that you can manually call, but it is not normally needed, unless you would like to ensure a sequence renders before d2d_end_draw_sequence() is called, or before the count passed d2d_start_draw_sequence() is met. If you are using twrWasmModuleAsync, or if you are re-rendering the entire frame for each animation update, you should ensure that all of your draws for a single complete frame are made without a call to flush() in the middle of the draw operations, as this may cause flashing.","title":"Overview"},{"location":"api/api-c-d2d/#functions","text":"These are the Canvas APIs currently available in C: struct d2d_draw_seq* d2d_start_draw_sequence(int flush_at_ins_count); void d2d_end_draw_sequence(struct d2d_draw_seq* ds); void d2d_flush(struct d2d_draw_seq* ds); int d2d_get_canvas_prop(const char* prop); void d2d_fillrect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_strokerect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_filltext(struct d2d_draw_seq* ds, const char* str, double x, double y); void d2d_fillcodepoint(struct d2d_draw_seq* ds, char c, double x, double y); void d2d_measuretext(struct d2d_draw_seq* ds, const char* str, struct d2d_text_metrics *tm); void d2d_save(struct d2d_draw_seq* ds); void d2d_restore(struct d2d_draw_seq* ds); void d2d_setlinewidth(struct d2d_draw_seq* ds, double width); void d2d_setfillstylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setstrokestylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setfillstyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setstrokestyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setfont(struct d2d_draw_seq* ds, const char* font); void d2d_createlineargradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double x1, double y1); void d2d_createradialgradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double radius0, double x1, double y1, double radius1); void d2d_addcolorstop(struct d2d_draw_seq* ds, long gradID, long position, const char* csscolor); void d2d_setfillstylegradient(struct d2d_draw_seq* ds, long gradID); void d2d_releaseid(struct d2d_draw_seq* ds, long id); void d2d_beginpath(struct d2d_draw_seq* ds); void d2d_fill(struct d2d_draw_seq* ds); void d2d_stroke(struct d2d_draw_seq* ds); void d2d_moveto(struct d2d_draw_seq* ds, double x, double y); void d2d_lineto(struct d2d_draw_seq* ds, double x, double y); void d2d_arc(struct d2d_draw_seq* ds, double x, double y, double radius, double start_angle, double end_angle, bool counterclockwise); void d2d_bezierto(struct d2d_draw_seq* ds, double cp1x, double cp1y, double cp2x, double cp2y, double x, double y); void d2d_imagedata(struct d2d_draw_seq* ds, long id, void* mem, unsigned long length, unsigned long width, unsigned long height); void d2d_putimagedata(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy); void d2d_putimagedatadirty(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy, unsigned long dirtyX, unsigned long dirtyY, unsigned long dirtyWidth, unsigned long dirtyHeight); d2d_measuretext() returns this structure: struct d2d_text_metrics { double actualBoundingBoxAscent; double actualBoundingBoxDescent; double actualBoundingBoxLeft; double actualBoundingBoxRight; double fontBoundingBoxAscent; double fontBoundingBoxDescent; double width; }; d2d_get_canvas_prop() returns a value of: export interface ICanvasProps { charWidth: number, charHeight: number, foreColor: number, backColor: number, widthInChars: number, heightInChars: number, canvasWidth:number, canvasHeight:number }","title":"Functions"},{"location":"api/api-c-general/","text":"General C API for WASM Overview This sections describes the \"general\" twr-wasm functions available that don't fit neatly into another category (such as standard C library functions, Draw 2D functions, etc.) These functions often start with \"twr_\" and are generally found in this include file: \\twr-wasm\\include\\twr-crt.h bzero Set a block of memory to zeros. Calls memset(to, 0, count) . #include void bzero (void *to, size_t count); getc This is the standard c library function (see the the standard library docs available on the internet). Of note this function will return extended ASCII (128-255 inclusive). The extend ASCII are always encoded with Windows-1252 encoding. See twr_getc32 for a list of related functions. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. twr_atod Similar to stdlib atof . #include \"twr-crt.h\" double twr_atod(const char* str); twr_atou64 Convert a string to a 64 bit unsigned integer, stopping when the first non-valid character is encountered. If len is provided, it will be set to the number of characters read. Radix should be >=2 and <=36 -- for example, 10 is a normal base 10 number and 16 is hexadecimal. #include \"twr-crt.h\" int64_t twr_atou64(const char *str, int* len, int radix); twr_dtoa The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed #include \"twr-crt.h\" void twr_dtoa(char* buffer, int sizeInBytes, double value, int max_precision); twr_cache_malloc/free These functions keep allocated memory in a cache for much faster re-access than the standard malloc/free. #include \"twr-crt.h\" void *twr_cache_malloc(twr_size_t size); void twr_cache_free(void* mem); twr_code_page_to_utf32_streamed Return a unicode code point (aka utf-32 value) when passed a byte stream that represents an encoded character using the current local's LC_CTYPE code page. A zero is returned if the byte stream has not yet completed a decode. For example: int cp setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region // turn a UTF-8 Euro into a UTF-32 value cp==twr_code_page_to_utf32_streamed(0xE2); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0x82); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0xAC); assert (cp==0x000020AC); // Euro Code points #include int twr_code_page_to_utf32_streamed(unsigned char byte) twr_conlog twr_conlog prints debug messages to the browser console from your C code. #include \"twr-crt.h\" void twr_conlog(char* format, ...); Each call to twr_conlog() will generate a single call to console.log() in JavaScript to ensure that you see debug prints. This call is identical to printf, except that it adds a newline. The current implementation does not wait for the debug string to output to the console before returning from twr_conlog, when using twrWasmModuleAsync. In this case, it can take a small bit of time for the string to make its way across the Worker Thread boundary. This is normally not a problem and results in faster performance. But if your code crashes soon after the debug print, the print might not appear. If you think this is an issue, you can call twr_sleep(1) after your twr_conlog call. This will force a blocking wait for the print to print. Prior to 1.0, this function was called twr_dbg_printf , and operated slightly differently. twr_epoch_timems Returns the number of milliseconds since the start of the epoch. #include \"twr-wasm.h\" uint64_t twr_epoch_timems(); twr_getc32 Gets a 32 bit unicode code point character from stdin . Unlike the standard C library function getchar , twr_getc32 does not buffer a line (that is, twr_getc32 will return a character before the user presses Enter). twr_getc32 is implemented as: int twr_getc32() { return io_getc32(twr_get_stdio_con()); } Note that stdlib getchar and ungetc are not currently implemented. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. Also see: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) #include \"twr-crt.h\" int twr_getc32(); twr_get_navlang Returns the BCP 47 language tag as found in javacript navigator.language . If len is not null, it will be filled in with the string length of the language tag. #include \"twr-crt.h\" const char* twr_get_navlang(int *len); twr_get_current_locale extern inline locale_t twr_get_current_locale(void); twr_get_current_locale will return the locale that has been set by setlocale . It can be used to pass to a function that takes a locale_t. twr_localize_numeric_string Functions like twr_dtoa do not localize the decimal point. To get a localized decimal point, you can use printf , or alternately twr_localize_numeric_string to post process a string. For example: char b[10]; strcpy(b, \"1.23\"); twr_localize_numeric_string(b, twr_get_current_locale()); // if locale was set to french, then b is now 1,23 #include void twr_localize_numeric_string(char* str, locale_t locale); twr_mem_debug_stats Print memory map and malloc stats to stderr or stdout. (note FILE * is the same as struct IoConsole*) #include void twr_mem_debug_stats(struct IoConsole* outcon); twr_mbgets Gets a string from stdin . The string will be in the current locale's character encoding -- ASCII for \"C\", and either UTF-8 or windows-1252 for \"\". See localization . #include \"twr-crt.h\" char* twr_mbgets(char* buffer); Internally this function uses the stdio IoConsole -- see the IoConsole section for more advanced input/output. This function will encode characters as specified by the LC_CTYPE category of the current locale. ASCII is used for \"C\", and UTF-8 and Windows-1252 are also supported (see localization ) Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. twr_mbslen_l Returns the number of characters in a string using the character encoding of the passed locale (ASCII for \"C\", UTF-8, or windows-1252 for \"\"). You can use twr_get_current_locale to find the current locale. #include size_t twr_mbslen_l(const char *str, locale_t locale); twr_sleep twr_sleep is a traditional blocking sleep function. This function is blocking, and you must use twrWasmModuleAsync. #include \"twr-wasm.h\" void twr_sleep(int ms); twr_tofixed This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_tofixed(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed twr_toexponential This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_toexponential(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed twr_strhorizflip Mirror image the passed in string. #include \"twr-crt.h\" void twr_strhorizflip(char * buffer, int n); twr_utf8_char_len Returns the number of bytes in a UTF-8 character (passed as a string pointer). UTF-8 characters can be 1 to 4 bytes in length. #include int twr_utf8_char_len(const char *str); twr_utf32_to_code_page Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page. For example: char strbuf[6]; // max size of utf-8 is 4+terminating zero. Max size of ASCII or windows 1252 is 1 + terminating zero setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region twr_utf32_to_code_page(strbuf, 0x000020AC); // encode a Euro code point printf(\"%s\", strbuf); assert ( strcmp(strbuf,\"\\xE2\\x82\\xAC\")==0 ); // utf-8 encoding of euro assert ( strcmp(strbuf,\"\u20ac\")==0 ); // clang string literals default to utf-8 encoding include void twr_utf32_to_code_page(char* out, int utf32) twr_vprintf Performs a printf by calling the callback with cbdata for each character. #include \"twr-crt.h\" void twr_vprintf(twr_cbprintf_callback out, void* cbdata, const char *format, va_list* args); floating math helpers int twr_isnan(double v); int twr_isinf(double v); double twr_nanval(); double twr_infval();","title":"C General"},{"location":"api/api-c-general/#general-c-api-for-wasm","text":"","title":"General C API for WASM"},{"location":"api/api-c-general/#overview","text":"This sections describes the \"general\" twr-wasm functions available that don't fit neatly into another category (such as standard C library functions, Draw 2D functions, etc.) These functions often start with \"twr_\" and are generally found in this include file: \\twr-wasm\\include\\twr-crt.h","title":"Overview"},{"location":"api/api-c-general/#bzero","text":"Set a block of memory to zeros. Calls memset(to, 0, count) . #include void bzero (void *to, size_t count);","title":"bzero"},{"location":"api/api-c-general/#getc","text":"This is the standard c library function (see the the standard library docs available on the internet). Of note this function will return extended ASCII (128-255 inclusive). The extend ASCII are always encoded with Windows-1252 encoding. See twr_getc32 for a list of related functions. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input.","title":"getc"},{"location":"api/api-c-general/#twr_atod","text":"Similar to stdlib atof . #include \"twr-crt.h\" double twr_atod(const char* str);","title":"twr_atod"},{"location":"api/api-c-general/#twr_atou64","text":"Convert a string to a 64 bit unsigned integer, stopping when the first non-valid character is encountered. If len is provided, it will be set to the number of characters read. Radix should be >=2 and <=36 -- for example, 10 is a normal base 10 number and 16 is hexadecimal. #include \"twr-crt.h\" int64_t twr_atou64(const char *str, int* len, int radix);","title":"twr_atou64"},{"location":"api/api-c-general/#twr_dtoa","text":"The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed #include \"twr-crt.h\" void twr_dtoa(char* buffer, int sizeInBytes, double value, int max_precision);","title":"twr_dtoa"},{"location":"api/api-c-general/#twr_cache_mallocfree","text":"These functions keep allocated memory in a cache for much faster re-access than the standard malloc/free. #include \"twr-crt.h\" void *twr_cache_malloc(twr_size_t size); void twr_cache_free(void* mem);","title":"twr_cache_malloc/free"},{"location":"api/api-c-general/#twr_code_page_to_utf32_streamed","text":"Return a unicode code point (aka utf-32 value) when passed a byte stream that represents an encoded character using the current local's LC_CTYPE code page. A zero is returned if the byte stream has not yet completed a decode. For example: int cp setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region // turn a UTF-8 Euro into a UTF-32 value cp==twr_code_page_to_utf32_streamed(0xE2); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0x82); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0xAC); assert (cp==0x000020AC); // Euro Code points #include int twr_code_page_to_utf32_streamed(unsigned char byte)","title":"twr_code_page_to_utf32_streamed"},{"location":"api/api-c-general/#twr_conlog","text":"twr_conlog prints debug messages to the browser console from your C code. #include \"twr-crt.h\" void twr_conlog(char* format, ...); Each call to twr_conlog() will generate a single call to console.log() in JavaScript to ensure that you see debug prints. This call is identical to printf, except that it adds a newline. The current implementation does not wait for the debug string to output to the console before returning from twr_conlog, when using twrWasmModuleAsync. In this case, it can take a small bit of time for the string to make its way across the Worker Thread boundary. This is normally not a problem and results in faster performance. But if your code crashes soon after the debug print, the print might not appear. If you think this is an issue, you can call twr_sleep(1) after your twr_conlog call. This will force a blocking wait for the print to print. Prior to 1.0, this function was called twr_dbg_printf , and operated slightly differently.","title":"twr_conlog"},{"location":"api/api-c-general/#twr_epoch_timems","text":"Returns the number of milliseconds since the start of the epoch. #include \"twr-wasm.h\" uint64_t twr_epoch_timems();","title":"twr_epoch_timems"},{"location":"api/api-c-general/#twr_getc32","text":"Gets a 32 bit unicode code point character from stdin . Unlike the standard C library function getchar , twr_getc32 does not buffer a line (that is, twr_getc32 will return a character before the user presses Enter). twr_getc32 is implemented as: int twr_getc32() { return io_getc32(twr_get_stdio_con()); } Note that stdlib getchar and ungetc are not currently implemented. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. Also see: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) #include \"twr-crt.h\" int twr_getc32();","title":"twr_getc32"},{"location":"api/api-c-general/#twr_get_navlang","text":"Returns the BCP 47 language tag as found in javacript navigator.language . If len is not null, it will be filled in with the string length of the language tag. #include \"twr-crt.h\" const char* twr_get_navlang(int *len);","title":"twr_get_navlang"},{"location":"api/api-c-general/#twr_get_current_locale","text":"extern inline locale_t twr_get_current_locale(void); twr_get_current_locale will return the locale that has been set by setlocale . It can be used to pass to a function that takes a locale_t.","title":"twr_get_current_locale"},{"location":"api/api-c-general/#twr_localize_numeric_string","text":"Functions like twr_dtoa do not localize the decimal point. To get a localized decimal point, you can use printf , or alternately twr_localize_numeric_string to post process a string. For example: char b[10]; strcpy(b, \"1.23\"); twr_localize_numeric_string(b, twr_get_current_locale()); // if locale was set to french, then b is now 1,23 #include void twr_localize_numeric_string(char* str, locale_t locale);","title":"twr_localize_numeric_string"},{"location":"api/api-c-general/#twr_mem_debug_stats","text":"Print memory map and malloc stats to stderr or stdout. (note FILE * is the same as struct IoConsole*) #include void twr_mem_debug_stats(struct IoConsole* outcon);","title":"twr_mem_debug_stats"},{"location":"api/api-c-general/#twr_mbgets","text":"Gets a string from stdin . The string will be in the current locale's character encoding -- ASCII for \"C\", and either UTF-8 or windows-1252 for \"\". See localization . #include \"twr-crt.h\" char* twr_mbgets(char* buffer); Internally this function uses the stdio IoConsole -- see the IoConsole section for more advanced input/output. This function will encode characters as specified by the LC_CTYPE category of the current locale. ASCII is used for \"C\", and UTF-8 and Windows-1252 are also supported (see localization ) Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input.","title":"twr_mbgets"},{"location":"api/api-c-general/#twr_mbslen_l","text":"Returns the number of characters in a string using the character encoding of the passed locale (ASCII for \"C\", UTF-8, or windows-1252 for \"\"). You can use twr_get_current_locale to find the current locale. #include size_t twr_mbslen_l(const char *str, locale_t locale);","title":"twr_mbslen_l"},{"location":"api/api-c-general/#twr_sleep","text":"twr_sleep is a traditional blocking sleep function. This function is blocking, and you must use twrWasmModuleAsync. #include \"twr-wasm.h\" void twr_sleep(int ms);","title":"twr_sleep"},{"location":"api/api-c-general/#twr_tofixed","text":"This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_tofixed(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed","title":"twr_tofixed"},{"location":"api/api-c-general/#twr_toexponential","text":"This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_toexponential(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed","title":"twr_toexponential"},{"location":"api/api-c-general/#twr_strhorizflip","text":"Mirror image the passed in string. #include \"twr-crt.h\" void twr_strhorizflip(char * buffer, int n);","title":"twr_strhorizflip"},{"location":"api/api-c-general/#twr_utf8_char_len","text":"Returns the number of bytes in a UTF-8 character (passed as a string pointer). UTF-8 characters can be 1 to 4 bytes in length. #include int twr_utf8_char_len(const char *str);","title":"twr_utf8_char_len"},{"location":"api/api-c-general/#twr_utf32_to_code_page","text":"Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page. For example: char strbuf[6]; // max size of utf-8 is 4+terminating zero. Max size of ASCII or windows 1252 is 1 + terminating zero setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region twr_utf32_to_code_page(strbuf, 0x000020AC); // encode a Euro code point printf(\"%s\", strbuf); assert ( strcmp(strbuf,\"\\xE2\\x82\\xAC\")==0 ); // utf-8 encoding of euro assert ( strcmp(strbuf,\"\u20ac\")==0 ); // clang string literals default to utf-8 encoding include void twr_utf32_to_code_page(char* out, int utf32)","title":"twr_utf32_to_code_page"},{"location":"api/api-c-general/#twr_vprintf","text":"Performs a printf by calling the callback with cbdata for each character. #include \"twr-crt.h\" void twr_vprintf(twr_cbprintf_callback out, void* cbdata, const char *format, va_list* args);","title":"twr_vprintf"},{"location":"api/api-c-general/#floating-math-helpers","text":"int twr_isnan(double v); int twr_isinf(double v); double twr_nanval(); double twr_infval();","title":"floating math helpers"},{"location":"api/api-c-stdlib/","text":"Standard C library for Web Assembly This section describes twr-wasm's support for the Standard C Library. twr-wasm includes its own implementation of the standard C library optimized for Web Assembly and wasm running in a web browser. This is a core feature of twr-wasm. For documentation of these functions, see the many standard C library documentation web sites. The following subset of the standard C library is available. Also see twr-wasm/include folder for include files. stdio.h * fprintf will only work with these -- stderr, stdin, stdout */ /* these return 'struct IoConsole *' which is same as 'FILE *' */ #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) int snprintf(char *buffer, size_t bufsz, const char *format, ... ); int sprintf( char *buffer, const char *format, ... ); int vsnprintf(char *buffer, size_t bufsz, const char *format, va_list vlist); int vasprintf(char **strp, const char* format, va_list vlist ); int printf(const char* format, ...); int vprintf(const char* format, va_list vlist ); int puts(const char *str); int putchar(int c); typedef struct IoConsole FILE; int vfprintf(FILE *stream, const char *format, va_list vlist); int fprintf(FILE *stream, const char* format, ...); size_t fwrite(const void* buffer, size_t size, size_t count, FILE* stream); int ferror(FILE *stream); int feof(FILE *stream); int fflush(FILE *stream); int is_terminal(FILE *stream); int fputc(int ch, FILE* stream); int putc(int ch, FILE* stream); int fgetc(FILE *stream ); int getc(FILE *stream); stdlib.h void *malloc(size_t size); void free(void *mem); size_t avail(void); void *realloc( void *ptr, size_t new_size ); void* calloc( size_t num, size_t size ); void *aligned_alloc( size_t alignment, size_t size ); int rand(void); void srand(int seed); #define __min(a,b) (((a) < (b)) ? (a) : (b)) #define __max(a,b) (((a) > (b)) ? (a) : (b)) int _fcvt_s( char* buffer, size_t sizeInBytes, double value, int fracpart_numdigits, int *dec, int *sign ); double atof(const char* str); int atoi(const char *str); long atol( const char *str ); long long atoll( const char *str ); long strtol(const char *str, char **str_end, int base); long long strtoll(const char *str, char **str_end, int base); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull(const char *str, char **str_end, int base); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); unsigned long strtoul(const char *str, char ** str_end, int base); float strtof(const char *str, char ** str_end); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod(const char *str, char **str_end); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold(const char *str, char **str_end); long double strtold_l(const char *str, char **str_end, locale_t locale); int _itoa_s(int64_t value, char * buffer, size_t size, int radix); div_t div( int x, int y ); ldiv_t ldiv( long x, long y ); lldiv_t lldiv( long long x, long long y ); _Noreturn void abort(void); int atexit(void (*func)(void)); Note that _fcvt_s as currently enabled has these limitations: - fractional digits <=100 - values must be less than 1e+21 - values negative exponents must be smaller than 1e-99 There is a full featured version of _fcvt_s in the source code, but is not currently enabled, since the version enabled is smaller and works in most use cases. assert.h void assert(int expression); math.h int abs(int n); double acos(double arg); double asin(double arg); double atan(double arg); double ceil(double arg); double cos(double arg); double exp(double arg); double fabs(double arg); double floor(double arg); double fmod(double x, double y); double log(double arg); double pow(double base, double exp); double sin(double arg); double sqrt(double arg); double tan(double arg); double trunc(double arg); stdarg.h #define va_start(v,l) __builtin_va_start(v,l) #define va_end(v) __builtin_va_end(v) #define va_arg(v,l) __builtin_va_arg(v,l) #define va_copy(d,s) __builtin_va_copy(d,s) typedef __builtin_va_list va_list; ctype.h int isascii(int); int toascii(int); int isalnum(int c); int isalpha(int c); int isblank(int); int iscntrl(int); int isdigit(int c); int isgraph(int c); int islower(int); int isprint(int); int ispunct(int); int isspace(int c); int isupper(int); int isxdigit(int); int tolower(int c); int toupper(int c); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); _stdtypes.h // don't include directly -- included by various .h files typedef unsigned long size_t; #define MAX_SIZE_T 2147483647 #ifdef __cplusplus #define NULL __null #else #define NULL ((void*)0) #endif typedef struct __locale_t_struct * locale_t; stddef.h #define offsetof(TYPE, MEMBER) __builtin_offsetof (TYPE, MEMBER) typedef __PTRDIFF_TYPE__ ptrdiff_t; typedef double max_align_t; string.h size_t strlen(const char * str); char *strdup(const char * source); char *strcpy(char *dest, const char *source); int strcat_s(char *dest, size_t destsz, const char *src); char* strcat(char *dest, const char *src); char *strncpy(char *dest, const char *source, size_t count); int strcmp(const char* string1, const char* string2); int strncmp(const char* lhs, const char* rhs, size_t count); int stricmp(const char* string1, const char* string2); int strnicmp(const char* string1, const char* string2, size_t count); int strcoll(const char* lhs, const char* rhs); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); char *strchr(const char *str, int ch); void *memchr(const void *ptr, int ch, size_t count); char *strstr(const char *haystack, const char *needle); char * strerror(int errnum ); char * _strerror(const char *strErrMsg); void *memmove(void *dest, const void *src, size_t n); int memcmp( const void* lhs, const void* rhs, size_t count ); void bzero (void *to, size_t count); // implemented in memcpy.wat void *memcpy(void *dest, const void * src, size_t n); void *memset(void *mem, int c, size_t n); time.h typedef unsigned long time_t; unsigned long time(unsigned long *time); size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale); struct tm *localtime(const time_t *timer); int gettimeofday(struct timeval *tv, void* notused); #define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) #define timercmp(tvp,uvp,cmp) \\ ((tvp)->tv_sec cmp (uvp)->tv_sec || \\ ((tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)) #define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0 locale.h #define LC_GLOBAL_LOCALE twr_get_current_locale() char* setlocale(int category, const char* locale); struct lconv *localeconv(void); locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); extern inline locale_t twr_get_current_locale(void); errno.h typedef int errno_t; extern int * _errno(void); #define errno (*_errno()) errno_t _set_errno(int _Value); errno_t _get_errno(int *_Value); Other include files available float.h limits.h stdbool.h stdint.h","title":"C Standard C Library"},{"location":"api/api-c-stdlib/#standard-c-library-for-web-assembly","text":"This section describes twr-wasm's support for the Standard C Library. twr-wasm includes its own implementation of the standard C library optimized for Web Assembly and wasm running in a web browser. This is a core feature of twr-wasm. For documentation of these functions, see the many standard C library documentation web sites. The following subset of the standard C library is available. Also see twr-wasm/include folder for include files.","title":"Standard C library for Web Assembly"},{"location":"api/api-c-stdlib/#stdioh","text":"* fprintf will only work with these -- stderr, stdin, stdout */ /* these return 'struct IoConsole *' which is same as 'FILE *' */ #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) int snprintf(char *buffer, size_t bufsz, const char *format, ... ); int sprintf( char *buffer, const char *format, ... ); int vsnprintf(char *buffer, size_t bufsz, const char *format, va_list vlist); int vasprintf(char **strp, const char* format, va_list vlist ); int printf(const char* format, ...); int vprintf(const char* format, va_list vlist ); int puts(const char *str); int putchar(int c); typedef struct IoConsole FILE; int vfprintf(FILE *stream, const char *format, va_list vlist); int fprintf(FILE *stream, const char* format, ...); size_t fwrite(const void* buffer, size_t size, size_t count, FILE* stream); int ferror(FILE *stream); int feof(FILE *stream); int fflush(FILE *stream); int is_terminal(FILE *stream); int fputc(int ch, FILE* stream); int putc(int ch, FILE* stream); int fgetc(FILE *stream ); int getc(FILE *stream);","title":"stdio.h"},{"location":"api/api-c-stdlib/#stdlibh","text":"void *malloc(size_t size); void free(void *mem); size_t avail(void); void *realloc( void *ptr, size_t new_size ); void* calloc( size_t num, size_t size ); void *aligned_alloc( size_t alignment, size_t size ); int rand(void); void srand(int seed); #define __min(a,b) (((a) < (b)) ? (a) : (b)) #define __max(a,b) (((a) > (b)) ? (a) : (b)) int _fcvt_s( char* buffer, size_t sizeInBytes, double value, int fracpart_numdigits, int *dec, int *sign ); double atof(const char* str); int atoi(const char *str); long atol( const char *str ); long long atoll( const char *str ); long strtol(const char *str, char **str_end, int base); long long strtoll(const char *str, char **str_end, int base); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull(const char *str, char **str_end, int base); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); unsigned long strtoul(const char *str, char ** str_end, int base); float strtof(const char *str, char ** str_end); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod(const char *str, char **str_end); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold(const char *str, char **str_end); long double strtold_l(const char *str, char **str_end, locale_t locale); int _itoa_s(int64_t value, char * buffer, size_t size, int radix); div_t div( int x, int y ); ldiv_t ldiv( long x, long y ); lldiv_t lldiv( long long x, long long y ); _Noreturn void abort(void); int atexit(void (*func)(void)); Note that _fcvt_s as currently enabled has these limitations: - fractional digits <=100 - values must be less than 1e+21 - values negative exponents must be smaller than 1e-99 There is a full featured version of _fcvt_s in the source code, but is not currently enabled, since the version enabled is smaller and works in most use cases.","title":"stdlib.h"},{"location":"api/api-c-stdlib/#asserth","text":"void assert(int expression);","title":"assert.h"},{"location":"api/api-c-stdlib/#mathh","text":"int abs(int n); double acos(double arg); double asin(double arg); double atan(double arg); double ceil(double arg); double cos(double arg); double exp(double arg); double fabs(double arg); double floor(double arg); double fmod(double x, double y); double log(double arg); double pow(double base, double exp); double sin(double arg); double sqrt(double arg); double tan(double arg); double trunc(double arg);","title":"math.h"},{"location":"api/api-c-stdlib/#stdargh","text":"#define va_start(v,l) __builtin_va_start(v,l) #define va_end(v) __builtin_va_end(v) #define va_arg(v,l) __builtin_va_arg(v,l) #define va_copy(d,s) __builtin_va_copy(d,s) typedef __builtin_va_list va_list;","title":"stdarg.h"},{"location":"api/api-c-stdlib/#ctypeh","text":"int isascii(int); int toascii(int); int isalnum(int c); int isalpha(int c); int isblank(int); int iscntrl(int); int isdigit(int c); int isgraph(int c); int islower(int); int isprint(int); int ispunct(int); int isspace(int c); int isupper(int); int isxdigit(int); int tolower(int c); int toupper(int c); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc);","title":"ctype.h"},{"location":"api/api-c-stdlib/#_stdtypesh","text":"// don't include directly -- included by various .h files typedef unsigned long size_t; #define MAX_SIZE_T 2147483647 #ifdef __cplusplus #define NULL __null #else #define NULL ((void*)0) #endif typedef struct __locale_t_struct * locale_t;","title":"_stdtypes.h"},{"location":"api/api-c-stdlib/#stddefh","text":"#define offsetof(TYPE, MEMBER) __builtin_offsetof (TYPE, MEMBER) typedef __PTRDIFF_TYPE__ ptrdiff_t; typedef double max_align_t;","title":"stddef.h"},{"location":"api/api-c-stdlib/#stringh","text":"size_t strlen(const char * str); char *strdup(const char * source); char *strcpy(char *dest, const char *source); int strcat_s(char *dest, size_t destsz, const char *src); char* strcat(char *dest, const char *src); char *strncpy(char *dest, const char *source, size_t count); int strcmp(const char* string1, const char* string2); int strncmp(const char* lhs, const char* rhs, size_t count); int stricmp(const char* string1, const char* string2); int strnicmp(const char* string1, const char* string2, size_t count); int strcoll(const char* lhs, const char* rhs); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); char *strchr(const char *str, int ch); void *memchr(const void *ptr, int ch, size_t count); char *strstr(const char *haystack, const char *needle); char * strerror(int errnum ); char * _strerror(const char *strErrMsg); void *memmove(void *dest, const void *src, size_t n); int memcmp( const void* lhs, const void* rhs, size_t count ); void bzero (void *to, size_t count); // implemented in memcpy.wat void *memcpy(void *dest, const void * src, size_t n); void *memset(void *mem, int c, size_t n);","title":"string.h"},{"location":"api/api-c-stdlib/#timeh","text":"typedef unsigned long time_t; unsigned long time(unsigned long *time); size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale); struct tm *localtime(const time_t *timer); int gettimeofday(struct timeval *tv, void* notused); #define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) #define timercmp(tvp,uvp,cmp) \\ ((tvp)->tv_sec cmp (uvp)->tv_sec || \\ ((tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)) #define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0","title":"time.h"},{"location":"api/api-c-stdlib/#localeh","text":"#define LC_GLOBAL_LOCALE twr_get_current_locale() char* setlocale(int category, const char* locale); struct lconv *localeconv(void); locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); extern inline locale_t twr_get_current_locale(void);","title":"locale.h"},{"location":"api/api-c-stdlib/#errnoh","text":"typedef int errno_t; extern int * _errno(void); #define errno (*_errno()) errno_t _set_errno(int _Value); errno_t _get_errno(int *_Value);","title":"errno.h"},{"location":"api/api-c-stdlib/#other-include-files-available","text":"float.h limits.h stdbool.h stdint.h","title":"Other include files available"},{"location":"api/api-libc%2B%2B/","text":"libc++ for Web Assembly This section describes twr-wasm's support for using the standard c++ library libc++ with Web Assembly. twr-wasm includes libc++ built for Web Assembly and included in the twr-wasm/lib-c folder. You can build twr-wasm projects in C++ with or without libc++. See the examples tests-libcxx and tests-user for examples of using libc++. See the balls example for how to create a C++ Web Assembly program without the standard C++ library. The primary advantage to this approach is a bit smaller code size. You don't need to staticly link libc++. twr-wasm's libc++ for Web Assembly was built with these build options: LIBCXX_ENABLE_LOCALIZATION=ON LIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON LIBCXXABI_ENABLE_STATIC_UNWINDER=ON LIBCXXABI_ENABLE_STATIC=ON LIBCXX_ENABLE_FILESYSTEM=OFF LIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF LIBCXX_ENABLE_MONOTONIC_CLOCK=OFF LIBCXX_ENABLE_RANDOM_DEVICE=OFF LIBCXX_ENABLE_UNICODE=OFF LIBCXX_ENABLE_WIDE_CHARACTERS=OFF LIBCXX_ENABLE_EXCEPTIONS=OFF LIBCXXABI_ENABLE_EXCEPTIONS=OFF LIBCXX_ENABLE_RTTI=OFF LIBCXX_ENABLE_THREADS=OFF LIBCXXABI_ENABLE_THREADS=OFF LIBCXXABI_HAS_PTHREAD_API=OFF LIBCXX_ENABLE_SHARED=OFF LIBCXXABI_ENABLE_SHARED=OFF","title":"C++ with libc++"},{"location":"api/api-libc%2B%2B/#libc-for-web-assembly","text":"This section describes twr-wasm's support for using the standard c++ library libc++ with Web Assembly. twr-wasm includes libc++ built for Web Assembly and included in the twr-wasm/lib-c folder. You can build twr-wasm projects in C++ with or without libc++. See the examples tests-libcxx and tests-user for examples of using libc++. See the balls example for how to create a C++ Web Assembly program without the standard C++ library. The primary advantage to this approach is a bit smaller code size. You don't need to staticly link libc++. twr-wasm's libc++ for Web Assembly was built with these build options: LIBCXX_ENABLE_LOCALIZATION=ON LIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON LIBCXXABI_ENABLE_STATIC_UNWINDER=ON LIBCXXABI_ENABLE_STATIC=ON LIBCXX_ENABLE_FILESYSTEM=OFF LIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF LIBCXX_ENABLE_MONOTONIC_CLOCK=OFF LIBCXX_ENABLE_RANDOM_DEVICE=OFF LIBCXX_ENABLE_UNICODE=OFF LIBCXX_ENABLE_WIDE_CHARACTERS=OFF LIBCXX_ENABLE_EXCEPTIONS=OFF LIBCXXABI_ENABLE_EXCEPTIONS=OFF LIBCXX_ENABLE_RTTI=OFF LIBCXX_ENABLE_THREADS=OFF LIBCXXABI_ENABLE_THREADS=OFF LIBCXXABI_HAS_PTHREAD_API=OFF LIBCXX_ENABLE_SHARED=OFF LIBCXXABI_ENABLE_SHARED=OFF","title":"libc++ for Web Assembly"},{"location":"api/api-localization/","text":"Locale Support for Web Assembly This section explains twr-wasm's Web Assembly localization support. Character encodings twr-wasm locales supports ASCII, UTF-8 or windows-1252 encoding. UTF-16/32 are not supported as a locale setting, but functions are provided to convert utf-32 (unicode code points) to and from ASCII, UTF-8, and windows-1252 \"code pages\" (there are other miscellaneous utf-32 based functions as well.) UTF-8 uses between one to four bytes to represent any unicode character, with ASCII compatibility in the first 128 bytes. It is also the standard for the web, and the default for clang. But because it uses a variable number of bytes per character it can make string manipulation in C a bit harder than ASCII. Windows-1252 is the default on most Windows computers in many countries - particularly the Americas and western Europe. It is an extension of ASCII that uses a single byte per character. This makes it easier than UTF-8 from a programmers perspective, but it doesn't represent as many characters. It is provided to make it easier to port legacy C code, windows code, as well as a simpler alternative to UTF-8. Although the locale settings don't support utf-32 directly, you can use int arrays (instead of byte arrays) to hold utf-32 strings, and then convert them to/from utf-8 with the help of the provided two functions for this purpose. Locales \"C\" \"C\" is the default locale, as usual. When \"C\" is selected, the functions operate as usual. One subtly is that console i/o functions (such as printf ) will generally function as expected with UTF-8, since the div and window consoles correctly handle UTF-8 character encoding. This is normal on some OSs, such as linux, but not the default on Windows (which often defaults to windows-1252 for backward compatibility). isgraph style functions will only recognize ASCII characters, as is normal. Functions such as strcmp operate on the byte sequence, which will typically results in UTF-8 codes being compared lexically. strcoll will use lexical ordering. \"POSIX\" \"POSIX\" is the same as \"C\" \"\" \"\" is the locale to specify the users default setting (this selects the setting used by the browser). This will also enable UTF-8 in functions such as strcoll . For example, if your browser is set to \"en-US\" as its default locale, setlocale(LC_ALL, \"\") will return en-US.UTF-8 . isgraph style functions will still only recognize ASCII characters (since UTF-8 doesn't encode any single bytes greater than 127). strcoll uses locale specific ordering, and printf will use locale specific decimal points. strcmp still compares two strings lexicographically (byte-by-byte) without considering locale-specific rules, per the spec. \".UTF-8\" \".UTF-8\" is the same as \"\" with twr-wasm. \".1252\" \".1252\" will select the current default locale, but use windows-1252 character encoding (instead of UTF-8). Windows-1252 is a super set of ISO-8859-1 and is the most commonly used encoding for many european languages when unicode is not used. This mode is primarily for legacy software, backwards compatibly, and windows compatibility. 1252 String Literals These days text editors generally default to UTF-8. In order to use windows-1252 source code and/or string literals, such as const char * str=\"\u20ac100\" you may need to: Configure your text editor to save in Windows-1252/ISO-8859-1 format (instead of UTF-8) use compiler flags like --finput-charset and -fexec-charset By default, the Microsoft Visual Studio C compiler (MSVC) does not treat string literals as UTF-8. Instead, it treats them as being encoded in the current code page of the system, which is typically Windows-1252 on western european language Windows systems. twr-wasm is designed to work with clang, which does default to utf-8, so if you are compiling code written for MSVC, and you use extend character sets (non ASCII), you may need to adjust your compiler settings with the flags mentioned above. Others Setting arbitrary locales, such as \"fr-FR\" when the browser is defaulted to another locale, is not supported. Select the default locale To select the user's browser's default locale using the C language, and enable consistent utf-8 support, use a call like this: setlocale(LC_ALL, \"\") libc++ If you are using C++, libc++ locale functions work as expected. C functions The normal standard C library locale support is available, along with some POSIX extensions. In addition, some locale useful twr-wasm specific functions are documented in C API , such as twr_get_current_locale , twr_mbgets , twr_getc32 , twr_utf8_char_len , twr_mbslen_l , twr_utf32_to_code_page , twr_code_page_to_utf32_streamed , twr_get_navlang , twr_localize_numeric_string . Note that io_getc32() , getc(stdin) , fgetc(stdin) do not look at the current locale. iogetc32 returns a 32 bit unicode code point, and getc / fgetc return extended ASCII. For a locale aware character input, use io_mbgetc() or twr_mbgets() . Both use the locale category LC_CTYPE. See C API . Note that when the locale is not set (or whenever the \"C\" locale is set) functions that get character(s) from stdin that are locale aware, like twr_mbgets() , behave different than functions that output characters to stdout (like puts , io_putstr , io_putc , putchar ). Characters to stdout in \"C\" locale will handle UTF-8 characters. For stdin, \"C\" locale uses ASCII. For consistent UTF-8 (or windows-1252) behavior, set the locale as discussed above ( use setlocale ) The primary standard C library locale functions are: char* setlocale(int category, const char* locale); struct lconv *localeconv(void); As well as the standard library functions above, appropriate functions take into account the current locale (printf, strcoll, etc). Note that setlocale returns a string using BCP 47 format (similar to a web browser). Locale strings look like \"en-US.UTF-8\", instead of \"en_US.UTF-8\". A dash, not an underscore, is used as a separator. POSIX functions These are the extended POSIX style functions provided that are related to locale: locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold_l(const char *str, char **str_end, locale_t locale); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale);","title":"C Localization"},{"location":"api/api-localization/#locale-support-for-web-assembly","text":"This section explains twr-wasm's Web Assembly localization support.","title":"Locale Support for Web Assembly"},{"location":"api/api-localization/#character-encodings","text":"twr-wasm locales supports ASCII, UTF-8 or windows-1252 encoding. UTF-16/32 are not supported as a locale setting, but functions are provided to convert utf-32 (unicode code points) to and from ASCII, UTF-8, and windows-1252 \"code pages\" (there are other miscellaneous utf-32 based functions as well.) UTF-8 uses between one to four bytes to represent any unicode character, with ASCII compatibility in the first 128 bytes. It is also the standard for the web, and the default for clang. But because it uses a variable number of bytes per character it can make string manipulation in C a bit harder than ASCII. Windows-1252 is the default on most Windows computers in many countries - particularly the Americas and western Europe. It is an extension of ASCII that uses a single byte per character. This makes it easier than UTF-8 from a programmers perspective, but it doesn't represent as many characters. It is provided to make it easier to port legacy C code, windows code, as well as a simpler alternative to UTF-8. Although the locale settings don't support utf-32 directly, you can use int arrays (instead of byte arrays) to hold utf-32 strings, and then convert them to/from utf-8 with the help of the provided two functions for this purpose.","title":"Character encodings"},{"location":"api/api-localization/#locales","text":"","title":"Locales"},{"location":"api/api-localization/#c","text":"\"C\" is the default locale, as usual. When \"C\" is selected, the functions operate as usual. One subtly is that console i/o functions (such as printf ) will generally function as expected with UTF-8, since the div and window consoles correctly handle UTF-8 character encoding. This is normal on some OSs, such as linux, but not the default on Windows (which often defaults to windows-1252 for backward compatibility). isgraph style functions will only recognize ASCII characters, as is normal. Functions such as strcmp operate on the byte sequence, which will typically results in UTF-8 codes being compared lexically. strcoll will use lexical ordering.","title":"\"C\""},{"location":"api/api-localization/#posix","text":"\"POSIX\" is the same as \"C\"","title":"\"POSIX\""},{"location":"api/api-localization/#_1","text":"\"\" is the locale to specify the users default setting (this selects the setting used by the browser). This will also enable UTF-8 in functions such as strcoll . For example, if your browser is set to \"en-US\" as its default locale, setlocale(LC_ALL, \"\") will return en-US.UTF-8 . isgraph style functions will still only recognize ASCII characters (since UTF-8 doesn't encode any single bytes greater than 127). strcoll uses locale specific ordering, and printf will use locale specific decimal points. strcmp still compares two strings lexicographically (byte-by-byte) without considering locale-specific rules, per the spec.","title":"\"\""},{"location":"api/api-localization/#utf-8","text":"\".UTF-8\" is the same as \"\" with twr-wasm.","title":"\".UTF-8\""},{"location":"api/api-localization/#1252","text":"\".1252\" will select the current default locale, but use windows-1252 character encoding (instead of UTF-8). Windows-1252 is a super set of ISO-8859-1 and is the most commonly used encoding for many european languages when unicode is not used. This mode is primarily for legacy software, backwards compatibly, and windows compatibility. 1252 String Literals These days text editors generally default to UTF-8. In order to use windows-1252 source code and/or string literals, such as const char * str=\"\u20ac100\" you may need to: Configure your text editor to save in Windows-1252/ISO-8859-1 format (instead of UTF-8) use compiler flags like --finput-charset and -fexec-charset By default, the Microsoft Visual Studio C compiler (MSVC) does not treat string literals as UTF-8. Instead, it treats them as being encoded in the current code page of the system, which is typically Windows-1252 on western european language Windows systems. twr-wasm is designed to work with clang, which does default to utf-8, so if you are compiling code written for MSVC, and you use extend character sets (non ASCII), you may need to adjust your compiler settings with the flags mentioned above.","title":"\".1252\""},{"location":"api/api-localization/#others","text":"Setting arbitrary locales, such as \"fr-FR\" when the browser is defaulted to another locale, is not supported.","title":"Others"},{"location":"api/api-localization/#select-the-default-locale","text":"To select the user's browser's default locale using the C language, and enable consistent utf-8 support, use a call like this: setlocale(LC_ALL, \"\")","title":"Select the default locale"},{"location":"api/api-localization/#libc","text":"If you are using C++, libc++ locale functions work as expected.","title":"libc++"},{"location":"api/api-localization/#c-functions","text":"The normal standard C library locale support is available, along with some POSIX extensions. In addition, some locale useful twr-wasm specific functions are documented in C API , such as twr_get_current_locale , twr_mbgets , twr_getc32 , twr_utf8_char_len , twr_mbslen_l , twr_utf32_to_code_page , twr_code_page_to_utf32_streamed , twr_get_navlang , twr_localize_numeric_string . Note that io_getc32() , getc(stdin) , fgetc(stdin) do not look at the current locale. iogetc32 returns a 32 bit unicode code point, and getc / fgetc return extended ASCII. For a locale aware character input, use io_mbgetc() or twr_mbgets() . Both use the locale category LC_CTYPE. See C API . Note that when the locale is not set (or whenever the \"C\" locale is set) functions that get character(s) from stdin that are locale aware, like twr_mbgets() , behave different than functions that output characters to stdout (like puts , io_putstr , io_putc , putchar ). Characters to stdout in \"C\" locale will handle UTF-8 characters. For stdin, \"C\" locale uses ASCII. For consistent UTF-8 (or windows-1252) behavior, set the locale as discussed above ( use setlocale ) The primary standard C library locale functions are: char* setlocale(int category, const char* locale); struct lconv *localeconv(void); As well as the standard library functions above, appropriate functions take into account the current locale (printf, strcoll, etc). Note that setlocale returns a string using BCP 47 format (similar to a web browser). Locale strings look like \"en-US.UTF-8\", instead of \"en_US.UTF-8\". A dash, not an underscore, is used as a separator.","title":"C functions"},{"location":"api/api-localization/#posix-functions","text":"These are the extended POSIX style functions provided that are related to locale: locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold_l(const char *str, char **str_end, locale_t locale); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale);","title":"POSIX functions"},{"location":"api/api-typescript/","text":"TypeScript-JavaScript API for WASM This section describes the twr-wasm TypeScript/JavaScript classes that you use to load your wasm modules, and to call C functions in your wasm modules. class twrWasmModule and class twrWasmModuleAsync have similar APIs. The primary difference is that class twrWasmModuleAsync proxies functionality through a Web Worker thread, which allows blocking C functions to be called in your Web Assembly Module. class twrWasmModule import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); twrWasmModule provides the two core JavaScript APIs for access to a Web Assembly Module: loadWasm to load your .wasm module (your compiled C code). callC to call a C function These functions are documented further down in this section. class twrWasmModuleAsync import {twrWasmModuleAsync} from \"twr-wasm\"; const amod = new twrWasmModuleAsync(); twrWasmModuleAsync implements all of the same functions as twrWasmModule , plus allows blocking inputs, and blocking code generally. This is achieved by proxying all the calls through a Web Worker thread. Use twrWasmModuleAsync if your C code blocks, or if you are unsure. If you want better performance and don't need the capabilities of twrWasmModuleAsync , use twrWasmModule . You must use twrWasmModuleAsync in order to: call any blocking C function (meaning it takes \"a long time\") to return use blocking input from a div or canvas ( eg. twr_mbgets ) use twr_sleep See stdio section for information on enabling blocking character input, as well as this Example . When comping/linking your C/C++ code, twrWasmModule and twrWasmModuleAsync use slightly different wasm-ld options since twrWasmModuleAsync uses shared memory. wrWasmModule will operate with shared memory, so technically you could just use the same share memory options with either module, but you don't need the overhead of shared memory when using twrWasmModule, and so better to not enable it. See Compiler Options . twrWasmModuleAsync uses SharedArrayBuffers which require certain HTTP headers to be set. Note that twrWasmModule has an advantage in that it does not use SharedArrayBuffers. Github pages doesn't support the needed CORS headers for SharedArrayBuffers. But other web serving sites do have options to enable the needed CORS headers. For example, the azure static web site config file staticwebapp.config.json looks like this: { \"globalHeaders\": { \"Access-Control-Allow-Origin\": \"*\", \"Cross-Origin-Embedder-Policy\": \"require-corp\", \"Cross-Origin-Opener-Policy\": \"same-origin\" } } server.py in the examples folder will launch a local server with the correct headers. To use Chrome without a web server, see the debugging section . Class Options The twrWasmModule and twrWasmModuleAsync constructor both take optional options. For example: let amod=new twrWasmModuleAsync(); let amod=new twrWasmModuleAsync({ windim:[50,20], forecolor:\"beige\", backcolor:\"DarkOliveGreen\", fontsize:18 }); For a
      it is simpler to set the color and font in the div tag per the normal HTML method. But for
      , that method won't work and you need to use the constructor options for color and fontsize. These are the options: export type TStdioVals=\"div\"|\"canvas\"|\"null\"|\"debug\"; export interface IModOpts { stdio?:TStdioVals, windim?:[number, number], forecolor?:string, backcolor?:string, fontsize?:number, imports?:{}, } stdio You can explicitly set your stdio source (for C/C++ printf, etc) with the stdio option, but typically you don't set it. Instead, it will auto set as described here windim This options is used with a terminal console ( ) to set the width and height, in characters. The canvas width and height, in pixels, will be set based on your fontsize and the width and height (in characters) of the terminal. forecolor and backcolor These can be set to a CSS color (like '#FFFFFF' or 'white') to change the default background and foreground colors. fonsize Changes the default fontsize for div or canvas based I/O. The size is in pixels. loadWasm Use loadWasm to load your compiled C/C++ code (the .wasm file). await mod.loadWasm(\"./mycode.wasm\") callC After your . wasm module is loaded with loadWasm , you call functions in your C/C++ from TypeScript/JavaScript like this: let result=await amod.callC([\"bounce_balls_move\", param1]) If you are calling into C++, you need to use extern \"C\" like this in your C++ code: extern \"C\" int bounce_balls_move() {} Each C/C++ function that you wish to call from TypeScript/JavaScript needs to be exported in your wasm-ld settings like this: --export=bounce_balls_move Or like this in your source file: __attribute__((export_name(\"bounce_balls_move\"))) void bounce_balls_move() { ... See the Compiler Options . callC takes an array where: the first entry is the name of the C function in the wasm module to call and the next entries are a variable number of parameters to pass to the C function, of type: number - will be converted to int32 or float64 as appropriate string - converted to a pointer to module Memory where string is copied into ArrayBuffer - the array is loaded into module memory. If you need to pass the length, pass it as a separate parameter. Any modifications to the memory made by your C code will be reflected back into the JavaScript ArrayBuffer. URL - the url contents are loaded into module Memory, and two C parameters are generated - index (pointer) to the memory, and length callC returns the value returned by the C function that was called. As well int and float , string and structs (or blocks of memory) can be returned. More details can be found in examples/function-calls . The FFT example demonstrates passing a Float32Array view of an ArrayBuffer. Also see Key Concepts . divLog If stdio is set to twr_iodiv , you can use the divLog twrWasmModule/Async function like this: import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); await mod.loadWasm(\"./tests.wasm\"); await mod.callC([\"tests\"]); mod.divLog(\"\\nsin() speed test\"); let sumA=0; const start=Date.now(); for (let i=0; i<2000000;i++) sumA=sumA+Math.sin(i); const endA=Date.now(); let sumB=await mod.callC([\"sin_test\"]); const endB=Date.now(); mod.divLog(\"sum A: \", sumA, \" in ms: \", endA-start); mod.divLog(\"sum B: \", sumB, \" in ms: \", endB-endA); Accessing Data in the Web Assembly Memory You probably will not need to use the twrWasmModule/Async functions in this section, as callC() will convert your parameters for you. But if you return or want to pass in more complicated structs, you might need to. The source in source/twr-wasm-ts/canvas.ts is an example of how these are used. async putString(sin:string, codePage=codePageUTF8) // returns index into WebAssembly.Memory async putU8(u8a:Uint8Array) // returns index into WebAssembly.Memory async putArrayBuffer(ab:ArrayBuffer) // returns index into WebAssembly.Memory async fetchAndPutURL(fnin:URL) // returns index into WebAssembly.Memory async malloc(size:number) // returns index in WebAssembly.Memory. stringToU8(sin:string, codePage=codePageUTF8) copyString(buffer:number, buffer_size:number, sin:string, codePage=codePageUTF8):void getLong(idx:number): number setLong(idx:number, value:number) getDouble(idx:number): number setDouble(idx:number, value:number) getShort(idx:number): number getString(strIndex:number, len?:number, codePage=codePageUTF8): string getU8Arr(idx:number): Uint8Array getU32Arr(idx:number): Uint32Array memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array;","title":"TypeScript/JavaScript"},{"location":"api/api-typescript/#typescript-javascript-api-for-wasm","text":"This section describes the twr-wasm TypeScript/JavaScript classes that you use to load your wasm modules, and to call C functions in your wasm modules. class twrWasmModule and class twrWasmModuleAsync have similar APIs. The primary difference is that class twrWasmModuleAsync proxies functionality through a Web Worker thread, which allows blocking C functions to be called in your Web Assembly Module.","title":"TypeScript-JavaScript API for WASM"},{"location":"api/api-typescript/#class-twrwasmmodule","text":"import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); twrWasmModule provides the two core JavaScript APIs for access to a Web Assembly Module: loadWasm to load your .wasm module (your compiled C code). callC to call a C function These functions are documented further down in this section.","title":"class twrWasmModule"},{"location":"api/api-typescript/#class-twrwasmmoduleasync","text":"import {twrWasmModuleAsync} from \"twr-wasm\"; const amod = new twrWasmModuleAsync(); twrWasmModuleAsync implements all of the same functions as twrWasmModule , plus allows blocking inputs, and blocking code generally. This is achieved by proxying all the calls through a Web Worker thread. Use twrWasmModuleAsync if your C code blocks, or if you are unsure. If you want better performance and don't need the capabilities of twrWasmModuleAsync , use twrWasmModule . You must use twrWasmModuleAsync in order to: call any blocking C function (meaning it takes \"a long time\") to return use blocking input from a div or canvas ( eg. twr_mbgets ) use twr_sleep See stdio section for information on enabling blocking character input, as well as this Example . When comping/linking your C/C++ code, twrWasmModule and twrWasmModuleAsync use slightly different wasm-ld options since twrWasmModuleAsync uses shared memory. wrWasmModule will operate with shared memory, so technically you could just use the same share memory options with either module, but you don't need the overhead of shared memory when using twrWasmModule, and so better to not enable it. See Compiler Options . twrWasmModuleAsync uses SharedArrayBuffers which require certain HTTP headers to be set. Note that twrWasmModule has an advantage in that it does not use SharedArrayBuffers. Github pages doesn't support the needed CORS headers for SharedArrayBuffers. But other web serving sites do have options to enable the needed CORS headers. For example, the azure static web site config file staticwebapp.config.json looks like this: { \"globalHeaders\": { \"Access-Control-Allow-Origin\": \"*\", \"Cross-Origin-Embedder-Policy\": \"require-corp\", \"Cross-Origin-Opener-Policy\": \"same-origin\" } } server.py in the examples folder will launch a local server with the correct headers. To use Chrome without a web server, see the debugging section .","title":"class twrWasmModuleAsync"},{"location":"api/api-typescript/#class-options","text":"The twrWasmModule and twrWasmModuleAsync constructor both take optional options. For example: let amod=new twrWasmModuleAsync(); let amod=new twrWasmModuleAsync({ windim:[50,20], forecolor:\"beige\", backcolor:\"DarkOliveGreen\", fontsize:18 }); For a
      it is simpler to set the color and font in the div tag per the normal HTML method. But for
      , that method won't work and you need to use the constructor options for color and fontsize. These are the options: export type TStdioVals=\"div\"|\"canvas\"|\"null\"|\"debug\"; export interface IModOpts { stdio?:TStdioVals, windim?:[number, number], forecolor?:string, backcolor?:string, fontsize?:number, imports?:{}, }","title":"Class Options"},{"location":"api/api-typescript/#stdio","text":"You can explicitly set your stdio source (for C/C++ printf, etc) with the stdio option, but typically you don't set it. Instead, it will auto set as described here","title":"stdio"},{"location":"api/api-typescript/#windim","text":"This options is used with a terminal console ( ) to set the width and height, in characters. The canvas width and height, in pixels, will be set based on your fontsize and the width and height (in characters) of the terminal.","title":"windim"},{"location":"api/api-typescript/#forecolor-and-backcolor","text":"These can be set to a CSS color (like '#FFFFFF' or 'white') to change the default background and foreground colors.","title":"forecolor and backcolor"},{"location":"api/api-typescript/#fonsize","text":"Changes the default fontsize for div or canvas based I/O. The size is in pixels.","title":"fonsize"},{"location":"api/api-typescript/#loadwasm","text":"Use loadWasm to load your compiled C/C++ code (the .wasm file). await mod.loadWasm(\"./mycode.wasm\")","title":"loadWasm"},{"location":"api/api-typescript/#callc","text":"After your . wasm module is loaded with loadWasm , you call functions in your C/C++ from TypeScript/JavaScript like this: let result=await amod.callC([\"bounce_balls_move\", param1]) If you are calling into C++, you need to use extern \"C\" like this in your C++ code: extern \"C\" int bounce_balls_move() {} Each C/C++ function that you wish to call from TypeScript/JavaScript needs to be exported in your wasm-ld settings like this: --export=bounce_balls_move Or like this in your source file: __attribute__((export_name(\"bounce_balls_move\"))) void bounce_balls_move() { ... See the Compiler Options . callC takes an array where: the first entry is the name of the C function in the wasm module to call and the next entries are a variable number of parameters to pass to the C function, of type: number - will be converted to int32 or float64 as appropriate string - converted to a pointer to module Memory where string is copied into ArrayBuffer - the array is loaded into module memory. If you need to pass the length, pass it as a separate parameter. Any modifications to the memory made by your C code will be reflected back into the JavaScript ArrayBuffer. URL - the url contents are loaded into module Memory, and two C parameters are generated - index (pointer) to the memory, and length callC returns the value returned by the C function that was called. As well int and float , string and structs (or blocks of memory) can be returned. More details can be found in examples/function-calls . The FFT example demonstrates passing a Float32Array view of an ArrayBuffer. Also see Key Concepts .","title":"callC"},{"location":"api/api-typescript/#divlog","text":"If stdio is set to twr_iodiv , you can use the divLog twrWasmModule/Async function like this: import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); await mod.loadWasm(\"./tests.wasm\"); await mod.callC([\"tests\"]); mod.divLog(\"\\nsin() speed test\"); let sumA=0; const start=Date.now(); for (let i=0; i<2000000;i++) sumA=sumA+Math.sin(i); const endA=Date.now(); let sumB=await mod.callC([\"sin_test\"]); const endB=Date.now(); mod.divLog(\"sum A: \", sumA, \" in ms: \", endA-start); mod.divLog(\"sum B: \", sumB, \" in ms: \", endB-endA);","title":"divLog"},{"location":"api/api-typescript/#accessing-data-in-the-web-assembly-memory","text":"You probably will not need to use the twrWasmModule/Async functions in this section, as callC() will convert your parameters for you. But if you return or want to pass in more complicated structs, you might need to. The source in source/twr-wasm-ts/canvas.ts is an example of how these are used. async putString(sin:string, codePage=codePageUTF8) // returns index into WebAssembly.Memory async putU8(u8a:Uint8Array) // returns index into WebAssembly.Memory async putArrayBuffer(ab:ArrayBuffer) // returns index into WebAssembly.Memory async fetchAndPutURL(fnin:URL) // returns index into WebAssembly.Memory async malloc(size:number) // returns index in WebAssembly.Memory. stringToU8(sin:string, codePage=codePageUTF8) copyString(buffer:number, buffer_size:number, sin:string, codePage=codePageUTF8):void getLong(idx:number): number setLong(idx:number, value:number) getDouble(idx:number): number setDouble(idx:number, value:number) getShort(idx:number): number getString(strIndex:number, len?:number, codePage=codePageUTF8): string getU8Arr(idx:number): Uint8Array getU32Arr(idx:number): Uint32Array memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array;","title":"Accessing Data in the Web Assembly Memory"},{"location":"examples/examples-balls/","text":"Bouncing Balls - Web Assembly C++ Example This example uses Web Assembly, C++, and twr-wasm to bounce balls around your HTML page. It uses twr-wasm's 2D Draw API and a C++ Canvas class. View bouncing balls Source for balls The bouncing balls example demonstrates C++ Using the twr-wasm draw 2D APIs that match Javascript Canvas APIs. A C++ wrapper for the JavaScript Canvas class This example does not use libc++, which results in smaller code size. For an example that uses libc++ see tests-libcxx .","title":"balls"},{"location":"examples/examples-fft/","text":"FFT - Web Assembly C Example This example is a demo of integrating an existing FFT C library with Typescript/JavaScript/HTML using Web Assembly. The FFT C library is compiled into a wasm (Web Assembly) module, with the help of twr-wasm. The FFT wasm module is used by the HTML page to calculate the FFT. The FFT input and output is drawn to the web page using the normal JavaScript functions. The FFT library exposes APIs to process data, and doesn't use stdio. The FFT APIs use float32 arrays for complex-number input and output data, and a configuration struct. In the example I generate the input data by adding a 1K and 5K sine waves, call the kiss FFT API to perform the FFT on the generated sine waves, and then graph the input and output data using JavaScript Canvas. View running on the web View Source Code Here is part of the code. The rest can be found in the example. Fast Fourier transform (FFT)
      Input Signal



      FFT Output
      import {twrWasmModule} from \"twr-wasm\"; export async function fftDemo() { const mod=new twrWasmModule(); // load the kiss_fft C code as is, unmodified await mod.loadWasm('kiss_fft.wasm'); // kissFFTData stores and graphs the input and output data // in this example the fft has 1024 bins, and I am using a 48K sampling rate let fft=new kissFFTData(1024, 48000); fft.genSin(1000) fft.addSin(5000) fft.graphIn(\"c-input\"); // see kiss_fft README, but in summary you: (a) alloc config, (b) compute the FFT, (c) free the config // kiss_fft_alloc() returns a malloced structure. Pointers are numbers (index into wasm module memory) in JS land // //kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 ); let cfg:number = await mod.callC([\"kiss_fft_alloc\", fft.nfft, 0, 0, 0 ]); // The FFT input and output data are C arrays of complex numbers. // typedef struct { // kiss_fft_scalar r; // kiss_fft_scalar i; // } kiss_fft_cpx; // // /* default is float */ // define kiss_fft_scalar float // So if the FFT data has 1024 bins, then 1024 * 2 floats (r & i) * 4 bytes per float are needed. // I use a JS Float32Array view on the ArrayBuffer to access the floats // When an arrayBuffer is passed in as an argument to mod.callC, // callC will malloc memory in the wasm module of a size that matches the array buffer, then // copy the arraybuffer into the malloc'd memory prior to the function call, // then copy the malloc'd memory contents back into the arrayBuffer post call. // The malloc'd memory is free'd post call. // void kiss_fft(kiss_fft_cfg cfg,const kiss_fft_cpx *fin,kiss_fft_cpx *fout); await mod.callC([\"kiss_fft\", cfg, fft.inArrayBuf, fft.outArrayBuf]); fft.graphOut(\"c-output\"); await mod.callC([\"free\", cfg]); // not much point to this since all the module memory is about to disappear }","title":"fft"},{"location":"examples/examples-helloworld/","text":"Hello World - Web Assembly C Example This example is an very simple twr-wasm program. It uses Web Assembly and C to print \"hello world\" to an HTML
      tag. Also see: Hello World - Step-by-Step C to WASM . View helloworld running live View helloworld Source","title":"hello world"},{"location":"examples/examples-libcxx/","text":"tests-libcxx - Web Assembly libc++ Example This simple smoke test for using libc++ with Web Assembly demonstrates a simple twr-wasm C++ program that uses libc++, and shows the needed makefile. view tests-libcxx running live View tests-libcxx Source Also see this Web Assembly program that uses libc++ with twr-wasm to implement a CLI console. tests-user Live tests-user Source","title":"libc++"},{"location":"examples/examples-maze/","text":"Maze - Web Assembly C Example This example is a port to wasm of a 20 year old Win32 C program with the help of twr-wasm 2D Draw APIs. View live maze here Source for maze This example (in winemu.c) uses the twr-wasm \"d2d\" (Draw 2D) APIs. These allow drawing onto an HTML canvas from C/C++. See the balls example for a C++ Canvas class. I have included the TypesScript below. You can see the C code in the examples/maze folder. This C is interesting in that it is a combination of blocking and non blocking functions. The CalcMaze() function is blocking when the \"slow draw\" flag is set. It uses Sleep() in this case. For this reason, I use twrWasmModuleAsync. The solve section uses repeated calls to SolveStep(), which works well with a JavaScript main loop. I used a javascript interval timer to make repeated calls to the C SolveStep(). If all the C code was structured this way, twrWasmModule could have been used (instead of the Async version) To port this code to twr-wasm I wrote a (very tiny) Win32 compatible API. It only implements the features needed to port maze, but it might be useful to use as a starting point for porting your Win32 code to the web. In the maze example, the two files are winemu.c and winemu.h. You use winemu.h to replace windows.h Maze import {twrWasmModuleAsync} from \"twr-wasm\"; export async function mazeRunner() { const amod=new twrWasmModuleAsync(); await amod.loadWasm('maze.wasm'); //void CalcMaze(HWND hWnd, LONG cell_size, LONG is_black_bg, LONG isd - slow draw) await amod.callC([\"CalcMaze\", 0, 7, 0, 1]); await amod.callC([\"SolveBegin\"]); let timer = setInterval(async ()=>{ let isdone=await amod.callC([\"SolveStep\", 0]); //SolveStep(hwnd)) if (isdone) clearInterval(timer); }, 50); }","title":"maze"},{"location":"examples/examples-more/","text":"More Web Assembly Examples Some other examples include: function-calls demos the different types of parameters that can be passed to a C function tests are the twr-wasm unit tests All Examples Live & Source The source for all of the examples is here on github All of the examples are available to view running live on the internet","title":"more"},{"location":"examples/examples-overview/","text":"Web Assembly C/C++ Examples These C and C++ examples demonstrate how to create different types of Web Assembly (wasm) programs with the twr-wasm library. These are good examples to use as starting points for your own wasm projects. These examples are a good place to learn how to configure clang and wasm-ld to compile and link C/C++ code for use with Web Assembly (wasm). Example Quick Links Click here to view C/C++ Web Assembly twr-wasm examples running live Click here to view source code and make files Examples Overview Each of these examples are designed to illustrate how to use a feature of twr-wasm. Name Description Link helloworld A very simple C wasm example to get you started helloworld stdio-div This simple C program demos inputting and printing characters to a div tag stdio-div stdio-canvas This simple C program demos writing and inputting from a tag that twr-wasm configures as a windowed \"mini-terminal\" stdio-canvas balls These fun Bouncing Balls are written in C++ and demo the 2D drawing APIs with a C++ Canvas wrapper class balls maze This is an old Win32 program ported to wasm and demos the 2D Draw APIs maze fft A demo of calling a C library to perform an FFT that is graphed in Typescript fft tests-libcxx Smoke test for libc++. Shows how to use libc++. tests-libcxx tests-user \"cli\" for tests using libc++ and tests-user more Demo of function calls, units tests more Building the Examples See Example Readme for more information on building and running the examples.","title":"Overview"},{"location":"examples/examples-stdio-canvas/","text":"stdio-canvas - Web Assembly 'terminal' C Example Print and input \"Hello World\" from a \"terminal\" window. A tiny Web Assembly C \"terminal\" can be created with input and output direct to a tag, and you can use it for character I/O with control over where the character appear in the terminal window. This example will move a string up or down in the terminal window when you press the u or d key. View stdio-canvas running live View stdio-canvas Source For another 'terminal' demo View tests-user #include #include #include #include \"twr-crt.h\" #include \"twr-wasm.h\" /* this twr-wasm C example draws a string in the middle of a windowed console, */ /* and allows the user to move the string up or down with the u or d keys */ /* see include/twr-io.h for available functions to draw chars to windowed console */ void show_str_centered(struct IoConsoleWindow* iow, int h, const char* str); void stdio_canvas() { struct IoConsoleWindow* iow=(struct IoConsoleWindow*)twr_get_stdio_con(); if (!(iow->con.header.type&IO_TYPE_WINDOW)) { // could also use assert here twr_conlog(\"error - expected window console\\n\"); return; } int h, c; const char* str=\"Hello World (press u or d)\"; const char* spc=\" \"; h=iow->display.height/2; while (1) { show_str_centered(iow, h, str); c=twr_getc32(); show_str_centered(iow, h, spc); // erase old string if (c=='u') { h=h-1; if (h<0) h=0; } if (c=='d') { h=h+1; if (h>=iow->display.height) h=iow->display.height-1; } } } void show_str_centered(struct IoConsoleWindow* iow, int h, const char* str) { int strlen=strlen(str); int x=(iow->display.width-strlen)/2; io_set_cursorxy(iow, x, h); io_putstr(&iow->con, str); } stdio-canvas example ","title":"stdio-canvas"},{"location":"examples/examples-stdio-div/","text":"stdio-div - Web Assembly stdio-to-div C Example This simple Web Assembly C program demos inputting and printing characters to a div tag. view stdio-div running live View stdio-div Source #include #include #include \"twr-crt.h\" void stdio_div() { char inbuf[64]; int i; printf(\"Square Calculator\\n\"); while (1) { printf(\"Enter an integer: \"); twr_mbgets(inbuf); i=atoi(inbuf); printf(\"%d squared is %d\\n\\n\",i,i*i); } } With an index.html like the following. This time we are using twrWasmModuleAsync which integrates blocking C code into JavaScript. twrWasmModuleAsync can also be used to receive key input from a
      or tag. stdio-div example
      Loading...
      ","title":"stdio-div"},{"location":"gettingstarted/compiler-opts/","text":"Compiling, Linking, and Memory Options This section described how to use clang to compile C/C++ code for Web Assembly, and how to link your files into a .wasm module. twr-wasm lets you use clang directly, without a wrapper. This section describes the needed clang compile options and the wasm-ld link options. You can also take a look at the example makefiles . clang with C When compiling C code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -nostdinc -nostdlib -isystem ../../include -isystem should point to the folder twr-wasm/include . The option line above uses a relative link to include that works if your project is a sub folder in the examples folder. If you installed using npm, then includes are at node_modules/twr-wasm/include (see the installation note on npm ). You will also need to link to twr.a (explained in the linking section below). clang with C++ When compiling C++ code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -fno-exceptions -fno-rtti -nostdlibinc -nostdinc -nostdlib -isystem ../../include You will also need to link to twr.a and libc++.a (explained in the linking section below). Be sure to adjust the path to twr.a , libc++.a , and the include folder as needed (see above note in the C section). linking Use the wasm-ld linker directly with twr-wasm. All of the twr-wasm functions are staticly linked from the library lib-c/twr.a . There is also a version ( lib-c/twrd.a ) of twr-wasm library available with debug symbols. One of these two static libraries should be added to the list of files to link (normally this is twr.a ). Both versions are built with asserts enabled. twr.a is built with -O3 . twrd.a is built with -g -O0 . To use libc++ , link to libc++.a (see the tests-libcxx example makefile). C functions that you wish to call from JavaScript should either have an -export option passed to wasm-ld , or you can use the __attribute__((export_name(\"function_name\"))) option in your C function definition. All exported functions to JavaScript should be C linkage ( extern \"C\" if using C++). wasm-ld should also be passed the following options: If Using twrWasmModule: --no-entry --initial-memory= --max-memory= If Using twrWasmModuleAsync: --no-entry --shared-memory --no-check-features --initial-memory= --max-memory= Memory You set the memory size for your module ( WebAssembly.Memory ) using wasm-ld options as follows (this examples sets your wasm memory to 1MB). The memory size should be a multiple of 64*1024 (64K) chunks. if using twrWasmModule : --initial-memory=1048576 --max-memory=1048576 If you are using twrWasmModuleAsync , shared memory must also be enabled. Like this: --shared-memory --no-check-features --initial-memory=1048576 --max-memory=1048576 See this production note on using shared memory . The memory is an export out of the .wasm into the JavaScript code. There is no support for automatically growing memory. You can change your C/C++ stack size from the default 64K with the following wasm-ld option. This example sets the stack at 128K -z stack-size=131072 You can print your module memory map, heap stats, and stack size using the function from C: void twr_mem_debug_stats(struct IoConsole* outcon); You can call it from Javascript with the output sent to the debug console (stderr) like this: twrWasmModule/Async.callC([\"twr_wasm_print_mem_debug_stats\"]) twrWasmModule and twrWasmModuleAsync expose malloc as an async function, as well as the Web Assembly Module memory as: async malloc(size:number); memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array; to call free() from JavaScript (you probably won't need to), you can use: twrWasmModule/Async.callC(\"twr_free\", index); // index to memory to free, as returned by malloc","title":"Compiler, Linker, Memory"},{"location":"gettingstarted/compiler-opts/#compiling-linking-and-memory-options","text":"This section described how to use clang to compile C/C++ code for Web Assembly, and how to link your files into a .wasm module. twr-wasm lets you use clang directly, without a wrapper. This section describes the needed clang compile options and the wasm-ld link options. You can also take a look at the example makefiles .","title":"Compiling, Linking, and Memory Options"},{"location":"gettingstarted/compiler-opts/#clang-with-c","text":"When compiling C code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -nostdinc -nostdlib -isystem ../../include -isystem should point to the folder twr-wasm/include . The option line above uses a relative link to include that works if your project is a sub folder in the examples folder. If you installed using npm, then includes are at node_modules/twr-wasm/include (see the installation note on npm ). You will also need to link to twr.a (explained in the linking section below).","title":"clang with C"},{"location":"gettingstarted/compiler-opts/#clang-with-c_1","text":"When compiling C++ code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -fno-exceptions -fno-rtti -nostdlibinc -nostdinc -nostdlib -isystem ../../include You will also need to link to twr.a and libc++.a (explained in the linking section below). Be sure to adjust the path to twr.a , libc++.a , and the include folder as needed (see above note in the C section).","title":"clang with C++"},{"location":"gettingstarted/compiler-opts/#linking","text":"Use the wasm-ld linker directly with twr-wasm. All of the twr-wasm functions are staticly linked from the library lib-c/twr.a . There is also a version ( lib-c/twrd.a ) of twr-wasm library available with debug symbols. One of these two static libraries should be added to the list of files to link (normally this is twr.a ). Both versions are built with asserts enabled. twr.a is built with -O3 . twrd.a is built with -g -O0 . To use libc++ , link to libc++.a (see the tests-libcxx example makefile). C functions that you wish to call from JavaScript should either have an -export option passed to wasm-ld , or you can use the __attribute__((export_name(\"function_name\"))) option in your C function definition. All exported functions to JavaScript should be C linkage ( extern \"C\" if using C++). wasm-ld should also be passed the following options: If Using twrWasmModule: --no-entry --initial-memory= --max-memory= If Using twrWasmModuleAsync: --no-entry --shared-memory --no-check-features --initial-memory= --max-memory=","title":"linking"},{"location":"gettingstarted/compiler-opts/#memory","text":"You set the memory size for your module ( WebAssembly.Memory ) using wasm-ld options as follows (this examples sets your wasm memory to 1MB). The memory size should be a multiple of 64*1024 (64K) chunks. if using twrWasmModule : --initial-memory=1048576 --max-memory=1048576 If you are using twrWasmModuleAsync , shared memory must also be enabled. Like this: --shared-memory --no-check-features --initial-memory=1048576 --max-memory=1048576 See this production note on using shared memory . The memory is an export out of the .wasm into the JavaScript code. There is no support for automatically growing memory. You can change your C/C++ stack size from the default 64K with the following wasm-ld option. This example sets the stack at 128K -z stack-size=131072 You can print your module memory map, heap stats, and stack size using the function from C: void twr_mem_debug_stats(struct IoConsole* outcon); You can call it from Javascript with the output sent to the debug console (stderr) like this: twrWasmModule/Async.callC([\"twr_wasm_print_mem_debug_stats\"]) twrWasmModule and twrWasmModuleAsync expose malloc as an async function, as well as the Web Assembly Module memory as: async malloc(size:number); memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array; to call free() from JavaScript (you probably won't need to), you can use: twrWasmModule/Async.callC(\"twr_free\", index); // index to memory to free, as returned by malloc","title":"Memory"},{"location":"gettingstarted/helloworld/","text":"Hello World - Step-by-Step C to WASM This section shows you step by step how to to create a C \"hello world\" program for Web Assembly (WASM) with twr-wasm, C, HTML, and JavaScript. You will learn how to: Create the helloworld.c C file Create the index.html HTML File Compile the helloworld.c code Link the helloworld.o and twr.a files to create a helloworld.wasm file Set the needed library and include paths to allow the twr-wasm libraries to be discovered Create an optional Makefile Execute the \"hello world\" program using a local web server or directly with VS Code and Chrome You can find all of the code for this section in the folder examples\\helloworld . Step 1: Create the C code Create a file helloworld.c #include void hello() { printf(\"hello world\\n\"); } Step 2: Create the HTML Create a file index.html Hello World
      This example uses Import Maps, which are used when not using a bundler like WebPack or Parcel. This can be a simpler and more clear debugging and development environment. The relative path in the importmap section should be updated to point to the location where you installed twr-wasm/lib-js . The path above is correct if your file is in an example subfolder. As another example, if you used git clone https://github.com/twiddlingbits/twr-wasm to create a folder named twr-wasm and you create your hello world project with a folder structure like this: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm Then you would use an Import Map code snippet like this: Step 3: Compile your C code to create your .wasm file clang --target=wasm32 -nostdinc -nostdlib -isystem ../../include -c helloworld.c -o helloworld.o wasm-ld helloworld.o ../../lib-c/twr.a -o helloworld.wasm --no-entry --initial-memory=131072 --max-memory=131072 --export=hello The path to twr.a and to include may need to be updated to match your installation. The above path is correct if your code is in an example subfolder. Alternately, if you had the folder structure described in Step 2: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm \u2514\u2500\u2500 Makefile You could use a MakeFile like this: CC := clang TWRCFLAGS := --target=wasm32 -nostdinc -nostdlib -isystem twr-wasm/include CFLAGS := -c -Wall -O3 $(TWRCFLAGS) CFLAGS_DEBUG := -c -Wall -g -O0 $(TWRCFLAGS) .PHONY: default default: helloworld.wasm helloworld.o: helloworld.c $(CC) $(CFLAGS) $< -o $@ helloworld.wasm: helloworld.o wasm-ld helloworld.o twr-wasm/lib-c/twr.a -o helloworld.wasm \\ --no-entry --initial-memory=131072 --max-memory=131072 \\ --export=hello Step 4: Load your web page The two easiest ways to load and execute your index.html web page locally are: Option A: Run a local web Server You can run a local server to view your helloworld program. Copy the file server.py from the examples folder to your project folder where your index.html resides. Execute with the shell command python server.py . Option B: VS Code launch.json Alternately, you can launch chrome without a local web server. Add an entry similar to the following to your VS code project's .vscode\\launch.json . Adjust the file and cwd lines to be correct for your project. { \"name\": \"hello\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [ \"--allow-file-access-from-files\", \"--autoplay-policy=no-user-gesture-required\", \"--enable-features=SharedArrayBuffer\" ], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" } --autoplay-policy=no-user-gesture-required and --enable-features=SharedArrayBuffer are not required for this simple \"hello world\" example, but will be needed if you request user input or you are using twrWasModuleAsync. See live version Here is a link to the helloworld function running in the twiddlingbits.dev site. Next steps after hello world A good way to get your own code up and running is to copy one of the twr-wasm/examples , get it to build and run, then start modifying it. The example makefiles prove a more practical way to configure and execute clang and wasm-ld. \"Hello World\" uses the twr-wasm class twrWasmModule . If you wish to use C blocking functions, such as twr_getc32 or twr_sleep , you can use twrWasmModuleAsync . This square calculator example shows how to do this. If you wish to build an app that makes non-block calls into C, the balls example shows how to do this. The maze example uses a combination of blocking and non-blocking C functions.","title":"Create wasm C Hello World"},{"location":"gettingstarted/helloworld/#hello-world-step-by-step-c-to-wasm","text":"This section shows you step by step how to to create a C \"hello world\" program for Web Assembly (WASM) with twr-wasm, C, HTML, and JavaScript. You will learn how to: Create the helloworld.c C file Create the index.html HTML File Compile the helloworld.c code Link the helloworld.o and twr.a files to create a helloworld.wasm file Set the needed library and include paths to allow the twr-wasm libraries to be discovered Create an optional Makefile Execute the \"hello world\" program using a local web server or directly with VS Code and Chrome You can find all of the code for this section in the folder examples\\helloworld .","title":"Hello World - Step-by-Step C to WASM"},{"location":"gettingstarted/helloworld/#step-1-create-the-c-code","text":"Create a file helloworld.c #include void hello() { printf(\"hello world\\n\"); }","title":"Step 1: Create the C code"},{"location":"gettingstarted/helloworld/#step-2-create-the-html","text":"Create a file index.html Hello World
      This example uses Import Maps, which are used when not using a bundler like WebPack or Parcel. This can be a simpler and more clear debugging and development environment. The relative path in the importmap section should be updated to point to the location where you installed twr-wasm/lib-js . The path above is correct if your file is in an example subfolder. As another example, if you used git clone https://github.com/twiddlingbits/twr-wasm to create a folder named twr-wasm and you create your hello world project with a folder structure like this: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm Then you would use an Import Map code snippet like this: ","title":"Step 2: Create the HTML"},{"location":"gettingstarted/helloworld/#step-3-compile-your-c-code-to-create-your-wasm-file","text":"clang --target=wasm32 -nostdinc -nostdlib -isystem ../../include -c helloworld.c -o helloworld.o wasm-ld helloworld.o ../../lib-c/twr.a -o helloworld.wasm --no-entry --initial-memory=131072 --max-memory=131072 --export=hello The path to twr.a and to include may need to be updated to match your installation. The above path is correct if your code is in an example subfolder. Alternately, if you had the folder structure described in Step 2: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm \u2514\u2500\u2500 Makefile You could use a MakeFile like this: CC := clang TWRCFLAGS := --target=wasm32 -nostdinc -nostdlib -isystem twr-wasm/include CFLAGS := -c -Wall -O3 $(TWRCFLAGS) CFLAGS_DEBUG := -c -Wall -g -O0 $(TWRCFLAGS) .PHONY: default default: helloworld.wasm helloworld.o: helloworld.c $(CC) $(CFLAGS) $< -o $@ helloworld.wasm: helloworld.o wasm-ld helloworld.o twr-wasm/lib-c/twr.a -o helloworld.wasm \\ --no-entry --initial-memory=131072 --max-memory=131072 \\ --export=hello","title":"Step 3: Compile your C code to create your .wasm file"},{"location":"gettingstarted/helloworld/#step-4-load-your-web-page","text":"The two easiest ways to load and execute your index.html web page locally are:","title":"Step 4: Load your web page"},{"location":"gettingstarted/helloworld/#option-a-run-a-local-web-server","text":"You can run a local server to view your helloworld program. Copy the file server.py from the examples folder to your project folder where your index.html resides. Execute with the shell command python server.py .","title":"Option A: Run a local web Server"},{"location":"gettingstarted/helloworld/#option-b-vs-code-launchjson","text":"Alternately, you can launch chrome without a local web server. Add an entry similar to the following to your VS code project's .vscode\\launch.json . Adjust the file and cwd lines to be correct for your project. { \"name\": \"hello\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [ \"--allow-file-access-from-files\", \"--autoplay-policy=no-user-gesture-required\", \"--enable-features=SharedArrayBuffer\" ], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" } --autoplay-policy=no-user-gesture-required and --enable-features=SharedArrayBuffer are not required for this simple \"hello world\" example, but will be needed if you request user input or you are using twrWasModuleAsync.","title":"Option B: VS Code launch.json"},{"location":"gettingstarted/helloworld/#see-live-version","text":"Here is a link to the helloworld function running in the twiddlingbits.dev site.","title":"See live version"},{"location":"gettingstarted/helloworld/#next-steps-after-hello-world","text":"A good way to get your own code up and running is to copy one of the twr-wasm/examples , get it to build and run, then start modifying it. The example makefiles prove a more practical way to configure and execute clang and wasm-ld. \"Hello World\" uses the twr-wasm class twrWasmModule . If you wish to use C blocking functions, such as twr_getc32 or twr_sleep , you can use twrWasmModuleAsync . This square calculator example shows how to do this. If you wish to build an app that makes non-block calls into C, the balls example shows how to do this. The maze example uses a combination of blocking and non-blocking C functions.","title":"Next steps after hello world"},{"location":"gettingstarted/installation/","text":"Installing twr-wasm This section describes how to install twr-wasm on your computer so that you can compile and link C/C++ to Web Assembly (WASM). npm install twr-wasm or git clone https://github.com/twiddlingbits/twr-wasm npm install will install everything necessary to build your software: built libraries (lib-js, lib-c), include. In addition the examples are installed. git clone will copy the built libraries (lib-js, lib-c), include, as well as the source, examples, doc source and VS Code settings. Either will work, although with different pros and cons -- see the below notes. After installation, Using twr-wasm can be a bit more complicated than using a package that is all JavaScript because your applications need to use twr-wasm JavaScript and C libraries. Installs for your C/C++ code To build C/C++ code for use in your wasm project, you will need to install clang and the wasm-ld linker. If you are using Windows, more details can be found at the end of the Building Source section. A Note on npm install After installation from npm, you will have a folder structure like this: node_modules\\ twr-wasm\\ examples\\ include\\ lib-c\\ lib-js\\ LICENSE package.json readme.md The JavaScript and TypeScript exports are in lib-js and should be found by VS Code, TypeScript or your bundler as usual when using a statement like import {twrWasmModule} from \"twr-wasm\" . The C library ( twr.a ) that you will need to link your C/C++ program to is found in the libs-c folder, and the C/C++ include files that you will need to use in your C/C++ program are found in the include folder. You will need to use paths to to these folders in your make file . All of the examples (in the examples folder above) have make files that use a relative path for twr.a and includes . These paths will work fine if your code is in an examples sub-folder as a peer to the other examples. But assuming your code is in your own project folder elsewhere, you will need to determine the correct path to twr.a and includes from your project's make file. Details on how to do this can be found in the leter sections: Hello World walkthrough and the Compiler and Linker Options section . There is no real downside to this installation method, except possibly: (1) it does not include source code (use git clone for that), and (b) the C libraries are buried inside your node_modules. A Note on git clone install This method of installation installs the complete code base, including source and build binaries. The primary downside to this method is that the JavaScript side of twr-wasm will not be placed in a node_modules folder. This will likely make it difficult for a bundler, TypeScript or VS Code to find the location of imports. There are a few solutions to this. In the provided hello world example, I use a package.json file with an alias entry. This syntax is supported by the Parcel bundler: { \"@parcel/resolver-default\": { \"packageExports\": true }, \"alias\": { \"twr-wasm\": \"../../lib-js/index.js\" }, \"dependencies\": { \"twr-wasm\": \"^2.0.0\" } } In the FFT example, I use the paths entry in the tsconfig.json file. This is found by TypeScript, VS Code and the Parcel bundler. \"paths\": { \"twr-wasm\": [\"./../../lib-js/index\"] } The paths for alias and paths shown above are correct for the included examples, but will likely need to be adjust for your project (see the following section \"Your First C Web Assembly Program\" ) As a alternative, you could install with both npm and git .","title":"Installation"},{"location":"gettingstarted/keyconcepts/","text":"Key Concepts - C/C++ WASM This section describes some key concepts that apply when using twr-wasm with your C/C++ Web Assembly code. Overview Your C/C++ Web Assembly 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 Web Assembly module by your JavaScript or HTML. 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. On the JavaScript side you will use the twr-wasm JavaScript/TypeScript class twrWasmModule or twrWasmModuleAsync to load the .wasm module, and then call C functions in it (more details are in the TypeScript/Javascript API section ). 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
      or 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 parameters. The C/C++ code could then generate no output, could render to a
      or using stdio type C/C++ functions, or it could render to a 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
      or to your HTML ( see stdio ) Use new twrWasmModule() , followed by a call to loadWasm() , then one or more callC() . Alternately, use twrWasmModuleAsync() -- which is interchangeable with twrWasmModule, but proxies through a worker thread, and adds blocking support, including blocking char input. Passing strings, arrayBuffers, etc The Web Assembly runtime provided in a browser will only pass numbers between C functions and JavaScript functions. This means if you use twrWasmModule.callC to call a C function, and pass integers or floats as arguments, they will work as expected. But if you pass a string, arrayBuffer, or the contents or a URL, twrWasmModule.callC will: allocate memory in your WebAssembly.Memory (using malloc). copy the string (or arrayBuffer or URL contents) into this memory. pass the memory index (aka a pointer in C land) to your C code. If URL contents are passed, your C function will receive a pointer to the data as the first argument, and a length as the second argument. If an arrayBuffer is passed to your C/C++ code, you probably will also need to pass in the length (unless it is already known). Upon return, the malloced memory is freed, and if the argument was an arrayBuffer, the appropriate contents in the wasm module memory are copied back into the arrayBuffer. This means that if your C code modifies a passed in block of arrayBuffer memory, the results will be reflected back into javaScript land. Some module functions (such as getString ) take or return an \"index:number\". Here index means an index into WebAssembly.Memory. As far as your C code is concerned, this is a pointer. Recalled that an arrayBuffer can be created and accessed using classes like Uint8Array or Float32Array . It is helpful to look at the examples .","title":"Key Concepts"},{"location":"gettingstarted/stdio/","text":"Stdio with C/C++ Web Assembly This section describes how you can direct C/C++ standard input or output to or from a div or canvas tag in a twr-wasm C/C++ wasm project. Use div or canvas tag Standard input and output can be directed to a
      or to a HTML tag. A
      is used for streamed character input and output, and a is used for sending characters or simple graphics to windowed input and output. In the windowed mode, the position of characters in a \"terminal\" style window can be specified. In windowed mode, you can use functions that output to stdout or input from stdin, as well as functions that use x,y coordinates, colors, etc.
      will be used for stdin and stdout if found. will be used for stdin and stdout if it exists and no div found. if neither of the above
      or is defined in your HTML, then stdout is sent to the debug console in your browser. And stdin is not available. If you use twrWasmModule options, a fourth null options is available. Unicode characters and symbols are supported in stdout and stdin and windowed i/o (see localization ). The window console also supports chunky (low res) graphics (each character cell can be used as a 2x3 graphic array). stderr streams to the browser's debug console. Examples Name View Live Link Source Link stdin and stdout to
      View square demo Source simple \"terminal\" via View hello world demo Source \"cli\" with a stdio View CLI demo using libc++ Source IO Console Docs stdin , stdout , and stderr are abstracted by a twr-wasm IO Consoles . UTF-8 or Windows-1252 Stdin and stdout can support UTF-8 or Windows-1252 character encodings (see localization ) stdout or stderr #include to access stdout , stdin , stderr , and FILE . FILE is supported for user input and output, and for stderr. File i/o (to a filesystem) is not currently supported. You can use these functions to output to the standard library defines stderr or stdout : fputc, putc, vfprintf, fprintf, fwrite You can use the IO Console functions referenced above to send to stdout and stderr . These functions go to stdout: printf, vprintf, puts, putchar Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. For example: #include fprintf(stderr, \"hello over there in browser debug console land\\n\"); A more common method to send output to the debug console is to use twr_conlog . See General C API Section . stdin You can get characters from the standard C define stdin with these functions: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) Reading from stdin is blocking, and so twrWasmModuleAsync must be used to receive keys from stdin. JavaScript needed for char input You should add a line like the following to your JavaScript for stdin to work: for twr_iodiv document.getElementById(\"twr_iodiv\").addEventListener(\"keydown\",(ev)=>{amod.keyDownDiv(ev)}); for twr_iocanvas document.getElementById(\"twr_iocanvas\").addEventListener(\"keydown\",(ev)=>{amod.keyDownCanvas(ev)}); You likely want a line like this to set the focus to the div or canvas so the user doesn't have to click on it: document.getElementById(\"twr_iocanvas\").focus(); You will also need to set the tabindex attribute in your div tag like this:
      See the stdio-div and stdio-canvas examples. Note that this section describes blocking input using stdin. As an alternative, you can send events (keyboard, mouse, timer, etc) to a non-blocking C function from JavaScript using callC . See the balls example.","title":"Stdio"},{"location":"more/building/","text":"Building the Source Source for twr-wasm The source can be found at: https://github.com/twiddlingbits/twr-wasm The main branch contains the latest release. The dev branch is work in progress. Tools needed You will need these core tools: NPM - package manager Typescript clang tool chain - for C/C++ code wasm-ld - to link the .wasm files wat2wasm - to compile web assembly (.wat) files of which I have a few GNU make git - to clone twr-wasm source, or to clone llvm, if you want to build libc++ In addition, you might need: VS Code - to use the debug launcher and build tasks Parcel v2 - to bundle the examples mkdocs - to build the documentation static web site python - mkdocs is built with python, and you need python to run server.py in examples CMake and ninja - to build llvm libc++ There is a deprecated gcc build that I used to use for testing, but now the tests are executed in wasm. To Build the Libraries (lib-c, lib-js) cd source make or on windows cd source mingw32-make To Build the Examples See examples/readme.md for more information. To build the examples, but not bundle them. cd examples sh buildall.sh To build bundles: sh buildbundles.sh To Build the docs In twr-wasm root folder: mkdocs build The destination of the build is found in the mkdocs.yml file ( site_dir: azure/docsite/ ). Usually the docs are built as part of building the static web site that hosts the docs and examples. This is accomplished using this shell script (found in examples folder): buildazure.sh To Build libc++ for wasm and twr-wasm See the instructions in the comments in the shell script source\\libcxx\\buildlibcxx.sh Installing clang and wasm-ld on Windows Here is how I installed the tools for windows: install MSYS2 1. https://www.msys2.org/ 2. After the install completes, run UCRT64 terminal by clicking on the MSYS2 UCRT64 in the Start menu 3. pacman -Syuu install gcc using MSYS2 UCRT64 1. Use MSYS2 UCRT64 terminal (per above) 1. pacman -S mingw-w64-ucrt-x86_64-toolchain install clang and wasm-ld using MSYS2 UCRT64 2. Use MSYS2 UCRT64 (per above) 1. pacman -S mingw-w64-ucrt-x86_64-clang 2. pacman -S mingw-w64-x86_64-lld update PATH env variable using the windows control panel (search for path) 2. added C:\\msys64\\ucrt64\\bin 3. added C:\\msys64\\mingw64\\bin 4. added C:\\msys64\\usr\\bin (for sh.exe used by mingw32-make) wabt tools: can be found here https://github.com/WebAssembly/wabt/releases","title":"Building the Source"},{"location":"more/debugging/","text":"Debugging This section describes some tips for debugging your Web Assembly (asm) program. Debug & Release libs There are release (twr.a) and debug (twrd.a) versions of the twr-wasm C library. See the examples for use of both. The \"debug\" version has debug symbols enabled and is built with -O0 . The \"release\" version has no debug symbols and optimization is set to -O3 . Both have asserts enabled. In general, you should use the \"release\" version unless you wish to step through the twr-wasm source -- in which case use the \"debug\" version. libc++.a is not built with debug symbols. C/C++ Source Level Debugging In order to enable C/C++ source debugging with wasm and clang, do the following: Use Chrome Install the Chrome extension: C/C++ DevTools Support (DWARF) ( https://chromewebstore.google.com/detail/pdcpmagijalfljmkmjngeonclgbbannb ) Use the clang compile flag -g to add debug annotation to your object files You will may want to turn off optimization to allow the debugger to have a bit more logical behavior (remove the -O flag or set to -O0) You may want to use the version of the twr-wasm C library that has debug symbols enabled (twrd.a). Only if you want to step into the twrd.a source. You need to serve your files with a (likely local) web server. For example, 'python server.py' is provided. 'server.py' can be found in the examples root folder. Note that your local server needs to enable SharedArrayBuffers -- see the server.py example. your code can be bundled or unbundled, but you need to ensure that the web server/browser can find the source code also see Example Readme Useful Functions Use twr_conlog to print 'printf' style to the JavaScript console from C (reference is elsewhere in this doc.) #include \"twr-wasm.h\" twr_conlog(\"hello 99 in hex: %x\",99); Use twrWasmModule.divLog() to print to a div inside JavaScript code (reference is elsewhere in this doc.) Testing Without a Web Server Note: If you use this technique, you will not be able to get the c/C++ DevTool chrome extension to run, and so source level debugging won't work. You can execute and debug JavaScript with wasm from local files without an HTTP server. It might be helpful to download the twr-wasm source code from github when you do this (so you can step through the twr-wasm typescript code as needed). See the examples and Example Readme for more detail on how this works. In general, you will need to add a clip of code similar to this to your HTML: Make sure the paths are correct. You will need to set the following flags when running chrome from the shell (the first is only strictly required if using twrWasmModuleAsync): --enable-features=SharedArrayBuffer --allow-file-access-from-files You can create a launch.json entry similar to this: { \"name\": \"Examples\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [\"--allow-file-access-from-files\",\"--autoplay-policy=no-user-gesture-required\",\"--enable-features=SharedArrayBuffer\"], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" }","title":"Debugging WASM"},{"location":"more/production/","text":"Production Important Production Note twr-wasm class twrWasmModuleAsync uses SharedArrayBuffers, and there are special CORS headers needed for these, that are not widely enabled by default on web servers. server.py or staticwebapp.config.json shows which headers to set (also see the SharedArrayBuffer documentation online).","title":"Production"},{"location":"more/wasm-problem/","text":"WASM Runtime Limitations HTML browsers can load a Web Assembly module, and execute it's bytecode in a browser virtual machine. You compile your code using clang with the target code format being web assembly (wasm) byte code. There are a few issues that one immediately encounters trying to execute code that is more complicated than squaring a number. The first is that there is no C/C++ runtime support native to a Web Assembly module. That is, no malloc or printf or similar functions. Even beyond than that, there are missing compiler support functions. That is, clang code generation will produce calls for compiler support routines needed for floating point, memcpy, and the like. This code is usually handled behind the scenes for you. For example, gcc will link to \"libgcc\" automatically. clang uses \"compile-rt\". This doesn't happen with Web Assembly compiles (unless you use emscripten or twr-wasm). The second problem is that all the function calls between your wasm module and your javascript are limited to parameters and return values that are numbers (integer and float). No strings, arrays, struct pointers, etc. The third problem is that legacy C code or games often block, and when written this way they don't naturally integrate with the JavaScript asynchronous programming model. twr-wasm is a static C library (twr.a) that you can link to your clang C/C++ code, as well as a set of JavaScript/Typescript modules that solve these issues.","title":"WASM Runtime Limitations"}]} \ No newline at end of file +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"twr-wasm - Easy C/C++ Web Assembly Modules Documentation for twr-wasm Version 2.1.0 twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web Assembly code directly with clang. It solves some common use cases with less work than the more feature rich emscripten. twr-wasm is easy to understand, and has some cool features. You can input and print streaming character i/o to a
      tag, use a element as an ANSI terminal, or use a C/C++ 2D drawing api (that is compatible with JavaScript Canvas APIs) to draw to a element. You can run blocking C/C++. twr-wasm allows you to run C/C++ code in a web browser. Legacy code, libraries, full applications, or single functions can be integrated with JavaScript and Typescript. twr-wasm is designed to be used with the standard llvm clang compiler and tools. twr-wasm was previously named tiny-wasm-runtime. View C++ Web Assembly Bouncing Ball Demo View bouncing balls here Key Features compile and link C/C++ for use with web assembly using clang directly standard C library, libc++. and purpose built APIs available from C/C++ TypeScrpt/JavaScript classes to load WASM modules and call C/C++ functions localization support, UTF-8, and windows-1252 support in C/C++, print and get characters to/from
      tags in your HTML page in C/C++, print and get characters to/from a based \"terminal\" in C/C++ use 2D drawing API compatible with JavaScript Canvas in C/C++, use the \"blocking loop\" pattern and integrate with Javascript's asynchronous event loop Why? WASM Runtime Limitations section explains why a library like twr-wasm is needed to use Web Assembly. Hello World Here is the simplest twr-wasm example. C code: #include void hello() { printf(\"hello world\\n\"); } index.html: Hello World
      View Live Web Assembly Demos Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze Source for maze Input from
      View square demo Source Mini-Terminal (hello world using ) View demo Source Mini-Terminal (\"cli\" using libc++ and ) View console Source On Github https://github.com/twiddlingbits/twr-wasm Version 2 vs. 1 libc++ built for Web Assembly is included most of the standard C library is now implemented instructions for Web Assembly C/C++ source level debugging version of library with debug symbols provided locale, UTF-8, and windows-1252 support Version 2 Limitations libc++ not built with exceptions enabled some standard C library functions are not 100% implemented Designed to work with a browser. Not tested with or designed to work with node.js Not all of compile-rt is ported (but most bits you need are) The following non-compatible changes since 1.0 (relatively minor) there is no longer 'twr_' prefixed std c lib functions (use the normal std c lib names) most 'twr_wasm_' prefixed functions have been shortened to 'twr_'. some functions were renamed or changed slightly to be more consistent, but no functionality is lost. Post Feedback Please post feedback (it worked for you, didn't work, requests, questions, etc) at https://github.com/twiddlingbits/twr-wasm/","title":"Home"},{"location":"#twr-wasm-easy-cc-web-assembly-modules","text":"Documentation for twr-wasm Version 2.1.0 twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web Assembly code directly with clang. It solves some common use cases with less work than the more feature rich emscripten. twr-wasm is easy to understand, and has some cool features. You can input and print streaming character i/o to a
      tag, use a element as an ANSI terminal, or use a C/C++ 2D drawing api (that is compatible with JavaScript Canvas APIs) to draw to a element. You can run blocking C/C++. twr-wasm allows you to run C/C++ code in a web browser. Legacy code, libraries, full applications, or single functions can be integrated with JavaScript and Typescript. twr-wasm is designed to be used with the standard llvm clang compiler and tools. twr-wasm was previously named tiny-wasm-runtime.","title":"twr-wasm - Easy C/C++ Web Assembly Modules"},{"location":"#view-c-web-assembly-bouncing-ball-demo","text":"View bouncing balls here","title":"View C++ Web Assembly Bouncing Ball Demo"},{"location":"#key-features","text":"compile and link C/C++ for use with web assembly using clang directly standard C library, libc++. and purpose built APIs available from C/C++ TypeScrpt/JavaScript classes to load WASM modules and call C/C++ functions localization support, UTF-8, and windows-1252 support in C/C++, print and get characters to/from
      tags in your HTML page in C/C++, print and get characters to/from a based \"terminal\" in C/C++ use 2D drawing API compatible with JavaScript Canvas in C/C++, use the \"blocking loop\" pattern and integrate with Javascript's asynchronous event loop","title":"Key Features"},{"location":"#why","text":"WASM Runtime Limitations section explains why a library like twr-wasm is needed to use Web Assembly.","title":"Why?"},{"location":"#hello-world","text":"Here is the simplest twr-wasm example. C code: #include void hello() { printf(\"hello world\\n\"); } index.html: Hello World
      ","title":"Hello World"},{"location":"#view-live-web-assembly-demos","text":"Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze Source for maze Input from
      View square demo Source Mini-Terminal (hello world using ) View demo Source Mini-Terminal (\"cli\" using libc++ and ) View console Source","title":"View Live Web Assembly Demos"},{"location":"#on-github","text":"https://github.com/twiddlingbits/twr-wasm","title":"On Github"},{"location":"#version-2-vs-1","text":"libc++ built for Web Assembly is included most of the standard C library is now implemented instructions for Web Assembly C/C++ source level debugging version of library with debug symbols provided locale, UTF-8, and windows-1252 support","title":"Version 2 vs. 1"},{"location":"#version-2-limitations","text":"libc++ not built with exceptions enabled some standard C library functions are not 100% implemented Designed to work with a browser. Not tested with or designed to work with node.js Not all of compile-rt is ported (but most bits you need are) The following non-compatible changes since 1.0 (relatively minor) there is no longer 'twr_' prefixed std c lib functions (use the normal std c lib names) most 'twr_wasm_' prefixed functions have been shortened to 'twr_'. some functions were renamed or changed slightly to be more consistent, but no functionality is lost.","title":"Version 2 Limitations"},{"location":"#post-feedback","text":"Please post feedback (it worked for you, didn't work, requests, questions, etc) at https://github.com/twiddlingbits/twr-wasm/","title":"Post Feedback"},{"location":"api/api-c-con/","text":"Console C API for Web Assembly (Streamed and Windowed) This section describes twr-wasm's method of providing and abstracting console I/O in Web Assembly Modules. C character based input/output is abstracted by struct IoConsole . Consoles can be \"tty\" aka \"streamed\", or they can be \"windowed\" (aka a \"terminal\"). Also see stdio Examples Name View Live Link Source Link \"terminal\" in/out with a View mini-term demo Source Getting stderr,stdin, stdout stdio.h defines stdin , stdout , stderr as explained here: stdio stdio.h also defines FILE like this: typedef struct IoConsole FILE; from : #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) Getting a new console stdin and stdout are set as explaind here . However, in unusual cases you might want to access the various consoles directly, regardless of how stdin, stdout, or stderr are set. You can do so like this: io_nullcon Returns an IoConsole that goes to the bit bucket. io_getc32 will return 0. #include \"twr-io.h\" struct IoConsole* io_nullcon(void); twr_debugcon Returns an IoConsole that goes to the browser's debug console. #include \"twr-crt.h\" struct IoConsole* twr_debugcon(void); twr_divcon Returns an IoConsole that goes to
      , if it exists. #include \"twr-crt.h\" struct IoConsole* twr_divcon(void); twr_windowcon Returns an IoConsole that goes to , if it exists. NOTE: Only one call can be made to this function, and it is usually made by the twr-wasm C runtime, so you likely won't call this function. #include \"twr-crt.h\" struct IoConsole* twr_windowcon(void); IO Console Functions io_putc Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_putc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_putc once for each byte of the multi-byte UTF-8 character). Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. #include \"twr-io.h\" void io_putc(struct IoConsole* io, unsigned char c); io_putstr Calls io_putc for each byte in the passed string. #include \"twr-io.h\" void io_putstr(struct IoConsole* io, const char* s); io_printf Identical to fprintf , however io_printf will call io_begin_draw and io_end_draw around its drawing activities -- resulting in snapper performance. For example: #include \"twr-io.h\" io_printf(twr_debugcon(), \"hello over there in browser debug console land\\n\"); or #include #include io_printf(stdout, \"hello world\\n\"); #include void io_printf(struct IoConsole *io, const char *format, ...); io_getc32 Waits for the user to enter and then returns a unicode code point. Currently only really works with an IoConsole that is stdin. To return characters encoded with the current locale, see io_mbgetc #include int io_getc32(struct IoConsole* io); io_mbgetc io_mbgetc will get a character from stdin and encode it using the character encoding of the LC_CTYPE category of the current locale. \"C\" will use ASCII. UTF-8 and windows-1252 are also supported. #include void io_mbgetc(struct IoConsole* io, char* strout); io_mbgets Gets a string from an IoConsole (which needs to be stdin). Returns when the user presses \"Enter\". Displays a cursor character and echos the inputted characters, at the current cursor position. Uses character encoding of LC_TYPE of current locale. #include char *io_mbgets(struct IoConsole* io, char *buffer ); io_get_cursor Returns an integer of the current cursor position. The cursor is where the next io_putc is going to go. For windowed consoles, the cursor position ranges from [0, width*height-1], inclusive. #include int io_get_cursor(struct IoConsole* io); io_set_colors For windowed consoles only. Sets a 24 bit RGB default color for the foreground and background. The prior default colors are changed (lost). For example, if you set the default colors when you created the window (see stdio ), the defaults will no longer be active. Use io_get_colors to save existing colors for later restoration using io_set_colors . A call to io_set_colors doesn't actually cause any on screen changes. Instead, these new default colors are used in future draw and text calls. A foreground and background color is set for each cell in the console window. The cell's colors are set to these default foreground/background colors when a call to io_setc , io_setreset , etc is made. #include void io_set_colors(struct IoConsole* io, unsigned long foreground, unsigned long background); io_get_colors For windowed consoles only. Gets the current default colors. #include void io_get_colors(struct IoConsole* io, unsigned long *foreground, unsigned long *background); io_cls For windowed consoles only. Clears the screen. That is, all character cells in the window are set to a space, their colors are reset to the current default colors (see io_set_colors ). #include void io_cls(struct IoConsoleWindow* iow); io_setc For windowed consoles only. Sets a window cell to a character. Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_setc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_setc once for each byte of the multi-byte UTF-8 character). #include bool io_setc(struct IoConsoleWindow* iow, int location, unsigned char c); io_setc32 For windowed consoles only. Sets a window cell to a unicode code point. The colors are set to the defaults (see io_set_colors ). #include void io_setc32(struct IoConsoleWindow* iow, int location, int c); io_setreset For windowed consoles only. Sets or resets (clears) a chunky graphics \"pixel\". Each character cell can also be a 2x3 grid of graphic \"pixels\". In other words, the terminal window has pixel dimensions of width 2 x height 3. The color will be set to the defaults if the impacted cell is not a graphics cell. If it is an existing graphics cell, the colors don't change. See the stdio-canvas example. #include bool io_setreset(struct IoConsoleWindow* iow, int x, int y, bool isset); io_point For windowed consoles only. Checks if a chunky graphics \"pixel\" is set or clear. See io_setreset . #include bool io_point(struct IoConsoleWindow* iow, int x, int y); io_set_cursor Moves the cursor. See io_get_cursor . #include void io_set_cursor(struct IoConsoleWindow* iow, int loc); io_begin_draw For windowed consoles only. This call (and its matching io_end_draw) are not required. But if you bracket any call sequence that draws to the terminal window with an io_begin_draw and io_end_draw , the updates will be batched into one update. io_begin_draw can be nested. This will increase performance and usually prevents the user from seeing partial updates. See the terminal-window io_canvas example. #include void io_begin_draw(struct IoConsole* io); io_end_draw For windowed consoles only. See io_begin_draw . #include void io_end_draw(struct IoConsole* io);","title":"C Console I/O"},{"location":"api/api-c-con/#console-c-api-for-web-assembly-streamed-and-windowed","text":"This section describes twr-wasm's method of providing and abstracting console I/O in Web Assembly Modules. C character based input/output is abstracted by struct IoConsole . Consoles can be \"tty\" aka \"streamed\", or they can be \"windowed\" (aka a \"terminal\"). Also see stdio","title":"Console C API for Web Assembly (Streamed and Windowed)"},{"location":"api/api-c-con/#examples","text":"Name View Live Link Source Link \"terminal\" in/out with a View mini-term demo Source","title":"Examples"},{"location":"api/api-c-con/#getting-stderrstdin-stdout","text":"stdio.h defines stdin , stdout , stderr as explained here: stdio stdio.h also defines FILE like this: typedef struct IoConsole FILE; from : #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con())","title":"Getting stderr,stdin, stdout"},{"location":"api/api-c-con/#getting-a-new-console","text":"stdin and stdout are set as explaind here . However, in unusual cases you might want to access the various consoles directly, regardless of how stdin, stdout, or stderr are set. You can do so like this:","title":"Getting a new console"},{"location":"api/api-c-con/#io_nullcon","text":"Returns an IoConsole that goes to the bit bucket. io_getc32 will return 0. #include \"twr-io.h\" struct IoConsole* io_nullcon(void);","title":"io_nullcon"},{"location":"api/api-c-con/#twr_debugcon","text":"Returns an IoConsole that goes to the browser's debug console. #include \"twr-crt.h\" struct IoConsole* twr_debugcon(void);","title":"twr_debugcon"},{"location":"api/api-c-con/#twr_divcon","text":"Returns an IoConsole that goes to
      , if it exists. #include \"twr-crt.h\" struct IoConsole* twr_divcon(void);","title":"twr_divcon"},{"location":"api/api-c-con/#twr_windowcon","text":"Returns an IoConsole that goes to , if it exists. NOTE: Only one call can be made to this function, and it is usually made by the twr-wasm C runtime, so you likely won't call this function. #include \"twr-crt.h\" struct IoConsole* twr_windowcon(void);","title":"twr_windowcon"},{"location":"api/api-c-con/#io-console-functions","text":"","title":"IO Console Functions"},{"location":"api/api-c-con/#io_putc","text":"Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_putc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_putc once for each byte of the multi-byte UTF-8 character). Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. #include \"twr-io.h\" void io_putc(struct IoConsole* io, unsigned char c);","title":"io_putc"},{"location":"api/api-c-con/#io_putstr","text":"Calls io_putc for each byte in the passed string. #include \"twr-io.h\" void io_putstr(struct IoConsole* io, const char* s);","title":"io_putstr"},{"location":"api/api-c-con/#io_printf","text":"Identical to fprintf , however io_printf will call io_begin_draw and io_end_draw around its drawing activities -- resulting in snapper performance. For example: #include \"twr-io.h\" io_printf(twr_debugcon(), \"hello over there in browser debug console land\\n\"); or #include #include io_printf(stdout, \"hello world\\n\"); #include void io_printf(struct IoConsole *io, const char *format, ...);","title":"io_printf"},{"location":"api/api-c-con/#io_getc32","text":"Waits for the user to enter and then returns a unicode code point. Currently only really works with an IoConsole that is stdin. To return characters encoded with the current locale, see io_mbgetc #include int io_getc32(struct IoConsole* io);","title":"io_getc32"},{"location":"api/api-c-con/#io_mbgetc","text":"io_mbgetc will get a character from stdin and encode it using the character encoding of the LC_CTYPE category of the current locale. \"C\" will use ASCII. UTF-8 and windows-1252 are also supported. #include void io_mbgetc(struct IoConsole* io, char* strout);","title":"io_mbgetc"},{"location":"api/api-c-con/#io_mbgets","text":"Gets a string from an IoConsole (which needs to be stdin). Returns when the user presses \"Enter\". Displays a cursor character and echos the inputted characters, at the current cursor position. Uses character encoding of LC_TYPE of current locale. #include char *io_mbgets(struct IoConsole* io, char *buffer );","title":"io_mbgets"},{"location":"api/api-c-con/#io_get_cursor","text":"Returns an integer of the current cursor position. The cursor is where the next io_putc is going to go. For windowed consoles, the cursor position ranges from [0, width*height-1], inclusive. #include int io_get_cursor(struct IoConsole* io);","title":"io_get_cursor"},{"location":"api/api-c-con/#io_set_colors","text":"For windowed consoles only. Sets a 24 bit RGB default color for the foreground and background. The prior default colors are changed (lost). For example, if you set the default colors when you created the window (see stdio ), the defaults will no longer be active. Use io_get_colors to save existing colors for later restoration using io_set_colors . A call to io_set_colors doesn't actually cause any on screen changes. Instead, these new default colors are used in future draw and text calls. A foreground and background color is set for each cell in the console window. The cell's colors are set to these default foreground/background colors when a call to io_setc , io_setreset , etc is made. #include void io_set_colors(struct IoConsole* io, unsigned long foreground, unsigned long background);","title":"io_set_colors"},{"location":"api/api-c-con/#io_get_colors","text":"For windowed consoles only. Gets the current default colors. #include void io_get_colors(struct IoConsole* io, unsigned long *foreground, unsigned long *background);","title":"io_get_colors"},{"location":"api/api-c-con/#io_cls","text":"For windowed consoles only. Clears the screen. That is, all character cells in the window are set to a space, their colors are reset to the current default colors (see io_set_colors ). #include void io_cls(struct IoConsoleWindow* iow);","title":"io_cls"},{"location":"api/api-c-con/#io_setc","text":"For windowed consoles only. Sets a window cell to a character. Sends a byte to an IoConsole and supports the current locale's character encoding. This function will \"stream\" using the current code page. In other words, if you io_setc ASCII, it will work as \"normal\". If the current locale is set to 1252, then you can send windows-1252 encoded characters. If the current locale is UTF-8, then you can stream UTF-8 (that is, call io_setc once for each byte of the multi-byte UTF-8 character). #include bool io_setc(struct IoConsoleWindow* iow, int location, unsigned char c);","title":"io_setc"},{"location":"api/api-c-con/#io_setc32","text":"For windowed consoles only. Sets a window cell to a unicode code point. The colors are set to the defaults (see io_set_colors ). #include void io_setc32(struct IoConsoleWindow* iow, int location, int c);","title":"io_setc32"},{"location":"api/api-c-con/#io_setreset","text":"For windowed consoles only. Sets or resets (clears) a chunky graphics \"pixel\". Each character cell can also be a 2x3 grid of graphic \"pixels\". In other words, the terminal window has pixel dimensions of width 2 x height 3. The color will be set to the defaults if the impacted cell is not a graphics cell. If it is an existing graphics cell, the colors don't change. See the stdio-canvas example. #include bool io_setreset(struct IoConsoleWindow* iow, int x, int y, bool isset);","title":"io_setreset"},{"location":"api/api-c-con/#io_point","text":"For windowed consoles only. Checks if a chunky graphics \"pixel\" is set or clear. See io_setreset . #include bool io_point(struct IoConsoleWindow* iow, int x, int y);","title":"io_point"},{"location":"api/api-c-con/#io_set_cursor","text":"Moves the cursor. See io_get_cursor . #include void io_set_cursor(struct IoConsoleWindow* iow, int loc);","title":"io_set_cursor"},{"location":"api/api-c-con/#io_begin_draw","text":"For windowed consoles only. This call (and its matching io_end_draw) are not required. But if you bracket any call sequence that draws to the terminal window with an io_begin_draw and io_end_draw , the updates will be batched into one update. io_begin_draw can be nested. This will increase performance and usually prevents the user from seeing partial updates. See the terminal-window io_canvas example. #include void io_begin_draw(struct IoConsole* io);","title":"io_begin_draw"},{"location":"api/api-c-con/#io_end_draw","text":"For windowed consoles only. See io_begin_draw . #include void io_end_draw(struct IoConsole* io);","title":"io_end_draw"},{"location":"api/api-c-d2d/","text":"2D Draw C API for Web Assembly This section describes twr-wasm's C D2D API, which allows your Web Assembly module to call many of the JavaScript Canvas APIs. There is also a C++ canvas wrapper class in the balls example. Examples Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze here Source for maze Overview Add a canvas tag to your HTML named twr_d2dcanvas like this example (you can use any width/height you like): To draw using the C API: - call d2d_start_draw_sequence() - call draw commands, like d2d_fillrect() - call d2d_end_draw_sequence() Commands are queued until flush'd, which will take the batch of queued draw cmds, and execute them. In the case of twrWasmModuleAsync, the batch of commands is sent over to the JavaScript main thread for execution. By batching the calls, performance is improved. Flush() waits for the commands to finish execution before returning. Flush() is called automatically by d2d_end_draw_sequence(). You pass an argument to d2d_start_draw_sequence() specifying how many instructions will trigger an automatic flush. You can make this larger for efficiency, or smaller if you want to see the render progress with more frequently. There is no limit on the size of the queue, except memory used in the wasm module. There is a flush() function that you can manually call, but it is not normally needed, unless you would like to ensure a sequence renders before d2d_end_draw_sequence() is called, or before the count passed d2d_start_draw_sequence() is met. If you are using twrWasmModuleAsync, or if you are re-rendering the entire frame for each animation update, you should ensure that all of your draws for a single complete frame are made without a call to flush() in the middle of the draw operations, as this may cause flashing. Functions These are the Canvas APIs currently available in C: struct d2d_draw_seq* d2d_start_draw_sequence(int flush_at_ins_count); void d2d_end_draw_sequence(struct d2d_draw_seq* ds); void d2d_flush(struct d2d_draw_seq* ds); int d2d_get_canvas_prop(const char* prop); void d2d_fillrect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_strokerect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_filltext(struct d2d_draw_seq* ds, const char* str, double x, double y); void d2d_fillcodepoint(struct d2d_draw_seq* ds, char c, double x, double y); void d2d_measuretext(struct d2d_draw_seq* ds, const char* str, struct d2d_text_metrics *tm); void d2d_save(struct d2d_draw_seq* ds); void d2d_restore(struct d2d_draw_seq* ds); void d2d_setlinewidth(struct d2d_draw_seq* ds, double width); void d2d_setfillstylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setstrokestylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setfillstyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setstrokestyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setfont(struct d2d_draw_seq* ds, const char* font); void d2d_createlineargradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double x1, double y1); void d2d_createradialgradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double radius0, double x1, double y1, double radius1); void d2d_addcolorstop(struct d2d_draw_seq* ds, long gradID, long position, const char* csscolor); void d2d_setfillstylegradient(struct d2d_draw_seq* ds, long gradID); void d2d_releaseid(struct d2d_draw_seq* ds, long id); void d2d_beginpath(struct d2d_draw_seq* ds); void d2d_fill(struct d2d_draw_seq* ds); void d2d_stroke(struct d2d_draw_seq* ds); void d2d_moveto(struct d2d_draw_seq* ds, double x, double y); void d2d_lineto(struct d2d_draw_seq* ds, double x, double y); void d2d_arc(struct d2d_draw_seq* ds, double x, double y, double radius, double start_angle, double end_angle, bool counterclockwise); void d2d_bezierto(struct d2d_draw_seq* ds, double cp1x, double cp1y, double cp2x, double cp2y, double x, double y); void d2d_imagedata(struct d2d_draw_seq* ds, long id, void* mem, unsigned long length, unsigned long width, unsigned long height); void d2d_putimagedata(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy); void d2d_putimagedatadirty(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy, unsigned long dirtyX, unsigned long dirtyY, unsigned long dirtyWidth, unsigned long dirtyHeight); d2d_measuretext() returns this structure: struct d2d_text_metrics { double actualBoundingBoxAscent; double actualBoundingBoxDescent; double actualBoundingBoxLeft; double actualBoundingBoxRight; double fontBoundingBoxAscent; double fontBoundingBoxDescent; double width; }; d2d_get_canvas_prop() returns a value of: export interface ICanvasProps { charWidth: number, charHeight: number, foreColor: number, backColor: number, widthInChars: number, heightInChars: number, canvasWidth:number, canvasHeight:number }","title":"C Draw 2D"},{"location":"api/api-c-d2d/#2d-draw-c-api-for-web-assembly","text":"This section describes twr-wasm's C D2D API, which allows your Web Assembly module to call many of the JavaScript Canvas APIs. There is also a C++ canvas wrapper class in the balls example.","title":"2D Draw C API for Web Assembly"},{"location":"api/api-c-d2d/#examples","text":"Name View Live Link Source Link Bouncing Balls (C++) View bouncing balls Source for balls Maze (Win32 C Port) View live maze here Source for maze","title":"Examples"},{"location":"api/api-c-d2d/#overview","text":"Add a canvas tag to your HTML named twr_d2dcanvas like this example (you can use any width/height you like): To draw using the C API: - call d2d_start_draw_sequence() - call draw commands, like d2d_fillrect() - call d2d_end_draw_sequence() Commands are queued until flush'd, which will take the batch of queued draw cmds, and execute them. In the case of twrWasmModuleAsync, the batch of commands is sent over to the JavaScript main thread for execution. By batching the calls, performance is improved. Flush() waits for the commands to finish execution before returning. Flush() is called automatically by d2d_end_draw_sequence(). You pass an argument to d2d_start_draw_sequence() specifying how many instructions will trigger an automatic flush. You can make this larger for efficiency, or smaller if you want to see the render progress with more frequently. There is no limit on the size of the queue, except memory used in the wasm module. There is a flush() function that you can manually call, but it is not normally needed, unless you would like to ensure a sequence renders before d2d_end_draw_sequence() is called, or before the count passed d2d_start_draw_sequence() is met. If you are using twrWasmModuleAsync, or if you are re-rendering the entire frame for each animation update, you should ensure that all of your draws for a single complete frame are made without a call to flush() in the middle of the draw operations, as this may cause flashing.","title":"Overview"},{"location":"api/api-c-d2d/#functions","text":"These are the Canvas APIs currently available in C: struct d2d_draw_seq* d2d_start_draw_sequence(int flush_at_ins_count); void d2d_end_draw_sequence(struct d2d_draw_seq* ds); void d2d_flush(struct d2d_draw_seq* ds); int d2d_get_canvas_prop(const char* prop); void d2d_fillrect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_strokerect(struct d2d_draw_seq* ds, double x, double y, double w, double h); void d2d_filltext(struct d2d_draw_seq* ds, const char* str, double x, double y); void d2d_fillcodepoint(struct d2d_draw_seq* ds, char c, double x, double y); void d2d_measuretext(struct d2d_draw_seq* ds, const char* str, struct d2d_text_metrics *tm); void d2d_save(struct d2d_draw_seq* ds); void d2d_restore(struct d2d_draw_seq* ds); void d2d_setlinewidth(struct d2d_draw_seq* ds, double width); void d2d_setfillstylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setstrokestylergba(struct d2d_draw_seq* ds, unsigned long color); void d2d_setfillstyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setstrokestyle(struct d2d_draw_seq* ds, const char* css_color); void d2d_setfont(struct d2d_draw_seq* ds, const char* font); void d2d_createlineargradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double x1, double y1); void d2d_createradialgradient(struct d2d_draw_seq* ds, long id, double x0, double y0, double radius0, double x1, double y1, double radius1); void d2d_addcolorstop(struct d2d_draw_seq* ds, long gradID, long position, const char* csscolor); void d2d_setfillstylegradient(struct d2d_draw_seq* ds, long gradID); void d2d_releaseid(struct d2d_draw_seq* ds, long id); void d2d_beginpath(struct d2d_draw_seq* ds); void d2d_fill(struct d2d_draw_seq* ds); void d2d_stroke(struct d2d_draw_seq* ds); void d2d_moveto(struct d2d_draw_seq* ds, double x, double y); void d2d_lineto(struct d2d_draw_seq* ds, double x, double y); void d2d_arc(struct d2d_draw_seq* ds, double x, double y, double radius, double start_angle, double end_angle, bool counterclockwise); void d2d_bezierto(struct d2d_draw_seq* ds, double cp1x, double cp1y, double cp2x, double cp2y, double x, double y); void d2d_imagedata(struct d2d_draw_seq* ds, long id, void* mem, unsigned long length, unsigned long width, unsigned long height); void d2d_putimagedata(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy); void d2d_putimagedatadirty(struct d2d_draw_seq* ds, long id, unsigned long dx, unsigned long dy, unsigned long dirtyX, unsigned long dirtyY, unsigned long dirtyWidth, unsigned long dirtyHeight); d2d_measuretext() returns this structure: struct d2d_text_metrics { double actualBoundingBoxAscent; double actualBoundingBoxDescent; double actualBoundingBoxLeft; double actualBoundingBoxRight; double fontBoundingBoxAscent; double fontBoundingBoxDescent; double width; }; d2d_get_canvas_prop() returns a value of: export interface ICanvasProps { charWidth: number, charHeight: number, foreColor: number, backColor: number, widthInChars: number, heightInChars: number, canvasWidth:number, canvasHeight:number }","title":"Functions"},{"location":"api/api-c-general/","text":"General C API for WASM Overview This sections describes the \"general\" twr-wasm functions available that don't fit neatly into another category (such as standard C library functions, Draw 2D functions, etc.) These functions often start with \"twr_\" and are generally found in this include file: \\twr-wasm\\include\\twr-crt.h bzero Set a block of memory to zeros. Calls memset(to, 0, count) . #include void bzero (void *to, size_t count); getc This is the standard c library function (see the the standard library docs available on the internet). Of note this function will return extended ASCII (128-255 inclusive). The extend ASCII are always encoded with Windows-1252 encoding. See twr_getc32 for a list of related functions. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. twr_atod Similar to stdlib atof . #include \"twr-crt.h\" double twr_atod(const char* str); twr_atou64 Convert a string to a 64 bit unsigned integer, stopping when the first non-valid character is encountered. If len is provided, it will be set to the number of characters read. Radix should be >=2 and <=36 -- for example, 10 is a normal base 10 number and 16 is hexadecimal. #include \"twr-crt.h\" int64_t twr_atou64(const char *str, int* len, int radix); twr_dtoa The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed #include \"twr-crt.h\" void twr_dtoa(char* buffer, int sizeInBytes, double value, int max_precision); twr_cache_malloc/free These functions keep allocated memory in a cache for much faster re-access than the standard malloc/free. #include \"twr-crt.h\" void *twr_cache_malloc(twr_size_t size); void twr_cache_free(void* mem); twr_code_page_to_utf32_streamed Return a unicode code point (aka utf-32 value) when passed a byte stream that represents an encoded character using the current local's LC_CTYPE code page. A zero is returned if the byte stream has not yet completed a decode. For example: int cp setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region // turn a UTF-8 Euro into a UTF-32 value cp==twr_code_page_to_utf32_streamed(0xE2); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0x82); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0xAC); assert (cp==0x000020AC); // Euro Code points #include int twr_code_page_to_utf32_streamed(unsigned char byte) twr_conlog twr_conlog prints debug messages to the browser console from your C code. #include \"twr-crt.h\" void twr_conlog(char* format, ...); Each call to twr_conlog() will generate a single call to console.log() in JavaScript to ensure that you see debug prints. This call is identical to printf, except that it adds a newline. The current implementation does not wait for the debug string to output to the console before returning from twr_conlog, when using twrWasmModuleAsync. In this case, it can take a small bit of time for the string to make its way across the Worker Thread boundary. This is normally not a problem and results in faster performance. But if your code crashes soon after the debug print, the print might not appear. If you think this is an issue, you can call twr_sleep(1) after your twr_conlog call. This will force a blocking wait for the print to print. Prior to 1.0, this function was called twr_dbg_printf , and operated slightly differently. twr_epoch_timems Returns the number of milliseconds since the start of the epoch. #include \"twr-wasm.h\" uint64_t twr_epoch_timems(); twr_getc32 Gets a 32 bit unicode code point character from stdin . Unlike the standard C library function getchar , twr_getc32 does not buffer a line (that is, twr_getc32 will return a character before the user presses Enter). twr_getc32 is implemented as: int twr_getc32() { return io_getc32(twr_get_stdio_con()); } Note that stdlib getchar and ungetc are not currently implemented. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. Also see: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) #include \"twr-crt.h\" int twr_getc32(); twr_get_navlang Returns the BCP 47 language tag as found in javacript navigator.language . If len is not null, it will be filled in with the string length of the language tag. #include \"twr-crt.h\" const char* twr_get_navlang(int *len); twr_get_current_locale extern inline locale_t twr_get_current_locale(void); twr_get_current_locale will return the locale that has been set by setlocale . It can be used to pass to a function that takes a locale_t. twr_localize_numeric_string Functions like twr_dtoa do not localize the decimal point. To get a localized decimal point, you can use printf , or alternately twr_localize_numeric_string to post process a string. For example: char b[10]; strcpy(b, \"1.23\"); twr_localize_numeric_string(b, twr_get_current_locale()); // if locale was set to french, then b is now 1,23 #include void twr_localize_numeric_string(char* str, locale_t locale); twr_mem_debug_stats Print memory map and malloc stats to stderr or stdout. (note FILE * is the same as struct IoConsole*) #include void twr_mem_debug_stats(struct IoConsole* outcon); twr_mbgets Gets a string from stdin . The string will be in the current locale's character encoding -- ASCII for \"C\", and either UTF-8 or windows-1252 for \"\". See localization . #include \"twr-crt.h\" char* twr_mbgets(char* buffer); Internally this function uses the stdio IoConsole -- see the IoConsole section for more advanced input/output. This function will encode characters as specified by the LC_CTYPE category of the current locale. ASCII is used for \"C\", and UTF-8 and Windows-1252 are also supported (see localization ) Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. twr_mbslen_l Returns the number of characters in a string using the character encoding of the passed locale (ASCII for \"C\", UTF-8, or windows-1252 for \"\"). You can use twr_get_current_locale to find the current locale. #include size_t twr_mbslen_l(const char *str, locale_t locale); twr_sleep twr_sleep is a traditional blocking sleep function. This function is blocking, and you must use twrWasmModuleAsync. #include \"twr-wasm.h\" void twr_sleep(int ms); twr_tofixed This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_tofixed(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed twr_toexponential This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_toexponential(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed twr_strhorizflip Mirror image the passed in string. #include \"twr-crt.h\" void twr_strhorizflip(char * buffer, int n); twr_utf8_char_len Returns the number of bytes in a UTF-8 character (passed as a string pointer). UTF-8 characters can be 1 to 4 bytes in length. #include int twr_utf8_char_len(const char *str); twr_utf32_to_code_page Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page. The buffer is 0 terminated. Also see c32rtomb and c16rtomb . For example: char strbuf[6]; // max size of utf-8 is 4+terminating zero. Max size of ASCII or windows 1252 is 1 + terminating zero setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region twr_utf32_to_code_page(strbuf, 0x000020AC); // encode a Euro code point printf(\"%s\", strbuf); assert ( strcmp(strbuf,\"\\xE2\\x82\\xAC\")==0 ); // utf-8 encoding of euro assert ( strcmp(strbuf,\"\u20ac\")==0 ); // clang string literals default to utf-8 encoding include void twr_utf32_to_code_page(char* out, int utf32) twr_vprintf Performs a printf by calling the callback with cbdata for each character. #include \"twr-crt.h\" void twr_vprintf(twr_cbprintf_callback out, void* cbdata, const char *format, va_list* args); floating math helpers int twr_isnan(double v); int twr_isinf(double v); double twr_nanval(); double twr_infval();","title":"C General"},{"location":"api/api-c-general/#general-c-api-for-wasm","text":"","title":"General C API for WASM"},{"location":"api/api-c-general/#overview","text":"This sections describes the \"general\" twr-wasm functions available that don't fit neatly into another category (such as standard C library functions, Draw 2D functions, etc.) These functions often start with \"twr_\" and are generally found in this include file: \\twr-wasm\\include\\twr-crt.h","title":"Overview"},{"location":"api/api-c-general/#bzero","text":"Set a block of memory to zeros. Calls memset(to, 0, count) . #include void bzero (void *to, size_t count);","title":"bzero"},{"location":"api/api-c-general/#getc","text":"This is the standard c library function (see the the standard library docs available on the internet). Of note this function will return extended ASCII (128-255 inclusive). The extend ASCII are always encoded with Windows-1252 encoding. See twr_getc32 for a list of related functions. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input.","title":"getc"},{"location":"api/api-c-general/#twr_atod","text":"Similar to stdlib atof . #include \"twr-crt.h\" double twr_atod(const char* str);","title":"twr_atod"},{"location":"api/api-c-general/#twr_atou64","text":"Convert a string to a 64 bit unsigned integer, stopping when the first non-valid character is encountered. If len is provided, it will be set to the number of characters read. Radix should be >=2 and <=36 -- for example, 10 is a normal base 10 number and 16 is hexadecimal. #include \"twr-crt.h\" int64_t twr_atou64(const char *str, int* len, int radix);","title":"twr_atou64"},{"location":"api/api-c-general/#twr_dtoa","text":"The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed #include \"twr-crt.h\" void twr_dtoa(char* buffer, int sizeInBytes, double value, int max_precision);","title":"twr_dtoa"},{"location":"api/api-c-general/#twr_cache_mallocfree","text":"These functions keep allocated memory in a cache for much faster re-access than the standard malloc/free. #include \"twr-crt.h\" void *twr_cache_malloc(twr_size_t size); void twr_cache_free(void* mem);","title":"twr_cache_malloc/free"},{"location":"api/api-c-general/#twr_code_page_to_utf32_streamed","text":"Return a unicode code point (aka utf-32 value) when passed a byte stream that represents an encoded character using the current local's LC_CTYPE code page. A zero is returned if the byte stream has not yet completed a decode. For example: int cp setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region // turn a UTF-8 Euro into a UTF-32 value cp==twr_code_page_to_utf32_streamed(0xE2); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0x82); assert (cp==0); cp=twr_code_page_to_utf32_streamed(0xAC); assert (cp==0x000020AC); // Euro Code points #include int twr_code_page_to_utf32_streamed(unsigned char byte)","title":"twr_code_page_to_utf32_streamed"},{"location":"api/api-c-general/#twr_conlog","text":"twr_conlog prints debug messages to the browser console from your C code. #include \"twr-crt.h\" void twr_conlog(char* format, ...); Each call to twr_conlog() will generate a single call to console.log() in JavaScript to ensure that you see debug prints. This call is identical to printf, except that it adds a newline. The current implementation does not wait for the debug string to output to the console before returning from twr_conlog, when using twrWasmModuleAsync. In this case, it can take a small bit of time for the string to make its way across the Worker Thread boundary. This is normally not a problem and results in faster performance. But if your code crashes soon after the debug print, the print might not appear. If you think this is an issue, you can call twr_sleep(1) after your twr_conlog call. This will force a blocking wait for the print to print. Prior to 1.0, this function was called twr_dbg_printf , and operated slightly differently.","title":"twr_conlog"},{"location":"api/api-c-general/#twr_epoch_timems","text":"Returns the number of milliseconds since the start of the epoch. #include \"twr-wasm.h\" uint64_t twr_epoch_timems();","title":"twr_epoch_timems"},{"location":"api/api-c-general/#twr_getc32","text":"Gets a 32 bit unicode code point character from stdin . Unlike the standard C library function getchar , twr_getc32 does not buffer a line (that is, twr_getc32 will return a character before the user presses Enter). twr_getc32 is implemented as: int twr_getc32() { return io_getc32(twr_get_stdio_con()); } Note that stdlib getchar and ungetc are not currently implemented. Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input. Also see: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) #include \"twr-crt.h\" int twr_getc32();","title":"twr_getc32"},{"location":"api/api-c-general/#twr_get_navlang","text":"Returns the BCP 47 language tag as found in javacript navigator.language . If len is not null, it will be filled in with the string length of the language tag. #include \"twr-crt.h\" const char* twr_get_navlang(int *len);","title":"twr_get_navlang"},{"location":"api/api-c-general/#twr_get_current_locale","text":"extern inline locale_t twr_get_current_locale(void); twr_get_current_locale will return the locale that has been set by setlocale . It can be used to pass to a function that takes a locale_t.","title":"twr_get_current_locale"},{"location":"api/api-c-general/#twr_localize_numeric_string","text":"Functions like twr_dtoa do not localize the decimal point. To get a localized decimal point, you can use printf , or alternately twr_localize_numeric_string to post process a string. For example: char b[10]; strcpy(b, \"1.23\"); twr_localize_numeric_string(b, twr_get_current_locale()); // if locale was set to french, then b is now 1,23 #include void twr_localize_numeric_string(char* str, locale_t locale);","title":"twr_localize_numeric_string"},{"location":"api/api-c-general/#twr_mem_debug_stats","text":"Print memory map and malloc stats to stderr or stdout. (note FILE * is the same as struct IoConsole*) #include void twr_mem_debug_stats(struct IoConsole* outcon);","title":"twr_mem_debug_stats"},{"location":"api/api-c-general/#twr_mbgets","text":"Gets a string from stdin . The string will be in the current locale's character encoding -- ASCII for \"C\", and either UTF-8 or windows-1252 for \"\". See localization . #include \"twr-crt.h\" char* twr_mbgets(char* buffer); Internally this function uses the stdio IoConsole -- see the IoConsole section for more advanced input/output. This function will encode characters as specified by the LC_CTYPE category of the current locale. ASCII is used for \"C\", and UTF-8 and Windows-1252 are also supported (see localization ) Note that C character input is blocking and you must use twrWasmModuleAsync -- see stdin for details on how to enable blocking character input.","title":"twr_mbgets"},{"location":"api/api-c-general/#twr_mbslen_l","text":"Returns the number of characters in a string using the character encoding of the passed locale (ASCII for \"C\", UTF-8, or windows-1252 for \"\"). You can use twr_get_current_locale to find the current locale. #include size_t twr_mbslen_l(const char *str, locale_t locale);","title":"twr_mbslen_l"},{"location":"api/api-c-general/#twr_sleep","text":"twr_sleep is a traditional blocking sleep function. This function is blocking, and you must use twrWasmModuleAsync. #include \"twr-wasm.h\" void twr_sleep(int ms);","title":"twr_sleep"},{"location":"api/api-c-general/#twr_tofixed","text":"This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_tofixed(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed","title":"twr_tofixed"},{"location":"api/api-c-general/#twr_toexponential","text":"This function is identical to its JavaScript version. #include \"twr-wasm.h\" void twr_toexponential(char* buffer, int buffer_size, double value, int dec_digits); The functions to convert double to text are snprintf , fcvt_s , twr_dtoa , twr_toexponential , and twr_tofixed","title":"twr_toexponential"},{"location":"api/api-c-general/#twr_strhorizflip","text":"Mirror image the passed in string. #include \"twr-crt.h\" void twr_strhorizflip(char * buffer, int n);","title":"twr_strhorizflip"},{"location":"api/api-c-general/#twr_utf8_char_len","text":"Returns the number of bytes in a UTF-8 character (passed as a string pointer). UTF-8 characters can be 1 to 4 bytes in length. #include int twr_utf8_char_len(const char *str);","title":"twr_utf8_char_len"},{"location":"api/api-c-general/#twr_utf32_to_code_page","text":"Takes a utf32 value (aka unicode code point value), and fills in the passed character array buffer with the character encoding of the utf32 value, using the current locale's LC_CTYPE code page. The buffer is 0 terminated. Also see c32rtomb and c16rtomb . For example: char strbuf[6]; // max size of utf-8 is 4+terminating zero. Max size of ASCII or windows 1252 is 1 + terminating zero setlocale(LC_ALL, \"\"); // set to default locale, which will be UTF-8 encoding with local language/region twr_utf32_to_code_page(strbuf, 0x000020AC); // encode a Euro code point printf(\"%s\", strbuf); assert ( strcmp(strbuf,\"\\xE2\\x82\\xAC\")==0 ); // utf-8 encoding of euro assert ( strcmp(strbuf,\"\u20ac\")==0 ); // clang string literals default to utf-8 encoding include void twr_utf32_to_code_page(char* out, int utf32)","title":"twr_utf32_to_code_page"},{"location":"api/api-c-general/#twr_vprintf","text":"Performs a printf by calling the callback with cbdata for each character. #include \"twr-crt.h\" void twr_vprintf(twr_cbprintf_callback out, void* cbdata, const char *format, va_list* args);","title":"twr_vprintf"},{"location":"api/api-c-general/#floating-math-helpers","text":"int twr_isnan(double v); int twr_isinf(double v); double twr_nanval(); double twr_infval();","title":"floating math helpers"},{"location":"api/api-c-stdlib/","text":"Standard C library for Web Assembly This section describes twr-wasm's support for the Standard C Library. twr-wasm includes its own implementation of the standard C library optimized for Web Assembly and wasm running in a web browser. This is a core feature of twr-wasm. For documentation of these functions, see the many standard C library documentation web sites. The following subset of the standard C library is available. Also see twr-wasm/include folder for include files. stdio.h * fprintf will only work with these -- stderr, stdin, stdout */ /* these return 'struct IoConsole *' which is same as 'FILE *' */ #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) int snprintf(char *buffer, size_t bufsz, const char *format, ... ); int sprintf( char *buffer, const char *format, ... ); int vsnprintf(char *buffer, size_t bufsz, const char *format, va_list vlist); int vasprintf(char **strp, const char* format, va_list vlist ); int printf(const char* format, ...); int vprintf(const char* format, va_list vlist ); int puts(const char *str); int putchar(int c); typedef struct IoConsole FILE; int vfprintf(FILE *stream, const char *format, va_list vlist); int fprintf(FILE *stream, const char* format, ...); size_t fwrite(const void* buffer, size_t size, size_t count, FILE* stream); int ferror(FILE *stream); int feof(FILE *stream); int fflush(FILE *stream); int is_terminal(FILE *stream); int fputc(int ch, FILE* stream); int putc(int ch, FILE* stream); int fgetc(FILE *stream ); int getc(FILE *stream); stdlib.h void *malloc(size_t size); void free(void *mem); size_t avail(void); void *realloc( void *ptr, size_t new_size ); void* calloc( size_t num, size_t size ); void *aligned_alloc( size_t alignment, size_t size ); int rand(void); void srand(int seed); #define __min(a,b) (((a) < (b)) ? (a) : (b)) #define __max(a,b) (((a) > (b)) ? (a) : (b)) int _fcvt_s( char* buffer, size_t sizeInBytes, double value, int fracpart_numdigits, int *dec, int *sign ); double atof(const char* str); int atoi(const char *str); long atol( const char *str ); long long atoll( const char *str ); long strtol(const char *str, char **str_end, int base); long long strtoll(const char *str, char **str_end, int base); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull(const char *str, char **str_end, int base); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); unsigned long strtoul(const char *str, char ** str_end, int base); float strtof(const char *str, char ** str_end); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod(const char *str, char **str_end); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold(const char *str, char **str_end); long double strtold_l(const char *str, char **str_end, locale_t locale); int _itoa_s(int64_t value, char * buffer, size_t size, int radix); div_t div( int x, int y ); ldiv_t ldiv( long x, long y ); lldiv_t lldiv( long long x, long long y ); _Noreturn void abort(void); int atexit(void (*func)(void)); Note that _fcvt_s as currently enabled has these limitations: - fractional digits <=100 - values must be less than 1e+21 - values negative exponents must be smaller than 1e-99 There is a full featured version of _fcvt_s in the source code, but is not currently enabled, since the version enabled is smaller and works in most use cases. assert.h void assert(int expression); math.h int abs(int n); double acos(double arg); double asin(double arg); double atan(double arg); double ceil(double arg); double cos(double arg); double exp(double arg); double fabs(double arg); double floor(double arg); double fmod(double x, double y); double log(double arg); double pow(double base, double exp); double sin(double arg); double sqrt(double arg); double tan(double arg); double trunc(double arg); stdarg.h #define va_start(v,l) __builtin_va_start(v,l) #define va_end(v) __builtin_va_end(v) #define va_arg(v,l) __builtin_va_arg(v,l) #define va_copy(d,s) __builtin_va_copy(d,s) typedef __builtin_va_list va_list; ctype.h int isascii(int); int toascii(int); int isalnum(int c); int isalpha(int c); int isblank(int); int iscntrl(int); int isdigit(int c); int isgraph(int c); int islower(int); int isprint(int); int ispunct(int); int isspace(int c); int isupper(int); int isxdigit(int); int tolower(int c); int toupper(int c); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); _stdtypes.h // don't include directly -- included by various .h files typedef unsigned long size_t; #define MAX_SIZE_T 2147483647 #ifdef __cplusplus #define NULL __null #else #define NULL ((void*)0) #endif typedef struct __locale_t_struct * locale_t; stddef.h #define offsetof(TYPE, MEMBER) __builtin_offsetof (TYPE, MEMBER) typedef __PTRDIFF_TYPE__ ptrdiff_t; typedef double max_align_t; string.h size_t strlen(const char * str); char *strdup(const char * source); char *strcpy(char *dest, const char *source); int strcat_s(char *dest, size_t destsz, const char *src); char* strcat(char *dest, const char *src); char *strncpy(char *dest, const char *source, size_t count); int strcmp(const char* string1, const char* string2); int strncmp(const char* lhs, const char* rhs, size_t count); int stricmp(const char* string1, const char* string2); int strnicmp(const char* string1, const char* string2, size_t count); int strcoll(const char* lhs, const char* rhs); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); char *strchr(const char *str, int ch); void *memchr(const void *ptr, int ch, size_t count); char *strstr(const char *haystack, const char *needle); char * strerror(int errnum ); char * _strerror(const char *strErrMsg); void *memmove(void *dest, const void *src, size_t n); int memcmp( const void* lhs, const void* rhs, size_t count ); void bzero (void *to, size_t count); // implemented in memcpy.wat void *memcpy(void *dest, const void * src, size_t n); void *memset(void *mem, int c, size_t n); time.h typedef unsigned long time_t; unsigned long time(unsigned long *time); size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale); struct tm *localtime(const time_t *timer); int gettimeofday(struct timeval *tv, void* notused); #define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) #define timercmp(tvp,uvp,cmp) \\ ((tvp)->tv_sec cmp (uvp)->tv_sec || \\ ((tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)) #define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0 locale.h #define LC_GLOBAL_LOCALE twr_get_current_locale() char* setlocale(int category, const char* locale); struct lconv *localeconv(void); locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); extern inline locale_t twr_get_current_locale(void); errno.h typedef int errno_t; extern int * _errno(void); #define errno (*_errno()) errno_t _set_errno(int _Value); errno_t _get_errno(int *_Value); Other include files available float.h limits.h stdbool.h stdint.h","title":"C Standard C Library"},{"location":"api/api-c-stdlib/#standard-c-library-for-web-assembly","text":"This section describes twr-wasm's support for the Standard C Library. twr-wasm includes its own implementation of the standard C library optimized for Web Assembly and wasm running in a web browser. This is a core feature of twr-wasm. For documentation of these functions, see the many standard C library documentation web sites. The following subset of the standard C library is available. Also see twr-wasm/include folder for include files.","title":"Standard C library for Web Assembly"},{"location":"api/api-c-stdlib/#stdioh","text":"* fprintf will only work with these -- stderr, stdin, stdout */ /* these return 'struct IoConsole *' which is same as 'FILE *' */ #define stderr (FILE *)(twr_get_stderr_con()) #define stdin (FILE *)(twr_get_stdio_con()) #define stdout (FILE *)(twr_get_stdio_con()) int snprintf(char *buffer, size_t bufsz, const char *format, ... ); int sprintf( char *buffer, const char *format, ... ); int vsnprintf(char *buffer, size_t bufsz, const char *format, va_list vlist); int vasprintf(char **strp, const char* format, va_list vlist ); int printf(const char* format, ...); int vprintf(const char* format, va_list vlist ); int puts(const char *str); int putchar(int c); typedef struct IoConsole FILE; int vfprintf(FILE *stream, const char *format, va_list vlist); int fprintf(FILE *stream, const char* format, ...); size_t fwrite(const void* buffer, size_t size, size_t count, FILE* stream); int ferror(FILE *stream); int feof(FILE *stream); int fflush(FILE *stream); int is_terminal(FILE *stream); int fputc(int ch, FILE* stream); int putc(int ch, FILE* stream); int fgetc(FILE *stream ); int getc(FILE *stream);","title":"stdio.h"},{"location":"api/api-c-stdlib/#stdlibh","text":"void *malloc(size_t size); void free(void *mem); size_t avail(void); void *realloc( void *ptr, size_t new_size ); void* calloc( size_t num, size_t size ); void *aligned_alloc( size_t alignment, size_t size ); int rand(void); void srand(int seed); #define __min(a,b) (((a) < (b)) ? (a) : (b)) #define __max(a,b) (((a) > (b)) ? (a) : (b)) int _fcvt_s( char* buffer, size_t sizeInBytes, double value, int fracpart_numdigits, int *dec, int *sign ); double atof(const char* str); int atoi(const char *str); long atol( const char *str ); long long atoll( const char *str ); long strtol(const char *str, char **str_end, int base); long long strtoll(const char *str, char **str_end, int base); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull(const char *str, char **str_end, int base); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); unsigned long strtoul(const char *str, char ** str_end, int base); float strtof(const char *str, char ** str_end); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod(const char *str, char **str_end); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold(const char *str, char **str_end); long double strtold_l(const char *str, char **str_end, locale_t locale); int _itoa_s(int64_t value, char * buffer, size_t size, int radix); div_t div( int x, int y ); ldiv_t ldiv( long x, long y ); lldiv_t lldiv( long long x, long long y ); _Noreturn void abort(void); int atexit(void (*func)(void)); Note that _fcvt_s as currently enabled has these limitations: - fractional digits <=100 - values must be less than 1e+21 - values negative exponents must be smaller than 1e-99 There is a full featured version of _fcvt_s in the source code, but is not currently enabled, since the version enabled is smaller and works in most use cases.","title":"stdlib.h"},{"location":"api/api-c-stdlib/#asserth","text":"void assert(int expression);","title":"assert.h"},{"location":"api/api-c-stdlib/#mathh","text":"int abs(int n); double acos(double arg); double asin(double arg); double atan(double arg); double ceil(double arg); double cos(double arg); double exp(double arg); double fabs(double arg); double floor(double arg); double fmod(double x, double y); double log(double arg); double pow(double base, double exp); double sin(double arg); double sqrt(double arg); double tan(double arg); double trunc(double arg);","title":"math.h"},{"location":"api/api-c-stdlib/#stdargh","text":"#define va_start(v,l) __builtin_va_start(v,l) #define va_end(v) __builtin_va_end(v) #define va_arg(v,l) __builtin_va_arg(v,l) #define va_copy(d,s) __builtin_va_copy(d,s) typedef __builtin_va_list va_list;","title":"stdarg.h"},{"location":"api/api-c-stdlib/#ctypeh","text":"int isascii(int); int toascii(int); int isalnum(int c); int isalpha(int c); int isblank(int); int iscntrl(int); int isdigit(int c); int isgraph(int c); int islower(int); int isprint(int); int ispunct(int); int isspace(int c); int isupper(int); int isxdigit(int); int tolower(int c); int toupper(int c); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc);","title":"ctype.h"},{"location":"api/api-c-stdlib/#_stdtypesh","text":"// don't include directly -- included by various .h files typedef unsigned long size_t; #define MAX_SIZE_T 2147483647 #ifdef __cplusplus #define NULL __null #else #define NULL ((void*)0) #endif typedef struct __locale_t_struct * locale_t;","title":"_stdtypes.h"},{"location":"api/api-c-stdlib/#stddefh","text":"#define offsetof(TYPE, MEMBER) __builtin_offsetof (TYPE, MEMBER) typedef __PTRDIFF_TYPE__ ptrdiff_t; typedef double max_align_t;","title":"stddef.h"},{"location":"api/api-c-stdlib/#stringh","text":"size_t strlen(const char * str); char *strdup(const char * source); char *strcpy(char *dest, const char *source); int strcat_s(char *dest, size_t destsz, const char *src); char* strcat(char *dest, const char *src); char *strncpy(char *dest, const char *source, size_t count); int strcmp(const char* string1, const char* string2); int strncmp(const char* lhs, const char* rhs, size_t count); int stricmp(const char* string1, const char* string2); int strnicmp(const char* string1, const char* string2, size_t count); int strcoll(const char* lhs, const char* rhs); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); char *strchr(const char *str, int ch); void *memchr(const void *ptr, int ch, size_t count); char *strstr(const char *haystack, const char *needle); char * strerror(int errnum ); char * _strerror(const char *strErrMsg); void *memmove(void *dest, const void *src, size_t n); int memcmp( const void* lhs, const void* rhs, size_t count ); void bzero (void *to, size_t count); // implemented in memcpy.wat void *memcpy(void *dest, const void * src, size_t n); void *memset(void *mem, int c, size_t n);","title":"string.h"},{"location":"api/api-c-stdlib/#timeh","text":"typedef unsigned long time_t; unsigned long time(unsigned long *time); size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale); struct tm *localtime(const time_t *timer); int gettimeofday(struct timeval *tv, void* notused); #define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) #define timercmp(tvp,uvp,cmp) \\ ((tvp)->tv_sec cmp (uvp)->tv_sec || \\ ((tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)) #define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0","title":"time.h"},{"location":"api/api-c-stdlib/#localeh","text":"#define LC_GLOBAL_LOCALE twr_get_current_locale() char* setlocale(int category, const char* locale); struct lconv *localeconv(void); locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); extern inline locale_t twr_get_current_locale(void);","title":"locale.h"},{"location":"api/api-c-stdlib/#errnoh","text":"typedef int errno_t; extern int * _errno(void); #define errno (*_errno()) errno_t _set_errno(int _Value); errno_t _get_errno(int *_Value);","title":"errno.h"},{"location":"api/api-c-stdlib/#other-include-files-available","text":"float.h limits.h stdbool.h stdint.h","title":"Other include files available"},{"location":"api/api-libc%2B%2B/","text":"libc++ for Web Assembly This section describes twr-wasm's support for using the standard c++ library libc++ with Web Assembly. twr-wasm includes libc++ built for Web Assembly and included in the twr-wasm/lib-c folder. For C++ the use of libc++ is optional. That is you can build twr-wasm projects in C++ with or without libc++. See the examples tests-libcxx and tests-user for examples of using libc++. See the balls example for how to create a C++ Web Assembly program without the standard C++ library. The primary advantage to this approach is a bit smaller code size. You don't need to staticly link libc++. Some of the key options twr-wasm's libc++ for Web Assembly was built with are these: DLIBCXX_ENABLE_LOCALIZATION=ON DLIBCXX_ENABLE_UNICODE=ON DLIBCXX_ENABLE_RTTI=ON DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON DCMAKE_BUILD_TYPE=Release DCMAKE_CXX_STANDARD=20 DLIBCXX_ENABLE_EXCEPTIONS=OFF DLIBCXX_ENABLE_THREADS=OFF DLIBCXX_ENABLE_SHARED=OFF DLIBCXX_ENABLE_WIDE_CHARACTERS=OFF DLIBCXX_ENABLE_FILESYSTEM=OFF DLIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF DLIBCXX_ENABLE_MONOTONIC_CLOCK=OFF DLIBCXX_ENABLE_RANDOM_DEVICE=OFF","title":"C++ with libc++"},{"location":"api/api-libc%2B%2B/#libc-for-web-assembly","text":"This section describes twr-wasm's support for using the standard c++ library libc++ with Web Assembly. twr-wasm includes libc++ built for Web Assembly and included in the twr-wasm/lib-c folder. For C++ the use of libc++ is optional. That is you can build twr-wasm projects in C++ with or without libc++. See the examples tests-libcxx and tests-user for examples of using libc++. See the balls example for how to create a C++ Web Assembly program without the standard C++ library. The primary advantage to this approach is a bit smaller code size. You don't need to staticly link libc++. Some of the key options twr-wasm's libc++ for Web Assembly was built with are these: DLIBCXX_ENABLE_LOCALIZATION=ON DLIBCXX_ENABLE_UNICODE=ON DLIBCXX_ENABLE_RTTI=ON DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON DCMAKE_BUILD_TYPE=Release DCMAKE_CXX_STANDARD=20 DLIBCXX_ENABLE_EXCEPTIONS=OFF DLIBCXX_ENABLE_THREADS=OFF DLIBCXX_ENABLE_SHARED=OFF DLIBCXX_ENABLE_WIDE_CHARACTERS=OFF DLIBCXX_ENABLE_FILESYSTEM=OFF DLIBCXX_ENABLE_TIME_ZONE_DATABASE=OFF DLIBCXX_ENABLE_MONOTONIC_CLOCK=OFF DLIBCXX_ENABLE_RANDOM_DEVICE=OFF","title":"libc++ for Web Assembly"},{"location":"api/api-localization/","text":"Locale Support for Web Assembly This section explains twr-wasm's Web Assembly localization support. Character encodings twr-wasm locales supports ASCII, UTF-8 or windows-1252 encoding. UTF-16/32 are not supported as a locale setting, but functions are provided to convert utf-32 (unicode code points) to and from ASCII, UTF-8, and windows-1252 \"code pages\" (there are other miscellaneous utf-32 based functions as well.) UTF-8 uses between one to four bytes to represent any unicode character, with ASCII compatibility in the first 128 bytes. It is also the standard for the web, and the default for clang. But because it uses a variable number of bytes per character it can make string manipulation in C a bit harder than ASCII. Windows-1252 is the default on most Windows computers in many countries - particularly the Americas and western Europe. It is an extension of ASCII that uses a single byte per character. This makes it easier than UTF-8 from a programmers perspective, but it doesn't represent as many characters. It is provided to make it easier to port legacy C code, windows code, as well as a simpler alternative to UTF-8. Although the locale settings don't support utf-32 directly, you can use int arrays (instead of byte arrays) to hold utf-32 strings, and then convert them to/from utf-8 with the help of the provided two functions for this purpose. Locales \"C\" \"C\" is the default locale, as usual. When \"C\" is selected, the functions operate as usual. One subtly is that console i/o functions (such as printf ) will generally function as expected with UTF-8, since the div and window consoles correctly handle UTF-8 character encoding. This is normal on some OSs, such as linux, but not the default on Windows (which often defaults to windows-1252 for backward compatibility). isgraph style functions will only recognize ASCII characters, as is normal. Functions such as strcmp operate on the byte sequence, which will typically results in UTF-8 codes being compared lexically. strcoll will use lexical ordering. \"POSIX\" \"POSIX\" is the same as \"C\" \"\" \"\" is the locale to specify the users default setting (this selects the setting used by the browser). This will also enable UTF-8 in functions such as strcoll . For example, if your browser is set to \"en-US\" as its default locale, setlocale(LC_ALL, \"\") will return en-US.UTF-8 . isgraph style functions will still only recognize ASCII characters (since UTF-8 doesn't encode any single bytes greater than 127). strcoll uses locale specific ordering, and printf will use locale specific decimal points. strcmp still compares two strings lexicographically (byte-by-byte) without considering locale-specific rules, per the spec. \".UTF-8\" \".UTF-8\" is the same as \"\" with twr-wasm. \".1252\" \".1252\" will select the current default locale, but use windows-1252 character encoding (instead of UTF-8). Windows-1252 is a super set of ISO-8859-1 and is the most commonly used encoding for many european languages when unicode is not used. This mode is primarily for legacy software, backwards compatibly, and windows compatibility. 1252 String Literals These days text editors generally default to UTF-8. In order to use windows-1252 source code and/or string literals, such as const char * str=\"\u20ac100\" you may need to: Configure your text editor to save in Windows-1252/ISO-8859-1 format (instead of UTF-8) use compiler flags like --finput-charset and -fexec-charset By default, the Microsoft Visual Studio C compiler (MSVC) does not treat string literals as UTF-8. Instead, it treats them as being encoded in the current code page of the system, which is typically Windows-1252 on western european language Windows systems. twr-wasm is designed to work with clang, which does default to utf-8, so if you are compiling code written for MSVC, and you use extend character sets (non ASCII), you may need to adjust your compiler settings with the flags mentioned above. Others Setting arbitrary locales, such as \"fr-FR\" when the browser is defaulted to another locale, is not supported. Select the default locale To select the user's browser's default locale using the C language, and enable consistent utf-8 support, use a call like this: setlocale(LC_ALL, \"\") libc++ If you are using C++, libc++ locale functions work as expected. C functions The normal standard C library locale support is available, along with some POSIX extensions. In addition, some locale useful twr-wasm specific functions are documented in C API , such as twr_get_current_locale , twr_mbgets , twr_getc32 , twr_utf8_char_len , twr_mbslen_l , twr_utf32_to_code_page , twr_code_page_to_utf32_streamed , twr_get_navlang , twr_localize_numeric_string . Note that io_getc32() , getc(stdin) , fgetc(stdin) do not look at the current locale. iogetc32 returns a 32 bit unicode code point, and getc / fgetc return extended ASCII. For a locale aware character input, use io_mbgetc() or twr_mbgets() . Both use the locale category LC_CTYPE. See C API . Note that when the locale is not set (or whenever the \"C\" locale is set) functions that get character(s) from stdin that are locale aware, like twr_mbgets() , behave different than functions that output characters to stdout (like puts , io_putstr , io_putc , putchar ). Characters to stdout in \"C\" locale will handle UTF-8 characters. For stdin, \"C\" locale uses ASCII. For consistent UTF-8 (or windows-1252) behavior, set the locale as discussed above ( use setlocale ) The primary standard C library locale functions are: char* setlocale(int category, const char* locale); struct lconv *localeconv(void); As well as the standard library functions above, appropriate functions take into account the current locale (printf, strcoll, etc). Note that setlocale returns a string using BCP 47 format (similar to a web browser). Locale strings look like \"en-US.UTF-8\", instead of \"en_US.UTF-8\". A dash, not an underscore, is used as a separator. POSIX functions These are the extended POSIX style functions provided that are related to locale: locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold_l(const char *str, char **str_end, locale_t locale); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale);","title":"C Localization"},{"location":"api/api-localization/#locale-support-for-web-assembly","text":"This section explains twr-wasm's Web Assembly localization support.","title":"Locale Support for Web Assembly"},{"location":"api/api-localization/#character-encodings","text":"twr-wasm locales supports ASCII, UTF-8 or windows-1252 encoding. UTF-16/32 are not supported as a locale setting, but functions are provided to convert utf-32 (unicode code points) to and from ASCII, UTF-8, and windows-1252 \"code pages\" (there are other miscellaneous utf-32 based functions as well.) UTF-8 uses between one to four bytes to represent any unicode character, with ASCII compatibility in the first 128 bytes. It is also the standard for the web, and the default for clang. But because it uses a variable number of bytes per character it can make string manipulation in C a bit harder than ASCII. Windows-1252 is the default on most Windows computers in many countries - particularly the Americas and western Europe. It is an extension of ASCII that uses a single byte per character. This makes it easier than UTF-8 from a programmers perspective, but it doesn't represent as many characters. It is provided to make it easier to port legacy C code, windows code, as well as a simpler alternative to UTF-8. Although the locale settings don't support utf-32 directly, you can use int arrays (instead of byte arrays) to hold utf-32 strings, and then convert them to/from utf-8 with the help of the provided two functions for this purpose.","title":"Character encodings"},{"location":"api/api-localization/#locales","text":"","title":"Locales"},{"location":"api/api-localization/#c","text":"\"C\" is the default locale, as usual. When \"C\" is selected, the functions operate as usual. One subtly is that console i/o functions (such as printf ) will generally function as expected with UTF-8, since the div and window consoles correctly handle UTF-8 character encoding. This is normal on some OSs, such as linux, but not the default on Windows (which often defaults to windows-1252 for backward compatibility). isgraph style functions will only recognize ASCII characters, as is normal. Functions such as strcmp operate on the byte sequence, which will typically results in UTF-8 codes being compared lexically. strcoll will use lexical ordering.","title":"\"C\""},{"location":"api/api-localization/#posix","text":"\"POSIX\" is the same as \"C\"","title":"\"POSIX\""},{"location":"api/api-localization/#_1","text":"\"\" is the locale to specify the users default setting (this selects the setting used by the browser). This will also enable UTF-8 in functions such as strcoll . For example, if your browser is set to \"en-US\" as its default locale, setlocale(LC_ALL, \"\") will return en-US.UTF-8 . isgraph style functions will still only recognize ASCII characters (since UTF-8 doesn't encode any single bytes greater than 127). strcoll uses locale specific ordering, and printf will use locale specific decimal points. strcmp still compares two strings lexicographically (byte-by-byte) without considering locale-specific rules, per the spec.","title":"\"\""},{"location":"api/api-localization/#utf-8","text":"\".UTF-8\" is the same as \"\" with twr-wasm.","title":"\".UTF-8\""},{"location":"api/api-localization/#1252","text":"\".1252\" will select the current default locale, but use windows-1252 character encoding (instead of UTF-8). Windows-1252 is a super set of ISO-8859-1 and is the most commonly used encoding for many european languages when unicode is not used. This mode is primarily for legacy software, backwards compatibly, and windows compatibility. 1252 String Literals These days text editors generally default to UTF-8. In order to use windows-1252 source code and/or string literals, such as const char * str=\"\u20ac100\" you may need to: Configure your text editor to save in Windows-1252/ISO-8859-1 format (instead of UTF-8) use compiler flags like --finput-charset and -fexec-charset By default, the Microsoft Visual Studio C compiler (MSVC) does not treat string literals as UTF-8. Instead, it treats them as being encoded in the current code page of the system, which is typically Windows-1252 on western european language Windows systems. twr-wasm is designed to work with clang, which does default to utf-8, so if you are compiling code written for MSVC, and you use extend character sets (non ASCII), you may need to adjust your compiler settings with the flags mentioned above.","title":"\".1252\""},{"location":"api/api-localization/#others","text":"Setting arbitrary locales, such as \"fr-FR\" when the browser is defaulted to another locale, is not supported.","title":"Others"},{"location":"api/api-localization/#select-the-default-locale","text":"To select the user's browser's default locale using the C language, and enable consistent utf-8 support, use a call like this: setlocale(LC_ALL, \"\")","title":"Select the default locale"},{"location":"api/api-localization/#libc","text":"If you are using C++, libc++ locale functions work as expected.","title":"libc++"},{"location":"api/api-localization/#c-functions","text":"The normal standard C library locale support is available, along with some POSIX extensions. In addition, some locale useful twr-wasm specific functions are documented in C API , such as twr_get_current_locale , twr_mbgets , twr_getc32 , twr_utf8_char_len , twr_mbslen_l , twr_utf32_to_code_page , twr_code_page_to_utf32_streamed , twr_get_navlang , twr_localize_numeric_string . Note that io_getc32() , getc(stdin) , fgetc(stdin) do not look at the current locale. iogetc32 returns a 32 bit unicode code point, and getc / fgetc return extended ASCII. For a locale aware character input, use io_mbgetc() or twr_mbgets() . Both use the locale category LC_CTYPE. See C API . Note that when the locale is not set (or whenever the \"C\" locale is set) functions that get character(s) from stdin that are locale aware, like twr_mbgets() , behave different than functions that output characters to stdout (like puts , io_putstr , io_putc , putchar ). Characters to stdout in \"C\" locale will handle UTF-8 characters. For stdin, \"C\" locale uses ASCII. For consistent UTF-8 (or windows-1252) behavior, set the locale as discussed above ( use setlocale ) The primary standard C library locale functions are: char* setlocale(int category, const char* locale); struct lconv *localeconv(void); As well as the standard library functions above, appropriate functions take into account the current locale (printf, strcoll, etc). Note that setlocale returns a string using BCP 47 format (similar to a web browser). Locale strings look like \"en-US.UTF-8\", instead of \"en_US.UTF-8\". A dash, not an underscore, is used as a separator.","title":"C functions"},{"location":"api/api-localization/#posix-functions","text":"These are the extended POSIX style functions provided that are related to locale: locale_t newlocale(int category_mask, const char *locale, locale_t base); locale_t uselocale(locale_t); void freelocale(locale_t); locale_t duplocale(locale_t); int isalnum_l(int c, locale_t loc); int isalpha_l(int c, locale_t loc); int isblank_l(int c, locale_t loc); int iscntrl_l(int c, locale_t loc); int isdigit_l(int c, locale_t loc); int isgraph_l(int c, locale_t loc); int islower_l(int c, locale_t loc); int isprint_l(int c, locale_t loc); int ispunct_l(int c, locale_t loc); int isspace_l(int c, locale_t loc); int isupper_l(int c, locale_t loc); int isxdigit_l(int c, locale_t loc); int tolower_l(int c, locale_t loc); int toupper_l(int c, locale_t loc); long long strtoll_l(const char *str, char **str_end, int base, locale_t loc); unsigned long long strtoull_l(const char *str, char **str_end, int base, locale_t loc); float strtof_l(const char *str, char ** str_end, locale_t locale); double strtod_l(const char *str, char **str_end, locale_t locale); long double strtold_l(const char *str, char **str_end, locale_t locale); int strcoll_l(const char* lhs, const char* rhs, locale_t loc); size_t strftime_l(char *s, size_t maxsize, const char *format, const struct tm *timeptr, locale_t locale);","title":"POSIX functions"},{"location":"api/api-typescript/","text":"TypeScript-JavaScript API for WASM This section describes the twr-wasm TypeScript/JavaScript classes that you use to load your wasm modules, and to call C functions in your wasm modules. class twrWasmModule and class twrWasmModuleAsync have similar APIs. The primary difference is that class twrWasmModuleAsync proxies functionality through a Web Worker thread, which allows blocking C functions to be called in your Web Assembly Module. class twrWasmModule import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); twrWasmModule provides the two core JavaScript APIs for access to a Web Assembly Module: loadWasm to load your .wasm module (your compiled C code). callC to call a C function These functions are documented further down in this section. class twrWasmModuleAsync import {twrWasmModuleAsync} from \"twr-wasm\"; const amod = new twrWasmModuleAsync(); twrWasmModuleAsync implements all of the same functions as twrWasmModule , plus allows blocking inputs, and blocking code generally. This is achieved by proxying all the calls through a Web Worker thread. Use twrWasmModuleAsync if your C code blocks, or if you are unsure. If you want better performance and don't need the capabilities of twrWasmModuleAsync , use twrWasmModule . You must use twrWasmModuleAsync in order to: call any blocking C function (meaning it takes \"a long time\") to return use blocking input from a div or canvas ( eg. twr_mbgets ) use twr_sleep See stdio section for information on enabling blocking character input, as well as this Example . When comping/linking your C/C++ code, twrWasmModule and twrWasmModuleAsync use slightly different wasm-ld options since twrWasmModuleAsync uses shared memory. wrWasmModule will operate with shared memory, so technically you could just use the same share memory options with either module, but you don't need the overhead of shared memory when using twrWasmModule, and so better to not enable it. See Compiler Options . twrWasmModuleAsync uses SharedArrayBuffers which require certain HTTP headers to be set. Note that twrWasmModule has an advantage in that it does not use SharedArrayBuffers. Github pages doesn't support the needed CORS headers for SharedArrayBuffers. But other web serving sites do have options to enable the needed CORS headers. For example, the azure static web site config file staticwebapp.config.json looks like this: { \"globalHeaders\": { \"Access-Control-Allow-Origin\": \"*\", \"Cross-Origin-Embedder-Policy\": \"require-corp\", \"Cross-Origin-Opener-Policy\": \"same-origin\" } } server.py in the examples folder will launch a local server with the correct headers. To use Chrome without a web server, see the debugging section . Class Options The twrWasmModule and twrWasmModuleAsync constructor both take optional options. For example: let amod=new twrWasmModuleAsync(); let amod=new twrWasmModuleAsync({ windim:[50,20], forecolor:\"beige\", backcolor:\"DarkOliveGreen\", fontsize:18 }); For a
      it is simpler to set the color and font in the div tag per the normal HTML method. But for
      , that method won't work and you need to use the constructor options for color and fontsize. These are the options: export type TStdioVals=\"div\"|\"canvas\"|\"null\"|\"debug\"; export interface IModOpts { stdio?:TStdioVals, windim?:[number, number], forecolor?:string, backcolor?:string, fontsize?:number, imports?:{}, } stdio You can explicitly set your stdio source (for C/C++ printf, etc) with the stdio option, but typically you don't set it. Instead, it will auto set as described here windim This options is used with a terminal console ( ) to set the width and height, in characters. The canvas width and height, in pixels, will be set based on your fontsize and the width and height (in characters) of the terminal. forecolor and backcolor These can be set to a CSS color (like '#FFFFFF' or 'white') to change the default background and foreground colors. fonsize Changes the default fontsize for div or canvas based I/O. The size is in pixels. loadWasm Use loadWasm to load your compiled C/C++ code (the .wasm file). await mod.loadWasm(\"./mycode.wasm\") callC After your . wasm module is loaded with loadWasm , you call functions in your C/C++ from TypeScript/JavaScript like this: let result=await amod.callC([\"bounce_balls_move\", param1]) If you are calling into C++, you need to use extern \"C\" like this in your C++ code: extern \"C\" int bounce_balls_move() {} Each C/C++ function that you wish to call from TypeScript/JavaScript needs to be exported in your wasm-ld settings like this: --export=bounce_balls_move Or like this in your source file: __attribute__((export_name(\"bounce_balls_move\"))) void bounce_balls_move() { ... See the Compiler Options . callC takes an array where: the first entry is the name of the C function in the wasm module to call and the next entries are a variable number of parameters to pass to the C function, of type: number - will be converted to int32 or float64 as appropriate string - converted to a pointer to module Memory where string is copied into ArrayBuffer - the array is loaded into module memory. If you need to pass the length, pass it as a separate parameter. Any modifications to the memory made by your C code will be reflected back into the JavaScript ArrayBuffer. URL - the url contents are loaded into module Memory, and two C parameters are generated - index (pointer) to the memory, and length callC returns the value returned by the C function that was called. As well int and float , string and structs (or blocks of memory) can be returned. More details can be found in examples/function-calls . The FFT example demonstrates passing a Float32Array view of an ArrayBuffer. Also see Key Concepts . divLog If stdio is set to twr_iodiv , you can use the divLog twrWasmModule/Async function like this: import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); await mod.loadWasm(\"./tests.wasm\"); await mod.callC([\"tests\"]); mod.divLog(\"\\nsin() speed test\"); let sumA=0; const start=Date.now(); for (let i=0; i<2000000;i++) sumA=sumA+Math.sin(i); const endA=Date.now(); let sumB=await mod.callC([\"sin_test\"]); const endB=Date.now(); mod.divLog(\"sum A: \", sumA, \" in ms: \", endA-start); mod.divLog(\"sum B: \", sumB, \" in ms: \", endB-endA); Accessing Data in the Web Assembly Memory You probably will not need to use the twrWasmModule/Async functions in this section, as callC() will convert your parameters for you. But if you return or want to pass in more complicated structs, you might need to. The source in source/twr-wasm-ts/canvas.ts is an example of how these are used. async putString(sin:string, codePage=codePageUTF8) // returns index into WebAssembly.Memory async putU8(u8a:Uint8Array) // returns index into WebAssembly.Memory async putArrayBuffer(ab:ArrayBuffer) // returns index into WebAssembly.Memory async fetchAndPutURL(fnin:URL) // returns index into WebAssembly.Memory async malloc(size:number) // returns index in WebAssembly.Memory. stringToU8(sin:string, codePage=codePageUTF8) copyString(buffer:number, buffer_size:number, sin:string, codePage=codePageUTF8):void getLong(idx:number): number setLong(idx:number, value:number) getDouble(idx:number): number setDouble(idx:number, value:number) getShort(idx:number): number getString(strIndex:number, len?:number, codePage=codePageUTF8): string getU8Arr(idx:number): Uint8Array getU32Arr(idx:number): Uint32Array memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array;","title":"TypeScript/JavaScript"},{"location":"api/api-typescript/#typescript-javascript-api-for-wasm","text":"This section describes the twr-wasm TypeScript/JavaScript classes that you use to load your wasm modules, and to call C functions in your wasm modules. class twrWasmModule and class twrWasmModuleAsync have similar APIs. The primary difference is that class twrWasmModuleAsync proxies functionality through a Web Worker thread, which allows blocking C functions to be called in your Web Assembly Module.","title":"TypeScript-JavaScript API for WASM"},{"location":"api/api-typescript/#class-twrwasmmodule","text":"import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); twrWasmModule provides the two core JavaScript APIs for access to a Web Assembly Module: loadWasm to load your .wasm module (your compiled C code). callC to call a C function These functions are documented further down in this section.","title":"class twrWasmModule"},{"location":"api/api-typescript/#class-twrwasmmoduleasync","text":"import {twrWasmModuleAsync} from \"twr-wasm\"; const amod = new twrWasmModuleAsync(); twrWasmModuleAsync implements all of the same functions as twrWasmModule , plus allows blocking inputs, and blocking code generally. This is achieved by proxying all the calls through a Web Worker thread. Use twrWasmModuleAsync if your C code blocks, or if you are unsure. If you want better performance and don't need the capabilities of twrWasmModuleAsync , use twrWasmModule . You must use twrWasmModuleAsync in order to: call any blocking C function (meaning it takes \"a long time\") to return use blocking input from a div or canvas ( eg. twr_mbgets ) use twr_sleep See stdio section for information on enabling blocking character input, as well as this Example . When comping/linking your C/C++ code, twrWasmModule and twrWasmModuleAsync use slightly different wasm-ld options since twrWasmModuleAsync uses shared memory. wrWasmModule will operate with shared memory, so technically you could just use the same share memory options with either module, but you don't need the overhead of shared memory when using twrWasmModule, and so better to not enable it. See Compiler Options . twrWasmModuleAsync uses SharedArrayBuffers which require certain HTTP headers to be set. Note that twrWasmModule has an advantage in that it does not use SharedArrayBuffers. Github pages doesn't support the needed CORS headers for SharedArrayBuffers. But other web serving sites do have options to enable the needed CORS headers. For example, the azure static web site config file staticwebapp.config.json looks like this: { \"globalHeaders\": { \"Access-Control-Allow-Origin\": \"*\", \"Cross-Origin-Embedder-Policy\": \"require-corp\", \"Cross-Origin-Opener-Policy\": \"same-origin\" } } server.py in the examples folder will launch a local server with the correct headers. To use Chrome without a web server, see the debugging section .","title":"class twrWasmModuleAsync"},{"location":"api/api-typescript/#class-options","text":"The twrWasmModule and twrWasmModuleAsync constructor both take optional options. For example: let amod=new twrWasmModuleAsync(); let amod=new twrWasmModuleAsync({ windim:[50,20], forecolor:\"beige\", backcolor:\"DarkOliveGreen\", fontsize:18 }); For a
      it is simpler to set the color and font in the div tag per the normal HTML method. But for
      , that method won't work and you need to use the constructor options for color and fontsize. These are the options: export type TStdioVals=\"div\"|\"canvas\"|\"null\"|\"debug\"; export interface IModOpts { stdio?:TStdioVals, windim?:[number, number], forecolor?:string, backcolor?:string, fontsize?:number, imports?:{}, }","title":"Class Options"},{"location":"api/api-typescript/#stdio","text":"You can explicitly set your stdio source (for C/C++ printf, etc) with the stdio option, but typically you don't set it. Instead, it will auto set as described here","title":"stdio"},{"location":"api/api-typescript/#windim","text":"This options is used with a terminal console ( ) to set the width and height, in characters. The canvas width and height, in pixels, will be set based on your fontsize and the width and height (in characters) of the terminal.","title":"windim"},{"location":"api/api-typescript/#forecolor-and-backcolor","text":"These can be set to a CSS color (like '#FFFFFF' or 'white') to change the default background and foreground colors.","title":"forecolor and backcolor"},{"location":"api/api-typescript/#fonsize","text":"Changes the default fontsize for div or canvas based I/O. The size is in pixels.","title":"fonsize"},{"location":"api/api-typescript/#loadwasm","text":"Use loadWasm to load your compiled C/C++ code (the .wasm file). await mod.loadWasm(\"./mycode.wasm\")","title":"loadWasm"},{"location":"api/api-typescript/#callc","text":"After your . wasm module is loaded with loadWasm , you call functions in your C/C++ from TypeScript/JavaScript like this: let result=await amod.callC([\"bounce_balls_move\", param1]) If you are calling into C++, you need to use extern \"C\" like this in your C++ code: extern \"C\" int bounce_balls_move() {} Each C/C++ function that you wish to call from TypeScript/JavaScript needs to be exported in your wasm-ld settings like this: --export=bounce_balls_move Or like this in your source file: __attribute__((export_name(\"bounce_balls_move\"))) void bounce_balls_move() { ... See the Compiler Options . callC takes an array where: the first entry is the name of the C function in the wasm module to call and the next entries are a variable number of parameters to pass to the C function, of type: number - will be converted to int32 or float64 as appropriate string - converted to a pointer to module Memory where string is copied into ArrayBuffer - the array is loaded into module memory. If you need to pass the length, pass it as a separate parameter. Any modifications to the memory made by your C code will be reflected back into the JavaScript ArrayBuffer. URL - the url contents are loaded into module Memory, and two C parameters are generated - index (pointer) to the memory, and length callC returns the value returned by the C function that was called. As well int and float , string and structs (or blocks of memory) can be returned. More details can be found in examples/function-calls . The FFT example demonstrates passing a Float32Array view of an ArrayBuffer. Also see Key Concepts .","title":"callC"},{"location":"api/api-typescript/#divlog","text":"If stdio is set to twr_iodiv , you can use the divLog twrWasmModule/Async function like this: import {twrWasmModule} from \"twr-wasm\"; const mod = new twrWasmModule(); await mod.loadWasm(\"./tests.wasm\"); await mod.callC([\"tests\"]); mod.divLog(\"\\nsin() speed test\"); let sumA=0; const start=Date.now(); for (let i=0; i<2000000;i++) sumA=sumA+Math.sin(i); const endA=Date.now(); let sumB=await mod.callC([\"sin_test\"]); const endB=Date.now(); mod.divLog(\"sum A: \", sumA, \" in ms: \", endA-start); mod.divLog(\"sum B: \", sumB, \" in ms: \", endB-endA);","title":"divLog"},{"location":"api/api-typescript/#accessing-data-in-the-web-assembly-memory","text":"You probably will not need to use the twrWasmModule/Async functions in this section, as callC() will convert your parameters for you. But if you return or want to pass in more complicated structs, you might need to. The source in source/twr-wasm-ts/canvas.ts is an example of how these are used. async putString(sin:string, codePage=codePageUTF8) // returns index into WebAssembly.Memory async putU8(u8a:Uint8Array) // returns index into WebAssembly.Memory async putArrayBuffer(ab:ArrayBuffer) // returns index into WebAssembly.Memory async fetchAndPutURL(fnin:URL) // returns index into WebAssembly.Memory async malloc(size:number) // returns index in WebAssembly.Memory. stringToU8(sin:string, codePage=codePageUTF8) copyString(buffer:number, buffer_size:number, sin:string, codePage=codePageUTF8):void getLong(idx:number): number setLong(idx:number, value:number) getDouble(idx:number): number setDouble(idx:number, value:number) getShort(idx:number): number getString(strIndex:number, len?:number, codePage=codePageUTF8): string getU8Arr(idx:number): Uint8Array getU32Arr(idx:number): Uint32Array memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array;","title":"Accessing Data in the Web Assembly Memory"},{"location":"examples/examples-balls/","text":"Bouncing Balls - Web Assembly C++ Example This example uses Web Assembly, C++, and twr-wasm to bounce balls around your HTML page. It uses twr-wasm's 2D Draw API and a C++ Canvas class. View bouncing balls Source for balls The bouncing balls example demonstrates C++ Using the twr-wasm draw 2D APIs that match Javascript Canvas APIs. A C++ wrapper for the JavaScript Canvas class This example does not use libc++, which results in smaller code size. For an example that uses libc++ see tests-libcxx .","title":"balls"},{"location":"examples/examples-fft/","text":"FFT - Web Assembly C Example This example is a demo of integrating an existing FFT C library with Typescript/JavaScript/HTML using Web Assembly. The FFT C library is compiled into a wasm (Web Assembly) module, with the help of twr-wasm. The FFT wasm module is used by the HTML page to calculate the FFT. The FFT input and output is drawn to the web page using the normal JavaScript functions. The FFT library exposes APIs to process data, and doesn't use stdio. The FFT APIs use float32 arrays for complex-number input and output data, and a configuration struct. In the example I generate the input data by adding a 1K and 5K sine waves, call the kiss FFT API to perform the FFT on the generated sine waves, and then graph the input and output data using JavaScript Canvas. View running on the web View Source Code Here is part of the code. The rest can be found in the example. Fast Fourier transform (FFT)
      Input Signal



      FFT Output
      import {twrWasmModule} from \"twr-wasm\"; export async function fftDemo() { const mod=new twrWasmModule(); // load the kiss_fft C code as is, unmodified await mod.loadWasm('kiss_fft.wasm'); // kissFFTData stores and graphs the input and output data // in this example the fft has 1024 bins, and I am using a 48K sampling rate let fft=new kissFFTData(1024, 48000); fft.genSin(1000) fft.addSin(5000) fft.graphIn(\"c-input\"); // see kiss_fft README, but in summary you: (a) alloc config, (b) compute the FFT, (c) free the config // kiss_fft_alloc() returns a malloced structure. Pointers are numbers (index into wasm module memory) in JS land // //kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 ); let cfg:number = await mod.callC([\"kiss_fft_alloc\", fft.nfft, 0, 0, 0 ]); // The FFT input and output data are C arrays of complex numbers. // typedef struct { // kiss_fft_scalar r; // kiss_fft_scalar i; // } kiss_fft_cpx; // // /* default is float */ // define kiss_fft_scalar float // So if the FFT data has 1024 bins, then 1024 * 2 floats (r & i) * 4 bytes per float are needed. // I use a JS Float32Array view on the ArrayBuffer to access the floats // When an arrayBuffer is passed in as an argument to mod.callC, // callC will malloc memory in the wasm module of a size that matches the array buffer, then // copy the arraybuffer into the malloc'd memory prior to the function call, // then copy the malloc'd memory contents back into the arrayBuffer post call. // The malloc'd memory is free'd post call. // void kiss_fft(kiss_fft_cfg cfg,const kiss_fft_cpx *fin,kiss_fft_cpx *fout); await mod.callC([\"kiss_fft\", cfg, fft.inArrayBuf, fft.outArrayBuf]); fft.graphOut(\"c-output\"); await mod.callC([\"free\", cfg]); // not much point to this since all the module memory is about to disappear }","title":"fft"},{"location":"examples/examples-helloworld/","text":"Hello World - Web Assembly C Example This example is an very simple twr-wasm program. It uses Web Assembly and C to print \"hello world\" to an HTML
      tag. Also see: Hello World - Step-by-Step C to WASM . View helloworld running live View helloworld Source","title":"hello world"},{"location":"examples/examples-libcxx/","text":"tests-libcxx - Web Assembly libc++ Example This simple smoke test for using libc++ with Web Assembly demonstrates a simple twr-wasm C++ program that uses libc++, and shows the needed makefile. view tests-libcxx running live View tests-libcxx Source Also see this Web Assembly program that uses libc++ with twr-wasm to implement a CLI console. tests-user Live tests-user Source","title":"libc++"},{"location":"examples/examples-maze/","text":"Maze - Web Assembly C Example This example is a port to wasm of a 20 year old Win32 C program with the help of twr-wasm 2D Draw APIs. View live maze here Source for maze This example (in winemu.c) uses the twr-wasm \"d2d\" (Draw 2D) APIs. These allow drawing onto an HTML canvas from C/C++. See the balls example for a C++ Canvas class. I have included the TypesScript below. You can see the C code in the examples/maze folder. This C is interesting in that it is a combination of blocking and non blocking functions. The CalcMaze() function is blocking when the \"slow draw\" flag is set. It uses Sleep() in this case. For this reason, I use twrWasmModuleAsync. The solve section uses repeated calls to SolveStep(), which works well with a JavaScript main loop. I used a javascript interval timer to make repeated calls to the C SolveStep(). If all the C code was structured this way, twrWasmModule could have been used (instead of the Async version) To port this code to twr-wasm I wrote a (very tiny) Win32 compatible API. It only implements the features needed to port maze, but it might be useful to use as a starting point for porting your Win32 code to the web. In the maze example, the two files are winemu.c and winemu.h. You use winemu.h to replace windows.h Maze import {twrWasmModuleAsync} from \"twr-wasm\"; export async function mazeRunner() { const amod=new twrWasmModuleAsync(); await amod.loadWasm('maze.wasm'); //void CalcMaze(HWND hWnd, LONG cell_size, LONG is_black_bg, LONG isd - slow draw) await amod.callC([\"CalcMaze\", 0, 7, 0, 1]); await amod.callC([\"SolveBegin\"]); let timer = setInterval(async ()=>{ let isdone=await amod.callC([\"SolveStep\", 0]); //SolveStep(hwnd)) if (isdone) clearInterval(timer); }, 50); }","title":"maze"},{"location":"examples/examples-more/","text":"More Web Assembly Examples Some other examples include: function-calls demos the different types of parameters that can be passed to a C function tests are the twr-wasm unit tests All Examples Live & Source The source for all of the examples is here on github All of the examples are available to view running live on the internet","title":"more"},{"location":"examples/examples-overview/","text":"Web Assembly C/C++ Examples These C and C++ examples demonstrate how to create different types of Web Assembly (wasm) programs with the twr-wasm library. These are good examples to use as starting points for your own wasm projects. These examples are a good place to learn how to configure clang and wasm-ld to compile and link C/C++ code for use with Web Assembly (wasm). Example Quick Links Click here to view C/C++ Web Assembly twr-wasm examples running live Click here to view source code and make files Examples Overview Each of these examples are designed to illustrate how to use a feature of twr-wasm. Name Description Link helloworld A very simple C wasm example to get you started helloworld stdio-div This simple C program demos inputting and printing characters to a div tag stdio-div stdio-canvas This simple C program demos writing and inputting from a tag that twr-wasm configures as a windowed \"mini-terminal\" stdio-canvas balls These fun Bouncing Balls are written in C++ and demo the 2D drawing APIs with a C++ Canvas wrapper class balls maze This is an old Win32 program ported to wasm and demos the 2D Draw APIs maze fft A demo of calling a C library to perform an FFT that is graphed in Typescript fft tests-libcxx Smoke test for libc++. Shows how to use libc++. tests-libcxx tests-user \"cli\" for tests using libc++ and tests-user more Demo of function calls, units tests more Building the Examples See Example Readme for more information on building and running the examples.","title":"Overview"},{"location":"examples/examples-stdio-canvas/","text":"stdio-canvas - Web Assembly 'terminal' C Example Print and input \"Hello World\" from a \"terminal\" window. A tiny Web Assembly C \"terminal\" can be created with input and output direct to a tag, and you can use it for character I/O with control over where the character appear in the terminal window. This example will move a string up or down in the terminal window when you press the u or d key. View stdio-canvas running live View stdio-canvas Source For another 'terminal' demo View tests-user #include #include #include #include \"twr-crt.h\" #include \"twr-wasm.h\" /* this twr-wasm C example draws a string in the middle of a windowed console, */ /* and allows the user to move the string up or down with the u or d keys */ /* see include/twr-io.h for available functions to draw chars to windowed console */ void show_str_centered(struct IoConsoleWindow* iow, int h, const char* str); void stdio_canvas() { struct IoConsoleWindow* iow=(struct IoConsoleWindow*)twr_get_stdio_con(); if (!(iow->con.header.type&IO_TYPE_WINDOW)) { // could also use assert here twr_conlog(\"error - expected window console\\n\"); return; } int h, c; const char* str=\"Hello World (press u or d)\"; const char* spc=\" \"; h=iow->display.height/2; while (1) { show_str_centered(iow, h, str); c=twr_getc32(); show_str_centered(iow, h, spc); // erase old string if (c=='u') { h=h-1; if (h<0) h=0; } if (c=='d') { h=h+1; if (h>=iow->display.height) h=iow->display.height-1; } } } void show_str_centered(struct IoConsoleWindow* iow, int h, const char* str) { int strlen=strlen(str); int x=(iow->display.width-strlen)/2; io_set_cursorxy(iow, x, h); io_putstr(&iow->con, str); } stdio-canvas example ","title":"stdio-canvas"},{"location":"examples/examples-stdio-div/","text":"stdio-div - Web Assembly stdio-to-div C Example This simple Web Assembly C program demos inputting and printing characters to a div tag. view stdio-div running live View stdio-div Source #include #include #include \"twr-crt.h\" void stdio_div() { char inbuf[64]; int i; printf(\"Square Calculator\\n\"); while (1) { printf(\"Enter an integer: \"); twr_mbgets(inbuf); i=atoi(inbuf); printf(\"%d squared is %d\\n\\n\",i,i*i); } } With an index.html like the following. This time we are using twrWasmModuleAsync which integrates blocking C code into JavaScript. twrWasmModuleAsync can also be used to receive key input from a
      or tag. stdio-div example
      Loading...
      ","title":"stdio-div"},{"location":"gettingstarted/compiler-opts/","text":"Compiling, Linking, and Memory Options This section described how to use clang to compile C/C++ code for Web Assembly, and how to link your files into a .wasm module. twr-wasm lets you use clang directly, without a wrapper. This section describes the needed clang compile options and the wasm-ld link options. You can also take a look at the example makefiles . C clang Compiler Options Targeting WASM When compiling C code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -nostdinc -nostdlib -isystem ../../include -isystem should point to the folder twr-wasm/include . The option line above uses a relative link to include that works if your project is a sub folder in the examples folder. If you installed using npm, then includes are at node_modules/twr-wasm/include (see the installation note on npm ). You will also need to link to twr.a (explained in the linking section below). C++ clang Compiler Options Targeting WASM When compiling C++ code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -fno-exceptions -fno-rtti -nostdlibinc -nostdinc -nostdlib -isystem ../../include You will also need to link to twr.a and libc++.a (explained in the linking section below). Be sure to adjust the path to twr.a , libc++.a , and the include folder as needed (see above note in the C section). wasm-ld Linker Options Use the wasm-ld linker directly with twr-wasm. All of the twr-wasm functions are staticly linked from the library lib-c/twr.a . There is also a version ( lib-c/twrd.a ) of twr-wasm library available with debug symbols. One of these two static libraries should be added to the list of files to link (normally this is twr.a ). Both versions are built with asserts enabled. twr.a is built with -O3 . twrd.a is built with -g -O0 . To use libc++ , link to libc++.a (see the tests-libcxx example makefile). C functions that you wish to call from JavaScript should either have an -export option passed to wasm-ld , or you can use the __attribute__((export_name(\"function_name\"))) option in your C function definition. All exported functions to JavaScript should be C linkage ( extern \"C\" if using C++). wasm-ld should also be passed the following options: If Using twrWasmModule: --no-entry --initial-memory= --max-memory= If Using twrWasmModuleAsync: --no-entry --shared-memory --no-check-features --initial-memory= --max-memory= Memory Options for Web Assembly You set the memory size for your module ( WebAssembly.Memory ) using wasm-ld options as follows (this examples sets your wasm memory to 1MB). The memory size should be a multiple of 64*1024 (64K) chunks. if using twrWasmModule : --initial-memory=1048576 --max-memory=1048576 If you are using twrWasmModuleAsync , shared memory must also be enabled. Like this: --shared-memory --no-check-features --initial-memory=1048576 --max-memory=1048576 See this production note on using shared memory . The memory is an export out of the .wasm into the JavaScript code. There is no support for automatically growing memory. You can change your C/C++ stack size from the default 64K with the following wasm-ld option. This example sets the stack at 128K -z stack-size=131072 You can print your module memory map, heap stats, and stack size using the function from C: void twr_mem_debug_stats(struct IoConsole* outcon); You can call it from Javascript with the output sent to the debug console (stderr) like this: twrWasmModule/Async.callC([\"twr_wasm_print_mem_debug_stats\"]) twrWasmModule and twrWasmModuleAsync expose malloc as an async function, as well as the Web Assembly Module memory as: async malloc(size:number); memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array; to call free() from JavaScript (you probably won't need to), you can use: twrWasmModule/Async.callC(\"twr_free\", index); // index to memory to free, as returned by malloc","title":"Compiler, Linker, Memory"},{"location":"gettingstarted/compiler-opts/#compiling-linking-and-memory-options","text":"This section described how to use clang to compile C/C++ code for Web Assembly, and how to link your files into a .wasm module. twr-wasm lets you use clang directly, without a wrapper. This section describes the needed clang compile options and the wasm-ld link options. You can also take a look at the example makefiles .","title":"Compiling, Linking, and Memory Options"},{"location":"gettingstarted/compiler-opts/#c-clang-compiler-options-targeting-wasm","text":"When compiling C code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -nostdinc -nostdlib -isystem ../../include -isystem should point to the folder twr-wasm/include . The option line above uses a relative link to include that works if your project is a sub folder in the examples folder. If you installed using npm, then includes are at node_modules/twr-wasm/include (see the installation note on npm ). You will also need to link to twr.a (explained in the linking section below).","title":"C clang Compiler Options Targeting WASM"},{"location":"gettingstarted/compiler-opts/#c-clang-compiler-options-targeting-wasm_1","text":"When compiling C++ code with clang for use with wasm and twr-wasm, use these clang options: --target=wasm32 -fno-exceptions -fno-rtti -nostdlibinc -nostdinc -nostdlib -isystem ../../include You will also need to link to twr.a and libc++.a (explained in the linking section below). Be sure to adjust the path to twr.a , libc++.a , and the include folder as needed (see above note in the C section).","title":"C++ clang Compiler Options Targeting WASM"},{"location":"gettingstarted/compiler-opts/#wasm-ld-linker-options","text":"Use the wasm-ld linker directly with twr-wasm. All of the twr-wasm functions are staticly linked from the library lib-c/twr.a . There is also a version ( lib-c/twrd.a ) of twr-wasm library available with debug symbols. One of these two static libraries should be added to the list of files to link (normally this is twr.a ). Both versions are built with asserts enabled. twr.a is built with -O3 . twrd.a is built with -g -O0 . To use libc++ , link to libc++.a (see the tests-libcxx example makefile). C functions that you wish to call from JavaScript should either have an -export option passed to wasm-ld , or you can use the __attribute__((export_name(\"function_name\"))) option in your C function definition. All exported functions to JavaScript should be C linkage ( extern \"C\" if using C++). wasm-ld should also be passed the following options: If Using twrWasmModule: --no-entry --initial-memory= --max-memory= If Using twrWasmModuleAsync: --no-entry --shared-memory --no-check-features --initial-memory= --max-memory=","title":"wasm-ld Linker Options"},{"location":"gettingstarted/compiler-opts/#memory-options-for-web-assembly","text":"You set the memory size for your module ( WebAssembly.Memory ) using wasm-ld options as follows (this examples sets your wasm memory to 1MB). The memory size should be a multiple of 64*1024 (64K) chunks. if using twrWasmModule : --initial-memory=1048576 --max-memory=1048576 If you are using twrWasmModuleAsync , shared memory must also be enabled. Like this: --shared-memory --no-check-features --initial-memory=1048576 --max-memory=1048576 See this production note on using shared memory . The memory is an export out of the .wasm into the JavaScript code. There is no support for automatically growing memory. You can change your C/C++ stack size from the default 64K with the following wasm-ld option. This example sets the stack at 128K -z stack-size=131072 You can print your module memory map, heap stats, and stack size using the function from C: void twr_mem_debug_stats(struct IoConsole* outcon); You can call it from Javascript with the output sent to the debug console (stderr) like this: twrWasmModule/Async.callC([\"twr_wasm_print_mem_debug_stats\"]) twrWasmModule and twrWasmModuleAsync expose malloc as an async function, as well as the Web Assembly Module memory as: async malloc(size:number); memory?:WebAssembly.Memory; mem8:Uint8Array; mem32:Uint32Array; memD:Float64Array; to call free() from JavaScript (you probably won't need to), you can use: twrWasmModule/Async.callC(\"twr_free\", index); // index to memory to free, as returned by malloc","title":"Memory Options for Web Assembly"},{"location":"gettingstarted/helloworld/","text":"Hello World - Step-by-Step C to WASM This section shows you step by step how to to create a C \"hello world\" program for Web Assembly (WASM) with twr-wasm, C, HTML, and JavaScript. You will learn how to: Create the helloworld.c C file Create the index.html HTML File Compile the helloworld.c code Link the helloworld.o and twr.a files to create a helloworld.wasm file Set the needed library and include paths to allow the twr-wasm libraries to be discovered Create an optional Makefile Execute the \"hello world\" program using a local web server or directly with VS Code and Chrome You can find all of the code for this section in the folder examples\\helloworld . Step 1: Create the C code Create a file helloworld.c #include void hello() { printf(\"hello world\\n\"); } Step 2: Create the HTML Create a file index.html Hello World
      This example uses Import Maps, which are used when not using a bundler like WebPack or Parcel. This can be a simpler and more clear debugging and development environment. The relative path in the importmap section should be updated to point to the location where you installed twr-wasm/lib-js . The path above is correct if your file is in an example subfolder. As another example, if you used git clone https://github.com/twiddlingbits/twr-wasm to create a folder named twr-wasm and you create your hello world project with a folder structure like this: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm Then you would use an Import Map code snippet like this: Step 3: Compile your C code to create your .wasm file clang --target=wasm32 -nostdinc -nostdlib -isystem ../../include -c helloworld.c -o helloworld.o wasm-ld helloworld.o ../../lib-c/twr.a -o helloworld.wasm --no-entry --initial-memory=131072 --max-memory=131072 --export=hello The path to twr.a and to include may need to be updated to match your installation. The above path is correct if your code is in an example subfolder. Alternately, if you had the folder structure described in Step 2: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm \u2514\u2500\u2500 Makefile You could use a MakeFile like this: CC := clang TWRCFLAGS := --target=wasm32 -nostdinc -nostdlib -isystem twr-wasm/include CFLAGS := -c -Wall -O3 $(TWRCFLAGS) CFLAGS_DEBUG := -c -Wall -g -O0 $(TWRCFLAGS) .PHONY: default default: helloworld.wasm helloworld.o: helloworld.c $(CC) $(CFLAGS) $< -o $@ helloworld.wasm: helloworld.o wasm-ld helloworld.o twr-wasm/lib-c/twr.a -o helloworld.wasm \\ --no-entry --initial-memory=131072 --max-memory=131072 \\ --export=hello Step 4: Load your web page The two easiest ways to load and execute your index.html web page locally are: Option A: Run a local web Server You can run a local server to view your helloworld program. Copy the file server.py from the examples folder to your project folder where your index.html resides. Execute with the shell command python server.py . Option B: VS Code launch.json Alternately, you can launch chrome without a local web server. Add an entry similar to the following to your VS code project's .vscode\\launch.json . Adjust the file and cwd lines to be correct for your project. { \"name\": \"hello\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [ \"--allow-file-access-from-files\", \"--autoplay-policy=no-user-gesture-required\", \"--enable-features=SharedArrayBuffer\" ], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" } --autoplay-policy=no-user-gesture-required and --enable-features=SharedArrayBuffer are not required for this simple \"hello world\" example, but will be needed if you request user input or you are using twrWasModuleAsync. See live version Here is a link to the helloworld function running in the twiddlingbits.dev site. Next steps after hello world A good way to get your own code up and running is to copy one of the twr-wasm/examples , get it to build and run, then start modifying it. The example makefiles prove a more practical way to configure and execute clang and wasm-ld. \"Hello World\" uses the twr-wasm class twrWasmModule . If you wish to use C blocking functions, such as twr_getc32 or twr_sleep , you can use twrWasmModuleAsync . This square calculator example shows how to do this. If you wish to build an app that makes non-block calls into C, the balls example shows how to do this. The maze example uses a combination of blocking and non-blocking C functions.","title":"Create wasm C Hello World"},{"location":"gettingstarted/helloworld/#hello-world-step-by-step-c-to-wasm","text":"This section shows you step by step how to to create a C \"hello world\" program for Web Assembly (WASM) with twr-wasm, C, HTML, and JavaScript. You will learn how to: Create the helloworld.c C file Create the index.html HTML File Compile the helloworld.c code Link the helloworld.o and twr.a files to create a helloworld.wasm file Set the needed library and include paths to allow the twr-wasm libraries to be discovered Create an optional Makefile Execute the \"hello world\" program using a local web server or directly with VS Code and Chrome You can find all of the code for this section in the folder examples\\helloworld .","title":"Hello World - Step-by-Step C to WASM"},{"location":"gettingstarted/helloworld/#step-1-create-the-c-code","text":"Create a file helloworld.c #include void hello() { printf(\"hello world\\n\"); }","title":"Step 1: Create the C code"},{"location":"gettingstarted/helloworld/#step-2-create-the-html","text":"Create a file index.html Hello World
      This example uses Import Maps, which are used when not using a bundler like WebPack or Parcel. This can be a simpler and more clear debugging and development environment. The relative path in the importmap section should be updated to point to the location where you installed twr-wasm/lib-js . The path above is correct if your file is in an example subfolder. As another example, if you used git clone https://github.com/twiddlingbits/twr-wasm to create a folder named twr-wasm and you create your hello world project with a folder structure like this: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm Then you would use an Import Map code snippet like this: ","title":"Step 2: Create the HTML"},{"location":"gettingstarted/helloworld/#step-3-compile-your-c-code-to-create-your-wasm-file","text":"clang --target=wasm32 -nostdinc -nostdlib -isystem ../../include -c helloworld.c -o helloworld.o wasm-ld helloworld.o ../../lib-c/twr.a -o helloworld.wasm --no-entry --initial-memory=131072 --max-memory=131072 --export=hello The path to twr.a and to include may need to be updated to match your installation. The above path is correct if your code is in an example subfolder. Alternately, if you had the folder structure described in Step 2: my_project/ \u251c\u2500\u2500 twr-wasm/ \u2514\u2500\u2500 index.html \u2514\u2500\u2500 helloworld.c \u2514\u2500\u2500 helloworld.wasm \u2514\u2500\u2500 Makefile You could use a MakeFile like this: CC := clang TWRCFLAGS := --target=wasm32 -nostdinc -nostdlib -isystem twr-wasm/include CFLAGS := -c -Wall -O3 $(TWRCFLAGS) CFLAGS_DEBUG := -c -Wall -g -O0 $(TWRCFLAGS) .PHONY: default default: helloworld.wasm helloworld.o: helloworld.c $(CC) $(CFLAGS) $< -o $@ helloworld.wasm: helloworld.o wasm-ld helloworld.o twr-wasm/lib-c/twr.a -o helloworld.wasm \\ --no-entry --initial-memory=131072 --max-memory=131072 \\ --export=hello","title":"Step 3: Compile your C code to create your .wasm file"},{"location":"gettingstarted/helloworld/#step-4-load-your-web-page","text":"The two easiest ways to load and execute your index.html web page locally are:","title":"Step 4: Load your web page"},{"location":"gettingstarted/helloworld/#option-a-run-a-local-web-server","text":"You can run a local server to view your helloworld program. Copy the file server.py from the examples folder to your project folder where your index.html resides. Execute with the shell command python server.py .","title":"Option A: Run a local web Server"},{"location":"gettingstarted/helloworld/#option-b-vs-code-launchjson","text":"Alternately, you can launch chrome without a local web server. Add an entry similar to the following to your VS code project's .vscode\\launch.json . Adjust the file and cwd lines to be correct for your project. { \"name\": \"hello\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [ \"--allow-file-access-from-files\", \"--autoplay-policy=no-user-gesture-required\", \"--enable-features=SharedArrayBuffer\" ], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" } --autoplay-policy=no-user-gesture-required and --enable-features=SharedArrayBuffer are not required for this simple \"hello world\" example, but will be needed if you request user input or you are using twrWasModuleAsync.","title":"Option B: VS Code launch.json"},{"location":"gettingstarted/helloworld/#see-live-version","text":"Here is a link to the helloworld function running in the twiddlingbits.dev site.","title":"See live version"},{"location":"gettingstarted/helloworld/#next-steps-after-hello-world","text":"A good way to get your own code up and running is to copy one of the twr-wasm/examples , get it to build and run, then start modifying it. The example makefiles prove a more practical way to configure and execute clang and wasm-ld. \"Hello World\" uses the twr-wasm class twrWasmModule . If you wish to use C blocking functions, such as twr_getc32 or twr_sleep , you can use twrWasmModuleAsync . This square calculator example shows how to do this. If you wish to build an app that makes non-block calls into C, the balls example shows how to do this. The maze example uses a combination of blocking and non-blocking C functions.","title":"Next steps after hello world"},{"location":"gettingstarted/installation/","text":"Installing twr-wasm This section describes how to install twr-wasm on your computer so that you can compile and link C/C++ to Web Assembly (WASM). npm install twr-wasm or git clone https://github.com/twiddlingbits/twr-wasm npm install will install everything necessary to build your software: built libraries (lib-js, lib-c), include. In addition the examples are installed. git clone will copy the built libraries (lib-js, lib-c), include, as well as the source, examples, doc source and VS Code settings. Either will work, although with different pros and cons -- see the below notes. After installation, Using twr-wasm can be a bit more complicated than using a package that is all JavaScript because your applications need to use twr-wasm JavaScript and C libraries. Installs for your C/C++ code To build C/C++ code for use in your wasm project, you will need to install clang and the wasm-ld linker. If you are using Windows, more details can be found at the end of the Building Source section. A Note on npm install After installation from npm, you will have a folder structure like this: node_modules\\ twr-wasm\\ examples\\ include\\ lib-c\\ lib-js\\ LICENSE package.json readme.md The JavaScript and TypeScript exports are in lib-js and should be found by VS Code, TypeScript or your bundler as usual when using a statement like import {twrWasmModule} from \"twr-wasm\" . The C library ( twr.a ) that you will need to link your C/C++ program to is found in the libs-c folder, and the C/C++ include files that you will need to use in your C/C++ program are found in the include folder. You will need to use paths to to these folders in your make file . All of the examples (in the examples folder above) have make files that use a relative path for twr.a and includes . These paths will work fine if your code is in an examples sub-folder as a peer to the other examples. But assuming your code is in your own project folder elsewhere, you will need to determine the correct path to twr.a and includes from your project's make file. Details on how to do this can be found in the leter sections: Hello World walkthrough and the Compiler and Linker Options section . There is no real downside to this installation method, except possibly: (1) it does not include source code (use git clone for that), and (b) the C libraries are buried inside your node_modules. A Note on git clone install This method of installation installs the complete code base, including source and build binaries. The primary downside to this method is that the JavaScript side of twr-wasm will not be placed in a node_modules folder. This will likely make it difficult for a bundler, TypeScript or VS Code to find the location of imports. There are a few solutions to this. In the provided hello world example, I use a package.json file with an alias entry. This syntax is supported by the Parcel bundler: { \"@parcel/resolver-default\": { \"packageExports\": true }, \"alias\": { \"twr-wasm\": \"../../lib-js/index.js\" }, \"dependencies\": { \"twr-wasm\": \"^2.0.0\" } } In the FFT example, I use the paths entry in the tsconfig.json file. This is found by TypeScript, VS Code and the Parcel bundler. \"paths\": { \"twr-wasm\": [\"./../../lib-js/index\"] } The paths for alias and paths shown above are correct for the included examples, but will likely need to be adjust for your project (see the following section \"Your First C Web Assembly Program\" ) As a alternative, you could install with both npm and git .","title":"Installation"},{"location":"gettingstarted/keyconcepts/","text":"Key Concepts - C/C++ WASM This section describes some key concepts that apply when using twr-wasm with your C/C++ Web Assembly code. Overview Your C/C++ Web Assembly 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 Web Assembly module by your JavaScript or HTML. 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. On the JavaScript side you will use the twr-wasm JavaScript/TypeScript class twrWasmModule or twrWasmModuleAsync to load the .wasm module, and then call C functions in it (more details are in the TypeScript/Javascript API section ). 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
      or 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 parameters. The C/C++ code could then generate no output, could render to a
      or using stdio type C/C++ functions, or it could render to a 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
      or to your HTML ( see stdio ) Use new twrWasmModule() , followed by a call to loadWasm() , then one or more callC() . Alternately, use twrWasmModuleAsync() -- which is interchangeable with twrWasmModule, but proxies through a worker thread, and adds blocking support, including blocking char input. Passing strings, arrayBuffers, etc The Web Assembly runtime provided in a browser will only pass numbers between C functions and JavaScript functions. This means if you use twrWasmModule.callC to call a C function, and pass integers or floats as arguments, they will work as expected. But if you pass a string, arrayBuffer, or the contents or a URL, twrWasmModule.callC will: allocate memory in your WebAssembly.Memory (using malloc). copy the string (or arrayBuffer or URL contents) into this memory. pass the memory index (aka a pointer in C land) to your C code. If URL contents are passed, your C function will receive a pointer to the data as the first argument, and a length as the second argument. If an arrayBuffer is passed to your C/C++ code, you probably will also need to pass in the length (unless it is already known). Upon return, the malloced memory is freed, and if the argument was an arrayBuffer, the appropriate contents in the wasm module memory are copied back into the arrayBuffer. This means that if your C code modifies a passed in block of arrayBuffer memory, the results will be reflected back into javaScript land. Some module functions (such as getString ) take or return an \"index:number\". Here index means an index into WebAssembly.Memory. As far as your C code is concerned, this is a pointer. Recalled that an arrayBuffer can be created and accessed using classes like Uint8Array or Float32Array . It is helpful to look at the examples .","title":"Key Concepts"},{"location":"gettingstarted/stdio/","text":"Stdio with C/C++ Web Assembly This section describes how you can direct C/C++ standard input or output to or from a div or canvas tag in a twr-wasm C/C++ wasm project. Use div or canvas tag Standard input and output can be directed to a
      or to a HTML tag. A
      is used for streamed character input and output, and a is used for sending characters or simple graphics to windowed input and output. In the windowed mode, the position of characters in a \"terminal\" style window can be specified. In windowed mode, you can use functions that output to stdout or input from stdin, as well as functions that use x,y coordinates, colors, etc.
      will be used for stdin and stdout if found. will be used for stdin and stdout if it exists and no div found. if neither of the above
      or is defined in your HTML, then stdout is sent to the debug console in your browser. And stdin is not available. If you use twrWasmModule options, a fourth null options is available. Unicode characters and symbols are supported in stdout and stdin and windowed i/o (see localization ). The window console also supports chunky (low res) graphics (each character cell can be used as a 2x3 graphic array). stderr streams to the browser's debug console. Examples Name View Live Link Source Link stdin and stdout to
      View square demo Source simple \"terminal\" via View hello world demo Source \"cli\" with a stdio View CLI demo using libc++ Source IO Console Docs stdin , stdout , and stderr are abstracted by a twr-wasm IO Consoles . UTF-8 or Windows-1252 Stdin and stdout can support UTF-8 or Windows-1252 character encodings (see localization ) stdout or stderr #include to access stdout , stdin , stderr , and FILE . FILE is supported for user input and output, and for stderr. File i/o (to a filesystem) is not currently supported. You can use these functions to output to the standard library defines stderr or stdout : fputc, putc, vfprintf, fprintf, fwrite You can use the IO Console functions referenced above to send to stdout and stderr . These functions go to stdout: printf, vprintf, puts, putchar Note that when characters are sent to the browser console using stderr they will not render to the console until a newline, return, or ASCII 03 (End-of-Text) is sent. For example: #include fprintf(stderr, \"hello over there in browser debug console land\\n\"); A more common method to send output to the debug console is to use twr_conlog . See General C API Section . stdin You can get characters from the standard C define stdin with these functions: io_mbgets - get a multibyte string from a console using the current locale character encoding twr_mbgets - similar to io_mbgets , except always gets a multibyte locale format string from stdin. io_mbgetc - get a multibyte character from an IoConsole (like stdin ) using the current locale character encoding getc (sames as fgetc ) - get a single byte from a FILE * (IoConsole) -- returning ASCII or extended ASCII (window-1252 encoding) io_getc32 - gets a 32 bit unicode code point from an IoConsole (which currently needs to be stdin) Reading from stdin is blocking, and so twrWasmModuleAsync must be used to receive keys from stdin. JavaScript needed for char input You should add a line like the following to your JavaScript for stdin to work: for twr_iodiv document.getElementById(\"twr_iodiv\").addEventListener(\"keydown\",(ev)=>{amod.keyDownDiv(ev)}); for twr_iocanvas document.getElementById(\"twr_iocanvas\").addEventListener(\"keydown\",(ev)=>{amod.keyDownCanvas(ev)}); You likely want a line like this to set the focus to the div or canvas so the user doesn't have to click on it: document.getElementById(\"twr_iocanvas\").focus(); You will also need to set the tabindex attribute in your div tag like this:
      See the stdio-div and stdio-canvas examples. Note that this section describes blocking input using stdin. As an alternative, you can send events (keyboard, mouse, timer, etc) to a non-blocking C function from JavaScript using callC . See the balls example.","title":"Stdio"},{"location":"more/building/","text":"Building the Source Source for twr-wasm The source can be found at: https://github.com/twiddlingbits/twr-wasm The main branch contains the latest release. The dev branch is work in progress. Tools needed You will need these core tools: NPM - package manager Typescript clang tool chain - for C/C++ code wasm-ld - to link the .wasm files wat2wasm - to compile web assembly (.wat) files of which I have a few GNU make git - to clone twr-wasm source, or to clone llvm, if you want to build libc++ In addition, you might need: VS Code - to use the debug launcher and build tasks Parcel v2 - to bundle the examples mkdocs - to build the documentation static web site python - mkdocs is built with python, and you need python to run server.py in examples CMake and ninja - to build llvm libc++ There is a deprecated gcc build that I used to use for testing, but now the tests are executed in wasm. To Build the Libraries (lib-c, lib-js) cd source make or on windows cd source mingw32-make To Build the Examples See examples/readme.md for more information. To build the examples, but not bundle them. cd examples sh buildall.sh To build bundles: sh buildbundles.sh To Build the docs In twr-wasm root folder: mkdocs build The destination of the build is found in the mkdocs.yml file ( site_dir: azure/docsite/ ). Usually the docs are built as part of building the static web site that hosts the docs and examples. This is accomplished using this shell script (found in examples folder): buildazure.sh To Build libc++ for wasm and twr-wasm See the instructions in the comments in the shell script source\\libcxx\\buildlibcxx.sh Installing clang and wasm-ld on Windows Here is how I installed the tools for windows: install MSYS2 1. https://www.msys2.org/ 2. After the install completes, run UCRT64 terminal by clicking on the MSYS2 UCRT64 in the Start menu 3. pacman -Syuu install gcc using MSYS2 UCRT64 1. Use MSYS2 UCRT64 terminal (per above) 1. pacman -S mingw-w64-ucrt-x86_64-toolchain install clang and wasm-ld using MSYS2 UCRT64 2. Use MSYS2 UCRT64 (per above) 1. pacman -S mingw-w64-ucrt-x86_64-clang 2. pacman -S mingw-w64-x86_64-lld update PATH env variable using the windows control panel (search for path) 2. added C:\\msys64\\ucrt64\\bin 3. added C:\\msys64\\mingw64\\bin 4. added C:\\msys64\\usr\\bin (for sh.exe used by mingw32-make) wabt tools: can be found here https://github.com/WebAssembly/wabt/releases","title":"Building the Source"},{"location":"more/debugging/","text":"Debugging Web Assembly This section describes some tips for debugging your Web Assembly (asm) program. Debug and Release libraries There are release (twr.a) and debug (twrd.a) versions of the twr-wasm C library. See the examples for use of both. The \"debug\" version has debug symbols enabled and is built with -O0 . The \"release\" version has no debug symbols and optimization is set to -O3 . Both have asserts enabled. In general, you should use the \"release\" version unless you wish to step through the twr-wasm source -- in which case use the \"debug\" version. libc++.a is not built with debug symbols. Source Level Debugging Web Assembly C/C++ In order to enable C/C++ source debugging with wasm and clang, do the following: Use Chrome Install the Chrome extension: C/C++ DevTools Support (DWARF) ( https://chromewebstore.google.com/detail/pdcpmagijalfljmkmjngeonclgbbannb ) Use the clang compile flag -g to add debug annotation to your object files You will may want to turn off optimization to allow the debugger to have a bit more logical behavior (remove the -O flag or set to -O0) You may want to use the version of the twr-wasm C library that has debug symbols enabled (twrd.a). Only if you want to step into the twrd.a source. You need to serve your files with a (likely local) web server. For example, 'python server.py' is provided. 'server.py' can be found in the examples root folder. Note that your local server needs to enable SharedArrayBuffers -- see the server.py example. your code can be bundled or unbundled, but you need to ensure that the web server/browser can find the source code also see Example Readme Useful twr-wasm Debug Functions Use twr_conlog to print 'printf' style to the JavaScript console from C (reference is elsewhere in this doc.) #include \"twr-wasm.h\" twr_conlog(\"hello 99 in hex: %x\",99); Use twrWasmModule.divLog() to print to a div inside JavaScript code (reference is elsewhere in this doc.) Testing Web Assembly Without a Web Server Note: If you use this technique, you will not be able to get the c/C++ DevTool chrome extension to run, and so source level debugging won't work. You can execute and debug JavaScript with wasm from local files without an HTTP server. It might be helpful to download the twr-wasm source code from github when you do this (so you can step through the twr-wasm typescript code as needed). See the examples and Example Readme for more detail on how this works. In general, you will need to add a clip of code similar to this to your HTML: Make sure the paths are correct. You will need to set the following flags when running chrome from the shell (the first is only strictly required if using twrWasmModuleAsync): --enable-features=SharedArrayBuffer --allow-file-access-from-files You can create a launch.json entry similar to this: { \"name\": \"Examples\", \"type\": \"chrome\", \"request\": \"launch\", \"runtimeArgs\": [\"--allow-file-access-from-files\",\"--autoplay-policy=no-user-gesture-required\",\"--enable-features=SharedArrayBuffer\"], \"file\": \"${workspaceFolder}/examples/index.html\", \"cwd\": \"${workspaceFolder}/examples/\" }","title":"Debugging WASM"},{"location":"more/production/","text":"Production Important Production Note twr-wasm class twrWasmModuleAsync uses SharedArrayBuffers, and there are special CORS headers needed for these, that are not widely enabled by default on web servers. server.py or staticwebapp.config.json shows which headers to set (also see the SharedArrayBuffer documentation online).","title":"Production"},{"location":"more/wasm-problem/","text":"WASM Runtime Limitations HTML browsers can load a Web Assembly module, and execute it's bytecode in a browser virtual machine. You compile your code using clang with the target code format being web assembly (wasm) byte code. There are a few issues that one immediately encounters trying to execute code that is more complicated than squaring a number. The first is that there is no C/C++ runtime support native to a Web Assembly module. That is, no malloc or printf or similar functions. Even beyond than that, there are missing compiler support functions. That is, clang code generation will produce calls for compiler support routines needed for floating point, memcpy, and the like. This code is usually handled behind the scenes for you. For example, gcc will link to \"libgcc\" automatically. clang uses \"compile-rt\". This doesn't happen with Web Assembly compiles (unless you use emscripten or twr-wasm). The second problem is that all the function calls between your wasm module and your javascript are limited to parameters and return values that are numbers (integer and float). No strings, arrays, struct pointers, etc. The third problem is that legacy C code or games often block, and when written this way they don't naturally integrate with the JavaScript asynchronous programming model. twr-wasm is a static C library (twr.a) that you can link to your clang C/C++ code, as well as a set of JavaScript/Typescript modules that solve these issues.","title":"WASM Runtime Limitations"}]} \ No newline at end of file diff --git a/azure/docsite/sitemap.xml b/azure/docsite/sitemap.xml index e52422fe..21279296 100644 --- a/azure/docsite/sitemap.xml +++ b/azure/docsite/sitemap.xml @@ -2,132 +2,132 @@ https://twiddlingbits.dev/docsite/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-c-con/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-c-d2d/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-c-general/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-c-stdlib/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-libc%2B%2B/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-localization/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/api/api-typescript/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-balls/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-fft/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-helloworld/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-libcxx/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-maze/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-more/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-overview/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-stdio-canvas/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/examples/examples-stdio-div/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/gettingstarted/compiler-opts/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/gettingstarted/helloworld/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/gettingstarted/installation/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/gettingstarted/keyconcepts/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/gettingstarted/stdio/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/more/building/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/more/debugging/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/more/production/ - 2024-06-19 + 2024-06-20 daily https://twiddlingbits.dev/docsite/more/wasm-problem/ - 2024-06-19 + 2024-06-20 daily \ No newline at end of file diff --git a/azure/docsite/sitemap.xml.gz b/azure/docsite/sitemap.xml.gz index 888c0346..d1f027e9 100644 Binary files a/azure/docsite/sitemap.xml.gz and b/azure/docsite/sitemap.xml.gz differ diff --git a/azure/examples/balls/balls-a.wasm b/azure/examples/balls/balls-a.wasm index 9fec7d4a..eafb34c4 100644 Binary files a/azure/examples/balls/balls-a.wasm and b/azure/examples/balls/balls-a.wasm differ diff --git a/azure/examples/balls/balls-dbg.wasm b/azure/examples/balls/balls-dbg.wasm index 6342df10..475c4835 100644 Binary files a/azure/examples/balls/balls-dbg.wasm and b/azure/examples/balls/balls-dbg.wasm differ diff --git a/azure/examples/balls/balls.wasm b/azure/examples/balls/balls.wasm index 08c732ef..d7ea0e12 100644 Binary files a/azure/examples/balls/balls.wasm and b/azure/examples/balls/balls.wasm differ diff --git a/azure/examples/dist/balls/balls-a.wasm b/azure/examples/dist/balls/balls-a.wasm index 9fec7d4a..eafb34c4 100644 Binary files a/azure/examples/dist/balls/balls-a.wasm and b/azure/examples/dist/balls/balls-a.wasm differ diff --git a/azure/examples/dist/balls/balls-dbg.wasm b/azure/examples/dist/balls/balls-dbg.wasm index 6342df10..475c4835 100644 Binary files a/azure/examples/dist/balls/balls-dbg.wasm and b/azure/examples/dist/balls/balls-dbg.wasm differ diff --git a/azure/examples/dist/balls/balls.wasm b/azure/examples/dist/balls/balls.wasm index 08c732ef..d7ea0e12 100644 Binary files a/azure/examples/dist/balls/balls.wasm and b/azure/examples/dist/balls/balls.wasm differ diff --git a/azure/examples/dist/balls/index.html b/azure/examples/dist/balls/index.html index e03d18d2..4e2f78e8 100644 --- a/azure/examples/dist/balls/index.html +++ b/azure/examples/dist/balls/index.html @@ -4,4 +4,4 @@ "twr-wasm": "../../lib-js/index.js" } } -

      Bouncing Balls Demo

      Web Assembly with twr-wasm


      \ No newline at end of file +

      Bouncing Balls Demo

      Web Assembly with twr-wasm


      \ No newline at end of file diff --git a/azure/examples/dist/fft/index.html b/azure/examples/dist/fft/index.html index 1ac4bea7..62e764c1 100644 --- a/azure/examples/dist/fft/index.html +++ b/azure/examples/dist/fft/index.html @@ -1,4 +1,4 @@ -Fast Fourier transform (FFT)Maze Maze stdio-canvas example stdio-canvas example Interactive User Tests Interactive User Tests Tests
      Tests