Class CL21

Direct Known Subclasses:
CL22

public class CL21 extends CL20
The core OpenCL 2.1 functionality.
  • Field Details

    • CL_VERSION_2_1

      public static final int CL_VERSION_2_1
      OpenCL Version.
      See Also:
    • CL_PLATFORM_HOST_TIMER_RESOLUTION

      public static final int CL_PLATFORM_HOST_TIMER_RESOLUTION
      Accepted as the param_name parameter of GetPlatformInfo, returns a cl_ulong value.

      Returns the resolution of the host timer in nanoseconds as used by GetDeviceAndHostTimer.

      Support for device and host timer synchronization is required for platforms supporting OpenCL 2.1 or 2.2. This value must be 0 for devices that do not support device and host timer synchronization.

      See Also:
    • CL_DEVICE_IL_VERSION

      public static final int CL_DEVICE_IL_VERSION
      Accepted as the param_name parameter of GetDeviceInfo, returns a char[] value.

      The intermediate languages that can be supported by CreateProgramWithIL for this device. Returns a space-separated list of IL version strings of the form <IL_Prefix>_<Major_Version>.<Minor_Version>.

      For an OpenCL 2.1 or 2.2 device, SPIR-V is a required IL prefix.

      If the device does not support intermediate language programs, the value must be "" (an empty string).

      See Also:
    • CL_DEVICE_MAX_NUM_SUB_GROUPS

      public static final int CL_DEVICE_MAX_NUM_SUB_GROUPS
      Accepted as the param_name parameter of GetDeviceInfo, returns a cl_uint value.

      Maximum number of sub-groups in a workgroup that a device is capable of executing on a single compute unit, for any given kernel instance running on the device.

      The minimum value is 1 if the device supports subgroups, and must be 0 for devices that do not support subgroups. Support for subgroups is required for an OpenCL 2.1 or 2.2 device.

      See Also:
    • CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS

      public static final int CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS
      Accepted as the param_name parameter of GetDeviceInfo, returns a cl_bool value.

      Is TRUE if this device supports independent forward progress of sub-groups, FALSE otherwise.

      This query must return TRUE for devices that support the cl_khr_subgroups extension, and must return FALSE for devices that do not support subgroups.

      See Also:
    • CL_QUEUE_DEVICE_DEFAULT

      public static final int CL_QUEUE_DEVICE_DEFAULT
      Accepted as the param_name parameter of GetCommandQueueInfo, returns a cl_command_queue value.

      Return the current default command queue for the underlying device.

      See Also:
    • CL_UNORM_INT_101010_2

      public static final int CL_UNORM_INT_101010_2
      cl_channel_type
      See Also:
    • CL_PROGRAM_IL

      public static final int CL_PROGRAM_IL
      Accepted as the param_name parameter of GetProgramInfo, returns a char[] value.

      Returns the program IL for programs created with CreateProgramWithIL.

      If program is created with CreateProgramWithSource, CreateProgramWithBinary or CreateProgramWithBuiltInKernels the memory pointed to by param_value will be unchanged and param_value_size_ret will be set to 0.

      See Also:
    • CL_KERNEL_MAX_NUM_SUB_GROUPS

      public static final int CL_KERNEL_MAX_NUM_SUB_GROUPS
      Accepted as the param_name parameter of GetKernelInfo, returns a size_t value.

      This provides a mechanism for the application to query the maximum number of sub-groups that may make up each workgroup 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. The returned value may be used to compute a work-group size to enqueue the kernel with to give a round number of sub-groups for an enqueue.

      See Also:
    • CL_KERNEL_COMPILE_NUM_SUB_GROUPS

      public static final int CL_KERNEL_COMPILE_NUM_SUB_GROUPS
      Accepted as the param_name parameter of GetKernelInfo, returns a size_t value.

      Returns the number of sub-groups per workgroup specified in the kernel source or IL. If the sub-group count is not specified then 0 is returned.

      See Also:
    • CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE

      public static final int CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE
      Accepted as the param_name parameter of GetKernelSubGroupInfo, returns a size_t value.

      Returns the maximum sub-group size for this kernel. All sub-groups must be the same size, while the last subgroup in any work-group (i.e. the subgroup with the maximum index) could be the same or smaller size.

      The input_value must be an array of size_t values corresponding to the local work size parameter of the intended dispatch. The number of dimensions in the ND-range will be inferred from the value specified for input_value_size.

      See Also:
    • CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE

      public static final int CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE
      Accepted as the param_name parameter of GetKernelSubGroupInfo, returns a size_t value.

      Returns the number of sub-groups that will be present in each workgroup for a given local work size. All workgroups, apart from the last workgroup in each dimension in the presence of nonuniform work-group sizes, will have the same number of subgroups.

      The input_value must be an array of size_t values corresponding to the local work size parameter of the intended dispatch. The number of dimensions in the ND-range will be inferred from the value specified for input_value_size.

      See Also:
    • CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT

      public static final int CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT
      Accepted as the param_name parameter of GetKernelSubGroupInfo, returns a size_t[] value.

      Returns the local size that will generate the requested number of sub-groups for the kernel. The output array must be an array of size_t values corresponding to the local size parameter. Any returned workgroup will have one dimension. Other dimensions inferred from the value specified for param_value_size will be filled with the value 1. The returned value will produce an exact number of sub-groups and result in no partial groups for an executing kernel except in the case where the last work-group in a dimension has a size different from that of the other groups. If no work-group size can accommodate the requested number of sub-groups, 0 will be returned in each element of the return array.

      See Also:
  • Method Details

    • clSetDefaultDeviceCommandQueue

      public static int clSetDefaultDeviceCommandQueue(long context, long device, long command_queue)
      Replaces a default device command queue created with CreateCommandQueueWithProperties and the QUEUE_ON_DEVICE_DEFAULT flag.
      Parameters:
      context - a valid OpenCL context
      device - a OpenCL device associated with context
      command_queue - a valid command-queue for device
      Returns:
      SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
      • INVALID_CONTEXT if context is not a valid context.
      • INVALID_DEVICE if device is not a valid device or is not associated with context.
      • INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclGetDeviceAndHostTimer

      public static int nclGetDeviceAndHostTimer(long device, long device_timestamp, long host_timestamp)
      Unsafe version of: GetDeviceAndHostTimer
    • clGetDeviceAndHostTimer

      public static int clGetDeviceAndHostTimer(long device, LongBuffer device_timestamp, LongBuffer host_timestamp)
      Returns a reasonably synchronized pair of timestamps from the device timer and the host timer as seen by device. Implementations may need to execute this query with a high latency in order to provide reasonable synchronization of the timestamps. The host timestamp and device timestamp returned by this function and GetHostTimer each have an implementation defined timebase. The timestamps will always be in their respective timebases regardless of which query function is used. The timestamp returned from GetEventProfilingInfo for an event on a device and a device timestamp queried from the same device will always be in the same timebase.
      Parameters:
      device - a device returned by GetDeviceIDs
      device_timestamp - will be updated with the value of the device timer in nanoseconds. The resolution of the timer is the same as the device profiling timer returned by GetDeviceInfo and the DEVICE_PROFILING_TIMER_RESOLUTION query.
      host_timestamp - will be updated with the value of the host timer in nanoseconds at the closest possible point in time to that at which device_timestamp was returned. The resolution of the timer may be queried via GetPlatformInfo and the flag PLATFORM_HOST_TIMER_RESOLUTION.
      Returns:
      SUCCESS with a time value in host_timestamp if provided. Otherwise, it returns one of the following errors:
      • INVALID_DEVICE if device is not a valid OpenCL device.
      • INVALID_VALUE if host_timestamp or device_timestamp is NULL.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclGetHostTimer

      public static int nclGetHostTimer(long device, long host_timestamp)
      Unsafe version of: GetHostTimer
    • clGetHostTimer

      public static int clGetHostTimer(long device, LongBuffer host_timestamp)
      Returns the current value of the host clock as seen by device. This value is in the same timebase as the host_timestamp returned from GetDeviceAndHostTimer. The implementation will return with as low a latency as possible to allow a correlation with a subsequent application sampled time. The host timestamp and device timestamp returned by this function and GetDeviceAndHostTimer each have an implementation defined timebase. The timestamps will always be in their respective timebases regardless of which query function is used. The timestamp returned from GetEventProfilingInfo for an event on a device and a device timestamp queried from the same device will always be in the same timebase.
      Parameters:
      device - a device returned by GetDeviceIDs
      host_timestamp - will be updated with the value of the current timer in nanoseconds. The resolution of the timer may be queried via GetPlatformInfo and the flag PLATFORM_HOST_TIMER_RESOLUTION.
      Returns:
      SUCCESS with a time value in host_timestamp if provided. Otherwise, it returns one of the following errors:
      • INVALID_DEVICE if device is not a valid OpenCL device.
      • INVALID_VALUE if host_timestamp is NULL.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclCreateProgramWithIL

      public static long nclCreateProgramWithIL(long context, long il, long length, long errcode_ret)
      Unsafe version of: CreateProgramWithIL
      Parameters:
      length - the number of bytes in il
    • clCreateProgramWithIL

      public static long clCreateProgramWithIL(long context, ByteBuffer il, @Nullable IntBuffer errcode_ret)
      Creates a program object for a context, and loads the IL pointed to by il and with length in bytes length into the program object.
      Parameters:
      context - a valid OpenCL context
      il - a pointer to a length-byte block of memory containing SPIR-V or an implementation-defined intermediate language
      errcode_ret - will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
      Returns:
      a valid non-zero program object and errcode_ret is set to 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:
      • INVALID_CONTEXT if context is not a valid context.
      • INVALID_VALUE if il is NULL or if length is zero.
      • INVALID_VALUE if the length-byte memory pointed to by il does not contain well-formed intermediate language input that can be consumed by the OpenCL runtime.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclCloneKernel

      public static long nclCloneKernel(long source_kernel, long errcode_ret)
      Unsafe version of: CloneKernel
    • clCloneKernel

      public static long clCloneKernel(long source_kernel, @Nullable IntBuffer errcode_ret)
      Makes a shallow copy of the kernel object, its arguments and any information passed to the kernel object using SetKernelExecInfo. If the kernel object was ready to be enqueued before copying it, the clone of the kernel object is ready to enqueue.

      The returned kernel object is an exact copy of source_kernel, with one caveat: the reference count on the returned kernel object is set as if it had been returned by CreateKernel. The reference count of source_kernel will not be changed.

      The resulting kernel will be in the same state as if CreateKernel is called to create the resultant kernel with the same arguments as those used to create source_kernel, the latest call to SetKernelArg or SetKernelArgSVMPointer for each argument index applied to kernel and the last call to SetKernelExecInfo for each value of the param name parameter are applied to the new kernel object.

      All arguments of the new kernel object must be intact and it may be correctly used in the same situations as kernel except those that assume a pre-existing reference count. Setting arguments on the new kernel object will not affect source_kernel except insofar as the argument points to a shared underlying entity and in that situation behavior is as if two kernel objects had been created and the same argument applied to each. Only the data stored in the kernel object is copied; data referenced by the kernel's arguments are not copied. For example, if a buffer or pointer argument is set on a kernel object, the pointer is copied but the underlying memory allocation is not.

      Parameters:
      source_kernel - a valid cl_kernel object that will be copied. source_kernel will not be modified in any way by this function.
      errcode_ret - will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
      Returns:
      a valid non-zero kernel object and errcode_ret is set to SUCCESS if the kernel is successfully copied. Otherwise it returns a NULL value with one of the following error values returned in errcode_ret:
      • INVALID_KERNEL if source_kernel is not a valid kernel object.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclGetKernelSubGroupInfo

      public static int nclGetKernelSubGroupInfo(long kernel, long device, int param_name, long input_value_size, long input_value, long param_value_size, long param_value, long param_value_size_ret)
      Unsafe version of: GetKernelSubGroupInfo
      Parameters:
      input_value_size - the size in bytes of memory pointed to by input_value
      param_value_size - the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type. If param_value is NULL, it is ignored.
    • clGetKernelSubGroupInfo

      public static int clGetKernelSubGroupInfo(long kernel, long device, int param_name, @Nullable ByteBuffer input_value, @Nullable ByteBuffer param_value, @Nullable PointerBuffer param_value_size_ret)
      Returns information about the kernel object.
      Parameters:
      kernel - the kernel object being queried
      device - 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 - the information to query. One of:
      KERNEL_MAX_NUM_SUB_GROUPSKERNEL_COMPILE_NUM_SUB_GROUPS
      KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGEKERNEL_SUB_GROUP_COUNT_FOR_NDRANGE
      KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT
      input_value - a pointer to memory where the appropriate parameterization of the query is passed from. If input_value is NULL, it is ignored.
      param_value - a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
      param_value_size_ret - the actual size in bytes of data being queried by param_value. If NULL, it is ignored.
      Returns:
      SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
      • 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.
      • INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value is < size of return type and param_value is not NULL.
      • INVALID_VALUE if param_name is KERNEL_SUB_GROUP_SIZE_FOR_NDRANGE and the size in bytes specified by input_value_size is not valid or if input_value is NULL.
      • INVALID_KERNEL if kernel is not a valid kernel object.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • clGetKernelSubGroupInfo

      public static int clGetKernelSubGroupInfo(long kernel, long device, int param_name, @Nullable ByteBuffer input_value, @Nullable PointerBuffer param_value, @Nullable PointerBuffer param_value_size_ret)
      Returns information about the kernel object.
      Parameters:
      kernel - the kernel object being queried
      device - 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 - the information to query. One of:
      KERNEL_MAX_NUM_SUB_GROUPSKERNEL_COMPILE_NUM_SUB_GROUPS
      KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGEKERNEL_SUB_GROUP_COUNT_FOR_NDRANGE
      KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT
      input_value - a pointer to memory where the appropriate parameterization of the query is passed from. If input_value is NULL, it is ignored.
      param_value - a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.
      param_value_size_ret - the actual size in bytes of data being queried by param_value. If NULL, it is ignored.
      Returns:
      SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
      • 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.
      • INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value is < size of return type and param_value is not NULL.
      • INVALID_VALUE if param_name is KERNEL_SUB_GROUP_SIZE_FOR_NDRANGE and the size in bytes specified by input_value_size is not valid or if input_value is NULL.
      • INVALID_KERNEL if kernel is not a valid kernel object.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • nclEnqueueSVMMigrateMem

      public static int nclEnqueueSVMMigrateMem(long command_queue, int num_svm_pointers, long svm_pointers, long sizes, long flags, int num_events_in_wait_list, long event_wait_list, long event)
      Unsafe version of: EnqueueSVMMigrateMem
      Parameters:
      num_svm_pointers - the number of pointers in the specified svm_pointers array, and the number of sizes in the sizes array, if sizes is not NULL.
      num_events_in_wait_list - the number of events in event_wait_list
    • clEnqueueSVMMigrateMem

      public static int clEnqueueSVMMigrateMem(long command_queue, PointerBuffer svm_pointers, @Nullable PointerBuffer sizes, long flags, @Nullable PointerBuffer event_wait_list, @Nullable PointerBuffer event)
      Enqueues a command to indicate which device a set of ranges of SVM allocations should be associated with. Once the event returned by clEnqueueSVMMigrateMem has become COMPLETE, the ranges specified by svm pointers and sizes have been successfully migrated to the device associated with command queue.

      The user is responsible for managing the event dependencies associated with this command in order to avoid overlapping access to SVM allocations. Improperly specified event dependencies passed to clEnqueueSVMMigrateMem could result in undefined results.

      Parameters:
      command_queue - a valid host command queue. The specified set of allocation ranges will be migrated to the OpenCL device associated with command_queue.
      svm_pointers - a pointer to an array of pointers. Each pointer in this array must be within an allocation produced by a call to SVMAlloc.
      sizes - an array of sizes. The pair svm_pointers[i] and sizes[i] together define the starting address and number of bytes in a range to be migrated. sizes may be NULL indicating that every allocation containing any svm_pointer[i] is to be migrated. Also, if sizes[i] is zero, then the entire allocation containing svm_pointer[i] is migrated.
      flags - a bit-field that is used to specify migration options
      event_wait_list - a list of 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. 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. If the event_wait_list and the event arguments are not NULL, the event argument should not refer to an element of the event_wait_list array.
      Returns:
      SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
      • INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
      • INVALID_CONTEXT if the context associated with command_queue and events in event_wait_list are not the same
      • INVALID_VALUE if num_svm_pointers is zero or svm_pointers is NULL.
      • INVALID_VALUE if sizes[i] is non-zero range [svm_pointers[i], svm_pointers[i]+sizes[i]) is not contained within an existing SVMAlloc allocation.
      • 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.
      • OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      See Also:
    • clGetDeviceAndHostTimer

      public static int clGetDeviceAndHostTimer(long device, long[] device_timestamp, long[] host_timestamp)
      Array version of: GetDeviceAndHostTimer
      See Also:
    • clGetHostTimer

      public static int clGetHostTimer(long device, long[] host_timestamp)
      Array version of: GetHostTimer
      See Also:
    • clCreateProgramWithIL

      public static long clCreateProgramWithIL(long context, ByteBuffer il, @Nullable int[] errcode_ret)
      Array version of: CreateProgramWithIL
      See Also:
    • clCloneKernel

      public static long clCloneKernel(long source_kernel, @Nullable int[] errcode_ret)
      Array version of: CloneKernel
      See Also: