Provided by: opencl-1.2-man-doc_1.0~svn33624-1_all bug

NAME

       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 nameDescription                      │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_int64_base_atomics(3clc)     │ 64-bit integer base atomic       │
           │                                    │ operations                       │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_int64_extended_atomics(3clc) │ 64-bit integer extended atomic   │
           │                                    │ operations                       │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_3d_image_writes(3clc)        │ Writes to 3D image objects       │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_fp16(3clc)                   │ Half-precision floating-point    │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_apple_gl_sharing                 │ MacOS X OpenGL sharing           │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_gl_sharing(3clc)             │ OpenGL sharing                   │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_gl_event(3clc)               │ CL event objects from GL sync    │
           │                                    │ objects                          │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_d3d10_sharing(3clc)          │ Sharing memory objects wth       │
           │                                    │ Direct3D 10                      │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_d3d11_sharing(3clc)          │ Sharing memory objects wth       │
           │                                    │ Direct3D 11                      │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_dx9_media_sharing(3clc)      │ Sharing memory objects wth       │
           │                                    │ Direct3D 9                       │
           ├────────────────────────────────────┼──────────────────────────────────┤
           │cl_khr_icd(3clc)                    │ Access Khronos OpenCL            │
           │                                    │ installable client driver loader │
           │                                    │ (ICD Loader.                     │
           └────────────────────────────────────┴──────────────────────────────────┘

         behavior
           One of the following values:

           ┌─────────┬─────────────────────────────────────────────────────────────────────────┐
           │behaviorDescription                                                             │
           ├─────────┼─────────────────────────────────────────────────────────────────────────┤
           │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 1.2. 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

SPECIFICATION

       OpenCL Specification[1]

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
           page 6, section 9.1 - Compiler Directives for Optional Extensions