Package org.lwjgl.opencl

Class CL21

  • Direct Known Subclasses:
    CL22
    public class CL21
extends CL20
    The core OpenCL 2.1 functionality.

    • Field Detail

      • 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.

      • 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).

      • 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.

      • 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.

      • 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.

      • 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.

      • 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.

      • 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.

    • Method Detail

      • 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:
        Reference Page

      • nclGetDeviceAndHostTimer

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

      • clGetDeviceAndHostTimer

        public static int clGetDeviceAndHostTimer​(long device,
                                          java.nio.LongBuffer device_timestamp,
                                          java.nio.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:
        Reference Page

      • nclGetHostTimer

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

      • clGetHostTimer

        public static int clGetHostTimer​(long device,
                                 java.nio.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:
        Reference Page

      • 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,
                                         java.nio.ByteBuffer il,
                                         @Nullable
                                         java.nio.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:
        Reference Page

      • nclCloneKernel

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

      • clCloneKernel

        public static long clCloneKernel​(long source_kernel,
                                 @Nullable
                                 java.nio.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:
        Reference Page

      • 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
                                          java.nio.ByteBuffer input_value,
                                          @Nullable
                                          java.nio.ByteBuffer param_value,
                                          @Nullable
                                          org.lwjgl.PointerBuffer param_value_size_ret)

public static int clGetKernelSubGroupInfo​(long kernel,
                                          long device,
                                          int param_name,
                                          @Nullable
                                          java.nio.ByteBuffer input_value,
                                          @Nullable
                                          org.lwjgl.PointerBuffer param_value,
                                          @Nullable
                                          org.lwjgl.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:
        Reference Page

      • 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,
                                         org.lwjgl.PointerBuffer svm_pointers,
                                         @Nullable
                                         org.lwjgl.PointerBuffer sizes,
                                         long flags,
                                         @Nullable
                                         org.lwjgl.PointerBuffer event_wait_list,
                                         @Nullable
                                         org.lwjgl.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:
        Reference Page

      • clGetDeviceAndHostTimer

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

      • clGetHostTimer

        public static int clGetHostTimer​(long device,
                                 long[] host_timestamp)
        Array version of: GetHostTimer
        See Also:
        Reference Page

      • clCreateProgramWithIL

        public static long clCreateProgramWithIL​(long context,
                                         java.nio.ByteBuffer il,
                                         @Nullable
                                         int[] errcode_ret)
        Array version of: CreateProgramWithIL
        See Also:
        Reference Page

      • clCloneKernel

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