This is a work in progress!
Copyright © 2013 Khronos Group
This Working Draft defines WebCL (Web Computing Language). WebCL is a JavaScript binding to the Khronos OpenCL standard for heterogeneous parallel computing. It enables web applications to harness GPU and multi-core CPU parallel processing from within a Web browser, enabling significant acceleration of computationally intensive applications, such as image and video processing and advanced physics for WebGL games.
This document is a Working Draft, not an official specification. Do not cite this document as anything other than work in progress. Public discussion of this document is welcome on the (archived) WebCL mailing list public_webcl@khronos.org (see instructions).
TODO
The following basic types are used in this document.
typedef boolean CLboolean; typedef long CLint; typedef unsigned long CLuint; typedef unsigned long CLenum; // Used for enumerated types, such as WebCL.DEVICE_TYPE_GPU
WebCL methods throw exceptions instead of returning error codes
as return values as in OpenCL. Exceptions that may be thrown by
each method are listed in that method's documentation.
Additionally, almost all methods may throw `OUT_OF_RESOURCES`,
`OUT_OF_HOST_MEMORY`, or the WebCL-specific
`WEBCL_IMPLEMENTATION_FAILURE`, so these are not listed
separately. Furthermore, calling any function on an object that
has been released (either explicitly, or implicitly by releasing
any of its parent objects), will
throw INVALID_TYPE, where `TYPE` is
`CONTEXT`, `COMMAND_QUEUE`, `MEM_OBJECT`, `SAMPLER`, `PROGRAM`,
`KERNEL`, or `EVENT`. These exceptions are also not listed
separately in the method descriptions.
exception WebCLException : DOMException {
DOMString name; // A string representation of the numeric error code, e.g. "INVALID_VALUE"
DOMString? message; // An implementation-specific description of what caused the exception
};
Both the `name` and `message` fields are present in any WebCLException thrown by the implementation, but the message may be `null`.
Each dynamically created WebCL object has a `release` method that releases the resources consumed by that object. This does not cause the object to be deleted or garbage collected; it will remain in place, but trying to use it will cause an exception. Trying to release an object that has already been released will be silently ignored.
For convenience, the WebCL and WebCLContext classes contain an additional `releaseAll` function, which releases the context(s), as well as all other WebCL objects created from them. The usage and behavior of the release methods are illustrated in the example below.
var ctx1 = WebCL.createContext(...); var ctx2 = WebCL.createContext(...); var ctx3 = WebCL.createContext(...); var A = ctx1.createBuffer(...); var B = ctx2.createBuffer(...); ctx1.release(); // releases ctx1, but not buffer A ctx2.releaseAll(); // releases ctx2 and buffer B A.release(); // releases buffer A B.release(); // does nothing: B is already released var C = ctx1.createBuffer(...); // EXCEPTION: ctx1 is no longer valid WebCL.releaseAll(); // releases ctx3
Applications are strongly recommended to explicitly release all WebCL objects as soon as they are no longer needed, instead of relying on the JavaScript garbage collector. This is necessary because garbage collectors typically do not give any guarantees on when (or indeed if) they will reclaim the objects that are no longer in scope.
When the global `document` object goes out of scope, the WebCL implementation must implicitly call `release` on all remaining WebCL objects.
WebCL allows certain long-running functions to be executed either synchronously or asynchronously. The asynchronous mode is used if a user-defined callback function is given as an argument to such functions. If a callback function is associated with a WebCL object that is subsequently released, the callback will no longer be invoked. The signature of the callback function must be as follows:
callback WebCLCallback = void (WebCLEvent event);
The callback function can call arbitrary JavaScript functions, including both blocking and non-blocking APIs. The following diagram is non-normative, but describes a possible implementation.
Depending on the implementation, WebCL operations may be running concurrently with JavaScript. In particular, it may be possible for the application to modify an ArrayBuffer while it's being asynchronously copied to/from a WebCLMemoryObject. To avoid corrupting the contents of either buffer, applications should not modify an ArrayBuffer that has been enqueued for async read/write, until the relevant WebCL command queue has finished.
Window implements WebCLEnvironment; WorkerUtils implements WebCLEnvironment;
[NoInterfaceObject]
interface WebCLEnvironment {
readonly attribute WebCL webcl;
};
No exceptions.
`WebCL` is a singleton object in the global namespace that can not be used as a constructor or invoked as a function. It provides functions for creating computing contexts and for querying the available CL platforms and extensions. It also defines all enumerated types used in the API.
interface WebCL {
// Functions
sequence<WebCLPlatform> getPlatforms();
WebCLContext? createContext(optional WebCLContextProperties properties);
sequence<DOMString>? getSupportedExtensions();
CLboolean enableExtension(DOMString extensionName);
void waitForEvents(sequence<WebCLEvent> eventWaitList,
optional WebCLCallback whenFinished);
void releaseAll();
// Enums
/* Error Codes */
CLint SUCCESS = 0;
CLint DEVICE_NOT_FOUND = -1;
CLint DEVICE_NOT_AVAILABLE = -2;
CLint COMPILER_NOT_AVAILABLE = -3;
CLint MEM_OBJECT_ALLOCATION_FAILURE = -4;
CLint OUT_OF_RESOURCES = -5;
CLint OUT_OF_HOST_MEMORY = -6;
CLint PROFILING_INFO_NOT_AVAILABLE = -7;
CLint MEM_COPY_OVERLAP = -8;
CLint IMAGE_FORMAT_MISMATCH = -9;
CLint IMAGE_FORMAT_NOT_SUPPORTED = -10;
CLint BUILD_PROGRAM_FAILURE = -11;
CLint MAP_FAILURE = -12;
CLint MISALIGNED_SUB_BUFFER_OFFSET = -13;
CLint EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST = -14;
CLint INVALID_VALUE = -30;
CLint INVALID_DEVICE_TYPE = -31;
CLint INVALID_PLATFORM = -32;
CLint INVALID_DEVICE = -33;
CLint INVALID_CONTEXT = -34;
CLint INVALID_QUEUE_PROPERTIES = -35;
CLint INVALID_COMMAND_QUEUE = -36;
CLint INVALID_HOST_PTR = -37;
CLint INVALID_MEM_OBJECT = -38;
CLint INVALID_IMAGE_FORMAT_DESCRIPTOR = -39;
CLint INVALID_IMAGE_SIZE = -40;
CLint INVALID_SAMPLER = -41;
CLint INVALID_BINARY = -42;
CLint INVALID_BUILD_OPTIONS = -43;
CLint INVALID_PROGRAM = -44;
CLint INVALID_PROGRAM_EXECUTABLE = -45;
CLint INVALID_KERNEL_NAME = -46;
CLint INVALID_KERNEL_DEFINITION = -47;
CLint INVALID_KERNEL = -48;
CLint INVALID_ARG_INDEX = -49;
CLint INVALID_ARG_VALUE = -50;
CLint INVALID_ARG_SIZE = -51;
CLint INVALID_KERNEL_ARGS = -52;
CLint INVALID_WORK_DIMENSION = -53;
CLint INVALID_WORK_GROUP_SIZE = -54;
CLint INVALID_WORK_ITEM_SIZE = -55;
CLint INVALID_GLOBAL_OFFSET = -56;
CLint INVALID_EVENT_WAIT_LIST = -57;
CLint INVALID_EVENT = -58;
CLint INVALID_OPERATION = -59;
//CLint INVALID_GL_OBJECT = -60; // moved to extension
CLint INVALID_BUFFER_SIZE = -61;
//CLint INVALID_MIP_LEVEL = -62; // moved to extension
CLint INVALID_GLOBAL_WORK_SIZE = -63;
CLint INVALID_PROPERTY = -64;
/* cl_bool */
CLenum FALSE = 0;
CLenum TRUE = 1;
/* cl_platform_info */
CLenum PLATFORM_PROFILE = 0x0900;
CLenum PLATFORM_VERSION = 0x0901;
CLenum PLATFORM_NAME = 0x0902;
CLenum PLATFORM_VENDOR = 0x0903;
CLenum PLATFORM_EXTENSIONS = 0x0904;
/* cl_device_type - bitfield */
CLenum DEVICE_TYPE_DEFAULT = 0x1;
CLenum DEVICE_TYPE_CPU = 0x2;
CLenum DEVICE_TYPE_GPU = 0x4;
CLenum DEVICE_TYPE_ACCELERATOR = 0x8;
CLenum DEVICE_TYPE_ALL = 0xFFFFFFFF;
/* cl_device_info */
CLenum DEVICE_TYPE = 0x1000;
CLenum DEVICE_VENDOR_ID = 0x1001;
CLenum DEVICE_MAX_COMPUTE_UNITS = 0x1002;
CLenum DEVICE_MAX_WORK_ITEM_DIMENSIONS = 0x1003;
CLenum DEVICE_MAX_WORK_GROUP_SIZE = 0x1004;
CLenum DEVICE_MAX_WORK_ITEM_SIZES = 0x1005;
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 0x1006;
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 0x1007;
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_INT = 0x1008;
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 0x1009;
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 0x100A;
//CLenum DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0x100B; // moved to extension
CLenum DEVICE_MAX_CLOCK_FREQUENCY = 0x100C;
CLenum DEVICE_ADDRESS_BITS = 0x100D;
CLenum DEVICE_MAX_READ_IMAGE_ARGS = 0x100E;
CLenum DEVICE_MAX_WRITE_IMAGE_ARGS = 0x100F;
CLenum DEVICE_MAX_MEM_ALLOC_SIZE = 0x1010;
CLenum DEVICE_IMAGE2D_MAX_WIDTH = 0x1011;
CLenum DEVICE_IMAGE2D_MAX_HEIGHT = 0x1012;
CLenum DEVICE_IMAGE3D_MAX_WIDTH = 0x1013;
CLenum DEVICE_IMAGE3D_MAX_HEIGHT = 0x1014;
CLenum DEVICE_IMAGE3D_MAX_DEPTH = 0x1015;
CLenum DEVICE_IMAGE_SUPPORT = 0x1016;
CLenum DEVICE_MAX_PARAMETER_SIZE = 0x1017;
CLenum DEVICE_MAX_SAMPLERS = 0x1018;
CLenum DEVICE_MEM_BASE_ADDR_ALIGN = 0x1019;
//CLenum DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 0x101A; // removed; deprecated in OpenCL 1.2
CLenum DEVICE_SINGLE_FP_CONFIG = 0x101B;
CLenum DEVICE_GLOBAL_MEM_CACHE_TYPE = 0x101C;
CLenum DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0x101D;
CLenum DEVICE_GLOBAL_MEM_CACHE_SIZE = 0x101E;
CLenum DEVICE_GLOBAL_MEM_SIZE = 0x101F;
CLenum DEVICE_MAX_CONSTANT_BUFFER_SIZE = 0x1020;
CLenum DEVICE_MAX_CONSTANT_ARGS = 0x1021;
CLenum DEVICE_LOCAL_MEM_TYPE = 0x1022;
CLenum DEVICE_LOCAL_MEM_SIZE = 0x1023;
CLenum DEVICE_ERROR_CORRECTION_SUPPORT = 0x1024;
CLenum DEVICE_PROFILING_TIMER_RESOLUTION = 0x1025;
CLenum DEVICE_ENDIAN_LITTLE = 0x1026;
CLenum DEVICE_AVAILABLE = 0x1027;
CLenum DEVICE_COMPILER_AVAILABLE = 0x1028;
CLenum DEVICE_EXECUTION_CAPABILITIES = 0x1029;
CLenum DEVICE_QUEUE_PROPERTIES = 0x102A;
CLenum DEVICE_NAME = 0x102B;
CLenum DEVICE_VENDOR = 0x102C;
CLenum DRIVER_VERSION = 0x102D;
CLenum DEVICE_PROFILE = 0x102E;
CLenum DEVICE_VERSION = 0x102F;
CLenum DEVICE_EXTENSIONS = 0x1030;
CLenum DEVICE_PLATFORM = 0x1031;
//CLenum DEVICE_DOUBLE_FP_CONFIG = 0x1032; // moved to extension
//CLenum DEVICE_HALF_FP_CONFIG = 0x1033; // moved to extension
//CLenum DEVICE_PREFERRED_VECTOR_WIDTH_HALF = 0x1034; // moved to extension
CLenum DEVICE_HOST_UNIFIED_MEMORY = 0x1035;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_CHAR = 0x1036;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_SHORT = 0x1037;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_INT = 0x1038;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_LONG = 0x1039;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_FLOAT = 0x103A;
//CLenum DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE = 0x103B; // moved to extension
//CLenum DEVICE_NATIVE_VECTOR_WIDTH_HALF = 0x103C; // moved to extension
CLenum DEVICE_OPENCL_C_VERSION = 0x103D;
/* cl_device_fp_config - bitfield */
CLenum FP_DENORM = 0x1;
CLenum FP_INF_NAN = 0x2;
CLenum FP_ROUND_TO_NEAREST = 0x4;
CLenum FP_ROUND_TO_ZERO = 0x8;
CLenum FP_ROUND_TO_INF = 0x10;
CLenum FP_FMA = 0x20;
CLenum FP_SOFT_FLOAT = 0x40;
/* cl_device_mem_cache_type */
CLenum NONE = 0x0;
CLenum READ_ONLY_CACHE = 0x1;
CLenum READ_WRITE_CACHE = 0x2;
/* cl_device_local_mem_type */
CLenum LOCAL = 0x1;
CLenum GLOBAL = 0x2;
/* cl_device_exec_capabilities - bitfield */
CLenum EXEC_KERNEL = 0x1;
//CLenum EXEC_NATIVE_KERNEL = 0x2; // disallowed
/* cl_command_queue_properties - bitfield */
CLenum QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE = 0x1;
CLenum QUEUE_PROFILING_ENABLE = 0x2;
/* cl_context_info */
//CLenum CONTEXT_REFERENCE_COUNT = 0x1080; // disallowed
CLenum CONTEXT_DEVICES = 0x1081;
CLenum CONTEXT_PROPERTIES = 0x1082;
CLenum CONTEXT_NUM_DEVICES = 0x1083;
/* cl_context_info + cl_context_properties */
CLenum CONTEXT_PLATFORM = 0x1084;
/* cl_command_queue_info */
CLenum QUEUE_CONTEXT = 0x1090;
CLenum QUEUE_DEVICE = 0x1091;
//CLenum QUEUE_REFERENCE_COUNT = 0x1092; // disallowed
CLenum QUEUE_PROPERTIES = 0x1093;
/* cl_mem_flags - bitfield */
CLenum MEM_READ_WRITE = 0x1;
CLenum MEM_WRITE_ONLY = 0x2;
CLenum MEM_READ_ONLY = 0x4;
/* cl_channel_order */
CLenum R = 0x10B0;
CLenum A = 0x10B1;
CLenum RG = 0x10B2;
CLenum RA = 0x10B3;
CLenum RGB = 0x10B4;
CLenum RGBA = 0x10B5;
CLenum BGRA = 0x10B6;
CLenum ARGB = 0x10B7;
CLenum INTENSITY = 0x10B8;
CLenum LUMINANCE = 0x10B9;
CLenum Rx = 0x10BA;
CLenum RGx = 0x10BB;
CLenum RGBx = 0x10BC;
/* cl_channel_type */
CLenum SNORM_INT8 = 0x10D0;
CLenum SNORM_INT16 = 0x10D1;
CLenum UNORM_INT8 = 0x10D2;
CLenum UNORM_INT16 = 0x10D3;
CLenum UNORM_SHORT_565 = 0x10D4;
CLenum UNORM_SHORT_555 = 0x10D5;
CLenum UNORM_INT_101010 = 0x10D6;
CLenum SIGNED_INT8 = 0x10D7;
CLenum SIGNED_INT16 = 0x10D8;
CLenum SIGNED_INT32 = 0x10D9;
CLenum UNSIGNED_INT8 = 0x10DA;
CLenum UNSIGNED_INT16 = 0x10DB;
CLenum UNSIGNED_INT32 = 0x10DC;
CLenum HALF_FLOAT = 0x10DD;
CLenum FLOAT = 0x10DE;
/* cl_mem_object_type */
CLenum MEM_OBJECT_BUFFER = 0x10F0;
CLenum MEM_OBJECT_IMAGE2D = 0x10F1;
CLenum MEM_OBJECT_IMAGE3D = 0x10F2;
/* cl_mem_info */
CLenum MEM_TYPE = 0x1100;
CLenum MEM_FLAGS = 0x1101;
CLenum MEM_SIZE = 0x1102;
//CLenum MEM_HOST_PTR = 0x1103; // disallowed
//CLenum MEM_MAP_COUNT = 0x1104; // disallowed
//CLenum MEM_REFERENCE_COUNT = 0x1105; // disallowed
CLenum MEM_CONTEXT = 0x1106;
CLenum MEM_ASSOCIATED_MEMOBJECT = 0x1107;
CLenum MEM_OFFSET = 0x1108;
/* cl_image_info */
CLenum IMAGE_FORMAT = 0x1110;
CLenum IMAGE_ELEMENT_SIZE = 0x1111;
CLenum IMAGE_ROW_PITCH = 0x1112;
CLenum IMAGE_WIDTH = 0x1114;
CLenum IMAGE_HEIGHT = 0x1115;
/* cl_addressing_mode */
//CLenum ADDRESS_NONE = 0x1130; // disallowed
CLenum ADDRESS_CLAMP_TO_EDGE = 0x1131;
CLenum ADDRESS_CLAMP = 0x1132;
CLenum ADDRESS_REPEAT = 0x1133;
CLenum ADDRESS_MIRRORED_REPEAT = 0x1134;
/* cl_filter_mode */
CLenum FILTER_NEAREST = 0x1140;
CLenum FILTER_LINEAR = 0x1141;
/* cl_sampler_info */
//CLenum SAMPLER_REFERENCE_COUNT = 0x1150; // disallowed
CLenum SAMPLER_CONTEXT = 0x1151;
CLenum SAMPLER_NORMALIZED_COORDS = 0x1152;
CLenum SAMPLER_ADDRESSING_MODE = 0x1153;
CLenum SAMPLER_FILTER_MODE = 0x1154;
/* cl_map_flags - bitfield */
//CLenum MAP_READ = 0x1; // disallowed
//CLenum MAP_WRITE = 0x2; // disallowed
/* cl_program_info */
//CLenum PROGRAM_REFERENCE_COUNT = 0x1160; // disallowed
CLenum PROGRAM_CONTEXT = 0x1161;
CLenum PROGRAM_NUM_DEVICES = 0x1162;
CLenum PROGRAM_DEVICES = 0x1163;
CLenum PROGRAM_SOURCE = 0x1164;
//CLenum PROGRAM_BINARY_SIZES = 0x1165; // disallowed
//CLenum PROGRAM_BINARIES = 0x1166; // disallowed
/* cl_program_build_info */
CLenum PROGRAM_BUILD_STATUS = 0x1181;
CLenum PROGRAM_BUILD_OPTIONS = 0x1182;
CLenum PROGRAM_BUILD_LOG = 0x1183;
/* cl_build_status */
CLint BUILD_SUCCESS = 0;
CLint BUILD_NONE = -1;
CLint BUILD_ERROR = -2;
CLint BUILD_IN_PROGRESS = -3;
/* cl_kernel_info */
CLenum KERNEL_FUNCTION_NAME = 0x1190;
CLenum KERNEL_NUM_ARGS = 0x1191;
//CLenum KERNEL_REFERENCE_COUNT = 0x1192; // disallowed
CLenum KERNEL_CONTEXT = 0x1193;
CLenum KERNEL_PROGRAM = 0x1194;
/* cl_kernel_work_group_info */
CLenum KERNEL_WORK_GROUP_SIZE = 0x11B0;
CLenum KERNEL_COMPILE_WORK_GROUP_SIZE = 0x11B1;
CLenum KERNEL_LOCAL_MEM_SIZE = 0x11B2;
CLenum KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE = 0x11B3;
CLenum KERNEL_PRIVATE_MEM_SIZE = 0x11B4;
/* cl_event_info */
CLenum EVENT_COMMAND_QUEUE = 0x11D0;
CLenum EVENT_COMMAND_TYPE = 0x11D1;
//CLenum EVENT_REFERENCE_COUNT = 0x11D2; // disallowed
CLenum EVENT_COMMAND_EXECUTION_STATUS = 0x11D3;
CLenum EVENT_CONTEXT = 0x11D4;
/* cl_command_type */
CLenum COMMAND_NDRANGE_KERNEL = 0x11F0;
CLenum COMMAND_TASK = 0x11F1;
//CLenum COMMAND_NATIVE_KERNEL = 0x11F2; // disallowed
CLenum COMMAND_READ_BUFFER = 0x11F3;
CLenum COMMAND_WRITE_BUFFER = 0x11F4;
CLenum COMMAND_COPY_BUFFER = 0x11F5;
CLenum COMMAND_READ_IMAGE = 0x11F6;
CLenum COMMAND_WRITE_IMAGE = 0x11F7;
CLenum COMMAND_COPY_IMAGE = 0x11F8;
CLenum COMMAND_COPY_IMAGE_TO_BUFFER = 0x11F9;
CLenum COMMAND_COPY_BUFFER_TO_IMAGE = 0x11FA;
//CLenum COMMAND_MAP_BUFFER = 0x11FB; // disallowed
//CLenum COMMAND_MAP_IMAGE = 0x11FC; // disallowed
//CLenum COMMAND_UNMAP_MEM_OBJECT = 0x11FD; // disallowed
CLenum COMMAND_MARKER = 0x11FE;
//CLenum COMMAND_ACQUIRE_GL_OBJECTS = 0x11FF; // moved to extension
//CLenum COMMAND_RELEASE_GL_OBJECTS = 0x1200; // moved to extension
CLenum COMMAND_READ_BUFFER_RECT = 0x1201;
CLenum COMMAND_WRITE_BUFFER_RECT = 0x1202;
CLenum COMMAND_COPY_BUFFER_RECT = 0x1203;
CLenum COMMAND_USER = 0x1204;
/* command execution status */
CLenum COMPLETE = 0x0;
CLenum RUNNING = 0x1;
CLenum SUBMITTED = 0x2;
CLenum QUEUED = 0x3;
/* cl_profiling_info */
CLenum PROFILING_COMMAND_QUEUED = 0x1280;
CLenum PROFILING_COMMAND_SUBMIT = 0x1281;
CLenum PROFILING_COMMAND_START = 0x1282;
CLenum PROFILING_COMMAND_END = 0x1283;
};
dictionary WebCLContextProperties {
sequence<WebCLDevice>? devices = null; // Default: let the implementation decide
WebCLPlatform? platform = null; // Default: let the implementation decide
CLenum deviceType = 0x1; // 0x1 == WebCL.DEVICE_TYPE_DEFAULT
};
| deviceType | Description |
|---|---|
| DEVICE_TYPE_CPU | A single-core or multi-core CPU, typically the host processor. |
| DEVICE_TYPE_GPU | A graphics processing unit, typically also used by WebGL. |
| DEVICE_TYPE_ACCELERATOR | A dedicated OpenCL accelerator. |
| DEVICE_TYPE_DEFAULT | The default device on this platform. |
| DEVICE_TYPE_ALL | All devices available on this platform. |
interface WebCLPlatform {
any getInfo(CLenum name);
sequence<WebCLDevice> getDevices(optional CLenum deviceType);
sequence<DOMString>? getSupportedExtensions();
CLboolean enableExtension(DOMString extensionName);
};
| deviceType | description |
|---|---|
| DEVICE_TYPE_CPU | A single-core or multi-core CPU, typically the host processor. |
| DEVICE_TYPE_GPU | A graphics processing unit, typically also used by WebGL. |
| DEVICE_TYPE_ACCELERATOR | A dedicated OpenCL accelerator. |
| DEVICE_TYPE_DEFAULT | The default device on this platform. |
| DEVICE_TYPE_ALL | All devices available on this platform. |
interface WebCLDevice {
any getInfo(CLenum name);
sequence<DOMString>? getSupportedExtensions();
CLboolean enableExtension(DOMString extensionName);
};
interface WebCLContext {
WebCLBuffer createBuffer(CLenum memFlags, CLuint sizeInBytes, optional ArrayBufferView hostPtr);
WebCLCommandQueue createCommandQueue(optional WebCLDevice? device, optional CLenum properties);
WebCLImage createImage(CLenum memFlags,
WebCLImageDescriptor descriptor,
optional ArrayBufferView hostPtr);
WebCLProgram createProgram(DOMString source);
WebCLSampler createSampler(CLboolean normalizedCoords,
CLenum addressingMode,
CLenum filterMode);
WebCLUserEvent createUserEvent();
any getInfo(CLenum name);
sequence<WebCLImageDescriptor>? getSupportedImageFormats(optional CLenum memFlags = MEM_READ_WRITE);
void release();
void releaseAll();
};
dictionary WebCLImageDescriptor {
CLenum channelOrder = 0x10B5; // 0x10B5 == WebCL.RGBA
CLenum channelType = 0x10D2; // 0x10D2 == WebCL.UNORM_INT8, 8-bit colors normalized to [0, 1]
CLuint width = 0, height = 0;
CLuint rowPitch = 0;
};
sizeInBytes == 0 || sizeInBytes > DEVICE_MAX_MEM_ALLOC_SIZEhostPtr.byteLength < sizeInBytesdescriptor.width == 0 || descriptor.width > DEVICE_IMAGE2D_MAX_WIDTH
descriptor.height == 0 || descriptor.height > DEVICE_IMAGE2D_MAX_HEIGHT
hostPtr.byteLength < descriptor.rowPitch * descriptor.height| name | return type |
|---|---|
| CONTEXT_NUM_DEVICES | CLuint |
| CONTEXT_DEVICES | sequence<WebCLDevice> |
| CONTEXT_PROPERTIES | WebCLContextProperties |
interface WebCLCommandQueue {
////////////////////////////////////////////////////////////////////////////
//
// Copying: Buffer <-> Buffer, Image <-> Image, Buffer <-> Image
//
void enqueueCopyBuffer(
WebCLBuffer srcBuffer,
WebCLBuffer dstBuffer,
CLuint srcOffset,
CLuint dstOffset,
CLuint numBytes,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueCopyBufferRect(
WebCLBuffer srcBuffer,
WebCLBuffer dstBuffer,
sequence<CLuint> srcOrigin,
sequence<CLuint> dstOrigin,
sequence<CLuint> region,
CLuint srcRowPitch,
CLuint srcSlicePitch,
CLuint dstRowPitch,
CLuint dstSlicePitch,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueCopyImage(
WebCLImage srcImage,
WebCLImage dstImage,
sequence<CLuint> srcOrigin,
sequence<CLuint> dstOrigin,
sequence<CLuint> region,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueCopyImageToBuffer(
WebCLImage srcImage,
WebCLBuffer dstBuffer,
sequence<CLuint> srcOrigin,
sequence<CLuint> srcRegion,
CLuint dstOffset,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueCopyBufferToImage(
WebCLBuffer srcBuffer,
WebCLImage dstImage,
CLuint srcOffset,
sequence<CLuint> dstOrigin,
sequence<CLuint> dstRegion,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
////////////////////////////////////////////////////////////////////////////
//
// Reading: Buffer -> Host, Image -> Host
//
void enqueueReadBuffer(
WebCLBuffer buffer,
CLboolean blockingRead,
CLuint bufferOffset,
CLuint numBytes,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueReadBufferRect(
WebCLBuffer buffer,
CLboolean blockingRead,
sequence<CLuint> bufferOrigin,
sequence<CLuint> hostOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
CLuint bufferSlicePitch,
CLuint hostRowPitch,
CLuint hostSlicePitch,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueReadImage(
WebCLImage image,
CLboolean blockingRead,
sequence<CLuint> origin,
sequence<CLuint> region,
CLuint hostRowPitch,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
////////////////////////////////////////////////////////////////////////////
//
// Writing: Host -> Buffer, Host -> Image
//
void enqueueWriteBuffer(
WebCLBuffer buffer,
CLboolean blockingWrite,
CLuint bufferOffset,
CLuint numBytes,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBufferRect(
WebCLBuffer buffer,
CLboolean blockingWrite,
sequence<CLuint> bufferOrigin,
sequence<CLuint> hostOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
CLuint bufferSlicePitch,
CLuint hostRowPitch,
CLuint hostSlicePitch,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteImage(
WebCLImage image,
CLboolean blockingWrite,
sequence<CLuint> origin,
sequence<CLuint> region,
CLuint hostRowPitch,
ArrayBufferView hostPtr,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
////////////////////////////////////////////////////////////////////////////
//
// Executing kernels
//
void enqueueNDRangeKernel(
WebCLKernel kernel,
CLuint workDim,
sequence<CLuint>? globalWorkOffset,
sequence<CLuint> globalWorkSize,
sequence<CLuint>? localWorkSize,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
////////////////////////////////////////////////////////////////////////////
//
// Synchronization
//
void enqueueMarker(WebCLEvent event);
void enqueueBarrier();
void enqueueWaitForEvents (sequence<WebCLEvent> eventWaitList);
void finish();
void flush();
////////////////////////////////////////////////////////////////////////////
//
// Querying command queue information
//
any getInfo(CLenum name);
void release();
};
numBytes %
hostPtr.BYTES_PER_ELEMENT !== 0host{Row,Slice}Pitch %
hostPtr.BYTES_PER_ELEMENT !== 0hostRowPitch % hostPtr.BYTES_PER_ELEMENT !== 0numBytes %
hostPtr.BYTES_PER_ELEMENT !== 0host{Row,Slice}Pitch %
hostPtr.BYTES_PER_ELEMENT !== 0hostRowPitch % hostPtr.BYTES_PER_ELEMENT !== 0globalWorkSize.length != workDimglobalWorkSize[i] > 232-1 for any `i`globalWorkOffset.length != workDimglobalWorkSize[i] + globalWorkOffset[i] > 232-1 for any `i`localWorkSize.length != workDimglobalWorkSize[i] % localWorkSize[i] !== 0 for any `i`localWorkSize[i] !== requiredSize[i] for any `i`, where
`requiredSize` is specified using the `reqd_work_group_size` qualifier in kernel sourcelocalWorkSize[i] > DEVICE_MAX_WORK_ITEM_SIZES[i] for any `i`| name | return type |
|---|---|
| QUEUE_CONTEXT | WebCLContext |
| QUEUE_DEVICE | WebCLDevice |
| QUEUE_PROPERTIES | CLenum |
// This example shows how to wait for two kernels to complete before a // third kernel executes var eventWaitList = [ new WebCLEvent(), new WebCLEvent() ]; queue.enqueueNDRangeKernel(kernel1, dim, null, globals, null, null, eventWaitList[0]); queue.enqueueNDRangeKernel(kernel2, dim, null, globals, null, null, eventWaitList[1]); queue.enqueueNDRangeKernel(kernel3, dim, null, globals, null, eventWaitList);
// This example reads the entire contents of a WebCL buffer object
// into a newly created Uint8Array in host memory.
function readBufferToHost(srcBuffer) {
// Query the number of bytes in the source buffer, create a new
// Uint8Array of that size, then fill it with a blocking read.
var numBytes = srcBuffer.getInfo(WebCL.MEM_SIZE);
var dstArray = new Uint8Array(numBytes);
queue.enqueueReadBuffer(srcBuffer, true, 0, numBytes, dstArray);
return dstArray;
};
// This example fills a WebCL image with pixels from a WebCL buffer.
function copyBufferToImage(srcBuffer, dstImage) {
// Extract the dimensions of the image.
var imgWidth = dstImage.getInfo(WebCL.IMAGE_WIDTH);
var imgHeight = dstImage.getInfo(WebCL.IMAGE_HEIGHT);
queue.enqueueCopyBufferToImage(srcBuffer, dstImage, 0, [0,0], [imgWidth, imgHeight]);
};
// This example copies a rectangular region of memory from a
// buffer object to another. The buffer objects are assumed
// to be the same size. The origin, width, height, and pitch
// (a.k.a. row stride) are given in bytes (not pixels, because
// these are buffers rather than images).
function copyBufferRect(srcBuffer, dstBuffer, srcX, srcY, dstX, dstY, w, h, pitch) {
// The row pitch could be different for source and destination,
// but is assumed to be the same in this example.
queue.enqueueCopyBufferRect(srcBuffer, dstBuffer, [srcX, srcY], [dstX, dstY],
[w, h], pitch, 0, pitch, 0);
};
interface WebCLMemoryObject {
any getInfo(CLenum name);
void release();
};
| name | return type | return value |
|---|---|---|
| `MEM_TYPE` | `CLenum` | `MEM_OBJECT_BUFFER` or `MEM_OBJECT_IMAGE2D` |
| `MEM_FLAGS` | `CLenum` | The `memFlags` as specified at construction time |
| `MEM_SIZE` | `CLuint` | The size of this memory object in bytes |
| `MEM_CONTEXT` | `WebCLContext` | the WebCL context of this memory object |
| `MEM_ASSOCIATED_MEMOBJECT` | `WebCLBuffer` | The buffer object that this buffer was created from, or `null` if this buffer was not created using `createSubBuffer` |
| `MEM_OFFSET` | `CLuint` | The offset given to `createSubBuffer`, or zero if this buffer was not created using `createSubBuffer` |
interface WebCLBuffer : WebCLMemoryObject {
WebCLBuffer createSubBuffer(CLenum memFlags, CLuint origin, CLuint sizeInBytes);
};
interface WebCLImage : WebCLMemoryObject {
WebCLImageDescriptor getInfo();
};
interface WebCLSampler {
any getInfo(CLenum name);
void release();
};
| name | return type |
|---|---|
| SAMPLER_CONTEXT | WebCLContext |
| SAMPLER_NORMALIZED_COORDS | CLboolean |
| SAMPLER_ADDRESSING_MODE | CLenum |
| SAMPLER_FILTER_MODE | CLenum |
interface WebCLProgram {
any getInfo(CLenum name);
any getBuildInfo(WebCLDevice device, CLenum name);
void build(optional sequence<WebCLDevice>? devices,
optional DOMString? options,
optional WebCLCallback whenFinished);
WebCLKernel createKernel(DOMString kernelName);
sequence<WebCLKernel> createKernelsInProgram();
void release();
};
| name | return type |
|---|---|
| PROGRAM_CONTEXT | WebCLContext |
| PROGRAM_NUM_DEVICES | CLuint |
| PROGRAM_DEVICES | sequence<WebCLDevice> |
| PROGRAM_SOURCE | DOMString |
| name | return type |
|---|---|
| PROGRAM_BUILD_STATUS | CLint |
| PROGRAM_BUILD_OPTIONS | DOMString |
| PROGRAM_BUILD_LOG | DOMString |
| Build option | Description |
|---|---|
| -D name | Equivalent to #define name in OpenCL C. |
| -D name=definition | Equivalent to #define name definition in OpenCL C. |
| -cl-opt-disable | Disable all optimizations. |
| -cl-single-precision-constant | Treat double-precision constants as single-precision. |
| -cl-denorms-are-zero | Allow denormalized numbers to be flushed to zero. |
| -cl-mad-enable | Allow a*b+c to be computed with potentially reduced accuracy. |
| -cl-no-signed-zeros | Allow optimizations that ignore the signedness of zero. |
| -cl-unsafe-math-optimizations | Allow optimizations that may violate IEEE 754 and OpenCL numerical compliance requirements. This option includes -cl-no-signed-zeros and cl-mad-enable. |
| -cl-finite-math-only | Allow optimizations that ignore NaNs and infinities. |
| -cl-fast-relaxed-math | Equivalent to -cl-finite-math-only and -cl-unsafe-math-optimizations. |
| -W | Inhibit all warning messages. |
| -Werror | Make all warnings into errors. |
The following methods are available for setting kernel arguments and querying kernel-specific information.
interface WebCLKernel {
any getInfo(CLenum name);
any getWorkGroupInfo(WebCLDevice device, CLenum name);
WebCLKernelArgInfo? getArgInfo(CLuint index);
void setArg(CLuint index, WebCLMemoryObject value);
void setArg(CLuint index, WebCLSampler value);
void setArg(CLuint index, ArrayBufferView value);
void release();
};
| name | return type |
|---|---|
| KERNEL_FUNCTION_NAME | DOMString |
| KERNEL_NUM_ARGS | CLuint |
| KERNEL_CONTEXT | WebCLContext |
| KERNEL_PROGRAM | WebCLProgram |
| name | return type |
|---|---|
| KERNEL_WORK_GROUP_SIZE | CLuint |
| KERNEL_COMPILE_WORK_GROUP_SIZE | sequence<CLuint> |
| KERNEL_LOCAL_MEM_SIZE | CLuint |
| KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE | CLuint |
| KERNEL_PRIVATE_MEM_SIZE | CLuint |
dictionary WebCLKernelArgInfo {
DOMString name;
DOMString typeName; // 'char', 'float', 'uint4', 'image2d', 'sampler', etc.
DOMString addressQualifier; // 'global', 'local', 'constant', or 'private'
DOMString accessQualifier; // 'read_only', 'write_only', 'read_write', or 'none'
};
Sets the given `memObject` to the kernel argument at the given `index`. Legal values for `index` range from zero to `N-1`, where `N` is the total number of arguments declared by the kernel.
Sets the given `sampler` to the kernel argument at the given `index`. Legal values for `index` range from zero to `N-1`, where `N` is the total number of arguments declared by the kernel.
Sets the given `value` to the kernel argument at the given `index`. Legal values for `index` range from zero to `N-1`, where `N` is the total number of arguments declared by the kernel.
The type and length of `value` must match the base type and vector width of the target kernel argument. For example, if the kernel argument is of type `float4`, then `value` must be a Float32Array of length 4. Arguments with the `local` address space qualifier must be set using a Uint32Array of length 1, specifying the number of bytes to be allocated.
Since there is no 64-bit integer variant of ArrayBufferView, 64-bit integers must be represented as pairs of 32-bit unsigned integers. The low-order 32 bits are stored in the first element of each pair, and the high-order 32 bits in the second element.
myKernel.setArg(0, 3.14159); // ERROR: Passing in a Number is not allowed myKernel.setArg(0, new Float32Array([3.14159])); // cast 3.14159 to `float`, then pass to kernel as arg #0 myKernel.setArg(1, new Uint32Array([1.23, 2.34])); // cast the numbers to `uint2`, then pass to kernel as arg #1 myKernel.setArg(2, new Uint32Array([512])); // reserve 512 bytes of local memory for arg #2 myKernel.setArg(3, myImage); // pass `myImage` to kernel as arg #3
interface WebCLEvent {
any getInfo(CLenum name);
any getProfilingInfo(CLenum name);
void setCallback(CLenum commandExecCallbackType, WebCLCallback notify);
void release();
};
| name | return type |
|---|---|
| EVENT_COMMAND_QUEUE | WebCLCommandQueue |
| EVENT_CONTEXT | WebCLContext |
| EVENT_COMMAND_TYPE | CLenum |
| EVENT_COMMAND_EXECUTION_STATUS | CLenum |
| name | return type |
|---|---|
| PROFILING_COMMAND_QUEUED | CLuint |
| PROFILING_COMMAND_SUBMIT | CLuint |
| PROFILING_COMMAND_START | CLuint |
| PROFILING_COMMAND_END | CLuint |
interface WebCLUserEvent : WebCLEvent {
void setUserEventStatus(CLenum executionStatus);
};
WebCL implementations may expose a number of extensions to the core functionality. In addition to the official Khronos extensions that are described in the following subsections, each WebCL implementation may also support vendor-specific extensions that are documented elsewhere. Each extension, regardless of its standardization status, must be explicitly enabled by the application before it can be used. This policy is aimed to minimize inadvertant usage of features that are not universally available.
The set of available extensions may vary from one WebCLDevice to another, and one WebCLPlatform to another, even within the same system. For example, the WebGL Resource Sharing extension may be supported by the GPU but not the CPU. The names of extensions that are supported system-wide can be queried via `WebCL.getSupportedExtensions()`. Similarly, calling `getSupportedExtensions` on a particular WebCLPlatform returns the set of extensions that are supported by all devices on that platform. Finally, `getSupportedExtensions()` on an individual WebCLDevice returns the set of extensions that are supported by that device.
WebCL extensions can be enabled by calling `enableExtension` with the name of the desired extension as a string parameter. This returns `true` if the extension is successfully enabled, and `false` if not.
Calling enableExtension("KHR_fp64") enables the
cl_khr_fp64
extension. This allows the following pragma to be used in any
subsequently compiled kernels:
#pragma OPENCL EXTENSION cl_khr_fp64 : enable
partial interface WebCL {
/* WebCLDevice getInfo() */
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0x100B;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE = 0x103B;
};
Calling enableExtension("KHR_fp16") enables the
cl_khr_fp16
extension. This allows the following pragma to be used in any
subsequently compiled kernels:
#pragma OPENCL EXTENSION cl_khr_fp16 : enable
partial interface WebCL {
/* WebCLDevice getInfo() */
CLenum DEVICE_PREFERRED_VECTOR_WIDTH_HALF = 0x1034;
CLenum DEVICE_NATIVE_VECTOR_WIDTH_HALF = 0x103C;
};
The WebGL Resource Sharing extension allows applications to use
WebGL buffers, renderbuffers and textures as WebCL memory
objects. The extension is enabled by
calling enableExtension("KHR_gl_sharing"), after
which the application may create a WebCLContext that can share
resources with a given WebGLRenderingContext.
partial interface WebCLContext {
WebCLContext? createContext(WebGLRenderingContext gl, optional WebCLContextProperties properties);
/* Error Codes */
CLenum INVALID_GL_OBJECT = -60;
CLenum INVALID_MIP_LEVEL = -62;
CLenum INVALID_GL_SHAREGROUP_REFERENCE_KHR = TODO;
/* cl_command_type */
CLenum COMMAND_ACQUIRE_GL_OBJECTS = 0x11FF;
CLenum COMMAND_RELEASE_GL_OBJECTS = 0x1200;
/* cl_gl_object_type */
CLenum GL_OBJECT_BUFFER = 0x2000;
CLenum GL_OBJECT_TEXTURE2D = 0x2001;
CLenum GL_OBJECT_RENDERBUFFER = 0x2003;
/* cl_gl_texture_info */
CLenum GL_TEXTURE_TARGET = 0x2004;
CLenum GL_MIPMAP_LEVEL = 0x2005;
};
partial interface WebCLContext {
WebCLBuffer createFromGLBuffer(CLenum memFlags, WebGLBuffer buffer);
WebCLImage createFromGLRenderbuffer(CLenum memFlags, WebGLRenderbuffer renderbuffer);
WebCLImage createFromGLTexture(CLenum memFlags,
GLenum textureTarget,
CLint miplevel,
WebGLTexture texture);
};
miplevel < 0 || miplevel > q, where `q` is as defined in OpenGL ES 2.0miplevel > 0 and creating from non-zero mipmap levels is not supported
partial interface WebCLCommandQueue {
void enqueueAcquireGLObjects(sequence<WebCLMemoryObject> memObjects,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueReleaseGLObjects(sequence<WebCLMemoryObject> memObjects,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
};
partial interface WebCLMemoryObject {
WebCLGLObjectInfo getGLObjectInfo();
};
dictionary WebCLGLObjectInfo {
any glObject; // the GL object used to create this memory object, 'undefined' if none
CLenum type; // the type of GL object attached to this memory object, 'undefined' if none
GLenum textureTarget; // 'undefined' if there is no texture associated
CLint mipmapLevel; // 'undefined' if there is no texture associated
};
The HTML Resource Sharing extension makes it more convenient and
potentially faster for applications to transfer image data from
HTML Image/Canvas/Video elements to WebCL memory objects, and
vice versa. The extension is enabled by
calling enableExtension("WEBCL_html_sharing"), after
which the application may call the functions specified below.
A WebCLBuffer or WebCLImage can be initialized at construction time from an ImageData, Canvas, or Image element. This does not create a binding of any kind between the WebCL memory object and the data source. The source pixel format is treated as 32-bit RGBA (8 bits per component) with non-premultiplied alpha, regardless of the source. A newly created WebCLImage will have `channelOrder` equal to `RGBA`, `channelType` equal to `UNORM_INT8`, and width and height equal to the source width and height.
partial interface WebCLContext {
WebCLBuffer createBuffer(CLenum memFlags, ImageData srcPixels);
WebCLBuffer createBuffer(CLenum memFlags, HTMLCanvasElement srcCanvas);
WebCLBuffer createBuffer(CLenum memFlags, HTMLImageElement srcImage);
WebCLImage createImage(CLenum memFlags, ImageData srcPixels);
WebCLImage createImage(CLenum memFlags, HTMLCanvasElement srcCanvas);
WebCLImage createImage(CLenum memFlags, HTMLImageElement srcImage);
};
The size in bytes of a new WebCLBuffer is computed from the source as follows:
srcCanvas.getContext("2d").getImageData().data.length.
srcImage.width * srcImage.height * 4.
If the HTMLImageElement object is not fully loaded, `createBuffer` and `createImage` will throw an `INVALID_HOST_PTR` exception.
A WebCLImage can be permanently bound to an HTML Video element at construction time. The Video element does not have to be fully loaded at that time, but its dimensions must be known. Doing an `enqueueWriteImage` from a video element is only allowed when the video element is bound to the target WebCLImage. Note that `memFlags` must be equal to `MEM_READ_ONLY`.
partial interface WebCLContext {
WebCLImage createImage(CLenum memFlags, HTMLVideoElement srcVideo);
};
The source video pixel format is treated as 32-bit RGBA (8 bits per component) with non-premultiplied alpha. The newly created WebCLImage will have `channelOrder` equal to `RGBA`, `channelType` equal to `UNORM_INT8`, and width and height equal to the source video width and height.
partial interface WebCLCommandQueue {
//////////////////////////////////////////////////////////////////////
//
// Writing to WebCLBuffer
//
void enqueueWriteBuffer(
WebCLBuffer buffer,
CLboolean blockingWrite,
CLuint bufferOffset,
ImageData srcPixels,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBuffer(
WebCLBuffer buffer,
CLboolean blockingWrite,
CLuint bufferOffset,
HTMLCanvasElement srcCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBuffer(
WebCLBuffer buffer,
CLboolean blockingWrite,
CLuint bufferOffset,
HTMLImageElement srcImage,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBufferRect(
WebCLBuffer buffer,
CLboolean blockingWrite,
sequence<CLuint> bufferOrigin,
sequence<CLuint> srcOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
ImageData srcPixels,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBufferRect(
WebCLBuffer buffer,
CLboolean blockingWrite,
sequence<CLuint> bufferOrigin,
sequence<CLuint> srcOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
HTMLCanvasElement srcCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteBufferRect(
WebCLBuffer buffer,
CLboolean blockingWrite,
sequence<CLuint> bufferOrigin,
sequence<CLuint> srcOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
HTMLImageElement srcImage,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
//////////////////////////////////////////////////////////////////////
//
// Writing to WebCLImage
//
void enqueueWriteImage(
WebCLImage image,
CLboolean blockingWrite,
sequence<CLuint> origin,
sequence<CLuint> region,
ImageData srcPixels,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteImage(
WebCLImage image,
CLboolean blockingWrite,
sequence<CLuint> origin,
sequence<CLuint> region,
HTMLCanvasElement srcCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteImage(
WebCLImage image,
CLboolean blockingWrite,
sequence<CLuint> origin,
sequence<CLuint> region,
HTMLImageElement srcImage,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueWriteImage(
WebCLImage image,
CLboolean blockingWrite,
sequence<CLuint> origin,
sequence<CLuint> region,
HTMLVideoElement srcVideo,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
//////////////////////////////////////////////////////////////////////
//
// Reading from WebCL
//
void enqueueReadBuffer(
WebCLBuffer buffer,
CLboolean blockingRead,
CLuint bufferOffset,
CLuint numBytes,
HTMLCanvasElement dstCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueReadBufferRect(
WebCLBuffer buffer,
CLboolean blockingRead,
sequence<CLuint> bufferOrigin,
sequence<CLuint> dstOrigin,
sequence<CLuint> region,
CLuint bufferRowPitch,
HTMLCanvasElement dstCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
void enqueueReadImage(
WebCLImage image,
CLboolean blockingRead,
sequence<CLuint> origin,
sequence<CLuint> region,
HTMLCanvasElement dstCanvas,
optional sequence<WebCLEvent>? eventWaitList,
optional WebCLEvent? event);
};
The Validation Info Query extension, enabled by
enableExtension("WEBCL_validation_info"), allows
applications to retrieve the results of kernel program
validation, including error messages, warnings, logs, and
instrumented source code. The results become available after
building (or attempting to build) a WebCLProgram. Validation
can also be triggered manually by calling the `validate` method
provided in this extension.
partial interface WebCLProgram {
void validate(optional sequence<WebCLDevice> devices,
optional DOMString? options,
optional WebCLCallback whenFinished);
CLint getValidationStatus();
DOMString? getValidationErrors();
DOMString? getValidationWarnings();
DOMString? getValidationInfo();
DOMString? getValidatedSource();
};
| Validator option | Description |
|---|---|
| -D name | Equivalent to #define name in OpenCL C. |
| -D name=definition | Equivalent to #define name definition in OpenCL C. |
| -cl-opt-disable | Disable all optimizations. |
| -W | Inhibit all warning messages. |
| -Werror | Make all warnings into errors. |
To promote robustness of the WebCL standard, the working group is actively working on identifying and remediating potential vulnerabilities. Depending upon the nature of the issue, the remediation may need to be addressed by the OpenCL Working Group or the WebCL Working Group, or both. The working group has identified the following security requirements for WebCL.
WebCL kernels must not be able to access unauthorized areas of memory, regardless of address space (private, local, global, or constant). If detected during compilation, out-of-bounds (OOB) accesses must generate a compiler error. At runtime, OOB reads must return zero and writes must be discarded. Alternatively, the kernel may be terminated and an exception be thrown.
For purposes of bounds checking, the implementation may treat all `private` variables as one contiguous block of memory, and similarly for `local` variables, instead of enforcing the bounds of each variable separately. For example, in a kernel program containing two `private` arrays, an OOB read from the first array is allowed to return any value from either the first or the second array, rather than zero.
WebCL will restrict the use of media, such as image and video, originating from a different web site than the hosting web page. WebCL will leverage provisions such as Cross-Origin Resource Sharing [CORS] to help enforce the restriction on the use of media by a web page different than the originating web site.
To prevent information leakage from un-initialized memory, all WebCL allocated memory objects (buffers and images), inclusive of private and local variables in kernel code, must be initialized at allocation time (before the application is allowed to use them). To minimize the performance burden on applications for initializing allocated memory to zeroes, WebCL implementations will ensure that memory is initialized to a pre-defined value at allocation time.
WebCL implementations must ensure that no information can leak from one WebCL/OpenCL context to another. It must not be possible for WebCL kernels or host code to access arbitrary system memory, or memory from another OpenCL/WebCL context.
Long running and/or computationally intensive kernels may cause the system to become unresponsive, and can lead to denial of service. It is not acceptable for content downloaded over the internet to lock up the browser. To prevent bugs/issues in unknown and untrusted code from monopolizing an OpenCL device and making it unresponsive, WebCL implementations need to be able to:
Although WebCL is based on OpenCL 1.1 (Embedded Profile), it can also be implemented on top of OpenCL 1.2, or any future version that remains backwards compatible with OpenCL 1.1.
The WebCL specification and conformance tests are written with the assumption that implementations will be based on conformant OpenCL drivers. Implementations are strongly recommended to support dynamic black-listing of malfunctioning or vulnerable OpenCL drivers in order to quickly eliminate any security or stability issues.
This section describes changes made to the WebCL API and the kernel programming language, relative to OpenCL 1.1 Embedded Profile. The main differences are as follows:
To promote application portability, WebCL not only defines a certain set of minimum capabilities that the platform must provide (these are generally the same as in OpenCL 1.1 Embedded Profile), but also allows implementations, at their discretion, to hide certain query properties that might be misused to target an application for specific hardware/software configurations. The always available and optionally available query properties, as well as their baseline values, are shown in the tables below.
| Platform Info: clGetPlatformInfo Parameter | OpenCL 1.1 Embedded Profile | WebCL |
|---|---|---|
| PLATFORM_PROFILE | "EMBEDDED_PROFILE" | "WEBCL_PROFILE" |
| PLATFORM_VERSION | "OpenCL 1.1" + optional vendor string | "WebCL 1.0" |
| PLATFORM_NAME | Not Specified | Optionally Visible |
| PLATFORM_VENDOR | Not Specified | Optionally Visible |
| PLATFORM_EXTENSIONS | Extension String | Optionally Visible |
| Device Info: clGetDeviceInfo Parameter | OpenCL 1.1 Embedded Profile | WebCL |
|---|---|---|
| DEVICE_TYPE | DEVICE_TYPE_CPU; DEVIDE_TYPE_GPU; DEVICE_TYPE_ACCELERATOR; DEVICE_TYPE_DEFAULT; (Or a combination of the above) | Visible |
| DEVICE_VENDOR_ID | Not Specified | Optionally Visible |
| DEVICE_MAX_COMPUTE_UNITS | >=1 | Visible |
| DEVICE_MAX_WORK_ITEM_DIMENSIONS | >=3 | Visible |
| DEVICE_MAX_WORK_ITEM_SIZES | >=(1, 1, 1) | Visible |
| DEVICE_MAX_WORK_GROUP_SIZE | >=1 | Visible |
| DEVICE_PREFERRED_VECTOR_WIDTH_* (*=CHAR, SHORT, INT, LONG, FLOAT, DOUBLE, HALF) | cl_uint | Visible |
| DEVICE_NATIVE_VECTOR_WIDTH_* | cl_uint | Optionally Visible |
| DEVICE_MAX_CLOCK_FREQUENCY | cl_uint | Optionally Visible |
| DEVICE_ADDRESS_BITS | 32 or 64 bits | Visible |
| DEVICE_MAX_MEM_ALLOC_SIZE | >= max(DEVICE_GLOBAL_MEM_SIZE/4, 1 MB) | Visible |
| DEVICE_IMAGE_SUPPORT | cl_bool | TRUE |
| DEVICE_MAX_READ_IMAGE_ARGS | >=8 (if image support) | Visible |
| DEVICE_MAX_WRITE_IMAGE_ARGS | >=1 (if image support) | Visible |
| DEVICE_IMAGE2D_MAX_WIDTH | >=2048 (if image support) | Visible |
| DEVICE_IMAGE2D_MAX_HEIGHT | >=2048 (if image support) | Visible |
| DEVICE_IMAGE3D_MAX_WIDTH | >=2048 (if 3D image support) | 0 (not supported) |
| DEVICE_IMAGE3D_MAX_HEIGHT | >=2048 (if 3D image support) | 0 (not supported) |
| DEVICE_IMAGE3D_MAX_DEPTH | >=2048 (if 3D image support) | 0 (not supported) |
| DEVICE_MAX_SAMPLERS | >=8 (if image support) | Visible |
| DEVICE_MAX_PARAMETER_SIZE | >=256 | Visible |
| DEVICE_MEM_BASE_ADDR_ALIGN | >= num bits(int16) | Visible |
| DEVICE_MIN_DATA_TYPE_ALIGN_SIZE | >=sizeof(int16) | Removed |
| DEVICE_SINGLE_FP_CONFIG | FP_ROUND_TO_NEAREST; FP_INF_NAN (others optional) | Visible |
| DEVICE_GLOBAL_MEM_CACHE_TYPE | NONE; READ_ONLY_CACHE; READ_WRITE_CACHE | Visible |
| DEVICE_GLOBAL_MEM_CACHELINE_SIZE | cl_uint | Visible |
| DEVICE_GLOBAL_MEM_CACHE_SIZE | cl_uint | Visible |
| DEVICE_GLOBAL_MEM_SIZE | cl_uint | Visible |
| DEVICE_MAX_CONSTANT_BUFFER_SIZE | >=1 KB | Visible |
| DEVICE_MAX_CONSTANT_ARGS | >=4 | Visible |
| DEVICE_LOCAL_MEM_TYPE | LOCAL; GLOBAL | Visible |
| DEVICE_LOCAL_MEM_SIZE | >=1 KB | Visible |
| DEVICE_ERROR_CORRECTION_SUPPORT | cl_bool | Visible |
| DEVICE_HOST_UNIFIED_MEMORY | cl_bool | Visible |
| DEVICE_PROFILING_TIMER_RESOLUTION | size_t | Visible |
| DEVICE_ENDIAN_LITTLE | cl_bool | Visible |
| DEVICE_AVAILABLE | cl_bool | Visible |
| DEVICE_COMPILER_AVAILABLE | cl_bool | Visible |
| DEVICE_EXECUTION_CAPABILITIES | EXEC_KERNEL; EXEC_NATIVE_KERNEL | EXEC_KERNEL |
| DEVICE_QUEUE_PROPERTIES | QUEUE_PROFILING_ENABLE; QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE (optional) | Visible |
| DEVICE_PLATFORM | cl_platform_id | Visible |
| DEVICE_NAME | Not Specified | Optionally Visible |
| DEVICE_VENDOR | Not Specified | Optionally Visible |
| DRIVER_VERSION | Version String | Optionally Visible |
| DEVICE_PROFILE | "EMBEDDED_PROFILE" | "WEBCL_PROFILE" |
| DEVICE_VERSION | Version String | "WebCL 1.0" |
| DEVICE_OPENCL_C_VERSION | Version String | Visible |
| DEVICE_EXTENSIONS | Extension String | Optionally Visible |
WebCL supports the minimum set of image formats and image data types allowed by OpenCL 1.1 Embedded Profile. Browsers may provide extensions to support other formats.
| channelOrder | channelType |
|---|---|
| RGBA | UNORM_INT8 UNORM_INT16 SIGNED_INT8 SIGNED_INT16 SIGNED_INT32 UNSIGNED_INT8 UNSIGNED_INT16 UNSIGNED_INT32 HALF_FLOAT FLOAT |
This Working Draft is produced by the Khronos WebCL Working Group.
Special thanks to: ...
Additional thanks to: ... and the members of the Khronos WebCL Working Group.