https://github.com/node-3d/opencl
OpenCL for Node.js
https://github.com/node-3d/opencl
api cl compute crossplatform gpgpu gpu node-3d node-addon nodejs opencl
Last synced: 10 days ago
JSON representation
OpenCL for Node.js
- Host: GitHub
- URL: https://github.com/node-3d/opencl
- Owner: node-3d
- License: mit
- Created: 2020-02-22T20:28:24.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2026-07-25T18:55:53.000Z (15 days ago)
- Last Synced: 2026-07-25T20:17:31.161Z (15 days ago)
- Topics: api, cl, compute, crossplatform, gpgpu, gpu, node-3d, node-addon, nodejs, opencl
- Language: C
- Homepage: https://github.com/node-3d/node-3d
- Size: 36.2 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# OpenCL for Node.js
This is a part of [Node3D](https://github.com/node-3d) project.
[](https://badge.fury.io/js/@node-3d%2Fopencl)
[](https://github.com/node-3d/opencl/actions/workflows/lint.yml)
[](https://github.com/node-3d/opencl/actions/workflows/test.yml)
[](https://github.com/node-3d/opencl/actions/workflows/cpplint.yml)
```bash
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:
```ts
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:
```ts
import * as cl from '@node-3d/opencl';
```
2. Fetch the CL control objects:
```ts
const { context, device } = cl.quickStart();
const queue = cl.createCommandQueue(context, device);
```
3. Prepare the data input/output buffers:
```ts
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:
```ts
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:
```ts
// 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:
```ts
// 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:
```ts
console.log(`A = [${arrayA.join(', ')}]`);
console.log(`B = [${arrayB.join(', ')}]`);
console.log(`C = [${arrayC.join(', ')}]`);
```
8. Release the CL objects:
```ts
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](examples/simple.ts).
## 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:
```bash
gh release download -R node-3d/opencl -p .gz
gh attestation verify .gz -R node-3d/opencl
```
> This addon is ABI-compatible across Node.js versions. **There is no compilation** during `npm install`.