OpenCL API 1.2 Reference Guide Page 1
©2011 Khronos Group - Rev. 1118 www.khronos.org/opencl
The OpenCL Runme
Command Queues [5.1]
cl_command_queue clCreateCommandQueue (
cl_context contex t, cl_device_id device,
cl_command_queue_properes properes,
cl_int *errcode_ret)
properes: 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
OpenCL (Open Compung Language) is a mul-vendor open standard
for general-purpose parallel programming of heterogeneous systems
that include CPUs, GPUs, and other processors. OpenCL provides
a uniform programming environment for soware developers to
write ecient, portable code for high-performance compute servers,
desktop computer systems, and handheld devices.
[n.n.n] refers to the secon in the OpenCL Specicaon.
[n.n.n] refers to the secon in the OpenCL Extension Specicaon
Text shown in purple is as per the OpenCL Extension Specicaon.
Specicaons are available at www.khronos.org/opencl.
Buer Objects
Elements of a buer object are stored sequenally and accessed
using a pointer by a kernel execung on a device. Data is stored
in the same format as it is accessed by the kernel.
Create Buer Objects [5.2.1]
cl_mem clCreateBuer (cl_context cont ext,
cl_mem_ags ags, size_t size, void *host_ptr,
cl_int *errcode_ret)
ags: CL_MEM_READ_WRITE,
CL_MEM_{WRITE, READ}_ONLY,
CL_MEM_HOST_NO_ACCESS,
CL_MEM_HOST_{READ, WRITE}_ONLY,
CL_MEM_{USE, ALLOC, COPY}_HOST_PTR
cl_mem clCreateSubBuer (cl_mem buer,
cl_mem_ags ags,
cl_buer_create_type buer_create_type,
const void *buer_create_info, cl_int *errcode_ret)
ags: same as for clCreateBuer
buer_create_type: CL_BUFFER_CREATE_TYPE_REGION
Read, Write, Copy Buer Objects [5.2.2]
cl_int clEnqueueReadBuer (
cl_command_queue command_queue, cl_mem buer,
cl_bool blocking_read, size_t oset, size_t size,
void *ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueReadBuerRect (
cl_command_queue command_queue, cl_mem buer,
cl_bool blocking_read, const size_t *buer_origin,
const size_t *host_origin, const size_t *region,
size_t buer_row_pitch, size_t buer_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 clEnqueueWriteBuer (
cl_command_queue command_queue, cl_mem buer,
cl_bool blocking_write, size_t oset, size_t size,
const void *ptr, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueWriteBuerRect (
cl_command_queue command_queue,
cl_mem buer, cl_bool blocking_write,
const size_t *buer_origin, const size_t *host_origin,
const size_t *region, size_t buer_row_pitch,
size_t buer_slice_pitch, size_t host_row_pitch,
size_t host_slice_pitch, const void *ptr,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueFillBuer (
cl_command_queue command_queue,
cl_mem buer, const void *paern,
size_t paern_size, size_t oset, size_t size,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueCopyBuer (
cl_command_queue command_queue,
cl_mem src_buer, cl_mem dst_buer,
size_t src_oset, size_t dst_oset, size_t size,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
cl_int clEnqueueCopyBuerRect (
cl_command_queue command_queue,
cl_mem src_buer, cl_mem dst_buer,
const size_t *src_origin, const size_t *dst_origin,
const size_t *region, 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 Buer Objects [5.2.3]
void * clEnqueueMapBuer (
cl_command_queue command_queue, cl_mem buer,
cl_bool blocking_map, cl_map_ags map_ags,
size_t oset, size_t size, cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event,
cl_int *errcode_ret)
map_ags: CL_MAP_{READ, WRITE},
CL_MAP_WRITE_INVALIDATE_REGION
Memory Objects [5.4.1, 5.4.2]
cl_int clRetainMemObject (cl_mem memobj)
cl_int clReleaseMemObject (cl_mem memobj)
cl_int clSetMemObjectDestructorCallback (
cl_mem memobj, void (CL_CALLBACK *pfn_nofy)
(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)
Migrate Memory Objects [5.4.4]
cl_int clEnqueueMigrateMemObjects (
cl_command_queue command_queue,
cl_uint num_mem_objects,
const cl_mem *mem_objects,
cl_mem_migraon_ags ags,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list, cl_event *event)
ags: CL_MIGRATE_MEM_OBJECT_HOST,
CL_MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED
Query Memory Object [5.4.5]
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,
CL_MEM_{D3D10, D3D11}_RESOURCE_KHR,
CL_MEM_DX9_MEDIA_ADAPTER_TYPE_KHR,
CL_MEM_DX9_MEDIA_SURFACE_INFO_KHR
The OpenCL Plaorm Layer
The OpenCL plaorm layer implements plaorm-specic
features that allow applicaons to query OpenCL devices,
device conguraon informaon, and to create OpenCL
contexts using one or more devices.
Querying Plaorm Info and Devices [4.1, 4.2]
cl_int clGetPlaormIDs (cl_uint num_entries,
cl_plaorm_id *plaorms, cl_uint *num_plaorms)
cl_int clGetPlaormInfo (cl_plaorm_id plaorm,
cl_plaorm_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_plaorm_id plaorm,
cl_device_type device_type, cl_uint num_entries,
cl_device_id *devices, cl_uint *num_devices)
device_type:
CL_DEVICE_TYPE_{ACCELERATOR, ALL, CPU},
CL_DEVICE_TYPE_{CUSTOM, DEFAULT, GPU}
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_{NAME, VENDOR, PROFILE, TYPE},
CL_DEVICE_NATIVE_VECTOR_WIDTH_{CHAR, INT},
CL_DEVICE_NATIVE_VECTOR_WIDTH_{LONG, SHORT},
CL_DEVICE_NATIVE_VECTOR_WIDTH_{DOUBLE, HALF},
CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT,
CL_DEVICE_PREFERRED_VECTOR_WIDTH_{CHAR, INT},
CL_DEVICE_PREFERRED_VECTOR_WIDTH_{LONG, SHORT},
CL_DEVICE_PREFERRED_VECTOR_WIDTH_{DOUBLE, HALF},
CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT,
CL_DEVICE_PREFERRED_INTEROP_USER_SYNC,
CL_DEVICE_ADDRESS_BITS, CL_DEVICE_AVAILABLE,
CL_DEVICE_BUILT_IN_KERNELS,
CL_DEVICE_COMPILER_AVAILABLE,
CL_DEVICE_{DOUBLE, HALF, SINGLE}_FP_CONFIG,
CL_DEVICE_ENDIAN_LITTLE, CL_DEVICE_EXTENSIONS,
CL_DEVICE_ERROR_CORRECTION_SUPPORT,
CL_DEVICE_EXECUTION_CAPABILITIES,
CL_DEVICE_GLOBAL_MEM_CACHE_{SIZE, TYPE},
CL_DEVICE_GLOBAL_MEM_{CACHELINE_SIZE, SIZE},
CL_DEVICE_HOST_UNIFIED_MEMORY,
CL_DEVICE_IMAGE_MAX_{ARRAY, BUFFER}_SIZE,
CL_DEVICE_IMAGE_SUPPORT,
CL_DEVICE_IMAGE2D_MAX_{WIDTH, HEIGHT},
CL_DEVICE_IMAGE3D_MAX_{WIDTH, HEIGHT, DEPTH},
CL_DEVICE_LOCAL_MEM_{TYPE, SIZE},
CL_DEVICE_MAX_{READ, WRITE}_IMAGE_ARGS,
CL_DEVICE_MAX_CLOCK_FREQUENCY,
CL_DEVICE_MAX_COMPUTE_UNITS,
CL_DEVICE_MAX_CONSTANT_{ARGS,BUFFER_SIZE},
CL_DEVICE_MAX_{MEM_ALLOC, PARAMETER}_SIZE,
CL_DEVICE_MAX_SAMPLERS,
CL_DEVICE_MAX_WORK_GROUP_SIZE,
CL_DEVICE_MAX_WORK_ITEM_{DIMENSIONS, SIZES},
CL_DEVICE_MEM_BASE_ADDR_ALIGN,
CL_DEVICE_OPENCL_C_VERSION, CL_DEVICE_PARENT_DEVICE,
CL_DEVICE_PARTITION_AFFINITY_DOMAIN,
CL_DEVICE_PARTITION_MAX_SUB_DEVICES,
CL_DEVICE_PARTITION_{PROPERTIES, TYPE},
CL_DEVICE_PLATFORM, CL_DEVICE_PRINTF_BUFFER_SIZE,
CL_DEVICE_PROFILING_TIMER_RESOLUTION,
CL_DEVICE_QUEUE_PROPERTIES,
CL_DEVICE_REFERENCE_COUNT,
CL_DEVICE_VENDOR_ID, CL_{DEVICE, DRIVER}_VERSION
Paroning a Device [4.3]
cl_int clCreateSubDevices (cl_device_id in_device,
const cl_device_paron_property *properes,
cl_uint num_devices, cl_device_id *out_devices,
cl_uint *num_devices_ret)
properes:
CL_DEVICE_PARTITION_EQUALLY,
CL_DEVICE_PARTITION_BY_{COUNTS, AFFINITY_DOMAIN}
(Anity domains may be:
CL_DEVICE_AFFINITY_DOMAIN_NUMA,
CL_DEVICE_AFFINITY_DOMAIN_{L4, L3, L2, L1}_CACHE,
CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE)
cl_int clRetainDevice (cl_device_id device)
cl_int clReleaseDevice (cl_device_id device)
Contexts [4.4]
cl_context clCreateContext (
const cl_context_properes *properes,
cl_uint num_devices, const cl_device_id *devices,
void (CL_CALLBACK*pfn_nofy)
(const char *errinfo, const void *private_info,
size_t cb, void *user_data),
void *user_data, cl_int *errcode_ret)
properes: NULL or
CL_CONTEXT_PLATFORM,
CL_CONTEXT_INTEROP_USER_SYNC,
CL_CONTEXT_{D3D10, D3D11}_DEVICE_KHR,
CL_CONTEXT_ADAPTER_{D3D9, D3D9EX, DXVA}_KHR,
CL_GL_CONTEXT_KHR, CL_CGL_SHAREGROUP_KHR,
CL_{EGL, GLX}_DISPLAY_KHR, CL_WGL_HDC_KHR
cl_context clCreateContextFromType (
const cl_context_properes *properes,
cl_device_type device_type,
void (CL_CALLBACK *pfn_nofy)
(const char *errinfo,
const void *private_info,
size_t cb, void *user_data),
void *user_data, cl_int *errcode_ret)
properes: 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, NUM_DEVICES, PROPERTIES},
CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR,
CL_CONTEXT_D3D11_PREFER_SHARED_RESOURCES_KHR
Get CL Extension Funcon Pointers [9.2]
void* clGetExtensionFunconAddressForPlaorm (
cl_plaorm_id plaorm, const char *funcname)