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

	Azula	Electron
CPU	1.2%	4.2%
RAM	37Mb	64Mb
DISK	31Mb	118Mb

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

Window

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

Name	Type	Description
width (Optional)	Number	The initial width of the window
height (Optional)	Number	The initial height of the window
title (Optional)	String	The initial title of the window
useOffscreenRendering (Optional)	Boolean	When true, creates the window in OSR mode

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

General

Window.prototype.title

Type	Description
String	A getter/setter allowing to retrieve or update the title of the window

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

Window.prototype.width

Type	Description
Number	A getter/setter allowing to retrieve or update the width of the window

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

Window.prototype.height

Type	Description
Number	A getter/setter allowing to retrieve or update the height of the window

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

Type	Description
Boolean	A boolean, indicating if the window should be closed

window.shouldClose(); // true/false

Loading

Window.prototype.loadHTML

Name	Type	Description
html	String	String representation of the HTML to load

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

Window.prototype.loadFile

Name	Type	Description
path	String	The path from where the content gets read from

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

Events

Window.prototype.onresize

Type	Description
Function	The function to call when the window gets resized

The callback’s Event parameter has the following structure:

Name	Type	Description
width	Number	The new width of the window
height	Number	The new height of the window

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

Window.prototype.oncursorchange

Type	Description
Function	The function to call when the cursor should be changed

The callback’s Event parameter has the following structure:

Name	Type	Description
name	String	A name representing the cursor type to change to

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

Window.prototype.onconsolemessage

Type	Description
Function	The function to call when a console message got sent

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:

Name	Type	Description
level	String	The level of the console call. For example “log”, “warn” or “error”
callee	Function	Node’s equivalent console function to call
message	String	The message passed to the console call
source	String	The file or location where the call was made. Is empty when loadHTML was used
location	Object	An Object describing the exact code location where the console call was made from

The location Object comes with the following structure:

Name	Type	Description
line	Number	The code line where the console call originated from
column	Number	The code column where the console call originated from

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

Name	Type	Description
type	String	The type of event
x	Number	The horizontal position of the mouse
y	Number	The vertical position of the mouse
button	Number	The currently pressed mouse button

The following event types are available:

Name	Type
onmousedown	Simulating a mouse press action
onmouseup	Simulating a mouse leave action
onmousemove	Simulating a mouse move action

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.

Name	Type	Description
type	String	The type of event
keyCode	Number	A key code representing which key to press

The following event types are available:

Name	Type
onkeydown	Simulating a key press action
onkeyup	Simulating a key leave action

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

Window.prototype.dispatchScrollEvent

Name	Type	Description
type	String	The type of event
deltaX	Number	The horizontal amount to scroll
deltaY	Number	The vertical amount to scroll

The following event types are available:

Name	Type
onmousewheel	Simulating a mouse wheel action

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

Object Messaging

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.

Name	Type	Description
object	Object	The Object to send to the GUI

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

Window.prototype.onobjectmessage

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

Type	Description
Function	The function to call when an object message was sent from the GUI

The callback’s Event parameter has the following structure:

Name	Type	Description
object	Object	The Object sent from the GUI

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.

Name	Type	Description
buffer	ArrayBuffer	The ArrayBuffer to send to the GUI
args (Optional)	Object	An Used-defined Object providing additional information about the buffer

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.

Type	Description
Function	The function to call when a binary message was sent from the GUI

The callback’s Event parameter has the following structure:

Name	Type	Description
buffer	ArrayBuffer	The ArrayBuffer sent from the GUI
args (Optional)	Object	An Used-defined Object providing additional information about the sent buffer

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

OSR Mode

Window.prototype.getSharedHandleD3D11

Type	Description
BigInt	A BigInt representing a Windows HANDLE

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

This site is open source. Improve this page.