| Name Strings |
| |
| cl_khr_gl_sharing |
| |
| Version |
| |
| Version 15, March 10, 2010 |
| |
| Number |
| |
| OpenCL Extension #1 |
| |
| Status |
| |
| Complete. Version 10 approved by the OpenCL Working Group. |
| Ratified by the Khronos Promoters, August 28, 2009. |
| |
| Extension Type |
| |
| OpenCL platform extension |
| |
| Dependencies |
| |
| OpenCL 1.0 is required. This extension is written against the OpenCL |
| 1.0 revision 47 specification draft. |
| |
| An OpenGL implementation supporting buffer objects and sharing of |
| texture and buffer object images with OpenCL is required. |
| |
| This extension is included in the OpenCL 1.0 specification as |
| section 9.11 for reference purposes. However, the normative version |
| of the extension, as approved by the OpenCL Working Group, will |
| always be the separate cl_khr_gl_sharing.txt document in the Khronos |
| API Registry. |
| |
| Overview |
| |
| OpenCL defines how to share image data with texture and buffer |
| objects in a parallel OpenGL implementation, but does not define how |
| the association between an OpenCL context and an OpenGL context or |
| share group is established. This extension defines optional |
| attributes to OpenCL context creation routines which associate a GL |
| context or share group object with a newly created OpenGL context. |
| |
| Header File |
| |
| This extension's interfaces are defined in cl_gl.h . |
| |
| New Types |
| |
| typedef cl_uint cl_gl_context_info; |
| |
| New Procedures and Functions |
| |
| cl_int clGetGLContextInfoKHR(const cl_context_properties *properties, |
| cl_gl_context_info param_name, |
| size_t param_value_size, |
| void *param_value, |
| size_t *param_value_size_ret); |
| |
| New Tokens |
| |
| Returned by clCreateContext, clCreateContextFromType, and |
| clGetGLContextInfoKHR when an invalid OpenGL context or share group |
| object handle is specified in <properties>: |
| |
| CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR -1000 |
| |
| Accepted as the <param_name> argument of clGetGLContextInfoKHR: |
| |
| CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR 0x2006 |
| CL_DEVICES_FOR_GL_CONTEXT_KHR 0x2007 |
| |
| Accepted as an attribute name in the 'properties' argument of |
| clCreateContext and clCreateContextFromType: |
| |
| CL_GL_CONTEXT_KHR 0x2008 |
| CL_EGL_DISPLAY_KHR 0x2009 |
| CL_GLX_DISPLAY_KHR 0x200A |
| CL_WGL_HDC_KHR 0x200B |
| CL_CGL_SHAREGROUP_KHR 0x200C |
| |
| Additions to Chapter 4 of the OpenCL 1.0 Specification |
| |
| In section 4.3, replace the description of <properties> under |
| clCreateContext on page 38 with: |
| |
| "<properties> points to an <attribute list>, which is a array of |
| ordered <attribute name, value> pairs terminated with zero. If an |
| attribute is not specified in <properties>, then its default value |
| (listed in table 4.4) is used (it is said to be specified |
| implicitly). If <properties> is NULL or empty (points to a list |
| whose first value is zero), all attributes take on their default |
| values. |
| |
| If the CL_CONTEXT_PLATFORM attribute is not specified, or is |
| specified with the default value of NULL, the selected platform is |
| implementation-defined. |
| |
| Other attributes control sharing of OpenCL memory objects with |
| OpenGL buffer, texture, and renderbuffer objects as described in |
| section 9.12. Depending on the platform-specific API used to bind |
| OpenGL contexts to the window system, the following attributes may |
| be set to identify an OpenGL context: |
| |
| * When the CGL binding API is supported, the attribute |
| CL_CGL_SHAREGROUP_KHR should be set to a CGLShareGroup handle to |
| a CGL share group object. |
| |
| * When the EGL binding API is supported, the attribute |
| CL_GL_CONTEXT_KHR should be set to an EGLContext handle to an |
| OpenGL ES or OpenGL context, and the attribute |
| CL_EGL_DISPLAY_KHR should be set to the EGLDisplay handle of the |
| display used to create the OpenGL ES or OpenGL context. |
| |
| * When the GLX binding API is supported, the attribute |
| CL_GL_CONTEXT_KHR should be set to a GLXContext handle to an |
| OpenGL context, and the attribute CL_GLX_DISPLAY_KHR should be |
| set to the Display handle of the X Window System display used to |
| create the OpenGL context. |
| |
| * When the WGL binding API is supported, the attribute |
| CL_GL_CONTEXT_KHR should be set to an HGLRC handle to an OpenGL |
| context, and the attribute CL_WGL_HDC_KHR should be set to the |
| HDC handle of the display used to create the OpenGL context. |
| |
| Memory objects created in the context so specified may be shared |
| with the specified OpenGL or OpenGL ES context (as well as with any |
| other OpenGL contexts on the share list of that context, according |
| to the description of sharing in the GLX 1.4 and EGL 1.4 |
| Specifications, and the WGL documentation for OpenGL implementations |
| on Microsoft Windows), or with the explicitly identified OpenGL |
| share group for CGL. If no OpenGL or OpenGL ES context or share |
| group is specified in the attribute list, then memory objects may |
| not be shared, and calling any of the commands in section 9.12 will |
| result in a CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR error." |
| |
| Replace existing table 4.4 with: |
| |
| "------------------------------------------------------------------------- |
| Attribute Name Allowed Values Description |
| (cl_context (default value |
| properties enum) is in *bold*) |
| --------------------- ------------------ ----------------------------- |
| CL_CONTEXT_PLATFORM *NULL*, Specifies the platform to |
| cl_platform_id create the OpenCL context on |
| pointer |
| CL_GL_CONTEXT_KHR *0*, OpenGL context to associate |
| OpenGL context the OpenCL context with |
| handle |
| CL_CGL_SHAREGROUP_KHR *0*, CGL share group to associate |
| CGL share group the OpenCL context with |
| handle |
| CL_EGL_DISPLAY_KHR *EGL_NO_DISPLAY*, EGLDisplay an OpenGL context |
| EGLDisplay handle was created with respect to |
| CL_GLX_DISPLAY_KHR *None* X Display an OpenGL context |
| X Display handle was created with respect to |
| CL_WGL_HDC_KHR *0*, HDC an OpenGL context |
| HDC handle was created with respect to |
| ------------------------------------------------------------------------ |
| Table 4.4: Context creation attributes" |
| |
| Add to the list of errors for clCreateContext: |
| |
| "* CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a context was specified |
| by any of the following means: |
| |
| * A context was specified for an EGL-based OpenGL ES or OpenGL |
| implementation by setting the attributes CL_GL_CONTEXT_KHR and |
| CL_EGL_DISPLAY_KHR |
| * A context was specified for a GLX-based OpenGL implementation by |
| setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR |
| * A context was specified for a WGL-based OpenGL implementation by |
| setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR |
| |
| and any of the following conditions hold: |
| |
| * The specified display and context attributes do not identify a |
| valid OpenGL or OpenGL ES context |
| * The specified context does not support buffer and renderbuffer |
| objects. |
| * The specified context is not compatible with the OpenCL context |
| being created (for example, it exists in a physically distinct |
| address space, such as another hardware device; or it does not |
| support sharing data with OpenCL due to implementation |
| restrictions). |
| |
| * CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a share group was |
| specified for a CGL-based OpenGL implementation by setting the |
| attribute CL_CGL_SHAREGROUP_KHR, and the specified share group |
| does not identify a valid CGL share group object. |
| |
| * CL_INVALID_OPERATION if a context or share group object was |
| specified for one of CGL, EGL, GLX, or WGL and any of the |
| following conditions hold: |
| |
| * The OpenGL implementation does not support the window-system |
| binding API for which a context or share group objects was |
| specified. |
| * More than one of the attributes CL_CGL_SHAREGROUP_KHR, |
| CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, and CL_WGL_HDC_KHR is |
| set to a non-default value. |
| * Both of the attributes CL_CGL_SHAREGROUP_KHR and |
| CL_GL_CONTEXT_KHR are set to non-default values. |
| * Any of the devices specified in the <devices> argument cannot |
| support OpenCL objects which share the data store of an OpenGL |
| object, as described in section 9.12." |
| |
| Replace the description of <properties> under |
| clCreateContextFromType with: |
| |
| "<properties> points to an attribute list whose format and valid |
| contents are identical to the <properties> argument of |
| clCreateContext." |
| |
| Add to the list of errors for clCreateContextFromType the same new |
| errors described above for clCreateContext. |
| |
| Additions to Section 9.12 (Sharing Memory Objects...) of the OpenCL 1.0 |
| Specification |
| |
| Add new section 9.12.7: |
| |
| "9.12.7 Querying devices corresponding to OpenGL contexts |
| |
| OpenCL device(s) corresponding to an OpenGL context may be queried. |
| Such a device may not always exist (for example, if an OpenGL |
| context is specified on a GPU not supporting OpenCL command queues, |
| but which does support shared CL/GL objects), and if it does exist, |
| may change over time. When such a device does exist, acquiring and |
| releasing shared CL/GL objects may be faster on a command queue |
| corresponding to this device than on command queues corresponding to |
| other devices available to an OpenCL context. To query the currently |
| corresponding device, use the function |
| |
| cl_int clGetGLContextInfoKHR(const cl_context_properties *properties, |
| cl_gl_context_info param_name, |
| size_t param_value_size, |
| void *param_value, |
| size_t *param_value_size_ret); |
| |
| <properties> points to an attribute list whose format and valid |
| contents are identical to the <properties> argument of |
| clCreateContext. <properties> must identify a single valid GL |
| context or GL share group object. |
| |
| <param_name> is a constant that specifies the GL context information |
| to query, and must be one of the values shown in table 9.ctxprop. |
| |
| <param_value> is a pointer to memory where the result of the query |
| is returned as described in table 9.ctxprop. If <param_value> is |
| NULL, it is ignored. |
| |
| <param_value_size> specifies the size in bytes of memory pointed to |
| by <param_value>. This size must be greater than or equal to the |
| size of the return type described in table 9.ctxprop. |
| |
| <param_value_size_ret> returns the actual size in bytes of data |
| being queried by <param_value>. If <param_value_size_ret> is NULL, |
| it is ignored. |
| |
| -------------------------------------------------------------------- |
| param_name, |
| return type info. returned in param_value |
| ----------- -------------------------------------------- |
| CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR, |
| cl_device_id CL device currently associated with the |
| specified OpenGL context |
| |
| CL_DEVICES_FOR_GL_CONTEXT_KHR, |
| cl_device_id[] List of all CL devices which may be |
| associated with the specified OpenGL context |
| -------------------------------------------------------------------- |
| Table 9.ctxprop: GL context information that can be queried with |
| clGetGLContextInfoKHR |
| |
| clGetGLContextInfoKHR returns CL_SUCCESS if the function is executed |
| successfully. If no device(s) exist corresponding to <param_name>, |
| the call will not fail, but the value of <param_value_size_ret> will |
| be zero. |
| |
| clGetGLContextInfoKHR returns CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR |
| if a context was specified by any of the following means: |
| * A context was specified for an EGL-based OpenGL ES or OpenGL |
| implementation by setting the attributes CL_GL_CONTEXT_KHR and |
| CL_EGL_DISPLAY_KHR |
| * A context was specified for a GLX-based OpenGL implementation by |
| setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR |
| * A context was specified for a WGL-based OpenGL implementation by |
| setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR |
| and any of the following conditions hold: |
| * The specified display and context attributes do not identify a |
| valid OpenGL or OpenGL ES context |
| * The specified context does not support buffer and renderbuffer |
| objects. |
| * The specified context is not compatible with the OpenCL context |
| being created (for example, it exists in a physically distinct |
| address space, such as another hardware device; or it does not |
| support sharing data with OpenCL due to implementation |
| restrictions). |
| |
| clGetGLContextInfoKHR returns CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR |
| if a share group was specified for a CGL-based OpenGL implementation |
| by setting the attribute CL_CGL_SHAREGROUP_KHR, and the specified |
| share group does not identify a valid CGL share group object. |
| |
| clGetGLContextInfoKHR returns CL_INVALID_OPERATION if a context was |
| specified as described above and any of the following conditions |
| hold: |
| * A context or share group object was specified for one of CGL, |
| EGL, GLX, or WGL and the OpenGL implementation does not support |
| that window-system binding API. |
| * More than one of the attributes CL_CGL_SHAREGROUP_KHR, |
| CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, and CL_WGL_HDC_KHR is |
| set to a non-default value. |
| * Both of the attributes CL_CGL_SHAREGROUP_KHR and |
| CL_GL_CONTEXT_KHR are set to non-default values. |
| * Any of the devices specified in the <devices> argument cannot |
| support OpenCL objects which share the data store of an OpenGL |
| object, as described in section 9.12. |
| |
| clGetGLContextInfoKHR returns CL_INVALID_VALUE if an attribute name |
| other than CL_GL_CONTEXT_KHR, CL_CGL_SHAREGROUP_KHR, |
| CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, or CL_WGL_HDC_KHR (as |
| described in table 4.4) is specified in <properties>, or if the same |
| property name is specified more than once. |
| |
| Additionally, clGetGLContextInfoKHR returns CL_INVALID_VALUE if |
| <param_name> is not one of the values listed in table 9.ctxprop, or |
| if the size in bytes specified by <param_value_size> is less than |
| the size of the return type shown in table 9.ctxprop, and |
| <param_value> is not a NULL value." |
| |
| Issues |
| |
| 1) How should the OpenGL context be identified when creating an |
| associated OpenCL context? |
| |
| RESOLVED: by using a (display,context handle) attribute pair to |
| identify an arbitrary OpenGL or OpenGL ES context with respect to |
| one of the window-system binding layers EGL, GLX, or WGL, or a share |
| group handle to identify a CGL share group. If a context is |
| specified, it need not be current to the thread calling |
| clCreateContext*. |
| |
| A previously suggested approach would use a single boolean attribute |
| CL_USE_GL_CONTEXT_KHR to allow creating a context associated with the |
| currently bound OpenGL context. This may still be implemented as a |
| separate extension, and might allow more efficient Acquire/Release |
| behavior in the special case where they are being executed in the |
| same thread as the bound GL context used to create the CL context. |
| |
| 2) What should the format of an attribute list be? |
| |
| After considerable discussion in bug 4340, we think we can live with |
| a list of <attribute name,value> pairs terminated by zero. The list |
| is passed as 'cl_context_properties *properties', where |
| cl_context_properties is typedefed to be 'intptr_t' in cl.h. |
| |
| This effectively allows encoding all scalar integer, pointer, and |
| handle values in the host API into the argument list and is |
| analogous to the structure and type of EGL attribute lists. NULL |
| attribute lists are also allowed. Again as for EGL, any attributes |
| not explicitly passed in the list will take on a defined default |
| value that does something reasonable. |
| |
| Experience with EGL, GLX, and WGL has shown attribute lists to be a |
| sufficiently flexible and general mechanism to serve the needs of |
| management calls such as context creation. It is not completely |
| general (encoding floating-point and non-scalar attribute values is |
| not straightforward), and other approaches were suggested in bug |
| 4340 such as opaque attribute lists with getter/setter methods, or |
| arrays of varadic structures. |
| |
| 3) What's the behavior of an associated OpenGL or OpenCL context when |
| using resources defined by the other associated context, and that |
| context is destroyed? |
| |
| RESOLVED: As described in section 9.12, OpenCL objects place a |
| reference on the data store underlying the corresponding GL object |
| when they're created. The GL name corresponding to that data store |
| may be deleted, but the data store itself remains so long as any CL |
| object has a reference to it. |
| |
| However, destroying all GL contexts in the share group corresponding |
| to a CL context results in implementation-dependent behavior when |
| using a corresponding CL object, up to and including program |
| termination. |
| |
| 4) How about sharing with D3D? |
| |
| Sharing between D3D and OpenCL should use the same attribute list |
| mechanism, though obviously with different parameters, and be |
| exposed as a similar parallel OpenCL extension. There may be an |
| interaction between that extension and this one since it's not yet |
| clear if it will be possible to create a CL context simultaneously |
| sharing GL and D3D objects. |
| |
| 5) Under what conditions will context creation fail due to sharing? |
| |
| RESOLVED: Several cross-platform failure conditions are described |
| (GL context or CGL share group doesn't exist, GL context doesn't |
| support types of GL objects required by the section 9.12 interfaces, |
| GL context implementation doesn't allow sharing), but additional |
| failures may result due to implementation-dependent reasons and |
| should be added to this extension as such failures are discovered. |
| Sharing between OpenCL and OpenGL requires integration at the driver |
| internals level. |
| |
| 6) What command queues can clEnqueueAcquire/ReleaseGLObjects be placed |
| on? |
| |
| RESOLVED: All command queues. This restriction is enforced at |
| context creation time. If any device passed to context creation |
| cannot support shared CL/GL objects, context creation will fail with |
| a CL_INVALID_OPERATION error. |
| |
| 7) How can applications determine which command queue to place an |
| Acquire/Release on? |
| |
| RESOLVED: The clGetGLContextInfoKHR returns either the CL device |
| currently corresponding to a specified GL context (typically the |
| display it's running on), or a list of all the CL devices the |
| specified context might run on (potentially useful in multiheaded / |
| "virtual screen" environments). This command is not simply placed in |
| section 9.12 because it relies on the same property-list method of |
| specifying a GL context introduced by this extension. |
| |
| If no devices are returned, it means that the GL context exists on |
| an older GPU not capable of running OpenCL, but still capable of |
| sharing objects between GL running on that GPU and CL running |
| elsewhere. |
| |
| 8) What is the meaning of the CL_DEVICES_FOR_GL_CONTEXT_KHR query? |
| |
| RESOLVED: the list of all CL devices that may ever be associated |
| with a specific GL context. On platforms such as MacOS X, |
| the "virtual screen" concept allows multiple GPUs to back a single |
| virtual display. Similar functionality might be implemented on other |
| windowing systems, such as a transparent heterogenous multiheaded X |
| server. Therefore the exact meaning of this query is interpreted |
| relative to the binding layer API in use. |
| |
| 9) Miscellaneous issues during syncing of version 12 with the OpenCL |
| 1.0 revision 47 spec language and the minor changes Affie made |
| including this extension as section 9.11 of that spec: |
| |
| - rev47 spec numbers table 9.ctxprop as "9.7" but this may depends |
| on the core spec revision. |
| - rev47 spec uses 'cl_context' as the return type for |
| clGetGLContextInfoKHR param names, but cl_device_id / |
| cl_device_id[] are the proper types. |
| - rev47 spec omits the paragraph describing CL_SUCCESS return from |
| clGetGLContextInfoKHR. |
| |
| Sample Code |
| |
| None yet. |
| |
| Conformance Tests |
| |
| None yet. The conformance suite's GL/CL interop testing will |
| probably make use of this extension in time. |
| |
| Revision History |
| |
| Version 15, 2010/03/10 (Jon Leech) - Add missing "Header File" |
| section now that the extension headers have been published. |
| |
| Version 14, 2009/12/02 (Jon Leech) - Add missing "New Types" section |
| with cl_gl_context_info type definition (public bug 239). |
| |
| Version 13, 2009/10/02 (Jon Leech) - Fix typo (CL_CONTEXT_PROPERTY |
| -> CL_CONTEXT_PLATFORM) and list a default value of NULL for this |
| attribute in table 4.4. |
| |
| Version 12, 2009/10/01 (Jon Leech) - Change value for |
| CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR from -63 to -1000, to be in a |
| new range of extension error codes instead of in the core API error |
| codes. Sync up spec language with movement of Appendix B to Section |
| 9.12 of the latest 1.0 specification update and modify existing |
| table 4.4 instead of adding a new table. Moved clGetGLContextInfoKHR |
| into a new subsection 9.12.7 and added the same INVALID_VALUE error |
| for badly formed attribute lists (repeated properties) as |
| clCreateContext, to encourage consistent treatment of attribute |
| lists everywhere they're used. Reduced number of quote marks around |
| new spec language. |
| |
| Version 11, 2009/09/02 (Jon Leech) - Fix capitalization of the name |
| string. Note that this is not purely a cosmetic change. |
| Implementations should not ship with the Version 10 and earlier |
| capitalization. Update status to note approval by the Promoters. |
| |
| Version 10, 2009/08/27 (Jon Leech) - Add 'const' attribute to |
| clGetGLContextInfoKHR <properties> parameter. |
| |
| Version 9, 2009/07/06 (Jon Leech) - Fix minor typos. Assign |
| enumerant values. Change CL_INVALID_GL_CONTEXT_KHR error to |
| CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR so it can apply to either |
| contexts or share group objects. Expand full text of error conditions |
| for clGetGLContextInfoKHR. Resolve all issues still marked |
| UNRESOLVED with the currently defined behaviors. Rename |
| CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR and |
| CL_DEVICES_FOR_GL_CONTEXT_KHR to drop "DISPLAY" and remove the |
| Apple-specific CGL_ prefix. |
| |
| Version 8, 2009/06/15 (Jon Leech) - remove unused OpenCL context |
| argument from clGetGLContextInfoKHR and fix type of param_name |
| argument, based on discussion in bug 4340. Fix minor typos. |
| |
| Version 7, 2009/04/27 (Jon Leech) - add "extension type", fill in a |
| few more fields from the prototype extension template, and tag this |
| as a platform extension. |
| |
| Version 6, 2009/04/21 (Jon Leech) - add CGL share group to attribute |
| list, expand errors section, rename CL_INVALID_CONTEXT to |
| CL_INVALID_GL_CONTEXT_KHR, fix some minor spec language errors. |
| Change extension name from use_gl_context to gl_sharing. |
| |
| Version 5, 2009/04/20 (Jon Leech) - add new functions & tokens to |
| the summary section at the top. Add KHR suffix to tokens for |
| specifying WGL/GLX/EGL context attributes. No functionality |
| changes relative to version 4. |
| |
| Version 4, 2009/04/13 (Jon Leech) - add error on context creation if |
| an unrecognized attribute name is specified. Replace |
| clGetCurrentGLDevice with clGetGLContextInfoKHR based on equivalent |
| Apple functionality. Update issue 7 and add issues 8/9. |
| |
| Version 3, 2009/03/24 (Jon Leech) - add error on context creation if |
| devices not supporting GL sharing are specified. Resolve issues 3 |
| and 6 as agreed in discussion last week. Add issue 7 for which |
| command queues an Acquire/Release should be placed on and add |
| proposed clGetCurrentGLDevice query. |
| |
| Version 2, 2009/02/17 (Jon Leech) - revise proposal to identify the |
| OpenGL context using an explicit handle, rather than using the |
| currently bound context. Revised issues 1 and 3 to match, and added |
| issue 6 suggesting changes to the "base" GL interop interace in |
| Appendix B. |
| |
| Version 1, 2009/01/29 (Jon Leech) - initial extension specification |
| based on discussion in bug 4340. |
