'\" t
.\"     Title: EXTENSION
.\"    Author: The Khronos Group
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/03/2019
.\"    Manual: OpenCL Manual
.\"    Source: The Khronos Group
.\"  Language: English
.\"
.TH "EXTENSION" "3clc" "02/03/2019" "The Khronos Group" "OpenCL Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
EXTENSION \- A #pragma directive to set the behavior for OpenCL extensions\&.
.SS ""
.TS
tab(:);
l.
T{
#pragma OPENCL EXTENSION \fIextension_name\fR : \fIbehavior\fR
#pragma OPENCL EXTENSION all : \fIbehavior\fR
T}
.TE
.sp 1
.SH "PARAMETERS"
.PP
\fI \fR\fI\fR\fI extension_name \fR
.RS 4
The name of the extension\&. The
\fIextension_name\fR
will have names of the form
\fBcl_khr_\fR<\fIname\fR> for an extension approved by the OpenCL working group and will have names of the form
\fBcl_\fR<\fIvendor_name\fR>_<\fIname\fR> for vendor extensions\&. The token
\fBall\fR
means that the behavior applies to all extensions supported by the compiler\&. The table below shows the legal values for
\fIextension_name\fR:
.TS
allbox tab(:);
lB lB.
T{
Extension name
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
\fBcl_khr_int64_base_atomics\fR(3clc)
T}:T{
64\-bit integer base atomic operations
T}
T{
\fBcl_khr_int64_extended_atomics\fR(3clc)
T}:T{
64\-bit integer extended atomic operations
T}
T{
\fBcl_khr_3d_image_writes\fR(3clc)
T}:T{
Writes to 3D image objects
T}
T{
\fBcl_khr_fp16\fR(3clc)
T}:T{
Half\-precision floating\-point
T}
T{
cl_apple_gl_sharing
T}:T{
MacOS X OpenGL sharing
T}
T{
\fBcl_khr_gl_sharing\fR(3clc)
T}:T{
OpenGL sharing
T}
T{
\fBcl_khr_gl_event\fR(3clc)
T}:T{
CL event objects from GL sync objects
T}
T{
\fBcl_khr_d3d10_sharing\fR(3clc)
T}:T{
Sharing memory objects wth Direct3D 10
T}
T{
\fBcl_khr_d3d11_sharing\fR(3clc)
T}:T{
Sharing memory objects wth Direct3D 11
T}
T{
\fBcl_khr_dx9_media_sharing\fR(3clc)
T}:T{
Sharing memory objects wth Direct3D 9
T}
T{
\fBcl_khr_icd\fR(3clc)
T}:T{
Access Khronos OpenCL installable client driver loader (ICD Loader\&.
T}
.TE
.sp 1
.RE
.PP
\fI \fR\fI\fR\fI behavior \fR
.RS 4
One of the following values:
.TS
allbox tab(:);
lB lB.
T{
behavior
T}:T{
Description
T}
.T&
l l
l l.
T{
enable
T}:T{
.if n \{\
.RS 4
.\}
.nf
Behave as specified by the extension \fIextension_name\fR\&.

Report an error on the \fB#pragma OPENCL EXTENSION\fR if the
\fIextension_name\fR is not supported, or if \fBall\fR is specified\&.
.fi
.if n \{\
.RE
.\}
.sp
T}
T{
disable
T}:T{
Behave (including issuing errors and warnings) as if the extension
\fIextension_name\fR is not part of the language definition\&.

If \fBall\fR is specified, then behavior must revert back to that of the non\-extended core version of the language being compiled to\&.

Warn on the \fB#pragma OPENCL EXTENSION\fR if the extension \fIextension_name\fR is not supported\&.
T}
.TE
.sp 1
.RE
.SH "DESCRIPTION"
.PP
The
\fB#pragma OPENCL EXTENSION\fR
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
\fBall\fR
variant sets the behavior for all extensions, overriding all previously issued extension directives, but only if the
\fIbehavior\fR
is set to
\fBdisable\fR\&.
.PP
The initial state of the compiler is as if the directive
\fB#pragma OPENCL EXTENSION all : disable\fR
was issued, telling the compiler that all error and warning reporting must be done according to this specification, ignoring any extensions\&.
.PP
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\&.
.SH "NOTES"
.PP
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
.PP
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
\fBCL_PLATFORM_EXTENSIONS\fR
or
\fBCL_DEVICE_EXTENSIONS\fR
string, and support the KHR\-affixed versions of functions and enumerants as a transition aid\&.
.SS "Example"
.PP
An extension which adds the extension string "cl_khr_3d_image_writes" should also add a preprocessor
#define
called
\fBcl_khr_3d_image_writes\fR\&. A kernel can now use this preprocessor
#define
to do something like the following:
.TS
tab(:);
l.
T{
#ifdef cl_khr_3d_image_writes
// do something using the extension
#else
// do something else or #error!
#endif
T}
.TE
.sp 1
.SH "SPECIFICATION"
.PP
\m[blue]\fBOpenCL Specification\fR\m[]\&\s-2\u[1]\d\s+2
.SH "AUTHORS"
.PP
\fBThe Khronos Group\fR
.SH "COPYRIGHT"
.br
Copyright \(co 2007-2011 The Khronos Group Inc.
.br
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.
.sp
.SH "NOTES"
.IP " 1." 4
OpenCL Specification
.RS 4
\%page 6, section 9.1 - Compiler Directives for Optional Extensions
.RE