The JavaScript APIs in preamble.js provide programmatic access for interacting with the compiled C code, including: calling compiled C functions, accessing memory, converting pointers to JavaScript Strings and Strings to pointers (with different encodings/formats), and other convenience functions.
Note
All functions should be called though the Module object (for example: Module.functionName). At optimisation -O2 (and higher) function names are minified by the closure compiler, and calling them directly will fail.
Table of Contents
Call a compiled C function from JavaScript.
The function executes a compiled C function from JavaScript and returns the result. C++ name mangling means that “normal” C++ functions cannot be called; the function must either be defined in a .c file or be a C++ function defined with extern "C".
// Call C from JavaScript
var result = Module.ccall('c_add', // name of C function
'number', // return type
['number', 'number'], // argument types
[10, 20]); // arguments
// result is 30
Note
ccall uses the C stack for temporary values. If you pass a string then it is only “alive” until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data.
If you need a string to live forever, you can create it, for example, using _malloc and writeStringToMemory(). However, you must later delete it manually!
LLVM optimizations can inline and remove functions, after which you will not be able to call them. Similarly, function names minified by the Closure Compiler are inaccessible. In either case, the solution is to add the functions to the EXPORTED_FUNCTIONS list when you invoke emcc :
-s EXPORTED_FUNCTIONS="['_main', '_myfunc']"Exported functions can be called as normal:
a_result = Module.ccall('myfunc', 'number', ['number'], 10)
Arguments: |
|
---|
Note
64-bit integers become two 32-bit parameters, for the low and high bits (since 64-bit integers cannot be represented in JavaScript numbers).
Arguments: |
|
---|---|
Returns: | The result of the function call as a native JavaScript value (as in returnType). |
Opts: | An optional options object. It can contain the following properties:
|
Returns a native JavaScript wrapper for a C function.
This is similar to ccall(), but returns a JavaScript function that can be reused as many time as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using extern "C" (to prevent name mangling).
// Call C from JavaScript
var c_javascript_add = Module.cwrap('c_add', // name of C function
'number', // return type
['number', 'number']); // argument types
// Call c_javascript_add normally
console.log(c_javascript_add(10, 20)); // 30
console.log(c_javascript_add(20, 30)); // 50
Note
cwrap uses the C stack for temporary values. If you pass a string then it is only “alive” until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data.
If you need a string to live forever, you can create it, for example, using _malloc and writeStringToMemory(). However, you must later delete it manually!
LLVM optimizations can inline and remove functions, after which you will not be able to “wrap” them. Similarly, function names minified by the Closure Compiler are inaccessible. In either case, the solution is to add the functions to the EXPORTED_FUNCTIONS list when you invoke emcc :
-s EXPORTED_FUNCTIONS="['_main', '_myfunc']"Exported functions can be called as normal:
my_func = Module.cwrap('myfunc', 'number', ['number']) my_func(12)
Arguments: |
|
---|---|
Returns: | A JavaScript function that can be used for running the C function. |
Sets a value at a specific memory address at run-time.
Note
Arguments: |
|
---|
Gets a value at a specific memory address at run-time.
Note
Arguments: |
|
---|---|
Returns: | The value stored at the specified memory address. |
Returns a JavaScript String from a pointer, for use in compiled code.
Arguments: |
|
---|---|
Returns: | A JavaScript String containing the data from ptr. |
Return type: | String |
Given a pointer ptr to a null-terminated UTF16LE-encoded string in the Emscripten HEAP, returns a copy of that string as a Javascript String object.
Arguments: |
|
---|---|
Returns: | A Javascript String object |
Copies the given JavaScript String object str to the Emscripten HEAP at address outPtr, null-terminated and encoded in UTF16LE form.
The copy will require at most (str.length*2+1)*2 bytes of space in the HEAP.
Arguments: |
|
---|
Given a pointer ptr to a null-terminated UTF32LE-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript String object.
Arguments: |
|
---|---|
Returns: | A Javascript String object. |
Copies the given JavaScript String object str to the Emscripten HEAP at address outPtr, null-terminated and encoded in UTF32LE form.
The copy will require at most (str.length+1)*4 bytes of space in the HEAP, but can use less, since str.length does not return the number of characters in the string, but the number of UTF-16 code units in the string.
Arguments: |
|
---|
This converts a JavaScript string into a C-line array of numbers, 0-terminated.
Arguments: |
|
---|---|
Returns: | The array created from stringy. |
This creates a JavaScript string from a zero-terminated C-line array of numbers.
Arguments: |
|
---|---|
Returns: | A String, containing the content of array. |
Writes a JavaScript string to a specified address in the heap.
// Allocate space for string and extra '0' at the end
var buffer = Module._malloc(myString.length+1);
// Write the string to memory
Module.writeStringToMemory(myString, buffer);
// We can now send buffer into a C function, it is just a normal char* pointer
Arguments: |
|
---|
Writes an array to a specified address in the heap. Note that memory should to be allocated for the array before it is written.
Arguments: |
|
---|
Writes an ASCII string to a specified address in the heap. Note that memory should to be allocated for the string before it is written.
The string is assumed to only have characters in the ASCII character set. If ASSERTIONS are enabled and this is not the case, it will fail.
// Allocate space for string
var buffer = Module._malloc(myString.length);
// Write the string to memory
Module.writeStringToMemory(myString, buffer);
Arguments: |
|
---|
Note that generally run dependencies are managed by the file packager and other parts of the system. It is rare for developers to use this API directly.
Adds an id to the list of run dependencies.
This adds a run dependency and increments the run dependency counter.
Arguments: |
|
---|
Removes a specified id from the list of run dependencies.
Arguments: |
|
---|
Returns the current stack track.
Note
The stack trace is not available at least on IE10 and Safari 6.
Returns: | The current stack trace, if available. |
---|
The Emscripten memory representation uses a typed array buffer (ArrayBuffer) to represent memory, with different views into it giving access to the different types. The views for accessing different types of memory are listed below.
View for 8-bit signed memory.
View for 16-bit signed memory.
View for 32-bit signed memory.
View for 32-bit unsigned memory.
View for 32-bit unsigned memory.
View for 16-bit unsigned memory.
View for 32-bit unsigned memory.
View for 32-bit float memory.
View for 64-bit float memory.