EXTENSION.adoc

_header.adoc

EXTENSION

A #pragma directive to set the behavior for OpenCL extensions.

#pragma OPENCL EXTENSION extension_name : behavior
#pragma OPENCL EXTENSION all : behavior

Parameters

extension_name

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 table below shows the legal values for extension_name:

Extension name	Description
cl_khr_3d_image_writes	Writes to 3D image objects
cl_khr_byte_addressable_store
cl_khr_context_abort
cl_khr_d3d10_sharing	Sharing memory objects wth Direct3D 10
cl_khr_d3d11_sharing	Sharing memory objects wth Direct3D 11
cl_khr_depth_images
cl_khr_device_enqueue_local_arg_types	Standard Portable Intermediate Representation (SPIR) support
cl_khr_dx9_media_sharing	Sharing memory objects wth Direct3D 9
cl_khr_egl_event	Create OpenCL event objects linked to EGL fence sync objects
cl_khr_egl_image	Create derived resources from EGLImages
cl_khr_fp16	Half-precision floating-point
cl_khr_fp64	Dobule-precision floating-point
cl_khr_gl_depth_images	GL depth or depth-stencil compatibility
cl_khr_gl_event	CL event objects from GL sync objects
cl_khr_gl_msaa_sharing	GL multi-sampled (MSAA) compatibility
cl_khr_gl_sharing	OpenGL sharing
cl_khr_global_int32_base_atomics
cl_khr_global_int32_extended_atomics
cl_khr_icd	Access Khronos OpenCL installable client driver loader (ICD Loader
cl_khr_il_program	Standard Portable Intermediate Representation (SPIR) support
cl_khr_image2d_from_buffer
cl_khr_initialize_memory	Initialize local or private memory
cl_khr_int64_base_atomics	64-bit integer base atomic operations
cl_khr_int64_extended_atomics	64-bit integer extended atomic operations
cl_khr_local_int32_base_atomics
cl_khr_local_int32_extended_atomics
cl_khr_mipmap_image	Standard Portable Intermediate Representation (SPIR) support
cl_khr_mipmap_image_writes	Standard Portable Intermediate Representation (SPIR) support
cl_khr_priority_hints	Standard Portable Intermediate Representation (SPIR) support
cl_khr_spir	Standard Portable Intermediate Representation (SPIR) support
cl_khr_srgb_image_writes	For writing to sRGB images
cl_khr_subgroups	Implementation-controlled subgroups
cl_khr_terminate_context	Termiate an OpenCL context on a device
cl_khr_throttle_hints	Standard Portable Intermediate Representation (SPIR) support
cles_khr_int64

behavior

One of the following values:

behavior	Description
enable	Behave as specified by the extension extension_name. Report an error on the #pragma OPENCL EXTENSION if the extension_name is not supported, or if all is specified.
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 #pragma OPENCL EXTENSION if the extension extension_name is not supported.

Description

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.

Notes

This document describes the list of optional features supported by OpenCL 2.1. Optional extensions may be supported by some OpenCL devices. Optional extensions are not required to be supported by a conformant OpenCL implementation, but are expected to be widely available; they define functionality that is likely to move into the required feature set in a future revision of the OpenCL specification

OpenCL extensions approved by the OpenCL working group can be promoted to required core features in later revisions of OpenCL. When this occurs, the extension specifications are merged into the core specification. Functions and enumerants that are part of such promoted extensions will have the KHR affix removed. OpenCL implementations of such later revisions must also export the name strings of promoted extensions in the CL_PLATFORM_EXTENSIONS or CL_DEVICE_EXTENSIONS string, and support the KHR-affixed versions of functions and enumerants as a transition aid.

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 the following:

#ifdef cl_khr_3d_image_writes
      // do something using the extension
#else
      // do something else or #error!
#endif

Also see

clGetExtensionFunctionAddressForPlatform

_footer.adoc