webcl-nodep

Introduction
============
This is an implementation of Khronos [WebCL][WEBCL] specification using NodeJS.
This implementation solely relies on [OpenCL][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
------------
- ~~[node-webgl][NODE_WEBGL]. This module is used for samples using WebGL interoperability with WebCL.~~
~~In turns, [node-webgl][NODE_WEBGL] relies on [node-glfw][NODE_GLFW] that relies on [GLFW][GLFW], [GLEW][GLEW], [AntTweakBar][ANTTWEAKBAR]. 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
------------
Since OpenCL is a compute specification, rendering is not the main purpose but if you want to use graphic acceleration, you should first install node-glfw and then node-webgl and make sure some of node-webgl samples are working. See node-webgl for instructions.

Note that installing the usual way:

npm install node-webcl

will also install node-webgl and node-glfw.

If you want to use the latest code, simply do

node-gyp rebuild

in node-webcl, node-webgl, and node-glfw.

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 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/][OPENCL]
Khronos WebCL working draft*, [https://cvs.khronos.org/svn/repos/registry/trunk/public/webcl/spec/latest/index.html][WEBCL]
Khronos WebGL specification*, [http://www.khronos.org/webgl/][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/

[OPENCL]: http://www.khronos.org/registry/cl/ "Khronos OpenCL specification"
[WEBCL]: https://cvs.khronos.org/svn/repos/registry/trunk/public/webcl/spec/latest/index.html "Khronos WebCL working draft"
[NODE_WEBGL]: https://github.com/mikeseven/node-webgl "node-webgl"
[NODE_GLFW]: https://github.com/mikeseven/node-glfw "node-glfw"
[WEBGL]: http://www.khronos.org/webgl/ "Khronos WebGL specification"
[GLFW]: http://www.glfw.org/ "GLFW"
[ANTTWEAKBAR]: "http://www.antisphere.com/Wiki/tools:anttweakbar" "AntTweakBar"
[GLEW]: http://glew.sourceforge.net/ "GLEW: The OpenGL Extension Wrangler Library"