WebCL KHR_gl_sharing Extension Specification

Name

KHR_gl_sharing

Contact

WebCL working group (public_webcl 'at' khronos.org)

Contributors

Tomi Aarnio, Nokia Research

Mikael Bourges-Sevenier, Advanced Micro Devices

Steven Eliuk, Samsung Electronics

Tasneem Brutch, Samsung Electronics

Members of the WebCL working group

Version

Last modified date: August 14, 2014
Revision: 4

Number

WebCL extension #4

Dependencies

Written against the WebCL API 1.0 specification.

Overview

This extension exposes the cl_khr_gl_sharing functionality to WebCL.

There are no WebCL-specific behavioral changes.

Consult the above extension for documentation, issues and new functions and enumerants.

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.

When this extension is enabled:

The application may create a WebCLContext that is able to share resources with the given WebGLRenderingContext.

IDL

partial interface WebCL {

  WebCLContext createContext(WebGLRenderingContext gl, optional CLenum deviceType = WebCL.DEVICE_TYPE_DEFAULT);

  WebCLContext createContext(WebGLRenderingContext gl, WebCLPlatform platform, optional CLenum deviceType = WebCL.DEVICE_TYPE_DEFAULT);

  WebCLContext createContext(WebGLRenderingContext gl, WebCLDevice device);

  WebCLContext createContext(WebGLRenderingContext gl, sequence<WebCLDevice> devices);

  /* Error Codes */
  CLenum INVALID_GL_OBJECT                         = -60;
  CLenum INVALID_MIP_LEVEL                         = -62;
  CLenum INVALID_GL_SHAREGROUP_REFERENCE_KHR       = -1000;

  /* 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 {

  WebGLRenderingContext getGLContext();

  WebCLBuffer createFromGLBuffer(CLenum memFlags, WebGLBuffer buffer);

  WebCLImage createFromGLRenderbuffer(CLenum memFlags, WebGLRenderbuffer renderbuffer);

  WebCLImage createFromGLTexture(CLenum memFlags, 
                                 GLenum textureTarget,
                                 CLint miplevel,
                                 WebGLTexture texture);
};


partial interface WebCLCommandQueue {

  void enqueueAcquireGLObjects(sequence<WebCLMemoryObject> memObjects,
                               optional sequence<WebCLEvent>? eventWaitList,
                               optional WebCLEvent? event = null);
	
  void enqueueReleaseGLObjects(sequence<WebCLMemoryObject> memObjects,
                               optional sequence<WebCLEvent>? eventWaitList,
                               optional WebCLEvent? event = null);
};


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
};

New Functions

WebCLContext createContext(WebGLRenderingContext gl, optional CLenum deviceType)

(OpenCL 1.1 §9.7, man page)

Returns a newly created WebCL context that is able to interoperate with the given WebGL context and runs on the given type of device. If there are multiple devices of the given type that can interoperate with the given GL context, the implementation will choose the device that it deems best suited for interoperating with the given GL context. The `deviceType` argument can be omitted, which is equivalent to specifying `DEVICE_TYPE_DEFAULT`.

Exceptions:

WebCLContext createContext(WebGLRenderingContext gl, WebCLPlatform platform, optional CLenum deviceType)

(OpenCL 1.1 §9.7, man page)

Returns a newly created WebCL context that is able to interoperate with the given WebGL context and runs on the given type of device and platform. If there are multiple devices of the given type that can interoperate with the given GL context, the implementation will choose the device that it deems best suited for interoperating with the given GL context. The `deviceType` argument can be omitted, which is equivalent to specifying `DEVICE_TYPE_DEFAULT`.

Exceptions:

WebCLContext createContext(WebGLRenderingContext gl, WebCLDevice device)

(OpenCL 1.1 §9.7, man page)

Returns a newly created WebCL context that is able to interoperate with the given WebGL context and runs on the given device.

Exceptions:

WebCLContext createContext(WebGLRenderingContext gl, sequence<WebCLDevice> devices)

(OpenCL 1.1 §9.7, man page)

Returns a newly created WebCL context that is able to interoperate with the given WebGL context spanning the given list of devices.

Exceptions:

WebGLRenderingContext getGLContext()

Returns the WebGLRenderingContext instance that this WebCLContext is associated with.

Exceptions:

WebCLBuffer createFromGLBuffer(CLenum memFlags, WebGLBuffer buffer)

(OpenCL 1.1 §9.8.2, man page)

Creates a WebCLBuffer object from a WebGLBuffer object.

Exceptions:

WebCLImage createFromGLRenderbuffer(CLenum memFlags, WebGLRenderbuffer renderbuffer)

(OpenCL 1.1 §9.8.4, man page)

Creates a WebCLImage object from a WebGLRenderbuffer object.

Exceptions:

WebCLImage createFromGLTexture(CLenum memFlags, GLenum textureTarget, CLint miplevel, WebGLTexture texture)

(OpenCL 1.1 §9.8.34, man page)

Creates a WebCLImage object from a WebGLTexture object, or a single face of a WebGL cubemap texture object.

Exceptions:

void enqueueAcquireGLObjects(sequence<WebCLMemoryObject> memObjects, optional sequence<WebCLEvent>? eventWaitList, optional WebCLEvent? event)

(OpenCL 1.1 §9.8.6, man page)

Acquire WebCL memory objects that have been created from WebGL objects.

Exceptions:

void enqueueReleaseGLObjects(sequence<WebCLMemoryObject> memObjects, optional sequence<WebCLEvent>? eventWaitList, optional WebCLEvent? event)

(OpenCL 1.1 §9.8.6, man page)

Release WebCL memory objects that have been created from WebGL objects.

Exceptions:

WebCLGLObjectInfo getGLObjectInfo()

(OpenCL 1.1 §9.8.5, man page)

Query the WebGL memory object used to create this WebCL memory object.

Exceptions:

Sample Code

try {
  var gl = canvas.getContext("webgl");
  var context = createCLGLContext(gl);
  queue = context.createCommandQueue();
  var aBuffer = context.createFromGLBuffer(WebCL.MEM_READ_WRITE, myGLBuffer);
  
  while (processing) {
    queue.enqueueAcquireGLObjects([aBuffer]);
    ...
    queue.enqueueReleaseGLObjects([aBuffer]);
    queue.finish();
  }

} catch (e) {
  console.error("Error sharing WebGL resources: " + e);
}

// Creates and returns a WebCL context that is able to interoperate with the given 
// WebGL context.  Returns null if there are no WebCL devices in the system that are
// able to interoperate with WebGL, or if context creation fails for any other reason.

function createCLGLContext(gl) {
  var context = null;
  webcl.getPlatforms().forEach(function(plat) {
    plat.getDevices().forEach(function(dev) {
      var isSupported = dev.enableExtension("KHR_gl_sharing");
      if (isSupported && context === null) {
        try {
          context = webcl.createContext(gl, devices[i], WebCL.DEVICE_TYPE_DEFAULT);
        } catch (e) {}
      }
    });
  });
  return context;
}

Revision History

Revision 1, 2013/11/19

Migrated from the WebCL Working Draft.

Revision 2, 2014/01/31

Updated createContext to match the core spec (work-in-progress).

Revision 3, 2014/08/13

Added missing documentation of createContext

Revision 4, 2014/08/14

Replaced obsolete example code with a new sample