@@ -287,8 +287,9 @@ Extensions to OpenCL C are described in the OpenCL C specification or in
287287vendor-provided documentation.
288288When an OpenCL C extension is supported an associated extension macro will be
289289predefined.
290- Please refer to the <<opencl-extension-spec,OpenCL Extension Specification>> for
291- more information about predefined extension macros.
290+ Please refer to <<preprocessor-directives-for-optional-extensions,Preprocessor
291+ Directives for Optional Extensions>> for more information about predefined
292+ extension macros.
292293
293294When an optional core language feature began as an extension it may have both an
294295associated feature macro and an associated extension macro. If an optional core
@@ -3979,6 +3980,7 @@ ifdef::cl_khr_initialize_memory[]
39793980endif::cl_khr_initialize_memory[]
39803981
39813982
3983+ [[EXTENSION]]
39823984[[preprocessor-directives-and-macros]]
39833985== Preprocessor Directives and Macros
39843986
@@ -4008,10 +4010,6 @@ following forms whose meanings are described elsewhere:
40084010----------
40094011// on-off-switch is one of ON, OFF, or DEFAULT
40104012#pragma OPENCL FP_CONTRACT on-off-switch
4011-
4012- #pragma OPENCL EXTENSION extensionname : behavior
4013-
4014- #pragma OPENCL EXTENSION all : behavior
40154013----------
40164014
40174015The following predefined macro names are available.
@@ -4116,6 +4114,86 @@ indicating optional language features. Such macros are listed in the
41164114--
41174115
41184116
4117+ [[preprocessor-directives-for-optional-extensions]]
4118+ === Preprocessor Directives for Optional Extensions
4119+
4120+ The *#pragma OPENCL EXTENSION* directive controls the behavior of the OpenCL
4121+ compiler with respect to extensions.
4122+ The *#pragma OPENCL EXTENSION* directive is defined as:
4123+
4124+ [source,opencl_c]
4125+ ----
4126+ #pragma OPENCL EXTENSION <extension_name> : <behavior>
4127+ #pragma OPENCL EXTENSION all : <behavior>
4128+ ----
4129+
4130+ where _extension_name_ is the name of the extension.
4131+ The token *all* means that the behavior applies to all extensions supported
4132+ by the compiler.
4133+ The _behavior_ can be set to one of the following values given by the table
4134+ below.
4135+
4136+ [cols="1,3",options="header",]
4137+ |====
4138+ | *behavior* | *Description*
4139+ | *enable*
4140+ | Behave as specified by the extension _extension_name_.
4141+
4142+ Report an error on the *`#pragma OPENCL EXTENSION`* if the
4143+ _extension_name_ is not supported, or if *all* is specified.
4144+
4145+ | *disable*
4146+ | Behave (including issuing errors and warnings) as if the extension
4147+ _extension_name_ is not part of the language definition.
4148+
4149+ If *all* is specified, then behavior must revert back to that of the
4150+ non-extended core version of the language being compiled to.
4151+
4152+ Warn on the *`#pragma OPENCL EXTENSION`* if the extension _extension_name_
4153+ is not supported.
4154+
4155+ |====
4156+
4157+ The *`#pragma OPENCL EXTENSION`* directive is a simple, low-level mechanism
4158+ to set the behavior for each extension.
4159+ It does not define policies such as which combinations are appropriate;
4160+ those must be defined elsewhere.
4161+ The order of directives matter in setting the behavior for each extension.
4162+ Directives that occur later override those seen earlier.
4163+ The *all* variant sets the behavior for all extensions, overriding all
4164+ previously issued extension directives, but only if the _behavior_ is set to
4165+ *disable*.
4166+
4167+ The initial state of the compiler is as if the directive
4168+
4169+ [source,opencl_c]
4170+ ----
4171+ #pragma OPENCL EXTENSION all : disable
4172+ ----
4173+
4174+ was issued, telling the compiler that all error and warning reporting must
4175+ be done according to this specification, ignoring any extensions.
4176+
4177+ Every extension which affects the OpenCL language semantics, syntax or adds
4178+ built-in functions to the language must create a preprocessor `#define` that
4179+ matches the extension name string.
4180+ This `#define` would be available in the language if and only if the
4181+ extension is supported on a given implementation.
4182+
4183+ For example, compilers that support the {cl_khr_3d_image_writes_EXT} extension
4184+ will add a preprocessor `#define` called {cl_khr_3d_image_writes_EXT}.
4185+ A kernel can now use this preprocessor `#define` to do something like:
4186+
4187+ [source,opencl_c]
4188+ ----
4189+ #ifdef cl_khr_3d_image_writes
4190+ // do something using the extension
4191+ #else
4192+ // do something else or #error!
4193+ #endif
4194+ ----
4195+
4196+
41194197[[attribute-qualifiers]]
41204198== Attribute Qualifiers
41214199
@@ -4586,9 +4664,6 @@ compile-time constant expression.
45864664
45874665The attribute syntax can be extended for standard language extensions and
45884666vendor specific extensions.
4589- Any extensions should follow the naming conventions outlined in the
4590- introduction to <<opencl-extension-spec,section 9 in the OpenCL 2.0
4591- Extension Specification>>.
45924667
45934668Attributes are intended as useful hints to the compiler.
45944669It is our intention that a particular implementation of OpenCL be free to
@@ -12384,7 +12459,7 @@ endif::cl_khr_mipmap_image_writes[]
1238412459[[built-in-image-query-functions]]
1238512460==== Built-in Image Query Functions
1238612461
12387- [open,refpage='imageQueryFunctions',desc='Built-in Image Query Functions',type='freeform',spec='clang',anchor='built-in-image-query-functions',xrefs='imageReadFunctions imageSamplerlessReadFunctions imageWriteFunctions',alias='get_image_width get_image_height get_image_depth get_image_channel_data_type get_image_channel_order get_image_dim get_image_array_size']
12462+ [open,refpage='imageQueryFunctions',desc='Built-in Image Query Functions',type='freeform',spec='clang',anchor='built-in-image-query-functions',xrefs='imageReadFunctions imageSamplerlessReadFunctions imageWriteFunctions',alias='get_image_width get_image_height get_image_depth get_image_channel_data_type get_image_channel_order get_image_dim get_image_array_size get_image_num_samples get_image_num_mip_levels ']
1238812463--
1238912464
1239012465The following built-in function calls to query image information are
@@ -17835,10 +17910,6 @@ one of the integers 0, 1, ... h~t~ - 1.
1783517910 "`Image Format Descriptor`" section (5.3.1.1), and the individual
1783617911 channel data types are defined in the "`List of supported Image Channel
1783717912 Data Types" table (5.7) of that Specification.
17838- . [[opencl-extension-spec]] "`The OpenCL Extension Specification, Version
17839- 3.0, Unified`", https://www.khronos.org/registry/OpenCL/ .
17840- References are to sections and tables of this specific version, although
17841- other versions exists.
1784217913 . [[sRGB-spec]] "`IEC 61966-2-1:1999 Multimedia systems and equipment -
1784317914 Colour measurement and management - Part 2-1: Colour management -
1784417915 Default RGB colour space - sRGB`",
0 commit comments