Menu
Umajin Developer > Native Libraries

Umajin has an interface that allows integrating native code into your project. Presently this is supported only on desktop platforms (Windows and Mac). It must be possible to create a DLL or Dynamic Library (dylib) with a C-style API.

Writing the native library

Your native library must implement the following C functions and export them to the DLL or Dylib.

const char* getIdentifier(void); 
const char* process(long long tag, const char* payload); 
const char* poll(long long tag, long long timestamp);

getIdentifier just returns an internal name for the library.

process is the interface for editor/JS to call into the library.

poll is called every frame for the library to send data to the project JS, if it has any; ie asynchronous events or responses.

Installing the native library

Once you have created your DLL and/or Dylib, place them in the Umajin Project folder as follows:

Windows: /manifest/win/bin

Mac: /manifest/osx/bin

You may need to create these folders if they do not already exist.

Note that while you may be able to use other folders, these are the standard folders that will work correctly in all situations, including when the app is “published” as a standalone application. In such standalone apps the files will be moved into appropriate places within the package. On Mac, they will be placed in the Contents/Frameworks folder in the .app folder.

Loading the library

From Javascript, call registerExternalFunction() with the library name and path. Presently, it is necessary to work out the path in detail:

var libFolder = getGlobal('project_path') + '/manifest';
var platformFolder = '';

if (getGlobal('os').toLowerCase().includes('windows')) {
    platformFolder = '/win/bin/';
} else {
    platformFolder = '/osx/bin/';
}

if (getGlobal('app_mode') == 0) {
    // Standalone app, path is internally resolved
    libFolder = '';
    platformFolder = '';
}

var libPath = libFolder + platformFolder + 'UmajinTestLib';

libraryId = registerExternalFunction( libPath, 'onLibData', 'onLibError');

This will return the same name/path as you pass in, which you should save in a global variable for use later. Or if the library could not be loaded, it will return blank; the on_error event will also be called. Note that all the 3 functions must be present with correct names for loading to succeed.

Using the library

Once successfully loaded, you can send data to the library using:

var result = externalFunctionProcess(libraryId , data);

This function can return data immediately.

If the library needs to send data back to the JS at another time (e.g. an asynchronous response to an earlier request), then it can return data when the poll() function is called. This will result in your onLibData function being called (that was registered with registerExternalFunction).

function onLibData(data) {
}
Menu