This page documents the public C++ APIs provided by emscripten.h.
Emscripten uses existing/familiar APIs where possible (for example: SDL). This API provides C++ support for capabilities that are specific to JavaScript or the browser environment, or for which there is no existing API.
Table of Contents
Guide material for the following APIs can be found in Calling JavaScript from C/C++.
Convenient syntax for inline assembly/JavaScript.
This allows you to declare JavaScript in your C code “inline”, which is then executed when your compiled code is run in the browser. For example, the following C code would display two alerts if it was compiled with Emscripten and run in the browser:
EM_ASM( alert(‘hai’));
alert(‘bai’)); )
Note
Input-output versions of EM_ASM.
EM_ASM_ (an extra “_” is added) or EM_ASM_ARGS allow values (int or double) to be sent into the code.
If you also want a return value, EM_ASM_INT receives arguments (of int or double type) and returns an int; EM_ASM_DOUBLE does the same and returns a double.
Arguments arrive as $0, $1 etc. The output value should be returned:
int x = EM_ASM_INT({
console.log('I received: ' + [$0, $1]);
return $0 + $1;
}, calc(), otherCalc());
Note the { and }.
If you just want to receive an output value (int or double) but not pass any values, you can use EM_ASM_INT_V or EM_ASM_DOUBLE_V, respectively.
Guide material for the following APIs can be found in Calling JavaScript from C/C++.
The following types are used to define function callback signatures used in a number of functions in this file.
General function pointer type for use in callbacks with no parameters.
Defined as:
typedef void (*em_callback_func)(void)
Generic function pointer type for use in callbacks with a single void* parameter.
This type is used to define function callbacks that need to pass arbitrary data. For example, emscripten_set_main_loop_arg() sets user-defined data, and passes it to a callback of this type on completion.
Defined as:
typedef void (*em_arg_callback_func)(void*)
General function pointer type for use in callbacks with a C string (const char *) parameter.
This type is used for function callbacks that need to be passed a C string. For example, it is used in emscripten_async_wget() to pass the name of a file that has been asynchronously loaded.
Defined as:
typedef void (*em_str_callback_func)(const char *)
Interface to the underlying JavaScript engine. This function will eval() the given script.
| Parameters: |
|
|---|---|
| Return type: | void |
Interface to the underlying JavaScript engine. This function will eval() the given script.
| Parameters: |
|
|---|---|
| Returns: | The result of the evaluation, as an integer. |
| Return type: | int |
Interface to the underlying JavaScript engine. This function will eval() the given script. Note that this overload uses a single buffer shared between calls.
| Parameters: |
|
|---|---|
| Returns: | The result of the evaluation, as a string. |
| Return type: | char* |
Asynchronously run a script, after a specified amount of time.
| Parameters: |
|
|---|---|
| Return type: | void |
Asynchronously loads a script from a URL.
This integrates with the run dependencies system, so your script can call addRunDependency multiple times, prepare various asynchronous tasks, and call removeRunDependency on them; when all are complete (or if there were no run dependencies to begin with), onload is called. An example use for this is to load an asset module, that is, the output of the file packager.
| Parameters: |
|
|---|---|
| Return type: | void |
Guide material for the following APIs can be found in Emscripten Runtime Environment.
Set a C function as the main event loop.
If the main loop function needs to receive user-defined data, use emscripten_set_main_loop_arg() instead.
The JavaScript environment will call that function at a specified number of frames per second. Setting 0 or a negative value as the fps will instead use the browser’s requestAnimationFrame mechanism to call the main loop function. This is HIGHLY recommended if you are doing rendering, as the browser’s requestAnimationFrame will make sure you render at a proper smooth rate that lines up properly with the the browser and monitor. If you do not render at all in your application, then you should pick a specific frame rate that makes sense for your code.
If simulate_infinite_loop is true, the function will throw an exception in order to stop execution of the caller. This will lead to the main loop being entered instead of code after the call to emscripten_set_main_loop() being run, which is the closest we can get to simulating an infinite loop (we do something similar in glutMainLoop in GLUT). If this parameter is false, then the behavior is the same as it was before this parameter was added to the API, which is that execution continues normally. Note that in both cases we do not run global destructors, atexit, etc., since we know the main loop will still be running, but if we do not simulate an infinite loop then the stack will be unwound. That means that if simulate_infinite_loop is false, and you created an object on the stack, it will be cleaned up before the main loop is called for the first time.
Tip
There can be only one main loop function at a time. To change the main loop function, first cancel the current loop, and then call this function to set another.
Note
See emscripten_set_main_loop_expected_blockers(), emscripten_pause_main_loop(), emscripten_resume_main_loop() and emscripten_cancel_main_loop() for information about blocking, pausing, and resuming the main loop.
Note
Calling this function overrides the effect of any previous calls to emscripten_set_main_loop_timing() by applying the timing mode specified by the parameter fps. To specify a different timing mode, call the function emscripten_set_main_loop_timing() after setting up the main loop.
| Parameters: |
|
|---|
Set a C function as the main event loop, passing it user-defined data.
See also
The information in emscripten_set_main_loop() also applies to this function.
| Parameters: |
|
|---|
Add a function that blocks the main loop.
The function is added to the back of a queue of events to be blocked; the main loop will not run until all blockers in the queue complete.
In the “counted” version, blockers are counted (internally) and Module.setStatus is called with some text to report progress (setStatus is a general hook that a program can define in order to show processing updates).
Note
| Parameters: |
|
|---|---|
| Return type: | void |
Pause and resume the main loop.
Pausing and resuming the main loop is useful if your app needs to perform some synchronous operation, for example to load a file from the network. It might be wrong to run the main loop before that finishes (the original code assumes that), so you can break the code up into asynchronous callbacks, but you must pause the main loop until they complete.
Note
These are fairly low-level functions. emscripten_push_main_loop_blocker() (and friends) provide more convenient alternatives.
Cancels the main event loop.
See also emscripten_set_main_loop() and emscripten_set_main_loop_arg() for information about setting and using the main loop.
Specifies the scheduling mode that the current main loop tick function will be called with.
This function can be used to interactively control the rate at which Emscripten runtime drives the main loop specified by calling the function emscripten_set_main_loop(). In native development, this corresponds with the “swap interval” or the “presentation interval” for 3D rendering. The new tick interval specified by this function takes effect immediately on the existing main loop, and this function must be called only after setting up a main loop via emscripten_set_main_loop().
| Parameters: |
|
||||||||
|---|---|---|---|---|---|---|---|---|---|
Returns the current main loop timing mode that is in effect. For interpretation of the values, see the documentation of the function emscripten_set_main_loop_timing(). The timing mode is controlled by calling the functions emscripten_set_main_loop_timing() and emscripten_set_main_loop().
| Parameters: |
|
|---|
Sets the number of blockers that are about to be pushed.
The number is used for reporting the relative progress through a set of blockers, after which the main loop will continue.
For example, a game might have to run 10 blockers before starting a new level. The operation would first set this value as ‘10’ and then push the 10 blockers. When the 3rd blocker (say) completes, progress is displayed as 3/10.
| Parameters: |
|
|---|
Call a C function asynchronously, that is, after returning control to the JavaScript event loop.
This is done by a setTimeout.
When building natively this becomes a simple direct call, after SDL_Delay (you must include SDL.h for that).
If millis is negative, the browser’s requestAnimationFrame mechanism is used.
| Parameters: |
|
|---|
Exits the program immediately, but leaves the runtime alive so that you can continue to run code later (so global destructors etc., are not run). Note that the runtime is kept alive automatically when you do an asynchronous operation like emscripten_async_call(), so you don’t need to call this function for those cases.
Shuts down the runtime and exits (terminates) the program, as if you called exit().
The difference is that emscripten_force_exit will shut down the runtime even if you previously called emscripten_exit_with_live_runtime() or otherwise kept the runtime alive. In other words, this method gives you the option to completely shut down the runtime after it was kept alive beyond the completion of main().
| Parameters: |
|
|---|
Returns the value of window.devicePixelRatio.
| Return type: | double |
|---|---|
| Returns: | The pixel ratio or 1.0 if not supported. |
Resizes the pixel width and height of the <canvas> element on the Emscripten web page.
| Parameters: |
|
|---|
Gets the current pixel width and height of the <canvas> element as well as whether the canvas is fullscreen or not.
| Parameters: |
|
|---|
Returns the highest-precision representation of the current time that the browser provides.
This uses either Date.now or performance.now. The result is not an absolute time, and is only meaningful in comparison to other calls to this function.
| Return type: | double |
|---|---|
| Returns: | The current time, in milliseconds (ms). |
Generates a random number in the range 0-1. This maps to Math.random().
| Return type: | float |
|---|---|
| Returns: | A random number. |
Function pointer type for the onload callback of emscripten_async_wget_data() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget_onload_func)(void*, void*, int)
Function pointer type for the onload callback of emscripten_async_wget2() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget2_onload_func)(void*, const char*)
Function pointer type for the onerror and onprogress callbacks of emscripten_async_wget2() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget2_onstatus_func)(void*, int)
Function pointer type for the onload callback of emscripten_async_wget2_data() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget2_data_onload_func)(void*, void *, unsigned*)
Function pointer type for the onerror callback of emscripten_async_wget2_data() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget2_data_onerror_func)(void*, int, const char*)
Function pointer type for the onprogress callback of emscripten_async_wget2_data() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_wget2_data_onprogress_func)(void*, int, int)
Function pointer type for the onload callback of emscripten_async_prepare_data() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_async_prepare_data_onload_func)(void*, const char*)
Load file from url in synchronously. For the asynchronous version, see the emscripten_async_wget().
In addition to fetching the URL from the network, the contents are prepared so that the data is usable in IMG_Load and so forth (we synchronously do the work to make the browser decode the image or audio etc.).
This function is blocking; it won’t return until all operations are finished. You can then open and read the file if it succeeded.
To use this function, you will need to compile your application with the linker flag -s ASYNCIFY=1
| Parameters: |
|
|---|
Loads a file from a URL asynchronously.
In addition to fetching the URL from the network, the contents are prepared so that the data is usable in IMG_Load and so forth (we asynchronously do the work to make the browser decode the image or audio etc.).
When the file is ready the onload callback will be called. If any error occurs onerror will be called. The callbacks are called with the file as their argument.
| Parameters: |
|
|---|
Loads a buffer from a URL asynchronously.
This is the “data” version of emscripten_async_wget().
Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot do the ‘prepare’ stage to set things up for IMG_Load and so forth (IMG_Load etc. work on files).
When the file is ready then the onload callback will be called. If any error occurred onerror will be called.
| Parameters: |
|
|---|
Loads a file from a URL asynchronously.
This is an experimental “more feature-complete” version of emscripten_async_wget().
In addition to fetching the URL from the network, the contents are prepared so that the data is usable in IMG_Load and so forth (we asynchronously do the work to make the browser decode the image, audio, etc.).
When the file is ready the onload callback will be called with the object pointers given in arg and file. During the download the onprogress callback is called.
| Parameters: |
|
|---|---|
| Returns: | A handle to request (int) that can be used to abort the request. |
Loads a buffer from a URL asynchronously.
This is the “data” version of emscripten_async_wget2(). It is an experimental “more feature complete” version of emscripten_async_wget_data().
Instead of writing to a file, this function writes to a buffer directly in memory. This avoids the overhead of using the emulated file system; note however that since files are not used, it cannot do the ‘prepare’ stage to set things up for IMG_Load and so forth (IMG_Load etc. work on files).
In addition to fetching the URL from the network, the contents are prepared so that the data is usable in IMG_Load and so forth (we asynchronously do the work to make the browser decode the image or audio etc.).
When the file is ready the onload callback will be called with the object pointers given in arg, a pointer to the buffer in memory, and an unsigned integer containing the size of the buffer. During the download the onprogress callback is called with progress information. If an error occurs, onerror will be called with the HTTP status code and a string containing the status description.
| Parameters: |
|
|---|---|
| Returns: | A handle to request (int) that can be used to abort the request. |
Abort an asynchronous request raised using emscripten_async_wget2() or emscripten_async_wget2_data().
| Parameters: |
|
|---|
Prepares a buffer of data asynchronously. This is a “data” version of emscripten_async_prepare(), which receives raw data as input instead of a filename (this can prevent the need to write data to a file first).
When file is loaded then the onload callback will be called. If any error occurs onerror will be called.
onload also receives a second parameter, which is a ‘fake’ filename which you can pass into IMG_Load (it is not an actual file, but it identifies this image for IMG_Load to be able to process it). Note that the user of this API is responsible for free() ing the memory allocated for the fake filename.
| Parameters: |
|
|---|
IndexedDB is a browser API that lets you store data persistently, that is, you can save data there and load it later when the user re-visits the web page. IDBFS provides one way to use IndexedDB, through the Emscripten filesystem layer. The emscripten_idb_* methods listed here provide an alternative API, directly to IndexedDB, thereby avoiding the overhead of the filesystem layer.
Loads data from local IndexedDB storage asynchronously. This allows use of persistent data, without the overhead of the filesystem layer.
When the data is ready then the onload callback will be called. If any error occurred onerror will be called.
| Parameters: |
|
|---|
Stores data to local IndexedDB storage asynchronously. This allows use of persistent data, without the overhead of the filesystem layer.
When the data has been stored then the onstore callback will be called. If any error occurred onerror will be called.
| Parameters: |
|
|---|
Deletes data from local IndexedDB storage asynchronously.
When the data has been deleted then the ondelete callback will be called. If any error occurred onerror will be called.
| Parameters: |
|
|---|
Checks if data with a certain ID exists in the local IndexedDB storage asynchronously.
When the data has been checked then the oncheck callback will be called. If any error occurred onerror will be called.
| Parameters: |
|
|---|
Prepares a file asynchronously.
This does just the preparation part of emscripten_async_wget(). That is, it works on file data already present and performs any required asynchronous operations (for example, decoding images for use in IMG_Load, decoding audio for use in Mix_LoadWAV, etc.).
Once the operations are complete (the file is prepared), the onload callback will be called. If any error occurs onerror will be called. The callbacks are called with the file as their argument.
| Parameters: |
|
|---|---|
| Returns: | 0 if successful, -1 if the file does not exist |
| Return type: | int |
Forces LLVM to not dead-code-eliminate a function.
This also exports the function, as if you added it to EXPORTED_FUNCTIONS.
For example:
void EMSCRIPTEN_KEEPALIVE my_function() { printf("I am being kept alive\n"); }
A wrapper around web workers that lets you create workers and communicate with them.
Note that the current API is mainly focused on a main thread that sends jobs to workers and waits for responses, i.e., in an asymmetrical manner, there is no current API to send a message without being asked for it from a worker to the main thread.
Function pointer type for the callback from emscripten_call_worker() (specific values of the parameters documented in that method).
Defined as:
typedef void (*em_worker_callback_func)(char*, int, void*)
Creates a worker.
A worker must be compiled separately from the main program, and with the BUILD_AS_WORKER flag set to 1.
| Parameters: |
|
|---|---|
| Returns: | A handle to the newly created worker. |
| Return type: | worker_handle |
Destroys a worker. See emscripten_create_worker()
| Parameters: |
|
|---|
Asynchronously calls a worker.
The worker function will be called with two parameters: a data pointer, and a size. The data block defined by the pointer and size exists only during the callback: it cannot be relied upon afterwards. If you need to keep some of that information outside the callback, then it needs to be copied to a safe location.
The called worker function can return data, by calling emscripten_worker_respond(). When the worker is called, if a callback was given it will be called with three arguments: a data pointer, a size, and an argument that was provided when calling emscripten_call_worker() (to more easily associate callbacks to calls). The data block defined by the data pointer and size behave like the data block in the worker function — it exists only during the callback.
| Parameters: |
|
|---|
Sends a response when in a worker call (that is, when called by the main thread using emscripten_call_worker()).
Both functions post a message back to the thread which called the worker. The emscripten_worker_respond_provisionally() variant can be invoked multiple times, which will queue up messages to be posted to the worker’s creator. Eventually, the _respond variant must be invoked, which will disallow further messages and free framework resources previously allocated for this worker call.
Note
Calling the provisional version is optional, but you must call the non-provisional version to avoid leaks.
| Parameters: |
|
|---|
Checks how many responses are being waited for from a worker.
This only counts calls to emscripten_call_worker() that had a callback (calls with null callbacks are ignored), and where the response has not yet been received. It is a simple way to check on the status of the worker to see how busy it is, and do basic decisions about throttling.
| Parameters: |
|
|---|---|
| Returns: | The number of responses waited on from a worker. |
| Return type: | int |
If specified, logs directly to the browser console/inspector window. If not specified, logs via the application Module.
If specified, prints a warning message.
If specified, prints an error message. If neither EM_LOG_WARN or EM_LOG_ERROR is specified, an info message is printed. EM_LOG_WARN and EM_LOG_ERROR are mutually exclusive.
If specified, prints a call stack that contains file names referring to original C sources using source map information.
If specified, prints a call stack that contains file names referring to lines in the built .js/.html file along with the message. The flags EM_LOG_C_STACK and EM_LOG_JS_STACK can be combined to output both untranslated and translated file and line information.
If specified, C/C++ function names are de-mangled before printing. Otherwise, the mangled post-compilation JavaScript function names are displayed.
If specified, the pathnames of the file information in the call stack will be omitted.
If specified, prints out the actual values of the parameters the functions were invoked with.
Returns the value of a compiler setting.
For example, to return the integer representing the value of PRECISE_F32 during compilation:
emscripten_get_compiler_setting("PRECISE_F32")
For values containing anything other than an integer, a string is returned (you will need to cast the int return value to a char*).
Some useful things this can do is provide the version of Emscripten (“EMSCRIPTEN_VERSION”), the optimization level (“OPT_LEVEL”), debug level (“DEBUG_LEVEL”), etc.
For this command to work, you must build with the following compiler option (as we do not want to increase the build size with this metadata):
-s RETAIN_COMPILER_SETTINGS=1
| Parameters: |
|
|---|---|
| Returns: | The value of the specified setting. Note that for values other than an integer, a string is returned (cast the int return value to a char*). |
| Return type: | int |
Emits debugger.
This is inline in the code, which tells the JavaScript engine to invoke the debugger if it gets there.
Prints out a message to the console, optionally with the callstack information.
| Parameters: |
|
|---|
Programmatically obtains the current callstack.
To query the amount of bytes needed for a callstack without writing it, pass 0 to out and maxbytes, in which case the function will return the number of bytes (including the terminating zero) that will be needed to hold the full callstack. Note that this might be fully accurate since subsequent calls will carry different line numbers, so it is best to allocate a few bytes extra to be safe.
| Parameters: |
|
|---|---|
| Returns: | The number of bytes written (not number of characters, so this will also include the terminating zero). |
| Return type: | int |
Gets preloaded image data and the size of the image.
The function returns pointer to loaded image or NULL — the pointer should be free()‘d. The width/height of the image are written to the w and h parameters if the data is valid.
| Parameters: |
|
|---|---|
| Type: | const char* |
| Returns: | A pointer to the preloaded image or NULL. |
| Return type: | char* |
Gets preloaded image data from a C FILE*.
| Parameters: |
|
|---|---|
| Type: | const char* |
| Returns: | A pointer to the preloaded image or NULL. |
| Return type: | char* |
The functions in this section register callback functions for receiving socket events. These events are analogous to WebSocket events but are emitted after the internal Emscripten socket processing has occurred. This means, for example, that the message callback will be triggered after the data has been added to the recv_queue, so that an application receiving this callback can simply read the data using the file descriptor passed as a parameter to the callback. All of the callbacks are passed a file descriptor (fd) representing the socket that the notified activity took place on. The error callback also takes an int representing the socket error number (errno) and a char* that represents the error message (msg).
Only a single callback function may be registered to handle any given event, so calling a given registration function more than once will cause the first callback to be replaced. Similarly, passing a NULL callback function to any emscripten_set_socket_*_callback call will de-register the callback registered for that event.
The userData pointer allows arbitrary data specified during event registration to be passed to the callback, this is particularly useful for passing this pointers around in Object Oriented code.
In addition to being able to register network callbacks from C it is also possible for native JavaScript code to directly use the underlying mechanism used to implement the callback registration. For example, the following code shows simple logging callbacks that are registered by default when SOCKET_DEBUG is enabled:
Module['websocket']['on']('error', function(error) {console.log('Socket error ' + error);});
Module['websocket']['on']('open', function(fd) {console.log('Socket open fd = ' + fd);});
Module['websocket']['on']('listen', function(fd) {console.log('Socket listen fd = ' + fd);});
Module['websocket']['on']('connection', function(fd) {console.log('Socket connection fd = ' + fd);});
Module['websocket']['on']('message', function(fd) {console.log('Socket message fd = ' + fd);});
Module['websocket']['on']('close', function(fd) {console.log('Socket close fd = ' + fd);});
Most of the JavaScript callback functions above get passed the file descriptor of the socket that triggered the callback, the on error callback however gets passed an array that contains the file descriptor, the error code and an error message.
Note
The underlying JavaScript implementation doesn’t pass userData. This is mostly of use to C/C++ code and the emscripten_set_socket_*_callback calls simply create a closure containing the userData and pass that as the callback to the underlying JavaScript event registration mechanism.
Function pointer for emscripten_set_socket_open_callback(), and the other socket functions (except emscripten_set_socket_error_callback()). This is defined as:
typedef void (*em_socket_callback)(int fd, void *userData);
| Parameters: |
|
|---|
Function pointer for the emscripten_set_socket_error_callback(), defined as:
typedef void (*em_socket_error_callback)(int fd, int err, const char* msg, void *userData);
| Parameters: |
|
|---|
Triggered by a WebSocket error.
See Socket event registration for more information.
| Parameters: |
|
|---|
Triggered when the WebSocket has opened.
See Socket event registration for more information.
| Parameters: |
|
|---|
Triggered when listen has been called (synthetic event).
See Socket event registration for more information.
| Parameters: |
|
|---|
Triggered when the connection has been established.
See Socket event registration for more information.
| Parameters: |
|
|---|
Triggered when data is available to be read from the socket.
See Socket event registration for more information.
| Parameters: |
|
|---|
Triggered when the WebSocket has closed.
See Socket event registration for more information.
| Parameters: |
|
|---|
Unaligned types. These may be used to force LLVM to emit unaligned loads/stores in places in your code where SAFE_HEAP found an unaligned operation.
For usage examples see tests/core/test_set_align.c.
Note
It is better to avoid unaligned operations, but if you are reading from a packed stream of bytes or such, these types may be useful!
Emterpreter-async functions are asynchronous functions that appear synchronously in C, the linker flags -s EMTERPRETIFY -s EMTERPRETIFY_ASYNC=1 are required to use these functions. See Emterpreter for more details.
Sleep for ms milliseconds. This is a normal “synchronous” sleep, which blocks all other operations while it runs. In other words, if there are other async events waiting to happen, they will not happen during this sleep, which makes sense as conceptually this code is on the stack (that’s how it looks in the C source code). If you do want things to happen while sleeping, see emscripten_sleep_with_yield.
Sleep for ms milliseconds, while allowing other asynchronous operations, e.g. caused by emscripten_async_call, to run normally, during this sleep. Note that this method does still block the main loop, as otherwise it could recurse, if you are calling this method from it. Even so, you should use this method carefully: the order of execution is potentially very confusing this way.
Synchronously fetches data off the network, and stores it to a buffer in memory, which is allocated for you. You must free the buffer, or it will leak!
| Parameters: |
|
|---|
Synchronously fetches data from IndexedDB, and stores it to a buffer in memory, which is allocated for you. You must free the buffer, or it will leak!
| Parameters: |
|
|---|
Synchronously stores data to IndexedDB.
| Parameters: |
|
|---|
Synchronously deletes data from IndexedDB.
| Parameters: |
|
|---|
Synchronously checks if a file exists in IndexedDB.
| Parameters: |
|
|---|
Asyncify functions are asynchronous functions that appear synchronously in C, the linker flag -s ASYNCIFY=1 is required to use these functions. See Asyncify for more details.