OpenCL memory objects may be created from OpenGL objects if and only if the OpenCL context has been created from an OpenGL share group object or context. OpenGL share groups and contexts are created using platform specific APIs such as EGL, CGL, WGL, and GLX. On macOS, an OpenCL context may be created from an OpenGL share group object using the OpenCL platform extension cl_apple_gl_sharing. On other platforms including Microsoft Windows, Linux/Unix and others, an OpenCL context may be created from an OpenGL context using the Khronos platform extension cl_khr_gl_sharing.
Any supported OpenGL object defined within the GL share group object, or the share group associated with the GL context from which the CL context is created, may be shared, with the exception of the default OpenGL objects (i.e. objects named zero), which may not be shared.
An OpenCL memory object created from an OpenGL object (hereinafter refered to as a “shared CL/GL object”) remains valid as long as the
corresponding GL object has not been deleted. If the GL object is deleted through the GL API (e.g. glDeleteBuffers, glDeleteTextures,
or glDeleteRenderbuffers), subsequent use of the CL buffer or image object will result in undefined behavior, including but not limited to
possible CL errors and data corruption, but may not result in program termination.
The CL context and corresponding command-queues are dependent on the existence of the GL share group object, or the share group associated with the GL context from which the CL context is created. If the GL share group object or all GL contexts in the share group are destroyed, any use of the CL context or command-queue(s) will result in undefined behavior, which may include program termination. Applications should destroy the CL command-queue(s) and CL context before destroying the corresponding GL share group or contexts.
The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.
If a GL context is bound to a thread other than the one in which EnqueueReleaseGLObjects is called, changes to any of the objects in
mem_objects may not be visible to that context without additional steps being taken by the application. For an OpenGL 3.1 (or later)
context, the requirements are described in Appendix D ("Shared Objects and Multiple Contexts") of the OpenGL 3.1 Specification. For prior versions
of OpenGL, the requirements are implementation dependent.
Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.
| Modifier and Type | Field and Description |
|---|---|
| public static final int | CL_GL_MIPMAP_LEVEL
cl_gl_texture_info |
| public static final int | CL_GL_OBJECT_BUFFER
cl_gl_object_type |
| public static final int | CL_GL_OBJECT_RENDERBUFFER
cl_gl_object_type |
| public static final int | CL_GL_OBJECT_TEXTURE2D
cl_gl_object_type |
| public static final int | CL_GL_OBJECT_TEXTURE3D
cl_gl_object_type |
| public static final int | CL_GL_TEXTURE_TARGET
cl_gl_texture_info |
| public static final int | CL_INVALID_GL_OBJECT
Error Codes |
| public static final int | CL_INVALID_MIP_LEVEL
Error Codes |
| Access | Constructor and Description |
|---|---|
| protected |
| Modifier and Type | Method and Description | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public static long | Returns: a valid non-zero OpenCL buffer object anderrcode_ret is set to SUCCESS if the buffer object is created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret:
a valid OpenCL context created from an OpenGL context context, long a bit-field that is used to specify usage information. One of: flags, int
the name of a GL buffer object. The data store of the GL buffer object must have have been previously created by calling bufobj, IntBuffer glBufferData,
although its contents need not be initialized. The size of the data store will be used to determine the size of the CL buffer object.will return an appropriate error code. If errcode_ret)errcode_ret is NULL, no error code is returned.Creates an OpenCL buffer object from an OpenGL buffer object. | |||||||||||
| public static long | clCreateFromGLBuffer(long context, long flags, int bufobj, int[] errcode_ret)
Array version of: | |||||||||||
| public static long | Returns: a valid non-zero OpenCL image object anderrcode_ret is set to SUCCESS if the image object is created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret:
a valid OpenCL context created from an OpenGL context context, long a bit-field that is used to specify usage information. One of: flags, int
the name of a GL renderbuffer object. The renderbuffer storage must be specified before the image object can be created. The renderbuffer, IntBuffer renderbuffer
format and dimensions defined by OpenGL will be used to create the 2D image object. Only GL renderbuffers with internal formats that maps to
appropriate OpenCL image channel order and data type can be used to create the 2D image object.will return an appropriate error code. If errcode_ret)errcode_ret is NULL, no error code is returned.Creates an OpenCL 2D image object from an OpenGL renderbuffer object. | |||||||||||
| public static long | clCreateFromGLRenderbuffer(long context, long flags, int renderbuffer, int[] errcode_ret)
Array version of: | |||||||||||
| public static long | Returns: a valid non-zero OpenCL image object anderrcode_ret is set to SUCCESS if the image object is created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret:
a valid OpenCL context created from an OpenGL context context, long a bit-field that is used to specify usage information. One of: flags, int
defines the image type of texture_target, int texture. No reference to a bound GL texture object is made or implied by this parameter. One of:
the mipmap level to be used. Implementations may return miplevel, int INVALID_OPERATION for miplevel values > 0.the name of a GL 2D, cubemap or rectangle texture object. The texture object must be a complete texture as per OpenGL rules on texture completeness.
The texture format and dimensions defined by OpenGL for the specified texture, IntBuffer miplevel of the texture will be used to create the 2D image object.
Only GL texture objects with an internal format that maps to appropriate OpenCL image channel order and data type may be used to create a 2D image
object.will return an appropriate error code. If errcode_ret)errcode_ret is NULL, no error code is returned.Creates an OpenCL 2D image object from an OpenGL 2D texture object, or a single face of an OpenGL cubemap texture object. | |||||||||||
| public static long | clCreateFromGLTexture2D(long context, long flags, int texture_target, int miplevel, int texture, int[] errcode_ret)
Array version of: | |||||||||||
| public static long | Returns: a valid non-zero image object anderrcode_ret is set to SUCCESS if the image object is created successfully. Otherwise, it returns a NULL value
with one of the following error values returned in errcode_ret:
a valid OpenCL context created from an OpenGL context context, long a bit-field that is used to specify usage information. One of: flags, int
defines the image type of texture_target, int texture. No reference to a bound GL texture object is made or implied by this parameter. Must be:
the mipmap level to be used miplevel, int the name of a GL 3D texture object. The texture object must be a complete texture as per OpenGL rules on texture completeness. The texture format
and dimensions defined by OpenGL for the specified texture, IntBuffer miplevel of the texture will be used to create the 3D image object. Only GL texture
objects with an internal format that maps to appropriate OpenCL image channel order and data type can be used to create the 3D image object.will return an appropriate error code. If errcode_ret)errcode_ret is NULL, no error code is returned.Creates an OpenCL 3D image object from an OpenGL 3D texture object. | |||||||||||
| public static long | clCreateFromGLTexture3D(long context, long flags, int texture_target, int miplevel, int texture, int[] errcode_ret)
Array version of: | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. If num_objects is 0 and mem_objects is NULL the function does nothing and returns
SUCCESS. Otherwise, it returns one of the following errors:
a valid command-queue. All devices used to create the OpenCL context associated with command_queue, PointerBuffer command_queue must support acquiring shared CL/GL
objects. This constraint is enforced at context creation time.a pointer to a list of CL memory objects that correspond to GL objects mem_objects, PointerBuffer a list of events that need to complete before this particular command can be executed. If event_wait_list, PointerBuffer event_wait_list is NULL, then this particular command
does not wait on any event to complete. The events specified in event_wait_list act as synchronization points. The context associated with events in
event_wait_list and command_queue must be the same.Returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
event)event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to
complete. If the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the
event_wait_list array.Acquire OpenCL memory objects that have been created from OpenGL objects. | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. If num_objects is 0 and mem_objects is NULL the function does nothing and returns
SUCCESS. Otherwise, it returns one of the following errors:
a valid command-queue. All devices used to create the OpenCL context associated with command_queue, long mem_object, PointerBuffer command_queue must support acquiring shared CL/GL
objects. This constraint is enforced at context creation time.a list of events that need to complete before this particular command can be executed. If event_wait_list, PointerBuffer event_wait_list is NULL, then this particular command
does not wait on any event to complete. The events specified in event_wait_list act as synchronization points. The context associated with events in
event_wait_list and command_queue must be the same.Returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
event)event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to
complete. If the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the
event_wait_list array.Acquire OpenCL memory objects that have been created from OpenGL objects. | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. If num_objects is 0 and mem_objects is NULL the function does nothing and returns
SUCCESS. Otherwise, it returns one of the following errors:
a valid command-queue command_queue, PointerBuffer a pointer to a list of CL memory objects that correpond to GL objects mem_objects, PointerBuffer a list of events that need to complete before this particular command can be executed. If event_wait_list, PointerBuffer event_wait_list is NULL, then this particular command
does not wait on any event to complete. The events specified in event_wait_list act as synchronization points. The context associated with events in
event_wait_list and command_queue must be the same.Returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
event)event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to
complete. If the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the
event_wait_list array.Releases OpenCL memory objects that have been created from OpenGL objects. | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. If num_objects is 0 and mem_objects is NULL the function does nothing and returns
SUCCESS. Otherwise, it returns one of the following errors:
a valid command-queue command_queue, long mem_object, PointerBuffer a list of events that need to complete before this particular command can be executed. If event_wait_list, PointerBuffer event_wait_list is NULL, then this particular command
does not wait on any event to complete. The events specified in event_wait_list act as synchronization points. The context associated with events in
event_wait_list and command_queue must be the same.Returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
event)event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to
complete. If the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the
event_wait_list array.Releases OpenCL memory objects that have been created from OpenGL objects. | |||||||||||
| public static int | Returns: SUCCESS if the call was executed successfully. Otherwise, it returns one of the following errors:
the memory object being queried memobj, IntBuffer returns the type of GL object attached to gl_object_type, IntBuffer memobj. If gl_object_type is NULL, it is ignored. One of:
the GL object name used to create gl_object_name)memobj. If gl_object_name is NULL, it is ignored.Queries the OpenGL object used to create the OpenCL memory object and information about the object type i.e. whether it is a texture, renderbuffer or buffer object. | |||||||||||
| public static int | clGetGLObjectInfo(long memobj, int[] gl_object_type, int[] gl_object_name)
Array version of: | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
specifies what additional information about the GL texture object associated with param_name, ByteBuffer memobj to query. One of:
a pointer to memory where the appropriate result being queried is returned. If param_value, PointerBuffer param_value is NULL, it is ignored.the actual size in bytes of data being queried by param_value_size_ret)param_value. If NULL, it is ignored.Returns additional information about the GL texture object associated with | |||||||||||
| public static int | Returns: SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
specifies what additional information about the GL texture object associated with param_name, IntBuffer memobj to query. One of:
a pointer to memory where the appropriate result being queried is returned. If param_value, PointerBuffer param_value is NULL, it is ignored.the actual size in bytes of data being queried by param_value_size_ret)param_value. If NULL, it is ignored.Returns additional information about the GL texture object associated with | |||||||||||
| public static int | clGetGLTextureInfo(long memobj, int param_name, int[] param_value, PointerBuffer param_value_size_ret)
Array version of: | |||||||||||
| public static long | nclCreateFromGLBuffer(long context, long flags, int bufobj, long errcode_ret)
Unsafe version of: | |||||||||||
| public static long | nclCreateFromGLRenderbuffer(long context, long flags, int renderbuffer, long errcode_ret)
Unsafe version of: | |||||||||||
| public static long | nclCreateFromGLTexture2D(long context, long flags, int texture_target, int miplevel, int texture, long errcode_ret)
Unsafe version of: | |||||||||||
| public static long | nclCreateFromGLTexture3D(long context, long flags, int texture_target, int miplevel, int texture, long errcode_ret)
Unsafe version of: | |||||||||||
| public static int | nclEnqueueAcquireGLObjects(long command_queue, int
the number of memory objects to be acquired in num_objects, long mem_objects, int mem_objectsthe number of events in num_events_in_wait_list, long event_wait_list, long event)event_wait_listUnsafe version of: | |||||||||||
| public static int | nclEnqueueReleaseGLObjects(long command_queue, int
the number of memory objects to be released in num_objects, long mem_objects, int mem_objectsthe number of events in num_events_in_wait_list, long event_wait_list, long event)event_wait_listUnsafe version of: | |||||||||||
| public static int | nclGetGLObjectInfo(long memobj, long gl_object_type, long gl_object_name)
Unsafe version of: | |||||||||||
| public static int | nclGetGLTextureInfo(long memobj, int param_name, long
the size in bytes of memory pointed to by param_value_size, long param_value, long param_value_size_ret)param_value. This size must be ≥ size of return type. If param_value is NULL, it is ignored.Unsafe version of: |