table of contents
CLCREATECONTEXT(3clc) | OpenCL Manual | CLCREATECONTEXT(3clc) |
NAME¶
clCreateContext - Creates an OpenCL context.
¶
cl_context clCreateContext(const cl_context_properties *properties, cl_uint num_devices, const cl_device_id *devices, (void CL_CALLBACK *pfn_notify) ( .sp .nf const char *errinfo, const void *private_info, size_t cb, void *user_data .fi ), void *user_data, cl_int *errcode_ret);
DESCRIPTION¶
An OpenCL context is created with one or more devices. 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.
PARAMETERS¶
properties
If the extension cl_khr_dx9_media_sharing(3clc) is enabled, then properties specifies a list of context property names and their corresponding values. Each property is followed immediately by the corresponding desired value. The list is terminated with zero. If a property is not specified in properties, then its default value (listed in the table below) 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 extension cl_khr_d3d10_sharing(3clc) is enabled, then properties specifies a list of context property names and their corresponding values. Each property is followed immediately by the corresponding desired value. The list is terminated with zero. if a property is not specified in properties, then its default value 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 value.
If the extension cl_khr_gl_sharing(3clc) is enabled, then 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 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..
cl_context_properties enum | Property value | Description |
CL_CONTEXT_PLATFORM | cl_platform_id | Specifies the platform to use. |
CL_CONTEXT_INTEROP_USER_SYNC | cl_bool | Specifies whether the user is responsible for synchronization between OpenCL and other APIs. Please refer to the specific sections in the OpenCL 1.2 extension specification that describe sharing with other APIs for restrictions on using this flag. If CL_CONTEXT_INTEROP_USER_ SYNC is not specified, a default of CL_FALSE is assumed. |
CL_CONTEXT_D3D10_DEVICE_KHR | ID3D10Device* | If the cl_khr_d3d10_sharing(3clc) extension is enabled, specifies the ID3D10Device* to use for Direct3D 10 interoperability. The default value is NULL. |
CL_GL_CONTEXT_KHR | 0, OpenGL context handle | OpenGL context to associated the OpenCL context with (available if the cl_khr_gl_sharing(3clc) extension is enabled) |
CL_EGL_DISPLAY_KHR | EGL_NO_DISPLAY, EGLDisplay handle | EGLDisplay an OpenGL context was created with respect to (available if the cl_khr_gl_sharing(3clc) extension is enabled) |
CL_GLX_DISPLAY_KHR | None, X handle | X Display an OpenGL context was created with respect to (available if the cl_khr_gl_sharing(3clc) extension is enabled) |
CL_CGL_SHAREGROUP_KHR | 0, CGL share group handle | CGL share group to associate the OpenCL context with (available if the cl_khr_gl_sharing(3clc) extension is enabled) |
CL_WGL_HDC_KHR | 0, HDC handle | HDC an OpenGL context was created with respect to (available if the cl_khr_gl_sharing(3clc) extension is enabled) |
CL_CONTEXT_ADAPTER_D3D9_KHR | IDirect3DDevice9 * | Specifies an IDirect3DDevice9 to use for D3D9 interop (if the cl_khr_dx9_media_sharing(3clc) extension is supported). |
CL_CONTEXT_ADAPTER_D3D9EX_KHR | IDirect3DDeviceEx* | Specifies an IDirect3DDevice9Ex to use for D3D9 interop (if the cl_khr_dx9_media_sharing(3clc) extension is supported). |
CL_CONTEXT_ADAPTER_DXVA_KHR | IDXVAHD_Device * | Specifies an IDXVAHD_Device to use for DXVA interop (if the cl_khr_dx9_media_sharing(3clc) extension is supported). |
CL_CONTEXT_D3D11_DEVICE_KHR | ID3D11Device * | Specifies the ID3D11Device * to use for Direct3D 11 interoperability. The default value is NULL. |
num_devices
devices
pfn_notify
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.
NOTE: 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.
user_data
errcode_ret
NOTES¶
clCreateContext and clCreateContextFromType(3clc) perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application. However, it is possible that the application may delete the context without informing the library. Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context being used by a library no longer being valid.
ERRORS¶
clCreateContext returns a valid non-zero context and errcode_ret is set to CL_SUCCESS if the context is created successfully. Otherwise, it returns NULL value with the following error values returned in errcode_ret:
and any of the following conditions hold:
SPECIFICATION¶
OpenCL Specification[1]
SEE ALSO¶
clGetDeviceIDs(3clc), clCreateContextFromType(3clc), clRetainContext(3clc), clReleaseContext(3clc), clGetContextInfo(3clc), classDiagram(3clc)
AUTHORS¶
The Khronos Group
COPYRIGHT¶
Copyright © 2007-2011 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to the
condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.
NOTES¶
- 1.
- OpenCL Specification
11/18/2024 | The Khronos Group |