C Specification

To create an OpenCL context, call the function:

// Provided by CL_VERSION_1_0
cl_context clCreateContext(
    const cl_context_properties* properties,
    cl_uint num_devices,
    const cl_device_id* devices,
    void (CL_CALLBACK* pfn_notify)(const char* errinfo, const void* private_info, size_t cb, void* user_data),
    void* user_data,
    cl_int* errcode_ret);

Parameters

  • properties specifies a list of context property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported properties, and their default values if not present in properties, is described in the Context Properties table. properties can be NULL, in which case all properties take on their default values.

  • num_devices is the number of devices specified in the devices argument.

  • devices is a pointer to a list of unique devices returned by clGetDeviceIDs or sub-devices created by clCreateSubDevices for a platform. [1]

  • pfn_notify is a callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. This callback function may be called asynchronously by the OpenCL implementation. It is the application’s responsibility to ensure that the callback function is thread-safe. If pfn_notify is NULL, no callback function is registered.

  • user_data will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.

  • errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

The parameters to the callback function pfn_notify are:

  • errinfo is a pointer to an error string.

  • private_info and cb represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.

  • user_data is a pointer to user supplied data.

Contexts are used by the OpenCL runtime for managing objects such as command-queues, memory, program and kernel objects and for executing kernels on one or more devices specified in the context.

Table 1. List of supported context creation properties by clCreateContext
Context Property Property Value Description

CL_CONTEXT_PLATFORM

cl_platform_id

Specifies the platform to use.

Defaults to an implementation-defined platform if not specified.

CL_CONTEXT_INTEROP_USER_SYNC

missing before version 1.2.

cl_bool

Specifies whether the user is responsible for synchronization between OpenCL and other APIs. Please refer to the specific sections in the OpenCL Extension Specification that describe sharing with other APIs for restrictions on using this flag.

Defaults to CL_FALSE if not specified.

CL_CONTEXT_ADAPTER_D3D9_KHR

provided by the cl_khr_dx9_media_sharing extension.

IDirect3DDevice9 *

Specifies an IDirect3DDevice9 to use for D3D9 interop.

CL_CONTEXT_ADAPTER_D3D9EX_KHR

provided by the cl_khr_dx9_media_sharing extension.

IDirect3DDeviceEx*

Specifies an IDirect3DDevice9Ex to use for D3D9 interop.

CL_CONTEXT_ADAPTER_DXVA_KHR

provided by the cl_khr_dx9_media_sharing extension.

IDXVAHD_Device *

Specifies an IDXVAHD_Device to use for DXVA interop.

CL_CONTEXT_D3D10_DEVICE_KHR

provided by the cl_khr_d3d10_sharing extension.

ID3D10Device *

Specifies the ID3D10Device * to use for Direct3D 10 interoperability.

The default value is NULL.

CL_CONTEXT_D3D11_DEVICE_KHR

provided by the cl_khr_d3d11_sharing extension.

ID3D11Device *

Specifies the ID3D11Device * to use for Direct3D 11 interoperability.

The default value is NULL.

CL_GL_CONTEXT_KHR

provided by the cl_khr_gl_sharing extension.

OpenGL context handle

OpenGL context to associate the OpenCL context with

Defaults to 0 if not specified.

CL_CGL_SHAREGROUP_KHR

provided by the cl_khr_gl_sharing extension.

CGL share group handle

CGL share group to associate the OpenCL context with

Defaults to 0 if not specified.

CL_EGL_DISPLAY_KHR

provided by the cl_khr_gl_sharing extension.

EGL EGLDisplay handle

EGLDisplay an OpenGL context was created with respect to

Defaults to EGL_NO_DISPLAY if not specified.

CL_GLX_DISPLAY_KHR

provided by the cl_khr_gl_sharing extension.

X handle

X Display an OpenGL context was created with respect to

Defaults to None if not specified.

CL_WGL_HDC_KHR

provided by the cl_khr_gl_sharing extension.

Windows HDC handle

HDC an OpenGL context was created with respect to

Defaults to 0 if not specified.

CL_CONTEXT_MEMORY_INITIALIZE_KHR

provided by the cl_khr_initialize_memory extension.

cl_context_memory_initialize_khr

Describes which memory types for the context must be initialized. This is a bit-field, where the following values are currently supported:

CL_CONTEXT_MEMORY_INITIALIZE_LOCAL_KHR — Initialize local memory to zeros.

CL_CONTEXT_MEMORY_INITIALIZE_PRIVATE_KHR — Initialize private memory to zeros.

CL_CONTEXT_TERMINATE_KHR

provided by the cl_khr_terminate_context extension.

cl_bool

Specifies whether the context can be terminated. The default value is CL_FALSE.

Some of the properties specified in the Context Properties table control sharing of OpenCL memory objects with OpenGL buffer, texture, and renderbuffer objects.

Depending on the platform-specific API used to bind OpenGL contexts to the window system, the following properties may be set to identify an OpenGL context:

  • When the CGL binding API is supported, the property 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 property CL_GL_CONTEXT_KHR should be set to an EGLContext handle to an OpenGL ES or OpenGL context, and the property 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 property CL_GL_CONTEXT_KHR should be set to a GLXContext handle to an OpenGL context, and the property 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 property CL_GL_CONTEXT_KHR should be set to an HGLRC handle to an OpenGL context, and the property 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.5 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 property list, then memory objects may not be shared, and attempts to create such objects will result in a CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR error.

OpenCL / OpenGL sharing does not support the CL_CONTEXT_INTEROP_USER_SYNC property defined in the Context Properties table. Specifying this property when creating a context with OpenCL / OpenGL sharing will return an appropriate error.

There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined.

clCreateContext returns a valid non-zero context and errcode_ret is set to CL_SUCCESS if the context is created successfully. Otherwise, it returns a NULL value with the following error values returned in errcode_ret:

  • CL_INVALID_PLATFORM if no platform is specified in properties and no platform could be selected, or if the platform specified in properties is not a valid platform.

  • CL_INVALID_PROPERTY if a context property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. This error code is missing before version 1.1.

  • CL_INVALID_VALUE if devices is NULL.

  • CL_INVALID_VALUE if num_devices is equal to zero.

  • CL_INVALID_VALUE if pfn_notify is NULL but user_data is not NULL.

  • CL_INVALID_DEVICE if any device in devices is not a valid device.

  • CL_DEVICE_NOT_AVAILABLE if a device in devices is currently not available even though the device was returned by clGetDeviceIDs.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

The following errors may be returned if the cl_khr_dx9_media_sharing extension is supported:

  • CL_INVALID_DX9_MEDIA_ADAPTER_KHR if any of the values of the properties CL_CONTEXT_ADAPTER_D3D9_KHR, CL_CONTEXT_ADAPTER_D3D9EX_KHR or CL_CONTEXT_ADAPTER_DXVA_KHR is non-NULL and does not specify a valid media adapter with which the cl_device_ids against which this context is to be created may interoperate.

The following errors may be returned if the cl_khr_d3d10_sharing extension is supported:

  • CL_INVALID_D3D10_DEVICE_KHR if the value of the property CL_CONTEXT_D3D10_DEVICE_KHR is non-NULL and does not specify a valid Direct3D 10 device with which the cl_device_ids against which this context is to be created may interoperate.

  • CL_INVALID_OPERATION if Direct3D 10 interoperability is specified by setting CL_INVALID_D3D10_DEVICE_KHR to a non-NULL value, and interoperability with another graphics API is also specified.

The following errors may be returned if the cl_khr_d3d11_sharing extension is supported:

  • CL_INVALID_D3D11_DEVICE_KHR if the value of the property CL_CONTEXT_D3D11_DEVICE_KHR is non-NULL and does not specify a valid Direct3D 11 device with which the cl_device_ids against which this context is to be created may interoperate.

  • CL_INVALID_OPERATION if Direct3D 11 interoperability is specified by setting CL_INVALID_D3D11_DEVICE_KHR to a non-NULL value, and interoperability with another graphics API is also specified.

The following errors may be returned if the cl_khr_gl_sharing extension is supported:

  • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a context was specified for an OpenGL or OpenGL ES implementation using the EGL, GLX, or WGL binding APIs, as described above; and any of the following conditions hold:

    • The specified display and context properties 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 property CL_CGL_SHAREGROUP_KHR, and the specified share group does not identify a valid CGL share group object.

  • 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 properties 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 properties 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.

  • CL_INVALID_PROPERTY if both CL_CONTEXT_INTEROP_USER_SYNC, and any of the properties defined by the cl_khr_gl_sharing extension are defined in properties.

The following errors may be returned if the cl_khr_terminate_context extension is supported:

  • CL_INVALID_PROPERTY if the cl_khr_terminate_context extension is supported and CL_CONTEXT_TERMINATE_KHR is set to CL_TRUE in properties, but not all of the devices associated with the context support the ability to support context termination (i.e. CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR is set for CL_DEVICE_TERMINATE_CAPABILITY_KHR).

It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified, when the context is created can be used to record appropriate information in the errinfo, private_info arguments passed to the callback function when the device becomes unavailable.

See Also

CL_VERSION_1_0, cl_context_properties, cl_device_id, cl_int, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. Duplicate devices specified in devices are ignored.