THIS IS A PREVIEW SPECIFICATION BUILD TO REVIEW IN-FLIGHT CHANGES!
Published specifications may be found on the Khronos OpenCL Registry; see https://registry.khronos.org/OpenCL/.
Copyright 2008-2024 The Khronos Group Inc.
This Specification is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.
This Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at www.khronos.org/files/member_agreement.pdf and defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.
Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms. Parties desiring to implement the Specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos Intellectual Property Rights Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this Specification; see https://www.khronos.org/adopters.
Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.
Where this Specification identifies specific sections of external references, only those specifically identified sections define normative functionality. The Khronos Intellectual Property Rights Policy excludes external references to materials and associated enabling technology not created by Khronos from the Scope of this specification, and any licenses that may be required to implement such referenced materials and associated technologies must be obtained separately and may involve royalty payments.
Khronos® and Vulkan® are registered trademarks, and SPIR™, SPIR-V™, and SYCL™ are trademarks of The Khronos Group Inc. OpenCL™ is a trademark of Apple Inc. used under license by Khronos. OpenGL® is a registered trademark and the OpenGL ES™ and OpenGL SC™ logos are trademarks of Hewlett Packard Enterprise used under license by Khronos. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.
1. Extensions Overview
Extensions are optional features which may be supported by OpenCL implementations. Extensions are not required to be supported by a conformant OpenCL implementation, but are expected to be widely available, and in some cases may define functionality that is likely to be required in a future revision of the OpenCL specification.
In the past, this document contained full specification language for
Khronos-approved khr
extensions, described in terms of changes to the core
OpenCL Specification.
This extension language has now been integrated into the OpenCL 3.0
Specification, and can be read in context there.
The remaining parts of this document describe general issues in using extensions, such as API Naming Conventions for Optional Extensions; OpenCL C Compiler Directives for Optional Extensions; and Getting OpenCL API Extension Function Pointers.
In addition, there is a section on Extensions to the OpenCL SPIR-V Environment.
Finally, the Quick Reference appendix summarizes khr extensions and links to them in the OpenCL API Specification. In some cases, extensions are mostly or entirely to the OpenCL C language rather than to the OpenCL API. Such extensions can be reached by following the links in the API Specification extension appendices.
1.1. Naming Convention for Optional Extensions
OpenCL extensions approved by the OpenCL working group use the following naming convention:
-
A unique name string of the form
"cl_khr_<name>"
is associated with each extension. If the extension is supported by an implementation, this string will be present in the implementation’sCL_PLATFORM_
string orEXTENSIONS CL_DEVICE_
string.EXTENSIONS -
All API functions defined by the extension will have names of the form cl<function_name>KHR.
-
All enumerants defined by the extension will have names of the form CL_<enum_name>_KHR.
Functions and enumerants defined by extensions that are promoted to
core features will have their KHR affix removed.
OpenCL implementations of such later revisions must also export the name
strings of promoted extensions in the CL_PLATFORM_
or
CL_DEVICE_
string, and support the KHR-affixed versions of
functions and enumerants as a transition aid.
Vendor extensions are strongly encouraged to follow a similar naming convention:
-
A unique name string of the form
"cl_<vendor_name>_<name>"
is associated with each extension. If the extension is supported by an implementation, this string will be present in the implementation’sCL_PLATFORM_
string orEXTENSIONS CL_DEVICE_
string.EXTENSIONS -
All API functions defined by the vendor extension will have names of the form cl<function_name><vendor_name>.
-
All enumerants defined by the vendor extension will have names of the form CL_<enum_name>_<vendor_name>.
1.2. Compiler Directives for Optional Extensions
The #pragma OPENCL EXTENSION directive controls the behavior of the OpenCL compiler with respect to extensions. The #pragma OPENCL EXTENSION directive is defined as:
#pragma OPENCL EXTENSION <extension_name> : <behavior>
#pragma OPENCL EXTENSION all : <behavior>
where extension_name is the name of the extension. The extension_name will have names of the form cl_khr_<name> for an extension approved by the OpenCL working group and will have names of the form cl_<vendor_name>_<name> for vendor extensions. The token all means that the behavior applies to all extensions supported by the compiler. The behavior can be set to one of the following values given by the table below.
behavior | Description |
---|---|
enable |
Behave as specified by the extension extension_name. Report an error on the |
disable |
Behave (including issuing errors and warnings) as if the extension extension_name is not part of the language definition. If all is specified, then behavior must revert back to that of the non-extended core version of the language being compiled to. Warn on the |
The #pragma OPENCL EXTENSION
directive is a simple, low-level mechanism
to set the behavior for each extension.
It does not define policies such as which combinations are appropriate;
those must be defined elsewhere.
The order of directives matter in setting the behavior for each extension.
Directives that occur later override those seen earlier.
The all variant sets the behavior for all extensions, overriding all
previously issued extension directives, but only if the behavior is set to
disable.
The initial state of the compiler is as if the directive
#pragma OPENCL EXTENSION all : disable
was issued, telling the compiler that all error and warning reporting must be done according to this specification, ignoring any extensions.
Every extension which affects the OpenCL language semantics, syntax or adds
built-in functions to the language must create a preprocessor #define
that
matches the extension name string.
This #define
would be available in the language if and only if the
extension is supported on a given implementation.
Example:
An extension which adds the extension string "cl_khr_3d_image_writes"
should also add a preprocessor #define
called cl_khr_3d_image_writes.
A kernel can now use this preprocessor #define
to do something like:
#ifdef cl_khr_3d_image_writes
// do something using the extension
#else
// do something else or #error!
#endif
1.3. Getting OpenCL API Extension Function Pointers
The function
void* clGetExtensionFunctionAddressForPlatform(cl_platform_id platform,
const char *funcname)
returns the address of the extension function named by funcname for a
given platform The pointer returned should be cast to a function pointer
type matching the extension function’s definition defined in the appropriate
extension specification and header file.
A return value of NULL
indicates that the specified function does not
exist for the implementation or platform is not a valid platform.
A non-NULL
return value for clGetExtensionFunctionAddressForPlatform
does not guarantee that an extension function is actually supported by the
platform.
The application must also make a corresponding query using
clGetPlatformInfo(platform, CL_PLATFORM_EXTENSIONS, …) or
clGetDeviceInfo(device, CL_DEVICE_EXTENSIONS, …) to determine if an
extension is supported by the OpenCL implementation.
Since there is no way to qualify the query with a device, the function pointer returned must work for all implementations of that extension on different devices for a platform. The behavior of calling a device extension function on a device not supporting that extension is undefined.
clGetExtensionFunctionAddressForPlatform may not be used to query for core (non-extension) functions in OpenCL. For extension functions that may be queried using clGetExtensionFunctionAddressForPlatform, implementations may also choose to export those functions statically from the object libraries implementing those functions, however, portable applications cannot rely on this behavior.
Function pointer typedefs must be declared for all extensions that add API entrypoints. These typedefs are a required part of the extension interface, to be provided in an appropriate header (such as cl_ext.h if the extension is an OpenCL extension, or cl_gl_ext.h if the extension is an OpenCL / OpenGL sharing extension).
The following convention must be followed for all extensions affecting the host API:
#ifndef extension_name
#define extension_name 1
// all data typedefs, token #defines, prototypes, and
// function pointer typedefs for this extension
// function pointer typedefs must use the
// following naming convention
typedef return_type
(CL_API_CALL *clExtensionFunctionNameTAG_fn)(...);
#endif // _extension_name_
where TAG
can be KHR
, EXT
or vendor-specific
.
Consider, for example, the cl_khr_
extension.
This extension would add the following to cl_gl_ext.h:
#ifndef cl_khr_gl_sharing
#define cl_khr_gl_sharing 1
// all data typedefs, token #defines, prototypes, and
// function pointer typedefs for this extension
#define CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR -1000
#define CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR 0x2006
#define CL_DEVICES_FOR_GL_CONTEXT_KHR 0x2007
#define CL_GL_CONTEXT_KHR 0x2008
#define CL_EGL_DISPLAY_KHR 0x2009
#define CL_GLX_DISPLAY_KHR 0x200A
#define CL_WGL_HDC_KHR 0x200B
#define CL_CGL_SHAREGROUP_KHR 0x200C
// function pointer typedefs must use the
// following naming convention
typedef cl_int
(CL_API_CALL *clGetGLContextInfoKHR_fn)(
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*/);
#endif // cl_khr_gl_sharing
Appendix A: Extensions Promoted to Core Features
A.1. For OpenCL 1.1:
-
The functionality previously described by
cl_khr_
is now part of the core feature set.byte_ addressable_ store -
The functionality previously described by
cl_khr_
,global_ int32_ base_ atomics cl_khr_
,global_ int32_ extended_ atomics cl_khr_
, andlocal_ int32_ base_ atomics cl_khr_
is now part of the core feature set.local_ int32_ extended_ atomics
A.2. For OpenCL 1.2:
-
The functionality previously described by
cl_khr_
is now an optional core feature.fp64
A.3. For OpenCL 2.0:
-
The functionality described by
cl_khr_
is part of the core feature set.3d_ image_ writes -
The functionality described by
cl_khr_
is part of the core feature set.create_ command_ queue -
The functionality described by
cl_khr_
is now part of the core feature set.depth_ images -
The functionality described by
cl_khr_
is now part of the core feature set.image2d_ from_ buffer
A.4. For OpenCL 2.1:
-
The functionality described by
cl_khr_
is now part of the core feature set.il_ program -
The API functionality described by
cl_khr_
is now part of the core API feature set, but the built-in functions described bysubgroups cl_khr_
must still be accessed as an extension to the OpenCL 2.0 C Language specification.subgroups
Appendix C: Quick Reference
Each extension in this table includes a link to the corresponding appendix in the OpenCL 3.0 API Specification, which provides a fuller description and references to the actual extension specification language in the API and C Language Specifications.
Extension Name and Link | Brief Description | Status |
---|---|---|
Write to 3D images |
Core Feature in OpenCL 2.0 |
|
Asynchronous Copy Fences |
Extension |
|
Read and write from 8-bit and 16-bit pointers |
Core Feature in OpenCL 1.1 |
|
Record and Replay Commands |
Provisional Extension |
|
Allow a command-buffer to contain commands targeting different devices |
Provisional Extension |
|
Modify kernel execution commands between enqueues of a command-buffer |
Provisional Extension |
|
API to Create Command-Queues with Properties |
Core Feature in OpenCL 2.0 |
|
Share Direct3D 10 Buffers and Textures with OpenCL |
Extension |
|
Share Direct3D 11 Buffers and Textures with OpenCL |
Extension |
|
Single Channel Depth Images |
Core Feature in OpenCL 2.0 |
|
Pass Non-Void Local Pointers to Child Kernels |
Extension |
|
Unique Device and Driver Identifier Queries |
Extension |
|
Share DirectX 9 Media Surfaces with OpenCL |
Extension |
|
Share EGL Sync Objects with OpenCL |
Extension |
|
Share EGL Images with OpenCL |
Extension |
|
2D and 3D Async Copies |
Extension |
|
Bit Insert, Extract, and Reverse Operations |
Extension |
|
Extend versioning of platform, devices, extensions, etc. |
Core Feature in OpenCL 3.0 (with minor changes) |
|
Common Functionality for External Memory Sharing |
Extension |
|
dma_buf External Memory Handles |
Extension |
|
Opaque File Descriptor External Memory Handles |
Extension |
|
NT Handle External Memory Handles |
Extension |
|
Kernel Optimization Hints |
Extension |
|
Common Functionality for External Semaphore Sharing |
Extension |
|
Opaque File Descriptor External Semaphore Handles |
Extension |
|
Sync FD External Semaphore Handles |
Extension |
|
NT Handle External Semaphore Handles |
Provisional Extension |
|
Operations on 16-bit Floating-Point Values |
Extension |
|
Operations on 64-bit Floating-Point Values |
Optional Core Feature in OpenCL 1.2 |
|
Share OpenGL Depth Images with OpenCL |
Extension |
|
Share OpenGL Fence Sync Objects with OpenCL |
Extension |
|
Share OpenGL MSAA Textures with OpenCL |
Extension |
|
Sharing OpenGL Buffers and Textures with OpenCL |
Extension |
|
Basic Atomic Operations on 32-bit Integers in Global Memory |
Core Feature in OpenCL 1.1 |
|
Extended Atomic Operations on 32-bit Integers in Global Memory |
Core Feature in OpenCL 1.1 |
|
Installable Client Drivers |
Extension |
|
Support for Intermediate Language (IL) Programs (SPIR-V) |
Core Feature in OpenCL 2.1 |
|
Create 2D Images from Buffers |
Core Feature in OpenCL 2.0 |
|
Initialize Local and Private Memory on Allocation |
Extension |
|
Basic Atomic Operations on 64-bit Integers in Global and Local Memory |
Extension |
|
Extended Atomic Operations on 64-bit Integers in Global and Local Memory |
Extension |
|
Basic Atomic Operations on 32-bit Integers in Local Memory |
Core Feature in OpenCL 1.1 |
|
Extended Atomic Operations on 32-bit Integers in Local Memory |
Core Feature in OpenCL 1.1 |
|
Integer dot product operations |
Extension |
|
Sample Clock Values Within a Kernel |
Extension |
|
Create and Use Images with Mipmaps |
Extension |
|
Query PCI Bus Information for an OpenCL Device |
Extension |
|
Create Command-Queues with Different Priorities |
Extension |
|
Set the Current Kernel Rounding Mode |
DEPRECATED |
|
Semaphore Synchronization Primitives |
Extension |
|
Standard Portable Intermediate Representation Programs |
Extension, Superseded by IL Programs / SPIR-V |
|
Allows Use of the SPIR-V |
Extension |
|
Allows Use of the SPIR-V |
Extension |
|
Allows Use of the SPIR-V |
Extension |
|
Write to sRGB Images |
Extension |
|
Sub-Groupings of Work Items |
Core Feature in OpenCL 2.1 (with minor changes) |
|
Exchange Ballots Among Sub-Groupings of Work Items |
Extension |
|
Clustered Reductions for Sub-Groupings of Work Items |
Extension |
|
Additional Type Support for Sub-group Functions |
Extension |
|
Barriers for Subsets of a Work-group |
Extension |
|
Sub-group Arithmetic Functions in Non-Uniform Control Flow |
Extension |
|
Hold Votes Among Sub-Groupings of Work Items |
Extension |
|
Rotation Among Sub-Groupings of Work Items |
Extension |
|
General-Purpose Shuffles Among Sub-Groupings of Work Items |
Extension |
|
Relative Shuffles Among Sub-Groupings of Work Items |
Extension |
|
Query a Suggested Local Work Size |
Extension |
|
Terminate an OpenCL Context |
Extension |
|
Create Command-Queues with Different Throttle Policies |
Extension |
|
Work-group Uniform Arithmetic |
Extension |