Opencl22 Reference Guide

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 24

Scroll down to view the document on your mobile browser.
OpenCL 2.2 Reference Guide Page 1 ©2017 Khronos Group - Rev. 0817 www.khronos.org/openclOpenCL APIThe OpenCL RunmeAPI calls that manage OpenCL objects such as command-queues, memory objects, program objects, kernel objects for __kernel funcons in a program and calls that allow you to enqueue commands to a command-queue such as execung a kernel, reading, or wring a memory object.Command queues [5.1]cl_command_queue   clCreateCommandQueueWithProperes ( cl_context context, cl_device_id device,  const cl_command_queue_properes *properes,  cl_int *errcode_ret)*properes: Points to a zero-terminated list of properes and their values: [Table 5.1] CL_QUEUE_SIZE, CL_QUEUE_PROPERTIES (biield which may be set to an OR of CL_QUEUE_* where * may be:  OUT_OF_ORDER_EXEC_MODE_ENABLE, PROFILING_ENABLE, ON_DEVICE[_DEFAULT]), CL_QUEUE_THROTTLE_{HIGH, MED, LOW}_KHR (requires the cl_khr_throle_hint extension), CL_QUEUE_PRIORITY_KHR (biield which may be one of CL_QUEUE_PRIORITY_HIGH_KHR,  CL_QUEUE_PRIORITY_MED_KHR,  CL_QUEUE_PRIORITY_LOW_KHR  (requires the cl_khr_priority_hints extension))cl_int clSetDefaultDeviceCommandQueue ( cl_context context, cl_device_id device,  cl_command_queue command_queue) 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: [Table 5.2]  CL_QUEUE_CONTEXT,  CL_QUEUE_DEVICE[_DEFAULT], CL_QUEUE_SIZE, CL_QUEUE_REFERENCE_COUNT,  CL_QUEUE_PROPERTIESOpenCL API Reference                                                                                                                          Secon and table references are to the OpenCL API 2.2 specicaon. OpenCLTM (Open Compung 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 soware developers to write ecient, portable code for high-performance compute servers, desktop computer systems, and handheld devices.  Specicaon documents and online reference are available at www.khronos.org/opencl. [n.n.n] and purple text: secons and text in the OpenCL API 2.2 Spec. [n.n.n] and green text: secons and text in the OpenCL C++ 2.2 Spec. [n.n.n] and brown text: secons and text in the OpenCL C 2.0 Spec.[n.n.n] and blue text: secons and text in the OpenCL Extension 2.2 Spec.The OpenCL Plaorm Layer The OpenCL plaorm layer implements plaorm-specic features that allow applicaons to query OpenCL devices, device conguraon informaon, and to create OpenCL contexts using one or more devices. Items in blue apply only when the appropriate extension is enabled (see Extensions on page 21 of this reference guide).Querying plaorm info & devices [4.1-2] [9.16.9]cl_int  clGetPlaormIDs (cl_uint num_entries,  cl_plaorm_id *plaorms, cl_uint *num_plaorms) cl_int clIcdGetPlaormIDsKHR (cl_uint num_entries, cl_plaorm_id * plaoms, cl_uint *num_plaorms)cl_int  clGetPlaormInfo (cl_plaorm_id plaorm,   cl_plaorm_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_PLATFORM_HOST_TIMER_RESOLUTION, CL_PLATFORM_ICD_SUFFIX_KHR [Table 4.1]cl_int  clGetDeviceIDs (cl_plaorm_id plaorm,  cl_device_type device_type, cl_uint num_entries,  cl_device_id *devices, cl_uint *num_devices) device_type: [Table 4.2] 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:  [Table 4.3] 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_GLOBAL_VARIABLE_PREFERRED_TOTAL_SIZE, CL_DEVICE_IL_VERSION,  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_IMAGE_BASE_ADDRESS_ALIGNMENT, CL_DEVICE_IMAGE_PITCH_ALIGNMENT,  CL_DEVICE_LINKER_AVAILABLE,  CL_DEVICE_LOCAL_MEM_{TYPE, SIZE},  CL_DEVICE_MAX_{CLOCK_FREQUENCY, PIPE_ARGS}, CL_DEVICE_MAX_{COMPUTE_UNITS, SAMPLERS}, CL_DEVICE_MAX_CONSTANT_{ARGS, BUFFER_SIZE}, CL_DEVICE_MAX_GLOBAL_VARIABLE_SIZE,  CL_DEVICE_MAX_{MEM_ALLOC, PARAMETER}_SIZE,  CL_DEVICE_MAX_NUM_SUB_GROUPS, CL_DEVICE_MAX_ON_DEVICE_{QUEUES, EVENTS},  CL_DEVICE_MAX_{READ, WRITE}_IMAGE_ARGS, CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS, CL_DEVICE_MAX_SUB_GROUPS,  CL_DEVICE_MAX_WORK_GROUP_SIZE,  CL_DEVICE_MAX_WORK_ITEM_{DIMENSIONS, SIZES}, CL_DEVICE_MEM_BASE_ADDR_ALIGN,  CL_DEVICE_NAME,  CL_DEVICE_NATIVE_VECTOR_WIDTH_-    {CHAR, INT, DOUBLE, HALF, LONG, SHORT, FLOAT),  CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT,   CL_DEVICE_{OPENCL_C_VERSION, PARENT_DEVICE},  CL_DEVICE_PARTITION_AFFINITY_DOMAIN,  CL_DEVICE_PARTITION_MAX_SUB_DEVICES,  CL_DEVICE_PARTITION_{PROPERTIES, TYPE},  CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS, CL_DEVICE_PIPE_MAX_PACKET_SIZE, CL_DEVICE_{PLATFORM, PRINTF_BUFFER_SIZE}, CL_DEVICE_PREFERRED_Y_ATOMIC_ALIGNMENT      (where Y may be LOCAL, GLOBAL, PLATFORM), CL_DEVICE_PREFERRED_VECTOR_WIDTH_Z       (where Z may be CHAR, INT, DOUBLE, HALF, LONG,        SHORT, FLOAT),  CL_DEVICE_PREFERRED_INTEROP_USER_SYNC,   CL_DEVICE_PROFILE,  CL_DEVICE_PROFILING_TIMER_RESOLUTION, CL_DEVICE_SPIR_VERSIONS,  CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_-PROGRESS  CL_DEVICE_QUEUE_ON_{DEVICE, HOST}_PROPERTIES,   CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE,  CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE, CL_DEVICE_{REFERENCE_COUNT, VENDOR_ID},  CL_DEVICE_SVM_CAPABILITIES,  CL_DEVICE_TERMINATE_CAPABILITY_KHR,  CL_DEVICE_{TYPE, VENDOR},  CL_DEVICE_VENDOR_ID,  CL_{DEVICE, DRIVER}_VERSION,  CL_DEVICE_MAX_NAMED_BARRIER_COUNT_KHRcl_int  clGetDeviceAndHostTimer (cl_device_id device,   cl_ulong *device_mestamp,  cl_ulong *host_mestamp) cl_int  clGetHostTimer (cl_device_id device,   cl_ulong *host_mestamp) Paroning a device [4.3]cl_int clCreateSubDevices (cl_device_id in_device, const cl_device_paron_property *properes,  cl_uint num_devices, cl_device_id *out_devices,  cl_uint *num_devices_ret)properes: [Table 4.4] CL_DEVICE_PARTITION_EQUALLY,  CL_DEVICE_PARTITION_BY_COUNTS,  CL_DEVICE_PARTITION_BY_AFFINITY_DOMAINcl_int  clRetainDevice (cl_device_id device)cl_int  clReleaseDevice (cl_device_id device)Contexts [4.4]cl_context  clCreateContext ( const cl_context_properes *properes,  cl_uint num_devices, const cl_device_id *devices,  void (CL_CALLBACK*pfn_nofy)          (const char *errinfo, const void *private_info,          size_t cb, void *user_data),  void *user_data, cl_int *errcode_ret)properes:  [Table 4.5] NULL or CL_CONTEXT_PLATFORM,  CL_CONTEXT_INTEROP_USER_SYNC,  CL_CONTEXT_{D3D10, D3D11}_DEVICE_KHR,  CL_CONTEXT_ADAPTER_{D3D9, D3D9EX}_KHR, CL_CONTEXT_ADAPTER_DXVA_KHR,  CL_CONTEXT_MEMORY_INITIALIZE_KHR,  CL_CONTEXT_TERMINATE_KHR, CL_GL_CONTEXT_KHR, CL_CGL_SHAREGROUP_KHR,  CL_{EGL, GLX}_DISPLAY_KHR, CL_WGL_HDC_KHR cl_context  clCreateContextFromType ( const cl_context_properes *properes,  cl_device_type device_type,  void (CL_CALLBACK *pfn_nofy)        (const char *errinfo,  const void *private_info,          size_t cb, void *user_data),  void *user_data, cl_int *errcode_ret) properes: See clCreateContextdevice_type: See clGetDeviceIDscl_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_X where X may be REFERENCE_COUNT,  DEVICES, NUM_DEVICES, PROPERTIES,  D3D10_PREFER_SHARED_RESOURCES_KHR,  D3D11_PREFER_SHARED_RESOURCES_KHR [Table 4.6]cl_int clTerminateContextKHR (cl_context context)Get CL extension funcon pointers [9.2]void* clGetExtensionFunconAddressForPlaorm ( cl_plaorm_id plaorm, const char *funcname)
OpenCL 2.2 Reference GuidePage 2©2017 Khronos Group - Rev. 0817 www.khronos.org/openclOpenCL APIBuer ObjectsElements of buer objects are stored sequenally and accessed using a pointer by a kernel execung on a device. Create buer objects [5.2.1]cl_mem clCreateBuer ( cl_context context, cl_mem_ags ags, size_t size,  void *host_ptr, cl_int *errcode_ret)ags:  [Table 5.3]  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_PTRcl_mem clCreateSubBuer ( cl_mem buer, cl_mem_ags ags, cl_buer_create_type buer_create_type,  const void *buer_create_info, cl_int *errcode_ret)ags: See clCreateBuerbuer_create_type: CL_BUFFER_CREATE_TYPE_REGIONRead, write, copy, & ll buer objects [5.2.2-3]  cl_int clEnqueueReadBuer ( cl_command_queue command_queue, cl_mem buer, cl_bool blocking_read, size_t oset, size_t size, void *ptr, cl_uint num_events_in_wait_list,  const cl_event *event_wait_list, cl_event *event)cl_int clEnqueueReadBuerRect ( cl_command_queue command_queue, cl_mem buer, cl_bool blocking_read, const size_t *buer_origin, const size_t *host_origin, const size_t *region,  size_t buer_row_pitch, size_t buer_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 clEnqueueWriteBuer ( cl_command_queue command_queue, cl_mem buer, cl_bool blocking_write, size_t oset, size_t size, const void *ptr, cl_uint num_events_in_wait_list,  const cl_event *event_wait_list, cl_event *event)cl_int clEnqueueWriteBuerRect ( cl_command_queue command_queue, cl_mem buer, cl_bool blocking_write,  const size_t *buer_origin, const size_t *host_origin, const size_t *region, size_t buer_row_pitch, size_t buer_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 clEnqueueFillBuer ( cl_command_queue command_queue, cl_mem buer, const void *paern,  size_t paern_size, size_t oset, size_t size, cl_uint num_events_in_wait_list,  const cl_event *event_wait_list, cl_event *event)cl_int clEnqueueCopyBuer ( cl_command_queue command_queue, cl_mem src_buer, cl_mem dst_buer,  size_t src_oset, size_t dst_oset, size_t size, cl_uint num_events_in_wait_list,  const cl_event *event_wait_list, cl_event *event)cl_int clEnqueueCopyBuerRect ( cl_command_queue command_queue, cl_mem src_buer, cl_mem dst_buer,  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 buer objects [5.2.4]  void * clEnqueueMapBuer ( cl_command_queue command_queue, cl_mem buer, cl_bool blocking_map, cl_map_ags map_ags, size_t oset, 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_REGIONImage ObjectsItems in blue apply when the appropriate extension is enabled.Create image objects [5.3.1]  cl_mem clCreateImage ( cl_context context, cl_mem_ags ags, const cl_image_format *image_format, const cl_image_desc *image_desc, void *host_ptr, cl_int *errcode_ret)ags: See clCreateBuerQuery list of supported image formats [5.3.2] cl_int clGetSupportedImageFormats ( cl_context context, cl_mem_ags ags, cl_mem_object_type image_type, cl_uint num_entries, cl_image_format *image_formats,  cl_uint *num_image_formats) ags: See clCreateBuerimage_type: CL_MEM_OBJECT_IMAGE{1D, 2D, 3D},  CL_MEM_OBJECT_IMAGE1D_BUFFER, CL_MEM_OBJECT_IMAGE{1D, 2D}_ARRAYRead, write, copy, & ll image objects [5.3.3-4]   cl_int clEnqueueReadImage ( cl_command_queue command_queue, cl_mem image, cl_bool blocking_read,  const size_t *origin, const size_t *region, 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, const size_t *region, 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 clEnqueueFillImage ( cl_command_queue command_queue, cl_mem image, const void *ll_color,  const size_t *origin, const size_t *region,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, const size_t *dst_origin, const size_t *region, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event) Copy between image & buer objects [5.3.5]cl_int clEnqueueCopyImageToBuer ( cl_command_queue command_queue, cl_mem src_image, cl_mem dst_buer,  const size_t *src_origin, const size_t *region, size_t dst_oset, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)cl_int clEnqueueCopyBuerToImage ( cl_command_queue command_queue, cl_mem src_buer, cl_mem dst_image,  size_t src_oset, const size_t *dst_origin, const size_t *region, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event) Map and unmap image objects [5.3.6]void * clEnqueueMapImage ( cl_command_queue command_queue, cl_mem image, cl_bool blocking_map,  cl_map_ags map_ags, const size_t *origin, const size_t *region, 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) map_ags: CL_MAP_{READ, WRITE}, CL_MAP_WRITE_INVALIDATE_REGIONQuery image objects [5.3.7]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:  [Table 5.10] CL_IMAGE_FORMAT, CL_IMAGE_{ARRAY, ELEMENT}_SIZE,  CL_IMAGE_{ROW, SLICE}_PITCH, CL_IMAGE_{HEIGHT, WIDTH, DEPTH},  CL_IMAGE_NUM_{SAMPLES, MIP_LEVELS},  CL_IMAGE_DX9_MEDIA_PLANE_KHR,  CL_IMAGE_{D3D10, D3D11}_SUBRESOURCE_KHRImage Formats [5.3.1.1]Supported combinaons of image_channel_order and image_channel_data_type.Built-in support [Table 5.8]CL_R (read or write): CL_[HALF_]FLOAT, CL_UNORM_INT{8,16}, CL_SNORM_INT{8,16},  CL_SIGNED_INT{8,16,32}, CL_UNSIGNED_INT{8,16,32} CL_DEPTH (read or write): CL_FLOAT,  CL_UNORM_INT16CL_DEPTH_STENCIL (read only): CL_FLOAT,  CL_UNORM_INT24  (Requires the extension cl_khr_gl_depth_images)CL_RG (read or write): CL_[HALF_]FLOAT, CL_UNORM_INT{8,16}, CL_SNORM_INT{8,16},  CL_SIGNED_INT{8,16,32}, CL_UNSIGNED_INT{8,16,32}CL_RGBA (read or write): CL_[HALF_]FLOAT, CL_UNORM_INT{8,16}, CL_UNORM_INT_101010_2, CL_SNORM_INT{8,16}, CL_SIGNED_INT{8,16,32}, CL_UNSIGNED_INT{8,16,32} CL_BGRA (read or write):  CL_UNORM_INT8CL_sRGBA (read only):  CL_UNORM_INT8  (Requires the extension cl_khr_srgb_image_writes)Supported image channel order values [Table 5.6]CL_R, CL_A (read and write): CL_[HALF_]FLOAT, CL_UNORM_INT{8,16},   CL_SIGNED_INT{8,16,32}, CL_UNSIGNED_INT{8,16,32}, CL_SNORM_INT{8,16} CL_INTENSITY: CL_[HALF_]FLOAT, CL_UNORM_INT{8,16}, CL_SNORM_INT{8|16} CL_DEPTH_STENCIL: Only used if extension  cl_khr_gl_depth_images  is enabled and  channel data type = CL_UNORM_INT24 or CL_FLOATCL_LUMINANCE: CL_UNORM_INT{8,16}, CL_[HALF_]FLOAT, CL_SNORM_INT{8,16} CL_RG, CL_RA: CL_[HALF_]FLOAT, CL_UNORM_INT{8,16}, CL_SIGNED_INT{8,16, 32} ,   CL_UNSIGNED_INT{8,16,32}, CL_SNORM_INT{8,16} CL_RGB: CL_UNORM_SHORT_{555,565} , CL_UNORM_INT_101010CL_ARGB:  CL_UNORM_INT8, CL_SIGNED_INT8,  CL_UNSIGNED_INT8, CL_SNORM_INT8 CL_BGRA:  CL_{SIGNED, UNSIGNED}_INT8, CL_SNORM_INT8

Navigation menu