OpenCL for Node.js

This is a part of Node3D project.

npm install @node-3d/opencl

Node.js addon with OpenCL 1.2 bindings. This is not WebCL.

Prebuilt addon binaries: Windows x64/ARM64, Linux x64/ARM64, macOS x64/ARM64. An OpenCL runtime/ICD is still required on Windows and Linux.

Platform Notes

OpenCL behavior depends on the installed platform runtime. This package is a thin binding layer and generally forwards calls and status codes directly to the native OpenCL implementation, so validation details can differ between vendors.

Windows ARM64 uses Microsoft's OpenCLOn12 compatibility layer in CI. That layer exposes OpenCL through Direct3D 12, which is currently the practical way to run OpenCL on GitHub-hosted Windows ARM64 runners. It can differ from vendor OpenCL runtimes for invalid-input edge cases, especially around program build failures and kernel argument validation. Valid kernel build, argument setup, queue, buffer, and execution paths are still tested there.

The API directly reflects the low-level OpenCL interface. There are minor changes similar to how WebGL is different from OpenGL.

• All cl* methods are available as cl.* starting lowercase, e.g: clCreateKernel -> cl.createKernel.
• All CL_* constants are available as cl.*, e.g.: CL_TRUE -> cl.TRUE.
• The CL resource pointers are wrapped in JS objects, such as TClPlatform, TClContext, TClEvent.
• For cl.enqueue*() methods, you can pass hasEvent = true, in that case a TClEvent is returned.
• The CL status is not returned, instead a JS exception is thrown in case of a CL error.

Most of the method arguments comply to the original C-style spec, some parameters are omitted due to JS specifics. For example, passing an array, you don't need to specify its length.

API

The package is intended to be imported as a namespace:

import * as cl from '@node-3d/opencl';

The namespace contains:

• OpenCL constants, with CL_ prefixes removed.
• Platform/device/context helpers such as getPlatformIDs, getDeviceIDs, createContext, and createContextFromType.
• Queue, program, kernel, sampler, memory, image, and event functions mirroring OpenCL 1.2.
• GL interop helpers such as createFromGLBuffer, createFromGLTexture, enqueueAcquireGLObjects, and enqueueReleaseGLObjects.
• quickStart(isLoggingDevices?), which chooses the first available platform/device and creates a context for examples and small tools.

Resources are native handles wrapped in JS objects. Release resources explicitly with the matching release* function when ownership ends.

Examples

1. Import the module:

   import * as cl from '@node-3d/opencl';

2. Fetch the CL control objects:

   const { context, device } = cl.quickStart();
   const queue = cl.createCommandQueue(context, device);

3. Prepare the data input/output buffers:

   const BUFFER_SIZE = 10;
   const BYTE_SIZE = BUFFER_SIZE * Uint32Array.BYTES_PER_ELEMENT;
      
   const arrayA = new Uint32Array(BUFFER_SIZE);
   const arrayB = new Uint32Array(BUFFER_SIZE);
   const arrayC = new Uint32Array(BUFFER_SIZE);
      
   for (let i = 0; i < BUFFER_SIZE; i++) {
   	arrayA[i] = i;
   	arrayB[i] = i * 2;
   }
      
   // Create buffer for arrayA and arrayB and copy host contents
   const bufferA = cl.createBuffer(context, cl.MEM_READ_ONLY, BYTE_SIZE);
   const bufferB = cl.createBuffer(context, cl.MEM_READ_ONLY, BYTE_SIZE);
      
   // Create buffer for arrayC to read results
   const bufferC = cl.createBuffer(context, cl.MEM_WRITE_ONLY, BYTE_SIZE);

4. Create a valid CL program, e.g. from source:

   const program = cl.createProgramWithSource(context, `
   	__kernel
   	void vadd(__global int *a, __global int *b, __global int *c, uint num) {
   		size_t i = get_global_id(0);
   		if (i < num) {
   			c[i] = a[i] + b[i];
   		}
   	}
   `);
   cl.buildProgram(program);

5. Fetch and set up a kernel from within the program:

   // Create a kernel object
   const kernel = cl.createKernel(program, 'vadd');
      
   // Set kernel args
   cl.setKernelArg(kernel, 0, 'uint*', bufferA);
   cl.setKernelArg(kernel, 1, 'uint*', bufferB);
   cl.setKernelArg(kernel, 2, 'uint*', bufferC);
   cl.setKernelArg(kernel, 3, 'uint', BUFFER_SIZE);

6. Launch the kernel and then read the results:

   // Do the work
   cl.enqueueWriteBuffer(queue, bufferA, true, 0, BYTE_SIZE, arrayA);
   cl.enqueueWriteBuffer(queue, bufferB, true, 0, BYTE_SIZE, arrayB);
   cl.enqueueNDRangeKernel(queue, kernel, 1, null, [BUFFER_SIZE]);
   cl.enqueueReadBuffer(queue, bufferC, true, 0, BYTE_SIZE, arrayC);

7. See if it worked:

   console.log(`A = [${arrayA.join(', ')}]`);
   console.log(`B = [${arrayB.join(', ')}]`);
   console.log(`C = [${arrayC.join(', ')}]`);

8. Release the CL objects:

   cl.releaseCommandQueue(queue);
   cl.releaseKernel(kernel);
   cl.releaseProgram(program);
   cl.releaseMemObject(bufferA);
   cl.releaseMemObject(bufferB);
   cl.releaseMemObject(bufferC);

See examples for more details. The full code of the above example is available here.

Binary Origin

Release archives are built by this repository's public GitHub Actions workflows.

Attestations: https://github.com/node-3d/opencl/attestations

To verify a downloaded archive:

gh release download <tag> -R node-3d/opencl -p <platform>.gz
gh attestation verify <platform>.gz -R node-3d/opencl

This addon is ABI-compatible across Node.js versions. There is no compilation during npm install.