maierfelix/azula

azula, a lightweight GPU accelerated HTML GUI for native JavaScript applications

‌‌

azula is a lightweight alternative to Electron. It is based on Ultralight, which is an embedding friendly Fork of WebKit, with less memory usage and low disk space requirements.

azula can optionally run in OSR mode, which makes it easy to embed azula in existing Projects like Game/VR Engines.

Characteristics

Platforms

azula comes with pre-built N-API binaries for the following platforms:

OS	Status
Windows	‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ✔ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌
Linux	‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ In Progress ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌
MacOS	‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ In Progress ‌‌ ‌‌ ‌‌ ‌‌ ‌‌ ‌‌

Getting Started

Install azula using:

npm install azula

You can now import azula into your project:

const azula = require("azula");

Or with ESM:

import azula from "azula";

API

• Window
  • General
    • title
    • width
    • height
    • update
    • flush
    • shouldClose
  • Loading
    • loadHTML
    • loadFile
  • Events
    • onresize
    • oncursorchange
    • onconsolemessage
  • Event Dispatching
    • dispatchMouseEvent
    • dispatchKeyEvent
    • dispatchScrollEvent
  • Object Messaging
    • dispatchObject
    • onobjectmessage
  • Binary Messaging
    • dispatchBinaryBuffer
    • onbinarymessage
  • OSR Mode
    • getSharedHandleD3D11

Window

When creating a new Window, the following parameters are available:

let window = new azula.Window({
  width: 480,
  height: 320,
  title: "My App",
  useOffscreenRendering: false
});

General

Window.prototype.title

window.title = "My App";
window.title; // "My App"

Window.prototype.width

window.width = 640;
window.width; // 640

Window.prototype.height

window.height = 480;
window.height; // 480

Window.prototype.update

This method should be called to poll window events (making the window interactive). In non-OSR mode, this method also does the painting of the window.

window.update();

Window.prototype.flush

This method should only be used in OSR mode. Calling this method executes all remaining render operations and flushes the underlying context.

window.flush();

Window.prototype.shouldClose

window.shouldClose(); // true/false

Loading

Window.prototype.loadHTML

window.loadHTML("<button>Hello World!</button>");

Window.prototype.loadFile

window.loadFile("./index.html");

Events

Window.prototype.onresize

The callback's Event parameter has the following structure:

window.onresize = e => {
  console.log(e.width, e.height);
};

Window.prototype.oncursorchange

The callback's Event parameter has the following structure:

window.oncursorchange = e => {
  console.log(e.name);
};

Window.prototype.onconsolemessage

The underlying JavaScript engine of azula is WebKit's JavaScriptCore engine. Now this means, that the JavaScript running in the GUI is separated from the JavaScript in Node. When the JavaScript in the GUI makes a call to the console, e.g. console.log(42);, we have to route this call over to Node.

The callback's Event parameter has the following structure:

The location Object comes with the following structure:

window.onconsolemessage = e => {
  let location = `at ${e.source ? e.source + ":" : ""}${e.location.line}:${e.location.column}`;
  e.callee.apply(console, [e.message, location]);
};

Event Dispatching

The Event Dispatching System should only be used in OSR mode. Event Dispatching allows to manually send events to the GUI, such as mouse gestures or key events.

Window.prototype.dispatchMouseEvent

The following event types are available:

window.dispatchMouseEvent("onmousedown", 16, 32, 1); // press the left mouse button at 16:32
window.dispatchMouseEvent("onmouseup", 16, 32, 1); // leave the left mouse button at 16:32
window.dispatchMouseEvent("onmousemove", 16, 32, 0); // move the mouse to 16:32 without pressing a mouse button

Window.prototype.dispatchKeyEvent

Key Codes are mapped towards GLFW's Key Codes.

The following event types are available:

window.dispatchKeyEvent("onkeydown", x); // press a key
window.dispatchKeyEvent("onkeyup", x); // leave a key

Window.prototype.dispatchScrollEvent

The following event types are available:

window.dispatchScrollEvent("onmousewheel", 0, 1); // scroll upwards, vertically by 1
window.dispatchScrollEvent("onmousewheel", -1, 0); // scroll downwards, horizontally by -1

Object Messaging

The underlying JavaScript engine of azula is WebKit's JavaScriptCore engine. The JavaScript engine of Node is different to the one used in azula, so we cannot directly exchange data. The Object Messaging System allows to send Object between both engines.

Note that to be sent Objects should kept small, as behind the scenes, they get serialized.

Window.prototype.dispatchObject

An equivalent method is available in the GUI. See this example as a reference.

window.dispatchObject({ message: "PING" });

Window.prototype.onobjectmessage

An equivalent method is available in the GUI. See this example as a reference.

The callback's Event parameter has the following structure:

window.onobjectmessage = object => {
  console.log(object);
};

Binary Messaging

The underlying JavaScript engine of azula is WebKit's JavaScriptCore engine. The JavaScript engine of Node is different to the one used in azula, so we cannot directly exchange data. The Binary Messaging System allows to efficiently pass ArrayBuffers between both engines. Even though the engines are different, ArrayBuffers can be exchanged without any copying, meaning they don't have any overhead.

Window.prototype.dispatchBinaryBuffer

An equivalent method is available in the GUI. See this example as a reference.

The binarymessage system should only be used when sending large data between Node and azula. The buffer argument is a referenced buffer, which means there is no overhead when sending it between Node and azula as the data is effectively referenced.

The second argument is an Object (and is optional), which can be used to give some additional information about the buffer argument. This Object should be kept small, as it gets serialized behind the scenes, and so comes with some overhead.

window.dispatchBinaryBuffer(new ArrayBuffer(16), { kind: "SOME_DATA" });

Window.prototype.onbinarymessage

An equivalent method is available in the GUI. See this example as a reference.

The binarymessage system should only be used when sending large data between Node and azula. The buffer argument is a referenced buffer, which means there is no overhead when sending it between Node and azula as the data is effectively referenced.

The second argument is an Object (and is optional), which can be used to give some additional information about the buffer argument. This Object should be kept small, as it gets serialized behind the scenes, and so comes with some overhead.

The callback's Event parameter has the following structure:

window.onbinarymessage = (buffer, args) => {
  console.log(buffer, args);
};

OSR Mode

Window.prototype.getSharedHandleD3D11

On Windows, you can use this method to retrieve a shared HANDLE to the underlying D3D11 render texture.

let handle = window.getSharedHandleD3D11();

OSR

See this example as a reference.

azula supports running in OSR (Offscreen rendering) mode. This means, that instead of creating a window, an invisible texture gets used and rendered into. This texture can then be imported into a 3D engine for example. Another common use case would be, to display the texture in a VR environment.

On Windows, you can request a shared HANDLE using the Window's getSharedHandleD3D11 method.

License

Azula is MIT licensed, while Ultralight comes with the following License:

Ultralight is free for non-commercial use, educational use, 
and also free for commercial use by small indie developers making
less than US$100,000 a year. You can find full terms in the SDK. 
Pricing plans for larger commercial projects will be announced later.

For further information regaring the licensing of Ultralight, see this link.

‌‌

No, you miscalculated! You should have feared me more! - Azula