C Specification

To create an OpenCL context from a specific device type [1], call the function:

// Provided by CL_VERSION_1_0
cl_context clCreateContextFromType(
    const cl_context_properties* properties,
    cl_device_type device_type,
    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 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.

  • device_type is a bit-field that identifies the type of device and is described in the Device Types table.

  • pfn_notify and user_data are described in clCreateContext.

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

Description

Only devices that are returned by clGetDeviceIDs for device_type are used to create the context. The context does not reference any sub-devices that may have been created from these devices.

clCreateContextFromType 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 pfn_notify is NULL but user_data is not NULL.

  • CL_INVALID_DEVICE_TYPE if device_type is not a valid value.

  • CL_DEVICE_NOT_AVAILABLE if no devices that match device_type and property values specified in properties are currently available.

  • CL_DEVICE_NOT_FOUND if no devices that match device_type and property values specified in properties were found.

  • 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 for clCreateContext; 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.

See Also

CL_VERSION_1_0, cl_context_properties, cl_device_type, cl_int

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. clCreateContextFromType may create a context for all or a subset of the actual physical devices present in the platform that match device_type.