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;
};
null if a suitable context could not be
created. The properties parameter can be omitted, in which
case the implementation will decide which platform and device
to use.
INVALID_DEVICE -- if properties.devices is non-null, but is not an array of valid device objectsINVALID_DEVICE -- if any devices in properties.devices are on different platformsINVALID_PLATFORM -- if properties.platform is non-null, but is not a valid platform objectDEVICE_NOT_AVAILABLE -- if a device in properties.devices is currently not availableenableExtension, must
enable the corresponding extension.
true if the extension is successfully
enabled, or false if not. The available extension names can
be queried by getSupportedExtensions.
INVALID_VALUE -- if eventWaitList is null or emptyINVALID_CONTEXT -- if events specified in
eventWaitList do not belong to the same contextINVALID_EVENT -- if any event in eventWaitList is
not a valid event objectINVALID_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST --
if the execution status of any of the events in
eventWaitList is a negative integer valuedictionary 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
};
null, it must not be empty, and must not contain
elements of any other type than WebCLDevice. The given
devices must be on the same platform. If the array is null,
the implementation will decide which device (on the given
platform and/or with the given deviceType) to use.
devices is non-null. If this field is null, the
implementation will decide which platform to use. Note that
in typical systems, there is only one WebCLPlatform.
devices is non-null. If there is no device of
the given type on the given platform, createContext will
return null. If platform is null, createContext will
select any device on any platform that matches the given type,
or failing that, will return null.
| 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);
};
DEVICE_TYPE_ALL.
| 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. |
INVALID_VALUE -- if deviceType is given, but is not one of the valid enumerated values listed in the table aboveDEVICE_NOT_FOUND -- if there is no WebCLDevice available that matches the given deviceTypeINVALID_VALUE -- if name is not one of the valid enumerated valuesenableExtension on this platform, or any device
on this platform, must enable the corresponding extension.
true if the extension is successfully enabled, or
false if not. The available extension names can be queried
by getSupportedExtensions.
interface WebCLDevice {
any getInfo(CLenum name);
sequence<DOMString>? getSupportedExtensions();
CLboolean enableExtension(DOMString extensionName);
};
INVALID_VALUE -- if name is not one of the valid enumerated valuesenableExtension, must enable the corresponding extension.
true if the extension is successfully enabled, or
false if not. The available extension names can be queried
by getSupportedExtensions.
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,
and optionally fills it with data from the given ArrayBufferView.
INVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_BUFFER_SIZE -- if sizeInBytes == 0 || sizeInBytes > DEVICE_MAX_MEM_ALLOC_SIZEINVALID_HOST_PTR -- if hostPtr.byteLength < sizeInBytesdevice
is null, the WebCL implementation will select any
WebCLDevice that matches the given properties and is covered
by this WebCLContext. If properties is omitted, the command
queue is created with out-of-order execution disabled and
profiling disabled.
INVALID_DEVICE -- if device is invalid or not associated with this contextINVALID_VALUE -- if values specified in properties are not validINVALID_QUEUE_PROPERTIES -- if values specified in properties are valid but not supported by the devicedescriptor, and optionally fills it with data from the
given ArrayBufferView.
INVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_IMAGE_SIZE -- if descriptor.width == 0 || descriptor.width > DEVICE_IMAGE2D_MAX_WIDTH
INVALID_IMAGE_SIZE -- if descriptor.height == 0 || descriptor.height > DEVICE_IMAGE2D_MAX_HEIGHT
INVALID_HOST_PTR -- if hostPtr.byteLength < descriptor.rowPitch * descriptor.heightINVALID_IMAGE_FORMAT_DESCRIPTOR -- if descriptor.channelOrder or descriptor.channelType is not validIMAGE_FORMAT_NOT_SUPPORTED -- if the given combination channelOrder, channelType and memFlags is not supported by this WebCLContextINVALID_VALUE -- if source is null or emptyADDRESS_NONE mode
is not available, due to its lack of bounds checking.
INVALID_VALUE -- if addressingMode is not
ADDRESS_CLAMP, ADDRESS_CLAMP_TO_EDGE,
ADDRESS_REPEAT, or ADDRESS_MIRRORED_REPEATINVALID_VALUE -- if filterMode is not
FILTER_NEAREST or FILTER_LINEARINVALID_VALUE -- if normalizedCoords is false and
addressingMode is ADDRESS_REPEAT or
ADDRESS_MIRRORED_REPEAT| name | return type |
|---|---|
| CONTEXT_NUM_DEVICES | CLuint |
| CONTEXT_DEVICES | sequence<WebCLDevice> |
| CONTEXT_PROPERTIES | WebCLContextProperties |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table abovememFlags. For example, passing
in MEM_READ_WRITE will return a list of image formats that
are available for both reading and writing in kernel code.
The returned WebCLImageDescriptor objects will only have the
channelOrder and channelType fields filled in; the other
fields will have their default value (zero).
INVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYinterface 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();
};
INVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as srcBuffer and
dstBufferINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitListINVALID_MEM_OBJECT -- if srcBuffer and dstBuffer
are not valid WebCLBuffer objectsINVALID_VALUE -- if srcOffset, dstOffset,
numBytes, srcOffset+numBytes, or
dstOffset+numBytes require accessing elements outside
the srcBuffer and dstBuffer buffer objects
respectively
INVALID_EVENT_WAIT_LIST -- if any event in
eventWaitList is invalidMEM_COPY_OVERLAP -- if srcBuffer and dstBuffer are
the same WebCLBuffer object and the source and destination
regions overlapMISALIGNED_SUB_BUFFER_OFFSET -- if srcBuffer or
dstBuffer is a sub-buffer object and the offset
specified when the sub-buffer object was created is not
aligned to the DEVICE_MEM_BASE_ADDR_ALIGN value for the
device associated with this WebCLCommandQueueMEM_OBJECT_ALLOCATION_FAILURE -- if there is a failure
to allocate memory for data store associated with
srcBuffer or dstBufferINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as srcBuffer and dstBufferINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_MEM_OBJECT -- if srcBuffer and dstBuffer are not valid WebCLBuffer objectsINVALID_VALUE -- if srcOrigin, dstOrigin, or region does not have exactly two elementsINVALID_VALUE -- if the origin, region and pitch
values would require accessing elements outside the
srcBuffer or dstBuffer objectsINVALID_EVENT_WAIT_LIST -- if any event in
eventWaitList is invalidMEM_COPY_OVERLAP -- if srcBuffer and dstBuffer are
the same WebCLBuffer object and the source and destination
regions overlapMISALIGNED_SUB_BUFFER_OFFSET -- if srcBuffer or
dstBuffer is a sub-buffer object and the offset
specified when the sub-buffer object was created is not
aligned to the DEVICE_MEM_BASE_ADDR_ALIGN value for the
device associated with this WebCLCommandQueueINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as srcImage and
dstImageINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitList orINVALID_MEM_OBJECT -- if srcImage or dstImage is
not a valid image objectIMAGE_FORMAT_MISMATCH -- if srcImage and dstImage
do not have the same image formatINVALID_VALUE -- if the srcOrigin, dstOrigin and
region values would require accessing elements outside
the boundaries of srcImage or dstImageINVALID_VALUE -- if srcOrigin, dstOrigin, or
region does not have exactly two elementsINVALID_EVENT_WAIT_LIST -- if any event in
eventWaitList is invalidINVALID_IMAGE_SIZE -- if the image dimensions of
srcImage or dstImage are not supported by the device
associated with this WebCLCommandQueueMEM_OBJECT_ALLOCATION_FAILURE -- if there is a failure
to allocate memory for data store associated with
srcImage or dstImageMEM_COPY_OVERLAP -- if srcImage and dstImage are
the same WebCLImage object and the source and destination
regions overlapINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as srcBuffer and
dstImageINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitListINVALID_MEM_OBJECT -- if srcBuffer is not a valid
buffer object or dstImage is not a valid image
objectINVALID_VALUE -- if dstOrigin or dstRegion does
not have exactly two elementsINVALID_VALUE -- if the srcOffset, dstOrigin and
dstRegion values would require accessing elements
outside the boundaries of srcBuffer or dstImageINVALID_EVENT_WAIT_LIST -- if any event in
eventWaitList is invalidINVALID_IMAGE_SIZE -- if the image dimensions of
dstImage are not supported by the device associated with
this WebCLCommandQueueMEM_OBJECT_ALLOCATION_FAILURE -- if there is a failure
to allocate memory for data store associated with
srcBuffer or dstImageINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as srcImage and
dstBufferINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitListINVALID_MEM_OBJECT -- if srcImage is not a valid
image object or dstBuffer is not a valid buffer
objectINVALID_VALUE -- if srcOrigin or srcRegion does
not have exactly two elementsINVALID_VALUE -- if the srcOrigin, srcRegion and
dstOffset values would require accessing elements
outside the boundaries of srcImage or dstBufferINVALID_EVENT_WAIT_LIST -- if any event in
eventWaitList is invalidINVALID_IMAGE_SIZE -- if the image dimensions of
srcImage are not supported by the device associated with
this WebCLCommandQueueMEM_OBJECT_ALLOCATION_FAILURE -- if there is a failure
to allocate memory for data store associated with
srcImage or dstBufferINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as bufferINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitListINVALID_MEM_OBJECT -- if buffer is not a valid
buffer objectINVALID_VALUE -- if any part of the region being read,
specified by bufferOffset and numBytes, is out of
bounds of bufferINVALID_VALUE -- if any part of the region being
written, specified by hostPtr and numBytes is out of
bounds of hostPtrINVALID_VALUE -- if numBytes %
hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if
blockingRead is true and the execution status of any
event in eventWaitList is a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as bufferINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_MEM_OBJECT -- if buffer is not a valid WebCLBuffer objectINVALID_VALUE -- if bufferOrigin, hostOrigin, or
region does not have exactly three elementsINVALID_VALUE -- if any part of the region being read,
specified by bufferOrigin, region, bufferRowPitch and
bufferSlicePitch, is out of bounds of bufferINVALID_VALUE -- if any part of the region being
written, specified by hostOrigin, region, hostRowPitch
and hostSlicePitch, is out of bounds of hostPtrINVALID_VALUE -- if host{Row,Slice}Pitch %
hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if
blockingRead is true and the execution status of any
event in eventWaitList is a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as imageINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_MEM_OBJECT -- if image is not a valid WebCLImage objectINVALID_IMAGE_SIZE -- if the image dimensions of image are not supported by this WebCLCommandQueueINVALID_VALUE -- if origin or region does not have exactly two elementsINVALID_VALUE -- if any part of the region being read, specified by origin and region, is out of bounds of imageINVALID_VALUE -- if any part of the region being written, specified by region and hostRowPitch, is out of bounds of hostPtrINVALID_VALUE -- if hostRowPitch % hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if blockingRead is true and the execution status of any event
in eventWaitListis a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as bufferINVALID_CONTEXT -- if this WebCLCommandQueue is not
associated with the same WebCLContext as all events in
eventWaitListINVALID_MEM_OBJECT -- if buffer is not a valid
buffer objectINVALID_VALUE -- if any part of the region being
written, specified by bufferOffset and numBytes, is
out of bounds of bufferINVALID_VALUE -- if any part of the region being read,
specified by hostPtr and numBytes, is out of bounds of
hostPtrINVALID_VALUE -- if numBytes %
hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if
blockingWrite is true and the execution status of any
event in eventWaitList is a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as bufferINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_MEM_OBJECT -- if buffer is not a valid WebCLBuffer objectINVALID_VALUE -- if bufferOrigin, hostOrigin, or
region does not have exactly three elementsINVALID_VALUE -- if any part of the region being written,
specified by bufferOrigin, region, bufferRowPitch and
bufferSlicePitch, is out of bounds of bufferINVALID_VALUE -- if any part of the region being
read, specified by hostOrigin, region, hostRowPitch
and hostSlicePitch, is out of bounds of hostPtrINVALID_VALUE -- if host{Row,Slice}Pitch %
hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if
blockingWrite is true and the execution status of any
event in eventWaitList is a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as imageINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_MEM_OBJECT -- if image is not a valid WebCLImage objectINVALID_IMAGE_SIZE -- if the image dimensions of image are not supported by this WebCLCommandQueueINVALID_VALUE -- if origin or region does not have exactly two elementsINVALID_VALUE -- if any part of the region being read, specified by origin and region, is out of bounds of imageINVALID_VALUE -- if any part of the region being written, specified by region and hostRowPitch, is out of bounds of hostPtrINVALID_VALUE -- if hostRowPitch % hostPtr.BYTES_PER_ELEMENT !== 0INVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidEXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST -- if
blockingWrite is true and the execution status of any
event in eventWaitListis a negative integer valueINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as kernelINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_KERNEL -- if kernel is not a valid WebCLKernel objectINVALID_PROGRAM_EXECUTABLE -- if there is no
successfully built program executable of kernel
available for the device associated with this
WebCLCommandQueueINVALID_KERNEL_ARGS -- if any kernel argument values have not been specified for kernelINVALID_WORK_DIMENSION -- if workDim is not equal to 1, 2, or 3INVALID_GLOBAL_WORK_SIZE -- if globalWorkSize.length != workDimINVALID_GLOBAL_WORK_SIZE -- if globalWorkSize[i] > 232-1 for any iINVALID_GLOBAL_OFFSET -- if globalWorkOffset.length != workDimINVALID_GLOBAL_OFFSET -- if globalWorkSize[i] + globalWorkOffset[i] > 232-1 for any iINVALID_WORK_GROUP_SIZE -- if localWorkSize.length != workDimINVALID_WORK_GROUP_SIZE -- if globalWorkSize[i] % localWorkSize[i] !== 0 for any iINVALID_WORK_GROUP_SIZE -- if localWorkSize[i] !== requiredSize[i] for any i, where
requiredSize is specified using the reqd_work_group_size qualifier in kernel sourceINVALID_WORK_GROUP_SIZE -- if localWorkSize is
null and the reqd_work_group_size qualifier is given
in kernel sourceINVALID_WORK_GROUP_SIZE -- if the total number of
work-items in a work-group (that is, the product of all
elements in localWorkSize) is greater than the value of
DEVICE_MAX_WORK_GROUP_SIZE queried from the device
associated with this queueINVALID_WORK_ITEM_SIZE -- if localWorkSize[i] > DEVICE_MAX_WORK_ITEM_SIZES[i] for any iINVALID_IMAGE_SIZE -- if an image object is specified as an argument to kernel, and the image dimensions
(width, height, pitch) are not supported by the device associated with this queueMEM_OBJECT_ALLOCATION_FAILURE -- if there is a failure to allocate memory for data store associated with
image or buffer objects specified as arguments to kernelINVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidINVALID_VALUE -- if event is not a valid WebCLEvent objectINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with the same WebCLContext as all events in eventWaitListINVALID_EVENT_WAIT_LIST -- if eventWaitList is empty or contains any invalid events| name | return type |
|---|---|
| QUEUE_CONTEXT | WebCLContext |
| QUEUE_DEVICE | WebCLDevice |
| QUEUE_PROPERTIES | CLenum |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above// 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 |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above
interface WebCLBuffer : WebCLMemoryObject {
WebCLBuffer createSubBuffer(CLenum memFlags, CLuint origin, CLuint sizeInBytes);
};
INVALID_MEM_OBJECT -- if this WebCLBuffer is already a sub-buffer objectINVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_VALUE -- if the region specified by (origin, sizeInBytes) is out of bounds in this WebCLBufferMISALIGNED_SUB_BUFFER_OFFSET -- if there is any
WebCLDevice in the WebCLContext associated with this
WebCLBuffer for which the given origin value would
result in an improperly aligned sub-buffer
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 |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above
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 |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above| name | return type |
|---|---|
| PROGRAM_BUILD_STATUS | CLint |
| PROGRAM_BUILD_OPTIONS | DOMString |
| PROGRAM_BUILD_LOG | DOMString |
INVALID_DEVICE -- if device is not associated with this WebCLProgramINVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above| 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. |
INVALID_DEVICE -- if any element in devices is not a valid WebCLDeviceINVALID_DEVICE -- if any device in devices is not associated with the WebCLContext of this WebCLProgramINVALID_BUILD_OPTIONS -- if the build options specified by options are invalidINVALID_OPERATION -- if a previous build of this
WebCLProgram for any of the devices listed in devices
has not completedBUILD_PROGRAM_FAILURE -- if there is a failure to build the program executableINVALID_OPERATION -- if there are WebCLKernel objects
already attached to this WebCLProgramINVALID_PROGRAM_EXECUTABLE -- if there is no successfully built executable for any device in this WebCLProgramINVALID_KERNEL_NAME -- if a kernel by the given name is not found in this WebCLProgramINVALID_KERNEL_DEFINITION -- if the function
definition of the given kernel function (name), such as
the number of arguments and the argument types, are not
the same for all devices for which the program executable
has been builtINVALID_PROGRAM_EXECUTABLE -- if there is no successfully built executable for any device in this WebCLProgramThe 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 |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table abovename and device.
| 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 |
INVALID_DEVICE -- if device is not associated with this WebCLKernelINVALID_DEVICE -- if device is null but there is more than one WebCLDevice associated with this WebCLKernelINVALID_VALUE -- if name is not one of the valid enumerated values listed in the table abovenull if index is not a valid argument index for
this WebCLKernel. Legal values for index range from zero to
N-1, where N is the total number of arguments declared by
the kernel.
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.
INVALID_ARG_INDEX -- if index is not a valid argument index for this WebCLKernelINVALID_ARG_VALUE -- if the expected kernel argument at index is not a memory objectINVALID_MEM_OBJECT -- if memObject is not a valid WebCLMemoryObject
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.
INVALID_ARG_INDEX -- if index is not a valid argument index for this WebCLKernelINVALID_ARG_VALUE -- if the expected kernel argument at index is not a samplerINVALID_SAMPLER -- if sampler is not a valid WebCLSampler
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.
INVALID_ARG_INDEX -- if index is not a valid argument index for this WebCLKernelINVALID_ARG_VALUE -- if the expected kernel argument at index is not a scalar, vector, or local memory sizeINVALID_ARG_VALUE -- if value.length is not 1, 2, 3, 4, 8, 16, or 32INVALID_ARG_VALUE -- if value.length is not equal to the vector width of the kernel argument at index,
or twice the vector width in case of a 64-bit integer argumentINVALID_ARG_VALUE -- if the kernel argument at index
has the local address space qualifier, and value is
not a Uint32Array of length 1myKernel.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 |
INVALID_VALUE -- if name is not one of the valid enumerated values listed in the table above| name | return type |
|---|---|
| PROFILING_COMMAND_QUEUED | CLuint |
| PROFILING_COMMAND_SUBMIT | CLuint |
| PROFILING_COMMAND_START | CLuint |
| PROFILING_COMMAND_END | CLuint |
PROFILING_INFO_NOT_AVAILABLE -- if the QUEUE_PROFILING_ENABLE flag is not set for this WebCLCommandQueuePROFILING_INFO_NOT_AVAILABLE -- if the execution status of this WebCLEvent is not COMPLETEPROFILING_INFO_NOT_AVAILABLE -- if this WebCLEvent is a user event objectINVALID_VALUE -- if name is not one of the valid enumerated values listed in the table abovenotify to be called when this
WebCLEvent reaches the given commandExecCallbackType status
(COMPLETE, RUNNING, SUBMITTED, or QUEUED). In this
version of WebCL, only the COMPLETE status is supported.
INVALID_VALUE -- if commandExecCallbackType is not COMPLETEinterface WebCLUserEvent : WebCLEvent {
void setUserEventStatus(CLenum executionStatus);
};
INVALID_VALUE -- if executionStatus is not COMPLETE or a negative integer valueINVALID_OPERATION -- if the execution status of this
event has already been changed by a previous call to
setUserEventStatusWebCL 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;
};
null
if such a context could not be created. If there are multiple
WebCLDevices that can interoperate with the given GL context
and that satisfy the constraints of the given properties,
the implementation will choose the WebCLDevice that it deems
best suited for interoperating with the given GL context. The
properties parameter can be omitted, in which case the
implementation will decide which platform and device to use.
WEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_DEVICE -- if properties.devices is non-null, but is not an array of valid device objectsINVALID_DEVICE -- if any devices in properties.devices are on different platformsINVALID_DEVICE -- if any device in properties.devices is not compatible with glINVALID_PLATFORM -- if properties.platform is non-null, but is not a valid platform objectINVALID_PLATFORM -- if no device on properties.platform is compatible with glDEVICE_NOT_AVAILABLE -- if a device in properties.devices is currently not availableINVALID_GL_SHAREGROUP_REFERENCE_KHR -- if gl is not a valid WebGLRenderingContextpartial interface WebCLContext {
WebCLBuffer createFromGLBuffer(CLenum memFlags, WebGLBuffer buffer);
WebCLImage createFromGLRenderbuffer(CLenum memFlags, WebGLRenderbuffer renderbuffer);
WebCLImage createFromGLTexture(CLenum memFlags,
GLenum textureTarget,
CLint miplevel,
WebGLTexture texture);
};
WEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_CONTEXT -- if this WebCLContext is not associated with a WebGLRenderingContextINVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_GL_OBJECT -- if buffer is not a valid WebGLBufferWEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_CONTEXT -- if this WebCLContext is not associated with a WebGLRenderingContextINVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_GL_OBJECT -- if renderbuffer is not a valid WebGLRenderbuffer, or has zero width or heightINVALID_IMAGE_FORMAT_DESCRIPTOR -- if the internal format of renderbuffer does not map to a supported WebCL image formatINVALID_OPERATION -- if renderbuffer is a multi-sample WebGLRenderbuffer objectWEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_CONTEXT -- if this WebCLContext is not associated with a WebGLRenderingContextINVALID_VALUE -- if memFlags is not MEM_READ_WRITE, MEM_WRITE_ONLY, or MEM_READ_ONLYINVALID_VALUE -- if textureTarget is not TEXTURE_2D or one of TEXTURE_CUBE_MAP_*INVALID_MIP_LEVEL -- if miplevel < 0 || miplevel > q, where q is as defined in OpenGL ES 2.0INVALID_MIP_LEVEL -- if miplevel > 0 and creating from non-zero mipmap levels is not supportedINVALID_GL_OBJECT -- if texture is not a valid WebGLTexture, or does not match the given textureTargetINVALID_GL_OBJECT -- if the specified miplevel is not defined for texture, or has zero width or heightINVALID_IMAGE_FORMAT_DESCRIPTOR -- if the internal format of texture does not map to a supported WebCL image formatpartial 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);
};
WEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with a WebGLRenderingContextINVALID_GL_OBJECT -- if any element in memObjects was not created from a GL objectINVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidWEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabledINVALID_CONTEXT -- if this WebCLCommandQueue is not associated with a WebGLRenderingContextINVALID_GL_OBJECT -- if any element in memObjects was not created from a GL objectINVALID_EVENT_WAIT_LIST -- if any event in eventWaitList is invalidpartial interface WebCLMemoryObject {
WebCLGLObjectInfo getGLObjectInfo();
};
WEBCL_EXTENSION_NOT_ENABLED -- if the KHR_gl_sharing extension has not been enabled
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:
srcPixels.data.length.
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);
};
INVALID_HOST_PTR -- if srcImage is not fully loadedINVALID_HOST_PTR -- if srcVideo is not bound to the given image
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. |
WEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledINVALID_DEVICE -- if any element in devices is not a valid WebCLDeviceINVALID_DEVICE -- if any device in devices is not associated with the WebCLContext of this WebCLProgramINVALID_BUILD_OPTIONS -- if the validator options specified by options are invalidINVALID_OPERATION -- if a previous validation of this
WebCLProgram for any of the devices listed in devices
has not completedBUILD_PROGRAM_FAILURE -- if there is a failure to validate the programWEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledWEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledWEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledWEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledWEBCL_EXTENSION_NOT_ENABLED -- if the WEBCL_validation_info extension has not been enabledTo 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:
ADDRESS_NONE sampler addressing mode is not supportedclEnqueueTaskclEnqueueNativeKernelclCreateImage3DclCreateProgramWithBinaryclEnqueueMapBufferclEnqueueMapImageclEnqueueUnmapMemObjectclSetMemObjectDestructorCallbackclUnloadCompilerasync_work_group_copyasync_work_group_strided_copywait_group_eventsTo 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.