|
|||||||||
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 has been extracted from the OpenCL specification.
References to tables and sections refer to version 1.0.43 of the
OpenCL specification.
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 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 & links) a program executable. |
static cl_mem |
clCreateBuffer(cl_context context,
long flags,
long size,
Pointer host_ptr,
int[] errcode_ret)
Used to create a buffer object. |
static cl_command_queue |
clCreateCommandQueue(cl_context context,
cl_device_id device,
long properties,
int[] errcode_ret)
Creates 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)
Creates 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)
Used to crate an image (1D, or 2D) 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)
Used to create a 3D image object . |
static cl_kernel |
clCreateKernel(cl_program program,
java.lang.String kernel_name,
int[] errcode_ret)
Create a kernel. |
static int |
clCreateKernelsInProgram(cl_program program,
int num_kernels,
cl_kernel[] kernels,
int[] num_kernels_ret)
Ccreates kernel objects for all kernel functions in program. |
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. |
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. |
static cl_sampler |
clCreateSampler(cl_context context,
boolean normalized_coords,
int addressing_mode,
int filter_mode,
int[] errcode_ret)
Creates a sampler 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)
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 a 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. |
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 in the image object. |
static int |
clEnqueueMarker(cl_command_queue command_queue,
cl_event event)
Enqueues a marker command to command_queue. |
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 |
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)
Enqueue commands 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. |
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 from 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)
Enqueue commands 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 have completed. |
static int |
clFlush(cl_command_queue command_queue)
Issues all previously queued OpenCL commands. |
static int |
clGetCommandQueueInfo(cl_command_queue command_queue,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Can be used to 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)
Can be used to 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)
Obtains 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)
Gets specific 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 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. |
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 memobj. |
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 created with clCreateImage{2D|3D}. |
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)
Rreturns 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)
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)
Returns a list of OpenCL platforms found. |
static int |
clGetPlatformInfo(cl_platform_id platform,
int param_name,
long param_value_size,
Pointer param_value,
long[] param_value_size_ret)
Gets 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)
Decrements 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 memobj 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)
Increments the context reference count. |
static int |
clRetainEvent(cl_event event)
Increments the event reference count. |
static int |
clRetainKernel(cl_kernel kernel)
Increments the kernel reference count. |
static int |
clRetainMemObject(cl_mem memobj)
Increments the memobj 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)
Can be used to enable or disable the properties of a command-queue. |
static int |
clSetKernelArg(cl_kernel kernel,
int arg_index,
long arg_size,
Pointer arg_value)
Set the argument value for a specific argument of a kernel. |
static int |
clUnloadCompiler()
Allows 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. |
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_VERSION_1_0
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_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 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 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_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_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_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_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_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_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_COMPLETE
public static final int CL_RUNNING
public static final int CL_SUBMITTED
public static final int CL_QUEUED
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 int clGetPlatformIDs(int num_entries, cl_platform_id[] platforms, int[] num_platforms)
cl_int clGetPlatformIDs (cl_uint_num_entries, cl_platform_id *platforms, cl_uint *num_platforms)
num_entries is 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 minimum 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.
clGetPlatformsIDs 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, and returns CL_SUCCESS if the function is executed successfully.
For JOCL:
public static int clGetPlatformInfo(cl_platform_id platform, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetPlatformInfo (cl_platform_id platform, cl_platform_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
The information that can be queried using clGetPlatformInfo is specified in the table below.
platform refers to the platform ID returned by clGetPlatformsIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.
param_name is an enumeration constant that identifies the platform information being queried. It can be one of the following values as specified in the table.
param_value is a pointer to memory location where appropriate values for a given param_name as specified in the table 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 >= size of return type specified in the table.
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_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. The embedded profile for OpenCL 1.0 is described in the OpenCL documentation, section 10. |
CL_PLATFORM_VERSION | char[] | OpenCL version string. Returns the OpenCL version supported by the implementation. This version string has the following format: OpenCL<space><major_version.min or_version><space><platformspecific information> The major_version.minor_version value returned will be 1.0. |
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. |
clGetPlatformInfo returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_PLATFORM_if platform is not a valid platform, returns CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the table and param_value is not a NULL value.
public static int clGetDeviceIDs(cl_platform_id platform, long device_type, int num_entries, cl_device_id[] devices, int[] num_devices)
Obtains the list of devices available on a platform.
cl_int clGetDeviceIDs3 (cl_platform_id platform, cl_device_type device_type, cl_uint num_entries, cl_device_id *devices, cl_uint *num_devices)
platform refers to the platform ID returned by clGetPlatformsIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.
device_type is 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 table.
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 is 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 returns 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 returns the number of OpenCL devices available that match device_type. If num_devices is NULL, this argument is ignored.
clGetDeviceIDs returns CL_INVALID_PLATFORM_if platform is not a valid platform, returns CL_INVALID_DEVICE_TYPE if device_type is not a valid value, returns CL_INVALID_VALUE if num_entries is equal to zero and devices is not NULL or if both num_devices and devices are NULL, returns CL_DEVICE_NOT_FOUND if no OpenCL devices that matched device_type were found, and returns CL_SUCCESS if the function is executed successfully.
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.
For JOCL:
public static int clGetDeviceInfo(cl_device_id device, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetDeviceInfo (cl_device_id device, cl_device_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
The information that can be queried using clGetDeviceInfo is specified in the table.
device is a device returned by clGetDeviceIDs.
param_name is an enumeration constant that identifies the device information being queried. It can be one of the following values as specified in the table.
param_value is a pointer to memory location where appropriate values for a given param_name as specified in the table 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 >= size of return type specified in the table.
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 | Return Type | Description |
---|---|---|
CL_DEVICE_TYPE | cl_device_type | The OpenCL device type. Currently supported values are: CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ACCELERATOR, CL_DEVICE_TYPE_DEFAULT or a combination of the above. |
CL_DEVICE_VENDOR_ID | cl_uint | A unique device vendor identifier. An example of a unique device identifier could be the PCIe ID. |
CL_DEVICE_MAX_COMPUTE_UNITS | cl_uint | The number of parallel compute cores on the OpenCL device. The minimum value is 1. |
CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS | 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 | size_t [] | Maximum number of work-items that can be specified in each dimension of the work-group to clEnqueueNDRangeKernel. Returns n size_t entries, where n is the value returned by the query for CL_DEVICE_MAX_WORK_ITEM_DI MENSIONS. The minimum value is (1, 1, 1). |
CL_DEVICE_MAX_WORK_GROUP_SIZE | 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_PREFERRED_VECTOR_WIDTH_CHAR CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE |
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_WID TH_DOUBLE must return 0. |
CL_DEVICE_MAX_CLOCK_FREQUENCY | cl_uint | Maximum configured clock frequency of the device in MHz. |
CL_DEVICE_ADDRESS_BITS | 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_MAX_MEM_ALLOC_SIZE | 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_IMAGE_SUPPORT | cl_bool | Is CL_TRUE if images are supported by the OpenCL device and CL_FALSE otherwise. |
CL_DEVICE_MAX_READ_IMAGE_ARGS | 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_WRITE_IMAGE_ARGS | 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_IMAGE2D_MAX_WIDTH | size_t | Max width of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE2D_MAX_HEIGHT | size_t | Max height of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE3D_MAX_WIDTH | size_t | Max width of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_IMAGE3D_MAX_HEIGHT | 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_DEPTH | size_t | Max depth of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_MAX_SAMPLERS | cl_uint | Maximum number of samplers that can be used in a kernel. Refer to section 6.11.8 for a detailed description on samplers. The minimum value is 16 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. |
CL_DEVICE_MAX_PARAMETER_SIZE | size_t | Max size in bytes of the arguments that can be passed to a kernel. The minimum value is 256. |
CL_DEVICE_MEM_BASE_ADDR_ALIGN | cl_uint | Describes the alignment in bits of the base address of any allocated memory object. |
CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE | cl_uint | The smallest alignment in bytes which can be used for any data type. |
CL_DEVICE_SINGLE_FP_CONFIG | 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. The mandated minimum floating-point capability is: CL_FP_ROUND_TO_NEAREST | CL_FP_INF_NAN. |
CL_DEVICE_GLOBAL_MEM_CACHE_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 | cl_uint | Size of global memory cache line in bytes. |
CL_DEVICE_GLOBAL_MEM_CACHE_SIZE | cl_ulong | Size of global memory cache in bytes. |
CL_DEVICE_GLOBAL_MEM_SIZE | cl_ulong | Size of global device memory in bytes. |
CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE | cl_ulong | Max size in bytes of a constant buffer allocation. The minimum value is 64 KB. |
CL_DEVICE_MAX_CONSTANT_ARGS | cl_uint | Max number of arguments declared with the __constant qualifier in a kernel. The minimum value is 8. |
CL_DEVICE_LOCAL_MEM_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_LOCAL_MEM_SIZE | cl_ulong | Size of local memory arena in bytes. The minimum value is 16 KB. |
CL_DEVICE_ERROR_CORRECTION_SUPPORT | cl_bool | Is CL_TRUE if the device implements error correction for the memories, caches, registers etc. in the device. Is CL_FALSE if the device does not implement error correction. This can be a requirement for certain clients of OpenCL. |
CL_DEVICE_PROFILING_TIMER_RESOLUTION | size_t | Describes the resolution of device timer. This is measured in nanoseconds. Refer to section 5.9 of the OpenCL documentation for details. |
CL_DEVICE_ENDIAN_LITTLE | cl_bool | Is CL_TRUE if the OpenCL device is a little endian device and CL_FALSE otherwise. |
CL_DEVICE_AVAILABLE | cl_bool | Is CL_TRUE if the device is available and CL_FALSE if the device is not available. |
CL_DEVICE_COMPILER_AVAILABLE | 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_EXECUTION_CAPABILITIES | 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_QUEUE_PROPERTIES | 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 a separate table. The mandated minimum capability is: CL_QUEUE_PROFILING_ENABLE. |
CL_DEVICE_PLATFORM | cl_platform_id | The platform associated with this device. |
CL_DEVICE_NAME | char[] | Device name string. |
CL_DEVICE_VENDOR | char[] | Vendor name string. |
CL_DRIVER_VERSION | char[] | OpenCL software driver version string in the form major_number.minor_number. |
CL_DEVICE_PROFILE4 | char[] | OpenCL profile string. Returns the profile name supported by the
device. 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_VERSION | char[] | OpenCL version string. Returns the OpenCL version supported by the device. This version string has the following format: OpenCL<space><major_version.min or_version><space><vendor-specific information> The major_version.minor_version value returned will be 1.0. |
CL_DEVICE_EXTENSIONS | 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_khr_select_fprounding_mode cl_khr_global_int32_base_atomics cl_khr_global_int32_extended_atomics cl_khr_local_int32_base_atomics cl_khr_local_int32_extended_atomics cl_khr_int64_base_atomics cl_khr_int64_extended_atomics cl_khr_3d_image_writes cl_khr_byte_addressable_store cl_khr_fp16 Please refer to section 9 of the OpenCL documentation for a detailed description of these extensions. |
clGetDeviceInfo returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_DEVICE if device is not valid, returns CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the table 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)
cl_context clCreateContext (cl_context_properties *properties, cl_uint num_devices, const cl_device_id *devices, void (*pfn_notify)(const char *errinfo, const void *private_info, size_t cb, void *user_data), 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.
properties 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. The list of supported properties is described in the table. properties can be NULL in which case the platform that is selected is implementation-defined.
cl_context_properties enum | Property value | Description |
CL_CONTEXT_PLATFORM | cl_platform_id | Specifies the platform to use. |
num_devices is the number of devices specified in the devices argument.
devices is a pointer to a list of unique devices returned by clGetDeviceIDs for a platform.
pfn_notify is 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. The parameters to this callback function are:
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned. clCreateContext 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
values returned in errcode_ret:
CL_INVALID_PLATFORM if properties is NULL and no platform could be selected or if platform value specified in properties is not a valid platform.
CL_INVALID_VALUE if context property name in properties is not a supported property name. CL_INVALID_VALUE if devices is NULL. CL_INVALID_VALUE if num_devices is equal to zero.
CL_INVALID_VALUE if pfn_notify is NULL but user_data is not NULL. CL_INVALID_DEVICE if devices contains an invalid device or are not associated with the specified platform.
CL_DEVICE_NOT_AVAILABLE if a device in devices is currently not available even though the device was returned by clGetDeviceIDs. CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static cl_context clCreateContextFromType(cl_context_properties properties, long device_type, CreateContextFunction pfn_notify, java.lang.Object user_data, int[] errcode_ret)
clCreateContextFromType (cl_context_properties *properties, cl_device_type device_type, void (*pfn_notify)(const char *errinfo, const void *private_info, size_t cb, void *user_data), void *user_data, cl_int *errcode_ret)
properties 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. The list of supported properties is described in the table in the documentation of clCreateContext. properties can also be NULL in which case the platform that is selected is implementation-defined.
device_type is a bit-field that identifies the type of device and is described in the table in the documentation of clGetDeviceIDs.
pfn_notify and user_data are described in clCreateContext.
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
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 values returned in errcode_ret:
CL_INVALID_PLATFORM if properties is NULL and no platform could be selected or if platform value specified in properties is not a valid platform.
CL_INVALID_VALUE if context property name in properties is not a supported property name.
CL_INVALID_VALUE if pfn_notify is NULL but user_data is not NULL.
CL_INVALID_DEVICE_TYPE if device_type is not a valid value.
CL_DEVICE_NOT_AVAILABLE if no devices that match device_type are currently available.
clCreateContextfromType may return all or a subset of the actual physical devices present in the platform and that match device_type.
CL_DEVICE_NOT_FOUND if no devices that match device_type were found.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clRetainContext(cl_context context)
cl_int clRetainContext (cl_context context)
clRetainContext returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_CONTEXT if context is not a valid OpenCL context.
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.
public static int clReleaseContext(cl_context context)
cl_int clReleaseContext (cl_context context)
decrements the context reference count. clReleaseContext returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_CONTEXT if context is not a valid OpenCL context.
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.
public static int clGetContextInfo(cl_context context, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetContextInfo (cl_context context, cl_context_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
can be used to query information about a context.
context specifies the OpenCL context being queried.
param_name is an enumeration constant that specifies the information to query.
param_value is 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.
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 clGetContextInfo is described in table.
cl_context_info | Return Type | Information returned in param_value |
CL_CONTEXT_REFERENCE_COUNT | cl_uint | Return the context reference count. |
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. |
clGetContextInfo returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_CONTEXT if context is not a valid context, returns CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the table, 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)
cl_command_queue clCreateCommandQueue (cl_context context, cl_device_id device, cl_command_queue_properties properties, cl_int *errcode_ret)
context must be a valid OpenCL context.
The table lists of supported cl_command_queue_property values and description.
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-oforder. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order. For a detailed description about CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE, refer to section 5.8 of the OpenCL documentation. |
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. For a detailed description, refer to section 5.9 of the OpenCL documentation. |
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 and is described in table 5.1. Only command-queue properties specified in table 5.1 can be set in properties; otherwise the value specified in properties is considered to be not valid.
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_DEVICE if device is not a valid device or is not associated with context.
CL_INVALID_VALUE if values specified in properties are not valid.
CL_INVALID_QUEUE_PROPERTIES if values specified in properties are valid but are not supported by the device.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clRetainCommandQueue(cl_command_queue command_queue)
cl_int clRetainCommandQueue (cl_command_queue command_queue)
clRetainCommandQueue 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 clReleaseCommandQueue(cl_command_queue command_queue)
cl_int clReleaseCommandQueue (cl_command_queue command_queue)
clReleaseCommandQueue returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
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.
public static int clGetCommandQueueInfo(cl_command_queue command_queue, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetCommandQueueInfo (cl_command_queue command_queue, cl_command_queue_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
command_queue specifies the command-queue being queried.
param_name specifies the information to query.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.2. 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 table 5.2.
cl_command_queue_info | Return Type | Information returned in param_value |
CL_QUEUE_CONTEXT | cl_context | Return the context specified when command-queue is created. |
CL_QUEUE_REFERENCE_COUNT | cl_uint | Return the command-queue reference count. |
---|---|---|
CL_QUEUE_PROPERTIES | cl_command_ queue_properties | Return the currently specified properties for the command-queue. These properties are specified by the properties argument in clCreateCommandQueue, and can be changed by clSetCommandQueueProperty. |
clGetCommandQueueInfo returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue, returns CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the table and param_value is not a NULL value.
public static int clSetCommandQueueProperty(cl_command_queue command_queue, long properties, boolean enable, long[] old_properties)
cl_int clSetCommandQueueProperty (cl_command_queue command_queue, cl_command_queue_properties properties, cl_bool enable, cl_command_queue_properties *old_properties)
properties specifies the new command-queue properties to be applied to command_queue. Only command-queue properties specified in the table in the documentation of 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 property values are described in the table in the documentation of clCreateCommandQueue
old_properties returns the command-queue properties before they were changed by clSetCommandQueueProperty. If old_properties is NULL, it is ignored.
As specified in the table in the documentation of 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.
clSetCommandQueueProperty returns CL_SUCCESS if the command-queue properties are successfully updated. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue, returns CL_INVALID_VALUE if the values specified in properties are not valid and returns CL_INVALID_QUEUE_PROPERTIES if values specified in 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)
cl_mem clCreateBuffer (cl_context context, cl_mem_flags flags, size_t size, void *host_ptr, cl_int *errcode_ret)
context is a valid OpenCL context used to create the buffer object.
flags is 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. Table 5.3 describes the possible values for flags: size is the size in bytes of the buffer memory object to be allocated.
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_WRITE_ONLY inside a kernel is undefined. |
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_READ_ONLY inside a kernel is undefined. |
CL_MEM_USE_HOST_PTR | This flag is valid only if host_ptr is not NULL. If specified, it indicates that the application wants the OpenCL implementation to use memory referenced by host_ptr as the storage bits for the memory object. OpenCL implementations are allowed to cache the buffer contents pointed to by host_ptr in device memory. This cached copy can be used when kernels are executed on a device. The result of OpenCL commands that operate on multiple |
buffer objects created with the same host_ptr or overlapping host regions is considered to be undefined. | |
CL_MEM_ALLOC_HOST_PTR | This flag specifies that the application wants the OpenCL implementation to allocate memory from host accessible memory. CL_MEM_ALLOC_HOST_PTR and CL_MEM_USE_HOST_PTR are mutually exclusive. |
CL_MEM_COPY_HOST_PTR | This flag is valid only if host_ptr is not NULL. If specified, it indicates that the application wants the OpenCL implementation to allocate memory for the memory object and copy the data from memory referenced by host_ptr. CL_MEM_COPY_HOST_PTR and CL_MEM_USE_HOST_PTR are mutually exclusive. CL_MEM_COPY_HOST_PTR can be used with CL_MEM_ALLOC_HOST_PTR to initialize the contents of the cl_mem object allocated using host-accessible (e.g. PCIe) memory. |
host_ptr is 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 >= size bytes.
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
clCreateBuffer 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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if values specified in flags are not valid.
CL_INVALID_BUFFER_SIZE if size is 0 or is greater than
CL_DEVICE_MAX_MEM_ALLOC_SIZE value specified in table 4.3 for all devices in context.
CL_INVALID_HOST_PTR if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for buffer object.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_mem clCreateImage2D (cl_context context, cl_mem_flags flags, const cl_image_format *image_format, size_t image_width, size_t image_height, size_t image_row_pitch, void *host_ptr, cl_int *errcode_ret)
context is a valid OpenCL context on which the image object is to be created.
flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in table 5.3.
image_format is a pointer to a structure that describes format properties of the image to be allocated. Refer to section 5.2.4.1 for a detailed description of the image format descriptor.
image_width, and image_height are the width and height of the image in pixels. These must be values greater than or equal to 1.
image_row_pitch is the scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or >= image_width * size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch = 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 is 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 >= 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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if values specified in flags are not valid.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.
CL_INVALID_IMAGE_SIZE if 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.
CL_INVALID_HOST_PTR if 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.
CL_IMAGE_FORMAT_NOT_SUPPORTED if the image_format is not supported.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for image object.
CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in table 4.3 is CL_FALSE).
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_mem clCreateImage3D (cl_context context, cl_mem_flags flags, const cl_image_format *image_format, size_t image_width, size_t image_height, size_t image_depth, size_t image_row_pitch, size_t image_slice_pitch, void *host_ptr, cl_int *errcode_ret)
context is a valid OpenCL context on which the image object is to be created.
flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in table 5.3.
image_format is a pointer to a structure that describes format properties of the image to be allocated. Refer to section 5.2.4.1 for a detailed description of the image format descriptor.
image_width, and image_height are the width and height of the image in pixels. These must be values greater than or equal to 1.
image_depth is the depth of the image in pixels. This must be a value > 1.
image_row_pitch is the scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or >= image_width * size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch = 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 is 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 >= image_row_pitch * image_height if host_ptr is not NULL. If host_ptr is not NULL and image_slice_pitch = 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 is 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 >= 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.
clCreateImage3D 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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if values specified in flags are not valid.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.
CL_INVALID_IMAGE_SIZE if image_width, image_height are 0 or if image_depth <= 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.
CL_INVALID_HOST_PTR if 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. CL_IMAGE_FORMAT_NOT_SUPPORTED if the image_format is not supported. CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for image object.
CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in table 4.3 is CL_FALSE). CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clRetainMemObject(cl_mem memobj)
cl_int clRetainMemObject (cl_mem memobj)
increments the memobj reference count. clRetainMemObject returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_MEM_OBJECT if memobj is not a valid memory object. clCreateBuffer and clCreateImage{2D|3D} perform an implicit retain.
public static int clReleaseMemObject(cl_mem memobj)
cl_int clReleaseMemObject (cl_mem memobj)
decrements the memobj reference count. 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. clReleaseMemObject returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.
public static int clGetSupportedImageFormats(cl_context context, long flags, int image_type, int num_entries, cl_image_format[] image_formats, int[] num_image_formats)
cl_int clGetSupportedImageFormats (cl_context context, cl_mem_flags flags, cl_mem_object_type image_type, cl_uint num_entries, cl_image_format *image_formats, cl_uint *num_image_formats)
context is a valid OpenCL context on which the image object(s) will be created.
flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in table 5.3.
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 is 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 is 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 returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_CONTEXT if context is not a valid context, returns CL_INVALID_VALUE if 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)
cl_int clGetMemObjectInfo (cl_mem memobj, cl_mem_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret) 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 table 5.8.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.8.
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.
clGetMemObjectInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.8 and param_value is not NULL, and returns CL_INVALID_MEM_OBJECT if memobj is a not a valid memory object.
cl_mem_info | Return type | Info. returned in param_value |
---|---|---|
CL_MEM_TYPE | cl_mem_object_type | Returns CL_MEM_OBJECT_BUFFER if memobj is created with clCreateBuffer, CL_MEM_OBJECT_IMAGE2D if memobj is created with clCreateImage2D or CL_MEM_OBJECT_IMAGE3D if memobj is created with clCreateImage3D. |
CL_MEM_FLAGS | cl_mem_flags | Return the flags argument value specified when memobj is created with clCreateBuffer or clCreateImage{2D|3D}. |
CL_MEM_SIZE | size_t | Return actual size of memobj in bytes. |
CL_MEM_HOST_PTR | void * | Return the host_ptr argument value specified when memobj is created. |
CL_MEM_MAP_COUNT8 | cl_uint | Map count. |
CL_MEM_REFERENCE_COUNT9 | cl_uint | Return memobj reference count. |
CL_MEM_CONTEXT | cl_context | Return context specified when memory object is created |
public static int clGetImageInfo(cl_mem image, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetImageInfo (cl_mem image, cl_image_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.9.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.9.
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.
clGetImageInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.9 and param_value is not NULL, and returns CL_INVALID_MEM_OBJECT if image is a not a valid image object.
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 clCreateImage{2D|3D}. |
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 the image in pixels |
CL_IMAGE_HEIGHT | size_t | Return height of the image in pixels |
CL_IMAGE_DEPTH | size_t | Return depth of the image in pixels. For a 2D image, depth = 0. |
public static cl_sampler clCreateSampler(cl_context context, boolean normalized_coords, int addressing_mode, int filter_mode, int[] errcode_ret)
cl_sampler clCreateSampler (cl_context context, cl_bool normalized_coords, cl_addressing_mode addressing_mode, cl_filter_mode filter_mode, cl_int *errcode_ret)
Refer to section 6.11.8.1 for a detailed description of how samplers work.
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_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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
clCreateSampler 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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if addressing_mode, filter_mode or normalized_coords or combination of these argument values are not valid.
CL_INVALID_OPERATION if images are not supported by any device associated with
context (i.e. CL_DEVICE_IMAGE_SUPPORT specified in table 4.3 is CL_FALSE).
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clRetainSampler(cl_sampler sampler)
cl_int clRetainSampler (cl_sampler sampler)
clCreateSampler does an implicit retain. clRetainSampler returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_SAMPLER if sampler is not a valid sampler object.
The function
public static int clReleaseSampler(cl_sampler sampler)
cl_int clReleaseSampler (cl_sampler sampler)
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. clReleaseSampler returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_SAMPLER if 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)
cl_int clGetSamplerInfo (cl_sampler sampler, cl_sampler_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.10.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.10.
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 | Info. returned in param_value |
---|---|---|
CL_SAMPLER_REFERENCE_ COUNT10 | cl_uint | Return the sampler reference count. |
CL_SAMPLER_CONTEXT | cl_context | Return the context specified when the sampler is created. |
CL_SAMPLER_ADDRESSING_ MODE | cl_addressing_ mode | Return the value specified by addressing_mode argument to clCreateSampler. |
CL_SAMPLER_FILTER_MODE | cl_filter_mode | Return the value specified by filter_mode argument to clCreateSampler. |
CL_SAMPLER_NORMALIZED_ COORDS | cl_bool | Return the value specified by normalized_coords argument to clCreateSampler. |
clGetSamplerInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.10 and param_value is not NULL, and returns CL_INVALID_SAMPLER if 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)
cl_program clCreateProgramWithSource (cl_context context, cl_uint count, const char **strings, const size_t *lengths, cl_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. The devices associated with the program object are the devices associated with context.
context must be a valid OpenCL context.
strings is an array of count pointers to optionally null-terminated character strings that make up the source code.
The lengths argument is 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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
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: CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if count is zero or if strings or any entry in strings is NULL.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_program clCreateProgramWithBinary (cl_context context, cl_uint num_devices, const cl_device_id *device_list, const size_t *lengths, const unsigned char **binaries, cl_int *binary_status, cl_int *errcode_ret)
creates a program object for a context, and loads the binary bits specified by binary into the program object.
context must be a valid OpenCL context.
device_list is 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 is 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 is an array of the size in bytes of the program binaries to be loaded for devices specified by device_list.
binaries is 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:
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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
clCreateProgramWithBinary 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:
CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if device_list is NULL or num_devices is zero.
CL_INVALID_DEVICE if OpenCL devices listed in device_list are not in the list of devices associated with context.
CL_INVALID_VALUE if lengths or binaries are NULL or if any entry in lengths[i] is zero or binaries[i] is NULL.
CL_INVALID_BINARY if an invalid program binary was encountered for any device. binary_status will return specific status for each device.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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.
public static int clRetainProgram(cl_program program)
cl_int clRetainProgram (cl_program program)
clCreateProgram does an implicit retain. clRetainProgram returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_PROGRAM if program is not a valid program object.
The function
public static int clReleaseProgram(cl_program program)
cl_int clReleaseProgram (cl_program program)
The program object is deleted after all kernel objects associated with program have been deleted and the program reference count becomes zero. clReleaseProgram returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_PROGRAM if 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)
cl_int clBuildProgram (cl_program program, cl_uint num_devices, const cl_device_id *device_list, const char *options, void (*pfn_notify)(cl_program, void *user_data), void *user_data)
builds (compiles & links) a program executable from the program source or binary for all the devices or a specific device(s) in the OpenCL context associated with program. OpenCL allows program executables to be built using the source or the binary.
program is the program object.
device_list is a pointer to a list of devices associated with program. If device_list is a 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 is the number of devices listed in device_list.
options is a pointer to a string that describes the build options to be used for building the program executable. The list of supported options is described in section 5.4.3.
pfn_notify is 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 will be passed as an argument when pfn_notify is called. user_data can be NULL.
clBuildProgram returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_PROGRAM if program is not a valid program object.
CL_INVALID_VALUE if device_list is NULL and num_devices is greater than zero, or if device_list is not NULL and num_devices is zero.
CL_INVALID_VALUE if pfn_notify is NULL but user_data is not NULL.
CL_INVALID_DEVICE if OpenCL devices listed in device_list are not in the list of devices associated with program.
CL_INVALID_BINARY if program is created with clCreateWithProgramBinary and devices listed in device_list do not have a valid program binary loaded.
CL_INVALID_BUILD_OPTIONS if the build options specified by options are invalid.
CL_INVALID_OPERATION if the build of a program executable for any of the devices listed in device_list by a previous call to clBuildProgram for program has not completed.
CL_COMPILER_NOT_AVAILABLE if program is created with clCreateProgramWithSource and a compiler is not available i.e. CL_DEVICE_COMPILER_AVAILABLE specified in table 4.3 is set to CL_FALSE.
CL_BUILD_PROGRAM_FAILURE if there is a failure to build the program executable. This error will be returned if clBuildProgram does not return until the build has completed.
CL_INVALID_OPERATION if there are kernel objects attached to program.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clUnloadCompiler()
cl_int clUnloadCompiler (void)
allows the implementation to release the resources allocated by the OpenCL compiler. 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)
cl_int clGetProgramInfo (cl_program program, cl_program_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.11.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.11.
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_program_info | Return Type | Info. returned in param_value |
---|---|---|
CL_PROGRAM_REFERENCE_ COUNT11 | cl_uint | Return the program reference count. |
CL_PROGRAM_CONTEXT | cl_context | Return the context specified when the program object is created |
CL_PROGRAM_NUM_DEVICES | cl_uint | Return the number of devices associated with program. |
CL_PROGRAM_DEVICES | 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 program object is created using clCreateProgramWithBinary. |
CL_PROGRAM_SOURCE | 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 param_value_size_ret. |
CL_PROGRAM_BINARY_SIZES | size_t[] | Returns an array that contains the size in bytes of the program binary for each device associated with program. The size of the array is the number of devices associated with program. If a binary is not available for a device(s), a size of zero is returned. |
CL_PROGRAM_BINARIES | unsigned char *[] | Return the program binaries for all devices associated with program. For each device in program, the binary returned can be the binary specified for the device when program is created with clCreateProgramWithBinary or it can be the executable binary generated by clBuildProgram. If program is created with clCreateProgramWithSource, the binary returned is the binary generated by clBuildProgram. The bits returned can be an implementation-specific intermediate representation (a.k.a. IR) or device specific executable bits or both. The decision on which information is returned in the binary is up to the OpenCL implementation. param_value points to an array of n pointers where nis the number of devices associated with program. The buffer sizes needed to allocate the memory that these n pointers refer to can be queried using the CL_PROGRAM_BINARY_SIZES query as described in this table. 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 CL_PROGRAM_DEVICES query to get the list of devices. There is a one-toone correspondence between the array of npointers returned by CL_PROGRAM_BINARIES and array of devices returned by CL_PROGRAM_DEVICES. |
clGetProgramInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.11 and param_value is not NULL, and returns CL_INVALID_PROGRAM if program is a 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)
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 table 5.12.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.12.
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_program_buid_info | Return Type | Info. returned in param_value |
---|---|---|
CL_PROGRAM_BUILD_STATUS | cl_build_status | Returns the build status of program for a specific device as given by device. This can be one of the following: CL_BUILD_NONE. The build status returned if no build has been performed on the specified program object for device. CL_BUILD_ERROR. The build status returned if the last call to clBuildProgram on the specified program object for device generated an error. CL_BUILD_SUCCESS. The build status retrned if the last call to clBuildProgram on the specified program object for device was successful. CL_BUILD_IN_PROGRESS. The build status returned if the last call to clBuildProgram on the specified program object for device has not finished. |
CL_PROGRAM_BUILD_OPTIONS | char[] | Return the build options specified by the options argument in clBuildProgram for device. If build status of program for device is CL_BUILD_NONE, an empty string is returned. |
CL_PROGRAM_BUILD_LOG | char[] | Return the build log when clBuildProgram was called for device. |
If build status of program for device is CL_BUILD_NONE, an empty string is returned.
clGetProgramBuildInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_DEVICE if device is not in the list of devices associated with program, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.12 and param_value is not NULL, and returns CL_INVALID_PROGRAM if program is a not a valid program object.
public static cl_kernel clCreateKernel(cl_program program, java.lang.String kernel_name, int[] errcode_ret)
cl_kernel clCreateKernel (cl_program program, const char *kernel_name, cl_int *errcode_ret)
program is a program object with a successfully built executable. kernel_name is a function name in the program declared with the __kernelqualifier. errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned. 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:CL_INVALID_PROGRAM if program is not a valid program object.
CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built executable for program.
CL_INVALID_KERNEL_NAME if kernel_name is not found in program. CL_INVALID_KERNEL_DEFINITION if the function definition for __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.
CL_INVALID_VALUE if kernel_name is NULL. CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clCreateKernelsInProgram(cl_program program, int num_kernels, cl_kernel[] kernels, int[] num_kernels_ret)
cl_int clCreateKernelsInProgram (cl_program program, cl_uint num_kernels, cl_kernel *kernels, cl_uint *num_kernels_ret)
Kernel objects are not created for any __kernelfunctions in program that do not have the same function definition across all devices for which a program executable has been successfully built.
program is a program object with a successfully built executable.
num_kernels is the size of memory pointed to by kernels specified as the number of cl_kernel entries.
kernels is 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 is the number of kernels in program. If num_kernels_ret is NULL, it is ignored.
clCreateKernelsInProgram will return CL_SUCCESS if the kernel objects were successfully allocated, returns CL_INVALID_PROGRAM if program is not a valid program object, returns CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built executable for any device in program, returns CL_INVALID_VALUE if kernels is not NULL and num_kernels is less than the number of kernels in program and returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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.
public static int clRetainKernel(cl_kernel kernel)
cl_int clRetainKernel (cl_kernel kernel)
clRetainKernel returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_KERNEL if kernel is not a valid kernel object. clCreateKernel or clCreateKernelsInProgram do an implicit retain.
public static int clReleaseKernel(cl_kernel kernel)
cl_int clReleaseKernel (cl_kernel kernel)
clReleaseKernel returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_KERNEL if kernel is not a valid kernel object. 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.
public static int clSetKernelArg(cl_kernel kernel, int arg_index, long arg_size, Pointer arg_value)
cl_int clSetKernelArg (cl_kernel kernel, cl_uint arg_index, size_t arg_size, const void *arg_value)
To execute a kernel, the kernel arguments must be set.
kernel is a valid kernel object.
arg_index is 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.
For example, consider the following kernel:
__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_filterwill be 0for n, 1for m, 2for filter_weights, 3for src_imageand 4for dst_image.
arg_value is 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. For all other kernel arguments, the arg_value entry must be a pointer to the actual data to be used as argument value.
The memory object specified as argument value must be a buffer object (or NULL) if the argument is declared to be a pointer of a built-in or user defined type with the __global or __constant qualifier. 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.
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.
NOTE: 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 kernel12.
clSetKernelArg returns CL_SUCCESS if the function was executed successfully. Otherwise, it returns one of the following errors:
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.
CL_INVALID_KERNEL if kernel is not a valid kernel object.
CL_INVALID_ARG_INDEX if arg_index is not a valid argument index.
CL_INVALID_ARG_VALUE if arg_value specified is NULL for an argument that is not declared with the __local qualifier or vice-versa.
CL_INVALID_MEM_OBJECT for an argument declared to be a memory object when the specified arg_value is not a valid memory object.
CL_INVALID_SAMPLER for an argument declared to be of type sampler_t when the specified arg_value is not a valid sampler object.
CL_INVALID_ARG_SIZE if 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).
public static int clGetKernelInfo(cl_kernel kernel, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetKernelInfo (cl_kernel kernel, cl_kernel_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.13.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.13.
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_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_ COUNT13 | cl_uint | Return the kernel reference count. |
CL_KERNEL_CONTEXT | cl_context | Return the context associated with kernel. |
CL_KERNEL_PROGRAM | cl_program | Return the program object associated with kernel. |
clGetKernelInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.13 and param_value is not NULL, and returns CL_INVALID_KERNEL if kernel is a 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)
cl_int clGetKernelWorkGroupInfo (cl_kernel kernel, cl_device_id device, cl_kernel_work_group_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.14.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.14.
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_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 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_ | size_t[3] | Returns the work-group size specified |
WORK_GROUP_SIZE | by the __attribute__((reqd_work_gr oup_size(X, Y, Z)))qualifier. Refer to section 6.7.2. 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 __localaddress 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 __localaddress qualifier, is not specified, its size is assumed to be 0. |
clGetKernelWorkGroupInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_DEVICE if 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, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.14 and param_value is not NULL, and returns CL_INVALID_KERNEL if kernel is a not a valid kernel object.
public static int clWaitForEvents(int num_events, cl_event[] event_list)
cl_int clWaitForEvents (cl_uint num_events, const cl_event *event_list)
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. The events specified in event_list act as synchronization points.
clWaitForEvents returns CL_SUCCESS if the function was executed successfully. It returns CL_INVALID_VALUE if num_events is zero, returns CL_INVALID_CONTEXT if events specified in event_list do not belong to the same context, and returns CL_INVALID_EVENT if event objects specified in event_list are not valid event objects.
public static int clGetEventInfo(cl_event event, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetEventInfo (cl_event event, cl_event_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
event specifies the event 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 clGetEventInfo is described in table 5.15.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.15.
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_event_info | Return Type | Info. returned in param_value |
---|---|---|
CL_EVENT_COMMAND_ QUEUE | cl_command_ queue | Return the command-queue 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_COMMAND_TASK CL_COMMAND_NATIVE_KERNEL CL_COMMAND_READ_BUFFER CL_COMMAND_WRITE_BUFFER CL_COMMAND_COPY_BUFFER CL_COMMAND_READ_IMAGE CL_COMMAND_WRITE_IMAGE CL_COMMAND_COPY_IMAGE CL_COMMAND_COPY_BUFFER_TO_IMAGE CL_COMMAND_COPY_IMAGE_TO_BUFFER CL_COMMAND_MAP_BUFFER CL_COMMAND_MAP_IMAGE CL_COMMAND_UNMAP_MEM_OBJECT CL_COMMAND_MARKER CL_COMMAND_ACQUIRE_GL_OBJECTS CL_COMMAND_RELEASE_GL_OBJECTS |
CL_EVENT_COMMAND_EXECUTION_STATUS | cl_int | Return the execution status of the command identified by event. 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.). |
CL_EVENT_REFERENCE_ COUNT15 | cl_uint | Return the event reference count. |
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.
clGetEventInfo returns CL_SUCCESS if the function is executed successfully, returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.15 and param_value is not NULL, and returns CL_INVALID_EVENT if event is a not a valid event object.
public static int clRetainEvent(cl_event event)
cl_int clRetainEvent (cl_event event)
clRetainEvent returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_EVENT if event is not a valid event object. The OpenCL commands that return an event perform an implicit retain.
15 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.
To release an event, use the following function
public static int clReleaseEvent(cl_event event)
cl_int clReleaseEvent (cl_event event)
clReleaseEvent returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_EVENT if event is not a valid event object. 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.
public static int clGetEventProfilingInfo(cl_event event, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetEventProfilingInfo (cl_event event, cl_profiling_info param_name, size_t param_value_size, void *param_value, size_t *param_value_size_ret)
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 table 5.16.
param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in table 5.16.
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_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 commandqueue. |
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.
clGetEventProfilingInfo returns CL_SUCCESS if the function is executed successfully and the profiling information has been recorded, returns CL_PROFILING_INFO_NOT_AVAILABLE if the CL_QUEUE_PROFILING_ENABLE flag is not set for the command-queue and if the profiling information is currently not available (because the command identified by event has not completed), returns CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table 5.16 and param_value is not NULL, and returns CL_INVALID_EVENT if event is a not a valid event object.
public static int clFlush(cl_command_queue command_queue)
cl_int clFlush (cl_command_queue command_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.
clFlush returns CL_SUCCESS if the function call was executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue and returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
Any blocking commands queued in a command-queue such as clEnqueueRead{Image|Buffer} with blocking_read set to CL_TRUE, clEnqueueWrite{Image|Buffer} with blocking_write set to CL_TRUE, clEnqueueMap{Buffer|Image} with blocking_map set to CL_TRUE or clWaitForEvents perform an implicit flush of the command-queue.
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.
public static int clFinish(cl_command_queue command_queue)
cl_int clFinish (cl_command_queue command_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.
clFinish returns CL_SUCCESS if the function call was executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue and 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 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)
cl_int clEnqueueReadBuffer (cl_command_queue command_queue, cl_mem buffer, cl_bool blocking_read, size_t offset, size_t cb, void *ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
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 operation is blocking or nonblocking.
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 is the offset in bytes in the buffer object to read from.
cb is the size in bytes of data being read.
ptr is the pointer to buffer in host memory where data is to be read into.
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.
clEnqueueReadBuffer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object.
CL_INVALID_VALUE if the region being read specified by (offset, cb) is out of bounds or if ptr is a NULL value.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
NOTE:
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:
java.lang.IllegalArgumentException
- If blocking_read==false
and
the given Pointer is not a Pointer to a direct 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)
cl_int clEnqueueWriteBuffer (cl_command_queue command_queue, cl_mem buffer, cl_bool blocking_write, size_t offset, size_t cb, const void *ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
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 operation is 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 is the offset in bytes in the buffer object to write to.
cb is the size in bytes of data being written.
ptr is the pointer to buffer in host memory where data is to be written to.
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.
clEnqueueWriteBuffer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object.
CL_INVALID_VALUE if the region being written specified by (offset, cb) is out of bounds or if ptr is a NULL value.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
NOTE:
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:
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)
cl_int clEnqueueCopyBuffer (cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_buffer, size_t src_offset, size_t dst_offset, size_t cb, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
enqueues a command to copy a buffer object identified by src_buffer to another buffer object identified by dst_buffer.
command_queue refers to 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 refers to the offset where to begin copying data from src_buffer.
dst_offset refers to the offset where to begin copying data into dst_buffer.
cb refers to the size in bytes to copy.
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 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.
clEnqueueCopyBuffer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if src_buffer and dst_buffer are not valid buffer objects.
CL_INVALID_VALUE if src_offset, dst_offset, cb, src_offset + cb or dst_offset + cb require accessing elements outside the buffer memory objects.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer object and the source and destination regions overlap.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_buffer or dst_buffer.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_int clEnqueueReadImage (cl_command_queue command_queue, cl_mem image, cl_bool blocking_read, const size_t origin[3], const size_t region[3], size_t row_pitch, size_t slice_pitch, void *ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
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 operation is blocking or nonblocking.
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. the read command 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 in clEnqueueReadImage is 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 (or 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.
Calling clEnqueueReadImage to read a region of the image object 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 object being read is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:
java.lang.IllegalArgumentException
- If blocking_read==false
and
the given Pointer is not a Pointer to a direct buffer.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)
cl_int clEnqueueWriteImage (cl_command_queue command_queue, cl_mem image, cl_bool blocking_write, const size_t origin[3], const size_t region[3], size_t input_row_pitch, size_t input_slice_pitch, const void * ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
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 nonblocking.
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 in clEnqueueWriteImage is 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 (or 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.
Calling clEnqueueWriteImage to update the latest bits in a region of the image object 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 object being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:
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)
cl_int clEnqueueCopyImage (cl_command_queue command_queue, cl_mem src_image, cl_mem dst_image, const size_t src_origin[3], const size_t dst_origin[3], const size_t region[3], cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
src_image and dst_image can be 2D or 3D image objects allowing us to perform the following actions:
Copy a 2D image object to a 2D image object. Copy a 2D image object to a 2D slice of a 3D image object. Copy a 2D slice of a 3D image object to a 2D image object. Copy a 3D image object to a 3D image object. 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 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 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).
clEnqueueCopyImage returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if src_image and dst_image are not valid image objects.
CL_IMAGE_FORMAT_MISMATCH if src_image and dst_image do not use the same image format.
CL_INVALID_VALUE if the 2D or 3D rectangular region specified by 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.
CL_INVALID_VALUE if src_image is a 2D image object and origin[2] is not equal to 0 or region[2] is not equal to 1.
CL_INVALID_VALUE if dst_image is a 2D image object and dst_origin[2] is not equal to 0 or region[2] is not equal to 1.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_image or dst_image.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_MEM_COPY_OVERLAP if 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)
cl_int clEnqueueCopyImageToBuffer (cl_command_queue command_queue, cl_mem src_image, cl_mem dst_buffer, const size_t src_origin[3], const size_t region[3], size_t dst_offset, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
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 is a valid image object.
dst_buffer is 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 refers to 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 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 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:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if src_image is not a valid image object or dst_buffer is not a valid buffer object.
CL_INVALID_VALUE if the 2D or 3D rectangular region specified by 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 to a region outside dst_buffer.
CL_INVALID_VALUE if src_image is a 2D image object and src_origin[2] is not equal to 0 or region[2] is not equal to 1.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_image or dst_buffer.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
The function
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)
cl_int clEnqueueCopyBufferToImage (cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_image, size_t src_offset, const size_t dst_origin[3], const size_t region[3], cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
command_queue must be a valid command-queue. The OpenCL context associated with command_queue, src_buffer and dst_image must be the same.
src_buffer is a valid buffer object.
dst_image is a valid image object.
src_offset refers to the offset where to begin copying data from src_buffer.
dst_origin refers to 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 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 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: CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if the context associated with 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.
CL_INVALID_MEM_OBJECT if src_buffer is not a valid buffer object or dst_image is not a valid image object.
CL_INVALID_VALUE if the 2D or 3D rectangular region specified by dst_origin and dst_origin + region refer to a region outside dst_image, or if the region specified by src_offset and src_offset + src_cb refer to a region outside src_buffer.
CL_INVALID_VALUE if dst_image is a 2D image object and dst_origin[2] is not equal to 0 or region[2] is not equal to 1.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with src_buffer or dst_image.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
void * clEnqueueMapBuffer (cl_command_queue command_queue, cl_mem buffer, cl_bool blocking_map, cl_map_flags map_flags, size_t offset, size_t cb, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event, cl_int *errcode_ret)
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.
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 is a valid buffer object. The OpenCL context associated with command_queue and buffer must be the same.
offset and cb are the offset in bytes and the size of the region in the buffer object that is being mapped.
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 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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
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:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if context associated with 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.
CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object.
CL_INVALID_VALUE if region being mapped given by (offset, cb) is out of bounds or if values specified in map_flags are not valid.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MAP_FAILURE if there is a failure to map the requested region into the host address space. This error cannot occur for buffer objects created with CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
The pointer returned maps a region starting at offset and is atleast cb bytes in size. The result of a memory access outside this region is undefined.
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)
void * clEnqueueMapImage (cl_command_queue command_queue, cl_mem image, cl_bool blocking_map, cl_map_flags map_flags, const size_t origin[3], const size_t region[3], size_t *image_row_pitch, size_t *image_slice_pitch, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event, cl_int *errcode_ret)
enqueues a command to map a region in the image object given by image into the host address space and returns a pointer to this mapped region.
command_queue must be a valid command-queue.
image is 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 is 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 and 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 and 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 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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
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:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if context associated with 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.
CL_INVALID_MEM_OBJECT if image is not a valid image object.
CL_INVALID_VALUE if region being mapped given by (origin, origin+region) is out of bounds or if values specified in map_flags are not valid.
CL_INVALID_VALUE if image is a 2D image object and origin[2] is not equal to 0 or region[2] is not equal to 1.
CL_INVALID_VALUE if image_row_pitch is NULL.
CL_INVALID_VALUE if image is a 3D image object and image_slice_pitch is NULL.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_MAP_FAILURE if there is a failure to map the requested region into the host address space. This error cannot occur for image objects created with CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image.
errcode_ret returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
The pointer returned maps a 2D or 3D region starting at origin and is atleast (image_row_pitch * region[1] + region[0]) pixels in size for a 2D image, and is atleast (image_slice_pitch * region[2] + image_row_pitch * region[1] + region[0]) pixels in size for a 3D image. The result of a memory access outside this region is undefined.
If the buffer or image object is created with CL_MEM_USE_HOST_PTR set in mem_flags, the following will be true:
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)
cl_int clEnqueueUnmapMemObject (cl_command_queue command_queue, cl_mem memobj, void *mapped_ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
Reads or writes from the host using the pointer returned by clEnqueueMapBuffer or clEnqueueMapImage are considered to be complete.
command_queue must be a valid command-queue.
memobj is a valid memory object. The OpenCL context associated with command_queue and memobj must be the same.
mapped_ptr is the host address returned by a previous call to clEnqueueMapBuffer or clEnqueueMapImage for memobj.
event_wait_list and 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 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.
clEnqueueUnmapMemObject returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.
CL_INVALID_VALUE if mapped_ptr is not a valid pointer returned by clEnqueueMapBuffer or clEnqueueMapImage for memobj.
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or if 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.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_INVALID_CONTEXT if context associated with 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.
clEnqueueMapBuffer and clEnqueueMapImage increments 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 memory object being mapped.
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)
cl_int clEnqueueNDRangeKernel (cl_command_queue command_queue, cl_kernel kernel, cl_uint work_dim, const size_t *global_work_offset, const size_t *global_work_size, const size_t *local_work_size, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
command_queue is a valid command-queue. The kernel will be queued for execution on the device associated with command_queue.
kernel is a valid kernel object. The OpenCL context associated with kernel and command-queue must be the same.
work_dim is 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 three.
global_work_offset must currently be a NULL value. In a future revision of OpenCL, 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 instead of having the global IDs always start at offset (0, 0, ... 0).
global_work_size14 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].
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 4.3 and the number of workitems 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 divisable 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 (refer to section 6.7.2). 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.
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 OpenCL 1.0, the starting global ID is always (0, 0, ... 0). 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.
clEnqueueNDRangeKernel returns CL_SUCCESS if the kernel execution was successfully queued. Otherwise, it returns one of the following errors: CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built program executable available for device associated with command_queue.
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_KERNEL if kernel is not a valid kernel object.
CL_INVALID_CONTEXT if context associated with 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.
CL_INVALID_KERNEL_ARGS if the kernel argument values have not been specified.
CL_INVALID_WORK_DIMENSION if work_dim is not a valid value (i.e. a value between 1 and 3).
CL_INVALID_WORK_GROUP_SIZE if local_work_size is specified and number of workitems 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.
CL_INVALID_WORK_ITEM_SIZE if the number of work-items specified in any of 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].
CL_INVALID_GLOBAL_OFFSET if global_work_offset is not NULL.
CL_OUT_OF_RESOURCES if there is a failure to queue the execution instance of 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.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image or buffer objects specified as arguments to kernel.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_int clEnqueueTask (cl_command_queue command_queue, cl_kernel kernel, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
The kernel is executed using a single work-item.
command_queue is a valid command-queue. The kernel will be queued for execution on the device associated with command_queue.
kernel is a valid kernel object. The OpenCL context associated with kernel and command-queue must be the same.
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.
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.
clEnqueueTask returns CL_SUCCESS if the kernel execution was successfully queued. Otherwise, it returns one of the following errors:
CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built program executable available for device associated with command_queue.
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_KERNEL if kernel is not a valid kernel object.
CL_INVALID_CONTEXT if context associated with 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.
CL_INVALID_KERNEL_ARGS if the kernel argument values have not been specified.
CL_INVALID_WORK_GROUP_SIZE if a work-group size is specified for kernel using the __attribute__((reqd_work_group_size(X, Y, Z)))qualifier in program source and is not (1, 1, 1).
CL_OUT_OF_RESOURCES if there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel.
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image or buffer objects specified as arguments to kernel.
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
The function
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)
cl_int clEnqueueNativeKernel (cl_command_queue command_queue, void (*user_func)(void *) void *args, size_t cb_args, cl_uint num_mem_objects, const cl_mem *mem_list, const void **args_mem_loc, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
command_queue is 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 table 4.3.
user_func is a pointer to a host-callable user function.
args is a pointer to the args list that user_func should be called with.
cb_args is 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_memvalues) 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 is the number of buffer objects that are passed in args.
mem_list is a list of valid buffer objects, if num_mem_objects > 0. The buffer object values specified in mem_list are memory object handles (cl_memvalues) returned by clCreateBuffer or NULL.
args_mem_loc is a pointer to appropriate locations that args points to where memory object handles (cl_memvalues) are stored. Before the user function is executed, the memory object handles are replaced by pointers to global memory.
event_wait_list, num_events_in_wait_list and event are as described in clEnqueueNDRangeKernel.
clEnqueueNativeKernel returns CL_SUCCESS if the user function execution instance was successfully queued. Otherwise, it returns one of the following errors: CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue. CL_INVALID_CONTEXT if context associated with command_queue and events in event_wait_list are not the same. CL_INVALID_VALUE if user_func is NULL. CL_INVALID_VALUE if args is a NULL value and cb_args > 0, or if args is a NULL value and num_mem_objects > 0. CL_INVALID_VALUE if args is not NULL and cb_args is 0. CL_INVALID_VALUE if num_mem_objects > 0 and mem_list or args_mem_loc are NULL. CL_INVALID_VALUE if num_mem_objects = 0 and mem_list or args_mem_loc are not NULL. CL_INVALID_OPERATION if device cannot execute the native kernel. CL_INVALID_MEM_OBJECT if one or more memory objects specified in mem_list are not valid or are not buffer objects. CL_OUT_OF_RESOURCES if there is a failure to queue the execution instance of kernel on the command-queue because of insufficient resources needed to execute the kernel. CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer objects specified as arguments to kernel. CL_INVALID_EVENT_WAIT_LIST if 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. CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static int clEnqueueMarker(cl_command_queue command_queue, cl_event event)
cl_int clEnqueueMarker (cl_command_queue command_queue, cl_event *event)
The marker command returns an event which can be used by to queue a wait on this marker event i.e. wait for all commands queued before the marker command to complete.
clEnqueueMarker returns CL_SUCCESS if the function is successfully executed. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue, returns CL_INVALID_VALUE if event is a NULL value and 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 clEnqueueWaitForEvents(cl_command_queue command_queue, int num_events, cl_event[] event_list)
cl_int clEnqueueWaitForEvents (cl_command_queue command_queue, cl_uint num_events, const 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. num_events specifies the number of events given by event_list. Each event in event_list must be a valid event object returned by a previous call to clEnqueueNDRangeKernel, clEnqueueTask, clEnqueueNativeKernel, clEnqueue{Read|Write|Map}{Buffer|Image}, clEnqueueCopy{Buffer|Image}, clEnqueueCopyBufferToImage, clEnqueueCopyImageToBuffer or clEnqueueMarker. The context associated with events in event_list and command_queue must be the same.
The events specified in event_list act as synchronization points.
clEnqueueWaitForEvents returns CL_SUCCESS if the function was successfully executed. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue, returns CL_INVALID_CONTEXT if the context associated with command_queue and events in event_list are not the same, returns CL_INVALID_VALUE if num_events is zero or event_list is NULL, returns CL_INVALID_EVENT if event objects specified in event_list are not valid events and 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 clEnqueueBarrier(cl_command_queue command_queue)
cl_int clEnqueueBarrier (cl_command_queue command_queue)
The clEnqueueBarrier command ensures that all queued commands in command_queue have finished execution before the next batch of commands can begin execution. clEnqueueBarrier is a synchronization point.
clEnqueueBarrier returns CL_SUCCESS if the function was executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue and returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static cl_mem clCreateFromGLBuffer(cl_context context, long flags, int bufobj, int[] errcode_ret)
cl_mem clCreateFromGLBuffer (cl_context context, cl_mem_flags flags, GLuint bufobj, cl_int * errcode_ret)
context is a valid OpenCL context created from an OpenGL context.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags . Only CL_MEM_READ_ONLY , CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in table 5.3 can be used.
bufobj is the name of a GL buffer object. The data store of the GL buffer object must have have been previously created by calling 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 will return an appropriate error code as described below. If errcode_ret is NULL , no error code is returned.
clCreateFromGLBuffer 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:
CL_INVALID_CONTEXT if context is not a valid context or was not created from a GL context.
CL_INVALID_VALUE if values specified in flags are not valid.
CL_INVALID_GL_OBJECT if bufobj is not a GL buffer object or is a GL buffer object but does not have an existing data store.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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.
public static cl_mem clCreateFromGLTexture2D(cl_context context, long flags, int target, int miplevel, int texture, int[] errcode_ret)
cl_mem clCreateFromGLTexture2D (cl_context context, cl_mem_flags flags, GLenum texture_target, GLint miplevel, GLuint texture, cl_int * errcode_ret)
context is a valid OpenCL context created from an OpenGL context.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags . Only CL_MEM_READ_ONLY , CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in table 5.3 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.
miplevel is the mipmap level to be used.
texture is 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 tables 5.4 and 5.5 may be used to create a 2D image object.
errcode_ret will return an appropriate error code as described below. If errcode_ret is NULL , no error code is returned.
clCreateFromGLTexture2D 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 :
CL_INVALID_CONTEXT if context is not a valid context or was not created from a GL context .
CL_INVALID_VALUE if values specified in flags are not valid or if value specified in texture_target is not one of the values specified in the description of texture_target .
CL_INVALID_MIPLEVEL if miplevel is less than the value of level base (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). level base 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.
CL_INVALID_MIPLEVEL if miplevel is greather than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.
CL_INVALID_GL_OBJECT if 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.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the OpenGL texture internal format does not map to a supported OpenCL image format.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
public static cl_mem clCreateFromGLTexture3D(cl_context context, long flags, int target, int miplevel, int texture, int[] errcode_ret)
cl_mem clCreateFromGLTexture3D (cl_context context, cl_mem_flags flags, GLenum texture_target, GLint miplevel, GLuint texture, cl_int *errcode_ret)
context is a valid OpenCL context created from an OpenGL context.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags . Only CL_MEM_READ_ONLY , CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in table 5.3 can be used.
texture_target must be GL_TEXTURE_3D . 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.
miplevel is the mipmap level to be used.
texture is 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 tables 5.4 and 5.5 can be used to create the 3D image object.
errcode_ret will return an appropriate error code as described below. If errcode_ret is NULL , no error code is returned.
clCreateFromGLTexture3D 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 :
CL_INVALID_CONTEXT if context is not a valid context or was not created from a GL context .
CL_INVALID_VALUE if values specified in flags are not valid or if value specified in texture_target is not one of the values specified in the description of texture_target .
CL_INVALID_MIPLEVEL if miplevel is less than the value of level base (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). level base 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.
CL_INVALID_MIPLEVEL if miplevel is greather than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.
CL_INVALID_GL_OBJECT if 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, height or depth of the specified miplevel is zero.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the OpenGL texture internal format
does not map to a supported OpenCL image format.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
If the state of a GL texture object is modified through the GL API (e.g. 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.
public static cl_mem clCreateFromGLRenderbuffer(cl_context context, long flags, int renderbuffer, int[] errcode_ret)
cl_mem clCreateFromGLRenderbuffer (cl_context context, cl_mem_flags flags, GLuint renderbuffer, cl_int *errcode_ret)
context is a valid OpenCL context created from an OpenGL context.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags . Only CL_MEM_READ_ONLY , CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in table 5.3 can be used.
renderbuffer is 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 maps to appropriate image channel order and data type specified in tables
5.4 and 5.5 can be used to create the 2D image object.
errcode_ret will return an appropriate error code as described below. If errcode_ret is NULL , no error code is returned.
clCreateFromGLRenderbuffer 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 :
CL_INVALID_CONTEXT if context is not a valid context or was not created from a GL context .
CL_INVALID_VALUE if values specified in flags are not valid.
CL_INVALID_GL_OBJECT if renderbuffer is not a GL renderbuffer object or if the width or height of renderbuffer is zero.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the OpenGL renderbuffer internal format does not map to a supported OpenCL image format.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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.
public static int clGetGLObjectInfo(cl_mem memobj, int[] gl_object_type, int[] gl_object_name)
cl_int clGetGLObjectInfo (cl_mem memobj, 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.
clGetGLObjectInfo returns CL_SUCCESS if the call was executed successfully. It returns CL_INVALID_MEM_OBJECT if memobj is not a valid OpenCL memory object, or CL_INVALID_GL_OBJECT if there is no GL object associated with memobj .
public static int clGetGLTextureInfo(cl_mem memobj, int param_name, long param_value_size, Pointer param_value, long[] param_value_size_ret)
cl_int clGetGLTextureInfo (cl_mem memobj, cl_gl_texture_info param_name, size_t param_value_size, void * param_value, size_t * param_value_size_ret)
param_name 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 table B.2 below.
param_value is a pointer to memory where the result being queried is returned. If param_value is NULL , it is ignored.
param_value_size is used to specify the size in bytes of memory pointed to by param_value . This size must be >= size of return type as described in table B.2 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 | Info. returned in param_value i> | ||||||
---|---|---|---|---|---|---|---|---|
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 . |
clGetGLTextureInfo returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_MEM_OBJECT if memobj is not a valid OpenCL memory object, CL_INVALID_GL_OBJECT if there is no GL texture object associated with memobj , or CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in table B.2 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)
cl_int clEnqueueAcquireGLObjects (cl_command_queue command_queue, cl_uint num_objects, const cl_mem * mem_objects, cl_uint num_events_in_wait_list, const cl_event * event_wait_list, cl_event * event)
Acquire OpenCL memory objects that have been created from OpenGL objects. 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.
command_queue is 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 is the number of memory objects to be acquired in mem_objects .
mem_objects is a pointer to a list of CL memory objects that correspond to GL objects.
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.
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.
clEnqueueAcquireGLObjects 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:
CL_INVALID_VALUE if num_objects is zero and mem_objects is not a NULL value or if num_objects > 0 and mem_objects is NULL.
CL_INVALID_MEM_OBJECT if memory objects in mem_objects are not valid OpenCL memory objects.
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if context associated with command_queue was not created from an OpenGL context
CL_INVALID_GL_OBJECT if memory objects in mem_objects have not been created from a GL object(s).
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
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)
cl_int clEnqueueReleaseGLObjects (cl_command_queue command_queue, cl_uint num_objects, const cl_mem * mem_objects, cl_uint num_events_in_wait_list, const cl_event * event_wait_list, cl_event *event)
Release OpenCL memory objects that have been created from OpenGL objects. 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 .
num_objects is the number of memory objects to be released in mem_objects .
mem_objects is a pointer to a list of CL memory objects that correpond to GL objects.
event_wait_list and num_events_in_wait_list 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.
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:
CL_INVALID_VALUE if num_objects is zero and mem_objects is not a NULL value or if num_objects > 0 and mem_objects is NULL.
CL_INVALID_MEM_OBJECT if memory objects in mem_objects are not valid OpenCL memory objects.
CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
CL_INVALID_CONTEXT if context associated with command_queue was not created from an OpenGL context
CL_INVALID_GL_OBJECT if memory objects in mem_objects have not been created from a GL object(s).
CL_INVALID_EVENT_WAIT_LIST if 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.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |