Appendix A. Summary of OpenCL 1.1
This appendix lists the APIs, data types, and other interfaces used by programmers working with OpenCL 1.1. Headings that introduce each topic in the appendix include in square brackets the section number in the OpenCL 1.1 specification where further information can be found. This text is also available as a compact reference card at www.khronos.org/files/opencl-1-1-quick-reference-card.pdf.
The OpenCL Platform Layer
The OpenCL platform layer implements platform-specific features that allow applications to query OpenCL devices and device configuration information and to create OpenCL contexts using one or more devices.
Contexts [4.3]
cl_context clCreateContext (
const cl_context_properties *properties,
cl_uint num_devices, const cl_device_id *devices,
void (CL_CALLBACK*pfn_notify)(const char *errinfo,
const void *private_info, size_t cb, void *user_data),
void *user_data, cl_int *errcode_ret)
properties: CL_CONTEXT_PLATFORM, CL_GL_CONTEXT_KHR,
CL_CGL_SHAREGROUP_KHR, CL_{EGL, GLX}_DISPLAY_KHR, CL_WGL_HDC_KHR
cl_context clCreateContextFromType (
const cl_context_properties *properties,
cl_device_type device_type,
void (CL_CALLBACK *pfn_notify)(const char *errinfo,
const void *private_info, size_t cb, void *user_data),
void *user_data, cl_int *errcode_ret)
properties: See clCreateContext
cl_int clRetainContext (cl_context context)
cl_int clReleaseContext (cl_context context)
cl_int clGetContextInfo (cl_context context,
cl_context_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_CONTEXT_REFERENCE_COUNT,
CL_CONTEXT_{DEVICES, PROPERTIES}, CL_CONTEXT_NUM_DEVICES
Querying Platform Information and Devices [4.1, 4.2]
cl_int clGetPlatformIDs (cl_uint num_entries,
cl_platform_id *platforms, cl_uint *num_platforms)
cl_int clGetPlatformInfo (cl_platform_id platform,
cl_platform_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_PLATFORM_{PROFILE, VERSION},
CL_PLATFORM_{NAME, VENDOR, EXTENSIONS}
cl_int clGetDeviceIDs (cl_platform_id platform,
cl_device_type device_type, cl_uint num_entries,
cl_device_id *devices, cl_uint *num_devices)
device_type: CL_DEVICE_TYPE_{CPU, GPU},
CL_DEVICE_TYPE_{ACCELERATOR, DEFAULT, ALL}
cl_int clGetDeviceInfo (cl_device_id device,
cl_device_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_DEVICE_TYPE,
CL_DEVICE_VENDOR_ID,
CL_DEVICE_MAX_COMPUTE_UNITS,
CL_DEVICE_MAX_WORK_ITEM_{DIMENSIONS, SIZES},
CL_DEVICE_MAX_WORK_GROUP_SIZE,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_CHAR,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_SHORT,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_INT,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_LONG,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_FLOAT,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_DOUBLE,
CL_DEVICE_{NATIVE, PREFERRED}_VECTOR_WIDTH_HALF,
CL_DEVICE_MAX_CLOCK_FREQUENCY,
CL_DEVICE_ADDRESS_BITS,
CL_DEVICE_MAX_MEM_ALLOC_SIZE,
CL_DEVICE_IMAGE_SUPPORT,
CL_DEVICE_MAX_{READ, WRITE}_IMAGE_ARGS,
CL_DEVICE_IMAGE2D_MAX_{WIDTH, HEIGHT},
CL_DEVICE_IMAGE3D_MAX_{WIDTH, HEIGHT, DEPTH},
CL_DEVICE_MAX_SAMPLERS,
CL_DEVICE_MAX_PARAMETER_SIZE,
CL_DEVICE_MEM_BASE_ADDR_ALIGN,
CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE,
CL_DEVICE_SINGLE_FP_CONFIG,
CL_DEVICE_GLOBAL_MEM_CACHE_{TYPE, SIZE},
CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE,
CL_DEVICE_GLOBAL_MEM_SIZE,
CL_DEVICE_MAX_CONSTANT_{BUFFER_SIZE, ARGS}
CL_DEVICE_LOCAL_MEM_{TYPE, SIZE},
CL_DEVICE_ERROR_CORRECTION_SUPPORT,
CL_DEVICE_PROFILING_TIMER_RESOLUTION,
CL_DEVICE_ENDIAN_LITTLE,
CL_DEVICE_AVAILABLE,
CL_DEVICE_COMPILER_AVAILABLE,
CL_DEVICE_EXECUTION_CAPABILITIES,
CL_DEVICE_QUEUE_PROPERTIES,
CL_DEVICE_{NAME, VENDOR, PROFILE, EXTENSIONS},
CL_DEVICE_HOST_UNIFIED_MEMORY,
CL_DEVICE_OPENCL_C_VERSION,
CL_DEVICE_VERSION,
CL_DRIVER_VERSION, CL_DEVICE_PLATFORM
The OpenCL Runtime
Command-Queues [5.1]
cl_command_queue clCreateCommandQueue (cl_context context,
cl_device_id device, cl_command_queue_properties properties,
cl_int *errcode_ret)
properties: CL_QUEUE_PROFILING_ENABLE,
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ ENABLE
cl_int clRetainCommandQueue (cl_command_queue command_queue)
cl_int clReleaseCommandQueue (cl_command_queue command_queue)
cl_int clGetCommandQueueInfo (cl_command_queue command_queue,
cl_command_queue_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_QUEUE_CONTEXT, CL_QUEUE_DEVICE,
CL_QUEUE_REFERENCE_COUNT, CL_QUEUE_PROPERTIES
Buffer Objects
Elements of a buffer object can be a scalar or vector data type or a user-defined structure. Elements are stored sequentially and are accessed using a pointer by a kernel executing on a device. Data is stored in the same format as it is accessed by the kernel.
Create Buffer Objects [5.2.1]
cl_mem clCreateBuffer (cl_context context, cl_mem_flags flags,
size_t size, void *host_ptr, cl_int *errcode_ret)
cl_mem clCreateSubBuffer (cl_mem buffer, cl_mem_flags flags,
cl_buffer_create_type buffer_create_type,
const void *buffer_create_info, cl_int *errcode_ret)
flags for clCreateBuffer and clCreateSubBuffer:
CL_MEM_READ_WRITE, CL_MEM_{WRITE, READ}_ONLY,
CL_MEM_{USE, ALLOC, COPY}_HOST_PTR
Read, Write, and Copy Buffer Objects [5.2.2]
cl_int clEnqueueReadBuffer ( cl_command_queue command_queue,
cl_mem buffer, cl_bool blocking_read, size_t offset, size_t cb,
void *ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueWriteBuffer (cl_command_queue command_queue,
cl_mem buffer, cl_bool blocking_write, size_t offset, size_t cb,
const void *ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueReadBufferRect (cl_command_queue command_queue,
cl_mem buffer, cl_bool blocking_read,
const size_t buffer_origin[3], const size_t host_origin[3],
const size_t region[3], size_t buffer_row_pitch,
size_t buffer_slice_pitch, size_t host_row_pitch,
size_t host_slice_pitch, void *ptr,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueWriteBufferRect (cl_command_queue command_queue,
cl_mem buffer, cl_bool blocking_write,
const size_t buffer_origin[3], const size_t host_origin[3],
const size_t region[3], size_t buffer_row_pitch,
size_t buffer_slice_pitch, size_t host_row_pitch,
size_t host_slice_pitch, void *ptr,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueCopyBuffer (cl_command_queue command_queue,
cl_mem src_buffer, cl_mem dst_buffer, size_t src_offset,
size_t dst_offset, size_t cb, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueCopyBufferRect (cl_command_queue command_queue,
cl_mem src_buffer, cl_mem dst_buffer, const size_t src_origin[3],
const size_t dst_origin[3], const size_t region[3],
size_t src_row_pitch, size_t src_slice_pitch,
size_t dst_row_pitch, size_t dst_slice_pitch,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
Map Buffer Objects [5.23]
void * clEnqueueMapBuffer (cl_command_queue command_queue,
cl_mem buffer, cl_bool blocking_map, cl_map_flags map_flags,
size_t offset, size_t cb, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event,
cl_int *errcode_ret)
Manage Buffer Objects [5.4.1–2]
cl_int clRetainMemObject (cl_mem memobj)
cl_int clReleaseMemObject (cl_mem memobj)
cl_int clSetMemObjectDestructorCallback (cl_mem memobj,
void (CL_CALLBACK *pfn_notify) (cl_mem memobj, void *user_data),
void *user_data)
cl_int clEnqueueUnmapMemObject (cl_command_queue command_queue,
cl_mem memobj, void *mapped_ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
Query Buffer Objects [5.4.3]
cl_int clGetMemObjectInfo (cl_mem memobj, cl_mem_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_MEM_{TYPE, FLAGS, SIZE, HOST_PTR},
CL_MEM_{MAP, REFERENCE}_COUNT, CL_MEM_OFFSET,
CL_MEM_CONTEXT, CL_MEM_ASSOCIATED_MEMOBJECT
Program Objects
Create Program Objects [5.6.1]
cl_program clCreateProgramWithSource ( cl_context context,
cl_uint count, const char **strings, const size_t *lengths,
cl_int *errcode_ret)
cl_program clCreateProgramWithBinary (cl_context context,
cl_uint num_devices, const cl_device_id *device_list,
const size_t *lengths, const unsigned char **binaries,
cl_int *binary_status, cl_int *errcode_ret)
cl_int clRetainProgram (cl_program program)
cl_int clReleaseProgram (cl_program program)
Build Program Executable [5.6.2]
cl_int clBuildProgram (cl_program program, cl_uint num_devices,
const cl_device_id *device_list, const char *options,
void (CL_CALLBACK*pfn_notify)(cl_program program,
void *user_data), void *user_data)
Build Options [5.6.3]
Preprocessor
(-D processed in order listed in clBuildProgram)
-D name
-D name=definition
-I dir
Optimization Options
-cl-opt-disable
-cl-strict-aliasing
-cl-mad-enable
-cl-no-signed-zeros
-cl-finite-math-only
-cl-fast-relaxed-math
-cl-unsafe-math-optimizations
Math Intrinsics
-cl-single-precision-constant
-cl-denorms-are-zero
Warning Request/Suppress
-w
-Werror
Control OpenCL C Language Version
-cl-std=CL1.1 // OpenCL 1.1 specification.
Query Program Objects [5.6.5]
cl_int clGetProgramInfo (cl_program program,
cl_program_info param_name,size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_PROGRAM_{REFERENCE_COUNT},
CL_PROGRAM_{CONTEXT, NUM_DEVICES, DEVICES},
CL_PROGRAM_{SOURCE, BINARY_SIZES, BINARIES}
cl_int clGetProgramBuildInfo (cl_program program,
cl_device_id device, cl_program_build_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_PROGRAM_BUILD_{STATUS, OPTIONS, LOG}
Unload the OpenCL Compiler [5.6.4]
cl_int clUnloadCompiler (void)
Kernel and Event Objects
Create Kernel Objects [5.7.1]
cl_kernel clCreateKernel (cl_program program,
const char *kernel_name, cl_int *errcode_ret)
cl_int clCreateKernelsInProgram (cl_program program,
cl_uint num_kernels, cl_kernel *kernels,
cl_uint *num_kernels_ret)
cl_int clRetainKernel (cl_kernel kernel)
cl_int clReleaseKernel (cl_kernel kernel)
Kernel Arguments and Object Queries [5.7.2, 5.7.3]
cl_int clSetKernelArg (cl_kernel kernel, cl_uint arg_index,
size_t arg_size, const void *arg_value)
cl_int clGetKernelInfo (cl_kernel kernel,cl_kernel_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_KERNEL_FUNCTION_NAME, CL_KERNEL_NUM_ARGS,
CL_KERNEL_REFERENCE_COUNT, CL_KERNEL_CONTEXT, CL_KERNEL_PROGRAM
cl_int clGetKernelWorkGroupInfo (cl_kernel kernel,
cl_device_id device, cl_kernel_work_group_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_KERNEL_WORK_GROUP_SIZE,
CL_KERNEL_COMPILE_WORK_GROUP_SIZE,
CL_KERNEL_{LOCAL, PRIVATE}_MEM_SIZE,
CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE
Execute Kernels [5.8]
cl_int clEnqueueNDRangeKernel ( cl_command_queue command_queue,
cl_kernel kernel, cl_uint work_dim,
const size_t *global_work_offset,
const size_t *global_work_size,
const size_t *local_work_size, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueTask (cl_command_queue command_queue,
cl_kernel kernel, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueNativeKernel (cl_command_queue command_queue,
void (*user_func)(void *), void *args, size_t cb_args,
cl_uint num_mem_objects, const cl_mem *mem_list,
const void **args_mem_loc, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
Event Objects [5.9]
cl_event clCreateUserEvent (cl_context context, cl_int *errcode_ret)
cl_int clSetUserEventStatus (cl_event event,
cl_int execution_status)
cl_int clWaitForEvents (cl_uint num_events,
const cl_event *event_list)
cl_int clGetEventInfo (cl_event event, cl_event_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_EVENT_COMMAND_{QUEUE, TYPE},
CL_EVENT_{CONTEXT, REFERENCE_COUNT},
CL_EVENT_COMMAND_EXECUTION_STATUS
cl_int clSetEventCallback (cl_event event,
cl_int command_exec_callback_type,
void (CL_CALLBACK *pfn_event_notify)(cl_event event,
cl_int event_command_exec_status,
void *user_data), void *user_data)
cl_int clRetainEvent (cl_event event)
cl_int clReleaseEvent (cl_event event)
Out-of-Order Execution of Kernels and Memory Object Commands [5.10]
cl_int clEnqueueMarker (cl_command_queue command_queue,
cl_event *event)
cl_int clEnqueueWaitForEvents (cl_command_queue command_queue,
cl_uint num_events, const cl_event *event_list)
cl_int clEnqueueBarrier (cl_command_queue command_queue)
Profiling Operations [5.11]
cl_int clGetEventProfilingInfo (cl_event event,
cl_profiling_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_PROFILING_COMMAND_QUEUED,
CL_PROFILING_COMMAND_{SUBMIT, START, END}
Flush and Finish [5.12]
cl_int clFlush (cl_command_queue command_queue)
cl_int clFinish (cl_command_queue command_queue)
Supported Data Types
Built-In Scalar Data Types [6.1.1]
Built-In Vector Data Types [6.1.2]
Other Built-In Data Types [6.1.3]
Reserved Data Types [6.1.4]
Vector Component Addressing [6.1.7]
Vector Components
Vector Addressing Equivalencies
Numeric indices are preceded by the letter s or S, for example, s1. Swizzling, duplication, and nesting are allowed, for example, v.yx, v.xx, v.lo.x.
When using .lo or .hi with a 3-component vector, the .w component is undefined.
Conversions and Type Casting Examples [6.2]
T a = (T)b; // Scalar to scalar, or scalar to vector
T a = convert_T(b);
T a = convert_T_R(b);
T a = as_T(b);
T a = convert_T_sat_R(b); //R is rounding mode
R can be one of the following rounding modes:
Operators [6.3]
These operators behave similarly as in C99 except that operands may include vector types when possible:
Address Space Qualifiers [6.5]
__global, global
__local, local
__constant, constant
__private, private
Function Qualifiers [6.7]
__kernel, kernel
__attribute__((vec_type_hint(type))) //type defaults to int
__attribute__((work_group_size_hint(X, Y, Z)))
__attribute__((reqd_work_group_size(X, Y, Z)))
Preprocessor Directives and Macros [6.9]
#pragma OPENCL FP_CONTRACT on-off-switch
where on-off-switch is one of ON OFF DEFAULT
Specify Type Attributes [6.10.1]
Use the following attributes to specify special attributes of enum, struct, and union types:
__attribute__((aligned(n)))
__attribute__((aligned))
__attribute__((packed))
__attribute__((endian(host)))
__attribute__((endian(device)))
__attribute__((endian))
Math Constants [6.11.2]
The values of the following symbolic constants are type float and are accurate within the precision of a single-precision floating-point number:
Each occurrence of T within a function call must be the same. n is 2, 3, 4, 8, or 16 unless otherwise specified.
Work-Item Built-In Functions [6.11.1]
D is dimension index.
Integer Built-In Functions [6.11.3]
T is type char, charn, uchar, ucharn, short, shortn, ushort, ushortn, int, intn, uint, uintn, long, longn, ulong, or ulongn.
U is the unsigned version of T. S is the scalar version of T.
For upsample, scalar types are permitted for the following vector types:
The following fast integer functions optimize the performance of kernels. In these functions, T is type int, int2, int3, int4, int8, int16, uint, uint2, uint4, uint8, or uint16.
Common Built-In Functions [6.11.4]
T is type float or floatn (or optionally double, doublen, or halfn). Optional extensions enable double, doublen, and halfn types.
Math Built-In Functions [6.11.2]
T is type float or floatn (or optionally double, doublen, or halfn). intn, uintn, and ulongn must be scalar when T is scalar. Q is qualifier __global, __local, or __private. HN indicates that Half and Native variants are available by prepending half_ or native_ to the function name. Optional extensions enable double, doublen, half, and halfn types.
Geometric Built-In Functions [6.11.5]
Vector types may have two, three, or four components. Optional extensions enable double, doublen, and halfn types.
Relational Built-In Functions [6.11.6]
T is type float, floatn, char, charn, uchar, ucharn, short, shortn, ushort, ushortn, int, intn, uint, uintn, long, longn, ulong, or ulongn (and optionally double, doublen). S is type char, charn, short, shortn, int, intn, long, or longn. U is type uchar, ucharn, ushort, ushortn, uint, uintn, ulong, or ulongn. Optional extensions enable double, doublen, and halfn types.
Vector Data Load/Store Functions [6.11.7]
Q is an address space qualifier listed in 6.5 unless otherwise noted. R defaults to the current rounding mode or is one of the rounding modes listed in 6.2.3.2. T is type char, uchar, short, ushort, int, uint, long, ulong, half, or float (or optionally double). Tn refers to the vector form of type T. Optional extensions enable the double, doublen, half, and halfn types.
Atomic Functions [6.11.11, 9.4]
T is type int or unsigned int. T may also be type float for atomic_xchg, and type long or ulong for extended 64-bit atomic functions. Q is volatile __global or volatile __local, except Q must be volatile __global for atomic_xchg when T is float.
The built-in atomic functions for 32-bit values begin with atomic_ and the extended 64-bit atomic functions begin with atom_. For example:
Extended 64-bit atomic functions are enabled by the following pragma; extension-name is one of cl_khr_int64_{base, extended}_atomics:
#pragma OPENCL EXTENSION extension-name : enable
Async Copies and Prefetch Functions [6.11.10]
T is type char, charn, uchar, ucharn, short, shortn, ushort, ushortn, int, intn, uint, uintn, long, longn, ulong, ulongn, float, floatn and optionally halfn double, doublen. Optional extensions enable the halfn, double, and doublen types.
Synchronization, Explicit Memory Fence [6.11.9-10]
The flags argument is the memory address space, set to a combination of CLK_LOCAL_MEM_FENCE and CLK_GLOBAL_MEM_FENCE.
Miscellaneous Vector Built-In Functions [6.11.12]
Tn and Tm are the 2-, 4-, 8-, or 16-component vectors of char, uchar, short, ushort, half, int, uint, long, ulong, float, double. Un is the built-in unsigned integer data type. For vec_step(), Tn also includes char3, uchar3, short3, ushort3, half3, int3, uint3, long3, ulong3, float3, and double3. half and double types are enabled by cl_khr_fp16 and cl_khr_fp64, respectively.
Image Read and Write Built-In Functions [6.11.13, 9.5, 9.6.8]
The built-in functions defined in this section can be used only with image memory objects created with clCreateImage2D or clCreateImage3D. sampler specifies the addressing and filtering mode to use. H = To enable read_imageh and write_imageh, enable extension cl_khr_fp16. 3D = To enable type image3d_t in write_image{f, i, ui}, enable extension cl_khr_3d_image_writes.
Image Objects
Create Image Objects [5.3.1]
cl_mem clCreateImage2D (cl_context context, cl_mem_flags flags,
const cl_image_format *image_format, size_t image_width,
size_t image_height, size_t image_row_pitch, void *host_ptr,
cl_int *errcode_ret)
flags: (also for clCreateImage3D, clGetSupportedImageFormats)
CL_MEM_READ_WRITE, CL_MEM_{WRITE, READ}_ONLY,
CL_MEM_{USE, ALLOC, COPY}_HOST_PTR
cl_mem clCreateImage3D (cl_context context, cl_mem_flags flags,
const cl_image_format *image_format, size_t image_width,
size_t image_height, size_t image_depth,
size_t image_row_pitch, size_t image_slice_pitch,
void *host_ptr, cl_int *errcode_ret)
flags: See clCreateImage2D
Query List of Supported Image Formats [5.3.2]
cl_int clGetSupportedImageFormats (cl_context context,
cl_mem_flags flags, cl_mem_object_type image_type,
cl_uint num_entries, cl_image_format *image_formats,
cl_uint *num_image_formats)
flags: See clCreateImage2D
Copy between Image, Buffer Objects [5.3.4]
cl_int clEnqueueCopyImageToBuffer (cl_command_queue command_queue,
cl_mem src_image, cl_mem dst_buffer, const size_t src_origin[3],
const size_t region[3], size_t dst_offset,
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event)
cl_int clEnqueueCopyBufferToImage (cl_command_queue command_queue,
cl_mem src_buffer, cl_mem dst_image, size_t src_offset,
const size_t dst_origin[3], const size_t region[3],
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event)
Map and Unmap Image Objects [5.3.5]
void * clEnqueueMapImage (cl_command_queue command_queue,
cl_mem image, cl_bool blocking_map, cl_map_flags map_flags,
const size_t origin[3], const size_t region[3],
size_t *image_row_pitch, size_t *image_slice_pitch,
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event, cl_int *errcode_ret)
Read, Write, Copy Image Objects [5.3.3]
cl_int clEnqueueReadImage (cl_command_queue command_queue,
cl_mem image, cl_bool blocking_read, const size_t origin[3],
const size_t region[3], size_t row_pitch,size_t slice_pitch,
void *ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueWriteImage (cl_command_queue command_queue,
cl_mem image, cl_bool blocking_write, const size_t origin[3],
const size_t region[3], size_t input_row_pitch,
size_t input_slice_pitch, const void *ptr,
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event)
cl_int clEnqueueCopyImage (cl_command_queue command_queue,
cl_mem src_image, cl_mem dst_image, const size_t src_origin[3],
const size_t dst_origin[3], const size_t region[3],
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event)
Query Image Objects [5.3.6]
cl_int clGetMemObjectInfo (cl_mem memobj, cl_mem_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_MEM_{TYPE, FLAGS, SIZE, HOST_PTR},
CL_MEM_{MAP, REFERENCE}_COUNT, CL_MEM_{CONTEXT, OFFSET},
CL_MEM_ASSOCIATED_MEMOBJECT
cl_int clGetImageInfo (cl_mem image, cl_image_info param_name,
size_t param_value_size, void *param_value,
size_t *param_value_size_ret)
param_name: CL_IMAGE_{FORMAT, ELEMENT_SIZE},
CL_IMAGE_{ROW, SLICE}_PITCH, CL_IMAGE_{HEIGHT, WIDTH, DEPTH},
CL_IMAGE_D3D10_SUBRESOURCE_KHR, CL_MEM_D3D10_RESOURCE_KHR
Image Formats [5.3.1.1, 9.5]
Supported image formats:
Access Qualifiers [6.6]
Apply to image image2d_t and image3d_t types to declare if the image memory object is being read or written by a kernel. The default qualifier is __read_only.
__read_only, read_only
__write_only, write_only
Sampler Objects [5.5]
cl_sampler clCreateSampler (cl_context context,
cl_bool normalized_coords, cl_addressing_mode addressing_mode,
cl_filter_mode filter_mode, cl_int *errcode_ret)
cl_int clRetainSampler (cl_sampler sampler)
cl_int clReleaseSampler (cl_sampler sampler)
cl_int clGetSamplerInfo (cl_sampler sampler,
cl_sampler_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_SAMPLER_REFERENCE_COUNT,
CL_SAMPLER_{CONTEXT, FILTER_MODE},
CL_SAMPLER_ADDRESSING_MODE, CL_SAMPLER_NORMALIZED_COORDS
Sampler Declaration Fields [6.11.13.1]
The sampler can be passed as an argument to the kernel using clSet-KernelArg, or it can be a constant variable of type sampler_t declared in the program source.
const sampler_t <sampler-name> =
<normalized-mode> | <address-mode> | <filter-mode>
normalized-mode:
CLK_NORMALIZED_COORDS_{TRUE, FALSE}
address-mode:
CLK_ADDRESS_{REPEAT, CLAMP, NONE},
CLK_ADDRESS_{CLAMP_TO_EDGE, MIRRORED_REPEAT}
filter-mode:
CLK_FILTER_NEAREST, CLK_FILTER_LINEAR
OpenCL Device Architecture Diagram [3.3]
This table shows memory regions with allocation and memory access capabilities.
This conceptual OpenCL device architecture includes processing elements (PEs), compute units (CUs), and devices. The host is not shown.
OpenCL/OpenGL Sharing APIs
Creating OpenCL memory objects from OpenGL objects using clCreateFromGLBuffer, clCreateFromGLTexture2D, clCreateFromGLTexture3D, and clCreateFromGLRenderbuffer ensure that the storage of the OpenGL object will not be deleted while the corresponding OpenCL memory object exists.
CL Buffer Objects > GL Buffer Objects [9.8.2]
cl_mem clCreateFromGLBuffer (cl_context context, cl_mem_flags flags,
GLuint bufobj, int *errcode_ret)
flags: CL_MEM_{READ, WRITE}_ONLY, CL_MEM_READ_WRITE
CL Image Objects > GL Textures [9.8.3]
cl_mem clCreateFromGLTexture2D (cl_context context,
cl_mem_flags flags, GLenum texture_target, GLint miplevel,
GLuint texture, cl_int *errcode_ret)
flags: See clCreateFromGLBuffer
texture_target: GL_TEXTURE_{2D, RECTANGLE},
GL_TEXTURE_CUBE_MAP_POSITIVE_{X, Y, Z},
GL_TEXTURE_CUBE_MAP_NEGATIVE_{X, Y, Z}
cl_mem clCreateFromGLTexture3D (cl_context context,
cl_mem_flags flags, GLenum texture_target, GLint miplevel,
GLuint texture, cl_int *errcode_ret)
flags: See clCreateFromGLBuffer
texture_target: GL_TEXTURE_3D
CL Image Objects > GL Renderbuffers [9.8.4]
cl_mem clCreateFromGLRenderbuffer (cl_context context,
cl_mem_flags flags, GLuint renderbuffer, cl_int *errcode_ret)
flags: clCreateFromGLBuffer
Query Information [9.8.5]
cl_int clGetGLObjectInfo (cl_mem memobj,
cl_gl_object_type *gl_object_type, GLuint *gl_object_name)
*gl_object_type returns: CL_GL_OBJECT_BUFFER,
CL_GL_OBJECT_{TEXTURE2D, TEXTURE3D}, CL_GL_OBJECT_RENDERBUFFER
cl_int clGetGLTextureInfo (cl_mem memobj,
cl_gl_texture_info param_name, size_t param_value_size,
void *param_value, size_t *param_value_size_ret)
param_name: CL_GL_TEXTURE_TARGET, CL_GL_MIPMAP_LEVEL
Share Objects [9.8.6]
cl_int clEnqueueAcquireGLObjects (cl_command_queue command_queue,
cl_uint num_objects, const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueReleaseGLObjects (cl_command_queue command_queue,
cl_uint num_objects, const cl_mem *mem_objects,
cl_uint num_events_in_wait_list, const cl_event *event_wait_list,
cl_event *event)
CL Event Objects > GL Sync Objects [9.9]
cl_event clCreateEventFromGLsyncKHR (cl_context context,
GLsync sync, cl_int *errcode_ret)
CL Context > GL Context, Sharegroup [9.7]
cl_int clGetGLContextInfoKHR (
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)
param_name: CL_DEVICES_FOR_GL_CONTEXT_KHR,
CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR
OpenCL/Direct3D 10 Sharing APIs [9.10]
Creating OpenCL memory objects from OpenGL objects using clCreateFromGLBuffer, clCreateFromGLTexture2D, clCreateFromGLTexture3D, or clCreateFromGLRenderbuffer ensures that the storage of that OpenGL object will not be deleted while the corresponding OpenCL memory object exists.
cl_int clGetDeviceIDsFromD3D10KHR (cl_platform_id platform,
cl_d3d10_device_source_khr d3d_device_source, void *d3d_object,
cl_d3d10_device_set_khr d3d_device_set, cl_uint num_entries,
cl_device_id *devices, cl_uint *num_devices)
d3d_device_source: CL_D3D10_DEVICE_KHR, CL_D3D10_DXGI_ADAPTER_KHR
d3d_object: ID3D10Device, IDXGIAdapter
d3d_device_set: CL_ALL_DEVICES_FOR_D3D10_KHR,
CL_PREFERRED_DEVICES_FOR_D3D10_KHR
cl_mem clCreateFromD3D10BufferKHR (cl_context context,
cl_mem_flags flags, ID3D10Buffer *resource, cl_int *errcode_ret)
flags: CL_MEM_{READ, WRITE}_ONLY, CL_MEM_READ_WRITE
cl_mem clCreateFromD3D10Texture2DKHR (cl_context context,
cl_mem_flags flags, ID3D10Texture2D *resource, UINT subresource,
cl_int *errcode_ret)
flags: See clCreateFromD3D10BufferKHR
cl_mem clCreateFromD3D10Texture3DKHR (cl_context context,
cl_mem_flags flags, ID3D10Texture3D *resource, UINT subresource,
cl_int *errcode_ret)
flags: See clCreateFromD3D10BufferKHR
cl_int clEnqueueAcquireD3D10ObjectsKHR (
cl_ command_queue command_queue, cl_uint num_objects,
const cl_mem *mem_objects, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueReleaseD3D10ObjectsKHR (
cl_ command_queue command_queue, cl_uint num_objects,
const cl_mem *mem_objects, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)