Important Notes

node-webcl will be soon superseeded by https://github.com/mikeseven/node-opencl. Node-opencl is a reimplementation of node.js bindings to OpenCL:

• true wrapper of OpenCL, not an object-oriented model as WebCL. This makes it easier to develop higher-level API
• supports OpenCL 1.1, 1.2, 2.0
• support for Nan2 and Node.JS 4
• no dependency on external packages such as node-webgl, which was a huge issue to install for many users
• Lots of unit tests

Introduction

This is an implementation of Khronos WebCL specification using NodeJS. This implementation solely relies on OpenCL 1.1 C headers.

Dislaimer

While we are close to the WebCL specification, some features in this code may or may not be available in the final specification. As such, this implementation should be considered for

• experimental development of WebCL/WebGL content,
• experimenting with new constructs that may not be available in browsers,
• coupled with Node.JS awesome capabilities, this software opens the door to non-browser applications (e.g. fast server-side image processing).

This implementation is not secure nor robust, we will update as the standard progresses in these areas. So beware that hacking your GPU may crash your computer; don't blame us!

License

node-webcl is distributed under BSD license

Copyright (c) 2011-2012, Motorola Mobility, Inc. All rights reserved.

See LICENSES in this distribution for all licenses used in samples from other companies.

Dependencies

• NAN must be installed first to support all versions of v8

• node-webgl. This module is used for samples using WebGL interoperability with WebCL. In turns, node-webgl relies on node-glfw that relies on GLFW, GLEW, AntTweakBar, and FreeImage. See node-webgl and node-glfw for instructions on how to install these modules.

• OpenCL 1.1 must be installed on your machine. Typically, this means your machine has a not too old graphic card (maybe not more than 3 years old) and its latest graphic drivers installed.

On Mac, we recommend using OSX 10.7 "Lion" since OSX 10.6 "Snow Leopard" only supports OpenCL 1.0 and is buggy.

On Windows, use Windows 7. Note that if your machine is 64-bit, you should use node.js 64-bit distribution, not the 32-bit default to avoid mismatch between node libraries and these native dependencies when node-gyp build the modules.

On Linux, make sure you use the latest AMD or NVidia drivers. This module has been tested with Ubuntu 10.10, 11.04 and 11.10 64-bit.

Pre-built binaries are available in submodule deps. Don't forget to do:

git submodule init
git submodule udpate

if you need these binaries.

Installation

Make sure GLEW, GLFW, AntTweakBar, and FreeImage libraries are in your path.

• on Windows, put DLLs in Windows\System32. Put headers in \include and static librairies in \lib for 32-bit libraries (if you use node.js in 32-bit) or \lib\x64 (if you use 64-bit node.js).

• on Mac, use homebrew

  brew install freeimage anttweakbar glfw3 glew

• on Linux use you package manager to install these libraries

Now install the usual way:

npm install node-webcl

this will also install https://github.com/mikeseven/node-webgl, https://github.com/mikeseven/node-glfw, https://github.com/mikeseven/node-image, and https://github.com/rvagg/nan.

If you want to use the latest code, retrieve each repo (node-webcl, node-webgl, node-glfw, and node-image) from github and simply do

node-gyp rebuild
npm link

A crash course on WebCL

WebCL is a JavaScript representation of OpenCL 1.1. It is not a straight mapping of OpenCL C methods but rather an object-oriented representation of OpenCL object model. Knowledge of OpenCL is therefore mandatory to be able to develop WebCL programs. See the Books section and/or jump directly into Specifications references at the end of this page.

There are few steps in creating a WebCL program:

1. Init WebCL
   1. find a suitable platform/device (cl.getPlatform(), cl.getDevices())
   2. create a context (context = cl.createContext())
   3. create a command queue (queue = context.createCommandQueue())
   4. compile a program (program = context.createProgram(), program.build())
   5. set up a kernel and its arguments (kernel = program.createKernel(), kernel.setArg())
   6. set up commands (queue.enqueueXXX())
2. Run computation
   1. set up kernel arguments (kernel.setArg())
   2. set up commands (queue.enqueueXXX())
   3. launch the computation (queue.enqueueTask() or queue.enqueueNDRange())

When used with WebGL, WebGL context must be created first because WebCL context is created with sharing the WebGL context. Remember that WebCL allows computations on WebGL buffers. WebCL doesn't do any rendering. By using WebCL and WebGL together, data remains in the device and this avoids expensive data transfer to/from CPU memory.

So the sequence becomes:

1. init WebGL
   1. init buffers
   2. init shaders
   3. init textures
2. init WebCL (context = cl.createContext({ sharedObject: gl }))
3. init shared objects (e.g. textures/array/pixel/render buffers)
4. launch WebGL rendering loop
   • ... execute GL commands
   • acquire GL objects (queue.enqueueAcquireGLObjects())
   • launch CL computation (queue.enqueueNDRange())
   • release GL objects (queue.enqueueReleaseGLObjects())
   • ... execute GL commands

References

Specifications

• Khronos OpenCL specification, http://www.khronos.org/registry/cl/
• Khronos WebCL working draft, https://cvs.khronos.org/svn/repos/registry/trunk/public/webcl/spec/latest/index.html
• Khronos WebGL specification, http://www.khronos.org/webgl/

Books

• Heterogeneous Computing with OpenCL, Benedict Gaster, Lee Howes, David R. Kaeli and Perhaad Mistry, Morgan Kaufmann, August 2011
• OpenCL Programming Guide by Aaftab Munshi, Benedict Gaster, Timothy G. Mattson and James Fung, Addison-Wesley Professional, July 2011
• OpenCL in Action: How to Accelerate Graphics and Computations, Matthew Scarpino, Manning Publications, November 2011
• The OpenCL Programming Book, Ryoji Tsuchiyama, Takashi Nakamura, Takuro Iizuka and Akihiro Asahara, Fixstars Corporation, April 2010, http://www.fixstars.com/en/opencl/book/OpenCLProgrammingBook/contents.html
• OpenCL Programming Guide for Mac OS X, http://developer.apple.com/library/mac/documentation/Performance/Conceptual/OpenCL_MacProgGuide/OpenCL_MacProgGuide.pdf

OpenCL SDKs (use latest!)

• NVidia graphic cards: NVidia CUDA/OpenCL SDK, http://developer.nvidia.com/opencl
• AMD/ATI graphics cards: AMD Accelerated Parallel Processing SDK, http://developer.amd.com/zones/openclzone/Pages/default.aspx
• Intel CPUs: Intel OpenCL SDK, http://software.intel.com/en-us/articles/vcsource-tools-opencl-sdk/