|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jocl.CL
public final class CL
JOCL - Java bindings for OpenCL.
The documentation of the OpenCL methods has been extracted from the OpenCL
registry at http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
and is copyright (c) 2007-2010 by The Khronos Group Inc.
Nested Class Summary | |
---|---|
static class |
CL.LogLevel
The log levels which may be used to control the internal logging of the native JOCL library |
Method Summary | |
---|---|
static java.nio.ByteBuffer |
allocateAligned(int size,
int alignment)
Creates an returns a new direct ByteBuffer with the given size, whose memory has the given alignment, in bytes. |
static int |
clBuildProgram(cl_program program,
int num_devices,
cl_device_id[] device_list,
java.lang.String options,
BuildProgramFunction pfn_notify,
java.lang.Object user_data)
Builds (compiles and links) a program executable from the program source or binary. |
static cl_mem |
clCreateBuffer(cl_context context,
long flags,
long size,
Pointer host_ptr,
int[] errcode_ret)
Creates a buffer object. |
static cl_command_queue |
clCreateCommandQueue(cl_context context,
cl_device_id device,
long properties,
int[] errcode_ret)
Create a command-queue on a specific device. |
static cl_context |
clCreateContext(cl_context_properties properties,
int num_devices,
cl_device_id[] devices,
CreateContextFunction pfn_notify,
java.lang.Object user_data,
int[] errcode_ret)
Creates an OpenCL context. |
static cl_context |
clCreateContextFromType(cl_context_properties properties,
long device_type,
CreateContextFunction pfn_notify,
java.lang.Object user_data,
int[] errcode_ret)
Create an OpenCL context from a device type that identifies the specific device(s) to use. |
static cl_mem |
clCreateFromGLBuffer(cl_context context,
long flags,
int bufobj,
int[] errcode_ret)
Creates an OpenCL buffer object from an OpenGL buffer object. |
static cl_mem |
clCreateFromGLRenderbuffer(cl_context context,
long flags,
int renderbuffer,
int[] errcode_ret)
Creates an OpenCL 2D image object from an OpenGL renderbuffer object. |
static cl_mem |
clCreateFromGLTexture2D(cl_context context,
long flags,
int target,
int miplevel,
int texture,
int[] errcode_ret)
Creates an OpenCL 2D image object from an OpenGL 2D texture object, or a single face of an OpenGL cubemap texture object. |
static cl_mem |
clCreateFromGLTexture3D(cl_context context,
long flags,
int target,
int miplevel,
int texture,
int[] errcode_ret)
Creates an OpenCL 3D image object from an OpenGL 3D texture object. |
static cl_mem |
clCreateImage2D(cl_context context,
long flags,
cl_image_format[] image_format,
long image_width,
long image_height,
long image_row_pitch,
Pointer host_ptr,
int[] errcode_ret)
Creates a 2D image object. |
static cl_mem |
clCreateImage3D(cl_context context,
long flags,
cl_image_format[] image_format,
long image_width,
long image_height,
long image_depth,
long image_row_pitch,
long image_slice_pitch,
Pointer host_ptr,
int[] errcode_ret)
Creates a 3D image object. |
static cl_kernel |
clCreateKernel(cl_program program,
java.lang.String kernel_name,
int[] errcode_ret)
Creates a kernal object. |
static int |
clCreateKernelsInProgram(cl_program program,
int num_kernels,
cl_kernel[] kernels,
int[] num_kernels_ret)
Creates kernel objects for all kernel functions in a program object. |
static cl_program |
clCreateProgramWithBinary(cl_context context,
int num_devices,
cl_device_id[] device_list,
long[] lengths,
byte[][] binaries,
int[] binary_status,
int[] errcode_ret)
Creates a program object for a context, and loads the binary bits specified by binary into the program object. |
static cl_program |
clCreateProgramWithSource(cl_context context,
int count,
java.lang.String[] strings,
long[] lengths,
int[] errcode_ret)
Creates a program object for a context, and loads the source code specified by the text strings in the strings array into the program object. |
static cl_sampler |
clCreateSampler(cl_context context,
boolean normalized_coords,
int addressing_mode,
int filter_mode,
int[] errcode_ret)
Creates a sampler object. |
static cl_mem |
clCreateSubBuffer(cl_mem buffer,
int flags,
int buffer_create_type,
Pointer buffer_create_info,
int[] errcode_ret)
Creates a buffer object (referred to as a sub-buffer object) from an existing buffer object. |
static cl_event |
clCreateUserEvent(cl_context context,
int[] errcode_ret)
Creates a user event object. |
static int |
clEnqueueAcquireGLObjects(cl_command_queue command_queue,
int num_objects,
cl_mem[] mem_objects,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Acquire OpenCL memory objects that have been created from OpenGL objects. |
static int |
clEnqueueBarrier(cl_command_queue command_queue)
A synchronization point that enqueues a barrier operation. |
static int |
clEnqueueCopyBuffer(cl_command_queue command_queue,
cl_mem src_buffer,
cl_mem dst_buffer,
long src_offset,
long dst_offset,
long cb,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to copy from one buffer object to another. |
static int |
clEnqueueCopyBufferRect(cl_command_queue command_queue,
cl_mem src_buffer,
cl_mem dst_buffer,
long[] src_origin,
long[] dst_origin,
long[] region,
long src_row_pitch,
long src_slice_pitch,
long dst_row_pitch,
long dst_slice_pitch,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to copy a rectangular region from the buffer object to another buffer object. |
static int |
clEnqueueCopyBufferToImage(cl_command_queue command_queue,
cl_mem src_buffer,
cl_mem dst_image,
long src_offset,
long[] dst_origin,
long[] region,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to copy a buffer object to an image object. |
static int |
clEnqueueCopyImage(cl_command_queue command_queue,
cl_mem src_image,
cl_mem dst_image,
long[] src_origin,
long[] dst_origin,
long[] region,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to copy image objects. |
static int |
clEnqueueCopyImageToBuffer(cl_command_queue command_queue,
cl_mem src_image,
cl_mem dst_buffer,
long[] src_origin,
long[] region,
long dst_offset,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to copy an image object to a buffer object. |
static java.nio.ByteBuffer |
clEnqueueMapBuffer(cl_command_queue command_queue,
cl_mem buffer,
boolean blocking_map,
long map_flags,
long offset,
long cb,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event,
int[] errcode_ret)
Enqueues a command to map a region of the buffer object given by buffer into the host address space and returns a pointer to this mapped region. |
static java.nio.ByteBuffer |
clEnqueueMapImage(cl_command_queue command_queue,
cl_mem image,
boolean blocking_map,
long map_flags,
long[] origin,
long[] region,
long[] image_row_pitch,
long[] image_slice_pitch,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event,
int[] errcode_ret)
Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region. |
static int |
clEnqueueMarker(cl_command_queue command_queue,
cl_event event)
Enqueues a marker command. |
static int |
clEnqueueNativeKernel(cl_command_queue command_queue,
EnqueueNativeKernelFunction user_func,
java.lang.Object args,
long cb_args,
int num_mem_objects,
cl_mem[] mem_list,
Pointer[] args_mem_loc,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler. |
static int |
clEnqueueNDRangeKernel(cl_command_queue command_queue,
cl_kernel kernel,
int work_dim,
long[] global_work_offset,
long[] global_work_size,
long[] local_work_size,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to execute a kernel on a device. |
static int |
clEnqueueReadBuffer(cl_command_queue command_queue,
cl_mem buffer,
boolean blocking_read,
long offset,
long cb,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueue commands to read from a buffer object to host memory. |
static int |
clEnqueueReadBufferRect(cl_command_queue command_queue,
cl_mem buffer,
boolean blocking_read,
long[] buffer_offset,
long[] host_offset,
long[] region,
long buffer_row_pitch,
long buffer_slice_pitch,
long host_row_pitch,
long host_slice_pitch,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueue commands to read from a rectangular region from a buffer object to host memory. |
static int |
clEnqueueReadImage(cl_command_queue command_queue,
cl_mem image,
boolean blocking_read,
long[] origin,
long[] region,
long row_pitch,
long slice_pitch,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to read from a 2D or 3D image object to host memory. |
static int |
clEnqueueReleaseGLObjects(cl_command_queue command_queue,
int num_objects,
cl_mem[] mem_objects,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Release OpenCL memory objects that have been created from OpenGL objects. |
static int |
clEnqueueTask(cl_command_queue command_queue,
cl_kernel kernel,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to execute a kernel on a device. |
static int |
clEnqueueUnmapMemObject(cl_command_queue command_queue,
cl_mem memobj,
java.nio.ByteBuffer mapped_ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to unmap a previously mapped region of a memory object. |
static int |
clEnqueueWaitForEvents(cl_command_queue command_queue,
int num_events,
cl_event[] event_list)
Enqueues a wait for a specific event or a list of events to complete before any future commands queued in the command-queue are executed. |
static int |
clEnqueueWriteBuffer(cl_command_queue command_queue,
cl_mem buffer,
boolean blocking_write,
long offset,
long cb,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueue commands to write to a buffer object from host memory. |
static int |
clEnqueueWriteBufferRect(cl_command_queue command_queue,
cl_mem buffer,
boolean blocking_read,
long[] buffer_offset,
long[] host_offset,
long[] region,
long buffer_row_pitch,
long buffer_slice_pitch,
long host_row_pitch,
long host_slice_pitch,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueue commands to write a rectangular region to a buffer object from host memory. |
static int |
clEnqueueWriteImage(cl_command_queue command_queue,
cl_mem image,
boolean blocking_write,
long[] origin,
long[] region,
long input_row_pitch,
long input_slice_pitch,
Pointer ptr,
int num_events_in_wait_list,
cl_event[] event_wait_list,
cl_event event)
Enqueues a command to write to a 2D or 3D image object from host memory. |
static int |
clFinish(cl_command_queue command_queue)
Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed. |
static int |
clFlush(cl_command_queue command_queue)
Issues all previously queued OpenCL commands in a command-queue to the device associated with the command-queue. |
static int |
clGetCommandQueueInfo(cl_command_queue command_queue,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Query information about a command-queue. |
static int |
clGetContextInfo(cl_context context,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Query information about a context. |
static int |
clGetDeviceIDs(cl_platform_id platform,
long device_type,
int num_entries,
cl_device_id[] devices,
int[] num_devices)
Obtain the list of devices available on a platform. |
static int |
clGetDeviceInfo(cl_device_id device,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Get information about an OpenCL device. |
static int |
clGetEventInfo(cl_event event,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns information about the event object. |
static int |
clGetEventProfilingInfo(cl_event event,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns profiling information for the command associated with event if profiling is enabled. |
static int |
clGetGLObjectInfo(cl_mem memobj,
int[] gl_object_type,
int[] gl_object_name)
Query an OpenGL memory object used to create an OpenCL memory object. |
static int |
clGetGLTextureInfo(cl_mem memobj,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns additional information about the GL texture object associated with a memory object. |
static int |
clGetImageInfo(cl_mem image,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Get information specific to an image object. |
static int |
clGetKernelInfo(cl_kernel kernel,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns information about the kernel object. |
static int |
clGetKernelWorkGroupInfo(cl_kernel kernel,
cl_device_id device,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns information about the kernel object that may be specific to a device. |
static int |
clGetMemObjectInfo(cl_mem memobj,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Used to get information that is common to all memory objects (buffer and image objects). |
static int |
clGetPlatformIDs(int num_entries,
cl_platform_id[] platforms,
int[] num_platforms)
Obtain the list of platforms available. |
static int |
clGetPlatformInfo(cl_platform_id platform,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Get specific information about the OpenCL platform. |
static int |
clGetProgramBuildInfo(cl_program program,
cl_device_id device,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns build information for each device in the program object. |
static int |
clGetProgramInfo(cl_program program,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns information about the program object. |
static int |
clGetSamplerInfo(cl_sampler sampler,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Returns information about the sampler object. |
static int |
clGetSupportedImageFormats(cl_context context,
long flags,
int image_type,
int num_entries,
cl_image_format[] image_formats,
int[] num_image_formats)
Get the list of image formats supported by an OpenCL implementation. |
static int |
clReleaseCommandQueue(cl_command_queue command_queue)
Decrements the command_queue reference count. |
static int |
clReleaseContext(cl_context context)
Decrement the context reference count. |
static int |
clReleaseEvent(cl_event event)
Decrements the event reference count. |
static int |
clReleaseKernel(cl_kernel kernel)
Decrements the kernel reference count. |
static int |
clReleaseMemObject(cl_mem memobj)
Decrements the memory object reference count. |
static int |
clReleaseProgram(cl_program program)
Decrements the program reference count. |
static int |
clReleaseSampler(cl_sampler sampler)
Decrements the sampler reference count. |
static int |
clRetainCommandQueue(cl_command_queue command_queue)
Increments the command_queue reference count. |
static int |
clRetainContext(cl_context context)
Increment the context reference count. |
static int |
clRetainEvent(cl_event event)
Increments the event reference count. |
static int |
clRetainKernel(cl_kernel kernel)
Increments the kernel object reference count. |
static int |
clRetainMemObject(cl_mem memobj)
Increments the memory object reference count. |
static int |
clRetainProgram(cl_program program)
Increments the program reference count. |
static int |
clRetainSampler(cl_sampler sampler)
Increments the sampler reference count. |
static int |
clSetCommandQueueProperty(cl_command_queue command_queue,
long properties,
boolean enable,
long[] old_properties)
Deprecated. This API introduces mutable state into the OpenCL implementation. It has been REMOVED to better facilitate thread safety. The 1.0 API is not thread safe. It is not tested by the OpenCL 1.1 conformance test, and consequently may not work or may not work dependably. It is likely to be non-performant. Use of this API is not advised. Use at your own risk. Software developers previously relying on this API are instructed to set the command queue properties when creating the queue, instead. |
static int |
clSetEventCallback(cl_event event,
int command_exec_callback_type,
EventCallbackFunction pfn_notify,
java.lang.Object user_data)
Registers a user callback function for a specific command execution status. |
static int |
clSetKernelArg(cl_kernel kernel,
int arg_index,
long arg_size,
Pointer arg_value)
Used to set the argument value for a specific argument of a kernel. |
static int |
clSetMemObjectDestructorCallback(cl_mem memobj,
MemObjectDestructorCallbackFunction pfn_notify,
java.lang.Object user_data)
Registers a user callback function that will be called when the memory object is deleted and its resources freed. |
static int |
clSetUserEventStatus(cl_event event,
int execution_status)
Sets the execution status of a user event object. |
static int |
clUnloadCompiler()
Allows the implementation to release the resources allocated by the OpenCL compiler. |
static int |
clWaitForEvents(int num_events,
cl_event[] event_list)
Waits on the host thread for commands identified by event objects to complete. |
static void |
setExceptionsEnabled(boolean enabled)
Enables or disables exceptions. |
static void |
setLogLevel(CL.LogLevel logLevel)
Set the specified log level for the library. |
static java.lang.String |
stringFor_cl_addressing_mode(int n)
Returns the String identifying the given cl_addressing_mode |
static java.lang.String |
stringFor_cl_build_status(int n)
Returns the String identifying the given cl_build_status |
static java.lang.String |
stringFor_cl_channel_order(int n)
Returns the String identifying the given cl_channel_order |
static java.lang.String |
stringFor_cl_channel_type(int n)
Returns the String identifying the given cl_channel_type |
static java.lang.String |
stringFor_cl_command_queue_info(int n)
Returns the String identifying the given cl_command_queue_info |
static java.lang.String |
stringFor_cl_command_queue_properties(long n)
Returns the string describing the given cl_command_queue_properties - bitfield |
static java.lang.String |
stringFor_cl_command_type(int n)
Returns the String identifying the given cl_command_type |
static java.lang.String |
stringFor_cl_context_info(int n)
Returns the String identifying the given cl_context_info |
static java.lang.String |
stringFor_cl_context_properties(int n)
Returns the String identifying the given cl_context_properties |
static java.lang.String |
stringFor_cl_device_address_info(long n)
Returns the string describing the given cl_device_address_info - bitfield |
static java.lang.String |
stringFor_cl_device_exec_capabilities(long n)
Returns the string describing the given cl_device_exec_capabilities - bitfield |
static java.lang.String |
stringFor_cl_device_fp_config(long n)
Returns the string describing the given cl_device_fp_config - bitfield |
static java.lang.String |
stringFor_cl_device_info(int n)
Returns the String identifying the given cl_device_info |
static java.lang.String |
stringFor_cl_device_local_mem_type(int n)
Returns the String identifying the given cl_device_local_mem_type |
static java.lang.String |
stringFor_cl_device_mem_cache_type(int n)
Returns the String identifying the given cl_device_mem_cache_type |
static java.lang.String |
stringFor_cl_device_type(long n)
Returns the string describing the given cl_device_type - bitfield |
static java.lang.String |
stringFor_cl_event_info(int n)
Returns the String identifying the given cl_event_info |
static java.lang.String |
stringFor_cl_filter_mode(int n)
Returns the String identifying the given cl_filter_mode |
static java.lang.String |
stringFor_cl_gl_object_type(int n)
Returns the String identifying the given cl_gl_object_type |
static java.lang.String |
stringFor_cl_gl_texture_info(int n)
Returns the String identifying the given cl_gl_texture_info |
static java.lang.String |
stringFor_cl_image_info(int n)
Returns the String identifying the given cl_image_info |
static java.lang.String |
stringFor_cl_kernel_info(int n)
Returns the String identifying the given cl_kernel_info |
static java.lang.String |
stringFor_cl_kernel_work_group_info(int n)
Returns the String identifying the given cl_kernel_work_group_info |
static java.lang.String |
stringFor_cl_khr_gl_sharing(int n)
Returns the String identifying the given cl_khr_gl_sharing |
static java.lang.String |
stringFor_cl_map_flags(long n)
Returns the string describing the given cl_map_flags - bitfield |
static java.lang.String |
stringFor_cl_mem_flags(long n)
Returns the string describing the given cl_mem_flags - bitfield |
static java.lang.String |
stringFor_cl_mem_info(int n)
Returns the String identifying the given cl_mem_info |
static java.lang.String |
stringFor_cl_mem_object_type(int n)
Returns the String identifying the given cl_mem_object_type |
static java.lang.String |
stringFor_cl_platform_info(int n)
Returns the String identifying the given cl_platform_info |
static java.lang.String |
stringFor_cl_profiling_info(int n)
Returns the String identifying the given cl_profiling_info |
static java.lang.String |
stringFor_cl_program_build_info(int n)
Returns the String identifying the given cl_program_build_info |
static java.lang.String |
stringFor_cl_program_info(int n)
Returns the String identifying the given cl_program_info |
static java.lang.String |
stringFor_cl_sampler_info(int n)
Returns the String identifying the given cl_sampler_info |
static java.lang.String |
stringFor_command_execution_status(int n)
Returns the command execution String identifying the given command_execution_status |
static java.lang.String |
stringFor_errorCode(int n)
Returns the String identifying the given error code |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int CL_CHAR_BIT
public static final int CL_SCHAR_MAX
public static final int CL_SCHAR_MIN
public static final int CL_CHAR_MAX
public static final int CL_CHAR_MIN
public static final int CL_UCHAR_MAX
public static final int CL_SHRT_MAX
public static final int CL_SHRT_MIN
public static final int CL_USHRT_MAX
public static final int CL_INT_MAX
public static final int CL_INT_MIN
public static final long CL_UINT_MAX
public static final long CL_LONG_MAX
public static final long CL_LONG_MIN
public static final long CL_ULONG_MAX
public static final int CL_FLT_DIG
public static final int CL_FLT_MANT_DIG
public static final int CL_FLT_MAX_10_EXP
public static final int CL_FLT_MAX_EXP
public static final int CL_FLT_MIN_10_EXP
public static final int CL_FLT_MIN_EXP
public static final int CL_FLT_RADIX
public static final float CL_FLT_MAX
public static final float CL_FLT_MIN
public static final float CL_FLT_EPSILON
public static final int CL_DBL_DIG
public static final int CL_DBL_MANT_DIG
public static final int CL_DBL_MAX_10_EXP
public static final int CL_DBL_MAX_EXP
public static final int CL_DBL_MIN_10_EXP
public static final int CL_DBL_MIN_EXP
public static final int CL_DBL_RADIX
public static final double CL_DBL_MAX
public static final double CL_DBL_MIN
public static final double CL_DBL_EPSILON
public static final int CL_SUCCESS
public static final int CL_DEVICE_NOT_FOUND
public static final int CL_DEVICE_NOT_AVAILABLE
public static final int CL_COMPILER_NOT_AVAILABLE
public static final int CL_MEM_OBJECT_ALLOCATION_FAILURE
public static final int CL_OUT_OF_RESOURCES
public static final int CL_OUT_OF_HOST_MEMORY
public static final int CL_PROFILING_INFO_NOT_AVAILABLE
public static final int CL_MEM_COPY_OVERLAP
public static final int CL_IMAGE_FORMAT_MISMATCH
public static final int CL_IMAGE_FORMAT_NOT_SUPPORTED
public static final int CL_BUILD_PROGRAM_FAILURE
public static final int CL_MAP_FAILURE
public static final int CL_MISALIGNED_SUB_BUFFER_OFFSET
public static final int CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST
public static final int CL_INVALID_VALUE
public static final int CL_INVALID_DEVICE_TYPE
public static final int CL_INVALID_PLATFORM
public static final int CL_INVALID_DEVICE
public static final int CL_INVALID_CONTEXT
public static final int CL_INVALID_QUEUE_PROPERTIES
public static final int CL_INVALID_COMMAND_QUEUE
public static final int CL_INVALID_HOST_PTR
public static final int CL_INVALID_MEM_OBJECT
public static final int CL_INVALID_IMAGE_FORMAT_DESCRIPTOR
public static final int CL_INVALID_IMAGE_SIZE
public static final int CL_INVALID_SAMPLER
public static final int CL_INVALID_BINARY
public static final int CL_INVALID_BUILD_OPTIONS
public static final int CL_INVALID_PROGRAM
public static final int CL_INVALID_PROGRAM_EXECUTABLE
public static final int CL_INVALID_KERNEL_NAME
public static final int CL_INVALID_KERNEL_DEFINITION
public static final int CL_INVALID_KERNEL
public static final int CL_INVALID_ARG_INDEX
public static final int CL_INVALID_ARG_VALUE
public static final int CL_INVALID_ARG_SIZE
public static final int CL_INVALID_KERNEL_ARGS
public static final int CL_INVALID_WORK_DIMENSION
public static final int CL_INVALID_WORK_GROUP_SIZE
public static final int CL_INVALID_WORK_ITEM_SIZE
public static final int CL_INVALID_GLOBAL_OFFSET
public static final int CL_INVALID_EVENT_WAIT_LIST
public static final int CL_INVALID_EVENT
public static final int CL_INVALID_OPERATION
public static final int CL_INVALID_GL_OBJECT
public static final int CL_INVALID_BUFFER_SIZE
public static final int CL_INVALID_MIP_LEVEL
public static final int CL_INVALID_GLOBAL_WORK_SIZE
public static final int CL_JOCL_INTERNAL_ERROR
public static final int CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR
public static final boolean CL_TRUE
public static final boolean CL_FALSE
public static final int CL_PLATFORM_PROFILE
public static final int CL_PLATFORM_VERSION
public static final int CL_PLATFORM_NAME
public static final int CL_PLATFORM_VENDOR
public static final int CL_PLATFORM_EXTENSIONS
public static final long CL_DEVICE_TYPE_DEFAULT
public static final long CL_DEVICE_TYPE_CPU
public static final long CL_DEVICE_TYPE_GPU
public static final long CL_DEVICE_TYPE_ACCELERATOR
public static final long CL_DEVICE_TYPE_ALL
public static final int CL_DEVICE_TYPE
public static final int CL_DEVICE_VENDOR_ID
public static final int CL_DEVICE_MAX_COMPUTE_UNITS
public static final int CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
public static final int CL_DEVICE_MAX_WORK_GROUP_SIZE
public static final int CL_DEVICE_MAX_WORK_ITEM_SIZES
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE
public static final int CL_DEVICE_MAX_CLOCK_FREQUENCY
public static final int CL_DEVICE_ADDRESS_BITS
public static final int CL_DEVICE_MAX_READ_IMAGE_ARGS
public static final int CL_DEVICE_MAX_WRITE_IMAGE_ARGS
public static final int CL_DEVICE_MAX_MEM_ALLOC_SIZE
public static final int CL_DEVICE_IMAGE2D_MAX_WIDTH
public static final int CL_DEVICE_IMAGE2D_MAX_HEIGHT
public static final int CL_DEVICE_IMAGE3D_MAX_WIDTH
public static final int CL_DEVICE_IMAGE3D_MAX_HEIGHT
public static final int CL_DEVICE_IMAGE3D_MAX_DEPTH
public static final int CL_DEVICE_IMAGE_SUPPORT
public static final int CL_DEVICE_MAX_PARAMETER_SIZE
public static final int CL_DEVICE_MAX_SAMPLERS
public static final int CL_DEVICE_MEM_BASE_ADDR_ALIGN
public static final int CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE
public static final int CL_DEVICE_SINGLE_FP_CONFIG
public static final int CL_DEVICE_GLOBAL_MEM_CACHE_TYPE
public static final int CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE
public static final int CL_DEVICE_GLOBAL_MEM_CACHE_SIZE
public static final int CL_DEVICE_GLOBAL_MEM_SIZE
public static final int CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE
public static final int CL_DEVICE_MAX_CONSTANT_ARGS
public static final int CL_DEVICE_LOCAL_MEM_TYPE
public static final int CL_DEVICE_LOCAL_MEM_SIZE
public static final int CL_DEVICE_ERROR_CORRECTION_SUPPORT
public static final int CL_DEVICE_PROFILING_TIMER_RESOLUTION
public static final int CL_DEVICE_ENDIAN_LITTLE
public static final int CL_DEVICE_AVAILABLE
public static final int CL_DEVICE_COMPILER_AVAILABLE
public static final int CL_DEVICE_EXECUTION_CAPABILITIES
public static final int CL_DEVICE_QUEUE_PROPERTIES
public static final int CL_DEVICE_NAME
public static final int CL_DEVICE_VENDOR
public static final int CL_DRIVER_VERSION
public static final int CL_DEVICE_PROFILE
public static final int CL_DEVICE_VERSION
public static final int CL_DEVICE_EXTENSIONS
public static final int CL_DEVICE_PLATFORM
public static final int CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF
public static final int CL_DEVICE_HOST_UNIFIED_MEMORY
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_INT
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE
public static final int CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF
public static final int CL_DEVICE_OPENCL_C_VERSION
public static final long CL_DEVICE_ADDRESS_32_BITS
public static final long CL_DEVICE_ADDRESS_64_BITS
public static final long CL_FP_DENORM
public static final long CL_FP_INF_NAN
public static final long CL_FP_ROUND_TO_NEAREST
public static final long CL_FP_ROUND_TO_ZERO
public static final long CL_FP_ROUND_TO_INF
public static final long CL_FP_FMA
public static final long CL_FP_SOFT_FLOAT
public static final int CL_NONE
public static final int CL_READ_ONLY_CACHE
public static final int CL_READ_WRITE_CACHE
public static final int CL_LOCAL
public static final int CL_GLOBAL
public static final long CL_EXEC_KERNEL
public static final long CL_EXEC_NATIVE_KERNEL
public static final long CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
public static final long CL_QUEUE_PROFILING_ENABLE
public static final int CL_CONTEXT_REFERENCE_COUNT
public static final int CL_CONTEXT_DEVICES
public static final int CL_CONTEXT_PROPERTIES
public static final int CL_CONTEXT_NUM_DEVICES
public static final int CL_CONTEXT_PLATFORM
public static final int CL_QUEUE_CONTEXT
public static final int CL_QUEUE_DEVICE
public static final int CL_QUEUE_REFERENCE_COUNT
public static final int CL_QUEUE_PROPERTIES
public static final long CL_MEM_READ_WRITE
public static final long CL_MEM_WRITE_ONLY
public static final long CL_MEM_READ_ONLY
public static final long CL_MEM_USE_HOST_PTR
public static final long CL_MEM_ALLOC_HOST_PTR
public static final long CL_MEM_COPY_HOST_PTR
public static final int CL_R
public static final int CL_A
public static final int CL_RG
public static final int CL_RA
public static final int CL_RGB
public static final int CL_RGBA
public static final int CL_BGRA
public static final int CL_ARGB
public static final int CL_INTENSITY
public static final int CL_LUMINANCE
public static final int CL_Rx
public static final int CL_RGx
public static final int CL_RGBx
public static final int CL_SNORM_INT8
public static final int CL_SNORM_INT16
public static final int CL_UNORM_INT8
public static final int CL_UNORM_INT16
public static final int CL_UNORM_SHORT_565
public static final int CL_UNORM_SHORT_555
public static final int CL_UNORM_INT_101010
public static final int CL_SIGNED_INT8
public static final int CL_SIGNED_INT16
public static final int CL_SIGNED_INT32
public static final int CL_UNSIGNED_INT8
public static final int CL_UNSIGNED_INT16
public static final int CL_UNSIGNED_INT32
public static final int CL_HALF_FLOAT
public static final int CL_FLOAT
public static final int CL_MEM_OBJECT_BUFFER
public static final int CL_MEM_OBJECT_IMAGE2D
public static final int CL_MEM_OBJECT_IMAGE3D
public static final int CL_MEM_TYPE
public static final int CL_MEM_FLAGS
public static final int CL_MEM_SIZE
public static final int CL_MEM_HOST_PTR
public static final int CL_MEM_MAP_COUNT
public static final int CL_MEM_REFERENCE_COUNT
public static final int CL_MEM_CONTEXT
public static final int CL_MEM_ASSOCIATED_MEMOBJECT
public static final int CL_MEM_OFFSET
public static final int CL_IMAGE_FORMAT
public static final int CL_IMAGE_ELEMENT_SIZE
public static final int CL_IMAGE_ROW_PITCH
public static final int CL_IMAGE_SLICE_PITCH
public static final int CL_IMAGE_WIDTH
public static final int CL_IMAGE_HEIGHT
public static final int CL_IMAGE_DEPTH
public static final int CL_ADDRESS_NONE
public static final int CL_ADDRESS_CLAMP_TO_EDGE
public static final int CL_ADDRESS_CLAMP
public static final int CL_ADDRESS_REPEAT
public static final int CL_ADDRESS_MIRRORED_REPEAT
public static final int CL_FILTER_NEAREST
public static final int CL_FILTER_LINEAR
public static final int CL_SAMPLER_REFERENCE_COUNT
public static final int CL_SAMPLER_CONTEXT
public static final int CL_SAMPLER_NORMALIZED_COORDS
public static final int CL_SAMPLER_ADDRESSING_MODE
public static final int CL_SAMPLER_FILTER_MODE
public static final long CL_MAP_READ
public static final long CL_MAP_WRITE
public static final int CL_PROGRAM_REFERENCE_COUNT
public static final int CL_PROGRAM_CONTEXT
public static final int CL_PROGRAM_NUM_DEVICES
public static final int CL_PROGRAM_DEVICES
public static final int CL_PROGRAM_SOURCE
public static final int CL_PROGRAM_BINARY_SIZES
public static final int CL_PROGRAM_BINARIES
public static final int CL_PROGRAM_BUILD_STATUS
public static final int CL_PROGRAM_BUILD_OPTIONS
public static final int CL_PROGRAM_BUILD_LOG
public static final int CL_BUILD_SUCCESS
public static final int CL_BUILD_NONE
public static final int CL_BUILD_ERROR
public static final int CL_BUILD_IN_PROGRESS
public static final int CL_KERNEL_FUNCTION_NAME
public static final int CL_KERNEL_NUM_ARGS
public static final int CL_KERNEL_REFERENCE_COUNT
public static final int CL_KERNEL_CONTEXT
public static final int CL_KERNEL_PROGRAM
public static final int CL_KERNEL_WORK_GROUP_SIZE
public static final int CL_KERNEL_COMPILE_WORK_GROUP_SIZE
public static final int CL_KERNEL_LOCAL_MEM_SIZE
public static final int CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE
public static final int CL_KERNEL_PRIVATE_MEM_SIZE
public static final int CL_EVENT_COMMAND_QUEUE
public static final int CL_EVENT_COMMAND_TYPE
public static final int CL_EVENT_REFERENCE_COUNT
public static final int CL_EVENT_COMMAND_EXECUTION_STATUS
public static final int CL_EVENT_CONTEXT
public static final int CL_COMMAND_NDRANGE_KERNEL
public static final int CL_COMMAND_TASK
public static final int CL_COMMAND_NATIVE_KERNEL
public static final int CL_COMMAND_READ_BUFFER
public static final int CL_COMMAND_WRITE_BUFFER
public static final int CL_COMMAND_COPY_BUFFER
public static final int CL_COMMAND_READ_IMAGE
public static final int CL_COMMAND_WRITE_IMAGE
public static final int CL_COMMAND_COPY_IMAGE
public static final int CL_COMMAND_COPY_IMAGE_TO_BUFFER
public static final int CL_COMMAND_COPY_BUFFER_TO_IMAGE
public static final int CL_COMMAND_MAP_BUFFER
public static final int CL_COMMAND_MAP_IMAGE
public static final int CL_COMMAND_UNMAP_MEM_OBJECT
public static final int CL_COMMAND_MARKER
public static final int CL_COMMAND_ACQUIRE_GL_OBJECTS
public static final int CL_COMMAND_RELEASE_GL_OBJECTS
public static final int CL_COMMAND_READ_BUFFER_RECT
public static final int CL_COMMAND_WRITE_BUFFER_RECT
public static final int CL_COMMAND_COPY_BUFFER_RECT
public static final int CL_COMMAND_USER
public static final int CL_COMPLETE
public static final int CL_RUNNING
public static final int CL_SUBMITTED
public static final int CL_QUEUED
public static final int CL_BUFFER_CREATE_TYPE_REGION
public static final int CL_PROFILING_COMMAND_QUEUED
public static final int CL_PROFILING_COMMAND_SUBMIT
public static final int CL_PROFILING_COMMAND_START
public static final int CL_PROFILING_COMMAND_END
public static final int CL_GL_OBJECT_BUFFER
public static final int CL_GL_OBJECT_TEXTURE2D
public static final int CL_GL_OBJECT_TEXTURE3D
public static final int CL_GL_OBJECT_RENDERBUFFER
public static final int CL_GL_TEXTURE_TARGET
public static final int CL_GL_MIPMAP_LEVEL
public static final int CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR
public static final int CL_DEVICES_FOR_GL_CONTEXT_KHR
public static final int CL_GL_CONTEXT_KHR
public static final int CL_EGL_DISPLAY_KHR
public static final int CL_GLX_DISPLAY_KHR
public static final int CL_WGL_HDC_KHR
public static final int CL_CGL_SHAREGROUP_KHR
Method Detail |
---|
public static void setExceptionsEnabled(boolean enabled)
enabled
- Whether exceptions are enabledpublic static java.lang.String stringFor_errorCode(int n)
n
- The error code
public static java.lang.String stringFor_cl_platform_info(int n)
n
- A cl_platform_info value
public static java.lang.String stringFor_cl_device_info(int n)
n
- A cl_device_info value
public static java.lang.String stringFor_cl_device_mem_cache_type(int n)
n
- A cl_device_mem_cache_type value
public static java.lang.String stringFor_cl_device_local_mem_type(int n)
n
- A cl_device_local_mem_type value
public static java.lang.String stringFor_cl_context_info(int n)
n
- A cl_context_info value
public static java.lang.String stringFor_cl_context_properties(int n)
n
- A cl_context_properties value
public static java.lang.String stringFor_cl_command_queue_info(int n)
n
- A cl_command_queue_info value
public static java.lang.String stringFor_cl_channel_order(int n)
n
- A cl_channel_order value
public static java.lang.String stringFor_cl_channel_type(int n)
n
- A cl_channel_type value
public static java.lang.String stringFor_cl_mem_object_type(int n)
n
- A cl_mem_object_type value
public static java.lang.String stringFor_cl_mem_info(int n)
n
- A cl_mem_info value
public static java.lang.String stringFor_cl_image_info(int n)
n
- A cl_image_info value
public static java.lang.String stringFor_cl_addressing_mode(int n)
n
- A cl_addressing_mode value
public static java.lang.String stringFor_cl_filter_mode(int n)
n
- A cl_filter_mode value
public static java.lang.String stringFor_cl_sampler_info(int n)
n
- A cl_sampler_info value
public static java.lang.String stringFor_cl_program_info(int n)
n
- A cl_program_info value
public static java.lang.String stringFor_cl_program_build_info(int n)
n
- A cl_program_build_info value
public static java.lang.String stringFor_cl_build_status(int n)
n
- A cl_build_status value
public static java.lang.String stringFor_cl_kernel_info(int n)
n
- A cl_kernel_info value
public static java.lang.String stringFor_cl_kernel_work_group_info(int n)
n
- A cl_kernel_work_group_info value
public static java.lang.String stringFor_cl_event_info(int n)
n
- A cl_event_info value
public static java.lang.String stringFor_cl_command_type(int n)
n
- A cl_command_type value
public static java.lang.String stringFor_command_execution_status(int n)
n
- A command_execution_status value
public static java.lang.String stringFor_cl_profiling_info(int n)
n
- A cl_profiling_info value
public static java.lang.String stringFor_cl_gl_object_type(int n)
n
- A cl_gl_object_type value
public static java.lang.String stringFor_cl_gl_texture_info(int n)
n
- A cl_gl_texture_info value
public static java.lang.String stringFor_cl_khr_gl_sharing(int n)
n
- A cl_khr_gl_sharing value
public static java.lang.String stringFor_cl_device_type(long n)
n
- The cl_device_type - bitfield
public static java.lang.String stringFor_cl_device_address_info(long n)
n
- The cl_device_address_info - bitfield
public static java.lang.String stringFor_cl_device_fp_config(long n)
n
- The cl_device_fp_config - bitfield
public static java.lang.String stringFor_cl_device_exec_capabilities(long n)
n
- The cl_device_exec_capabilities - bitfield
public static java.lang.String stringFor_cl_command_queue_properties(long n)
n
- The cl_command_queue_properties - bitfield
public static java.lang.String stringFor_cl_mem_flags(long n)
n
- The cl_mem_flags - bitfield
public static java.lang.String stringFor_cl_map_flags(long n)
n
- The cl_map_flags - bitfield
public static void setLogLevel(CL.LogLevel logLevel)
logLevel
- The log level to use.public static java.nio.ByteBuffer allocateAligned(int size, int alignment)
size
- The size of the bufferalignment
- The alignment, in bytes
public static int clGetPlatformIDs(int num_entries, cl_platform_id[] platforms, int[] num_platforms)
Obtain the list of platforms available.
cl_int clGetPlatformIDs(
| cl_uintnum_entries, |
cl_platform_id*platforms, | |
cl_uint*num_platforms) |
num_entries
The number of cl_platform_id entries that can be added to platforms
. If platforms
is not NULL, the num_entries
must be greater than zero.
platforms
Returns a list of OpenCL platforms found. The cl_platform_id values returned in
platforms
can be used to identify a specific OpenCL platform. If platforms
argument is NULL, this argument is ignored. The number of OpenCL platforms returned is the mininum of the value
specified by num_entries
or the number of OpenCL platforms available.
num_platforms
Returns the number of OpenCL platforms available. If num_platforms
is NULL, this argument is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise it returns CL_INVALID_VALUE if num_entries
is equal to zero and platforms
is not NULL, or if both num_platforms
and platforms
are NULL.
Returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clGetPlatformInfo(cl_platform_id platform, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Get specific information about the OpenCL platform.
cl_int clGetPlatformInfo(
| cl_platform_idplatform, |
cl_platform_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
platform
The platform ID returned by clGetPlatformIDs or can be NULL. If platform
is NULL, the behavior is implementation-defined.
param_name
An enumeration constant that identifies the platform information being queried. It can be one of the following values as specified in the table below.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size in bytes must be greater than or equal to size of return type specified in the table below.
param_value
A pointer to memory location where appropriate values for a given param_value
will be returned. Possible param_value
values returned are listed in the table below. If param_value
is NULL, it is ignored.
param_value_size_ret
Returns the actual size in bytes of data being queried by param_value
. If param_value_size_ret
is NULL, it is ignored
OpenCL Platform Queries
cl_platform_info | Return Type | Description |
---|---|---|
CL_PLATFORM_PROFILE
|
char[] |
OpenCL profile string. Returns the profile name supported by the implementation. The profile name returned can be one of the following strings: FULL_PROFILE - if the implementation supports the OpenCL specification (functionality defined as part of the core specification and does not require any extensions to be supported). EMBEDDED_PROFILE - if the implementation supports the OpenCL embedded profile. The embedded profile is defined to be a subset for each version of OpenCL. |
CL_PLATFORM_VERSION
|
char[] |
OpenCL version string. Returns the OpenCL version supported by the implementation. This version string has the following format:
The |
CL_PLATFORM_NAME
|
char[] | Platform name string. |
CL_PLATFORM_VENDOR
|
char[] | Platform vendor string. |
CL_PLATFORM_EXTENSIONS
|
char[] | Returns a space-separated list of extension names (the extension names themselves do not contain any spaces) supported by the platform. Extensions defined here must be supported by all devices associated with this platform. |
A null terminated string is returned by OpenCL query function calls if the return type of the information being queried is a char[].
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:
platform
is not a valid platform.
param_name
is not one of the supported values or if size in bytes specified by param_value_size
is less than size of return type and param_value
is not a NULL value.
The OpenCL specification does not describe the order of precedence for error codes returned by API calls.
public static int clGetDeviceIDs(cl_platform_id platform, long device_type, int num_entries, cl_device_id[] devices, int[] num_devices)
Obtain the list of devices available on a platform.
cl_int clGetDeviceIDs(
| cl_platform_idplatform, |
cl_device_typedevice_type, | |
cl_uintnum_entries, | |
cl_device_id*devices, | |
cl_uint*num_devices) |
platform
Refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform
is NULL, the behavior is implementation-defined.
device_type
A bitfield that identifies the type of OpenCL device. The device_type
can be used to query specific OpenCL devices or all OpenCL devices available. The valid values for device_type
are specified in the following table.
cl_device_type | Description |
---|---|
CL_DEVICE_TYPE_CPU
|
An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU. |
CL_DEVICE_TYPE_GPU
|
An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX. |
CL_DEVICE_TYPE_ACCELERATOR
|
Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe. |
CL_DEVICE_TYPE_DEFAULT
|
The default OpenCL device in the system. |
CL_DEVICE_TYPE_ALL
|
All OpenCL devices available in the system. |
num_entries
The number of cl_device entries that can be added to devices
. If devices
is not NULL, the num_entries
must be greater than zero.
devices
A list of OpenCL devices found. The cl_device_id values returned in devices
can be used to identify a specific OpenCL device. If devices
argument is NULL, this argument is ignored. The number of OpenCL devices returned is the mininum of the value specified by num_entries
or the number of OpenCL devices whose type matches device_type
.
num_devices
The number of OpenCL devices available that match device_type
. If num_devices
is NULL, this argument is ignored.
clGetDeviceIDs
may return all or a subset of the actual physical devices present in the platform and that match device_type
.
The application can query specific capabilities of the OpenCL device(s) returned by clGetDeviceIDs
. This can be used by the application to determine which device(s) to use.
clGetDeviceIDs
returns CL_SUCCESS if the function is executed successfully. Otherwise it returns one of the following:
platform
is not a valid platform.
device_type
is not a valid value.
num_entries
is equal to zero and devices
is not NULL or if both num_devices
and devices
are NULL.
device_type
were found.
public static int clGetDeviceInfo(cl_device_id device, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Get information about an OpenCL device.
cl_int clGetDeviceInfo(
| cl_device_iddevice, |
cl_device_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
device
Refers to the device returned by clGetDeviceIDs.
param_name
An enumeration constant that identifies the device information being queried. It can be one of the values as specified in the table below.
param_value
A pointer to memory location where appropriate values for a given param_name
as specified in the table below will be returned. If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size in bytes must be greater than or equal to size of return type specified in the table below.
param_value_size_ret
Returns the actual size in bytes of data being queried by param_value
. If param_value_size_ret
is NULL, it is ignored
cl_device_info | Description |
---|---|
CL_DEVICE_ADDRESS_BITS
|
Return type: cl_uint The default compute device address space size specified as an unsigned integer value in bits. Currently supported values are 32 or 64 bits. |
CL_DEVICE_AVAILABLE
|
Return type: cl_bool Is CL_TRUE if the device is available and CL_FALSE if the device is not available. |
CL_DEVICE_COMPILER_AVAILABLE
|
Return type: cl_bool Is CL_FALSE if the implementation does not have a compiler available to compile the program source. Is CL_TRUE if the compiler is available. This can be CL_FALSE for the embedded platform profile only. |
CL_DEVICE_DOUBLE_FP_CONFIG
|
Return type: cl_device_fp_config Describes the OPTIONAL double precision floating-point capability of the OpenCL device. This is a bit-field that describes one or more of the following values:
The mandated minimum double precision floating-point capability is CL_FP_FMA | CL_FP_ROUND_TO_NEAREST | CL_FP_ROUND_TO_ZERO | CL_FP_ROUND_TO_INF | CL_FP_INF_NAN | CL_FP_DENORM. |
CL_DEVICE_ENDIAN_LITTLE
|
Return type: cl_bool Is CL_TRUE if the OpenCL device is a little endian device and CL_FALSE otherwise. |
CL_DEVICE_ERROR_CORRECTION_SUPPORT
|
Return type: cl_bool Is CL_TRUE if the device implements error correction for all accesses to compute device memory (global and constant). Is CL_FALSE if the device does not implement such error correction. |
CL_DEVICE_EXECUTION_CAPABILITIES
|
Return type: cl_device_exec_capabilities Describes the execution capabilities of the device. This is a bit-field that describes one or more of the following values: CL_EXEC_KERNEL - The OpenCL device can execute OpenCL kernels. CL_EXEC_NATIVE_KERNEL - The OpenCL device can execute native kernels. The mandated minimum capability is CL_EXEC_KERNEL. |
CL_DEVICE_EXTENSIONS
|
Return type: char[] Returns a space-separated list of extension names (the extension names themselves do not contain any spaces). The list of extension names returned currently can include one or more of the following approved extension names: cl_khr_fp64 |
CL_DEVICE_GLOBAL_MEM_CACHE_SIZE
|
Return type: cl_ulong Size of global memory cache in bytes. |
CL_DEVICE_GLOBAL_MEM_CACHE_TYPE
|
Return type: cl_device_mem_cache_type Type of global memory cache supported. Valid values are: CL_NONE, CL_READ_ONLY_CACHE, and CL_READ_WRITE_CACHE. |
CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE
|
Return type: cl_uint Size of global memory cache line in bytes. |
CL_DEVICE_GLOBAL_MEM_SIZE
|
Return type: cl_ulong Size of global device memory in bytes. |
CL_DEVICE_HALF_FP_CONFIG
|
Return type: cl_device_fp_config Describes the OPTIONAL half precision floating-point capability of the OpenCL device. This is a bit-field that describes one or more of the following values:
The required minimum half precision floating-point capability as implemented by this extension is CL_FP_ROUND_TO_ZERO or CL_FP_ROUND_TO_INF | CL_FP_INF_NAN. |
CL_DEVICE_HOST_UNIFIED_MEMORY
|
Return type: cl_bool Is CL_TRUE if the device and the host have a unified memory subsystem and is CL_FALSE otherwise. |
CL_DEVICE_IMAGE_SUPPORT
|
Return type: cl_bool Is CL_TRUE if images are supported by the OpenCL device and CL_FALSE otherwise. |
CL_DEVICE_IMAGE2D_MAX_HEIGHT
|
Return type: size_t Max height of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE2D_MAX_WIDTH
|
Return type: size_t Max width of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE3D_MAX_DEPTH
|
Return type: size_t Max depth of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE3D_MAX_HEIGHT
|
Return type: size_t Max height of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE3D_MAX_WIDTH
|
Return type: size_t Max width of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_LOCAL_MEM_SIZE
|
Return type: cl_ulong Size of local memory arena in bytes. The minimum value is 32 KB. |
CL_DEVICE_LOCAL_MEM_TYPE
|
Return type: cl_device_local_mem_type Type of local memory supported. This can be set to CL_LOCAL implying dedicated local memory storage such as SRAM, or CL_GLOBAL. |
CL_DEVICE_MAX_CLOCK_FREQUENCY
|
Return type: cl_uint Maximum configured clock frequency of the device in MHz. |
CL_DEVICE_MAX_COMPUTE_UNITS
|
Return type: cl_uint The number of parallel compute cores on the OpenCL device. The minimum value is 1. |
CL_DEVICE_MAX_CONSTANT_ARGS
|
Return type: cl_uint Max number of arguments declared with the __constant qualifier in a kernel. The minimum value is 8. |
CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE
|
Return type: cl_ulong Max size in bytes of a constant buffer allocation. The minimum value is 64 KB. |
CL_DEVICE_MAX_MEM_ALLOC_SIZE
|
Return type: cl_ulong Max size of memory object allocation in bytes. The minimum value is max (1/4th of CL_DEVICE_GLOBAL_MEM_SIZE, 128*1024*1024) |
CL_DEVICE_MAX_PARAMETER_SIZE
|
Return type: size_t Max size in bytes of the arguments that can be passed to a kernel. The minimum value is 1024. For this minimum value, only a maximum of 128 arguments can be passed to a kernel. |
CL_DEVICE_MAX_READ_IMAGE_ARGS
|
Return type: cl_uint Max number of simultaneous image objects that can be read by a kernel. The minimum value is 128 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_MAX_SAMPLERS
|
Return type: cl_uint Maximum number of samplers that can be used in a kernel. The minimum value is 16 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. (Also see sampler_t.) |
CL_DEVICE_MAX_WORK_GROUP_SIZE
|
Return type: size_t Maximum number of work-items in a work-group executing a kernel using the data parallel execution model. (Refer to clEnqueueNDRangeKernel). The minimum value is 1. |
CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
|
Return type: cl_uint Maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model. (Refer to clEnqueueNDRangeKernel). The minimum value is 3. |
CL_DEVICE_MAX_WORK_ITEM_SIZES
|
Return type: size_t[] Maximum number of work-items that can be specified in each dimension of the work-group to clEnqueueNDRangeKernel. Returns |
CL_DEVICE_MAX_WRITE_IMAGE_ARGS
|
Return type: cl_uint Max number of simultaneous image objects that can be written to by a kernel. The minimum value is 8 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_MEM_BASE_ADDR_ALIGN
|
Return type: cl_uint Describes the alignment in bits of the base address of any allocated memory object. |
CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE
|
Return type: cl_uint The smallest alignment in bytes which can be used for any data type. |
CL_DEVICE_NAME
|
Return type: char[] Device name string. |
CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR
|
Return type: cl_uint Returns the native ISA vector width. The vector width is defined as the number of scalar elements that can be stored in the vector. If the cl_khr_fp64 extension is not supported, CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE must return 0. If the cl_khr_fp16 extension is not supported, CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF must return 0. |
CL_DEVICE_OPENCL_C_VERSION
|
Return type: char[] OpenCL C version string. Returns the highest OpenCL C version supported by the compiler for this device. This version string has the following format:
The The |
CL_DEVICE_PLATFORM
|
Return type: cl_platform_id The platform associated with this device. |
CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR
|
Return type: cl_uint Preferred native vector width size for built-in scalar types that can be put into vectors. The vector width is defined as the number of scalar elements that can be stored in the vector. If the cl_khr_fp64 extension is not supported, CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE must return 0. If the cl_khr_fp16 extension is not supported, CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF must return 0. |
CL_DEVICE_PROFILE
|
Return type: char[] OpenCL profile string. Returns the profile name supported by the device (see note). The profile name returned can be one of the following strings: FULL_PROFILE - if the device supports the OpenCL specification (functionality defined as part of the core specification and does not require any extensions to be supported). EMBEDDED_PROFILE - if the device supports the OpenCL embedded profile. |
CL_DEVICE_PROFILING_TIMER_RESOLUTION
|
Return type: size_t Describes the resolution of device timer. This is measured in nanoseconds. |
CL_DEVICE_QUEUE_PROPERTIES
|
Return type: cl_command_queue_properties Describes the command-queue properties supported by the device. This is a bit-field that describes one or more of the following values: CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE CL_QUEUE_PROFILING_ENABLE These properties are described in the table for clCreateCommandQueue. The mandated minimum capability is CL_QUEUE_PROFILING_ENABLE. |
CL_DEVICE_SINGLE_FP_CONFIG
|
Return type: cl_device_fp_config Describes single precision floating-point capability of the device. This is a bit-field that describes one or more of the following values: CL_FP_DENORM - denorms are supported CL_FP_INF_NAN - INF and quiet NaNs are supported CL_FP_ROUND_TO_NEAREST - round to nearest even rounding mode supported CL_FP_ROUND_TO_ZERO - round to zero rounding mode supported CL_FP_ROUND_TO_INF - round to +ve and -ve infinity rounding modes supported CL_FP_FMA - IEEE754-2008 fused multiply-add is supported CL_FP_SOFT_FLOAT - Basic floating-point operations (such as addition, subtraction, multiplication) are implemented in software. The mandated minimum floating-point capability is CL_FP_ROUND_TO_NEAREST | CL_FP_INF_NAN. |
CL_DEVICE_TYPE
|
Return type: cl_device_type The OpenCL device type. Currently supported values are one of or a combination of: CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ACCELERATOR, or CL_DEVICE_TYPE_DEFAULT. |
CL_DEVICE_VENDOR
|
Return type: char[] Vendor name string. |
CL_DEVICE_VENDOR_ID
|
Return type: cl_uint A unique device vendor identifier. An example of a unique device identifier could be the PCIe ID. |
CL_DEVICE_VERSION
|
Return type: char[] OpenCL version string. Returns the OpenCL version supported by the device. This version string has the following format:
The |
CL_DRIVER_VERSION
|
Return type: char[] OpenCL software driver version string in the form |
CL_DEVICE_PROFILE: The platform profile returns the profile that is implemented by the OpenCL framework. If the platform profile returned is FULL_PROFILE, the OpenCL framework will support devices that are FULL_PROFILE and may also support devices that are EMBEDDED_PROFILE. The compiler must be available for all devices i.e. CL_DEVICE_COMPILER_AVAILABLE is CL_TRUE. If the platform profile returned is EMBEDDED_PROFILE, then devices that are only EMBEDDED_PROFILE are supported.
clGetDeviceInfo
returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:
device
is not valid.
param_name
is not one of the supported values or if size in
bytes specified by param_value_size
is less than size of return type as shown in the table above and
param_value
is not a NULL value.
public static cl_context clCreateContext(cl_context_properties properties, int num_devices, cl_device_id[] devices, CreateContextFunction pfn_notify, java.lang.Object user_data, int[] errcode_ret)
Creates an OpenCL context.
cl_context clCreateContext(
| const cl_context_properties*properties, |
cl_uintnum_devices, | |
const cl_device_id*devices, | |
(voidCL_CALLBACK *pfn_notify)
(
constchar*errinfo, ) ,
|
|
void*user_data, | |
cl_int*errcode_ret) |
An OpenCL context is created with one or more devices. Contexts are used by the OpenCL runtime for managing objects such as command-queues, memory, program and kernel objects and for executing kernels on one or more devices specified in the context.
Specifies a list of context property names and their corresponding values. Each property name is
immediately followed by the corresponding desired value. The list is terminated with 0.
properties
can be NULL in which case the platform that is selected is
implementation-defined. The list of supported properties
is described in the table below.
If the extension cl_khr_d3d10_sharing
is enabled, then if a property is not specified in properties
, then its default value is used
(it is said to be specified implicitly). If properties
is NULL or empty (points to a list
whose first value is zero), all attributes take on their default value.
If the extension cl_khr_gl_sharing
is enabled, then properties
points to an attribute list, which is a array of ordered <attribute name, value> pairs terminated with zero. If an attribute is not specified in properties
, then its default value is used (it is said to be specified implicitly). If properties
is NULL or empty (points to a list whose first value is zero), all attributes take on their default values..
cl_context_properties enum | Property value | Description |
---|---|---|
CL_CONTEXT_PLATFORM
|
cl_platform_id | Specifies the platform to use. |
CL_CONTEXT_D3D10_DEVICE_KHR
|
ID3D10Device* | If the cl_khr_d3d10_sharing extension is enabled, specifies the ID3D10Device* to use for Direct3D 10 interoperability. The default value is NULL. |
|
Available if the cl_khr_gl_sharing extension is enabled. |
num_devices
The number of devices specified in the devices
argument.
devices
A pointer to a list of unique devices returned by clGetDeviceIDs
for a platform. Duplicate devices specified in devices
are ignored.
pfn_notify
A callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors that occur in this context. This callback function may be called asynchronously by the OpenCL implementation.
It is the application's responsibility to ensure that the callback function is thread-safe. If pfn_notify
is NULL, no callback function is registered. The parameters to this callback function are:
errinfo
is a pointer to an error string.
private_info
and cb
represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.
user_data
is a pointer to user supplied data.
NOTE: There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify
callback. Where these notifications go is implementation-defined.
user_data
Passed as the user_data
argument when pfn_notify
is called. user_data
can be NULL.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
clCreateContext
and clCreateContextFromType perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application.
However, it is possible that the application may delete the context without informing the library.
Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context
being used by a library no longer being valid.
clCreateContext
returns a valid non-zero context and errcode_ret
is set to CL_SUCCESS if the context is created successfully. Otherwise, it returns NULL value with the following error
values returned in errcode_ret
:
properties
is NULL and no platform could be selected or if platform value specified in properties
is not a valid platform. (If the extension cl_khr_gl_sharing is enabled, then see error "CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR" below.)
properties
is not a supported
property name, if the value specified for a supported property name is not valid, or if the
same property name is specified more than once. However if the extension cl_khr_gl_sharing is enabled, then CL_INVALID_PROPERTY is returned if an attribute name other than those listed in the table for properties
above is specified in properties
.
devices
is NULL; if num_devices
is equal to zero; or
if pfn_notify
is NULL but user_data
is not NULL.
devices
contains an invalid device.
devices
is currently not available
even though the device was returned by clGetDeviceIDs.
cl_device_ids
against which this context
is to be created may interoperate (if the
cl_khr_d3d10_sharing extension is enabled).
properties
(only if the
cl_khr_gl_sharing extension is enabled).
public static cl_context clCreateContextFromType(cl_context_properties properties, long device_type, CreateContextFunction pfn_notify, java.lang.Object user_data, int[] errcode_ret)
Create an OpenCL context from a device type that identifies the specific device(s) to use.
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)
|
Specifies a list of context property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. properties
can be NULL in which case the platform that is selected is implementation-defined. The list of supported properties is described in the table below.
cl_context_properties enum | Property value | Description |
---|---|---|
CL_CONTEXT_PLATFORM
|
cl_platform_id | Specifies the platform to use. |
CL_CONTEXT_D3D10_DEVICE_KHR
|
ID3D10Device* | If the cl_khr_d3d10_sharing extension is enabled, specifies the ID3D10Device* to use for Direct3D 10 interoperability. The default value is NULL. |
|
Available if the cl_khr_gl_sharing extension is enabled. |
A bit-field that identifies the type of device and is described in the table below.
cl_device_type | Description |
---|---|
CL_DEVICE_TYPE_CPU
|
An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU. |
CL_DEVICE_TYPE_GPU
|
An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX. |
CL_DEVICE_TYPE_ACCELERATOR
|
Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe. |
CL_DEVICE_TYPE_DEFAULT
|
The default OpenCL device in the system. |
CL_DEVICE_TYPE_ALL
|
All OpenCL devices available in the system. |
pfn_notify
A callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors that occur in this context. This callback function may be called asynchronously by the OpenCL implementation.
It is the application's responsibility to ensure that the callback function is thread-safe. If pfn_notify
is NULL, no callback function is registered. The parameters to this callback function are:
errinfo
is a pointer to an error string.
private_info
and cb
represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.
user_data
is a pointer to user supplied data.
There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify
callback. Where these notifications go is implementation-defined.
user_data
Passed as the user_data
argument when pfn_notify
is called. user_data can be NULL.
errcode_ret
Return an appropriate error code. If errcode_ret is NULL, no error code is returned.
clCreateContextFromType
may return all or a subset of the actual physical devices present in the platform and that match device_type
.
clCreateContextFromType
and clCreateContext perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application.
However, it is possible that the application may delete the context without informing the library.
Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context
being used by a library no longer being valid.
clCreateContextFromType
returns a valid non-zero context and errcode_ret
is set
to CL_SUCCESS if the context is created successfully. Otherwise, it returns a NULL value with the following
error vlaues returned in errcode_ret
:
properties
is NULL and no platform could be selected or
if platform value specified in properties
is not a valid platform. (If the extension cl_khr_gl_sharing is enabled, then see error "CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR" below.)
properties
is not a supported property
name, or if the value specified for a supported property name is not valid, or if the same property name is specified more than once.
pfn_notify
is NULL but user_data
is not NULL.
device_type
is not a valid value.
device_type
and property values
specified in properties
are currently available.
device_type
and property values
specified in properties
were found.
cl_device_ids
against which this context
is to be created may interoperate (if the
cl_khr_d3d10_sharing extension is enabled).
properties
if the cl_khr_gl_sharing extension is enabled.
Example goes here - it will be set in "code" type with white space preserved. |
public static int clRetainContext(cl_context context)
Increment the context reference count.
cl_int
clRetainContext
(
| cl_contextcontext) |
context
The context to retain.
clCreateContext and clCreateContextFromType perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application. However, it is possible that the application may delete the context without informing the library. Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context being used by a library no longer being valid.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following values:
context
is not a valid OpenCL context.
public static int clReleaseContext(cl_context context)
Decrement the context reference count.
cl_int
clReleaseContext
(
| cl_contextcontext) |
context
The context to release.
After the context
reference count becomes zero and all the objects attached to context
(such as
memory objects, command-queues) are released, the context
is deleted.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following values:
context
is not a valid OpenCL context.
public static int clGetContextInfo(cl_context context, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Query information about a context.
cl_int
clGetContextInfo
(
| cl_contextcontext, |
cl_context_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t *param_value_size_ret) |
context
Specifies the OpenCL context being queried.
param_name
An enumeration constant that specifies the information to query.
The valid values for param_name
are:
cl_context_info | Return Type | Information returned in param_value |
---|---|---|
CL_CONTEXT_REFERENCE_COUNT
|
cl_uint |
Return the context reference count. The reference count returned should be
considered immediately stale. It is unsuitable for general use in applications. This feature is provided
for identifying memory leaks.
|
CL_CONTEXT_NUM_DEVICES
|
cl_uint |
Return the number of devices in context .
|
CL_CONTEXT_DEVICES
|
cl_device_id[] |
Return the list of devices in context .
|
CL_CONTEXT_PROPERTIES
|
cl_context_properties[] |
Return the properties argument specified
in clCreateContext or
clCreateContextFromType.
If the
If the |
CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR
|
cl_bool |
If the
cl_khr_d3d10_sharing
extension is enabled, returns CL_TRUE if Direct3D 10 resources created as
shared by setting MiscFlags to include D3D10_RESOURCE_MISC_SHARED will perform if
aster when shared with OpenCL, compared with resources which have not set this flag. Otherwise
returns CL_FALSE.
|
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size must be greater than or equal to the size of return type as described in the table above.
param_value_size_ret
Returns the actual size in bytes of data being queried by param_value
. If
param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
context
is not a valid context.
param_name
is not one of the supported values or if size in
bytes specified by param_value_size
is less than size of return type as specified in the table above
and param_value
is not a NULL value.
public static cl_command_queue clCreateCommandQueue(cl_context context, cl_device_id device, long properties, int[] errcode_ret)
Create a command-queue on a specific device.
cl_command_queue clCreateCommandQueue(
| cl_contextcontext, |
cl_device_iddevice, | |
cl_command_queue_propertiesproperties, | |
cl_int*errcode_ret) |
context
Must be a valid OpenCL context.
device
Must be a device associated with context
. It can either be in the list of devices specified when context
is created using clCreateContext or have the same device type as the device type specified when the context
is created using clCreateContextFromType.
properties
Specifies a list of properties for the command-queue. This is a bit-field. Only command-queue properties specified in the table below can be set in
properties
; otherwise the value specified in properties
is considered to be not valid.
Command-Queue Properties | Description |
---|---|
CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
|
Determines whether the commands queued in the command-queue are executed in-order or out-of-order. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order. |
CL_QUEUE_PROFILING_ENABLE
|
Enable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled. See clGetEventProfilingInfo for more information. |
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL
, no error code is returned.
The OpenCL functions that are submitted to a command-queue are enqueued in the order the
calls are made but can be configured to execute in-order or out-of-order. The properties
argument in clCreateCommandQueue
can be used to specify the execution order.
If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a command-queue is not set, the commands enqueued to a command-queue execute in order. For example, if an application calls clEnqueueNDRangeKernel to execute kernel A followed by a clEnqueueNDRangeKernel to execute kernel B, the application can assume that kernel A finishes first and then kernel B is executed. If the memory objects output by kernel A are inputs to kernel B then kernel B will see the correct data in memory objects produced by execution of kernel A. If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a commandqueue is set, then there is no guarantee that kernel A will finish before kernel B starts execution.
Applications can configure the commands enqueued to a command-queue to execute out-of-order by setting the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of the command-queue. This can be specified when the command-queue is created. In out-of-order execution mode there is no guarantee that the enqueued commands will finish execution in the order they were queued. As there is no guarantee that kernels will be executed in order, that is based on when the clEnqueueNDRangeKernel calls are made within a command-queue, it is therefore possible that an earlier clEnqueueNDRangeKernel call to execute kernel A identified by event A may execute and/or finish later than a clEnqueueNDRangeKernel call to execute kernel B which was called by the application at a later point in time. To guarantee a specific order of execution of kernels, a wait on a particular event (in this case event A) can be used. The wait for event A can be specified in the event_wait_list
argument to clEnqueueNDRangeKernel for kernel B.
In addition, a wait for events or a barrier command can be enqueued to the command-queue. The wait for events command ensures that previously enqueued commands identified by the list of events to wait for have finished before the next batch of commands is executed. The barrier command ensures that all previously enqueued commands in a command-queue have finished execution before the next batch of commands is executed.
Similarly, commands to read, write, copy or map memory objects that are enqueued after clEnqueueNDRangeKernel, clEnqueueTask or clEnqueueNativeKernel commands are not guaranteed to wait for kernels scheduled for execution to have completed (if the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property is set). To ensure correct ordering of commands, the event object returned by clEnqueueNDRangeKernel, clEnqueueTask or clEnqueueNativeKernel can be used to enqueue a wait for event or a barrier command can be enqueued that must complete before reads or writes to the memory object(s) occur.
clCreateCommandQueue
returns a valid non-zero command-queue and errcode_ret
is set to CL_SUCCESS if the command-queue is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret
:
context
is not a valid context.
device
is not a valid device or is
not associated with context
.
properties
are not valid.
properties
are valid but are not supported by the device.
public static int clRetainCommandQueue(cl_command_queue command_queue)
Increments the command_queue
reference count.
cl_int clRetainCommandQueue(
| cl_command_queuecommand_queue) |
command_queue
Specifies the command-queue to retain.
clCreateCommandQueue
performs an implicit retain. This is very helpful for 3rd party libraries, which typically get a command-queue passed to them by the application. However, it is possible that the application may delete the command-queue without informing the library. Allowing functions to attach to (i.e. retain) and release a command-queue solves the problem of a command-queue being used by a library no longer being valid.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
command_queue
is not a valid command-queue.
public static int clReleaseCommandQueue(cl_command_queue command_queue)
Decrements the command_queue
reference count.
cl_int clReleaseCommandQueue(
| cl_command_queuecommand_queue) |
command_queue
Specifies the command-queue to release.
After the command_queue
reference count becomes zero and all commands queued to
command_queue
have finished (e.g., kernel executions, memory object updates, etc.), the command-queue is deleted.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following:
command_queue
is not a valid command queue.
Returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue
is not a valid command-queue.
public static int clGetCommandQueueInfo(cl_command_queue command_queue, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Query information about a command-queue.
cl_int clGetCommandQueueInfo(
| cl_command_queuecommand_queue, |
cl_command_queue_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
command_queue
Specifies the command-queue being queried.
param_name
Specifies the information to query.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size must be greater than or equal to the size of return type as described in the table below. If param_value
is NULL, it is ignored.
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size_ret
Returns the actual size in bytes of data being queried by param_value
. If param_value_size_ret
is NULL, it is ignored
The list of supported param_name
values and the information returned in param_value
by clGetCommandQueueInfo
is described in the table below.
cl_command_queue_info | Return Type and Information returned in param_value |
---|---|
CL_QUEUE_CONTEXT
|
Return type: cl_context
Return the context specified when the command-queue is created. |
CL_QUEUE_DEVICE
|
Return type: cl_device_id
Return the device specified when the command-queue is created. |
CL_QUEUE_REFERENCE_COUNT
|
Return type: cl_uint
Return the command-queue reference count.
The reference count returned with |
CL_QUEUE_PROPERTIES
|
Return type: cl_command_queue_properties
Return the currently specified properties for the command-queue. These properties are specified by the properties argument in clCreateCommandQueue. |
It is possible that a device(s) becomes unavailable after a context and command-queues that use
this device(s) have been created and commands have been queued to command-queues. In this
case the behavior of OpenCL API calls that use this context (and command-queues) are
considered to be implementation-defined. The user callback function, if specified, when the
context is created can be used to record appropriate information in the errinfo
, private_info
arguments passed to the callback function when the device becomes unavailable.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:
command_queue
is not a valid command-queue.
param_name
is not one of the supported values or if size
in bytes specified by param_value_size
is less than size of return type and param_value
is not a NULL value.
public static int clSetCommandQueueProperty(cl_command_queue command_queue, long properties, boolean enable, long[] old_properties)
Enable or disable the properties of a command-queue.
cl_int clSetCommandQueueProperty(
| cl_command_queuecommand_queue, |
cl_command_queue_propertiesproperties, | |
cl_boolenable, | |
cl_command_queue_properties*old_properties) |
THIS FUNCITON IS DEPRECATED.
command_queue
Specifies the command-queue being queried.
properties
Specifies the new command-queue properties to be applied to command_queue
. Only command-queue properties specified for clCreateCommandQueue can be set in properties
; otherwise the value specified in properties
is considered to be not valid.
enable
Determines whether the values specified by properties
are enabled (if enable
is CL_TRUE
) or disabled (if enable
is CL_FALSE
) for the command-queue. The allowed property values are the same as those specified for clCreateCommandQueue.
old_properties
Returns the command-queue properties before they were changed by
clSetCommandQueueProperty
. If old_properties
is NULL, it is ignored.
As specified for clCreateCommandQueue, the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
command-queue property determines whether the commands in a command-queue are executed in-order or out-of-order. Changing this command-queue property will cause the OpenCL implementation to block until all previously queued commands in command_queue
have completed. This can be an expensive operation and therefore changes to the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property should be only done when absolutely necessary.
It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this
case the behavior of OpenCL API calls that use this context (and command-queues) are
considered to be implementation-defined. The user callback function, if specified when the
context is created, can be used to record appropriate information in the errinfo
, private_info
arguments passed to the callback function when the device becomes unavailable.
Returns CL_SUCCESS if the command-queue properties are successfully updated. Otherwise, it returns the following:
command_queue
is not a valid command-queue.
properties
are not valid.
properties
are not supported by the device.
public static cl_mem clCreateBuffer(cl_context context, long flags, long size, Pointer host_ptr, int[] errcode_ret)
Creates a buffer object.
cl_mem clCreateBuffer
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
size_tsize, | |
void*host_ptr, | |
cl_int*errcode_ret) |
context
A valid OpenCL context used to create the buffer object.
flags
A bit-field that is used to specify allocation and usage information such as the memory
arena that should be used to allocate the buffer object and how it will be used. The
following table describes the possible values for flags
:
cl_mem_flags | Description |
---|---|
CL_MEM_READ_WRITE
|
This flag specifies that the memory object will be read and written by a kernel. This is the default. |
CL_MEM_WRITE_ONLY
|
This flags specifies that the memory object will be written but not read by a kernel. Reading from a buffer or image object created with
|
CL_MEM_READ_ONLY
|
This flag specifies that the memory object is a read-only memory object when used inside a kernel. Writing to a buffer or image object created with
|
CL_MEM_USE_HOST_PTR
|
This flag is valid only if OpenCL implementations are allowed to cache the buffer
contents pointed to by The result of OpenCL commands that operate on multiple
buffer objects created with the same |
CL_MEM_ALLOC_HOST_PTR
|
This flag specifies that the application wants the OpenCL implementation to allocate memory from host accessible memory.
|
CL_MEM_COPY_HOST_PTR
|
This flag is valid only if
|
size
The size in bytes of the buffer memory object to be allocated.
host_ptr
A pointer to the buffer data that may already be allocated by the application. The size
of the buffer that host_ptr
points to must be greater than or equal to the size
bytes.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
Returns a valid non-zero buffer object and errcode_ret
is set to CL_SUCCESS if
the buffer object is created successfully. Otherwise, it returns a NULL value with one of the
following error values returned in errcode_ret
:
context
is not a valid context..
flags
are not valid.
size
is 0 or is greater than
CL_DEVICE_MAX_MEM_ALLOC_SIZE value specified in table of OpenCL Device Queries
for clGetDeviceInfo for all devices in context
.
host_ptr
is NULL and CL_MEM_USE_HOST_PTR or
CL_MEM_COPY_HOST_PTR are set in flags
or if host_ptr
is not NULL but
CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in flags
.
public static cl_mem clCreateSubBuffer(cl_mem buffer, int flags, int buffer_create_type, Pointer buffer_create_info, int[] errcode_ret)
Creates a buffer object (referred to as a sub-buffer object) from an existing buffer object.
cl_mem clCreateSubBuffer
(
| cl_membuffer, |
cl_mem_flagsflags, | |
cl_buffer_create_typebuffer_create_type, | |
const void*buffer_create_info, | |
cl_int*errcode_ret) |
buffer
A valid object. Cannot be a sub-buffer object.
flags
A bit-field that is used to specify allocation and usage information about the image memory
object being created. The
following table describes the possible values for flags
:
cl_mem_flags | Description |
---|---|
CL_MEM_READ_WRITE
|
This flag specifies that the memory object will be read and written by a kernel. This is the default. |
CL_MEM_WRITE_ONLY
|
This flags specifies that the memory object will be written but not read by a kernel. Reading from a buffer or image object created with
|
CL_MEM_READ_ONLY
|
This flag specifies that the memory object is a read-only memory object when used inside a kernel. Writing to a buffer or image object created with
|
CL_MEM_USE_HOST_PTR
|
This flag is valid only if OpenCL implementations are allowed to cache the buffer
contents pointed to by The result of OpenCL commands that operate on multiple
buffer objects created with the same |
CL_MEM_ALLOC_HOST_PTR
|
This flag specifies that the application wants the OpenCL implementation to allocate memory from host accessible memory.
|
CL_MEM_COPY_HOST_PTR
|
This flag is valid only if
|
buffer_create_type
and buffer_create_info
The type of buffer object to be created. The supported value for buffer_create_type
is CL_BUFFER_CREATE_TYPE_REGION, which create a buffer object that represents a specific region in buffer
. buffer_create_info
is a pointer to the following structure:
typedefstruct_cl_buffer_region{
size_torigin;
size_tsize;
}cl_buffer_region;
(origin, size
) defines the offset and size in bytes in buffer
.
If buffer
is created with CL_MEM_USE_HOST_PTR, the host_ptr
associated with the buffer object returned is host_ptr
+ origin
.
The buffer object returned references the data store allocated for buffer
and points to a specific region given by (origin, size
) in this data store.
CL_INVALID_VALUE is returned in errcode_ret
if the region specified by (origin, size
) is out of bounds in buffer
.
CL_MISALIGNED_SUB_BUFFER_OFFSET is returned in errcode_ret
if there are no devices in context associated with buffer
for which the origin
value is aligned to the CL_DEVICE_MEM_BASE_ADDR_ALIGN value.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
The implementation may return the same cl_mem object with the reference count incremented
appropriately for multiple calls to clCreateSubBuffer
that use the same values for buffer
, flags
, buffer_create_type
and buffer_create_info
points to the same descriptor or descriptors that
describe values that are exactly the same.
The result of OpenCL commands that read from and write to multiple sub-buffer objects created
using clCreateSubBuffer
with the same buffer object but represent overlapping regions in the
buffer object is undefined. The result of OpenCL commands that read from and write to a buffer
object and its sub-buffer object(s) created using clCreateSubBuffer
with the same buffer object
is undefined. OpenCL commands that only read from multiple sub-buffer objects created using
clCreateSubBuffer
with the same buffer object but represent overlapping regions in the buffer
object or read from a buffer object and its sub-buffer objects should work as defined.
Returns a valid non-zero buffer object and errcode_ret
is set to CL_SUCCESS if
the buffer object is created successfully. Otherwise, it returns one of the following error in errcode_ret
:
buffer
is not a valid buffer object or is a sub-buffer object.
flags
are not valid; or if value specified in buffer_create_type
is not valid; or if value(s) specified in buffer_create_info
(for a given buffer_create_type
) is not valid or if buffer_create_info
is NULL.
public static cl_mem clCreateImage2D(cl_context context, long flags, cl_image_format[] image_format, long image_width, long image_height, long image_row_pitch, Pointer host_ptr, int[] errcode_ret)
Creates a 2D image object.
cl_mem clCreateImage2D
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
const cl_image_format*image_format, | |
size_timage_width, | |
size_timage_height, | |
size_timage_row_pitch, | |
void*host_ptr, | |
cl_int*errcode_ret) |
context
A valid OpenCL context on which the image object is to be created.
flags
A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table List of supported cl_mem_flags values for clCreateBuffer.
image_format
A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.
image_width
,
image_height
The width and height of the image in pixels. These must be values greater than or equal to 1.
image_row_pitch
The scan-line pitch in bytes. This must be 0 if host_ptr
is NULL and can be
either 0 or greater than or equal to image_width
* size of element in bytes
if host_ptr
is not NULL. If host_ptr
is not
NULL and image_row_pitch
is equal to 0, image_row_pitch
is calculated as image_width
* size of
element in bytes. If image_row_pitch
is not 0, it must be a multiple of the image element size in
bytes.
host_ptr
A pointer to the image data that may already be allocated by the application. The size
of the buffer that host_ptr
points to must be greater than or equal to image_row_pitch
* image_height
. The size of
each element in bytes must be a power of 2. The image data specified by host_ptr
is stored as a
linear sequence of adjacent scanlines. Each scanline is stored as a linear sequence of image elements.
errcode_ret
Will return an appropriate error code. If errcode_ret
is NULL, no error code is returned.
clCreateImage2D
returns a valid non-zero image object
and errcode_ret
is set to CL_SUCCESS
if the image object is created successfully. Otherwise, it returns a NULL value
with one of the following error values returned in errcode_ret
:
context
is not a valid context.
flags
are not valid.
image_format
are not valid or if image_format
is NULL.
image_width
or
image_height
are 0 or if they exceed values specified in
CL_DEVICE_IMAGE2D_MAX_WIDTH
or CL_DEVICE_IMAGE2D_MAX_HEIGHT
respectively for all devices in context
or if values specified by
image_row_pitch
do not follow rules
described in the argument description above.
host_ptr
is NULL and
CL_MEM_USE_HOST_PTR
or CL_MEM_COPY_HOST_PTR
are set in flags
or if host_ptr
is not NULL but
CL_MEM_COPY_HOST_PTR
or CL_MEM_USE_HOST_PTR
are not set in flags
.
image_format
is not supported.
context
that support images
(i.e. CL_DEVICE_IMAGE_SUPPORT
(specified in the table of OpenCL Device Queries for
clGetDeviceInfo) is CL_FALSE).
public static cl_mem clCreateImage3D(cl_context context, long flags, cl_image_format[] image_format, long image_width, long image_height, long image_depth, long image_row_pitch, long image_slice_pitch, Pointer host_ptr, int[] errcode_ret)
Creates a 3D image object.
cl_mem clCreateImage3D
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
const cl_image_format*image_format, | |
size_timage_width, | |
size_timage_height, | |
size_timage_depth, | |
size_timage_row_pitch, | |
size_timage_slice_pitch, | |
void*host_ptr, | |
cl_int*errcode_ret) |
context
A valid OpenCL context on which the image object is to be created.
flags
A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table List of supported cl_mem_flags values for clCreateBuffer.
image_format
A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.
image_width
,
image_height
The width and height of the image in pixels. These must be values greater than or equal to 1.
image depth
The depth of the image in pixels. This must be a value greater than 1.
image_row_pitch
The scan-line pitch in bytes. This must be 0 if host_ptr
is NULL and can be
either 0 or greater than or equal to image_width
* size of element in bytes
if host_ptr
is not NULL. If host_ptr
is not
NULL and image_row_pitch
is equal to 0, image_row_pitch
is calculated as image_width
* size of
element in bytes. If image_row_pitch
is not 0, it must be a multiple of the image element size in
bytes.
image_slice_pitch
The size in bytes of each 2D slice in the 3D image. This must be 0 if
host_ptr
is NULL and can be either 0 or greater than or equal to image_row_pitch
* image_height
if host_ptr
is not
NULL. If host_ptr
is not NULL and image_slice_pitch
equal to 0, image_slice_pitch
is calculated as
image_row_pitch
* image_height
. If image_slice_pitch
is not 0, it must be a multiple of the
image_row_pitch
.
host_ptr
A pointer to the image data that may already be allocated by the application. The size
of the buffer that host_ptr
points to must be greater than or equal to image_slice_pitch
* image_depth
. The size of
each element in bytes must be a power of 2. The image data specified by host_ptr
is stored as a
linear sequence of adjacent 2D slices. Each 2D slice is a linear sequence of adjacent scanlines.
Each scanline is a linear sequence of image elements.
errcode_ret
Will return an appropriate error code. If errcode_ret
is NULL, no error code is returned.
Returns a valid non-zero image object created and the errcode_ret
is set to
CL_SUCCESS if the image object is created successfully. Otherwise, it
returns a NULL value with one of the following error values returned in errcode_ret
:
context
is not a valid context.
flags
are not valid.
image_format
are
not valid or if image_format
is NULL.
image_width
, image_height
are 0 or if image_depth
less than or equal to 1
or if they exceed values specified in CL_DEVICE_IMAGE3D_MAX_WIDTH
,
CL_DEVICE_IMAGE3D_MAX_HEIGHT
or CL_DEVICE_IMAGE3D_MAX_DEPTH
respectively for all devices in context
or if values specified by image_row_pitch
and
image_slice_pitch
do not follow rules described in the argument description above.
host_ptr
is NULL and CL_MEM_USE_HOST_PTR
or CL_MEM_COPY_HOST_PTR
are set in flags
or if host_ptr
is not NULL but
CL_MEM_COPY_HOST_PTR
or CL_MEM_USE_HOST_PTR
are not set in flags
.
image_format
is not supported.
context
that support images (i.e.
CL_DEVICE_IMAGE_SUPPORT
(specified in the table of OpenCL Device Queries for clGetDeviceInfo) is CL_FALSE).
public static int clRetainMemObject(cl_mem memobj)
Increments the memory object reference count.
cl_int
clRetainMemObject
(
| cl_memmemobj) |
After the memobj
reference count becomes zero and
commands queued for execution on a command-queue(s) that use memobj
have finished, the
memory object is deleted.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
memobj
is a not a valid memory object (buffer or image object).
clCreateBuffer, clCreateSubBuffer, clCreateImage2D, and clCreateImage3D perform an implicit retain. clCreateSubBuffer also performs an implicit retain on the memory object used to create the sub-buffer or image object.
public static int clReleaseMemObject(cl_mem memobj)
Decrements the memory object reference count.
cl_int
clReleaseMemObject
(
| cl_memmemobj) |
After the memobj
reference count becomes zero and
commands queued for execution on a command-queue(s) that use memobj
have finished, the
memory object is deleted.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
memobj
is a not a valid memory object.
After the memobj
reference count becomes zero and commands queued for execution on a
command-queue(s) that use memobj
have finished, the memory object is deleted.
public static int clGetSupportedImageFormats(cl_context context, long flags, int image_type, int num_entries, cl_image_format[] image_formats, int[] num_image_formats)
Get the list of image formats supported by an OpenCL implementation.
cl_int
clGetSupportedImageFormats
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
cl_mem_object_typeimage_type, | |
cl_uintnum_entries, | |
cl_image_format*image_formats, | |
cl_uint*num_image_formats) |
context
A valid OpenCL context on which the image object(s) will be created.
flags
A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the List of supported cl_mem_flags values for clCreateBuffer
image_type
Describes the image type and must be either CL_MEM_OBJECT_IMAGE2D
or
CL_MEM_OBJECT_IMAGE3D
.
num_entries
Specifies the number of entries that can be returned in the memory location given by
image_formats
.
image_formats
A pointer to a memory location where the list of supported image formats are
returned. Each entry describes a cl_image_format structure supported
by the OpenCL implementation. If image_formats
is NULL, it is ignored.
num_image_formats
The actual number of supported image formats for a specific context
and
values specified by flags
. If num_image_formats
is NULL, it is ignored.
clGetSupportedImageFormats
can be used to get the list of image formats supported by an OpenCL
implementation when the following information about an image memory object is specified:
The minimum list of supported image formats is given by the table below:
image_num_channels |
image_channel_order |
image_channel_data_type |
---|---|---|
4 |
CL_RGBA |
CL_UNORM_INT8 |
4 |
CL_BGRA |
CL_UNORM_INT8 |
If CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_TRUE, the values assigned to the following constants by the implementation must be greater than or equal to the minimum values specified in the table of OpenCL Device Queries for clGetDeviceInfo: CL_DEVICE_MAX_READ_IMAGE_ARGS, CL_DEVICE_MAX_WRITE_IMAGE_ARGS, CL_DEVICE_IMAGE2D_MAX_WIDTH, CL_DEVICE_IMAGE2D_MAX_HEIGHT, CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT, CL_DEVICE_IMAGE3D_MAX_DEPTH, CL_DEVICE_MAX_SAMPLERS.
Returns CL_SUCCESS if the function is executed successfully.
Otherwise, it returns a NULL value
with one of the following error values returned in errcode_ret
:
context
is not a valid context.
flags
or image_type
are not valid, or
if num_entries
is 0 and image_formats
is not NULL.
public static int clGetMemObjectInfo(cl_mem memobj, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Used to get information that is common to all memory objects (buffer and image objects).
cl_int
clGetMemObjectInfo
(
| cl_memmemobj, |
cl_mem_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
memobj
Specifies the memory object being queried.
param_name
Specifies the information to query. The list of supported param_name
types and the
information returned in param_value
by clGetMemObjectInfo
is described
in the table below.
cl_mem_info | Return Type | Info. returned in param_value |
---|---|---|
CL_MEM_TYPE
|
cl_mem_object_type |
Returns one of the following values:
|
CL_MEM_FLAGS
|
cl_mem_flags |
Returns the flags argument value
specified when memobj is created with clCreateBuffer,
clCreateSubBuffer, clCreateImage2D, or clCreateImage3D.
|
CL_MEM_SIZE
|
size_t |
Return actual size of the data store associated with memobj in bytes.
|
CL_MEM_HOST_PTR
|
void * |
Return the host_ptr argument value specified when memobj is created.
|
CL_MEM_MAP_COUNT
|
cl_uint | Map count. The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging. |
CL_MEM_REFERENCE_COUNT
|
cl_uint |
Return memobj reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in
applications. This feature is provided for identifying memory leaks.
|
CL_MEM_CONTEXT
|
cl_context | Return context specified when memory object is created. |
CL_MEM_ASSOCIATED_MEMOBJECT
|
cl_mem |
Return memory object from which memobj is created.
This returns the memory object specified as Otherwise a NULL value is returned. |
CL_MEM_OFFSET
|
size_t |
Return offset if memobj is a sub-buffer object created using
clCreateSubBuffer.
This return 0 if |
CL_MEM_D3D10_RESOURCE_KHR
|
ID3D10Resource * |
The propery being queried (if the
cl_khr_d3d10_sharing
extension is enabled). If memobj was created using
clCreateFromD3D10BufferKHR,
clCreateFromD3D10Texture2DKHR,
or clCreateFromD3D10Texture3DKHR,
returns the resource argument specified
when memobj was created.
|
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Used to specify the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to size of return type as described in the table above.
param_value_size_ret
Returns the actual size in bytes of data being queried by param_value
. If param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
param_name
is not valid, or if size
in bytes specified by param_value_size
is less than the size of return type as
described in the table above and param_value
is not NULL.
param_name
is
CL_MEM_D3D10_RESOURCE_KHR and memobj
was not created by the function
clCreateFromD3D10BufferKHR,
clCreateFromD3D10Texture2DKHR, or
clCreateFromD3D10Texture3DKHR.
memobj
is a not a valid memory object.
public static int clGetImageInfo(cl_mem image, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Get information specific to an image object.
cl_int * clGetImageInfo
(
| cl_memimage, |
cl_image_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
image
Specifies the image object being queried.
param_name
Specifies the information to query. The list of supported param_name
types and the
information returned in param_value
by clGetImageInfo
is described in the table below.
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Used to specify the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to size of return type as described in the table below.
cl_image_info | Return Type | Info. returned in param_value |
---|---|---|
CL_IMAGE_FORMAT
|
cl_image_format |
Return image format descriptor specified when
image is created with clCreateImage2D or clCreateImage3D.
|
CL_IMAGE_ELEMENT_SIZE
|
size_t |
Return size of each element of the image
memory object given by image . An element is
made up of n channels. The value of n is given
in cl_image_format descriptor.
|
CL_IMAGE_ROW_PITCH
|
size_t |
Return size in bytes of a row of elements of the
image object given by image .
|
CL_IMAGE_SLICE_PITCH
|
size_t |
Return size in bytes of a 2D slice for the 3D
image object given by image . For a 2D image
object this value will be 0.
|
CL_IMAGE_WIDTH
|
size_t | Return width of image in pixels. |
CL_IMAGE_HEIGHT
|
size_t | Return height of image in pixels. |
CL_IMAGE_DEPTH
|
size_t | Return depth of the image in pixels. For a 2D image, depth equals 0. |
CL_IMAGE_D3D10_SUBRESOURCE_KHR
|
ID3D10Resource * |
The propery being queried (if the
cl_khr_d3d10_sharing
extension is enabled). If image was created using
clCreateFromD3D10Texture2DKHR or
clCreateFromD3D10Texture3DKHR,
returns the subresource argument
specified when image was created.
|
param_value_size_ret
the actual size in bytes of data being queried by param_value
. If param_value_size_ret
is NULL, it is ignored.
To get information that is common to all memory objects (buffer and image objects), use the clGetMemObjectInfo function.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
image
is a not a valid image object.
param_name
is not valid, or if
size in bytes specified by param_value_size
is less than the size of return
type as described in the table above and param_value
is not NULL.
param_name
is
CL_MEM_D3D10_SUBRESOURCE_KHR and image
was not created by the function
clCreateFromD3D10Texture2DKHR or
clCreateFromD3D10Texture3DKHR.
public static int clSetMemObjectDestructorCallback(cl_mem memobj, MemObjectDestructorCallbackFunction pfn_notify, java.lang.Object user_data)
Registers a user callback function that will be called when the memory object is deleted and its resources freed.
cl_int
clSetMemObjectDestructorCallback
(
| cl_memmemobj, |
void (CL_CALLBACK *pfn_notify) (cl_mem memobj, | |
void*user_data), | |
void*user_data) |
memobj
A valid memory object.
pfn_notify
The callback function that can be registered by the application. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are:
memobj
: the memory object being deleted.
user_data
: a pointer to user supplied data.
user_data
Data which will be passed as the user_data
argument when
pfn_notify
is called. user_data
can be NULL.
Each call to clSetMemObjectDestructorCallback
registers the specified user
callback function on a callback stack associated with memobj
. The registered user
callback functions are called in the reverse order in which they were registered. The user callback
functions are called and then the memory object's resources are freed and the memory object is
deleted. This provides a mechanism for the application (and libraries) using memobj
to be notified when the memory referenced by host_ptr
, specified when the memory object
is created and used as the storage bits for the memory object, can be reused or freed.
When the user callback function is called by the implementation, the contents of the
memory region pointed to by host_ptr
(if the memory object is created with
CL_MEM_USE_HOST_PTR) are undefined. The callback function is typically used by the application to
either free or reuse the memory region pointed to by host_ptr
.
The behavior of calling expensive system routines, OpenCL API calls to create contexts or command-queues, or blocking OpenCL operations from the following list below, in a callback is undefined.
If an application needs to wait for completion of a routine from the above list in a callback, please use the non-blocking form of the function, and assign a completion callback to it to do the remainder of your work. Note that when a callback (or other code) enqueues commands to a command-queue, the commands are not required to begin execution until the queue is flushed. In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a command queue should either call clFlush on the queue before returning or arrange for clFlush to be called later on another thread.
The user callback function may not call OpenCL APIs with the memory object for which the callback function is invoked and for such cases the behavior of OpenCL APIs is considered to be undefined.
Returns CL_SUCCESS if the command-queue properties are successfully updated. Otherwise, it returns the following:
memobj
is not a valid memory object.
pfn_notify
is NULL.
public static cl_sampler clCreateSampler(cl_context context, boolean normalized_coords, int addressing_mode, int filter_mode, int[] errcode_ret)
Creates a sampler object.
cl_sampler clCreateSampler
(
| cl_contextcontext, |
cl_boolnormalized_coords, | |
cl_addressing_modeaddressing_mode, | |
cl_filter_modefilter_mode, | |
cl_int*errcode_ret) |
context
Must be a valid OpenCL context.
normalized_coords
Determines if the image coordinates specified are normalized (if
normalized_coords
is CL_TRUE
) or not (if normalized_coords
is CL_FALSE
).
addressing_mode
Specifies how out-of-range image coordinates are handled when reading from
an image. This can be set to CL_ADDRESS_MIRRORED_REPEAT
, CL_ADDRESS_REPEAT
, CL_ADDRESS_CLAMP_TO_EDGE
, CL_ADDRESS_CLAMP
, and CL_ADDRESS_NONE
.
filtering_mode
Specifies the type of filter that must be applied when reading an image. This can be CL_FILTER_NEAREST
or CL_FILTER_LINEAR
.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
A sampler object describes how to sample an image when the image is read in the kernel. The built-in functions to read from an image in a kernel take a sampler as an argument. The sampler arguments to the image read function can be sampler objects created using OpenCL functions and passed as argument values to the kernel or can be samplers declared inside a kernel. In this section we discuss how sampler objects are created using OpenCL functions.
Returns a valid non-zero sampler object and errcode_ret
is set to CL_SUCCESS if the sampler object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret
:
context
is not a valid context.
addressing_mode
,
filter_mode
, or normalized_coords
or a combination of these argument values are not valid.
context
(i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
public static int clRetainSampler(cl_sampler sampler)
Increments the sampler reference count.
cl_int
clRetainSampler(
| cl_samplersampler) |
sampler
sampler
being retained.
clCreateSampler performs an implicit retain.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
sampler
is not a valid sampler object.
public static int clReleaseSampler(cl_sampler sampler)
Decrements the sampler reference count.
cl_int
clReleaseSampler
(
| cl_samplersampler) |
The sampler object is deleted after the reference count
becomes zero and commands queued for execution on a command-queue(s) that use
sampler
have finished.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
sampler
is not a valid sampler object.
public static int clGetSamplerInfo(cl_sampler sampler, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns information about the sampler object.
cl_int
clGetSamplerInfo
(
| cl_samplersampler, |
cl_sampler_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
sampler
Specifies the sampler being queried.
param_name
Specifies the information to query. The list of supported
param_name
types and the information returned in
param_value
by clGetSamplerInfo
is described in the table below.
param_value
A pointer to memory where the appropriate result being queried is
returned. If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by
param_value
. This size must be greater than or equal to size of
return type as described in the table below.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
.
If param_value_size_ret
is NULL, it is ignored.
cl_sampler_info | Return Type and Info. returned in param_value |
---|---|
CL_SAMPLER_REFERENCE_COUNT
|
Return type: cl_uint
Return the |
CL_SAMPLER_CONTEXT
|
Return type: cl_context
Return the context specified when the sampler is created. |
CL_SAMPLER_ADDRESSING_MODE
|
Return type: cl_addressing_mode
Return the addressing mode value associated with
|
CL_SAMPLER_FILTER_MODE
|
Return type: cl_filter_mode
Return the filter mode value associated with
|
CL_SAMPLER_NORMALIZED_COORDS
|
Return type: cl_bool
Return the normalized coords value associated with
|
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
param_name
is not valid, or if size
in bytes specified by param_value_size
is less than return type as described in
the table above and param_value
is not NULL
sampler
is a not a valid sampler object.
public static cl_program clCreateProgramWithSource(cl_context context, int count, java.lang.String[] strings, long[] lengths, int[] errcode_ret)
Creates a program object for a context, and loads the source code specified by the text strings in
the strings
array into the program object.
cl_program clCreateProgramWithSource
(
| cl_contextcontext, |
cl_uintcount, | |
const char**strings, | |
const size_t*lengths, | |
cl_int*errcode_ret) |
context
Must be a valid OpenCL context.
strings
An array of count
pointers to optionally null-terminated character strings that make up the source code.
lengths
An array with the number of chars in each string (the string length). If
an element in lengths
is zero, its accompanying string is null-terminated. If lengths
is NULL, all strings in the strings
argument are considered null-terminated. Any length value passed in that is greater than zero excludes the null terminator in its count.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
The devices associated with the program object are the devices associated with context
.
OpenCL allows applications to create a program object using the program source or binary and build appropriate program executables. This allows applications to determine whether they want to use the pre-built offline binary or load and compile the program source and use the executable compiled/linked online as the program executable. This can be very useful as it allows applications to load and build program executables online on its first instance for appropriate OpenCL devices in the system. These executables can now be queried and cached by the application. Future instances of the application launching will no longer need to compile and build the program executables. The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time.
An OpenCL program consists of a set of kernels that are identified as functions declared with the __kernel qualifier in the program source. OpenCL programs may also contain auxiliary functions and constant data that can be used by __kernel functions. The program executable can be generated online or offline by the OpenCL compiler for the appropriate target device(s).
clCreateProgramWithSource
returns a valid non-zero program object and errcode_ret
is set to
CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value
with one of the following error values returned in errcode_ret
:
context
is not a valid context.
count
is zero or if strings
or any entry in strings
is NULL.
public static cl_program clCreateProgramWithBinary(cl_context context, int num_devices, cl_device_id[] device_list, long[] lengths, byte[][] binaries, int[] binary_status, int[] errcode_ret)
Creates a program object for a context, and loads the binary bits specified by binary into the program object.
cl_program clCreateProgramWithBinary
(
| cl_contextcontext, |
cl_uintnum_devices, | |
const cl_device_id*device_list, | |
const size_t*lengths, | |
const unsigned char**binaries, | |
cl_int*binary_status, | |
cl_int*errcode_ret) |
context
Must be a valid OpenCL context.
device_list
A pointer to a list of devices that are in context
. device_list
must be a non-NULL
value. The binaries are loaded for devices specified in this list.
num_devices
The number of devices listed in device_list
.
The devices associated with the program object will be the list of devices specified by
device_list
. The list of devices specified by device_list
must be devices associated with context
.
lengths
An array of the size in bytes of the program binaries to be loaded for devices specified
by device_list
.
binaries
An array of pointers to program binaries to be loaded for devices specified by device_list
. For each device given by device_list
[i], the pointer to the program binary for that device is given by binaries
[i] and the length of this corresponding binary is given by lengths
[i]. lengths
[i] cannot be zero and binaries
[i] cannot be a NULL pointer.
The program binaries specified by binaries
contain the bits that describe the program executable that will be run on the device(s) associated with context
. The program binary can consist of either or both of device-specific executable(s), and/or implementation-specific intermediate representation (IR) which will be converted to the device-specific executable.
binary_status
Returns whether the program binary for each device specified in device_list
was loaded successfully or not. It is an array of num_devices
entries and
returns CL_SUCCESS in binary_status
[i] if binary
was successfully loaded for device specified by device_list
[i];
otherwise returns CL_INVALID_VALUE if lengths
[i]
is zero or if binaries
[i] is a NULL value or
CL_INVALID_BINARY in binary_status
[i] if program
binary is not a valid binary for the
specified device. If binary_status
is NULL, it is ignored.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is
returned.
OpenCL allows applications to create a program object using the program source or binary and build appropriate program executables. This allows applications to determine whether they want to use the pre-built offline binary or load and compile the program source and use the executable compiled/linked online as the program executable. This can be very useful as it allows applications to load and build program executables online on its first instance for appropriate OpenCL devices in the system. These executables can now be queried and cached by the application. Future instances of the application launching will no longer need to compile and build the program executables. The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time.
Returns a valid non-zero program object and errcode_ret
is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret
:
context
is not a valid context.
device_list
is NULL or num_devices
is zero; or if lengths
or binaries
are NULL or if any entry
in lengths
[i] or binaries
[i] is NULL.
device_list
are not
in the list of devices associated with context
.
binary_status
will return specific status for each device.
public static int clRetainProgram(cl_program program)
Increments the program
reference count.
cl_int
clRetainProgram
(
| cl_programprogram) |
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
program
is not a valid program object.
public static int clReleaseProgram(cl_program program)
Decrements the program
reference count.
cl_int clReleaseProgram
(
| cl_programprogram) |
The program object is deleted after all kernel objects
associated with program
have been deleted and the program
reference count becomes zero.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
program
is not a valid program object.
public static int clBuildProgram(cl_program program, int num_devices, cl_device_id[] device_list, java.lang.String options, BuildProgramFunction pfn_notify, java.lang.Object user_data)
Builds (compiles and links) a program executable from the program source or binary.
cl_int
clBuildProgram
(
| cl_programprogram, |
cl_uintnum_devices, | |
const cl_device_id*device_list, | |
const char*options, | |
void(CL_CALLBACK *pfn_notify)(cl_program program, void *user_data), | |
void*user_data) |
program
The program object
device_list
A pointer to a list of devices associated with program
. If device_list
is NULL value, the program executable is built for all devices associated with program
for which a source or binary has been loaded. If device_list
is a non-NULL value, the program executable is built for devices specified in this list for which a source or binary has been loaded.
num_devices
The number of devices listed in device_list
.
options
A pointer to a null-terminated string of characters that describes the build options to be used for building the program executable. The list of supported options is described in "Build Options" below.
pfn_notify
A function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully). If pfn_notify
is not NULL, clBuildProgram
does not need to wait for the build to complete and can return immediately. If pfn_notify
is NULL, clBuildProgram
does not return until the build has completed. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe.
user_data
Passed as an argument when pfn_notify
is called. user_data
can be NULL.
OpenCL allows program executables to be built using the source or the binary. clBuildProgram
must
be called for program
created using
either clCreateProgramWithSource
or clCreateProgramWithBinary to build the program executable
for one or more devices associated with program
.
The build options are categorized as pre-processor options, options for math intrinsics, options that control optimization and miscellaneous options. This specification defines a standard set of options that must be supported by an OpenCL compiler when building program executables online or offline. These may be extended by a set of vendor- or platform-specific options.
clBuildProgram
.
Predefine name
as a macro, with definition 1.
The contents of definition
are tokenized and processed as if they appeared during translation phase three in a `#define' directive. In particular, the definition will be truncated by embedded newline characters.
Add the directory dir
to the list of directories to be searched for header files.
Treat double precision floating-point constant as single precision constant.
This option controls how single precision and double precision denormalized numbers are handled. If specified as a build option, the single precision denormalized numbers may be flushed to zero; double precision denormalized numbers may also be flushed to zero if the optional extension for double precsion is supported. This is intended to be a performance hint and the OpenCL compiler can choose not to flush denorms to zero if the device supports single precision (or double precision) denormalized numbers.
This option is ignored for single precision numbers if the device does not support single precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_SINGLE_FP_CONFIG.
This option is ignored for double precision numbers if the device does not support double precision or if it does support double precison but CL_FP_DENORM bit is not set in CL_DEVICE_DOUBLE_FP_CONFIG.
This flag only applies for scalar and vector single precision floating-point variables and computations on these floating-point variables inside a program. It does not apply to reading from or writing to image objects.
This option disables all optimizations. The default is optimizations are enabled.
This option allows the compiler to assume the strictest aliasing rules.
The following options control compiler behavior regarding floating-point arithmetic. These options trade off between performance and correctness and must be specifically enabled. These options are not turned on by default since it can result in incorrect output for programs which depend on an exact implementation of IEEE 754 rules/specifications for math functions.
Allow a * b + c
to be replaced by a mad
. The mad
computes a * b + c
with reduced accuracy. For example, some OpenCL devices
implement mad
as truncate the result of a * b
before adding it to c
.
Allow optimizations for floating-point arithmetic that ignore the signedness of zero. IEEE 754 arithmetic
specifies the distinct behavior of +0.0
and -0.0
values, which then prohibits
simplification of expressions such as x+0.0
or 0.0*x
(even with -clfinite-math
only). This option implies that the sign of a zero result isn't significant.
Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid, (b) may violate IEEE 754 standard and (c) may violate the OpenCL numerical compliance requirements as defined in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5. This option includes the -cl-no-signed-zeros and -cl-mad-enable options.
Allow optimizations for floating-point arithmetic that assume that arguments and results are not NaNs or ∞. This option may violate the OpenCL numerical compliance requirements defined in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5.
Sets the optimization options -cl-finite-math-only and -cl-unsafe-math-optimizations.
This allows optimizations for floating-point arithmetic that may violate the IEEE 754
standard and the OpenCL numerical compliance requirements defined in the specification in
section 7.4 for single-precision floating-point, section 9.3.9 for double-precision
floating-point, and edge case behavior in section 7.5. This option causes the preprocessor
macro __FAST_RELAXED_MATH__
to be defined in the OpenCL program.
Inhibit all warning messages.
Make all warnings into errors.
Determine the OpenCL C language version to use. A value for this option must be provided. Valid values are:
CL1.1 - Support all OpenCL C programs that use the OpenCL C language features defined in section 6 of the OpenCL 1.1 specification.
Calls to clBuildProgram
with the -cl-std=CL1.1 option will fail
to build the program executable for any devices with CL_DEVICE_OPENCL_C_VERSION = OpenCL C 1.0.
If the -cl-std build option is not specified, the CL_DEVICE_OPENCL_C_VERSION is used to select the version of OpenCL C to be used when building the program executable for each device.
clBuildProgram
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
program
is not a valid program object.
device_list
is NULL
and num_devices
is greater than zero, or if device_list
is not NULL
and num_devices
is zero.
pfn_notify
is NULL
but user_data
is not NULL.
device_list
are not in the list of devices associated with program
.
program
is created
with clCreateWithProgramWithBinary and
devices listed in device_list
do not have a valid program binary loaded.
options
are invalid.
device_list
by a previous call to clBuildProgram
for program
has not
completed.
program
is created with
clCreateProgramWithSource
and a compiler is not available i.e.
CL_DEVICE_COMPILER_AVAILABLE specified in the table of OpenCL Device Queries
for clGetDeviceInfo is set
to CL_FALSE.
clBuildProgram
does not return until the build has
completed.
program
.
public static int clUnloadCompiler()
Allows the implementation to release the resources allocated by the OpenCL compiler.
cl_int
clUnloadCompiler
(
| void) |
This is a hint from the application and does not guarantee that the compiler will not be used in the future or that the compiler will actually be unloaded by the implementation. Calls to clBuildProgram after clUnloadCompiler
will reload the compiler, if necessary, to build the appropriate program executable.
This call currently always returns CL_SUCCESS.
public static int clGetProgramInfo(cl_program program, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns information about the program object.
cl_int
clGetProgramInfo
(
| cl_programprogram, |
cl_program_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
program
Specifies the program object being queried.
param_name
Specifies the information to query. The list of supported param_name
types and the information returned in param_value
by clGetProgramInfo
is described in the table below.
cl_program_info | Return Type and Info. returned in param_value |
---|---|
CL_PROGRAM_REFERENCE_COUNT
|
Return type: cl_uint
Return the The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
CL_PROGRAM_CONTEXT
|
Return type: cl_context
Return the context specified when the program object is created |
CL_PROGRAM_NUM_DEVICES
|
Return type: cl_uint
Return the number of devices associated with |
CL_PROGRAM_DEVICES
|
Return type: cl_device_id[]
Return the list of devices associated with the program object. This can be the devices associated with context on which the program object has been created or can be a subset of devices that are specified when a progam object is created using clCreateProgramWithBinary. |
CL_PROGRAM_SOURCE
|
Return type: char[]
Return the program source code specified by clCreateProgramWithSource. The source string returned is a concatenation of all source strings specified to clCreateProgramWithSource with a null terminator. The concatenation strips any nulls in the original source strings.
The actual number of characters that
represents the program source code
including the null terminator is returned
in |
CL_PROGRAM_BINARY_SIZES
|
Return type: size_t[]
Returns an array that contains the size
in bytes of the program binary for each
device associated with |
CL_PROGRAM_BINARIES
|
Return type: unsigned char *[]
Return the program binaries for all
devices associated with
Each entry in this array is used by the
implementation as the location in
memory where to copy the program
binary for a specific device, if there is a
binary available. To find out which
device the program binary in the array
refers to, use the
If an entry value in the array is NULL, the implementation skips copying the program binary for the specific device identified by the array index. |
param_value
A pointer to memory where the appropriate result being queried is returned.
If param_value
is NULL, it is ignored.
param_value_size
Used to specify the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to the size of return type as described in the table above.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
.
If param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
param_name
is not valid, or if size in
bytes specified by param_value_size
is less than the size of return type as described
in the table above and param_value
is not NULL.
program
is not a valid program object.
public static int clGetProgramBuildInfo(cl_program program, cl_device_id device, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns build information for each device in the program object.
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) |
program
Specifies the program object being queried.
device
Specifies the device for which build information is being queried.
device
must be a valid device associated with program
.
param_name
Specifies the information to query. The list of supported param_name
types and the
information returned in param_value
by clGetProgramBuildInfo
is
described in the table below.
cl_program_buid_info | Return Type and Info. returned in param_value |
---|---|
CL_PROGRAM_BUILD_STATUS
|
Return type: cl_build_status
Returns the build status of
CL_BUILD_NONE. The build status returned if no build has
been performed on the specified program object for
CL_BUILD_ERROR. The build status returned if the last call
to clBuildProgram on the specified program object for
CL_BUILD_SUCCESS. The build status returned if the last call
to clBuildProgram on the
specified program object for
CL_BUILD_IN_PROGRESS. The build status returned if the last call
to clBuildProgram on the
specified program object for |
CL_PROGRAM_BUILD_OPTIONS |
Return type: char[]
Return the build options specified by the
If build status of |
CL_PROGRAM_BUILD_LOG |
Return type: char[]
Return the build log when
clBuildProgram was called
for |
param_value
A pointer to memory where the appropriate result being queried is returned.
If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size
must be greater than or equal to the size of return type as described in the table above.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
.
If param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise it returns the following:
device
is not in the list of devices associated with program
.
param_name
is not valid, or if size in bytes specified by param_value_size
is less than size of return type
and param_value
is not NULL.
program
is a not a valid program object.
public static cl_kernel clCreateKernel(cl_program program, java.lang.String kernel_name, int[] errcode_ret)
Creates a kernal object.
cl_kernel clCreateKernel
(
| cl_program program, |
const char*kernel_name, | |
cl_int*errcode_ret) |
program
A program object with a successfully built executable.
kernel_name
A function name in the program declared with the __kernel
qualifier
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
A kernel is a function declared in a program. A kernel is identified by the __kernel qualifier applied to any function in a program. A kernel object encapsulates the specific __kernel
function declared in a program and the argument values to be used when executing this __kernel
function.
clCreateKernel
returns a valid non-zero kernel object and errcode_ret
is set to CL_SUCCESS if
the kernel object is created successfully. Otherwise, it returns a NULL value with one of the
following error values returned in errcode_ret
:
program
is not a valid program object.
program
.
kernel_name
is not found in program
.
__kernel
function
given by kernel_name
such as the number of arguments, the argument types are not the
same for all devices for which the program
executable has been built.
kernel_name
is NULL.
public static int clCreateKernelsInProgram(cl_program program, int num_kernels, cl_kernel[] kernels, int[] num_kernels_ret)
Creates kernel objects for all kernel functions in a program object.
cl_int
clCreateKernelsInProgram
(
| cl_program program, |
cl_uintnum_kernels, | |
cl_kernel*kernels, | |
cl_uint*num_kernels_ret) |
program
A program object with a successfully built executable.
num_kernels
The size of memory pointed to by kernels
specified as the number of cl_kernel entries.
kernels
The buffer where the kernel objects for kernels in program
will be returned. If kernels
is NULL, it is ignored. If kernels
is not NULL, num_kernels
must be greater than or equal to the number of kernels in program
.
num_kernels_ret
The number of kernels in program
. If num_kernels_ret
is NULL, it is ignored.
Creates kernel objects for all kernel functions in program
. Kernel objects are not created for any __kernel functions in program
that do not have the same function definition across all devices
for which a program executable has been successfully built.
Kernel objects can only be created once you have a program object with a valid program source
or binary loaded into the program object and the program executable has been successfully built
for one or more devices associated with program. No changes to the program executable are
allowed while there are kernel objects associated with a program object. This means that calls to
clBuildProgram return CL_INVALID_OPERATION if there are kernel objects attached to a
program object. The OpenCL context associated with program
will be the context associated
with kernel
. The list of devices associated with program
are the devices associated with kernel.
Devices associated with a program object for which a valid program executable has been built
can be used to execute kernels declared in the program object.
Returns CL_SUCCESS if the kernel objects are successfully allocated. Otherwise, it returns one of the following errors:
program
is not a valid program object.
program
.
kernels
is not NULL
and num_kernels
is less than the number of kernels in program
.
public static int clRetainKernel(cl_kernel kernel)
Increments the kernel object reference count.
cl_int
clRetainKernel
(
| cl_kernelkernel) |
clCreateKernel or clCreateKernelsInProgram do an implicit retain.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
kernel
is not a valid kernel object.
public static int clReleaseKernel(cl_kernel kernel)
Decrements the kernel reference count.
cl_int
clReleaseKernel
(
| cl_kernelkernel) |
The kernel object is deleted once the number of instances that are retained
to kernel
become zero and the kernel object is no longer needed by any
enqueued commands that use kernel
.
Returns CL_SUCCESS if the kernel objects are successfully alloctaed. Otherwise, it returns one of the following errors:
kernel
is not a valid kernel object.
public static int clSetKernelArg(cl_kernel kernel, int arg_index, long arg_size, Pointer arg_value)
Used to set the argument value for a specific argument of a kernel.
cl_int
clSetKernelArg
(
| cl_kernelkernel, |
cl_uintarg_index, | |
size_targ_size, | |
const void*arg_value) |
kernel
A valid kernel object.
arg_index
The argument index. Arguments to the kernel are referred by indices that go from 0 for the leftmost argument to n - 1, where n is the total number of arguments declared by a kernel.
arg_value
A pointer to data that should be used as the argument value for argument specified
by arg_index
. The argument data pointed to by arg_value
is copied and the arg_value
pointer can therefore be reused by the application after clSetKernelArg
returns. The argument value specified is the value used by all API calls that enqueue kernel
(clEnqueueNDRangeKernel and
clEnqueueTask) until the argument value is changed by a call to clSetKernelArg
for kernel
.
If the argument is a memory object (buffer or image), the arg_value
entry will be a
pointer to the appropriate buffer or image object. The memory object must be created with the context
associated with the kernel object. A NULL value can also be specified if the argument is a buffer
object in which case a NULL value will be used as the value for the argument declared as a
pointer to __global
or __constant
memory in the kernel. If the
argument is declared with the __local
qualifier, the arg_value
entry must be NULL. If the argument is of type sampler_t
, the arg_value
entry must be a pointer to the sampler object.
If the argument is declared to be a pointer of a built-in or user defined type with
the __global
or __constant
qualifier, the memory object specified as
argument value must be a buffer object (or NULL). If the argument is declared with the __constant
qualifier, the size in bytes of the memory object cannot exceed CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE and the
number of arguments declared with the __constant
qualifier cannot exceed
CL_DEVICE_MAX_CONSTANT_ARGS.
The memory object specified as argument value must be a 2D image object if the argument is
declared to be of type image2d_t
. The memory object specified as argument value must
be a 3D image object if argument is declared to be of type image3d_t
.
For all other kernel arguments, the arg_value
entry must be a pointer to the actual
data to be used as argument value.
arg_size
Specifies the size of the argument value. If the argument is a memory object, the size is
the size of the buffer or image object type. For arguments declared with the __local
qualifier, the size specified will be the size in bytes of the buffer that must be allocated
for the __local
argument. If the argument is of type sampler_t
,
the arg_size
value must be equal to sizeof(cl_sampler)
. For all other
arguments, the size will be the size of argument type.
A kernel object does not update the reference count for objects such as memory, sampler
objects specified as argument values by clSetKernelArg
. Users may not rely on a kernel object
to retain objects specified as argument values to the kernel.
Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no
mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership
rights on kernel args, that would make it impossible for the user to tell with certainty when he may safely release
user allocated resources associated with OpenCL objects such as the cl_mem backing store used with
CL_MEM_USE_HOST_PTR
.
An OpenCL API call is considered to be thread-safe if the internal state as managed by OpenCL remains consistent when called simultaneously by multiple host threads. OpenCL API calls that are thread-safe allow an application to call these functions in multiple host threads without having to implement mutual exclusion across these host threads i.e. they are also re-entrant-safe.
All OpenCL API calls are thread-safe except clSetKernelArg
, which is safe to call
from any host thread, and is safe to call re-entrantly so long as concurrent calls operate on
different cl_kernel objects. However, the behavior of the cl_kernel object is undefined if
clSetKernelArg
is called from multiple host threads on the same cl_kernel object at the same
time.
There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with clEnqueueNDRangeKernel or clEnqueueTask. Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. Rather than attempt to share cl_kernel objects among multiple host threads, applications are strongly encouraged to make additional cl_kernel objects for kernel functions for each host thread.
clSetKernelArg
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
kernel
is not a valid kernel object.
arg_index
is not a valid argument index.
arg_value
specified is NULL for an argument that is not
declared with the __local
qualifier or vice-versa.
arg_value
is not a valid memory object.
sampler_t
when
the specified arg_value
is not a valid sampler object.
arg_size
does not match the size of the
data type for an argument that is not a memory object or if the argument is a memory object
and arg_size
!= sizeof(cl_mem)
or if arg_size
is zero
and the argument is declared with the __local
qualifier or if the argument is a sampler and arg_size
!= sizeof(cl_sampler)
.
__kernel void image_filter (int n, int m, __constant float *filter_weights, __read_only image2d_t src_image, __write_only image2d_t dst_image) { ... } |
Argument index values for image_filter
will be 0 for n, 1 for m, 2 for
filter_weights
, 3 for src_image
and 4 for dst_image
.
public static int clGetKernelInfo(cl_kernel kernel, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns information about the kernel object.
cl_int
clGetKernelInfo
(
| cl_kernelkernel, |
cl_kernel_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
kernel
Specifies the kernel object being queried.
param_name
Specifies the information to query. The list of supported param_name
types and the
information returned in param_value
by clGetKernelInfo
is described in the table below.
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Used to specify the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to size of return type as described in the table below.
cl_kernel_info | Return Type | Info. returned in param_value |
---|---|---|
CL_KERNEL_FUNCTION_NAME
|
char[] | Return the kernel function name. |
CL_KERNEL_NUM_ARGS
|
cl_uint |
Return the number of arguments to kernel .
|
CL_KERNEL_REFERENCE_COUNT
|
cl_uint |
Return the The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks. |
CL_KERNEL_CONTEXT
|
cl_context |
Return the context associated with kernel .
|
CL_KERNEL_PROGRAM
|
cl_program |
Return the program object associated with kernel .
|
param_value_size_ret
the actual size in bytes of data copied to param_value
. If param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
param_name
is not valid, or if size
in bytes specified by param_value_size
is less than the size of return type as
described in the table above and param_value
is not NULL
kernel
is not a valid kernel object.
public static int clGetKernelWorkGroupInfo(cl_kernel kernel, cl_device_id device, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns information about the kernel object that may be specific to a device.
cl_int
clGetKernelWorkGroupInfo
(
| cl_kernelkernel, |
cl_device_iddevice, | |
cl_kernel_work_group_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
kernel
Specifies the kernel object being queried.
device
Identifies a specific device in the list of devices associated with kernel
. The list of devices
is the list of devices in the OpenCL context that is associated with kernel
. If the list of devices
associated with kernel
is a single device, device
can be a NULL value.
param_name
Specifies the information to query. The list of supported param_name
types and the
information returned in param_value
by clGetKernelWorkGroupInfo
is described in the table below.
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Used to specify the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to size of return type as described in the table below.
cl_kernel_work_group_info | Return Type | Info. returned in param_value |
---|---|---|
CL_KERNEL_WORK_GROUP_SIZE
|
size_t |
This provides a mechanism for the
application to query the maximum work-group size
that can be used to execute a kernel on a
specific device given by device . The
OpenCL implementation uses the
resource requirements of the kernel
(register usage etc.) to determine what
this work-group size should be.
|
CL_KERNEL_COMPILE_WORK_GROUP_SIZE
|
size_t[3] |
Returns the work-group size specified
by the __attribute__((reqd_work_gr
oup_size(X, Y, Z))) qualifier.
See Function Qualifiers.
If the work-group size is not specified
using the above attribute qualifier (0, 0,
0) is returned.
|
CL_KERNEL_LOCAL_MEM_SIZE
|
cl_ulong |
Returns the amount of local memory in bytes being used by a kernel. This includes local memory that may be needed by an implementation to execute the kernel, variables declared inside the kernel with the __local address qualifier and local memory to be allocated for arguments to the kernel declared as pointers with the __local address qualifier and whose size is specified with clSetKernelArg. If the local memory size, for any pointer argument to the kernel declared with the __local address qualifier, is not specified, its size is assumed to be 0. |
CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE
|
size_t | Returns the preferred multiple of workgroup size for launch. This is a performance hint. Specifying a workgroup size that is not a multiple of the value returned by this query as the value of the local work size argument to clEnqueueNDRangeKernelwill not fail to enqueue the kernel for execution unless the work-group size specified is larger than the device maximum. |
CL_KERNEL_PRIVATE_MEM_SIZE
|
cl_ulong | Returns the minimum amount of private memory, in bytes, used by each workitem in the kernel. This value may include any private memory needed by an implementation to execute the kernel, including that used by the language built-ins and variable declared inside the kernel with the __private qualifier. |
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
. If param_value_size_ret
is NULL, it is ignored.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
device
is not in the list of devices
associated with kernel
or if device
is NULL but there is more than
one device associated with kernel
.
param_name
is not valid, or if size in
bytes specified by param_value_size
is less than the size of return type as described in
the table above and param_value
is not NULL.
kernel
is a not a valid kernel object.
public static int clWaitForEvents(int num_events, cl_event[] event_list)
Waits on the host thread for commands identified by event objects to complete.
cl_int
clWaitForEvents
(
| cl_uintnum_events, |
const cl_event*event_list) |
event_list
The events specified in event_list
act as synchronization points.
Waits on the host thread for commands identified by event objects in event_list
to
complete. A command is considered complete if its execution status is CL_COMPLETE
or a negative value.
If the cl_khr_gl_event extension is enabled, event objects can also be used to reflect the status of an OpenGL sync object. The sync object in turn refers to a fence command executing in an OpenGL command stream. This provides another method of coordinating sharing of buffers and images between OpenGL and OpenCL.
Returns CL_SUCCESS if the execution status of all
events in event_list
is CL_COMPLETE.
Otherwise, it returns one of the following errors:
num_events
is zero or event_list
is NULL..
event_list
do
not belong to the same context.
event_list
are not valid event objects.
event_list
is a negative integer value.
public static int clGetEventInfo(cl_event event, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns information about the event object.
cl_int
clGetEventInfo
(
| cl_eventevent, |
cl_event_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
event
Specifies the event object being queried.
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
. This size must be greater than or equal to the size of the return type as described in the table below.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
. If
param_value_size_ret
is NULL, it is ignored.
param_name
Specifies the information to query. The list of supported param_name
types and the information returned in param_value
by clGetEventInfo
is described in the table below:
cl_event_info | Return Type | Information returned in param_value |
---|---|---|
CL_EVENT_COMMAND_QUEUE
|
cl_command_queue |
Return the command-queue associated with event .
For user event objects, a NULL value is returned.
|
CL_EVENT_CONTEXT
|
cl_context |
Return the context associated with event .
|
CL_EVENT_COMMAND_TYPE
|
cl_command_type |
Return the command associated with event .
Can be one of the following values:
CL_COMMAND_NDRANGE_KERNEL |
CL_EVENT_COMMAND_ EXECUTION_STATUS
|
cl_int |
Return the execution status of the command identified by event . The valid values are:
CL_QUEUED (command has been enqueued in the command-queue), CL_SUBMITTED (enqueued command has been submitted by the host to the device associated with the command-queue), CL_RUNNING (device is currently executing this command), CL_COMPLETE (the command has completed), or Error code given by a negative integer value. (command was abnormally terminated – this may be caused by a bad memory access etc.) These error codes come from the same set of error codes that are returned from the platform or runtime API calls as return values or The error code values are negative, and event state values are positive. The event state values are ordered from the largest value (CL_QUEUED) for the first or initial state to the smallest value (CL_COMPLETE or negative integer value) for the last or complete state. The value of CL_COMPLETE and CL_SUCCESS are the same. |
CL_EVENT_REFERENCE_COUNT
|
cl_uint |
Return the event reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
|
Using clGetEventInfo
to determine if a command identified by event has finished execution (i.e. CL_EVENT_COMMAND_EXECUTION_STATUS
returns CL_COMPLETE
) is not a synchronization point. There are no guarantees that the memory objects being modified by command associated with event
will be visible to other enqueued commands.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
param_name
is not valid, or if size in
bytes specified by param_value_size
is less than size of return type as described
in the table above and param_value
is not NULL.
param_name
cannot be queried for event.
event
is not a valid
event
object.
public static cl_event clCreateUserEvent(cl_context context, int[] errcode_ret)
Creates a user event object.
cl_event clCreateUserEvent
(
| cl_contextcontext, |
cl_int*errcode_ret) |
context
A valid OpenCL context used to create the user event object.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL,
no error code is returned.
User events allow applications to enqueue commands that wait on a user event to finish before the command is executed by the device.
The execution status of the user event object created is set to CL_SUBMITTED.
Returns a valid non-zero buffer object and errcode_ret
is set to CL_SUCCESS if
the user event object is created successfully. Otherwise, it returns a NULL value with one of the
following error values returned in errcode_ret
:
context
is not a valid context.
public static int clRetainEvent(cl_event event)
Increments the event
reference count.
cl_int
clRetainEvent
(
| cl_eventevent) |
event
Event object being retained.
The OpenCL commands that return an event perform an implicit retain.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
event
is not a valid event object.
public static int clReleaseEvent(cl_event event)
Decrements the event
reference count.
cl_int
clReleaseEvent
(
| cl_eventevent) |
event
Event object being released.
Decrements the event
reference count. The event object is deleted once the reference count becomes zero, the specific command identified by this event has completed (or terminated) and there are no commands in the command-queues of a context that require a wait for this event to complete.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
event
is not a valid event object.
public static int clSetUserEventStatus(cl_event event, int execution_status)
Sets the execution status of a user event object.
cl_mem clSetUserEventStatus
(
| cl_eventevent, |
cl_intexecution_status) |
event
A user event object created using clCreateUserEvent.
execution_status
Specifies the new execution status to be set and can be CL_COMPLETE or a negative integer value
to indicate an error. A negative integer value causes all enqueued commands that wait on this user event
to be terminated. clSetUserEventStatus
can only be called once to change the execution
status of event
.
Enqueued commands that specify user events in the event_wait_list
argument of
clEnqueue***
commands must ensure that the status of these user events being waited on are
set using clSetUserEventStatus
before any OpenCL APIs that release OpenCL objects except for
event objects are called; otherwise the behavior is undefined.
Returns CL_SUCCESS if the function was executed successfully. Otherwise, it returns one of the following errors
event
is not a valid user event.
execution_status
is not CL_COMPLETE
or a negative integer value.
execution_status
for
event
has already been changed by a previous call to
clSetUserEventStatus
.
For example, the following code sequence will result in undefined behavior of clReleaseMemObject.
ev1 = clCreateUserEvent(ctx, NULL); clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., 1, &ev1, NULL; clEnqueueWriteBuffer(cq, buf2, CL_FALSE,...); clReleaseMemObject(buf2); clSetUserEventStatus(ev1, CL_COMPLETE); |
The following code sequence, however, works correctly.
ev1 = clCreateUserEvent(ctx, NULL); clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., 1, &ev1, NULL; clEnqueueWriteBuffer(cq, buf2, CL_FALSE,...); clSetUserEventStatus(ev1, CL_COMPLETE); clReleaseMemObject(buf2); |
public static int clSetEventCallback(cl_event event, int command_exec_callback_type, EventCallbackFunction pfn_notify, java.lang.Object user_data)
Registers a user callback function for a specific command execution status.
cl_int clSetEventCallback
(
| cl_eventevent, |
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) |
event
A valid event object.
command_exec_callback_type
The command execution status for which the callback is registered. The command execution callback value for which a callback can be registered is CL_COMPLETE. There is no guarantee that the callback functions registered for various execution status values for an event will be called in the exact order that the execution status of a command changes.
The callback function registered for a command_exec_callback_type
value of
CL_COMPLETE will be called when the command has completed successfully or is abnormally terminated.
pfn_event_notify
The event callback function that can be registered by the application. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are:
event
: the event object for which the callback function is invoked.
event_command_exec_status
: the execution status of command for which
this callback function is invoked. See the table of values for
clGetEventInfoparam_value
for the command execution status values. If the callback
is
called as the result of the command associated with event being abnormally terminated, an
appropriate error code for the error that caused the termination will be passed to
event_command_exec_status
instead.
user_data
: a pointer to user supplied data.
user_data
Will be passed as the user_data
argument when pfn_notify
is called. user_data
can be NULL.
The registered callback function will be called when the execution status of command associated with
event
changes to the execution status specified by command_exec_status
.
Each call to clSetEventCallback
registers the specified user callback function on a
callback stack associated with event
. The order in which the registered user callback
functions are called is undefined.
All callbacks registered for an event object must be called. All enqueued callbacks shall be called before the event object is destroyed. Callbacks must return promptly. The behavior of calling expensive system routines, OpenCL API calls to create contexts or command-queues, or blocking OpenCL operations from the following list below, in a callback is undefined.
If an application needs to wait for completion of a routine from the above l ist in a callback, please use the non-blocking form of the function, and assign a completion callback to it to do the remainder of your work. Note that when a callback (or other code) enqueues commands to a command-queue, the commands are not required to begin execution until the queue is flushed. In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a command queue should either call clFlush on the queue before returning or arrange for clFlush to be called later on another thread.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
event
is not a valid event object.
pfn_event_notify
is NULL or if
command_exec_callback_type
is not CL_COMPLETE.
public static int clGetEventProfilingInfo(cl_event event, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns profiling information for the command associated with event if profiling is enabled.
cl_int
clGetEventProfilingInfo
(
| cl_eventevent, |
cl_profiling_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
event
Specifies the event object.
param_name
Specifies the profiling data to query. The list of supported param_name
types and the information returned in param_value
by clGetEventProfilingInfo
is described in the table of parameter queries below.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
.
This size must be greater than or equal to the size of return type as described in the table bolow.
param_value
A pointer to memory where the appropriate result being queried is returned. If
param_value
is NULL, it is ignored.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
. If
param_value_size_ret
is NULL, it is ignored.
The following is a table of clGetEventProfilingInfo
parameter queries
cl_profiling_info | Return Type | Info. returned in param_value |
---|---|---|
CL_PROFILING_COMMAND_QUEUED
|
cl_ulong |
A 64-bit value that describes the current
device time counter in nanoseconds when
the command identified by event is
enqueued in a command-queue by the
host.
|
CL_PROFILING_COMMAND_SUBMIT
|
cl_ulong |
A 64-bit value that describes the current
device time counter in nanoseconds when
the command identified by event that has
been enqueued is submitted by the host to
the device associated with the command-queue.
|
CL_PROFILING_COMMAND_START
|
cl_ulong |
A 64-bit value that describes the current
device time counter in nanoseconds when
the command identified by event starts
execution on the device.
|
CL_PROFILING_COMMAND_END
|
cl_ulong |
A 64-bit value that describes the current
device time counter in nanoseconds when
the command identified by event has
finished execution on the device.
|
The unsigned 64-bit values returned can be used to measure the time in nano-seconds consumed by OpenCL commands.
OpenCL devices are required to correctly track time across changes in device frequency and
power states. The CL_DEVICE_PROFILING_TIMER_RESOLUTION
specifies the resolution of
the timer i.e. the number of nanoseconds elapsed before the timer is incremented.
Event objects can be used to capture profiling information that measure execution time of a
command. Profiling of OpenCL commands can be enabled either by using a command-queue
created with CL_QUEUE_PROFILING_ENABLE flag set in properties
argument to
clCreateCommandQueue.
Returns CL_SUCCESS if the function is executed successfully and the profiling information has been recorded. Otherwise, it returns one of the following errors:
event
is not CL_COMPLETE or if event
is a user event
object.
param_name
is not valid, or if size in bytes
specified by param_value_size
is less than the size of return type as described in the above
table and param_value
is not NULL.
event
is a not a valid event object.
public static int clFlush(cl_command_queue command_queue)
Issues all previously queued OpenCL commands in a command-queue to the device associated with the command-queue.
cl_int
clFlush
(
| cl_command_queuecommand_queue) |
Issues all previously queued OpenCL commands in command_queue
to the device associated
with command_queue
.
clFlush
only guarantees that all queued commands to command_queue
get issued to the appropriate device. There is no guarantee that they will be complete after
clFlush
returns.
Any blocking commands queued in a command-queue perform an implicit flush of the command-queue.
These blocking commands are
clEnqueueReadBuffer,
clEnqueueReadBufferRect, or
clEnqueueReadImage with
blocking_read
set to CL_TRUE;
clEnqueueWriteBuffer,
clEnqueueWriteBufferRect, or
clEnqueueWriteImage with
blocking_write
set to CL_TRUE;
clEnqueueMapBuffer or
clEnqueueMapImage with
blocking_map
set to CL_TRUE;
or clWaitForEvents.
To use event objects that refer to commands enqueued in a command-queue as event objects to
wait on by commands enqueued in a different command-queue, the application must call a
clFlush
or any blocking commands that perform an implicit flush of the command-queue where
the commands that refer to these event objects are enqueued.
Returns CL_SUCCESS if the function call was executed successfully. Otherwise, it returns one of the following:
command_queue
is not a valid command-queue.
public static int clFinish(cl_command_queue command_queue)
Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed.
cl_int
clFinish
(
| cl_command_queuecommand_queue) |
Blocks until all previously queued OpenCL commands in command_queue
are issued to the
associated device and have completed.
clFinish
does not return until all queued commands in
command_queue
have been processed and completed. clFinish
is also a synchronization point.
Returns CL_SUCCESS if the function call was executed successfully. Otherwise, it returns one of the following:
command_queue
is not a valid command-queue.
public static int clEnqueueReadBuffer(cl_command_queue command_queue, cl_mem buffer, boolean blocking_read, long offset, long cb, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueue commands to read from a buffer object to host memory.
cl_int
clEnqueueReadBuffer
(
| cl_command_queuecommand_queue, |
cl_membuffer, | |
cl_boolblocking_read, | |
size_toffset, | |
size_tcb, | |
void*ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the read command will be
queued. command_queue
and buffer
must be created with the same OpenCL context.
buffer
Refers to a valid buffer object.
blocking_read
Indicates if the read operations are blocking
or non-blocking. If blocking_read
is CL_TRUE
i.e. the read command is blocking, clEnqueueReadBuffer
does not return until the buffer data has been read and copied into memory pointed to by ptr
.
If blocking_read
is CL_FALSE
i.e. the read command is non-blocking
, clEnqueueReadBuffer
queues a non-blocking
read command and returns. The contents of the buffer that ptr
points to
cannot be used until the read command has completed. The event
argument returns an event
object which can be used to query the execution status of the read command. When the read
command has completed, the contents of the buffer that ptr
points to can be used by the
application.
offset
The offset in bytes in the buffer object to read from.
cb
The size in bytes of data being read.
ptr
The pointer to buffer in host memory where data is to be read into.
event_wait_list
,
num_events_in_wait_list
event_wait_list
and num_events_in_wait_list
specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular read command and can be used
to query or queue a wait for this particular command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue a
wait for this command to complete.
Calling clEnqueueReadBuffer
to read a region of the buffer object with the ptr
argument value
set to host_ptr
+ offset
, where host_ptr
is a pointer to the memory region specified when the
buffer object being read is created with CL_MEM_USE_HOST_PTR
, must meet the following
requirements in order to avoid undefined behavior:
clEnqueueReadBuffer
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
and buffer
are not the same or if the context associated with command_queue
and events in
event_wait_list
are not the same.
buffer
is not a valid buffer object.
offset
, cb
) is out of bounds or if ptr
is a NULL value.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with
queue
.
event_wait_list
is a negative integer value.
buffer
.
java.lang.IllegalArgumentException
- If blocking_read==false
and
the given Pointer is not a Pointer to a direct buffer.public static int clEnqueueReadBufferRect(cl_command_queue command_queue, cl_mem buffer, boolean blocking_read, long[] buffer_offset, long[] host_offset, long[] region, long buffer_row_pitch, long buffer_slice_pitch, long host_row_pitch, long host_slice_pitch, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueue commands to read from a rectangular region from a buffer object to host memory.
cl_int
clEnqueueReadBufferRect
(
| cl_command_queuecommand_queue, |
cl_membuffer, | |
cl_boolblocking_read, | |
const size_tbuffer_origin[3], | |
const size_thost_origin[3], | |
const size_tregion[3], | |
size_tbuffer_row_pitch, | |
size_tbuffer_slice_pitch, | |
size_thost_row_pitch, | |
size_thost_slice_pitch, | |
void*ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the read command will be
queued. command_queue
and buffer
must be created with the same OpenCL context.
buffer
Refers to a valid buffer object.
blocking_read
Indicates if the read operations are blocking
or non-blocking. If blocking_read
is CL_TRUE
i.e. the read command is blocking, clEnqueueReadBufferRect
does not return until the buffer data has been read and copied into memory pointed to by ptr
.
If blocking_read
is CL_FALSE
i.e. the read command is non-blocking
, clEnqueueReadBufferRect
queues a non-blocking
read command and returns. The contents of the buffer that ptr
points to
cannot be used until the read command has completed. The event
argument argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr
points to can be used by the application.
buffer_origin
The (x, y, z) offset in the memory region associated with buffer
. For a 2D rectangle region, the z
value given by buffer_origin
[2] should be 0. The offset in bytes is computed as buffer_origin
[2] * buffer_slice_pitch
+ buffer_origin
[1] * buffer_row_pitch
+ buffer_origin
[0].
host_origin
The (x, y, z) offset in the memory region pointed to by ptr
. For a 2D rectangle region, the z
value given by host_origin
[2] should be 0. The offset in bytes is computed as host_origin
[2] * host_slice_pitch
+ host_origin
[1] * host_row_pitch
+ host_origin
[0].
region
The (width, height, depth) in bytes of the 2D or 3D rectangle being read or written. For a 2D rectangle copy, the depth
value given by region
[2] should be 1.
buffer_row_pitch
The length of each row in bytes to be used for the memory region associated with buffer
. If buffer_row_pitch
is 0, buffer_row_pitch
is computed as region
[0].
buffer_slice_pitch
The length of each 2D slice in bytes to be used for the memory region associated with buffer
. If buffer_slice_pitch
is 0, buffer_slice_pitch
is computed as region
[1] * buffer_row_pitch
.
host_row_pitch
The length of each row in bytes to be used for the memory region pointed to by ptr
. If host_row_pitch
is 0, host_row_pitch
is computed as region
[0].
host_slice_pitch
The length of each 2D slice in bytes to be used for the memory region pointed to by ptr
. If host_slice_pitch
is 0, host_slice_pitch
is computed as region
[1] * host_row_pitch
.
ptr
The pointer to buffer in host memory where data is to be read into.
event_wait_list
,
num_events_in_wait_list
event_wait_list
and num_events_in_wait_list
specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular read command and can be used
to query or queue a wait for this particular command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue a
wait for this command to complete.
Calling clEnqueueReadBufferRect
to read a region of the buffer object with the
ptr
argument value set to host_ptr
and host_origin
,
buffer_origin
values are the same, where host_ptr
is a pointer to the
memory region specified when the buffer object being read is created with CL_MEM_USE_HOST_PTR, must meet the
same requirements given for clEnqueueReadBuffer.
clEnqueueReadBufferRect
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
and buffer
are not the same or if the context associated with command_queue
and events in event_wait_list
are not the same.
buffer
is not a valid buffer object.
buffer_origin
, region
) is out of bounds.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
event_wait_list
is a negative integer value.
buffer
.
public static int clEnqueueWriteBuffer(cl_command_queue command_queue, cl_mem buffer, boolean blocking_write, long offset, long cb, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueue commands to write to a buffer object from host memory.
cl_int
clEnqueueWriteBuffer
(
| cl_command_queuecommand_queue, |
cl_membuffer, | |
cl_boolblocking_write, | |
size_toffset, | |
size_tcb, | |
const void*ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the write command will be
queued. command_queue
and buffer
must be created with the same OpenCL context.
buffer
Refers to a valid buffer object.
blocking_write
Indicates if the write operations are blocking
or nonblocking
.
If blocking_write
is CL_TRUE
, the OpenCL implementation copies the data referred to by ptr
and enqueues the write operation in the command-queue. The memory pointed to by ptr
can be
reused by the application after the clEnqueueWriteBuffer
call returns.
If blocking_write
is CL_FALSE
, the OpenCL implementation will use ptr
to perform a nonblocking
write. As the write is non-blocking the implementation can return immediately. The
memory pointed to by ptr
cannot be reused by the application after the call returns. The event
argument returns an event object which can be used to query the execution status of the write
command. When the write command has completed, the memory pointed to by ptr
can then be
reused by the application.
offset
The offset in bytes in the buffer object to write to.
cb
The size in bytes of data being written.
ptr
The pointer to buffer in host memory where data is to be written from.
event_wait_list
,
num_events_in_wait_list
event_wait_list
and num_events_in_wait_list
specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in
event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular write command and can be used
to query or queue a wait for this particular command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue a
wait for this command to complete.
Calling clEnqueueWriteBuffer
to update the latest bits in a region of the buffer object with
the ptr
argument value set to host_ptr
+ offset
, where host_ptr
is a pointer to the memory region specified when the buffer object being written is created with CL_MEM_USE_HOST_PTR
,
must meet the following requirements in order to avoid undefined behavior:
clEnqueueWriteBuffer
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
and buffer
are
not the same or if the context associated with command_queue
and events in
event_wait_list
are not the same.
buffer
is not a valid buffer object.
offset
,
cb
) is out of bounds or if ptr
is a NULL value.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL
and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated
with queue
.
event_wait_list
is a negative integer value.
buffer
.
public static int clEnqueueWriteBufferRect(cl_command_queue command_queue, cl_mem buffer, boolean blocking_read, long[] buffer_offset, long[] host_offset, long[] region, long buffer_row_pitch, long buffer_slice_pitch, long host_row_pitch, long host_slice_pitch, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueue commands to write a rectangular region to a buffer object from host memory.
cl_int
clEnqueueWriteBufferRect
(
| cl_command_queuecommand_queue, |
cl_membuffer, | |
cl_boolblocking_write, | |
const size_tbuffer_origin[3], | |
const size_thost_origin[3], | |
const size_tregion[3], | |
size_tbuffer_row_pitch, | |
size_tbuffer_slice_pitch, | |
size_thost_row_pitch, | |
size_thost_slice_pitch, | |
void*ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the write command will be
queued. command_queue
and buffer
must be created with the same OpenCL context.
buffer
Refers to a valid buffer object.
blocking_write
Indicates if the write operations are blocking
or non-blocking. If blocking_write
is CL_TRUE
, the OpenCL implementation copies the data referred to by ptr
and enqueues the write operation in the command-queue. The memory pointed to by ptr
can be
reused by the application after the clEnqueueWriteBufferRect
call returns.
If blocking_write
is CL_FALSE
, the OpenCL implementation will use ptr
to perform a nonblocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr
cannot be reused by the application after the call returns. The event
argument returns an event object which can be used to query the execution status of the write command. When the write command has completed, the memory pointed to by ptr
can then be
reused by the application.
buffer_origin
The (x, y, z) offset in the memory region associated with buffer
. For a 2D rectangle region, the z
value given by buffer_origin
[2] should be 0. The offset in bytes is computed as buffer_origin
[2] * buffer_slice_pitch
+ buffer_origin
[1] * buffer_row_pitch
+ buffer_origin
[0].
host_origin
The (x, y, z) offset in the memory region pointed to by ptr
. For a 2D rectangle region, the z
value given by host_origin
[2] should be 0. The offset in bytes is computed as host_origin
[2] * host_slice_pitch
+ host_origin
[1] * host_row_pitch
+ host_origin
[0].
region
The (width, height, depth) in bytes of the 2D or 3D rectangle being read or written. For a 2D rectangle copy, the depth
value given by region
[2] should be 1.
buffer_row_pitch
The length of each row in bytes to be used for the memory region associated with buffer
. If buffer_row_pitch
is 0, buffer_row_pitch
is computed as region
[0].
buffer_slice_pitch
The length of each 2D slice in bytes to be used for the memory region associated with buffer
. If buffer_slice_pitch
is 0, buffer_slice_pitch
is computed as region
[1] * buffer_row_pitch
.
host_row_pitch
The length of each row in bytes to be used for the memory region pointed to by ptr
. If host_row_pitch
is 0, host_row_pitch
is computed as region
[0].
host_slice_pitch
The length of each 2D slice in bytes to be used for the memory region pointed to by ptr
. If host_slice_pitch
is 0, host_slice_pitch
is computed as region
[1] * host_row_pitch
.
ptr
The pointer to buffer in host memory where data is to be written from.
event_wait_list
,
num_events_in_wait_list
event_wait_list
and num_events_in_wait_list
specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular write command
and can be used to query or queue a wait for this particular command to
complete. event
can be NULL in which
case it will not be possible for the application to query the status of
this command or queue a wait for this command to complete.
Calling clEnqueueWriteBufferRect
to update the latest bits in a region of the buffer object with the ptr
argument value set to host_ptr
and host_origin
, buffer_origin
values are the same, where host_ptr
is a pointer to the memory region specified when the buffer object being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:
buffer_origin region
) contains the latest bits when the enqueued write command begins execution.
clEnqueueWriteBufferRect
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
and buffer
are not the same or if the context associated with command_queue
and events in
event_wait_list
are not the same.
buffer
is not a valid buffer object.
buffer_origin
, region
) is out of bounds or if ptr
is a NULL value.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
event_wait_list
is a negative integer value.
buffer
.
public static int clEnqueueCopyBuffer(cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_buffer, long src_offset, long dst_offset, long cb, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to copy from one buffer object to another.
cl_int clEnqueueCopyBuffer
(
| cl_command_queuecommand_queue, |
cl_memsrc_buffer, | |
cl_memdst_buffer, | |
size_tsrc_offset, | |
size_tdst_offset, | |
size_tcb, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
The command-queue in which the copy command will be queued. The
OpenCL context associated with command_queue
, src_buffer
, and dst_buffer
must be the same.
src_offset
The offset where to begin copying data from src_buffer
.
dst_offset
The offset where to begin copying data into dst_buffer
.
cb
Refers to the size in bytes to copy.
event_wait_list,
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
, src_buffer
, and
dst_buffer
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
src_buffer
and dst_buffer
are not valid buffer objects.
src_offset
, dst_offset
, cb
, src_offset
+ cb
, or dst_offset
+ cb
require accessing elements outside the src_buffer
and dst_buffer
buffer objects
respectively.
event_wait_list
is NULL and
num_events_in_wait_list
is greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
src_buffer
and dst_buffer
are the same
buffer object and the source and destination regions overlap.
src_buffer
is a sub-buffer object
and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated with queue.
dst_buffer
is a sub-buffer object
and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated with queue.
src_buffer
or dst_buffer
.
public static int clEnqueueCopyBufferRect(cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_buffer, long[] src_origin, long[] dst_origin, long[] region, long src_row_pitch, long src_slice_pitch, long dst_row_pitch, long dst_slice_pitch, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to copy a rectangular region from the buffer object to another buffer object.
cl_int clEnqueueCopyBufferRect
(
| cl_command_queuecommand_queue, |
cl_memsrc_buffer, | |
cl_memdst_buffer, | |
const size_tsrc_origin[3], | |
const size_tdst_origin[3], | |
const size_tregion[3], | |
size_tsrc_row_pitch, | |
size_tsrc_slice_pitch, | |
size_tdst_row_pitch, | |
size_tdst_slice_pitch, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
The command-queue in which the copy command will be queued. The
OpenCL context associated with command_queue
, src_buffer
, and dst_buffer
must be the same.
src_origin
The (x, y, z) offset in the memory region associated with src_buffer
. For a 2D rectangle region, the z
value given by src_origin
[2] should be 0. The offset in bytes is computed as src_origin
[2] * src_slice_pitch
+ src_origin
[1] * src_row_pitch
+ src_origin
[0].
dst_origin
The (x, y, z) offset in the memory region associated with dst_buffer
. For a 2D rectangle region, the z
value given by dst_origin
[2] should be 0. The offset in bytes is computed as dst_origin
[2] * dst_slice_pitch
+ dst_origin
[1] * dst_row_pitch
+ dst_origin
[0].
region
The (width, height, depth) in bytes of the 2D or 3D rectangle being copied. For a
2D rectangle, the depth
value given by region
[2] should be 1.
src_row_pitch
The length of each row in bytes to be used for the memory region associated with src_buffer
. If src_row_pitch
is 0, src_row_pitch
is computed as region
[0].
src_slice_pitch
The length of each 2D slice in bytes to be used for the memory region associated with src_buffer
. If src_slice_pitch
is 0, src_slice_pitch
is computed as region
[1] * src_row_pitch
.
dst_row_pitch
The length of each row in bytes to be used for the memory region associated with dst_buffer
. If dst_row_pitch
is 0, dst_row_pitch
is computed as region
[0].
dst_slice_pitch
The length of each 2D slice in bytes to be used for the memory region associated with dst_buffer
. If dst_slice_pitch
is 0, dst_slice_pitch
is computed as region
[1] * dst_row_pitch
.
event_wait_list,
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
, src_buffer
, and
dst_buffer
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
src_buffer
and dst_buffer
are not valid buffer objects.
src_offset
, region
) or (dst_offset
, region
) require accessing elements outside the src_buffer
and dst_buffer
objects respectively.
event_wait_list
is NULL and
num_events_in_wait_list
is greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
src_buffer
and dst_buffer
are the same buffer object and the source and destination regions overlap.
src_buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
dst_buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
src_buffer
or dst_buffer
.
public static int clEnqueueReadImage(cl_command_queue command_queue, cl_mem image, boolean blocking_read, long[] origin, long[] region, long row_pitch, long slice_pitch, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to read from a 2D or 3D image object to host memory.
cl_int
clEnqueueReadImage
(
| cl_command_queuecommand_queue, |
cl_memimage, | |
cl_boolblocking_read, | |
const size_torigin[3], | |
const size_tregion[3], | |
size_trow_pitch, | |
size_tslice_pitch, | |
void*ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the read command will be
queued. command_queue
and image
must be created with the same OpenCL context.
image
Refers to a valid 2D or 3D image object.
blocking_read
Indicates if the read operations are blocking
or non-blocking
.
If blocking_read
is CL_TRUE
i.e. the read command is blocking, clEnqueueReadImage
does not return until the
buffer data has been read and copied into memory pointed to by ptr
.
If blocking_read
is CL_FALSE
i.e. map operation is non-blocking, clEnqueueReadImage
queues a non-blocking read command and returns. The contents of the buffer that ptr
points to cannot be used until the read command has completed. The event
argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr
points to can be used by the application.
origin
Defines the (x, y, z) offset in pixels in the image from where to read. If image
is a 2D image object, the z value given by origin
[2] must be 0.
region
Defines the (width
, height
, depth
) in pixels of the 2D or 3D rectangle being read. If image
is a 2D image object, the depth
value given by region
[2] must be 1.
row_pitch
The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width
. If row_pitch
is set to 0, the appropriate row pitch is calculated
based on the size of each element in bytes multiplied by width
.
slice_pitch
Size in bytes of the 2D slice of the 3D region of a 3D image being read. This must be 0 if image
is a 2D image. This value must be greater than or equal to row_pitch
* height
. If slice_pitch
is set to 0, the appropriate slice pitch is calculated based on the row_pitch
* height
.
ptr
The pointer to a buffer in host memory where image data is to be read from.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular read command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
Calling clEnqueueReadImage
to read a region of the image
with the ptr
argument value set to host_ptr
+ (origin
[2] * image slice pitch
+ origin
[1] * image row pitch
+ origin
[0] *
bytes per pixel
), where host_ptr
is a pointer to the memory region specified when the image
being read is created with CL_MEM_USE_HOST_PTR
, must meet the following requirements in order to avoid undefined behavior:
row_pitch
and slice_pitch
argument values in clEnqueueReadImage
must be set to
the image row pitch and slice pitch.
clEnqueueReadImage
returns CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors.
command_queue
is not a valid command-queue.
command_queue
and
image
are not the same or if the context associated with
command_queue
and events in event_wait_list
are not the same.
image
is
not a valid image object.
origin
and region
is out of bounds or if
ptr
is a NULL value.
image
is a
2D image object and origin
[2]
is not equal to 0 or region
[2] is not equal to 1 or
slice_pitch
is not equal to 0.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in
event_wait_list
are not valid events.
image
are not
supported by device associated with queue
.
event_wait_list
is a negative integer value.
command_queue
does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT
specified in the table of OpenCL Device Queries
for clGetDeviceInfo is CL_FALSE).
image
.
public static int clEnqueueWriteImage(cl_command_queue command_queue, cl_mem image, boolean blocking_write, long[] origin, long[] region, long input_row_pitch, long input_slice_pitch, Pointer ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to write to a 2D or 3D image object from host memory.
cl_int
clEnqueueWriteImage
(
| cl_command_queuecommand_queue, |
cl_memimage, | |
cl_boolblocking_write, | |
const size_torigin[3], | |
const size_tregion[3], | |
size_tinput_row_pitch, | |
size_tinput_slice_pitch, | |
const void* ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the write command will be
queued. command_queue
and image
must be created with the same OpenCL context.
image
Refers to a valid 2D or 3D image object.
blocking_write
Indicates if the write operation is blocking
or non-blocking
.
If blocking_write
is CL_TRUE
the OpenCL implementation copies the data referred to by ptr
and enqueues the write command in the command-queue. The memory pointed to by ptr
can be reused by the application after the clEnqueueWriteImage
call returns.
If blocking_write
is CL_FALSE
the OpenCL implementation will use ptr
to perform a nonblocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr
cannot be reused by the application after the call returns. The event
argument returns an event object which can be used to query the execution status of the write
command. When the write command has completed, the memory pointed to by ptr
can then be reused by the application.
origin
Defines the (x, y, z) offset in pixels in the image from where to write. If image
is a 2D image object, the z value given by origin
[2] must be 0.
region
Defines the (width
, height
, depth
) in pixels of the 2D or 3D rectangle being written. If image
is a 2D image object, the depth
value given by region
[2] must be 1.
input_row_pitch
The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width
. If input_row_pitch
is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width
.
input_slice_pitch
Size in bytes of the 2D slice of the 3D region of a 3D image being written. This must be 0 if image
is a 2D image. This value must be greater than or equal to row_pitch
* height
. If input_slice_pitch
is set to 0, the appropriate slice pitch is calculated based on the row_pitch
* height
.
ptr
The pointer to a buffer in host memory where image data is to be written to.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular write command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue a
wait for this command to complete.
Calling clEnqueueWriteImage
to update the latest bits in a region of the image
with the
ptr
argument value set to host_ptr
+ (origin
[2] * image slice pitch
+ origin
[1] * image row pitch
+ origin
[0] * bytes per pixel
), where host_ptr
is a pointer to the memory region specified when
the image
being written is created with CL_MEM_USE_HOST_PTR
, must meet the following requirements in order to avoid undefined behavior:
input_row_pitch
and input_slice_pitch
argument values in clEnqueueWriteImage
must be set to the image row pitch and slice pitch.
clEnqueueWriteImage
return CL_SUCCESS if the function is
executed successfully. Otherwise, it returns one of the following errors.
command_queue
is not a valid command-queue.
command_queue
and image
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
image
is not a valid image object.
origin
and region
is out of bounds or if ptr
is a NULL value.
image
is a 2D image object and origin
[2] is not equal to 0 or
region
[2] is not equal to 1 or slice_pitch
is not equal to 0.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
image
are not supported by device associated with queue
.
command_queue
does not
support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries
for clGetDeviceInfo is CL_FALSE).
event_wait_list
is a negative integer value.
image
.
public static int clEnqueueCopyImage(cl_command_queue command_queue, cl_mem src_image, cl_mem dst_image, long[] src_origin, long[] dst_origin, long[] region, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to copy image objects.
cl_int
clEnqueueCopyImage
(
| cl_command_queuecommand_queue, |
cl_memsrc_image, | |
cl_memdst_image, | |
const size_tsrc_origin[3], | |
const size_tdst_origin[3], | |
const size_tregion[3], | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Refers to the command-queue in which the copy command will be queued. The
OpenCL context associated with command_queue
, src_image
and dst_image
must be the same.
src_origin
Defines the starting (x, y, z) location in pixels in src_image
from where to start the data copy. If src_image
is a 2D image object, the z value given by src_origin
[2] must be 0.
dst_origin
Defines the starting (x, y, z) location in pixels in dst_image
from where to start the data copy. If dst_image
is a 2D image object, the z value given by dst_origin
[2] must be 0.
region
Defines the (width
, height
, depth
) in pixels of the 2D or 3D rectangle to copy. If src_image
or dst_image
is a 2D image object, the depth
value given by region
[2] must be 1.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.
It is currently a requirement that the src_image
and dst_image
image memory objects for clEnqueueCopyImage
must have the exact same image format (i.e. the cl_image_format descriptor specified when src_image
and dst_image
are created must match).
src_image
and dst_image
can be 2D or 3D image objects
allowing us to perform the following actions:
clEnqueueCopyImage
returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
, src_image
and dst_image
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
src_image
and dst_image
are not valid image objects.
src_image
and dst_image
do not use the same
image format.
src_origin
and src_origin
+ region
refers to a region outside src_image
,
or if the 2D or 3D rectangular region specified by dst_origin
and dst_origin
+ region
refers to a region outside dst_image
.
src_image
is a 2D image object and src_origin
[2]
is not equal to 0 or region
[2] is not equal to 1.
dst_image
is a 2D image object and dst_origin
[2]
is not equal to 0 or region
[2] is not equal to 1.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL
and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
src_image
are not supported by device associated with queue
.
dst_image
are not supported by device associated with queue
.
src_image
or dst_image
.
command_queue
does not support images
(i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries
for clGetDeviceInfo is CL_FALSE).
src_image
and dst_image
are the
same image object and the source and destination regions overlap.
public static int clEnqueueCopyImageToBuffer(cl_command_queue command_queue, cl_mem src_image, cl_mem dst_buffer, long[] src_origin, long[] region, long dst_offset, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to copy an image object to a buffer object.
cl_int
clEnqueueCopyImageToBuffer
(
| cl_command_queuecommand_queue, |
cl_memsrc_image, | |
cl_mem dst_buffer, | |
const size_tsrc_origin[3], | |
const size_tregion[3], | |
size_tdst_offset, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Must be a valid command-queue. The OpenCL context associated with command_queue
, src_image
, and dst_buffer
must be the same.
src_image
A valid image object.
dst_buffer
A valid buffer object.
src_origin
Defines the (x, y, z) offset in pixels in the image from where to copy. If src_image
is a 2D image object, the z value given by src_origin
[2] must be 0.
region
Defines the (width
, height
, depth
) in pixels of the 2D or 3D rectangle to copy. If src_image
is a 2D image object, the depth
value given by region
[2] must be 1.
dst_offset
The offset where to begin copying data into dst_buffer
. The size in bytes of the region to be copied referred to as dst_cb
is computed as width
* height
* depth
* bytes
/image element
if src_image
is a 3D image object and is computed as width
* height
* bytes
/image element
if src_image
is a 2D image object.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.
clEnqueueCopyImageToBuffer
returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
, src_image
and dst_buffer
are not the same or if the context associated with command_queue
and events in event_wait_list
are not the same.
src_image
is not a valid image object and dst_buffer
is not a valid buffer object.
src_origin
and src_origin
+ region
refers to a region outside src_image
, or if the region specified by dst_offset
and dst_offset
+ dst_cb
refers to a region outside dst_buffer
.
src_image
is a 2D image object and src_origin
[2] is not equal to 0 or region
[2] is not equal to 1.
event_wait_list
is NULL and num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
dst_buffer
is a sub-buffer object
and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated with queue
.
src_image
are not supported by device associated with queue
.
command_queue
does not support images
(i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries
for clGetDeviceInfo is CL_FALSE).
src_image
or dst_buffer
.
public static int clEnqueueCopyBufferToImage(cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_image, long src_offset, long[] dst_origin, long[] region, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to copy a buffer object to an image object.
cl_int
clEnqueueCopyBufferToImage
(
| cl_command_queuecommand_queue, |
cl_memsrc_buffer, | |
cl_mem dst_image, | |
size_tsrc_offset, | |
const size_tdst_origin[3], | |
const size_tregion[3], | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue. The OpenCL context associated with
command_queue
, src_buffer
, and dst_image
must be the same.
src_buffer
A valid buffer object.
dst_image
A valid image object.
src_offset
The offset where to begin copying data from src_buffer
.
dst_origin
The (x, y, z) offset in pixels where to begin copying data to dst_image
. If dst_image
is a 2D image object, the z value given by dst_origin
[2] must be 0.
region
Defines the (width
, height
, depth
) in pixels of the 2D or 3D rectangle to copy. If dst_image
is a 2D image object, the depth
value given by region
[2] must be 1.
The size in bytes of the region to be copied from src_buffer
referred to as src_cb
is computed as width
* height
* depth
* bytes
/image element
if dst_image
is a 3D image object and is computed as width
* height
* bytes
/image element
if dst_image
is a 2D image object.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to
query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.
clEnqueueCopyBufferToImage
returns CL_SUCCESS if the function is executed successfully.
Otherwise, it returns one of the following errors:
command_queue
is not a valid command-queue.
command_queue
, src_buffer
and
dst_image
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
src_buffer
is not a valid buffer object and dst_image
is not a valid image object.
dst_origin
and
dst_origin
+ region
refers to a region outside dst_origin
, or if the region specified
by src_offset
and src_offset
+ src_cb
refers to a region outside
src_buffer
.
dst_image
is a 2D image object and dst_origin
[2] is not equal to 0
or region
[2] is not equal to 1.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
src_buffer
is a sub-buffer object and offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with
queue
.
dst_image
are not supported by device associated with queue
.
command_queue
does not support images
(i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries
for clGetDeviceInfo is CL_FALSE).
src_buffer
or dst_image
.
public static java.nio.ByteBuffer clEnqueueMapBuffer(cl_command_queue command_queue, cl_mem buffer, boolean blocking_map, long map_flags, long offset, long cb, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event, int[] errcode_ret)
Enqueues a command to map a region of the buffer object given by buffer
into the host address space and returns a pointer to this mapped region.
void * clEnqueueMapBuffer
(
| cl_command_queuecommand_queue, |
cl_membuffer, | |
cl_boolblocking_map, | |
cl_map_flagsmap_flags, | |
size_toffset, | |
size_tcb, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event, | |
cl_int*errcode_ret) |
command_queue
Must be a valid command-queue.
blocking_map
Indicates if the map operation is blocking
or non-blocking
.
If blocking_map
is CL_TRUE
, clEnqueueMapBuffer
does not return until the specified region in buffer
can be mapped.
If blocking_map
is CL_FALSE
i.e. map operation is non-blocking, the pointer to the mapped region returned by clEnqueueMapBuffer
cannot be used until the map command has completed. The event
argument returns an event object which can be used to query the execution status of the map command. When the map command is completed, the application can access the contents of the mapped region using the pointer returned by clEnqueueMapBuffer
.
map_flags
Is a bit-field and can be set to CL_MAP_READ
to indicate that the region specified by (offset
, cb
) in the buffer object is being mapped for reading, and/or CL_MAP_WRITE
to indicate that the region specified by (offset
, cb
) in the buffer object is being mapped for writing.
buffer
A valid buffer object. The OpenCL context associated with command_queue
and buffer
must be the same.
offset,
cb
The offset in bytes and the size of the region in the buffer object that is being mapped.
event_wait_list,
num_events_in_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in
event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
If the buffer object is created with CL_MEM_USE_HOST_PTR
set in mem_flags
, the host_ptr
specified in clCreateBuffer is guaranteed to contain the latest bits in the region being mapped when the clEnqueueMapBuffer
command has completed; and the pointer value returned by clEnqueueMapBuffer
will be derived from the host_ptr
specified when the buffer object is created.
Mapped buffer objects are unmapped using clEnqueueUnmapMemObject.
The contents of the regions of a memory object mapped for writing (i.e. CL_MAP_WRITE
is set in map_flags
argument to clEnqueueMapBuffer
or clEnqueueMapImage) are considered to be undefined until this region is unmapped. Reads and writes by a kernel executing on a device to a memory region(s) mapped for writing are undefined.
Multiple command-queues can map a region or overlapping regions of a memory object for
reading (i.e. map_flags
= CL_MAP_READ
). The contents of the regions of a memory object mapped for reading can also be read by kernels executing on a device(s). The behavior of writes by a kernel executing on a device to a mapped region of a memory object is undefined. Mapping (and unmapping) overlapped regions of a buffer or image memory object for writing is undefined.
The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.
The pointer returned maps a region starting at offset
and is at least cb
bytes in size. The result of a memory access outside this region is undefined.
clEnqueueMapBuffer
will return a pointer to the mapped region if the function is executed successfully. The errcode_ret
is set to CL_SUCCESS.
A NULL pointer is returned otherwise with one of the following error values returned in errcode_ret
:
command_queue
is not a valid command-queue.
command_queue
and buffer
are not the
same or if the context associated with
command_queue
and events
in event_wait_list
are not the same.
buffer
is not a valid buffer object.
offset
, cb
) is out of bounds or if
values specified in map_flags
are not valid
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
event_wait_list
is a negative integer value.
buffer
is a sub-buffer object and
offset
specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN
value for device associated with queue
.
CL_MEM_USE_HOST_PTR
or CL_MEM_ALLOC_HOST_PTR
.
buffer
.
public static java.nio.ByteBuffer clEnqueueMapImage(cl_command_queue command_queue, cl_mem image, boolean blocking_map, long map_flags, long[] origin, long[] region, long[] image_row_pitch, long[] image_slice_pitch, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event, int[] errcode_ret)
Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.
void * clEnqueueMapImage
(
| cl_command_queuecommand_queue, |
cl_memimage, | |
cl_boolblocking_map, | |
cl_map_flagsmap_flags, | |
const size_torigin[3], | |
const size_tregion[3], | |
size_t*image_row_pitch, | |
size_t*image_slice_pitch, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event, | |
cl_int*errcode_ret) |
command_queue
Must be a valid command-queue.
image
A valid image object. The OpenCL context associated with command_queue
and image
must be the same.
blocking_map
Indicates if the map operation is blocking
or non-blocking
. If blocking_map
is CL_TRUE
, clEnqueueMapImage
does not return until the specified region in image
can be mapped.
If blocking_map
is CL_FALSE
i.e. map operation is non-blocking, the pointer to the mapped region returned by clEnqueueMapImage
cannot be used until the map command has completed. The event
argument returns an event object which can be used to query the execution status of the map command. When the map command is completed, the application can access the contents of the mapped region using the pointer returned by clEnqueueMapImage
.
map_flags
Is a bit-field and can be set to CL_MAP_READ
to indicate that the region specified by (origin
, region
) in the image object is being mapped for reading, and/or CL_MAP_WRITE
to indicate that the region specified by (origin
, region
) in the image object is being mapped for writing.
origin,
region
Define the (x, y, z) offset in pixels and (width
, height
, depth
) in pixels of the 2D or 3D rectangle region that is to be mapped. If image
is a 2D image object, the z value given by origin
[2] must be 0 and the depth
value given by region
[2] must be 1.
image_row_pitch
Returns the scan-line pitch in bytes for the mapped region. This must be a non-NULL value.
image_slice_pitch
Returns the size in bytes of each 2D slice for the mapped region. For a 2D image, zero is returned if this argument is not NULL. For a 3D image, image_slice_pitch
must be a non-NULL value.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before clEnqueueMapImage
can be executed. If event_wait_list
is NULL, then clEnqueueMapImage
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event
can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL, no error code is returned.
If the image object is created with CL_MEM_USE_HOST_PTR
set in mem_flags
, the
following will be true:
host_ptr
specified in clCreateImage2d
or clCreateImage3d is guaranteed to contain the latest bits
in the region being mapped when the clEnqueueMapImage
command has completed.
clEnqueueMapImage
will be derived from
the host_ptr
specified when the image object is created.
Mapped image objects are unmapped using clEnqueueUnmapMemObject.
The contents of the regions of a memory object mapped for writing (i.e. CL_MAP_WRITE
is set
in map_flags
argument to clEnqueueMapBuffer or clEnqueueMapImage
) are considered to be
undefined until this region is unmapped. Reads and writes by a kernel executing on a device to a
memory region(s) mapped for writing are undefined.
Multiple command-queues can map a region or overlapping regions of a memory object for
reading (i.e. map_flags
= CL_MAP_READ
). The contents of the regions of a memory object
mapped for reading can also be read by kernels executing on a device(s). The behavior of writes
by a kernel executing on a device to a mapped region of a memory object is undefined.
Mapping (and unmapping) overlapped regions of a memory object for writing is
undefined.
The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.
The pointer returned maps a 2D or 3D region starting at origin
and is at least (image_row_pitch
* region
[1]) pixels in size for a 2D image, and is at least (image_slice_pitch
* region
[2]) pixels in size for a 3D image. The result of a memory access outside this region is undefined.
clEnqueueMapImage
will return a pointer to the mapped region if the function is executed successfully.
The errcode_ret
is set to CL_SUCCESS.
A NULL pointer is returned otherwise with one of the following error values returned in
errcode_ret
:
command_queue
is not a valid command-queue.
command_queue
and image
are not the same or if the context associated with command_queue
and events
in event_wait_list
are not the same.
image
is not a valid image object.
origin
, origin
+region
) is out of bounds or if
values specified in map_flags
are not valid.
image
is a 2D image object and origin
[2] is not equal to 0 or
region
[2] is not equal to 1.
image_row_pitch
is NULL.
image
is a 3D image object and image_slice_pitch
is NULL.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
image
are not supported by device associated with queue
.
CL_MEM_USE_HOST_PTR
or CL_MEM_ALLOC_HOST_PTR
.
buffer
.
event_wait_list
is a negative integer value.
command_queue
does not support
images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries
for clGetDeviceInfo.
public static int clEnqueueUnmapMemObject(cl_command_queue command_queue, cl_mem memobj, java.nio.ByteBuffer mapped_ptr, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to unmap a previously mapped region of a memory object.
cl_int clEnqueueUnmapMemObject
(
| cl_command_queuecommand_queue, |
cl_memmemobj, | |
void*mapped_ptr, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
Must be a valid command-queue.
memobj
A valid memory object. The OpenCL context associated with command_queue
and memobj
must be the same.
mapped_ptr
The host address returned by a previous call to clEnqueueMapBuffer or
clEnqueueMapImage for memobj
.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before clEnqueueUnmapMemObject
can be executed. If event_wait_list
is NULL, then clEnqueueUnmapMemObject
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue a
wait for this command to complete. clEnqueueBarrier can be used instead.
Reads or writes from the host using the pointer returned by clEnqueueMapBuffer or clEnqueueMapImage are considered to be complete.
clEnqueueMapBuffer and clEnqueueMapImage increment the mapped count of the memory
object. The initial mapped count value of a memory object is zero. Multiple calls to
clEnqueueMapBuffer or clEnqueueMapImage on the same memory object will increment this
mapped count by appropriate number of calls. clEnqueueUnmapMemObject
decrements the
mapped count of the memory object.
clEnqueueMapBuffer and clEnqueueMapImage act as synchronization points for a region of the buffer object being mapped.
clEnqueueUnmapMemObject
returns CL_SUCCESS if the function is executed successfully.
Otherwise, it returns one of the following errors:.
command_queue
is not a valid command-queue.
memobj
is not a valid memory object.
mapped_ptr
is not a valid pointer returned by
clEnqueueMapBuffer or
clEnqueueMapImage for memobj
.
event_wait_list
is NULL and
num_events_in_wait_list
greater than 0, or event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in event_wait_list
are
not valid events.
command_queue
and memobj
are not the same or if the context associated with command_queue
and events in event_wait_list
are not the same.
public static int clEnqueueNDRangeKernel(cl_command_queue command_queue, cl_kernel kernel, int work_dim, long[] global_work_offset, long[] global_work_size, long[] local_work_size, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to execute a kernel on a device.
cl_int
clEnqueueNDRangeKernel
(
| cl_command_queuecommand_queue, |
cl_kernelkernel, | |
cl_uintwork_dim, | |
const size_t*global_work_offset, | |
const size_t*global_work_size, | |
const size_t*local_work_size, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue. The kernel will be queued for execution on the device associated with command_queue
.
kernel
A valid kernel object. The OpenCL context associated with kernel
and command_queue
must be the same.
work_dim
The number of dimensions used to specify the global work-items and work-items
in the work-group. work_dim
must be greater than zero and less than or
equal to CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS.
global_work_offset
global_work_offset
can be used to specify an array
of work_dim
unsigned values that describe the offset used to calculate
the global ID of a work-item. If global_work_offset
is NULL,
the global IDs start at offset (0, 0, ... 0).
global_work_size
Points to an array of work_dim
unsigned values that describe the number of global work-items in work_dim
dimensions that will execute the kernel function. The total number of global work-items is computed as global_work_size
[0] *...* global_work_size
[work_dim
- 1].
The values specified in global_work_size
+ corresponding values specified in global_work_offset
cannot exceed the range given by the sizeof(size_t)
for the device on which the kernel execution will be enqueued. The sizeof(size_t)
for a device can be determined using CL_DEVICE_ADDRESS_BITS
in the table of OpenCL Device Queries for clGetDeviceInfo. If, for example, CL_DEVICE_ADDRESS_BITS
= 32, i.e. the device uses a 32-bit address space, size_t is a 32-bit unsigned integer and global_work_size
values must be in the range 1 .. 2^32 - 1. Values outside this range return a CL_OUT_OF_RESOURCES
error.
local_work_size
Points to an array of work_dim
unsigned values that describe the number of work-items that make up a work-group (also referred to as the size of the work-group) that will execute the kernel specified by kernel
. The total number of work-items in a work-group is computed as local_work_size
[0] *... * local_work_size
[work_dim
- 1]. The total number of work-items in the work-group must be less than or equal to the
CL_DEVICE_MAX_WORK_GROUP_SIZE
value specified in table of OpenCL Device Queries for clGetDeviceInfo and the number of work-items specified in local_work_size
[0],... local_work_size
[work_dim
- 1] must be less than or
equal to the corresponding values specified by CL_DEVICE_MAX_WORK_ITEM_SIZES
[0],....
CL_DEVICE_MAX_WORK_ITEM_SIZES
[work_dim
- 1]. The explicitly specified local_work_size
will be used to determine how to break the global work-items specified by global_work_size
into appropriate work-group instances. If local_work_size
is specified, the values specified in global_work_size
[0],... global_work_size
[work_dim
- 1] must be evenly divisible by the corresponding values specified in local_work_size
[0],... local_work_size
[work_dim
- 1].
The work-group size to be used for kernel
can also be specified in the program source using the __attribute__((reqd_work_group_size(X, Y, Z)))
qualifier. In this case the size of work group specified by local_work_size
must match the value specified by the reqd_work_group_size
__attribute__ qualifier.
local_work_size
can also be a NULL value in which case the OpenCL implementation will determine how to be break the global work-items into appropriate work-group instances.
See note for more information.
These work-group instances are executed in parallel across multiple compute units or concurrently on the same compute unit.
Each work-item is uniquely identified by a global identifier. The global ID, which can be read inside the kernel, is computed using the value given by global_work_size
and global_work_offset
. In addition, a work-item is also identified within a work-group by a unique local ID. The local ID, which can also be read by the kernel, is computed using the value given by local_work_size
. The starting local ID is always (0, 0, ... 0).
event_wait_list
and
num_events_in_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event
is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.
Returns CL_SUCCESS if the kernel execution was successfully queued. Otherwise, it returns one of the following errors:
command_queue
.
command_queue
is not a
valid command-queue.
kernel
is not a valid kernel object.
command_queue
and kernel
is not the same or if the context associated
with command_queue
and events in event_wait_list
are not the same.
work_dim
is not a valid value
(i.e. a value between 1 and 3).
global_work_size
is NULL, or
if any of the values specified in global_work_size
[0], ...global_work_size
[work_dim
- 1] are 0 or exceed the range given by the sizeof(size_t)
for the
device on which the kernel execution will be enqueued.
global_work_size
+ the corresponding values in global_work_offset
for any dimensions is greater
than the sizeof(size_t)
for the device on which the kernel execution will be enqueued.
local_work_size
is
specified and number of work-items specified by global_work_size
is not evenly
divisable by size of work-group given by local_work_size
or does not match the
work-group size specified for kernel
using
the
__attribute__
((reqd_work_group_size(X, Y, Z))) qualifier in program source.
local_work_size
is specified and the total number of work-items in the work-group computed as local_work_size
[0] *... local_work_size
[work_dim
- 1] is greater than the value specified by CL_DEVICE_MAX_WORK_GROUP_SIZE in the table of OpenCL Device Queries for clGetDeviceInfo.
local_work_size
is NULL and the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier is used to declare the work-group size for kernel
in the program source.
local_work_size
[0], ... local_work_size
[work_dim
- 1] is greater than the corresponding values specified by CL_DEVICE_MAX_WORK_ITEM_SIZES[0], ....
CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim
- 1].
offset
specified when the sub-buffer object
is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
queue
.
kernel
on the command-queue because of insufficient resources needed to execute the kernel.
For example, the explicitly specified local_work_size
causes a failure to execute the kernel
because of insufficient resources such as registers or local memory. Another example would be the number of
read-only image args used in kernel
exceed the CL_DEVICE_MAX_READ_IMAGE_ARGS
value for device or the number of write-only image args used in kernel
exceed
the CL_DEVICE_MAX_WRITE_IMAGE_ARGS value for device or the number of samplers used
in kernel
exceed CL_DEVICE_MAX_SAMPLERS for device.
kernel
.
event_wait_list
is NULL
and num_events_in_wait_list
> 0, or event_wait_list
is not NULL
and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
public static int clEnqueueTask(cl_command_queue command_queue, cl_kernel kernel, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to execute a kernel on a device.
cl_int
clEnqueueTask
(
| cl_command_queuecommand_queue, |
cl_kernelkernel, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue. The kernel will be queued for execution on the
device associated with command_queue
.
kernel
A valid kernel object. The OpenCL context associated with kernel
and command_queue
must be the same.
num_events_in_wait_list
and event_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue must be the same.
event
Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event
is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.
The kernel is executed using a single work-item.
clEnqueueTask
is equivalent to calling clEnqueueNDRangeKernel with work_dim
= 1,
global_work_offset
= NULL, global_work_size
[0] set to 1, and local_work_size
[0] set to 1.
Returns CL_SUCCESS if the kernel execution was successfully queued, or one of the errors below:
command_queue
.
command_queue
is not a valid command-queue.
kernel
is not a valid kernel object.
command_queue
and kernel
is not the same or if the context associated with command_queue
and events in event_wait_list
are not the same.
kernel
using the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier in program source and is not (1, 1, 1).
offset
specified when the sub-buffer object
is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue
.
queue
.
kernel
on the command-queue because of insufficient resources needed to execute the kernel.
kernel
.
event_wait_list
is NULL
and num_events_in_wait_list
is greater than 0, or event_wait_list
is not
NULL and num_events_in_wait_list
is 0, or if event objects in event_wait_list
are not valid events.
public static int clEnqueueNativeKernel(cl_command_queue command_queue, EnqueueNativeKernelFunction user_func, java.lang.Object args, long cb_args, int num_mem_objects, cl_mem[] mem_list, Pointer[] args_mem_loc, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler.
cl_int
clEnqueueNativeKernel
(
| cl_command_queuecommand_queue, |
void(*user_func)(void *), | |
void*args, | |
size_tcb_args, | |
cl_uintnum_mem_objects, | |
const cl_mem*mem_list, | |
const void**args_mem_loc, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue. A native user function can only be executed on a command-queue created on a device that has CL_EXEC_NATIVE_KERNEL capability set in CL_DEVICE_EXECUTION_CAPABILITIES as specified in the table of OpenCL Device Queries for clGetDeviceInfo.
user_func
A pointer to a host-callable user function.
args
A pointer to the args list that user_func
should be called with.
cb_args
The size in bytes of the args list that args
points to.
The data pointed to by args
and cb_args
bytes in size will be copied and a pointer to this copied region will be passed to user_func
. The copy needs to be done because the memory objects (cl_mem
values) that args
may contain need to be modified and replaced by appropriate pointers to global memory. When clEnqueueNativeKernel
returns, the memory region pointed to by args
can be reused by the application.
num_mem_objects
The number of buffer objects that are passed in args
.
mem_list
A list of valid buffer objects, if num_mem_objects
is greater than 0. The buffer object values
specified in mem_list
are memory object handles (cl_mem
values) returned by clCreateBuffer or NULL.
args_mem_loc
A pointer to appropriate locations that args
points to where memory object handles (cl_mem
values) are stored. Before the user function is executed, the memory object handles are replaced by pointers to global memory.
event_wait_list
and
num_events_in_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command does not wait on any event to complete. If event_wait_list
is NULL, num_events_in_wait_list
must be 0. If event_wait_list
is not NULL, the list of events pointed to by event_wait_list
must be valid and num_events_in_wait_list
must be greater than 0. The events specified in
event_wait_list
act as synchronization points. The context associated with events in event_wait_list
and command_queue
must be the same.
event
Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event
is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.
The data pointed to by args
and cb_args
bytes in size will be copied and a pointer to this copied region will be passed to user_func
. The copy needs to be done because the memory objects
(cl_mem
values) that args
may contain need to be modified and replaced by appropriate pointers to global memory. When clEnqueueNativeKernel
returns, the memory region pointed to by args
can be reused by the application.
Returns CL_SUCCESS if the user function execution instance was successfully queued, or one of the errors below:
command_queue
is not a valid command-queue.
command_queue
and events in event-wait_list
are not the same.
user_func
is NULL.
args
is a NULL value and
cb_args
is greater than 0, or if args
is a NULL
value and num_mem_objects
is greater than 0.
args
is not NULL and
cb_args
is 0.
num_mem_objects
is greater than 0
and mem_list
or args_mem_loc
are NULL.
num_mem_objects
= 0 and
mem_list
or args_mem_loc
are not NULL.
command_queue
cannot execute the native kernel.
mem_list
are not valid or are not buffer objects.
kernel
on the command-queue because of insufficient resources
needed to execute the kernel.
kernel
.
event_wait_list
is NULL
and num_events_in_wait_list
is greater than 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects
in event_wait_list
are not valid events.
public static int clEnqueueMarker(cl_command_queue command_queue, cl_event event)
Enqueues a marker command.
cl_int
clEnqueueMarker
(
| cl_command_queuecommand_queue, |
cl_event*event) |
Enqueues a marker command to command_queue
. The marker command is not completed until
all commands enqueued before it have completed. The marker command returns an event
which
can be waited on, i.e. this event can be waited on to ensure that all commands which have been queued before the market command have been completed.
complete.
Returns CL_SUCCESS if the function executed successfully, or one of the errors below:
command_queue
is not a valid command-queue.
event
is a NULL value.
public static int clEnqueueWaitForEvents(cl_command_queue command_queue, int num_events, cl_event[] event_list)
Enqueues a wait for a specific event or a list of events to complete before any future commands queued in the command-queue are executed.
cl_int
clEnqueueWaitForEvents
(
| cl_command_queuecommand_queue, |
cl_uintnum_events, | |
const cl_event*event_list) |
command_queue
A valid command-queue.
num_events
Specifies the number of events given by event_list
.
event_list
Events specified in event_list
act as synchronization points. The context associated
with events in event_list
and command_queue
must be the same.
Each event in event_list
must be a valid event object returned by a previous call
to the following:
The context associated with events in event_list
and
command_queue
must be the same.
Returns CL_SUCCESS if the function was successfully executed, or one of the errors below:
command_queue
is not a valid command-queue.
command_queue
and events in event_list
are not the same.
num_events
is zero or
event_list
is NULL.
event_list
are not valid events.
public static int clEnqueueBarrier(cl_command_queue command_queue)
A synchronization point that enqueues a barrier operation.
cl_int
clEnqueueBarrier
(
| cl_command_queuecommand_queue) |
clEnqueueBarrier
is a synchronization point that ensures that all
queued commands in command_queue
have finished execution before the next
batch of commands can begin execution.
Returns CL_SUCCESS if the function was successfully executed, or one of the errors below:
command_queue
is not a valid command-queue.
public static cl_mem clCreateFromGLBuffer(cl_context context, long flags, int bufobj, int[] errcode_ret)
Creates an OpenCL buffer object from an OpenGL buffer object.
cl_mem
clCreateFromGLBuffer
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
GLuintbufobj, | |
cl_int* errcode_ret) |
context
A valid OpenCL context created from an OpenGL context.
flags
A bit-field that is used to specify usage information.
Refer to the table for
clCreateBuffer
for a description of flags
. Only
CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in the table at clCreateBuffer
can be used.
bufobj
The name of a GL buffer object. The data store of the GL buffer object must have have been previously created by calling OpenGL function glBufferData
, although its contents need not be initialized. The size of the data store will be used to determine the size of the CL buffer object.
errcode_ret
Returns an appropriate error code as described below. If errcode_ret
is NULL, no error code is returned.
The size of the GL buffer object data store at the time clCreateFromGLBuffer
is called will be used as the size of buffer object returned by clCreateFromGLBuffer
. If the state of a GL buffer object is modified through the GL API (e.g. glBufferData
) while there exists a corresponding CL buffer object, subsequent use of the CL buffer object will result in undefined behavior.
The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the buffer object.
Returns a valid non-zero OpenCL buffer object and errcode_ret
is set
to CL_SUCCESS if the buffer object is created successfully. Otherwise, it returns a NULL value
with one of the following error values returned in errcode_ret
:
context
is not a valid context or was
not created from a GL context.
flags
are not valid.
bufobj
is not a GL buffer object or is a
GL buffer object but does not have an existing data store.
public static cl_mem clCreateFromGLTexture2D(cl_context context, long flags, int target, int miplevel, int texture, int[] errcode_ret)
Creates an OpenCL 2D image object from an OpenGL 2D texture object, or a single face of an OpenGL cubemap texture object.
cl_mem
clCreateFromGLTexture2D
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
GLenumtexture_target, | |
GLintmiplevel, | |
GLuinttexture, | |
cl_int*errcode_ret) |
context
A valid OpenCL context created from an OpenGL context.
flags
A bit-field that is used to specify usage information. Refer to
the table for
clCreateBuffer
for a description of flags
. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE
values specified in the table for clCreateBuffer
may be used.
texture_target
Must be one of GL_TEXTURE_2D, GL_TEXTURE_CUBE_MAP_POSITIVE_X,
GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z,
GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y,
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, or GL_TEXTURE_RECTANGLE. texture_target
is
used only to define the image type of texture
. No reference to a bound GL
texture object is made or implied by this parameter.
Using GL_TEXTURE_RECTANGLE for texture_target requires OpenGL 3.1. Alternatively, GL_TEXTURE_RECTANGLE_ARB may be specified if the OpenGL extension GL_ARB_texture_rectangle is supported.
miplevel
The mipmap level to be used. Implementations may return CL_INVALID_OPERATION for miplevel values greater than 0.
texture
The name of a GL 2D, cubemap or rectangle texture object. The
texture object must be a complete texture as per OpenGL rules on
texture completeness. The texture
format and
dimensions defined by OpenGL for the specified miplevel
of the texture will be used to create the 2D image object. Only GL texture
objects with an internal format that maps to appropriate image channel order
and data type specified in the table of supported Image Channel Order
Values and the table of supported Image Channel Data Types for
cl_image_format
may be used to create a 2D image object.
errcode_ret
Returns an appropriate error code as described below.
If errcode_ret
is NULL, no error code is returned.
Returns a valid non-zero OpenCL image object and errcode_ret
is
set to CL_SUCCESS if the image object is
created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret
:
context
is not a valid context or was not created from a GL context.
flags
are not valid or if value specified in
texture_target
is not one of the values specified
in the description of texture_target
.
miplevel
is less
than the value of levelbase
(for OpenGL
implementations) or zero (for OpenGL ES implementations); or greater than the value of
q
(for both OpenGL and OpenGL ES).
levelbase
and q
are defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 specification and section 3.7.10 of the OpenGL ES 2.0 specification.
miplevel
is greater than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.
texture
is not a GL texture object whose type matches
texture_target
, if the specified miplevel
of
texture
is not defined,
or if the width or height
of the specified miplevel
is zero.
texture
is a GL texture object created with a border width value greater than zero.
public static cl_mem clCreateFromGLTexture3D(cl_context context, long flags, int target, int miplevel, int texture, int[] errcode_ret)
Creates an OpenCL 3D image object from an OpenGL 3D texture object.
cl_mem
clCreateFromGLTexture3D
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
GLenumtexture_target, | |
GLintmiplevel, | |
GLuinttexture, | |
cl_int* errcode_ret) |
context
A valid OpenCL context created from an OpenGL 3D context.
flags
A bit-field that is used to specify usage information. Refer to
the table for
clCreateBuffer
for a description of flags
. Only the valuesCL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE can be used.
texture_target
texture_target
is used only to define the image
type of texture
. Must be GL_TEXTURE_3D. No reference to
a bound GL texture object is made or implied by this parameter.
miplevel
The mipmap level to be used.
texture
The name of a GL 3D texture object. The texture object must be a
complete texture as per OpenGL rules on texture completeness. The
texture
format and dimensions defined by OpenGL
for the specified miplevel
of the texture will be
used to create the 3D image object. Only GL texture objects with an
internal format that maps to appropriate image channel order and data
type specified in the table of supported Image Channel Order Values
and the table of supported Image Channel Data Types at
cl_image_format can be used to create the 3D image object.
errcode_ret
Returns an appropriate error code as described below.
If errcode_ret
is NULL, no error code is returned.
If the state of a GL texture object is modified through the GL API (e.g. the OpenGL functions
glTexImage2D
, glTexImage3D
,
or the values of the texture parameters GL_TEXTURE_BASE_LEVEL or
GL_TEXTURE_MAX_LEVEL are modified) while there exists a corresponding CL image object,
subsequent use of the CL image object will result in undefined behavior.
The
clRetainMemObject
and
clReleaseMemObject
functions can be used to retain and release
the image objects.
Returns a valid non-zero OpenCL image object and errcode_ret
is
set to CL_SUCCESS if the image object is
created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret
:
context
is not a valid context or was not created from a GL context.
.
flags
are not valid or if value specified in texture_target
is not one of the
values specified in the description of texture_target
.
miplevel
is less than the
value of levelbase
(for OpenGL implementations) or zero
(for OpenGL ES implementations); or greater than the value of q
(for both OpenGL
and OpenGL ES). levelbase
and q
are
defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 specification
and section 3.7.10 of the OpenGL ES 2.0.
miplevel
is greater
than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.
texture
is not a
GL texture object whose type matches texture_target
, if the
specified miplevel
of texture
is not defined,
or if the width or height of the specified miplevel
is zero.
public static cl_mem clCreateFromGLRenderbuffer(cl_context context, long flags, int renderbuffer, int[] errcode_ret)
Creates an OpenCL 2D image object from an OpenGL renderbuffer object.
cl_mem
clCreateFromGLRenderbuffer
(
| cl_contextcontext, |
cl_mem_flagsflags, | |
GLuintrenderbuffer, | |
cl_int* errcode_ret) |
context
A valid OpenCL context created from an OpenGL context.
flags
A bit-field that is used to specify usage information. Refer to the table at clCreateBuffer for a description of flags
. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, and CL_MEM_READ_WRITE values specified in the table at clCreateBuffer can be used.
renderbuffer
The name of a GL renderbuffer object. The renderbuffer storage must be
specified before the image object can be created. The renderbuffer
format and dimensions defined by OpenGL will be used to create the 2D image object. Only GL renderbuffers with
internal formats that map to appropriate image channel order and data type specified in the table of supported Image Channel Order Values and
the table of supported Image Channel Data Types for cl_image_format
can be used to create the 2D image object.
errcode_ret
Returns an appropriate error code as described below.
If errcode_ret
is NULL, no error code is returned.
If the state of a GL renderbuffer object is modified through the GL API (i.e. changes to the
dimensions or format used to represent pixels of the GL renderbuffer using appropriate GL API
calls such as glRenderbufferStorage
) while there exists a corresponding CL image object,
subsequent use of the CL image object will result in undefined behavior.
The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the image objects.
The table below describes the list of GL renderbuffer internal formats and the corresponding CL image formats. If a GL renderbuffer object with an internal format from the table below is successfully created by OpenGL, then there is guaranteed to be a mapping to one of the corresponding CL image format(s) in that table. Renderbuffer objects created with other OpenGL internal formats may (but are not guaranteed to) have a mapping to a CL image format; if such mappings exist, they are guaranteed to preserve all color components, data types, and at least the number of bits/component actually allocated by OpenGL for that format.
GL internal format | CL image format (channel order, channel data type) |
---|---|
GL_RGBA8 | CL_RGBA, CL_UNORM_INT8 or CL_BGRA, CL_UNORM_INT8 |
GL_RGBA16 | CL_RGBA, CL_UNORM_INT16 |
GL_RGBA8I, GL_RGBA8I_EXT | CL_RGBA, CL_SIGNED_INT8 |
GL_RGBA16I, GL_RGBA16I_EXT | CL_RGBA, CL_SIGNED_INT16 |
GL_RGBA32I, GL_RGBA32I_EXT | CL_RGBA, CL_SIGNED_INT32 |
GL_RGBA8UI, GL_RGBA8UI_EXT | CL_RGBA, CL_UNSIGNED_INT8 |
GL_RGBA16UI, GL_RGBA16UI_EXT | CL_RGBA, CL_UNSIGNED_INT16 |
GL_RGBA32UI, GL_RGBA32UI_EXT | CL_RGBA, CL_UNSIGNED_INT32 |
GL_RGBA16F, GL_RGBA16F_ARB | CL_RGBA, CL_HALF_FLOAT |
GL_RGBA32F, GL_RGBA32F_ARB | CL_RGBA, CL_FLOAT |
Returns a valid non-zero OpenCL image object and errcode_ret
is set to CL_SUCCESS if the image object is created successfully. Otherwise, it returns a NULL
value with one of the following error values returned in errcode_ret
:
context
is not
a valid context or was not created from a GL context.
flags
are not valid.
renderbuffer
is not a GL renderbuffer object or if the width or height of renderbuffer
is zero.
renderbuffer
is a multi-sample
GL renderbuffer object.
public static int clGetGLObjectInfo(cl_mem memobj, int[] gl_object_type, int[] gl_object_name)
Query an OpenGL memory object used to create an OpenCL memory object.
cl_int
clGetGLObjectInfo
(
| cl_memmemobj, |
cl_gl_object_type*gl_object_type, | |
GLuint*gl_object_name) |
gl_object_type
Returns the type of GL object attached to memobj
and can be
CL_GL_OBJECT_BUFFER,
CL_GL_OBJECT_TEXTURE2D,
CL_GL_OBJECT_TEXTURE3D, or
CL_GL_OBJECT_RENDERBUFFER.
If gl_object_type
is NULL, it is ignored.
gl_object_name
Returns the GL object name used to create memobj
. If gl_object_name
is NULL,
it is ignored.
The OpenGL object used to create the OpenCL memory object and information about the object type i.e. whether it is a texture, renderbuffer, or buffer object can be queried using this function.
Returns CL_SUCCESS if the call was executed successfully. Otherwise, it returns one of the following errors:
memobj
is not a valid OpenCL memory object
memobj
.
public static int clGetGLTextureInfo(cl_mem memobj, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
Returns additional information about the GL texture object associated with a memory object.
cl_int
clGetGLTextureInfo
(
| cl_memmemobj, |
cl_gl_texture_infoparam_name, | |
size_tparam_value_size, | |
void*param_value, | |
size_t*param_value_size_ret) |
param_name
Specifies what additional information about the GL texture object associated with
memobj
to query. The list of supported
param_name
types and the information returned in
param_value
by
clGetGLTextureInfo
is described in the table below.
param_value
A pointer to memory where the result being queried is returned. If param_value
is NULL, it is ignored.
param_value_size
Specifies the size in bytes of memory pointed to by param_value
.
This size must be >= size of return type as described in the table below.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value
. If
param_value_size_ret
is NULL, it is ignored.
cl_gl_texture_info | Return Type | Information returned in param_value |
---|---|---|
CL_GL_TEXTURE_TARGET
|
GLenum |
The texture_target argument specified in
clCreateGLTexture2D or
clCreateGLTexture3D.
|
CL_GL_MIPMAP_LEVEL
|
GLint |
The miplevel argument specified in
clCreateGLTexture2D or
clCreateGLTexture3D.
|
Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
memobj
is not a valid OpenCL
memory object
memobj
.
param_name
is not valid, or if size
in bytes specified by param_value_size
is less than the size of return type as
described in the table above and param_value
is not NULL, or if
param_value
and param_value_size_ret
are NULL.
public static int clEnqueueAcquireGLObjects(cl_command_queue command_queue, int num_objects, cl_mem[] mem_objects, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Acquire OpenCL memory objects that have been created from OpenGL objects.
cl_int
clEnqueueAcquireGLObjects
(
| cl_command_queuecommand_queue, |
cl_uintnum_objects, | |
const cl_mem*mem_objects, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue. All devices used to create the OpenCL context
associated with command_queue
must support acquiring shared CL/GL objects.
This constraint is enforced at context creation time.
num_objects
The number of memory objects to be acquired in mem_objects
.
mem_objects
A pointer to a list of CL memory objects that correspond to GL objects.
event_wait_list
,
num_events_in_wait_list
Specify events that need to complete before this
particular command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL,
num_events_in_wait_list
must be 0. If event_wait_list
is not NULL,
the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0.
The events specified in
event_wait_list
act as synchronization points.
event
Returns an event object that identifies this command and can be used to query or queue a
wait for the command to complete. event
can be NULL in which
case it will not be possible for the application to query the status of this command or queue
a wait for this command to complete.
When the cl_khr_gl_event extension is enabled, If an OpenGL context is bound to the current thread, then any OpenGL commands which:
mem_objects
list, and
will complete before execution of any OpenCL commands following the
clEnqueueAcquireGLObjects
which affect or access any of those memory objects. If a non-NULL event
object is
returned, it will report completion only after completion of such OpenGL commands.
These
objects need to be acquired before they can be used by any OpenCL commands queued to a
command-queue. The OpenGL objects are acquired by the OpenCL context associated with
command_queue
and can therefore be used by all command-queues associated with the OpenCL
context.
In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/GL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.
Prior to calling clEnqueueAcquireGLObjects
, the application
must ensure that any pending GL operations which access the objects specified in
mem_objects
have completed. This may be accomplished portably
by issuing and waiting for completion of a
glFinish command on
all GL contexts with pending references to these objects. Implementations may
offer more efficient synchronization methods; for example on some platforms
calling glFlush
may be sufficient, or synchronization may be implicit within a thread, or
there may be vendor-specific extensions that enable placing a fence in the
GL command stream and waiting for completion of that fence in the
CL command queue. Note that no synchronization methods other than
glFinish are
portable between OpenGL implementations at this time.
Similarly, after calling clEnqueueReleaseGLObjects
,
the application is responsible for ensuring that any pending OpenCL operations
which access the objects specified in mem_objects
have
completed prior to executing subsequent GL commands which reference these objects. This
may be accomplished portably by calling clWaitForEvents with the event object returned by
clEnqueueReleaseGLObjects
, or by calling glFinish. As above, some implementations may
offer more efficient methods.
The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.
If a GL context is bound to a thread other than the one in which clEnqueueReleaseGLObjects
is called, changes to any of the objects in mem_objects
may not be visible to that context without
additional steps being taken by the application. For an OpenGL 3.1 (or later) context, the
requirements are described in Appendix G ("Shared Objects and Multiple Contexts") of the
OpenGL 3.1 Specification. For prior versions of OpenGL, the requirements are implementationdependent.
Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.
Returns CL_SUCCESS if the function is executed successfully. If
num_objects
is 0 and mem_objects
is NULL
the function does nothing and returns CL_SUCCESS.
Otherwise, it returns one of the following errors:
num_objects
is zero and
mem_objects
is not a NULL value or if num_objects
> 0
and mem_objects
is NULL.
mem_objects
are not valid OpenCL memory objects.
command_queue
is not a
valid command-queue.
command_queue
was not created from an OpenGL context.
mem_objects
have not been created from a GL object(s).
event_wait_list
is NULL and num_events_in_wait_list
> 0, or
event_wait_list
is not NULL and
num_events_in_wait_list
is 0, or if event objects in
event_wait_list
are not valid events.
public static int clEnqueueReleaseGLObjects(cl_command_queue command_queue, int num_objects, cl_mem[] mem_objects, int num_events_in_wait_list, cl_event[] event_wait_list, cl_event event)
Release OpenCL memory objects that have been created from OpenGL objects.
cl_int
clEnqueueReleaseGLObjects
(
| cl_command_queuecommand_queue, |
cl_uintnum_objects, | |
const cl_mem*mem_objects, | |
cl_uintnum_events_in_wait_list, | |
const cl_event*event_wait_list, | |
cl_event*event) |
command_queue
A valid command-queue.
num_objects
The number of memory objects to be released in mem_objects
.
mem_objects
A pointer to a list of CL memory objects that correspond to GL objects.
event_wait_list
,
num_events_in_wait_list
These parameters specify events that need to complete before this
command can be executed. If event_wait_list
is NULL, then this particular command
does not wait on any event to complete. If event_wait_list
is NULL,
num_events_in_wait_list
must be 0. If event_wait_list
is not NULL,
the list of events pointed to by event_wait_list
must
be valid and num_events_in_wait_list
must be greater than 0.
The events specified in
event_wait_list
act as synchronization points.
event
Returns an event object that identifies this particular read/write
command and can be used to query or queue a wait for the command to complete.
event
can be NULL in which case it will not be possible
for the application to query the status of this command or queue a wait
for this command to complete.
When the cl_khr_gl_event extension is enabled, If an OpenGL context is bound to the current thread, then any OpenGL commands which:
mem_objects
list, and
will not execute until after execution of any OpenCL commands preceding the
clEnqueueReleaseGLObjects
which affect or access any of those memory objects. If a non-NULL event
object is
returned, it will report completion before execution of such OpenGL commands.
These objects need to be released before they can be used by OpenGL.
The OpenGL objects are released by the OpenCL context associated with command_queue
.
In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/GL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.
Prior to calling clEnqueueAcquireGLObjects
, the application
must ensure that any pending GL operations which access the objects specified in
mem_objects
have completed. This may be accomplished portably
by issuing and waiting for completion of a
glFinish command on
all GL contexts with pending references to these objects. Implementations may
offer more efficient synchronization methods; for example on some platforms
calling glFlush
may be sufficient, or synchronization may be implicit within a thread, or
there may be vendor-specific extensions that enable placing a fence in the
GL command stream and waiting for completion of that fence in the
CL command queue. Note that no synchronization methods other than
glFinish are
portable between OpenGL implementations at this time.
Similarly, after calling clEnqueueReleaseGLObjects
,
the application is responsible for ensuring that any pending OpenCL operations
which access the objects specified in mem_objects
have
completed prior to executing subsequent GL commands which reference these objects. This
may be accomplished portably by calling clWaitForEvents with the event object returned by
clEnqueueReleaseGLObjects
, or by calling glFinish. As above, some implementations may
offer more efficient methods.
The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.
If a GL context is bound to a thread other than the one in which clEnqueueReleaseGLObjects
is called, changes to any of the objects in mem_objects
may not be visible to that context without
additional steps being taken by the application. For an OpenGL 3.1 (or later) context, the
requirements are described in Appendix G ("Shared Objects and Multiple Contexts") of the
OpenGL 3.1 Specification. For prior versions of OpenGL, the requirements are implementationdependent.
Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.
clEnqueueReleaseGLObjects
returns CL_SUCCESS if the function is executed successfully. If num_objects
is 0 and mem_objects
is NULL the function does nothing and returns CL_SUCCESS. Otherwise, it returns one of the following errors:
num_objects
is zero
and mem_objects
is not a NULL value or if
num_objects
> 0 and mem_objects
is NULL.
mem_objects
are not valid OpenCL memory objects.
command_queue
is not a valid command-queue.
command_queue
was not created from an OpenGL context.
mem_objects
have not been created from a GL object(s).
event_wait_list
is
NULL and num_events_in_wait_list
> 0, or event_wait_list
is not NULL and num_events_in_wait_list
is 0, or if event objects in
event_wait_list
are not valid events.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |