
preamble.js
***********

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
^^^^^^^^^^^^^^^^^

* Calling compiled C functions from JavaScript

* Accessing memory

* Conversion functions — strings, pointers and arrays

* Run dependencies

* Stack trace

* Type accessors for the memory model


Calling compiled C functions from JavaScript
============================================

ccall(ident, returnType, argTypes, args, opts)

   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:
      * **ident** -- The name of the C function to be called.

      * **returnType** -- The return type of the function. This can
        be ""number"", ""string"" or ""array"", which correspond to
        the appropriate JavaScript types (use ""number"" for any C
        pointer, and ""array"" for JavaScript arrays and typed arrays;
        note that arrays are 8-bit), or for a void function it can be
        "null" (note: the JavaScript "null" value, not a string
        containing the word "null").

   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:
      * **argTypes** -- An array of the types of arguments for the
        function (if there are no arguments, this can be omitted).
        Types are as in "returnType", except that "array" is not
        supported as there is no way for us to know the length of the
        array).

      * **args** -- An array of the arguments to the function, as
        native JavaScript values (as in "returnType"). Note that
        string arguments will be stored on the stack (the JavaScript
        string will become a C string on the stack).

   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:

      * "async": Implies that the ccall will perform an async
        operation. This assumes you are using the Emterpreter-Async
        option for your code. When using this option, the ccalled
        function cannot return a value (it can't be received
        synchronously anyhow).

cwrap(ident, returnType, argTypes)

   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:
      * **ident** -- The name of the C function to be called.

      * **returnType** -- The return type of the function. This will
        be one of the JavaScript types "number", "string" or "array"
        (use "number" for any C pointer, and "array" for JavaScript
        arrays and typed arrays; note that arrays are 8-bit).

      * **argTypes** -- An array of the types of arguments for the
        function (if there are no arguments, this can be omitted).
        Types are as in "returnType", except that "array" is not
        supported as there is no way for us to know the length of the
        array).

   Returns:
      A JavaScript function that can be used for running the C
      function.


Accessing memory
================

setValue(ptr, value, type[, noSafe])

   Sets a value at a specific memory address at run-time.

   Note: * "setValue()" and "getValue()" only do *aligned* writes
     and

       reads.

     * The "type" is an LLVM IR type (one of "i8", "i16", "i32",
       "i64", "float", "double", or a pointer type like "i8*" or just
       "*"), not JavaScript types as used in "ccall()" or "cwrap()".
       This is a lower-level operation, and we do need to care what
       specific type is being used.

   Arguments:
      * **ptr** -- A pointer (number) representing the memory
        address.

      * **value** -- The value to be stored

      * **type** -- An LLVM IR type as a string (see "note" above).

      * **noSafe** (*bool*) -- Developers should ignore this
        variable. It is only used in "SAFE_HEAP" compilation mode,
        where it can help avoid infinite recursion in some specialist
        use cases.

getValue(ptr, type[, noSafe])

   Gets a value at a specific memory address at run-time.

   Note: * "setValue()" and "getValue()" only do *aligned* writes
     and

       reads!

     * The "type" is an LLVM IR type (one of "i8", "i16", "i32",
       "i64", "float", "double", or a pointer type like "i8*" or just
       "*"), not JavaScript types as used in "ccall()" or "cwrap()".
       This is a lower-level operation, and we do need to care what
       specific type is being used.

   Arguments:
      * **ptr** -- A pointer (number) representing the memory
        address.

      * **type** -- An LLVM IR type as a string (see "note" above).

      * **noSafe** (*bool*) -- Developers should ignore this
        variable. It is only used in "SAFE_HEAP" compilation mode,
        where it can help avoid infinite recursion in some specialist
        use cases.

   Returns:
      The value stored at the specified memory address.


Conversion functions — strings, pointers and arrays
===================================================

Pointer_stringify(ptr[, length])

   Returns a JavaScript String from a pointer, for use in compiled
   code.

   Arguments:
      * **ptr** -- The pointer to be converted to a "String".

      * **length** -- The length of the data in the pointer
        (optional).

   Returns:
      A JavaScript "String" containing the data from "ptr".

   Return type:
      String

UTF16ToString(ptr)

   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:
      * **ptr** -- A pointer to a null-terminated UTF16LE-encoded
        string in the Emscripten HEAP.

   Returns:
      A JavaScript "String" object

stringToUTF16(str, outPtr)

   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:
      * **str** (*String*) -- A JavaScript "String" object.

      * **outPtr** -- Pointer to data copied from "str", encoded in
        UTF16LE format and null-terminated.

UTF32ToString(ptr)

   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:
      * **ptr** -- A pointer to a null-terminated UTF32LE-encoded
        string in the Emscripten HEAP.

   Returns:
      A JavaScript "String" object.

stringToUTF32(str, outPtr)

   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:
      * **str** (*String*) -- A JavaScript "String" object.

      * **outPtr** -- Pointer to data copied from "str", encoded in
        encoded in UTF32LE format and null-terminated.

intArrayFromString(stringy, dontAddNull[, length])

   This converts a JavaScript string into a C-line array of numbers,
   0-terminated.

   Arguments:
      * **stringy** (*String*) -- The string to be converted.

      * **dontAddNull** (*bool*) -- If "true", the new array is not
        zero-terminated.

      * **length** -- The length of the array (optional).

   Returns:
      The array created from "stringy".

intArrayToString(array)

   This creates a JavaScript string from a zero-terminated C-line
   array of numbers.

   Arguments:
      * **array** -- The array to convert.

   Returns:
      A "String", containing the content of "array".

writeStringToMemory(string, buffer, dontAddNull)

   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:
      * **string** (*String*) -- The string to write into memory.

      * **buffer** (*Number*) -- The address (number) where "string"
        is to be written.

      * **dontAddNull** (*bool*) -- If "true", the new array is not
        zero-terminated.

writeArrayToMemory(array, buffer)

   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:
      * **array** -- The array to write to memory.

      * **buffer** (*Number*) -- The address (number) where "array"
        is to be written.

writeAsciiToMemory(str, buffer, dontAddNull)

   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:
      * **string** -- The string to write into memory.

      * **buffer** -- The address where "string" is to be written.

      * **dontAddNull** (*bool*) -- If "true", the new string is not
        zero-terminated.


Run dependencies
================

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.

addRunDependency(id)

   Adds an "id" to the list of run dependencies.

   This adds a run dependency and increments the run dependency
   counter.

   Arguments:
      * **id** (*String*) -- An arbitrary id representing the
        operation.

removeRunDependency(id)

   Removes a specified "id" from the list of run dependencies.

   Arguments:
      * **id** (*String*) -- The identifier for the specific
        dependency to be removed (added with "addRunDependency()")


Stack trace
===========

stackTrace()

   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.


Type accessors for the memory model
===================================

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.

HEAP8

   View for 8-bit signed memory.

HEAP16

   View for 16-bit signed memory.

HEAP32

   View for 32-bit signed memory.

HEAPU8

   View for 32-bit unsigned memory.

HEAPU8

   View for 32-bit unsigned memory.

HEAPU16

   View for 16-bit unsigned memory.

HEAPU32

   View for 32-bit unsigned memory.

HEAPF32

   View for 32-bit float memory.

HEAPF64

   View for 64-bit float memory.
