Logo

DOME

The comfortable framework for making games in Wren

View the Project on GitHub avivbeeri/dome

< Back

ffi

The ffi module provides an interface to dynamically loaded libraries (DLLs) written and compiled from other languages, allowing you to extend the functionality of DOME.

You do this by first declaring the API that the functions within the DLL expect, and then calling it appropriately. This module depends on libffi and is considered optional, so it is only included if DOME is built using DOME_OPT_FFI=1 when running make.

Accessing methods using this module is a very low level operation, and comes with certain caveats:

Types

Types are referred to as a string of the C type, except for “pointer” and the names of user-defined structs.

It contains the following classes:

Library

Static Methods

static load(shortName: String, libraryName: String): Library

Given a libraryName which is valid and on the path in your execution environment, DOME will load that DLL for future use, and return you a Library object representing it. It will be assigned the given shortName, for future retrieval if necessary.

static get(shortName: String): Library

If a library was loaded with the given shortName, return it. This is useful for retrieving previously loaded library.

static unload(shortName: String): Void

Unload the shortNameed DLL. After this, all functions within that library are inaccessible and invalidated.

Instance Methods

bind(fnName: String, retType: String, paramTypeList: String)[]): Void

This defines a function named fnName which returns a value of retType and is called with parameters in order of paramTypeList.

call(fnName: String, params: Any[]): Any

Calls the function fnName with the parameters in the params list. There is minimal type checking performed here, and you are responsible for passing in the correct types.

Struct

Static Methods

static declare(typeName: String, fieldTypeList: String): StructType

Defines a structType which can be passed to functions in a library.

static init(typeName: String, params: Any[]): Struct

Initialises a struct with the given parameters, ready to be passed to a function.

Instance Methods

getValue(index: Number): Any

Retrieves the value held in the field at the given index.

Pointer

This represents a pointer to a block of contiguous memory. It can be returned by a function or reference memory reserved by reserve.

Static Methods

reserve(bytes: Number): Pointer

Reserve bytes of memory and return a pointer to it. This pointer can be freed by calling free.

Instance Methods

free(): Void

Frees memory reserved by reserve.

asString(): String

Treats the pointer as a C-String so it will return all bytes until a null-terminator.

asBytes(size: Number): String

Treats the pointer as an array of bytes and returns as many bytes as expected.