Node3D QML Extension

This is a part of Node3D project.

npm install @node-3d/plugin-qml

QML-rendering helpers for Node3D. The QML backend is Qt 6.8.0.

Note: IMPORTANT, QML has its own OpenGL context. Make sure to switch back. Use document.makeCurrent() or release() (see exported below).

CI runs full QML context-sharing tests on Windows x64 and Linux x64. Linux ARM64 loads and runs the plugin but skips screenshot comparison because Qt Quick rendering is not available on the hosted ARM runner. macOS CI validates binary and package loading only: QMLUI needs native Cocoa/NSGL handles, while hosted macOS cannot create a suitable NSGL pixel format and core's NULL/EGL path does not expose those handles.

import * as three from 'three';
import { init, addThreeHelpers, gl } from '@node-3d/core';
import { init as initQml } from '@node-3d/plugin-qml';

// Standard Node3D init
const { doc } = init({
	isGles3: true,
	isWebGL2: true,
	autoEsc: true,
});
addThreeHelpers(three);

// Initialize QML and fetch the helpers
const { QmlOverlay, Property, Method, View, loop, release, textureFromId } = initQml({
	doc,
	gl,
	cwd: import.meta.dirname,
	three,
});

• See example for a complete setup.

API

init(opts): TQml3D

Initializes QML rendering for a Node3D document and returns a cached object. Required options:

• doc - the @node-3d/core document.
• gl - the WebGL/OpenGL API from @node-3d/core.
• three - the Three.js module instance.
• cwd - base directory for QML files. Defaults to process.cwd().

Returned helpers:

• View, Property, Method - re-exported from @node-3d/qml.
• release() - switches the active OpenGL context back to the Node3D document.
• loop(cb) - updates QML, restores the document context, then runs cb every frame.
• textureFromId(id, renderer) - wraps a QML texture ID as a Three.js Texture.
• QmlMaterial, QmlOverlayMaterial, QmlOverlay - Three.js integration classes.

QmlOverlay

Loads a QML view and exposes a Three.js mesh intended for full-screen overlays. Add overlay.mesh to your scene, then listen to events emitted from QML via eventEmit.

QmlMaterial and QmlOverlayMaterial

Materials that use a QML View as their texture source. Use them when QML should appear on arbitrary meshes or overlay planes.

It is also possible to run QtQuick examples on Node.js with this renderer. But it will only work with QtQuick components, i.e. not QtMultimedia, QtNetwork, etc. - because those libs are not included. See Qt Quick Calqlatr example being copied as a proof of concept.

QmlOverlay

A common use-case is full-screen overlay UI:

// Loads QML and creates all threejs-related resources, e.g. `overlay.mesh` is `THREE.Mesh`
const overlay = new QmlOverlay({ file: `${import.meta.dirname}/qml/Test.qml` });
scene.add(overlay.mesh);

// QML property access shortcut
const propTest = new Property<string>({
	view: overlay,
	name: 'hud',
	key: 'testProp',
});

// A typed callable example
type TMethodTest = (arg0: number) => void;
const methodTest: TMethodTest = new Method({
	view: overlay,
	name: 'hud',
	key: 'testMethod',
});

// Listen to a user-defined event (could be any other name)
overlay.on('custom-event', (event) => {
	release();
	if (event.button === 'test') {
		console.log('test');
	}
	if (event.button === 'quit') {
		process.exit(0);
	}
});

propTest.value = 'test';
methodTest(123);

See examples for more details.

Any Material

Creating a threejs Texture from QML View is also supported. Such textures may be used in arbitrary threejs materials of your choice.

const testView = new View({ file: `${import.meta.dirname}/qml/Test.qml` });
const materialTest = new three.SpriteMaterial();

// If the view already has some texture - use it
materialTest.map = textureFromId(testView.textureId, renderer);

// If the view creates a new texture - update the material
testView.on('reset', (textureId) => {
	release();
	materialTest.map = textureFromId(textureId, renderer);
});