This package has been deprecated

Author message:

'node-vulkan' is now 'nvk'

node-vulkan

This is a Vulkan API for node.js, which allows to interact from JavaScript/TypeScript with the low-level interface of Vulkan. The API style of this project strives to be as close as possible to Vulkan's C99 API. Currently the latest supported Vulkan version is 1.1.92, which includes support for e.g. NVIDIA's Ray Tracing extension VK_NVX_raytracing.

• Preview
• Example
• Installation
  • Requirements
  • Windows
• CLI
  • Syntax
  • Flags
  • Usage
    • Generation
    • Building
• TypeScript
• Syntactic Sugar
  • sType auto-filling
  • Structure creation shortcut
• Project Structure
• Binding Code Generator
• HTML, CSS based UIs
• TODOs

Preview:

You can find more previews and demos in /examples

Example:

In most cases the bindings match the native style of Vulkan. This allows you to follow existing C/C++ tutorials, but write the implementation itself with node-vulkan. Note that both interfaces end up with a similar amount of code. Optionally you can use some syntactic sugar to write things quicker.

JavaScript/TypeScript:

let instance = new VkInstance();
let appInfo = new VkApplicationInfo();
appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
appInfo.pApplicationName = "App";
appInfo.applicationVersion = VK_MAKE_VERSION(1, 0, 0);
appInfo.pEngineName = "Engine";
appInfo.engineVersion = VK_MAKE_VERSION(1, 0, 0);
appInfo.apiVersion = VK_API_VERSION_1_0;
 
let validationLayers = [
  "VK_LAYER_LUNARG_standard_validation"
];
let instanceInfo = new VkInstanceCreateInfo();
instanceInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
instanceInfo.pApplicationInfo = appInfo;
instanceInfo.ppEnabledLayerNames = validationLayers;
instanceInfo.enabledLayerCount = validationLayers.length;
vkCreateInstance(instanceInfo, null, instance);

C++:

VkInstance instance;
VkApplicationInfo appInfo = {};
appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
appInfo.pApplicationName = "App";
appInfo.applicationVersion = VK_MAKE_VERSION(1, 0, 0);
appInfo.pEngineName = "Engine";
appInfo.engineVersion = VK_MAKE_VERSION(1, 0, 0);
appInfo.apiVersion = VK_API_VERSION_1_0;
 
const std::vector<const char*> validationLayers = {
  "VK_LAYER_LUNARG_standard_validation"
};
VkInstanceCreateInfo instanceInfo = {};
instanceInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
instanceInfo.pApplicationInfo = &appInfo;
instanceInfo.ppEnabledLayerNames = validationLayers.data();
instanceInfo.enabledLayerCount = static_cast<uint32_t>(validationLayers.size());
vkCreateInstance(&instanceInfo, nullptr, &instance);

Installation:

Requirements:

• node.js >= v10.9.0 recommended

Windows:

Make sure you have Visual Studio >= 15 installed or use

npm install --global --production windows-build-tools

Install the corresponding Vulkan SDK version from here. The later installer will ask you to setup bindings for 1.1.92, so make sure you have Vulkan SDK 1.1.92 installed.

Install node-vulkan

npm install node-vulkan

After installing node-vulkan, a setup will ask you, if it should automate the whole binding build process for you.

Afterwards you can require or import node-vulkan in your project!

CLI:

Syntax:

npm run [script] [flag] [value]

Flags:

 [--vkversion] [version]: The Vulkan version to generate bindings for
 [--msvsversion] [msvsversion]: The Visual Studio version to build the bindings with

Usage:

Generation:

You can specify a version to generate bindings for like this:

npm run generate --vkversion=1.1.92

• Make sure the specified version to generate bindings for can be found here
• The binding specification file gets auto-downloaded and is stored in generate/specifications/{vkversion}.xml
  
• The generated bindings can then be found in generated/{vkversion}/

Building:

You can build the generated bindings like this:

npm run build --vkversion=1.1.92 --msvsversion=2017

The compiled bindings can then be found in generated/{vkversion}/build

TypeScript:

When generating bindings, a TypeScript definition file is auto-generated as well (see e.g. the file here).

To use the definition file, simply follow the installation steps above. Afterwards in your .ts file, import and use node-vulkan as follows:

import {
  VulkanWindow,
  VkApplicationInfo,
  VK_MAKE_VERSION,
  VK_API_VERSION_1_0
} from "node-vulkan/generated/1.1.92/index";
 
let win = new VulkanWindow({ width: 480, height: 320 });
 
let appInfo = new VkApplicationInfo({
  pApplicationName: "Hello!",
  applicationVersion: VK_MAKE_VERSION(1, 0, 0),
  pEngineName: "No Engine",
  engineVersion: VK_MAKE_VERSION(1, 0, 0),
  apiVersion: VK_API_VERSION_1_0
});

Also note, that it is recommended to enable the --strict mode in the compiler options.

Syntactic Sugar:

The API gives you some sugar to write things quicker, but still gives you the option to write everything explicitly

sType auto-filling

sType members get auto-filled, but you can still set them yourself

let appInfo = new VkApplicationInfo();
appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;

Becomes:

let appInfo = new VkApplicationInfo(); // sType auto-filled

Structure creation shortcut

Instead of:

let offset = new VkOffset2D();
offset.x = 0;
offset.y = 0;
let extent = new VkExtent2D();
extent.width = 640;
extent.height = 480;
let renderArea = new VkRect2D();
renderArea.offset = offset;
renderArea.extent = extent;

You can write:

let renderArea = new VkRect2D({
  offset: new VkOffset2D({ x: 0, y: 0 }),
  extent: new VkExtent2D({ width: 640, height: 480 })
});

Project Structure:

• generator: code for binding generation
• generated: the generated binding code
• examples: ready-to-run examples
• lib: required third party libs
• src: classes for e.g. window creation

This tool uses a new JavaScript type called BigInt to represent memory addresses returned by Vulkan. The BigInt type was recently added, so make sure you use a recent node.js version.

Binding Code Generator:

The Generator generates C++ code from a vk.xml specification file. It first converts the XML file into an AST, which is then used by the code generator. Currently a total of ~170.000 lines of code get generated, where ~110.000 lines are C++ code.

If you're interested in what a generated file look like, checkout calls.h or VkGraphicsPipelineCreateInfo.cpp

HTML, CSS based UIs

The chromium-ui branch contains an experiment about letting users create UIs with a complete HTML/CSS browser toolchain. The website (browser frame) can then be rendered inside Vulkan. This is done using Chromium-Embedded-Framework. The browser texture is shared with vulkan's memory, so you can directly render it on top of your application. Oh yes!

There is one last thing that prevents me from merging it. At the moment, browser redraws trigger a CPU texture copying path, which is horribly slow. At the moment the pipeline is:

• [ CEF |-> OpenGL <-> Vulkan ]

CEF recently got shared textures added, meaning crazy performance and no CPU wandering anymore! The above pipeline could now be:

• [ CEF <-> D3D11 <-> Vulkan ]

---

• |-> copying
• <-> sharing

But CEF's shared textures on Windows require D3D11 which I'm not familiar with. If you're interested in helping and solving this one last step, please make a PR!

TODOs:

• Struct generation (~95%)
• Handle generation (~100%)
• Enum generation (100%)
• Function generation (~95%)
• Deallocation (~90%)
• Vulkan API fill V8 reflection (~90%)
• Documentation generator (0%)
• CEF D3D11 high-performance texture sharing (~0%)