Package org.jocl

Class CL


  • public final class CL
    extends java.lang.Object
    JOCL - Java bindings for OpenCL.

    The documentation of the OpenCL methods has been extracted from the OpenCL registry at https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/ and is copyright (c) 2007-2010 by The Khronos Group Inc.
    • Constructor Detail

      • CL

        private CL()
        Private constructor to prevent instantiation
    • Method Detail

      • loadNativeLibrary

        static void loadNativeLibrary()
        Load the native library, if it was not loaded yet
      • initNativeLibrary

        static boolean initNativeLibrary​(java.lang.String fullName)
        Initialize the native library. That is, initialize the function pointers which will be used to call the OpenCL functions.
        Parameters:
        fullName - The full, platform specific name of the OpenCL implementation library (e.g. "OpenCL.dll")
        Returns:
        Whether the initialization succeeded.
      • setExceptionsEnabled

        public static void setExceptionsEnabled​(boolean enabled)
        Enables or disables exceptions. By default, the methods of this class only return the error code from the underlying OpenCL function. If exceptions are enabled, a CLException with a detailed error message will be thrown if a method is about to return a result code that is not CL_SUCCESS
        Parameters:
        enabled - Whether exceptions are enabled
      • checkResult

        private static int checkResult​(int result)
        If the given result is different to CL_SUCCESS and exceptions have been enabled, this method will throw a CLException with an error message that corresponds to the given result code. Otherwise, the given result is simply returned.
        Parameters:
        result - The result to check
        Returns:
        The result that was given as the parameter
        Throws:
        CLException - If exceptions have been enabled and the given result code is not CL_SUCCESS
      • stringFor_errorCode

        public static java.lang.String stringFor_errorCode​(int n)
        Returns the String identifying the given error code
        Parameters:
        n - The error code
        Returns:
        The String identifying the given error code
      • stringFor_cl_platform_info

        public static java.lang.String stringFor_cl_platform_info​(int n)
        Returns the String identifying the given cl_platform_info
        Parameters:
        n - A cl_platform_info value
        Returns:
        The String for the given cl_platform_info
      • stringFor_cl_device_info

        public static java.lang.String stringFor_cl_device_info​(int n)
        Returns the String identifying the given cl_device_info
        Parameters:
        n - A cl_device_info value
        Returns:
        The String for the given cl_device_info
      • stringFor_cl_device_mem_cache_type

        public static java.lang.String stringFor_cl_device_mem_cache_type​(int n)
        Returns the String identifying the given cl_device_mem_cache_type
        Parameters:
        n - A cl_device_mem_cache_type value
        Returns:
        The String for the given cl_device_mem_cache_type
      • stringFor_cl_device_local_mem_type

        public static java.lang.String stringFor_cl_device_local_mem_type​(int n)
        Returns the String identifying the given cl_device_local_mem_type
        Parameters:
        n - A cl_device_local_mem_type value
        Returns:
        The String for the given cl_device_local_mem_type
      • stringFor_cl_context_info

        public static java.lang.String stringFor_cl_context_info​(int n)
        Returns the String identifying the given cl_context_info
        Parameters:
        n - A cl_context_info value
        Returns:
        The String for the given cl_context_info
      • stringFor_cl_context_properties

        public static java.lang.String stringFor_cl_context_properties​(int n)
        Returns the String identifying the given cl_context_properties
        Parameters:
        n - A cl_context_properties value
        Returns:
        The String for the given cl_context_properties
      • stringFor_cl_device_partition_property

        public static java.lang.String stringFor_cl_device_partition_property​(int n)
        Returns the String identifying the given cl_device_partition_property
        Parameters:
        n - A cl_device_partition_property value
        Returns:
        The String for the given cl_device_partition_property
      • stringFor_cl_command_queue_info

        public static java.lang.String stringFor_cl_command_queue_info​(int n)
        Returns the String identifying the given cl_command_queue_info
        Parameters:
        n - A cl_command_queue_info value
        Returns:
        The String for the given cl_command_queue_info
      • stringFor_cl_channel_order

        public static java.lang.String stringFor_cl_channel_order​(int n)
        Returns the String identifying the given cl_channel_order
        Parameters:
        n - A cl_channel_order value
        Returns:
        The String for the given cl_channel_order
      • stringFor_cl_channel_type

        public static java.lang.String stringFor_cl_channel_type​(int n)
        Returns the String identifying the given cl_channel_type
        Parameters:
        n - A cl_channel_type value
        Returns:
        The String for the given cl_channel_type
      • stringFor_cl_mem_object_type

        public static java.lang.String stringFor_cl_mem_object_type​(int n)
        Returns the String identifying the given cl_mem_object_type
        Parameters:
        n - A cl_mem_object_type value
        Returns:
        The String for the given cl_mem_object_type
      • stringFor_cl_mem_info

        public static java.lang.String stringFor_cl_mem_info​(int n)
        Returns the String identifying the given cl_mem_info
        Parameters:
        n - A cl_mem_info value
        Returns:
        The String for the given cl_mem_info
      • stringFor_cl_image_info

        public static java.lang.String stringFor_cl_image_info​(int n)
        Returns the String identifying the given cl_image_info
        Parameters:
        n - A cl_image_info value
        Returns:
        The String for the given cl_image_info
      • stringFor_cl_pipe_info

        public static java.lang.String stringFor_cl_pipe_info​(int n)
        Returns the String identifying the given cl_pipe_info
        Parameters:
        n - A cl_pipe_info value
        Returns:
        The String for the given cl_pipe_info
      • stringFor_cl_addressing_mode

        public static java.lang.String stringFor_cl_addressing_mode​(int n)
        Returns the String identifying the given cl_addressing_mode
        Parameters:
        n - A cl_addressing_mode value
        Returns:
        The String for the given cl_addressing_mode
      • stringFor_cl_filter_mode

        public static java.lang.String stringFor_cl_filter_mode​(int n)
        Returns the String identifying the given cl_filter_mode
        Parameters:
        n - A cl_filter_mode value
        Returns:
        The String for the given cl_filter_mode
      • stringFor_cl_sampler_info

        public static java.lang.String stringFor_cl_sampler_info​(int n)
        Returns the String identifying the given cl_sampler_info
        Parameters:
        n - A cl_sampler_info value
        Returns:
        The String for the given cl_sampler_info
      • stringFor_cl_program_info

        public static java.lang.String stringFor_cl_program_info​(int n)
        Returns the String identifying the given cl_program_info
        Parameters:
        n - A cl_program_info value
        Returns:
        The String for the given cl_program_info
      • stringFor_cl_program_build_info

        public static java.lang.String stringFor_cl_program_build_info​(int n)
        Returns the String identifying the given cl_program_build_info
        Parameters:
        n - A cl_program_build_info value
        Returns:
        The String for the given cl_program_build_info
      • stringFor_cl_program_binary_type

        public static java.lang.String stringFor_cl_program_binary_type​(int n)
        Returns the String identifying the given cl_program_binary_type
        Parameters:
        n - A cl_program_binary_type value
        Returns:
        The String for the given cl_program_binary_type
      • stringFor_cl_build_status

        public static java.lang.String stringFor_cl_build_status​(int n)
        Returns the String identifying the given cl_build_status
        Parameters:
        n - A cl_build_status value
        Returns:
        The String for the given cl_build_status
      • stringFor_cl_kernel_info

        public static java.lang.String stringFor_cl_kernel_info​(int n)
        Returns the String identifying the given cl_kernel_info
        Parameters:
        n - A cl_kernel_info value
        Returns:
        The String for the given cl_kernel_info
      • stringFor_cl_kernel_arg_info

        public static java.lang.String stringFor_cl_kernel_arg_info​(int n)
        Returns the String identifying the given cl_kernel_arg_info
        Parameters:
        n - A cl_kernel_arg_info value
        Returns:
        The String for the given cl_kernel_arg_info
      • stringFor_cl_kernel_arg_address_qualifier

        public static java.lang.String stringFor_cl_kernel_arg_address_qualifier​(int n)
        Returns the String identifying the given cl_kernel_arg_address_qualifier
        Parameters:
        n - A cl_kernel_arg_address_qualifier value
        Returns:
        The String for the given cl_kernel_arg_address_qualifier
      • stringFor_cl_kernel_arg_access_qualifier

        public static java.lang.String stringFor_cl_kernel_arg_access_qualifier​(int n)
        Returns the String identifying the given cl_kernel_arg_access_qualifier
        Parameters:
        n - A cl_kernel_arg_access_qualifier value
        Returns:
        The String for the given cl_kernel_arg_access_qualifier
      • stringFor_cl_kernel_work_group_info

        public static java.lang.String stringFor_cl_kernel_work_group_info​(int n)
        Returns the String identifying the given cl_kernel_work_group_info
        Parameters:
        n - A cl_kernel_work_group_info value
        Returns:
        The String for the given cl_kernel_work_group_info
      • stringFor_cl_kernel_exec_info

        public static java.lang.String stringFor_cl_kernel_exec_info​(int n)
        Returns the String identifying the given cl_kernel_exec_info
        Parameters:
        n - A cl_kernel_exec_info value
        Returns:
        The String for the given cl_kernel_exec_info
      • stringFor_cl_event_info

        public static java.lang.String stringFor_cl_event_info​(int n)
        Returns the String identifying the given cl_event_info
        Parameters:
        n - A cl_event_info value
        Returns:
        The String for the given cl_event_info
      • stringFor_cl_command_type

        public static java.lang.String stringFor_cl_command_type​(int n)
        Returns the String identifying the given cl_command_type
        Parameters:
        n - A cl_command_type value
        Returns:
        The String for the given cl_command_type
      • stringFor_command_execution_status

        public static java.lang.String stringFor_command_execution_status​(int n)
        Returns the command execution String identifying the given command_execution_status
        Parameters:
        n - A command_execution_status value
        Returns:
        The String for the given command_execution_status
      • stringFor_cl_profiling_info

        public static java.lang.String stringFor_cl_profiling_info​(int n)
        Returns the String identifying the given cl_profiling_info
        Parameters:
        n - A cl_profiling_info value
        Returns:
        The String for the given cl_profiling_info
      • stringFor_cl_gl_object_type

        public static java.lang.String stringFor_cl_gl_object_type​(int n)
        Returns the String identifying the given cl_gl_object_type
        Parameters:
        n - A cl_gl_object_type value
        Returns:
        The String for the given cl_gl_object_type
      • stringFor_cl_gl_texture_info

        public static java.lang.String stringFor_cl_gl_texture_info​(int n)
        Returns the String identifying the given cl_gl_texture_info
        Parameters:
        n - A cl_gl_texture_info value
        Returns:
        The String for the given cl_gl_texture_info
      • stringFor_cl_khr_gl_sharing

        public static java.lang.String stringFor_cl_khr_gl_sharing​(int n)
        Returns the String identifying the given cl_khr_gl_sharing
        Parameters:
        n - A cl_khr_gl_sharing value
        Returns:
        The String for the given cl_khr_gl_sharing
      • stringFor_cl_gl_platform_info

        public static java.lang.String stringFor_cl_gl_platform_info​(int n)
        Returns the string identifying the given cl_gl_platform_info
        Parameters:
        n - A cl_gl_platform_info value
        Returns:
        The String for the given cl_gl_platform_info
      • stringFor_cl_device_type

        public static java.lang.String stringFor_cl_device_type​(long n)
        Returns the string describing the given cl_device_type - bitfield
        Parameters:
        n - The cl_device_type - bitfield
        Returns:
        The string describing the cl_device_type - bitfield
      • stringFor_cl_device_address_info

        public static java.lang.String stringFor_cl_device_address_info​(long n)
        Returns the string describing the given cl_device_address_info - bitfield
        Parameters:
        n - The cl_device_address_info - bitfield
        Returns:
        The string describing the cl_device_address_info - bitfield
      • stringFor_cl_device_fp_config

        public static java.lang.String stringFor_cl_device_fp_config​(long n)
        Returns the string describing the given cl_device_fp_config - bitfield
        Parameters:
        n - The cl_device_fp_config - bitfield
        Returns:
        The string describing the cl_device_fp_config - bitfield
      • stringFor_cl_device_exec_capabilities

        public static java.lang.String stringFor_cl_device_exec_capabilities​(long n)
        Returns the string describing the given cl_device_exec_capabilities - bitfield
        Parameters:
        n - The cl_device_exec_capabilities - bitfield
        Returns:
        The string describing the cl_device_exec_capabilities - bitfield
      • stringFor_cl_command_queue_properties

        public static java.lang.String stringFor_cl_command_queue_properties​(long n)
        Returns the string describing the given cl_command_queue_properties - bitfield
        Parameters:
        n - The cl_command_queue_properties - bitfield
        Returns:
        The string describing the cl_command_queue_properties - bitfield
      • stringFor_cl_device_affinity_domain

        public static java.lang.String stringFor_cl_device_affinity_domain​(long n)
        Returns the string describing the given cl_device_affinity_domain - bitfield
        Parameters:
        n - The cl_device_affinity_domain - bitfield
        Returns:
        The string describing the cl_device_affinity_domain - bitfield
      • stringFor_cl_device_svm_capabilities

        public static java.lang.String stringFor_cl_device_svm_capabilities​(long n)
        Returns the string describing the given cl_device_svm_capabilities - bitfield
        Parameters:
        n - The cl_device_svm_capabilities - bitfield
        Returns:
        The string describing the cl_device_svm_capabilities - bitfield
      • stringFor_cl_mem_flags

        public static java.lang.String stringFor_cl_mem_flags​(long n)
        Returns the string describing the given cl_mem_flags - bitfield
        Parameters:
        n - The cl_mem_flags - bitfield
        Returns:
        The string describing the cl_mem_flags - bitfield
      • stringFor_cl_mem_migration_flags

        public static java.lang.String stringFor_cl_mem_migration_flags​(long n)
        Returns the string describing the given cl_mem_migration_flags - bitfield
        Parameters:
        n - The cl_mem_migration_flags - bitfield
        Returns:
        The string describing the cl_mem_migration_flags - bitfield
      • stringFor_cl_map_flags

        public static java.lang.String stringFor_cl_map_flags​(long n)
        Returns the string describing the given cl_map_flags - bitfield
        Parameters:
        n - The cl_map_flags - bitfield
        Returns:
        The string describing the cl_map_flags - bitfield
      • stringFor_cl_kernel_arg_type_qualifer

        public static java.lang.String stringFor_cl_kernel_arg_type_qualifer​(long n)
        Returns the string describing the given cl_kernel_arg_type_qualifer - bitfield
        Parameters:
        n - The cl_kernel_arg_type_qualifer - bitfield
        Returns:
        The string describing the cl_kernel_arg_type_qualifer - bitfield
      • setLogLevel

        public static void setLogLevel​(CL.LogLevel logLevel)
        Set the specified log level for the library.

        Currently supported log levels:

        LOG_QUIET: Never print anything

        LOG_ERROR: Print error messages

        LOG_TRACE: Print a trace of all native function calls

        Parameters:
        logLevel - The log level to use.
      • setLogLevelNative

        private static void setLogLevelNative​(int logLevel)
      • scheduleReferenceRelease

        private static void scheduleReferenceRelease​(cl_event event,
                                                     java.lang.Object object,
                                                     boolean doRetainEvent)
        Keep a reference to the given object, to prevent it from being garbage collected, until waiting for the given event on a separate thread has completed.
        Parameters:
        event - The event to wait for
        object - The object to which a reference should be kept
        doRetainEvent - Whether the event was given to the calling method from outside. If this is true, then the event has to be retained (in order to increase its reference count), so that it will not become invalid when the user calls clReleaseEvent on it before the waiting operation started.
      • clGetPlatformIDs

        public static int clGetPlatformIDs​(int num_entries,
                                           cl_platform_id[] platforms,
                                           int[] num_platforms)

        Obtain the list of platforms available.

        cl_int clGetPlatformIDs( cl_uint num_entries,
        cl_platform_id *platforms,
        cl_uint *num_platforms)

        Parameters

        num_entries

        The number of cl_platform_id entries that can be added to platforms. If platforms is not NULL, the num_entries must be greater than zero.

        platforms

        Returns a list of OpenCL platforms found. The cl_platform_id values returned in platforms can be used to identify a specific OpenCL platform. If platforms argument is NULL, this argument is ignored. The number of OpenCL platforms returned is the mininum of the value specified by num_entries or the number of OpenCL platforms available.

        num_platforms

        Returns the number of OpenCL platforms available. If num_platforms is NULL, this argument is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. If the cl_khr_icd extension is enabled, clGetPlatformIDs returns CL_SUCCESS if the function is executed successfully and there are a non zero number of platforms available.

        Otherwise it returns one of the following errors:

        • CL_INVALID_VALUE if num_entries is equal to zero and platforms is not NULL or if both num_platforms and platforms are NULL.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_PLATFORM_NOT_FOUND_KHR if the cl_khr_icd extension is enabled and no platforms are found.

        Also see

        clGetPlatformInfo, clGetDeviceInfo, Cardinality Diagram

      • clGetPlatformIDsNative

        private static int clGetPlatformIDsNative​(int num_entries,
                                                  cl_platform_id[] platforms,
                                                  int[] num_platforms)
      • clGetPlatformInfo

        public static int clGetPlatformInfo​(cl_platform_id platform,
                                            int param_name,
                                            long param_value_size,
                                            Pointer param_value,
                                            long[] param_value_size_ret)

        Get specific information about the OpenCL platform.

        cl_int clGetPlatformInfo( cl_platform_idplatform,
        cl_platform_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        platform

        The platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.

        param_name

        An enumeration constant that identifies the platform information being queried. It can be one of the following values as specified in the table below.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size in bytes must be greater than or equal to size of return type specified in the table below.

        param_value

        A pointer to memory location where appropriate values for a given param_value will be returned. Possible param_value values returned are listed in the table below. If param_value is NULL, it is ignored.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored

        OpenCL Platform Queries

        cl_platform_info Return Type Description
        CL_PLATFORM_PROFILE char[]

        OpenCL profile string. Returns the profile name supported by the implementation. The profile name returned can be one of the following strings:

        FULL_PROFILE - if the implementation supports the OpenCL specification (functionality defined as part of the core specification and does not require any extensions to be supported).

        EMBEDDED_PROFILE - if the implementation supports the OpenCL embedded profile. The embedded profile is defined to be a subset for each version of OpenCL.

        CL_PLATFORM_VERSION char[]

        OpenCL version string. Returns the OpenCL version supported by the implementation. This version string has the following format:

        OpenCL<space><major_version.minor_version><space><platform-specific information>

        The major_version.minor_version value returned will be 1.1.

        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.

        Notes

        A null terminated string is returned by OpenCL query function calls if the return type of the information being queried is a char[].

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:

        • CL_INVALID_PLATFORM if platform is not a valid platform.
        • CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is less than size of return type and param_value is not a NULL value.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        The OpenCL specification does not describe the order of precedence for error codes returned by API calls.

      • clGetPlatformInfoNative

        private static int clGetPlatformInfoNative​(cl_platform_id platform,
                                                   int param_name,
                                                   long param_value_size,
                                                   Pointer param_value,
                                                   long[] param_value_size_ret)
      • clGetDeviceIDs

        public static int clGetDeviceIDs​(cl_platform_id platform,
                                         long device_type,
                                         int num_entries,
                                         cl_device_id[] devices,
                                         int[] num_devices)

        Obtain the list of devices available on a platform.

        cl_int clGetDeviceIDs( cl_platform_idplatform,
        cl_device_typedevice_type,
        cl_uintnum_entries,
        cl_device_id*devices,
        cl_uint*num_devices)

        Parameters

        platform

        Refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.

        device_type

        A bitfield that identifies the type of OpenCL device. The device_type can be used to query specific OpenCL devices or all OpenCL devices available. The valid values for device_type are specified in the following table.

        cl_device_type Description
        CL_DEVICE_TYPE_CPU An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU.
        CL_DEVICE_TYPE_GPU An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX.
        CL_DEVICE_TYPE_ACCELERATOR Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe.
        CL_DEVICE_TYPE_DEFAULT The default OpenCL device in the system.
        CL_DEVICE_TYPE_ALL All OpenCL devices available in the system.
        num_entries

        The number of cl_device entries that can be added to devices. If devices is not NULL, the num_entries must be greater than zero.

        devices

        A list of OpenCL devices found. The cl_device_id values returned in devices can be used to identify a specific OpenCL device. If devices argument is NULL, this argument is ignored. The number of OpenCL devices returned is the mininum of the value specified by num_entries or the number of OpenCL devices whose type matches device_type.

        num_devices

        The number of OpenCL devices available that match device_type. If num_devices is NULL, this argument is ignored.

        Notes

        clGetDeviceIDs may return all or a subset of the actual physical devices present in the platform and that match device_type.

        The application can query specific capabilities of the OpenCL device(s) returned by clGetDeviceIDs. This can be used by the application to determine which device(s) to use.

        Errors

        clGetDeviceIDs returns CL_SUCCESS if the function is executed successfully. Otherwise it returns one of the following:

        • CL_INVALID_PLATFORM if platform is not a valid platform.
        • CL_INVALID_DEVICE_TYPE if device_type is not a valid value.
        • CL_INVALID_VALUE if num_entries is equal to zero and devices is not NULL or if both num_devices and devices are NULL.
        • CL_DEVICE_NOT_FOUND if no OpenCL devices that matched device_type were found.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetDeviceIDsNative

        private static int clGetDeviceIDsNative​(cl_platform_id platform,
                                                long device_type,
                                                int num_entries,
                                                cl_device_id[] devices,
                                                int[] num_devices)
      • clGetDeviceInfo

        public static int clGetDeviceInfo​(cl_device_id device,
                                          int param_name,
                                          long param_value_size,
                                          Pointer param_value,
                                          long[] param_value_size_ret)

        Get information about an OpenCL device.

        cl_int clGetDeviceInfo( cl_device_iddevice,
        cl_device_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        device

        Refers to the device returned by clGetDeviceIDs.

        param_name

        An enumeration constant that identifies the device information being queried. It can be one of the values as specified in the table below.

        param_value

        A pointer to memory location where appropriate values for a given param_name as specified in the table below will be returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size in bytes must be greater than or equal to size of return type specified in the table below.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored

        cl_device_info Description
        CL_DEVICE_ADDRESS_BITS

        Return type: cl_uint

        The default compute device address space size specified as an unsigned integer value in bits. Currently supported values are 32 or 64 bits.

        CL_DEVICE_AVAILABLE

        Return type: cl_bool

        Is CL_TRUE if the device is available and CL_FALSE if the device is not available.

        CL_DEVICE_COMPILER_AVAILABLE

        Return type: cl_bool

        Is CL_FALSE if the implementation does not have a compiler available to compile the program source. Is CL_TRUE if the compiler is available. This can be CL_FALSE for the embedded platform profile only.

        CL_DEVICE_DOUBLE_FP_CONFIG

        Return type: cl_device_fp_config

        Describes the OPTIONAL double precision floating-point capability of the OpenCL device. This is a bit-field that describes one or more of the following values:

        • CL_FP_DENORM - denorms are supported.
        • CL_FP_INF_NAN - INF and 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.
        • CP_FP_FMA - IEEE754-2008 fused multiply-add is supported.

        The mandated minimum double precision floating-point capability is CL_FP_FMA | CL_FP_ROUND_TO_NEAREST | CL_FP_ROUND_TO_ZERO | CL_FP_ROUND_TO_INF | CL_FP_INF_NAN | CL_FP_DENORM.

        CL_DEVICE_ENDIAN_LITTLE

        Return type: cl_bool

        Is CL_TRUE if the OpenCL device is a little endian device and CL_FALSE otherwise.

        CL_DEVICE_ERROR_CORRECTION_SUPPORT

        Return type: cl_bool

        Is CL_TRUE if the device implements error correction for all accesses to compute device memory (global and constant). Is CL_FALSE if the device does not implement such error correction.

        CL_DEVICE_EXECUTION_CAPABILITIES

        Return type: cl_device_exec_capabilities

        Describes the execution capabilities of the device. This is a bit-field that describes one or more of the following values:

        CL_EXEC_KERNEL - The OpenCL device can execute OpenCL kernels.

        CL_EXEC_NATIVE_KERNEL - The OpenCL device can execute native kernels.

        The mandated minimum capability is CL_EXEC_KERNEL.

        CL_DEVICE_EXTENSIONS

        Return type: char[]

        Returns a space-separated list of extension names (the extension names themselves do not contain any spaces). The list of extension names returned currently can include one or more of the following approved extension names:

        cl_khr_fp64
        cl_khr_int64_base_atomics
        cl_khr_int64_extended_atomics
        cl_khr_fp16
        cl_khr_gl_sharing
        cl_khr_gl_event
        cl_khr_d3d10_sharing

        CL_DEVICE_GLOBAL_MEM_CACHE_SIZE

        Return type: cl_ulong

        Size of global memory cache in bytes.

        CL_DEVICE_GLOBAL_MEM_CACHE_TYPE

        Return type: cl_device_mem_cache_type

        Type of global memory cache supported. Valid values are: CL_NONE, CL_READ_ONLY_CACHE, and CL_READ_WRITE_CACHE.

        CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE

        Return type: cl_uint

        Size of global memory cache line in bytes.

        CL_DEVICE_GLOBAL_MEM_SIZE

        Return type: cl_ulong

        Size of global device memory in bytes.

        CL_DEVICE_HALF_FP_CONFIG

        Return type: cl_device_fp_config

        Describes the OPTIONAL half precision floating-point capability of the OpenCL device. This is a bit-field that describes one or more of the following values:

        • CL_FP_DENORM - denorms are supported.
        • CL_FP_INF_NAN - INF and 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.
        • CP_FP_FMA - IEEE754-2008 fused multiply-add is supported.
        • CL_FP_SOFT_FLOAT - Basic floating-point operations (such as addition, subtraction, multiplication) are implemented in software.

        The required minimum half precision floating-point capability as implemented by this extension is CL_FP_ROUND_TO_ZERO or CL_FP_ROUND_TO_INF | CL_FP_INF_NAN.

        CL_DEVICE_HOST_UNIFIED_MEMORY

        Return type: cl_bool

        Is CL_TRUE if the device and the host have a unified memory subsystem and is CL_FALSE otherwise.

        CL_DEVICE_IMAGE_SUPPORT

        Return type: cl_bool

        Is CL_TRUE if images are supported by the OpenCL device and CL_FALSE otherwise.

        CL_DEVICE_IMAGE2D_MAX_HEIGHT

        Return type: size_t

        Max height of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_IMAGE2D_MAX_WIDTH

        Return type: size_t

        Max width of 2D image in pixels. The minimum value is 8192 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_IMAGE3D_MAX_DEPTH

        Return type: size_t

        Max depth of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_IMAGE3D_MAX_HEIGHT

        Return type: size_t

        Max height of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_IMAGE3D_MAX_WIDTH

        Return type: size_t

        Max width of 3D image in pixels. The minimum value is 2048 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_LOCAL_MEM_SIZE

        Return type: cl_ulong

        Size of local memory arena in bytes. The minimum value is 32 KB.

        CL_DEVICE_LOCAL_MEM_TYPE

        Return type: cl_device_local_mem_type

        Type of local memory supported. This can be set to CL_LOCAL implying dedicated local memory storage such as SRAM, or CL_GLOBAL.

        CL_DEVICE_MAX_CLOCK_FREQUENCY

        Return type: cl_uint

        Maximum configured clock frequency of the device in MHz.

        CL_DEVICE_MAX_COMPUTE_UNITS

        Return type: cl_uint

        The number of parallel compute cores on the OpenCL device. The minimum value is 1.

        CL_DEVICE_MAX_CONSTANT_ARGS

        Return type: cl_uint

        Max number of arguments declared with the __constant qualifier in a kernel. The minimum value is 8.

        CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE

        Return type: cl_ulong

        Max size in bytes of a constant buffer allocation. The minimum value is 64 KB.

        CL_DEVICE_MAX_MEM_ALLOC_SIZE

        Return type: cl_ulong

        Max size of memory object allocation in bytes. The minimum value is max (1/4th of CL_DEVICE_GLOBAL_MEM_SIZE, 128*1024*1024)

        CL_DEVICE_MAX_PARAMETER_SIZE

        Return type: size_t

        Max size in bytes of the arguments that can be passed to a kernel. The minimum value is 1024. For this minimum value, only a maximum of 128 arguments can be passed to a kernel.

        CL_DEVICE_MAX_READ_IMAGE_ARGS

        Return type: cl_uint

        Max number of simultaneous image objects that can be read by a kernel. The minimum value is 128 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_MAX_SAMPLERS

        Return type: cl_uint

        Maximum number of samplers that can be used in a kernel. The minimum value is 16 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE. (Also see sampler_t.)

        CL_DEVICE_MAX_WORK_GROUP_SIZE

        Return type: size_t

        Maximum number of work-items in a work-group executing a kernel using the data parallel execution model. (Refer to clEnqueueNDRangeKernel). The minimum value is 1.

        CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS

        Return type: cl_uint

        Maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model. (Refer to clEnqueueNDRangeKernel). The minimum value is 3.

        CL_DEVICE_MAX_WORK_ITEM_SIZES

        Return type: size_t[]

        Maximum number of work-items that can be specified in each dimension of the work-group to clEnqueueNDRangeKernel.

        Returns n size_t entries, where n is the value returned by the query for CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS. The minimum value is (1, 1, 1).

        CL_DEVICE_MAX_WRITE_IMAGE_ARGS

        Return type: cl_uint

        Max number of simultaneous image objects that can be written to by a kernel. The minimum value is 8 if CL_DEVICE_IMAGE_SUPPORT is CL_TRUE.

        CL_DEVICE_MEM_BASE_ADDR_ALIGN

        Return type: cl_uint

        Describes the alignment in bits of the base address of any allocated memory object.

        CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE

        Return type: cl_uint

        The smallest alignment in bytes which can be used for any data type.

        CL_DEVICE_NAME

        Return type: char[]

        Device name string.

        CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR

        CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT

        CL_DEVICE_NATIVE_VECTOR_WIDTH_INT

        CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG

        CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT

        CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE

        CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF

        Return type: cl_uint

        Returns the native ISA vector width. The vector width is defined as the number of scalar elements that can be stored in the vector.

        If the cl_khr_fp64 extension is not supported, CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE must return 0.

        If the cl_khr_fp16 extension is not supported, CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF must return 0.

        CL_DEVICE_OPENCL_C_VERSION

        Return type: char[]

        OpenCL C version string. Returns the highest OpenCL C version supported by the compiler for this device. This version string has the following format:

        OpenCL<space>C<space><major_version.minor_version><space><vendor-specific information>

        The major_version.minor_version value must be 1.1 if CL_DEVICE_VERSION is OpenCL 1.1.

        The major_version.minor_version value returned can be 1.0 or 1.1 if CL_DEVICE_VERSION is OpenCL 1.0. If OpenCL C 1.1 is returned, this implies that the language feature set defined in section 6 of the OpenCL 1.1 specification is supported by the OpenCL 1.0 device.

        CL_DEVICE_PLATFORM

        Return type: cl_platform_id

        The platform associated with this device.

        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_DEVICE_PREFERRED_VECTOR_WIDTH_HALF

        Return type: cl_uint

        Preferred native vector width size for built-in scalar types that can be put into vectors. The vector width is defined as the number of scalar elements that can be stored in the vector.

        If the cl_khr_fp64 extension is not supported, CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE must return 0.

        If the cl_khr_fp16 extension is not supported, CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF must return 0.

        CL_DEVICE_PROFILE

        Return type: char[]

        OpenCL profile string. Returns the profile name supported by the device (see note). The profile name returned can be one of the following strings:

        FULL_PROFILE - if the device supports the OpenCL specification (functionality defined as part of the core specification and does not require any extensions to be supported).

        EMBEDDED_PROFILE - if the device supports the OpenCL embedded profile.

        CL_DEVICE_PROFILING_TIMER_RESOLUTION

        Return type: size_t

        Describes the resolution of device timer. This is measured in nanoseconds.

        CL_DEVICE_QUEUE_PROPERTIES

        Return type: cl_command_queue_properties

        Describes the command-queue properties supported by the device. This is a bit-field that describes one or more of the following values:

        CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE

        CL_QUEUE_PROFILING_ENABLE

        These properties are described in the table for clCreateCommandQueue. The mandated minimum capability is CL_QUEUE_PROFILING_ENABLE.

        CL_DEVICE_SINGLE_FP_CONFIG

        Return type: cl_device_fp_config

        Describes single precision floating-point capability of the device. This is a bit-field that describes one or more of the following values:

        CL_FP_DENORM - denorms are supported

        CL_FP_INF_NAN - INF and quiet NaNs are supported

        CL_FP_ROUND_TO_NEAREST - round to nearest even rounding mode supported

        CL_FP_ROUND_TO_ZERO - round to zero rounding mode supported

        CL_FP_ROUND_TO_INF - round to +ve and -ve infinity rounding modes supported

        CL_FP_FMA - IEEE754-2008 fused multiply-add is supported

        CL_FP_SOFT_FLOAT - Basic floating-point operations (such as addition, subtraction, multiplication) are implemented in software.

        The mandated minimum floating-point capability is CL_FP_ROUND_TO_NEAREST | CL_FP_INF_NAN.

        CL_DEVICE_TYPE

        Return type: cl_device_type

        The OpenCL device type. Currently supported values are one of or a combination of: CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, CL_DEVICE_TYPE_ACCELERATOR, or CL_DEVICE_TYPE_DEFAULT.

        CL_DEVICE_VENDOR

        Return type: char[]

        Vendor name string.

        CL_DEVICE_VENDOR_ID

        Return type: cl_uint

        A unique device vendor identifier. An example of a unique device identifier could be the PCIe ID.

        CL_DEVICE_VERSION

        Return type: char[]

        OpenCL version string. Returns the OpenCL version supported by the device. This version string has the following format:

        OpenCL<space><major_version.minor_version><space><vendor-specific information>

        The major_version.minor_version value returned will be 1.1.

        CL_DRIVER_VERSION

        Return type: char[]

        OpenCL software driver version string in the form major_number.minor_number.

        Notes

        CL_DEVICE_PROFILE: The platform profile returns the profile that is implemented by the OpenCL framework. If the platform profile returned is FULL_PROFILE, the OpenCL framework will support devices that are FULL_PROFILE and may also support devices that are EMBEDDED_PROFILE. The compiler must be available for all devices i.e. CL_DEVICE_COMPILER_AVAILABLE is CL_TRUE. If the platform profile returned is EMBEDDED_PROFILE, then devices that are only EMBEDDED_PROFILE are supported.

        Errors

        clGetDeviceInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:

        • CL_INVALID_DEVICE if device is not valid.
        • CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is less than size of return type as shown in the table above and param_value is not a NULL value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetDeviceInfoNative

        private static int clGetDeviceInfoNative​(cl_device_id device,
                                                 int param_name,
                                                 long param_value_size,
                                                 Pointer param_value,
                                                 long[] param_value_size_ret)
      • clCreateSubDevices

        public static int clCreateSubDevices​(cl_device_id in_device,
                                             cl_device_partition_property properties,
                                             int num_devices,
                                             cl_device_id[] out_devices,
                                             int[] num_devices_ret)

        Creates an array of sub-devices that each reference a non-intersecting set of compute units within in_device.

        cl_int clCreateSubDevices ( cl_device_id in_device ,
        const cl_device_partition_property *properties ,
        cl_uint num_devices ,
        cl_device_id *out_devices ,
        cl_uint *num_devices_ret )

        Parameters

        in_device

        The device to be partitioned.

        properties

        Specifies how in_device is to be partition described by a partition name and its corresponding value. Each partition name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported partitioning schemes is described in the table below. Only one of the listed partitioning schemes can be specified in properties.

        cl_device_partition_ property enum (Partition value) Description
        CL_DEVICE_PARTITION_EQUALLY (unsigned int) Split the aggregate device into as many smaller aggregate devices as can be created, each containing n compute units. The value n is passed as the value accompanying this property. If n does not divide evenly into CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS, then the remaining compute units are not used.
        CL_DEVICE_PARTITION_BY_COUNTS (unsigned int) This property is followed by a CL_DEVICE_PARTITION_BY_COUNTS_LIST_END terminated list of compute unit counts. For each nonzero count m in the list, a sub-device is created with m compute units in it. CL_DEVICE_PARTITION_BY_COUNTS_LIST_END is defined to be 0.

        The number of non-zero count entries in the list may not exceed CL_DEVICE_PARTITION_MAX_SUB_DEVICES.

        The total number of compute units specified may not exceed CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS.

        CL_DEVICE_PARTITION_BY_- AFFINITY_DOMAIN (cl_device_affinity_domain) Split the device into smaller aggregate devices containing one or more compute units that all share part of a cache hierarchy. The value accompanying this property may be drawn from the following list:

        CL_DEVICE_AFFINITY_DOMAIN_NUMA - Split the device into sub-devices comprised of compute units that share a NUMA node.

        CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE - Split the device into sub-devices comprised of compute units that share a level 4 data cache.

        CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE - Split the device into sub-devices comprised of compute units that share a level 3 data cache.

        CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE - Split the device into sub-devices comprised of compute units that share a level 2 data cache.

        CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE - Split the device into sub-devices comprised of compute units that share a level 1 data cache.

        CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE - Split the device along the next partitionable affinity domain. The implementation shall find the first level along which the device or sub-device may be further subdivided in the order NUMA, L4, L3, L2, L1, and partition the device into sub-devices comprised of compute units that share memory subsystems at this level.

        The user may determine what happened by calling clGetDeviceInfo (CL_DEVICE_PARTITION_TYPE) on the sub-devices.

        num_devices

        Size of memory pointed to by out_devices specified as the number of cl_device_id entries.

        out_devices

        The buffer where the OpenCL sub-devices will be returned. If out_devices is NULL, this argument is ignored. If out_devices is not NULL, num_devices must be greater than or equal to the number of sub-devices that device may be partitioned into according to the partitioning scheme specified in properties.

        num_devices_ret

        Returns the number of sub-devices that device may be partitioned into according to the partitioning scheme specified in properties. If num_devices_ret is NULL, it is ignored.

        Notes

        Creates an array of sub-devices that each reference a non-intersecting set of compute units within in_device, according to a partition scheme given by properties. The output sub-devices may be used in every way that the root (or parent) device can be used, including creating contexts, building programs, further calls to clCreateSubDevices and creating command-queues. When a command-queue is created against a sub-device, the commands enqueued on the queue are executed only on the sub-device.

        Errors

        Returns CL_SUCCESS if the partition is created successfully. Otherwise, it returns a null value with the following error values returned in errcode_ret:

        • CL_INVALID_DEVICE if in_device is not valid.
        • CL_INVALID_VALUE if values specified in properties are not valid or if values specified in properties are valid but not supported by the device.
        • CL_INVALID_VALUE if out_devices is not NULL and num_devices is less than the number of sub-devices created by the partition scheme.
        • CL_DEVICE_PARTITION_FAILED if the partition name is supported by the implementation but in_device could not be further partitioned.
        • CL_INVALID_DEVICE_PARTITION_COUNT if the partition name specified in properties is CL_DEVICE_PARTITION_BY_COUNTS and the number of sub-devices requested exceeds CL_DEVICE_PARTITION_MAX_SUB_DEVICES or the total number of compute units requested exceeds CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS for in_device, or the number of compute units requested for one or more sub-devices is less than zero or the number of sub-devices requested exceeds CL_DEVICE_PARTITION_MAX_COMPUTE_UNITS for in_device.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Example

        A few examples that describe how to specify partition properties in properties argument to clCreateSubDevices are given below.

        To partition a device containing 16 compute units into two sub-devices, each containing 8 compute units, pass the following in properties:

        { CL_DEVICE_PARTITION_EQUALLY, 8, 0 }

        To partition a device with four compute units into two sub-devices with one sub-device containing 3 compute units and the other sub-device 1 compute unit, pass the following in properties argument:

        { CL_DEVICE_PARTITION_BY_COUNTS, 3, 1, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END, 0 }

        To split a device along the outermost cache line (if any), pass the following in properties argument:

        { CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN, CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE, 0 }
        Since:
        OpenCL 1.2
      • clRetainDevice

        public static int clRetainDevice​(cl_device_id device)

        Increments the devices reference count.

        cl_int clRetainDevice ( cl_device_id device )

        Notes

        Increments the device reference count if device is a valid sub-device created by a call to clCreateSubDevices. If device is a root level device i.e. a cl_device_id returned by clGetDeviceIDs, the device reference count remains unchanged.

        Errors

        Returns CL_SUCCESS if the function is executed successfully or the device is a root-level device. Otherwise, it returns one of the following errors:

        • CL_INVALID_DEVICE if device is not a valid sub-device created by a call to clCreateSubDevices.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clRetainDeviceNative

        private static int clRetainDeviceNative​(cl_device_id device)
      • clReleaseDevice

        public static int clReleaseDevice​(cl_device_id device)

        Decrements the device reference count.

        cl_int clReleaseDevice ( cl_device_iddevice)

        Notes

        Decrements the device reference count if device is a valid sub-device created by a call to clCreateSubDevices. If device is a root level device i.e. a cl_device_id returned by clGetDeviceIDs, the device reference count remains unchanged.

        After the device reference count becomes zero and all the objects attached to device (such as command-queues) are released, the device object is deleted.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_DEVICE if device is not a valid sub-device created by a call to clCreateSubDevices.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clReleaseDeviceNative

        private static int clReleaseDeviceNative​(cl_device_id device)
      • clCreateContext

        public static cl_context clCreateContext​(cl_context_properties properties,
                                                 int num_devices,
                                                 cl_device_id[] devices,
                                                 CreateContextFunction pfn_notify,
                                                 java.lang.Object user_data,
                                                 int[] errcode_ret)

        Creates an OpenCL context.

        cl_context clCreateContext( const cl_context_properties*properties,
        cl_uintnum_devices,
        const cl_device_id*devices,
        (voidCL_CALLBACK *pfn_notify) (

        constchar*errinfo,
        constvoid*private_info,size_tcb,
        void*user_data

        ),
        void*user_data,
        cl_int*errcode_ret)

        Description

        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.

        Parameters

        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. properties can be NULL in which case the platform that is selected is implementation-defined. The list of supported properties is described in the table below.

        If the extension cl_khr_d3d10_sharing is enabled, then if a property is not specified in properties, then its default value is used (it is said to be specified implicitly). If properties is NULL or empty (points to a list whose first value is zero), all attributes take on their default value.

        If the extension cl_khr_gl_sharing is enabled, then properties points to an attribute list, which is a array of ordered <attribute name, value> pairs terminated with zero. If an attribute is not specified in properties, then its default value is used (it is said to be specified implicitly). If properties is NULL or empty (points to a list whose first value is zero), all attributes take on their default values..

        cl_context_properties enum Property value Description
        CL_CONTEXT_PLATFORM cl_platform_id Specifies the platform to use.
        CL_CONTEXT_D3D10_DEVICE_KHR ID3D10Device* If the cl_khr_d3d10_sharing extension is enabled, specifies the ID3D10Device* to use for Direct3D 10 interoperability. The default value is NULL.

        CL_GL_CONTEXT_KHR
        CL_EGL_DISPLAY_KHR
        CL_GLX_DISPLAY_KHR
        CL_WGL_HDC_KHR
        CL_CGL_SHAREGROUP_KHR

        Available if the cl_khr_gl_sharing extension is enabled.
        num_devices

        The number of devices specified in the devices argument.

        devices

        A pointer to a list of unique devices returned by clGetDeviceIDs for a platform. Duplicate devices specified in devices are ignored.

        pfn_notify

        A callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors that occur in this context. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. If pfn_notify is NULL, no callback function is registered. The parameters to this callback function are:

        errinfo is a pointer to an error string.

        private_info and cb represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.

        user_data is a pointer to user supplied data.

        NOTE: There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined.

        user_data

        Passed as the user_data argument when pfn_notify is called. user_data can be NULL.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        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.

        Errors

        clCreateContext returns a valid non-zero context and errcode_ret is set to CL_SUCCESS if the context is created successfully. Otherwise, it returns NULL value with the following error values returned in errcode_ret:

        • 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. (If the extension cl_khr_gl_sharing is enabled, then see error "CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR" below.)
        • CL_INVALID_PROPERTY if context property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. However if the extension cl_khr_gl_sharing is enabled, then CL_INVALID_PROPERTY is returned if an attribute name other than those listed in the table for properties above is specified in properties.
        • CL_INVALID_VALUE if devices is NULL; if num_devices is equal to zero; or if pfn_notify is NULL but user_data is not NULL.
        • CL_INVALID_DEVICE if devices contains an invalid device.
        • CL_INVALID_OPERATION if Direct3D 10 interoperability is specified by setting CL_INVALID_D3D10_DEVICE_KHR to a non-NULL value, and interoperability with another graphics API is also specified (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_DEVICE_NOT_AVAILABLE if a device in devices is currently not available even though the device was returned by clGetDeviceIDs.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_INVALID_D3D10_DEVICE_KHR if the Direct3D 10 device specified for interoperability is not compatible with the devices against which the context is to be created (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_INVALID_D3D10_DEVICE_KHR if the value of the property CL_CONTEXT_D3D10_DEVICE_KHR is non-NULL and does not specify a valid Direct3D 10 device with which the cl_device_ids against which this context is to be created may interoperate (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR when an invalid OpenGL context or share group object handle is specified in properties (only if the cl_khr_gl_sharing extension is enabled).
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if the cl_khr_gl_sharing extension is enabled and if a context was specified by any of the following means:
          • Context specified for an EGL-based OpenGL ES or OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_EGL_DISPLAY_KHR.
          • Context was specified for a GLX-based OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR.
          • Context was specified for a WGL-based OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR.
          and any of the following conditions hold:
          • The specified display and context attributes do not identify a valid OpenGL or OpenGL ES context.
          • The specified context does not support buffer and renderbuffer objects.
          • The specified context is not compatible with the OpenCL context being created (for example, it exists in a physically distinct address space, such as another hardware device, or does not support sharing data with OpenCL due to implementation restrictions).
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a share group was specified for a CGL-based OpenGL implementation by setting the attribute CL_CGL_SHAREGROUP_KHR, and the specified share group does not identify a valid CGL share group object (only if the cl_khr_gl_sharing extension is enabled).
      • clCreateContextFromType

        public static cl_context clCreateContextFromType​(cl_context_properties properties,
                                                         long device_type,
                                                         CreateContextFunction pfn_notify,
                                                         java.lang.Object user_data,
                                                         int[] errcode_ret)

        Create an OpenCL context from a device type that identifies the specific device(s) to use.

        cl_context clCreateContextFromType ( const cl_context_properties *properties,
        cl_device_type device_type,
        void (CL_CALLBACK *pfn_notify) (const char *errinfo,
        const void *private_info,
        size_t cb,
        void *user_data),
        void *user_data,
        cl_int *errcode_ret)

        Parameters

        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. properties can be NULL in which case the platform that is selected is implementation-defined. The list of supported properties is described in the table below.

        cl_context_properties enum Property value Description
        CL_CONTEXT_PLATFORM cl_platform_id Specifies the platform to use.
        CL_CONTEXT_D3D10_DEVICE_KHR ID3D10Device* If the cl_khr_d3d10_sharing extension is enabled, specifies the ID3D10Device* to use for Direct3D 10 interoperability. The default value is NULL.

        CL_GL_CONTEXT_KHR
        CL_EGL_DISPLAY_KHR
        CL_GLX_DISPLAY_KHR
        CL_WGL_HDC_KHR
        CL_CGL_SHAREGROUP_KHR

        Available if the cl_khr_gl_sharing extension is enabled.
        device_type

        A bit-field that identifies the type of device and is described in the table below.

        cl_device_type Description
        CL_DEVICE_TYPE_CPU An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU.
        CL_DEVICE_TYPE_GPU An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX.
        CL_DEVICE_TYPE_ACCELERATOR Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe.
        CL_DEVICE_TYPE_DEFAULT The default OpenCL device in the system.
        CL_DEVICE_TYPE_ALL All OpenCL devices available in the system.
        pfn_notify

        A callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors that occur in this context. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. If pfn_notify is NULL, no callback function is registered. The parameters to this callback function are:

        errinfo is a pointer to an error string.

        private_info and cb represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.

        user_data is a pointer to user supplied data.

        There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined.

        user_data

        Passed as the user_data argument when pfn_notify is called. user_data can be NULL.

        errcode_ret

        Return an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        clCreateContextFromType may return all or a subset of the actual physical devices present in the platform and that match device_type.

        clCreateContextFromType and clCreateContext perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application. However, it is possible that the application may delete the context without informing the library. Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context being used by a library no longer being valid.

        Errors

        clCreateContextFromType returns a valid non-zero context and errcode_ret is set to CL_SUCCESS if the context is created successfully. Otherwise, it returns a NULL value with the following error vlaues returned in errcode_ret:

        • 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. (If the extension cl_khr_gl_sharing is enabled, then see error "CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR" below.)
        • CL_INVALID_PROPERTY if context property name in properties is not a supported property name, or if the value specified for a supported property name is not valid, or if the same property name is specified more than once.
        • 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_INVALID_OPERATION if Direct3D 10 interoperability is specified by setting CL_INVALID_D3D10_DEVICE_KHR to a non-NULL value, and interoperability with another graphics API is also specified (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_DEVICE_NOT_AVAILABLE if no devices that match device_type and property values specified in properties are currently available.
        • CL_DEVICE_NOT_FOUND if no devices that match device_type and property values specified in properties were found.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_INVALID_D3D10_DEVICE_KHR if the Direct3D 10 device specified for interoperability is not compatible with the devices against which the context is to be created (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_INVALID_D3D10_DEVICE_KHR if the value of the property CL_CONTEXT_D3D10_DEVICE_KHR is non-NULL and does not specify a valid Direct3D 10 device with which the cl_device_ids against which this context is to be created may interoperate (if the cl_khr_d3d10_sharing extension is enabled).
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR when an invalid OpenGL context or share group object handle is specified in properties if the cl_khr_gl_sharing extension is enabled.
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if the cl_khr_gl_sharing extension is enabled and if a context was specified by any of the following means:
          • Context specified for an EGL-based OpenGL ES or OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_EGL_DISPLAY_KHR.
          • Context was specified for a GLX-based OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR.
          • Context was specified for a WGL-based OpenGL implementation by setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR.
          and any of the following conditions hold:
          • The specified display and context attributes do not identify a valid OpenGL or OpenGL ES context.
          • The specified context does not support buffer and renderbuffer objects.
          • The specified context is not compatible with the OpenCL context being created (for example, it exists in a physically distinct address space, such as another hardware device, or does not support sharing data with OpenCL due to implementation restrictions).
        • CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a share group was specified for a CGL-based OpenGL implementation by setting the attribute CL_CGL_SHAREGROUP_KHR, and the specified share group does not identify a valid CGL share group object (only if the cl_khr_gl_sharing extension is enabled).

        Example

        Example goes here - it will be set in "code" type with white space preserved.
      • clRetainContext

        public static int clRetainContext​(cl_context context)

        Increment the context reference count.

        cl_int clRetainContext ( cl_contextcontext)

        Parameters

        context

        The context to retain.

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following values:

        • CL_INVALID_CONTEXT if context is not a valid OpenCL context.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainContextNative

        private static int clRetainContextNative​(cl_context context)
      • clReleaseContext

        public static int clReleaseContext​(cl_context context)

        Decrement the context reference count.

        cl_int clReleaseContext ( cl_contextcontext)

        Parameters

        context

        The context to release.

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following values:

        • CL_INVALID_CONTEXT if context is not a valid OpenCL context.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clReleaseContextNative

        private static int clReleaseContextNative​(cl_context context)
      • clGetContextInfo

        public static int clGetContextInfo​(cl_context context,
                                           int param_name,
                                           long param_value_size,
                                           Pointer param_value,
                                           long[] param_value_size_ret)

        Query information about a context.

        cl_int clGetContextInfo ( cl_contextcontext,
        cl_context_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t *param_value_size_ret)

        Parameters

        context

        Specifies the OpenCL context being queried.

        param_name

        An enumeration constant that specifies the information to query. The valid values for param_name are:

        cl_context_info Return Type Information returned in param_value
        CL_CONTEXT_REFERENCE_COUNT cl_uint Return the context reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
        CL_CONTEXT_NUM_DEVICES cl_uint Return the number of devices in context.
        CL_CONTEXT_DEVICES cl_device_id[] Return the list of devices in context.
        CL_CONTEXT_PROPERTIES cl_context_properties[] Return the properties argument specified in clCreateContext or clCreateContextFromType.

        If the properties argument specified in clCreateContext or clCreateContextFromType used to create context is not NULL, the implementation must return the values specified in the properties argument.

        If the properties argument specified in clCreateContext or clCreateContextFromType used to create context is NULL, the implementation may return either a param_value_size_ret of 0, i.e. there is no context property value to be returned or can return a context property value of 0 (where 0 is used to terminate the context properties list) in the memory that param_value points to.

        CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR cl_bool If the cl_khr_d3d10_sharing extension is enabled, returns CL_TRUE if Direct3D 10 resources created as shared by setting MiscFlags to include D3D10_RESOURCE_MISC_SHARED will perform if aster when shared with OpenCL, compared with resources which have not set this flag. Otherwise returns CL_FALSE.
        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table above.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_CONTEXT if context is not a valid context.
        • CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is less than size of return type as specified in the table above and param_value is not a NULL value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetContextInfoNative

        private static int clGetContextInfoNative​(cl_context context,
                                                  int param_name,
                                                  long param_value_size,
                                                  Pointer param_value,
                                                  long[] param_value_size_ret)
      • clCreateCommandQueue

        public static cl_command_queue clCreateCommandQueue​(cl_context context,
                                                            cl_device_id device,
                                                            long properties,
                                                            int[] errcode_ret)

        Create a command-queue on a specific device.

        cl_command_queue clCreateCommandQueue( cl_contextcontext,
        cl_device_iddevice,
        cl_command_queue_propertiesproperties,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        device

        Must be a device associated with context. It can either be in the list of devices specified when context is created using clCreateContext or have the same device type as the device type specified when the context is created using clCreateContextFromType.

        properties

        Specifies a list of properties for the command-queue. This is a bit-field. Only command-queue properties specified in the table below can be set in properties; otherwise the value specified in properties is considered to be not valid.

        Command-Queue Properties Description
        CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE Determines whether the commands queued in the command-queue are executed in-order or out-of-order. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order.
        CL_QUEUE_PROFILING_ENABLE Enable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled. See clGetEventProfilingInfo for more information.
        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        The OpenCL functions that are submitted to a command-queue are enqueued in the order the calls are made but can be configured to execute in-order or out-of-order. The properties argument in clCreateCommandQueue can be used to specify the execution order.

        If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a command-queue is not set, the commands enqueued to a command-queue execute in order. For example, if an application calls clEnqueueNDRangeKernel to execute kernel A followed by a clEnqueueNDRangeKernel to execute kernel B, the application can assume that kernel A finishes first and then kernel B is executed. If the memory objects output by kernel A are inputs to kernel B then kernel B will see the correct data in memory objects produced by execution of kernel A. If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a commandqueue is set, then there is no guarantee that kernel A will finish before kernel B starts execution.

        Applications can configure the commands enqueued to a command-queue to execute out-of-order by setting the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of the command-queue. This can be specified when the command-queue is created. In out-of-order execution mode there is no guarantee that the enqueued commands will finish execution in the order they were queued. As there is no guarantee that kernels will be executed in order, that is based on when the clEnqueueNDRangeKernel calls are made within a command-queue, it is therefore possible that an earlier clEnqueueNDRangeKernel call to execute kernel A identified by event A may execute and/or finish later than a clEnqueueNDRangeKernel call to execute kernel B which was called by the application at a later point in time. To guarantee a specific order of execution of kernels, a wait on a particular event (in this case event A) can be used. The wait for event A can be specified in the event_wait_list argument to clEnqueueNDRangeKernel for kernel B.

        In addition, a wait for events or a barrier command can be enqueued to the command-queue. The wait for events command ensures that previously enqueued commands identified by the list of events to wait for have finished before the next batch of commands is executed. The barrier command ensures that all previously enqueued commands in a command-queue have finished execution before the next batch of commands is executed.

        Similarly, commands to read, write, copy or map memory objects that are enqueued after clEnqueueNDRangeKernel, clEnqueueTask or clEnqueueNativeKernel commands are not guaranteed to wait for kernels scheduled for execution to have completed (if the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property is set). To ensure correct ordering of commands, the event object returned by clEnqueueNDRangeKernel, clEnqueueTask or clEnqueueNativeKernel can be used to enqueue a wait for event or a barrier command can be enqueued that must complete before reads or writes to the memory object(s) occur.

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateCommandQueueWithProperties

        public static cl_command_queue clCreateCommandQueueWithProperties​(cl_context context,
                                                                          cl_device_id device,
                                                                          cl_queue_properties properties,
                                                                          int[] errcode_ret)

        Create a host or device command-queue on a specific device.

        cl_command_queue clCreateCommandQueueWithProperties( cl_context context,
        cl_device_id device,
        const cl_queue_properties *properties,
        cl_int *errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        device

        Must be a device associated with context. It can either be in the list of devices specified when context is created using clCreateContext or have the same device type as the device type specified when the context is created using clCreateContextFromType.

        properties

        Specifies a list of properties for the command-queue 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 below. If a supported property and its value is not specified in properties, its default value will be used. properties can be NULL in which case the default values for supported command-queue properties will be used.

        Queue Properties Property Value Description
        CL_QUEUE_PROPERTIES cl_command_queue_- properties

        This is a bitfield and can be set to a combination of the following values:

        CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE - Determines whether the commands queued in the command-queue are executed in-order or out-of-order. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order.

        CL_QUEUE_PROFILING_ENABLE - Enable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled.

        CL_QUEUE_ON_DEVICE - Indicates that this is a device queue. If CL_QUEUE_ON_DEVICE is set, CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE must also be set. Only out-of-order device queues are supported.

        CL_QUEUE_ON_DEVICE_DEFAULT - indicates that this is the default device queue. This can only be used with CL_QUEUE_ON_DEVICE. The application should create the default device queue if needed. There can only be one default device queue per context. clCreateCommandQueueWithProperties with CL_QUEUE_PROPERTIES set to CL_QUEUE_ON_DEVICE | CL_QUEUE_ON_DEVICE_DEFAULT will return the default device queue thas already been created and increment its retain count by 1.

        If CL_QUEUE_PROPERTIES is not specified an in-order host command queue is created for the specified device.

        CL_QUEUE_SIZE cl_uint

        Specifies the size of the device queue in bytes.

        This can only be specified if CL_QUEUE_ON_DEVICE is set in CL_QUEUE_PROPERTIES. This must be a value ≤ CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE.

        For best performance, this should be ≤ CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE.

        If CL_QUEUE_SIZE is not specified, the device queue is created with CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE as the size of the queue.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        OpenCL objects such as memory, program and kernel objects are created using a context. Operations on these objects are performed using a command-queue. The command-queue can be used to queue a set of operations (referred to as commands) in order. Having multiple command-queues allows applications to queue multiple independent commands without requiring synchronization. Note that this should work as long as these objects are not being shared. Sharing of objects across multiple command-queues will require the application to perform appropriate synchronization. This is described in Appendix A of the specification.

        Out-of-order Execution of Kernels and Memory Object Commands

        The OpenCL functions that are submitted to a command-queue are enqueued in the order the calls are made but can be configured to execute in-order or out-of-order. The properties argument in clCreateCommandQueueWithProperties can be used to specify the execution order.

        If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a command-queue is not set, the commands enqueued to a command-queue execute in order. For example, if an application calls clEnqueueNDRangeKernel to execute kernel A followed by a clEnqueueNDRangeKernel to execute kernel B, the application can assume that kernel A finishes first and then kernel B is executed. If the memory objects output by kernel A are inputs to kernel B then kernel B will see the correct data in memory objects produced by execution of kernel A. If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of a command-queue is set, then there is no guarantee that kernel A will finish before kernel B starts execution.

        Applications can configure the commands enqueued to a command-queue to execute out-of-order by setting the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property of the command-queue. This can be specified when the command-queue is created. In out-of-order execution mode there is no guarantee that the enqueued commands will finish execution in the order they were queued. As there is no guarantee that kernels will be executed in order, i.e. based on when the clEnqueueNDRangeKernel calls are made within a command-queue, it is therefore possible that an earlier clEnqueueNDRangeKernel call to execute kernel A identified by event A may execute and/or finish later than a clEnqueueNDRangeKernel call to execute kernel B which was called by the application at a later point in time. To guarantee a specific order of execution of kernels, a wait on a particular event (in this case event A) can be used. The wait for event A can be specified in the event_wait_list argument to clEnqueueNDRangeKernel for kernel B.

        In addition, a wait for events (clEnqueueMarkerWithWaitList) or a barrier (clEnqueueBarrierWithWaitList) command can be enqueued to the command-queue. The wait for events command ensures that previously enqueued commands identified by the list of events to wait for have finished before the next batch of commands is executed. The barrier command ensures that all previously enqueued commands in a command-queue have finished execution before the next batch of commands is executed.

        Similarly, commands to read, write, copy or map memory objects that are enqueued after clEnqueueNDRangeKernel or clEnqueueNativeKernel commands are not guaranteed to wait for kernels scheduled for execution to have completed (if the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property is set). To ensure correct ordering of commands, the event object returned by clEnqueueNDRangeKernel or clEnqueueNativeKernel can be used to enqueue a wait for event or a barrier command can be enqueued that must complete before reads or writes to the memory object(s) occur.

        Errors

        clCreateCommandQueueWithProperties 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clGetCommandQueueInfo, clReleaseCommandQueue, clRetainCommandQueue, clCreateContext, clCreateContextFromType, clEnqueueNDRangeKernel

      • clRetainCommandQueue

        public static int clRetainCommandQueue​(cl_command_queue command_queue)

        Increments the command_queue reference count.

        cl_int clRetainCommandQueue( cl_command_queuecommand_queue)

        Parameters

        command_queue

        Specifies the command-queue to retain.

        Notes

        clCreateCommandQueue performs an implicit retain. This is very helpful for 3rd party libraries, which typically get a command-queue passed to them by the application. However, it is possible that the application may delete the command-queue without informing the library. Allowing functions to attach to (i.e. retain) and release a command-queue solves the problem of a command-queue being used by a library no longer being valid.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainCommandQueueNative

        private static int clRetainCommandQueueNative​(cl_command_queue command_queue)
      • clReleaseCommandQueue

        public static int clReleaseCommandQueue​(cl_command_queue command_queue)

        Decrements the command_queue reference count.

        cl_int clReleaseCommandQueue( cl_command_queuecommand_queue)

        Parameters

        command_queue

        Specifies the command-queue to release.

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command queue.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. It returns CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.

      • clReleaseCommandQueueNative

        private static int clReleaseCommandQueueNative​(cl_command_queue command_queue)
      • clGetCommandQueueInfo

        public static int clGetCommandQueueInfo​(cl_command_queue command_queue,
                                                int param_name,
                                                long param_value_size,
                                                Pointer param_value,
                                                long[] param_value_size_ret)

        Query information about a command-queue.

        cl_int clGetCommandQueueInfo( cl_command_queuecommand_queue,
        cl_command_queue_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        command_queue

        Specifies the command-queue being queried.

        param_name

        Specifies the information to query.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table below. If param_value is NULL, it is ignored.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored

        The list of supported param_name values and the information returned in param_value by clGetCommandQueueInfo is described in the table below.

        cl_command_queue_info Return Type and Information returned in param_value
        CL_QUEUE_CONTEXT Return type: cl_context

        Return the context specified when the command-queue is created.

        CL_QUEUE_DEVICE Return type: cl_device_id

        Return the device specified when the command-queue is created.

        CL_QUEUE_REFERENCE_COUNT Return type: cl_uint

        Return the command-queue reference count.

        The reference count returned with CL_QUEUE_REFERENCE_COUNT should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

        CL_QUEUE_PROPERTIES Return type: cl_command_queue_properties

        Return the currently specified properties for the command-queue. These properties are specified by the properties argument in clCreateCommandQueue.

        Notes

        It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified, when the context is created can be used to record appropriate information in the errinfo, private_info arguments passed to the callback function when the device becomes unavailable.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:

        • 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 less than size of return type and param_value is not a NULL value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetCommandQueueInfoNative

        private static int clGetCommandQueueInfoNative​(cl_command_queue command_queue,
                                                       int param_name,
                                                       long param_value_size,
                                                       Pointer param_value,
                                                       long[] param_value_size_ret)
      • clSetCommandQueueProperty

        public static int clSetCommandQueueProperty​(cl_command_queue command_queue,
                                                    long properties,
                                                    boolean enable,
                                                    long[] old_properties)
        Deprecated.
        This API introduces mutable state into the OpenCL implementation. It has been REMOVED to better facilitate thread safety. The 1.0 API is not thread safe. It is not tested by the OpenCL 1.1 conformance test, and consequently may not work or may not work dependably.
        It is likely to be non-performant. Use of this API is not advised. Use at your own risk.

        Software developers previously relying on this API are instructed to set the command queue properties when creating the queue, instead.

        Enable or disable the properties of a command-queue.

        cl_int clSetCommandQueueProperty( cl_command_queuecommand_queue,
        cl_command_queue_propertiesproperties,
        cl_boolenable,
        cl_command_queue_properties*old_properties)

        Parameters

        THIS FUNCITON IS DEPRECATED.

        command_queue

        Specifies the command-queue being queried.

        properties

        Specifies the new command-queue properties to be applied to command_queue. Only command-queue properties specified for clCreateCommandQueue can be set in properties; otherwise the value specified in properties is considered to be not valid.

        enable

        Determines whether the values specified by properties are enabled (if enable is CL_TRUE) or disabled (if enable is CL_FALSE) for the command-queue. The allowed property values are the same as those specified for clCreateCommandQueue.

        old_properties

        Returns the command-queue properties before they were changed by clSetCommandQueueProperty. If old_properties is NULL, it is ignored.

        Notes

        As specified for clCreateCommandQueue, the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE command-queue property determines whether the commands in a command-queue are executed in-order or out-of-order. Changing this command-queue property will cause the OpenCL implementation to block until all previously queued commands in command_queue have completed. This can be an expensive operation and therefore changes to the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE property should be only done when absolutely necessary.

        It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified when the context is created, can be used to record appropriate information in the errinfo, private_info arguments passed to the callback function when the device becomes unavailable.

        Errors

        Returns CL_SUCCESS if the command-queue properties are successfully updated. Otherwise, it returns the following:

        • 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.
        • Returns CL_INVALID_QUEUE_PROPERTIES if the values specified in properties are not supported by the device.
      • clSetCommandQueuePropertyNative

        private static int clSetCommandQueuePropertyNative​(cl_command_queue command_queue,
                                                           long properties,
                                                           boolean enable,
                                                           long[] old_properties)
      • clCreateBuffer

        public static cl_mem clCreateBuffer​(cl_context context,
                                            long flags,
                                            long size,
                                            Pointer host_ptr,
                                            int[] errcode_ret)

        Creates a buffer object.

        cl_mem clCreateBuffer ( cl_contextcontext,
        cl_mem_flagsflags,
        size_tsize,
        void*host_ptr,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context used to create the buffer object.

        flags

        A bit-field that is used to specify allocation and usage information such as the memory arena that should be used to allocate the buffer object and how it will be used. The following table describes the possible values for flags:

        cl_mem_flags Description
        CL_MEM_READ_WRITE This flag specifies that the memory object will be read and written by a kernel. This is the default.
        CL_MEM_WRITE_ONLY

        This flags specifies that the memory object will be written but not read by a kernel.

        Reading from a buffer or image object created with CL_MEM_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.

        size

        The size in bytes of the buffer memory object to be allocated.

        host_ptr

        A pointer to the buffer data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to the size bytes.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Errors

        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 of OpenCL Device Queries for clGetDeviceInfo 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateBufferNative

        private static cl_mem clCreateBufferNative​(cl_context context,
                                                   long flags,
                                                   long size,
                                                   Pointer host_ptr,
                                                   int[] errcode_ret)
      • clCreateSubBuffer

        public static cl_mem clCreateSubBuffer​(cl_mem buffer,
                                               long flags,
                                               int buffer_create_type,
                                               Pointer buffer_create_info,
                                               int[] errcode_ret)
        Deprecated.
        The buffer_create_info that has to be passed to this function is specific for the underlying architecture (32/64 bit). The preferred way of creating a sub-buffer is now via clCreateSubBuffer(cl_mem, long, int, cl_buffer_region, int[])
        Since:
        OpenCL 1.1
      • clCreateSubBufferNative

        private static cl_mem clCreateSubBufferNative​(cl_mem buffer,
                                                      long flags,
                                                      int buffer_create_type,
                                                      Pointer buffer_create_info,
                                                      int[] errcode_ret)
      • clCreateSubBuffer

        public static cl_mem clCreateSubBuffer​(cl_mem buffer,
                                               long flags,
                                               int buffer_create_type,
                                               cl_buffer_region buffer_create_info,
                                               int[] errcode_ret)

        Creates a buffer object (referred to as a sub-buffer object) from an existing buffer object.

        cl_mem clCreateSubBuffer ( cl_membuffer,
        cl_mem_flagsflags,
        cl_buffer_create_typebuffer_create_type,
        const void*buffer_create_info,
        cl_int*errcode_ret)

        Parameters

        buffer

        A valid object. Cannot be a sub-buffer object.

        flags

        A bit-field that is used to specify allocation and usage information about the image memory object being created. The following table describes the possible values for flags:

        cl_mem_flags Description
        CL_MEM_READ_WRITE This flag specifies that the memory object will be read and written by a kernel. This is the default.
        CL_MEM_WRITE_ONLY

        This flags specifies that the memory object will be written but not read by a kernel.

        Reading from a buffer or image object created with CL_MEM_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.

        buffer_create_type and buffer_create_info

        The type of buffer object to be created. The supported value for buffer_create_type is CL_BUFFER_CREATE_TYPE_REGION, which create a buffer object that represents a specific region in buffer. buffer_create_info is a pointer to the following structure:


        typedefstruct_cl_buffer_region{
        size_torigin;
        size_tsize;
        }cl_buffer_region;

        (origin, size) defines the offset and size in bytes in buffer.

        If buffer is created with CL_MEM_USE_HOST_PTR, the host_ptr associated with the buffer object returned is host_ptr + origin.

        The buffer object returned references the data store allocated for buffer and points to a specific region given by (origin, size) in this data store.

        CL_INVALID_VALUE is returned in errcode_ret if the region specified by (origin, size) is out of bounds in buffer.

        CL_MISALIGNED_SUB_BUFFER_OFFSET is returned in errcode_ret if there are no devices in context associated with buffer for which the origin value is aligned to the CL_DEVICE_MEM_BASE_ADDR_ALIGN value.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        The implementation may return the same cl_mem object with the reference count incremented appropriately for multiple calls to clCreateSubBuffer that use the same values for buffer, flags, buffer_create_type and buffer_create_info points to the same descriptor or descriptors that describe values that are exactly the same.

        The result of OpenCL commands that read from and write to multiple sub-buffer objects created using clCreateSubBuffer with the same buffer object but represent overlapping regions in the buffer object is undefined. The result of OpenCL commands that read from and write to a buffer object and its sub-buffer object(s) created using clCreateSubBuffer with the same buffer object is undefined. OpenCL commands that only read from multiple sub-buffer objects created using clCreateSubBuffer with the same buffer object but represent overlapping regions in the buffer object or read from a buffer object and its sub-buffer objects should work as defined.

        Errors

        Returns a valid non-zero buffer object and errcode_ret is set to CL_SUCCESS if the buffer object is created successfully. Otherwise, it returns one of the following error in errcode_ret:

        • CL_INVALID_MEM_OBJECT if buffer is not a valid buffer object or is a sub-buffer object.
        • CL_INVALID_VALUE if values specified in flags are not valid; or if value specified in buffer_create_type is not valid; or if value(s) specified in buffer_create_info (for a given buffer_create_type) is not valid or if buffer_create_info is NULL.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clCreateSubBuffer2Native

        private static cl_mem clCreateSubBuffer2Native​(cl_mem buffer,
                                                       long flags,
                                                       int buffer_create_type,
                                                       cl_buffer_region buffer_create_info,
                                                       int[] errcode_ret)
      • clCreateImage

        public static cl_mem clCreateImage​(cl_context context,
                                           long flags,
                                           cl_image_format image_format,
                                           cl_image_desc image_desc,
                                           Pointer host_ptr,
                                           int[] errcode_ret)

        Creates a 1D image, 1D image buffer, 1D image array, 2D image, 2D image array or 3D image object.

        cl_mem clCreateImage ( cl_contextcontext,
        cl_mem_flagsflags,
        const cl_image_format*image_format,
        const cl_image_desc*image_desc,
        void*host_ptr,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context on which the image object is to be created.

        flags

        A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table below.

        For all image types except CL_MEM_OBJECT_IMAGE1D_BUFFER, if value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.

        For CL_MEM_OBJECT_IMAGE1D_BUFFER image type, if the CL_MEM_READ_WRITE, CL_MEM_READ_ONLY or CL_MEM_WRITE_ONLY values are not specified in flags, they are inherited from the corresponding memory access qualifers associated with buffer. The CL_MEM_USE_HOST_PTR, CL_MEM_ALLOC_HOST_PTR and CL_MEM_COPY_HOST_PTR values cannot be specified in flags but are inherited from the corresponding memory access qualifiers associated with buffer. If CL_MEM_COPY_HOST_PTR is specified in the memory access qualifier values associated with buffer it does not imply any additional copies when the sub-buffer is created from buffer. If the CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS values are not specified in flags, they are inherited from the corresponding memory access qualifiers associated with buffer.

        cl_mem_flags Description
        CL_MEM_READ_WRITE This flag specifies that the memory object will be read and written by a kernel. This is the default.
        CL_MEM_WRITE_ONLY

        This flags specifies that the memory object will be written but not read by a kernel.

        Reading from a buffer or image object created with CL_MEM_WRITE_ONLY inside a kernel is undefined.

        CL_MEM_READ_WRITE and CL_MEM_WRITE_ONLY are mutually exclusive.

        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_READ_WRITE or CL_MEM_WRITE_ONLY and CL_MEM_READ_ONLY are mutually exclusive.

        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.

        Refer to the description of the alignment rules for host_ptr for memory objects (buffer and images) created using CL_MEM_USE_HOST_PTR.

        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.

        CL_MEM_COPY_HOST_WRITE_ONLY

        This flag specifies that the host will only write to the memory object (using OpenCL APIs that enqueue a write or a map for write). This can be used to optimize write access from the host (e.g. enable write combined allocations for memory objects for devices that communicate with the host over a system bus such as PCIe).

        CL_MEM_COPY_HOST_READ_ONLY

        This flag specifies that the host will only read the memory object (using OpenCL APIs that enqueue a read or a map for read).

        CL_MEM_HOST_WRITE_ONLY and CL_MEM_HOST_READ_ONLY are mutually exclusive.

        CL_MEM_COPY_HOST_NO_ACCESS

        This flag specifies that the host will not read or write the memory object.

        CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_READ_ONLY and CL_MEM_HOST_NO_ACCESS are mutually exclusive.

        image_format

        A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.

        image_desc

        A pointer to a structure that describes type and dimensions of the image to be allocated. See imageDescriptor for more information.

        host_ptr

        A pointer to the image data that may already be allocated by the application. Refer to table below for a description of how large the buffer that host_ptr points to must be.

        Image Type Size of buffer that host_ptr points to
        CL_MEM_OBJECT_IMAGE1D >= image_row_pitch
        CL_MEM_OBJECT_IMAGE1D_BUFFER >= image_row_pitch
        CL_MEM_OBJECT_IMAGE2D >= image_row_pitch * image_height
        CL_MEM_OBJECT_IMAGE3D >= image_slice_pitch * image_depth
        CL_MEM_OBJECT_IMAGE1D_ARRAY >= image_slice_pitch * image_array_size
        CL_MEM_OBJECT_IMAGE2D_ARRAY >= image_slice_pitch * image_array_size

        For a 3D image or 2D image array, the image data specified by host_ptr is stored as a linear sequence of adjacent 2D image slices or 2D images respectively. Each 2D image is a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements.

        For a 2D image, the image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements.

        For a 1D image array, the image data specified by host_ptr is stored as a linear sequence of adjacent 1D images respectively. Each 1D image or 1D image buffer is a single scanline which is a linear sequence of adjacent elements.

        errcode_ret

        Will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Errors

        clCreateImage 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_DESCRIPTOR if values specified in image_desc are not valid or if image_desc is NULL.
        • CL_INVALID_IMAGE_SIZE if image dimensions specified in image_desc exceed the minimum maximum image dimensions described in the table of allowed values for param_name for clGetDeviceInfo for all devices in context.
        • CL_INVALID_HOST_PTR if host_ptr in image_desc 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_INVALID_VALUE if a 1D image buffer is being created and the buffer object was created with CL_MEM_WRITE_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_READ_ONLY, or if the buffer object was created with CL_MEM_READ_ONLY and flags specifies CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY, or if flags specifies CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR.
        • CL_INVALID_VALUE if a 1D image buffer is being created and the buffer object was created with CL_MEM_HOST_WRITE_ONLY and flags specifies CL_MEM_HOST_READ_ONLY, or if the buffer object was created with CL_MEM_HOST_READ_ONLY and flags specifies CL_MEM_HOST_WRITE_ONLY, or if the buffer object was created with CL_MEM_HOST_NO_ACCESS and flags specifies CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_WRITE_ONLY.
        • 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 the table of OpenCL Device Queries for clGetDeviceInfo) is CL_FALSE).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Throws:
        java.lang.IllegalArgumentException - If the given mapping flags contain CL_MEM_USE_HOST_PTR, and the given Pointer is not a Pointer to a direct buffer.
        Since:
        OpenCL 1.2 Note: If the given flags contain CL_MEM_USE_HOST_PTR, then the given Pointer must be a Pointer to a direct buffer. Otherwise, an IllegalArgumentException will be thrown.
      • clCreatePipe

        public static cl_mem clCreatePipe​(cl_context context,
                                          long flags,
                                          int pipe_packet_size,
                                          int pipe_max_packets,
                                          cl_pipe_properties properties,
                                          int[] errcode_ret)

        Creates a pipe object.

        cl_mem clCreatePipe ( cl_context context,
        cl_mem_flags flags,
        cl_uint pipe_packet_size,
        cl_uint pipe_max_packets,
        const cl_pipe_properties * properties,
        cl_int *errcode_ret)

        Parameters

        context

        A valid OpenCL context used to create the pipe object.

        flags

        A bit-field that is used to specify allocation and usage information such as the memory arena that should be used to allocate the pipe object and how it will be used. The table below describes the possible values for flags. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, CL_MEM_READ_WRITE, and CL_MEM_HOST_NO_ACCESS can be specified when creating a pipe object. If value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.

        cl_mem_flags Description
        CL_MEM_READ_WRITE This flag specifies that the memory object will be read and written by a kernel. This is the default.
        CL_MEM_WRITE_ONLY

        This flag 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_WRITE and CL_MEM_WRITE_ONLY are mutually exclusive.

        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_READ_WRITE or CL_MEM_WRITE_ONLY and CL_MEM_READ_ONLY are mutually exclusive.

        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.

        Refer to the description of the alignment rules for host_ptr for memory objects (buffer and images) created using CL_MEM_USE_HOST_PTR.

        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.

        CL_MEM_HOST_WRITE_ONLY

        This flag specifies that the host will only write to the memory object (using OpenCL APIs that enqueue a write or a map for write). This can be used to optimize write access from the host (e.g. enable write-combined allocations for memory objects for devices that communicate with the host over a system bus such as PCIe).

        CL_MEM_HOST_READ_ONLY

        This flag specifies that the host will only read the memory object (using OpenCL APIs that enqueue a read or a map for read).

        CL_MEM_HOST_WRITE_ONLY and CL_MEM_HOST_READ_ONLY are mutually exclusive.

        CL_MEM_HOST_NO_ACCESS

        This flag specifies that the host will not read or write the memory object.

        CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_READ_ONLY and CL_MEM_HOST_NO_ACCESS are mutually exclusive.

        pipe_packet_size

        Size in bytes of a pipe packet.

        pipe_max_packets

        Specifies the pipe capacity by specifying the maximum number of packets the pipe can hold.

        properties

        A list of properties for the pipe and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. In OpenCL 2.0, properties must be NULL.

        errcode_ret

        Will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        Pipes follow the same memory consistency model as defined for buffer and image objects. The pipe state i.e. contents of the pipe across kernel executions (on the same or different devices) is enforced at a synchronization point.

        Errors

        clCreatePipe returns a valid non-zero pipe object and errcode_ret is set to CL_SUCCESS if the pipe 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 as defined above.
        • CL_INVALID_VALUE if properties is not NULL.
        • CL_INVALID_PIPE_SIZE if pipe_packet_size is 0 or the pipe_packet_size exceeds CL_DEVICE_PIPE_MAX_PACKET_SIZE value specified in table 4.3 (see clGetDeviceInfo) for all devices in context or if pipe_max_packets is 0.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for the pipe object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clCreateBuffer, clCreateImage

      • clCreatePipeNative

        private static cl_mem clCreatePipeNative​(cl_context context,
                                                 long flags,
                                                 int pipe_packet_size,
                                                 int pipe_max_packets,
                                                 cl_pipe_properties properties,
                                                 int[] errcode_ret)
      • clCreateImage2D

        public static cl_mem clCreateImage2D​(cl_context context,
                                             long flags,
                                             cl_image_format[] image_format,
                                             long image_width,
                                             long image_height,
                                             long image_row_pitch,
                                             Pointer host_ptr,
                                             int[] errcode_ret)

        Creates a 2D image object.

        cl_mem clCreateImage2D ( cl_contextcontext,
        cl_mem_flagsflags,
        const cl_image_format*image_format,
        size_timage_width,
        size_timage_height,
        size_timage_row_pitch,
        void*host_ptr,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context on which the image object is to be created.

        flags

        A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table List of supported cl_mem_flags values for clCreateBuffer.

        image_format

        A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.

        image_width , image_height

        The width and height of the image in pixels. These must be values greater than or equal to 1.

        image_row_pitch

        The scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or greater than or equal to image_width * size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch is equal to 0, image_row_pitch is calculated as image_width * size of element in bytes. If image_row_pitch is not 0, it must be a multiple of the image element size in bytes.

        host_ptr

        A pointer to the image data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to image_row_pitch * image_height. The size of each element in bytes must be a power of 2. The image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is stored as a linear sequence of image elements.

        errcode_ret

        Will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Errors

        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 the table of OpenCL Device Queries for clGetDeviceInfo) is CL_FALSE).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateImage2DNative

        private static cl_mem clCreateImage2DNative​(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)
      • clCreateImage3D

        public static cl_mem clCreateImage3D​(cl_context context,
                                             long flags,
                                             cl_image_format[] image_format,
                                             long image_width,
                                             long image_height,
                                             long image_depth,
                                             long image_row_pitch,
                                             long image_slice_pitch,
                                             Pointer host_ptr,
                                             int[] errcode_ret)

        Creates a 3D image object.

        cl_mem clCreateImage3D ( cl_contextcontext,
        cl_mem_flagsflags,
        const cl_image_format*image_format,
        size_timage_width,
        size_timage_height,
        size_timage_depth,
        size_timage_row_pitch,
        size_timage_slice_pitch,
        void*host_ptr,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context on which the image object is to be created.

        flags

        A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the table List of supported cl_mem_flags values for clCreateBuffer.

        image_format

        A pointer to a structure that describes format properties of the image to be allocated. See cl_image_format for a detailed description of the image format descriptor.

        image_width , image_height

        The width and height of the image in pixels. These must be values greater than or equal to 1.

        image depth

        The depth of the image in pixels. This must be a value greater than 1.

        image_row_pitch

        The scan-line pitch in bytes. This must be 0 if host_ptr is NULL and can be either 0 or greater than or equal to image_width * size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and image_row_pitch is equal to 0, image_row_pitch is calculated as image_width * size of element in bytes. If image_row_pitch is not 0, it must be a multiple of the image element size in bytes.

        image_slice_pitch

        The size in bytes of each 2D slice in the 3D image. This must be 0 if host_ptr is NULL and can be either 0 or greater than or equal to image_row_pitch * image_height if host_ptr is not NULL. If host_ptr is not NULL and image_slice_pitch equal to 0, image_slice_pitch is calculated as image_row_pitch * image_height. If image_slice_pitch is not 0, it must be a multiple of the image_row_pitch.

        host_ptr

        A pointer to the image data that may already be allocated by the application. The size of the buffer that host_ptr points to must be greater than or equal to image_slice_pitch * image_depth. The size of each element in bytes must be a power of 2. The image data specified by host_ptr is stored as a linear sequence of adjacent 2D slices. Each 2D slice is a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements.

        errcode_ret

        Will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Errors

        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 less than or equal to 1 or if they exceed values specified in CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT or CL_DEVICE_IMAGE3D_MAX_DEPTH respectively for all devices in context or if values specified by image_row_pitch and image_slice_pitch do not follow rules described in the argument description above.
        • 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 the table of OpenCL Device Queries for clGetDeviceInfo) is CL_FALSE).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateImage3DNative

        private static cl_mem clCreateImage3DNative​(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)
      • clRetainMemObject

        public static int clRetainMemObject​(cl_mem memobj)

        Increments the memory object reference count.

        cl_int clRetainMemObject ( cl_memmemobj)

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_MEM_OBJECT if memobj is a not a valid memory object (buffer or image object).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        clCreateBuffer, clCreateSubBuffer, clCreateImage2D, and clCreateImage3D perform an implicit retain. clCreateSubBuffer also performs an implicit retain on the memory object used to create the sub-buffer or image object.

      • clRetainMemObjectNative

        private static int clRetainMemObjectNative​(cl_mem memobj)
      • clReleaseMemObject

        public static int clReleaseMemObject​(cl_mem memobj)

        Decrements the memory object reference count.

        cl_int clReleaseMemObject ( cl_memmemobj)

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_MEM_OBJECT if memobj is a not a valid memory object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        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.

      • clReleaseMemObjectNative

        private static int clReleaseMemObjectNative​(cl_mem memobj)
      • clGetSupportedImageFormats

        public static int clGetSupportedImageFormats​(cl_context context,
                                                     long flags,
                                                     int image_type,
                                                     int num_entries,
                                                     cl_image_format[] image_formats,
                                                     int[] num_image_formats)

        Get the list of image formats supported by an OpenCL implementation.

        cl_int clGetSupportedImageFormats ( cl_contextcontext,
        cl_mem_flagsflags,
        cl_mem_object_typeimage_type,
        cl_uintnum_entries,
        cl_image_format*image_formats,
        cl_uint*num_image_formats)

        Parameters

        context

        A valid OpenCL context on which the image object(s) will be created.

        flags

        A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the List of supported cl_mem_flags values for clCreateBuffer

        image_type

        Describes the image type and must be either CL_MEM_OBJECT_IMAGE2D or CL_MEM_OBJECT_IMAGE3D.

        num_entries

        Specifies the number of entries that can be returned in the memory location given by image_formats.

        image_formats

        A pointer to a memory location where the list of supported image formats are returned. Each entry describes a cl_image_format structure supported by the OpenCL implementation. If image_formats is NULL, it is ignored.

        num_image_formats

        The actual number of supported image formats for a specific context and values specified by flags. If num_image_formats is NULL, it is ignored.

        Notes

        clGetSupportedImageFormats can be used to get the list of image formats supported by an OpenCL implementation when the following information about an image memory object is specified:

        • Context
        • Image type - 2D or 3D image
        • Image object allocation information

        The minimum list of supported image formats is given by the table below:

        image_num_channels

        image_channel_order

        image_channel_data_type

        4

        CL_RGBA

        CL_UNORM_INT8
        CL_UNORM_INT16

        CL_SIGNED_INT8
        CL_SIGNED_INT16
        CL_SIGNED_INT32

        CL_UNSIGNED_INT8
        CL_UNSIGNED_INT16
        CL_UNSIGNED_INT32

        CL_HALF_FLOAT
        CL_FLOAT

        4

        CL_BGRA

        CL_UNORM_INT8

        If CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_TRUE, the values assigned to the following constants by the implementation must be greater than or equal to the minimum values specified in the table of OpenCL Device Queries for clGetDeviceInfo: CL_DEVICE_MAX_READ_IMAGE_ARGS, CL_DEVICE_MAX_WRITE_IMAGE_ARGS, CL_DEVICE_IMAGE2D_MAX_WIDTH, CL_DEVICE_IMAGE2D_MAX_HEIGHT, CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT, CL_DEVICE_IMAGE3D_MAX_DEPTH, CL_DEVICE_MAX_SAMPLERS.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

        • CL_INVALID_CONTEXT if context is not a valid context.
        • CL_INVALID_VALUE if flags or image_type are not valid, or if num_entries is 0 and image_formats is not NULL.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetSupportedImageFormatsNative

        private static int clGetSupportedImageFormatsNative​(cl_context context,
                                                            long flags,
                                                            int image_type,
                                                            int num_entries,
                                                            cl_image_format[] image_formats,
                                                            int[] num_image_formats)
      • clGetMemObjectInfo

        public static int clGetMemObjectInfo​(cl_mem memobj,
                                             int param_name,
                                             long param_value_size,
                                             Pointer param_value,
                                             long[] param_value_size_ret)

        Used to get information that is common to all memory objects (buffer and image objects).

        cl_int clGetMemObjectInfo ( cl_memmemobj,
        cl_mem_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        memobj

        Specifies the memory object being queried.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetMemObjectInfo is described in the table below.

        cl_mem_info Return Type Info. returned in param_value
        CL_MEM_TYPE cl_mem_object_type Returns one of the following values:

        CL_MEM_OBJECT_BUFFER if memobj is created with clCreateBuffer or clCreateSubBuffer,

        CL_MEM_OBJECT_IMAGE2D if memobj is a 2D image object, or

        CL_MEM_OBJECT_IMAGE3D if memobj is a 3D image object.

        CL_MEM_FLAGS cl_mem_flags Returns the flags argument value specified when memobj is created with clCreateBuffer, clCreateSubBuffer, clCreateImage2D, or clCreateImage3D.
        CL_MEM_SIZE size_t Return actual size of the data store associated with memobj in bytes.
        CL_MEM_HOST_PTR void * Return the host_ptr argument value specified when memobj is created.
        CL_MEM_MAP_COUNT cl_uint Map count. The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging.
        CL_MEM_REFERENCE_COUNT cl_uint Return memobj reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
        CL_MEM_CONTEXT cl_context Return context specified when memory object is created.
        CL_MEM_ASSOCIATED_MEMOBJECT cl_mem Return memory object from which memobj is created.

        This returns the memory object specified as buffer argument to clCreateSubBuffer.

        Otherwise a NULL value is returned.

        CL_MEM_OFFSET size_t Return offset if memobj is a sub-buffer object created using clCreateSubBuffer.

        This return 0 if memobj is not a subbuffer object.

        CL_MEM_D3D10_RESOURCE_KHR ID3D10Resource * The propery being queried (if the cl_khr_d3d10_sharing extension is enabled). If memobj was created using clCreateFromD3D10BufferKHR, clCreateFromD3D10Texture2DKHR, or clCreateFromD3D10Texture3DKHR, returns the resource argument specified when memobj was created.
        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to size of return type as described in the table above.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_D3D10_RESOURCE_KHR If the cl_khr_d3d10_sharing extension is enabled and if param_name is CL_MEM_D3D10_RESOURCE_KHR and memobj was not created by the function clCreateFromD3D10BufferKHR, clCreateFromD3D10Texture2DKHR, or clCreateFromD3D10Texture3DKHR.
        • CL_INVALID_MEM_OBJECT if memobj is a not a valid memory object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetMemObjectInfoNative

        private static int clGetMemObjectInfoNative​(cl_mem memobj,
                                                    int param_name,
                                                    long param_value_size,
                                                    Pointer param_value,
                                                    long[] param_value_size_ret)
      • clGetImageInfo

        public static int clGetImageInfo​(cl_mem image,
                                         int param_name,
                                         long param_value_size,
                                         Pointer param_value,
                                         long[] param_value_size_ret)

        Get information specific to an image object.

        cl_int * clGetImageInfo ( cl_memimage,
        cl_image_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        image

        Specifies the image object being queried.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetImageInfo is described in the table below.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to size of return type as described in the table below.

        cl_image_info Return Type Info. returned in param_value
        CL_IMAGE_FORMAT cl_image_format Return image format descriptor specified when image is created with clCreateImage2D or clCreateImage3D.
        CL_IMAGE_ELEMENT_SIZE size_t Return size of each element of the image memory object given by image. An element is made up of n channels. The value of n is given in cl_image_format descriptor.
        CL_IMAGE_ROW_PITCH size_t Return size in bytes of a row of elements of the image object given by image.
        CL_IMAGE_SLICE_PITCH size_t Return size in bytes of a 2D slice for the 3D image object given by image. For a 2D image object this value will be 0.
        CL_IMAGE_WIDTH size_t Return width of image in pixels.
        CL_IMAGE_HEIGHT size_t Return height of image in pixels.
        CL_IMAGE_DEPTH size_t Return depth of the image in pixels. For a 2D image, depth equals 0.
        CL_IMAGE_D3D10_SUBRESOURCE_KHR ID3D10Resource * The propery being queried (if the cl_khr_d3d10_sharing extension is enabled). If image was created using clCreateFromD3D10Texture2DKHR or clCreateFromD3D10Texture3DKHR, returns the subresource argument specified when image was created.
        param_value_size_ret

        the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

        Notes

        To get information that is common to all memory objects (buffer and image objects), use the clGetMemObjectInfo function.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_MEM_OBJECT if image is a not a valid image object.
        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_D3D10_RESOURCE_KHR if param_name is CL_MEM_D3D10_SUBRESOURCE_KHR and image was not created by the function clCreateFromD3D10Texture2DKHR or clCreateFromD3D10Texture3DKHR.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetImageInfoNative

        private static int clGetImageInfoNative​(cl_mem image,
                                                int param_name,
                                                long param_value_size,
                                                Pointer param_value,
                                                long[] param_value_size_ret)
      • clGetPipeInfo

        public static int clGetPipeInfo​(cl_mem pipe,
                                        int param_name,
                                        long param_value_size,
                                        Pointer param_value,
                                        long[] param_value_size_ret)

        Get information specific to a pipe object created with clCreatePipe.

        cl_int clGetPipeInfo ( cl_mem pipe ,
        cl_pipe_info param_name ,
        size_t param_value_size ,
        void *param_value ,
        size_t *param_value_size_ret )

        Parameters

        pipe

        Specifies the pipe 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 clGetPipeInfo is described in the table below.

        cl_pipe_info Return Type Info. returned in param_value
        CL_PIPE_PACKET_SIZE cl_uint Return pipe packet size specified when pipe is created with clCreatePipe.
        CL_PIPE_MAX_PACKETS cl_uint Return max. number of packets specified when pipe is created with clCreatePipe.
        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in the table above.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

        Notes

        To get information that is common to all memory objects, use the clGetMemObjectInfo function.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < the size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_MEM_OBJECT if pipe is a not a valid memory object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clGetImageInfo

      • clGetPipeInfoNative

        private static int clGetPipeInfoNative​(cl_mem pipe,
                                               int param_name,
                                               long param_value_size,
                                               Pointer param_value,
                                               long[] param_value_size_ret)
      • clSetMemObjectDestructorCallback

        public static int clSetMemObjectDestructorCallback​(cl_mem memobj,
                                                           MemObjectDestructorCallbackFunction pfn_notify,
                                                           java.lang.Object user_data)

        Registers a user callback function that will be called when the memory object is deleted and its resources freed.

        cl_int clSetMemObjectDestructorCallback ( cl_memmemobj,
        void (CL_CALLBACK *pfn_notify) (cl_mem memobj,
        void*user_data),
        void*user_data)

        Parameters

        memobj

        A valid memory object.

        pfn_notify

        The callback function that can be registered by the application. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are:

        • memobj: the memory object being deleted.
        • user_data: a pointer to user supplied data.
        user_data

        Data which will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.

        Notes

        Each call to clSetMemObjectDestructorCallback registers the specified user callback function on a callback stack associated with memobj. The registered user callback functions are called in the reverse order in which they were registered. The user callback functions are called and then the memory object's resources are freed and the memory object is deleted. This provides a mechanism for the application (and libraries) using memobj to be notified when the memory referenced by host_ptr, specified when the memory object is created and used as the storage bits for the memory object, can be reused or freed.

        When the user callback function is called by the implementation, the contents of the memory region pointed to by host_ptr (if the memory object is created with CL_MEM_USE_HOST_PTR) are undefined. The callback function is typically used by the application to either free or reuse the memory region pointed to by host_ptr.

        The behavior of calling expensive system routines, OpenCL API calls to create contexts or command-queues, or blocking OpenCL operations from the following list below, in a callback is undefined.

        • clFinish
        • clWaitForEvents
        • blocking calls to clEnqueueReadBuffer, clEnqueueReadBufferRect, clEnqueueWriteBuffer, clEnqueueWriteBufferRect
        • blocking calls to clEnqueueReadImage and clEnqueueWriteImage
        • blocking calls to clEnqueueMapBuffer and clEnqueueMapImage
        • blocking calls to clBuildProgram

        If an application needs to wait for completion of a routine from the above list in a callback, please use the non-blocking form of the function, and assign a completion callback to it to do the remainder of your work. Note that when a callback (or other code) enqueues commands to a command-queue, the commands are not required to begin execution until the queue is flushed. In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a command queue should either call clFlush on the queue before returning or arrange for clFlush to be called later on another thread.

        The user callback function may not call OpenCL APIs with the memory object for which the callback function is invoked and for such cases the behavior of OpenCL APIs is considered to be undefined.

        Errors

        Returns CL_SUCCESS if the command-queue properties are successfully updated. Otherwise, it returns the following:

        • CL_INVALID_MEM_OBJECT if memobj is not a valid memory object.
        • CL_INVALID_VALUE if pfn_notify is NULL.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clSVMAlloc

        public static Pointer clSVMAlloc​(cl_context context,
                                         long flags,
                                         long size,
                                         int alignment)

        Allocates a shared virtual memory (SVM) buffer that can be shared by the host and all devices in an OpenCL context that support shared virtual memory.

        void * clSVMAlloc ( cl_context context,
        cl_svm_mem_flags flags,
        size_t size,
        unsigned int alignment)

        Parameters

        context

        A valid OpenCL context used to create the SVM buffer.

        flags

        A bit-field that is used to specify allocation and usage information. The following table describes the possible values for flags.

        cl_svm_mem_flags Description
        CL_MEM_READ_WRITE This flag specifies that the SVM buffer will be read and written by a kernel. This is the default.
        CL_MEM_WRITE_ONLY

        This flag specifies that the SVM buffer will be written but not read by a kernel.

        Reading from a SVM buffer created with CL_MEM_WRITE_ONLY inside a kernel is undefined.

        CL_MEM_READ_WRITE and CL_MEM_WRITE_ONLY are mutually exclusive.

        CL_MEM_READ_ONLY

        This flag specifies that the SVM buffer object is a read-only memory object when used inside a kernel.

        Writing to a SVM buffer created with CL_MEM_READ_ONLY inside a kernel is undefined.

        CL_MEM_READ_WRITE or CL_MEM_WRITE_ONLY and CL_MEM_READ_ONLY are mutually exclusive.

        CL_MEM_SVM_FINE_GRAIN_BUFFER This specifies that the application wants the OpenCL implementation to do a fine-grained allocation.
        CL_MEM_SVM_ATOMICS This flag is valid only if CL_MEM_SVM_FINE_GRAIN_BUFFER is specified in flags. It is used to indicate that SVM atomic operations can control visibility of memory accesses in this SVM buffer.
        size

        The size in bytes of the SVM buffer to be allocated.

        alignment

        The minimum alignment in bytes that is required for the newly created buffer’s memory region. It must be a power of two up to the largest data type supported by the OpenCL device. For the full profile, the largest data type is long16. For the embedded profile, it is long16 if the device supports 64-bit integers; otherwise it is int16. If alignment is 0, a default alignment will be used that is equal to the size of largest data type supported by the OpenCL implementation.

        Notes

        If CL_MEM_SVM_FINE_GRAIN_BUFFER is not specified, the buffer can be created as a coarse grained SVM allocation. Similarly, if CL_MEM_SVM_ATOMICS is not specified, the buffer can be created without support for the OpenCL 2.0 SVM atomic operations (refer to section 6.13.11 of the OpenCL C 2.0 specification).

        Calling clSVMAlloc does not itself provide consistency for the shared memory region. When the host can’t use the SVM atomic operations, it must rely on OpenCL’s guaranteed memory consistency at synchronization points. To initialize a buffer to be shared with a kernel, the host can create the buffer and use the resulting virtual memory pointer to initialize the buffer’s contents.

        For SVM to be used efficiently, the host and any devices sharing a buffer containing virtual memory pointers should have the same endianness. If the context passed to clSVMAlloc has devices with mixed endianness and the OpenCL implementation is unable to implement SVM because of that mixed endianness, clSVMAlloc will fail and return NULL.

        Although SVM is generally not supported for image objects, clCreateImage may create an image from a buffer (a 1D image from a buffer or a 2D image from buffer) if the buffer specified in its image description parameter is a SVM buffer. Such images have a linear memory representation so their memory can be shared using SVM. However, fine grained sharing and atomics are not supported for image reads and writes in a kernel.

        If clCreateBuffer is called with a pointer returned by clSVMAlloc as its host_ptr argument, and CL_MEM_USE_HOST_PTR is set in its flags argument, clCreateBuffer will succeed and return a valid non-zero buffer object as long as the size argument to clCreateBuffer is no larger than the size argument passed in the original clSVMAlloc call. The new buffer object returned has the shared memory as the underlying storage. Locations in the buffer’s underlying shared memory can be operated on using, e.g., atomic operations if the device supports them.

        Errors

        Returns a valid non-NULL shared virtual memory address if the SVM buffer is successfully allocated. Otherwise, like malloc, it returns a NULL pointer value. clSVMAlloc will fail if:

        • context is not a valid context.
        • flags does not contain CL_MEM_SVM_FINE_GRAIN_BUFFER but does contain CL_MEM_SVM_ATOMICS.
        • Values specified in flags do not follow rules described for supported values in the table above.
        • CL_MEM_SVM_FINE_GRAIN_BUFFER or CL_MEM_SVM_ATOMICS is specified in flags and these are not supported by at least one device in context.
        • The values specified in flags are not valid i.e. don’t match those defined in the table above.
        • size is 0 or > CL_DEVICE_MAX_MEM_ALLOC_SIZE value for any device in context.
        • alignment is not a power of two or the OpenCL implementation cannot support the specified alignment for at least one device in context.
        • There was a failure to allocate resources.

        Also see

        clSVMFree, Shared Virtual Memory Functions

      • clSVMAllocNative

        private static Pointer clSVMAllocNative​(cl_context context,
                                                long flags,
                                                long size,
                                                int alignment)
      • clSVMFree

        public static void clSVMFree​(cl_context context,
                                     Pointer svm_pointer)

        Frees a shared virtual memory buffer allocated using clSVMAlloc.

        void clSVMFree ( cl_context context,
        void *svm_pointer)

        Parameters

        context

        A valid OpenCL context used to create the SVM buffer.

        svm_pointer

        Must be the value returned by a call to clSVMAlloc. If a NULL pointer is passed in svm_pointer, no action occurs.

        Notes

        Note that clSVMFree does not wait for previously enqueued commands that may be using svm_pointer to finish before freeing svm_pointer. It is the responsibility of the application to make sure that enqueued commands that use svm_pointer have finished before freeing svm_pointer. This can be done by enqueuing a blocking operation such as clFinish, clWaitForEvents, clEnqueueReadBuffer or by registering a callback with the events associated with enqueued commands and when the last enqueued comamnd has finished freeing svm_pointer.

        The behavior of using svm_pointer after it has been freed is undefined. In addition, if a buffer object is created using clCreateBuffer with svm_pointer, the buffer object must first be released before the svm_pointer is freed.

        The clEnqueueSVMFree API can also be used to enqueue a callback to free the shared virtual memory buffer allocated using clSVMAlloc or a shared system memory pointer.

        Also see

        clSVMAlloc, Shared Virtual Memory Functions

      • clSVMFreeNative

        private static void clSVMFreeNative​(cl_context context,
                                            Pointer svm_pointer)
      • clCreateSamplerWithProperties

        public static cl_sampler clCreateSamplerWithProperties​(cl_context context,
                                                               cl_sampler_properties properties,
                                                               int[] errcode_ret)

        Creates a sampler object.

        cl_sampler clCreateSamplerWithProperties ( cl_context context,
        const cl_sampler_properties *sampler_properties,
        cl_int *errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        sampler_properties

        Specifies a list of sampler property names and their corresponding values. Each sampler 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 below. If a supported property and its value is not specified in sampler_properties, its default value will be used. sampler_properties can be NULL in which case the default values for supported sampler properties will be used.

        cl_sampler_properties enum Property Value Description
        CL_SAMPLER_NORMALIZED_COORDS cl_bool

        A boolean value that specifies whether the image coordinates specified are normalized or not.

        The default value (i.e. the value used if this property is not specified in sampler_properties) is CL_TRUE.

        CL_SAMPLER_ADDRESSING_MODE cl_addressing_mode

        Specifies how out-of-range image coordinates are handled when reading from an image.

        Valid values are:

        • CL_ADDRESS_MIRRORED_REPEAT
        • CL_ADDRESS_REPEAT
        • CL_ADDRESS_CLAMP_TO_EDGE
        • CL_ADDRESS_CLAMP
        • CL_ADDRESS_NONE

        The default is CL_ADDRESS_CLAMP.

        CL_SAMPLER_FILTER_MODE cl_filter_mode

        Specifies the type of filter that must be applied when reading an image. Valid values are:

        • CL_FILTER_NEAREST
        • CL_FILTER_LINEAR

        The default is CL_FILTER_NEAREST.

        If the cl_khr_mipmap_image extension is supported, the following sampler properties can be specified when a sampler object is created using clCreateSamplerWithProperties:

        cl_sampler_properties enum Property Value Default Value
        CL_SAMPLER_MIP_FILTER_MODE cl_filter_mode CL_FILTER_NONE
        CL_SAMPLER_LOD_MIN float 0.0f
        CL_SAMPLER_LOD_MAX float MAXFLOAT
        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        A sampler object describes how to sample an image when the image is read in the kernel. The built-in functions to read from an image in a kernel take a sampler as an argument. The sampler arguments to the image read function can be sampler objects created using OpenCL functions and passed as argument values to the kernel or can be samplers declared inside a kernel.

        For more information about working with samplers, see sampler_t

        If the cl_khr_mipmap_image extension is supported, the sampler properties CL_SAMPLER_MIP_FILTER_MODE, CL_SAMPLER_LOD_MIN and CL_SAMPLER_LOD_MAX cannot be specified with any samplers initialized in the OpenCL program source. Only the default values for these properties will be used. To create a sampler with specific values for these properties, a sampler object must be created with clCreateSamplerWithProperties and passed as an argument to a kernel.

        Errors

        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 the property name in sampler_properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once.
        • CL_INVALID_OPERATION if images are not supported by any device associated with context (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clRetainSampler, clReleaseSampler, clGetSamplerInfo sampler_t, cl_khr_mipmap_image

      • clCreateSampler

        public static cl_sampler clCreateSampler​(cl_context context,
                                                 boolean normalized_coords,
                                                 int addressing_mode,
                                                 int filter_mode,
                                                 int[] errcode_ret)

        Creates a sampler object.

        cl_sampler clCreateSampler ( cl_contextcontext,
        cl_boolnormalized_coords,
        cl_addressing_modeaddressing_mode,
        cl_filter_modefilter_mode,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        normalized_coords

        Determines if the image coordinates specified are normalized (if normalized_coords is CL_TRUE) or not (if normalized_coords is CL_FALSE).

        addressing_mode

        Specifies how out-of-range image coordinates are handled when reading from an image. This can be set to CL_ADDRESS_MIRRORED_REPEAT, CL_ADDRESS_REPEAT, CL_ADDRESS_CLAMP_TO_EDGE, CL_ADDRESS_CLAMP, and CL_ADDRESS_NONE.

        filtering_mode

        Specifies the type of filter that must be applied when reading an image. This can be CL_FILTER_NEAREST or CL_FILTER_LINEAR.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        A sampler object describes how to sample an image when the image is read in the kernel. The built-in functions to read from an image in a kernel take a sampler as an argument. The sampler arguments to the image read function can be sampler objects created using OpenCL functions and passed as argument values to the kernel or can be samplers declared inside a kernel. In this section we discuss how sampler objects are created using OpenCL functions.

        Errors

        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 a 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 the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateSamplerNative

        private static cl_sampler clCreateSamplerNative​(cl_context context,
                                                        boolean normalized_coords,
                                                        int addressing_mode,
                                                        int filter_mode,
                                                        int[] errcode_ret)
      • clRetainSampler

        public static int clRetainSampler​(cl_sampler sampler)

        Increments the sampler reference count.

        cl_int clRetainSampler( cl_samplersampler)

        Parameters

        sampler
        Specifies the sampler being retained.

        Notes

        clCreateSampler performs an implicit retain.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_SAMPLER if sampler is not a valid sampler object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainSamplerNative

        private static int clRetainSamplerNative​(cl_sampler sampler)
      • clReleaseSampler

        public static int clReleaseSampler​(cl_sampler sampler)

        Decrements the sampler reference count.

        cl_int clReleaseSampler ( cl_samplersampler)

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_SAMPLER if sampler is not a valid sampler object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clReleaseSamplerNative

        private static int clReleaseSamplerNative​(cl_sampler sampler)
      • clGetSamplerInfo

        public static int clGetSamplerInfo​(cl_sampler sampler,
                                           int param_name,
                                           long param_value_size,
                                           Pointer param_value,
                                           long[] param_value_size_ret)

        Returns information about the sampler object.

        cl_int clGetSamplerInfo ( cl_samplersampler,
        cl_sampler_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        sampler

        Specifies the sampler being queried.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetSamplerInfo is described in the table below.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to size of return type as described in the table below.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        cl_sampler_info Return Type and Info. returned in param_value
        CL_SAMPLER_REFERENCE_COUNT Return type: cl_uint

        Return the sampler reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

        CL_SAMPLER_CONTEXT Return type: cl_context

        Return the context specified when the sampler is created.

        CL_SAMPLER_ADDRESSING_MODE Return type: cl_addressing_mode

        Return the addressing mode value associated with sampler.

        CL_SAMPLER_FILTER_MODE Return type: cl_filter_mode

        Return the filter mode value associated with sampler.

        CL_SAMPLER_NORMALIZED_COORDS Return type: cl_bool

        Return the normalized coords value associated with sampler.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than return type as described in the table above and param_value is not NULL
        • CL_INVALID_SAMPLER if sampler is a not a valid sampler object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetSamplerInfoNative

        private static int clGetSamplerInfoNative​(cl_sampler sampler,
                                                  int param_name,
                                                  long param_value_size,
                                                  Pointer param_value,
                                                  long[] param_value_size_ret)
      • clCreateProgramWithSource

        public static cl_program clCreateProgramWithSource​(cl_context context,
                                                           int count,
                                                           java.lang.String[] strings,
                                                           long[] lengths,
                                                           int[] errcode_ret)

        Creates a program object for a context, and loads the source code specified by the text strings in the strings array into the program object.

        cl_program clCreateProgramWithSource ( cl_contextcontext,
        cl_uintcount,
        const char**strings,
        const size_t*lengths,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        strings

        An array of count pointers to optionally null-terminated character strings that make up the source code.

        lengths

        An array with the number of chars in each string (the string length). If an element in lengths is zero, its accompanying string is null-terminated. If lengths is NULL, all strings in the strings argument are considered null-terminated. Any length value passed in that is greater than zero excludes the null terminator in its count.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        The devices associated with the program object are the devices associated with context.

        OpenCL allows applications to create a program object using the program source or binary and build appropriate program executables. This allows applications to determine whether they want to use the pre-built offline binary or load and compile the program source and use the executable compiled/linked online as the program executable. This can be very useful as it allows applications to load and build program executables online on its first instance for appropriate OpenCL devices in the system. These executables can now be queried and cached by the application. Future instances of the application launching will no longer need to compile and build the program executables. The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time.

        An OpenCL program consists of a set of kernels that are identified as functions declared with the __kernel qualifier in the program source. OpenCL programs may also contain auxiliary functions and constant data that can be used by __kernel functions. The program executable can be generated online or offline by the OpenCL compiler for the appropriate target device(s).

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateProgramWithSourceNative

        private static cl_program clCreateProgramWithSourceNative​(cl_context context,
                                                                  int count,
                                                                  java.lang.String[] strings,
                                                                  long[] lengths,
                                                                  int[] errcode_ret)
      • clCreateProgramWithBinary

        public static cl_program clCreateProgramWithBinary​(cl_context context,
                                                           int num_devices,
                                                           cl_device_id[] device_list,
                                                           long[] lengths,
                                                           byte[][] binaries,
                                                           int[] binary_status,
                                                           int[] errcode_ret)

        Creates a program object for a context, and loads the binary bits specified by binary into the program object.

        cl_program clCreateProgramWithBinary ( cl_contextcontext,
        cl_uintnum_devices,
        const cl_device_id*device_list,
        const size_t*lengths,
        const unsigned char**binaries,
        cl_int*binary_status,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        device_list

        A pointer to a list of devices that are in context. device_list must be a non-NULL value. The binaries are loaded for devices specified in this list.

        num_devices

        The number of devices listed in device_list.

        The devices associated with the program object will be the list of devices specified by device_list. The list of devices specified by device_list must be devices associated with context.

        lengths

        An array of the size in bytes of the program binaries to be loaded for devices specified by device_list.

        binaries

        An array of pointers to program binaries to be loaded for devices specified by device_list. For each device given by device_list[i], the pointer to the program binary for that device is given by binaries[i] and the length of this corresponding binary is given by lengths[i]. lengths[i] cannot be zero and binaries[i] cannot be a NULL pointer.

        The program binaries specified by binaries contain the bits that describe the program executable that will be run on the device(s) associated with context. The program binary can consist of either or both of device-specific executable(s), and/or implementation-specific intermediate representation (IR) which will be converted to the device-specific executable.

        binary_status

        Returns whether the program binary for each device specified in device_list was loaded successfully or not. It is an array of num_devices entries and returns CL_SUCCESS in binary_status[i] if binary was successfully loaded for device specified by device_list[i]; otherwise returns CL_INVALID_VALUE if lengths[i] is zero or if binaries[i] is a NULL value or CL_INVALID_BINARY in binary_status[i] if program binary is not a valid binary for the specified device. If binary_status is NULL, it is ignored.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        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.

        Errors

        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; or if lengths or binaries are NULL or if any entry in lengths[i] or binaries[i] is NULL.
        • CL_INVALID_DEVICE if OpenCL devices listed in device_list are not in the list of devices associated with context.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateProgramWithBinaryNative

        private static cl_program clCreateProgramWithBinaryNative​(cl_context context,
                                                                  int num_devices,
                                                                  cl_device_id[] device_list,
                                                                  long[] lengths,
                                                                  byte[][] binaries,
                                                                  int[] binary_status,
                                                                  int[] errcode_ret)
      • clCreateProgramWithBuiltInKernels

        public static cl_program clCreateProgramWithBuiltInKernels​(cl_context context,
                                                                   int num_devices,
                                                                   cl_device_id[] device_list,
                                                                   java.lang.String kernel_names,
                                                                   int[] errcode_ret)

        Creates a program object for a context, and loads the information related to the built-in kernels into a program object.

        cl_program clCreateProgramWithBuiltInKernels ( cl_contextcontext,
        cl_uintnum_devices,
        const cl_device_id*device_list,
        const char*kernel_names,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        num_devices

        The number of devices listed in device_list.

        device_list

        A pointer to a list of devices that are in context. device_list must be a non-NULL value. The built-in kernels are loaded for devices specified in this 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.

        kernel_names

        A semi-colon separated list of built-in kernel names.

        Errors

        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_VALUE if kernel_names is NULL or kernel_names contains a kernel name that is not supported by any of the devices in device_list.
        • CL_INVALID_DEVICE if devices listed in device_list are not in the list of devices associated with context.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clCreateProgramWithBuiltInKernelsNative

        private static cl_program clCreateProgramWithBuiltInKernelsNative​(cl_context context,
                                                                          int num_devices,
                                                                          cl_device_id[] device_list,
                                                                          java.lang.String kernel_names,
                                                                          int[] errcode_ret)
      • clRetainProgram

        public static int clRetainProgram​(cl_program program)

        Increments the program reference count.

        cl_int clRetainProgram ( cl_programprogram)

        Errors

        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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainProgramNative

        private static int clRetainProgramNative​(cl_program program)
      • clReleaseProgram

        public static int clReleaseProgram​(cl_program program)

        Decrements the program reference count.

        cl_int clReleaseProgram ( cl_programprogram)

        Notes

        The program object is deleted after all kernel objects associated with program have been deleted and the program reference count becomes zero.

        Errors

        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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clReleaseProgramNative

        private static int clReleaseProgramNative​(cl_program program)
      • clBuildProgram

        public static int clBuildProgram​(cl_program program,
                                         int num_devices,
                                         cl_device_id[] device_list,
                                         java.lang.String options,
                                         BuildProgramFunction pfn_notify,
                                         java.lang.Object user_data)

        Builds (compiles and links) a program executable from the program source or binary.

        cl_int clBuildProgram ( cl_programprogram,
        cl_uintnum_devices,
        const cl_device_id*device_list,
        const char*options,
        void(CL_CALLBACK *pfn_notify)(cl_program program, void *user_data),
        void*user_data)

        Parameters

        program

        The program object

        device_list

        A pointer to a list of devices associated with program. If device_list is NULL value, the program executable is built for all devices associated with program for which a source or binary has been loaded. If device_list is a non-NULL value, the program executable is built for devices specified in this list for which a source or binary has been loaded.

        num_devices

        The number of devices listed in device_list.

        options

        A pointer to a null-terminated string of characters that describes the build options to be used for building the program executable. The list of supported options is described in "Build Options" below.

        pfn_notify

        A function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully). If pfn_notify is not NULL, clBuildProgram does not need to wait for the build to complete and can return immediately. If pfn_notify is NULL, clBuildProgram does not return until the build has completed. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe.

        user_data

        Passed as an argument when pfn_notify is called. user_data can be NULL.

        Notes

        OpenCL allows program executables to be built using the source or the binary. clBuildProgram must be called for program created using either clCreateProgramWithSource or clCreateProgramWithBinary to build the program executable for one or more devices associated with program.

        The build options are categorized as pre-processor options, options for math intrinsics, options that control optimization and miscellaneous options. This specification defines a standard set of options that must be supported by an OpenCL compiler when building program executables online or offline. These may be extended by a set of vendor- or platform-specific options.

        Preprocessor Options

        These options control the OpenCL preprocessor which is run on each program source before actual compilation. -D options are processed in the order they are given in the options argument to clBuildProgram.
        -D name

        Predefine name as a macro, with definition 1.

        -D name=definition

        The contents of definition are tokenized and processed as if they appeared during translation phase three in a `#define' directive. In particular, the definition will be truncated by embedded newline characters.

        -I dir

        Add the directory dir to the list of directories to be searched for header files.


        Math Intrinsics Options

        These options control compiler behavior regarding floating-point arithmetic. These options trade off between speed and correctness.
        -cl-single-precision-constant

        Treat double precision floating-point constant as single precision constant.

        -cl-denorms-are-zero

        This option controls how single precision and double precision denormalized numbers are handled. If specified as a build option, the single precision denormalized numbers may be flushed to zero; double precision denormalized numbers may also be flushed to zero if the optional extension for double precsion is supported. This is intended to be a performance hint and the OpenCL compiler can choose not to flush denorms to zero if the device supports single precision (or double precision) denormalized numbers.

        This option is ignored for single precision numbers if the device does not support single precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_SINGLE_FP_CONFIG.

        This option is ignored for double precision numbers if the device does not support double precision or if it does support double precison but CL_FP_DENORM bit is not set in CL_DEVICE_DOUBLE_FP_CONFIG.

        This flag only applies for scalar and vector single precision floating-point variables and computations on these floating-point variables inside a program. It does not apply to reading from or writing to image objects.


        Optimization Options

        These options control various sorts of optimizations. Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program.
        -cl-opt-disable

        This option disables all optimizations. The default is optimizations are enabled.

        -cl-strict-aliasing

        This option allows the compiler to assume the strictest aliasing rules.

        The following options control compiler behavior regarding floating-point arithmetic. These options trade off between performance and correctness and must be specifically enabled. These options are not turned on by default since it can result in incorrect output for programs which depend on an exact implementation of IEEE 754 rules/specifications for math functions.

        -cl-mad-enable

        Allow a * b + c to be replaced by a mad. The mad computes a * b + c with reduced accuracy. For example, some OpenCL devices implement mad as truncate the result of a * b before adding it to c.

        -cl-no-signed-zeros

        Allow optimizations for floating-point arithmetic that ignore the signedness of zero. IEEE 754 arithmetic specifies the distinct behavior of +0.0 and -0.0 values, which then prohibits simplification of expressions such as x+0.0 or 0.0*x (even with -clfinite-math only). This option implies that the sign of a zero result isn't significant.

        -cl-unsafe-math-optimizations

        Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid, (b) may violate IEEE 754 standard and (c) may violate the OpenCL numerical compliance requirements as defined in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5. This option includes the -cl-no-signed-zeros and -cl-mad-enable options.

        -cl-finite-math-only

        Allow optimizations for floating-point arithmetic that assume that arguments and results are not NaNs or ∞. This option may violate the OpenCL numerical compliance requirements defined in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5.

        -cl-fast-relaxed-math

        Sets the optimization options -cl-finite-math-only and -cl-unsafe-math-optimizations. This allows optimizations for floating-point arithmetic that may violate the IEEE 754 standard and the OpenCL numerical compliance requirements defined in the specification in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5. This option causes the preprocessor macro __FAST_RELAXED_MATH__ to be defined in the OpenCL program.


        Options to Request or Suppress Warnings

        Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there may have been an error. The following languageindependent options do not enable specific warnings but control the kinds of diagnostics produced by the OpenCL compiler.
        -w

        Inhibit all warning messages.

        -Werror

        Make all warnings into errors.


        Options Controlling the OpenCL C Version

        The following option controls the version of OpenCL C that the compiler accepts.
        -cl-std=

        Determine the OpenCL C language version to use. A value for this option must be provided. Valid values are:

        CL1.1 - Support all OpenCL C programs that use the OpenCL C language features defined in section 6 of the OpenCL 1.1 specification.

        Calls to clBuildProgram with the -cl-std=CL1.1 option will fail to build the program executable for any devices with CL_DEVICE_OPENCL_C_VERSION = OpenCL C 1.0.

        If the -cl-std build option is not specified, the CL_DEVICE_OPENCL_C_VERSION is used to select the version of OpenCL C to be used when building the program executable for each device.

        Errors

        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 clCreateWithProgramWithBinary 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 the table of OpenCL Device Queries for clGetDeviceInfo 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • obtainBuildLogs

        private static java.lang.String obtainBuildLogs​(cl_program program)
        Obtain a single String containing the build logs of the given program for all devices that are associated with the given program object.
        Parameters:
        program - The program object
        Returns:
        The build logs, as a single string.
      • clBuildProgramNative

        private static int clBuildProgramNative​(cl_program program,
                                                int num_devices,
                                                cl_device_id[] device_list,
                                                java.lang.String options,
                                                BuildProgramFunction pfn_notify,
                                                java.lang.Object user_data)
      • clCompileProgram

        public static int clCompileProgram​(cl_program program,
                                           int num_devices,
                                           cl_device_id[] device_list,
                                           java.lang.String options,
                                           int num_input_headers,
                                           cl_program[] input_headers,
                                           java.lang.String[] header_include_names,
                                           BuildProgramFunction pfn_notify,
                                           java.lang.Object user_data)

        Compiles a programs source for all the devices or a specific device(s) in the OpenCL context associated with program.

        cl_int clCompileProgram ( cl_programprogram,
        cl_uintnum_devices,
        const cl_device_id*device_list,
        const char*options,
        cl_uintnum_input_heaaders,
        const cl_program*input_heaaders,
        const char**heaader_include_names,
        void(CL_CALLBACK *pfn_notify)( cl_program program, void *user_data),
        void*user_data)

        Parameters

        program

        The program object that is the compilation target.

        device_list

        A pointer to a list of devices associated with program. If device_list is a NULL value, the compile is performed for all devices associated with program. If device_list is a non-NULL value, the compile is performed for devices specified in this list.

        num_devices

        The number of devices listed in device_list.

        options

        A pointer to a null-terminated string of characters that describes the compilation options to be used for building the program executable. The list of supported options is as described below.

        num_input_headers

        Specifies the number of programs that describe headers in the array referenced by input_headers.

        input_headers

        An array of program embedded headers created with clCreateProgramWithSource.

        header_include_names

        An array that has a one to one correspondence with input_headers. Each entry in header_include_names specifies the include name used by source in program that comes from an embedded header. The corresponding entry in input_headers identifies the program object which contains the header source to be used. The embedded headers are first searched before the headers in the list of directories specified by the -I compile option (as described in section 5.6.4.1). If multiple entries in header_include_names refer to the same header name, the first one encountered will be used.

        pfn_notify

        A function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully). If pfn_notify is not NULL, clCompileProgram does not need to wait for the compiler to complete and can return immediately once the compilation can begin. The compilation can begin if the context, program whose sources are being compiled, list of devices, input headers, programs that describe input headers and compiler options specified are all valid and appropriate host and device resources needed to perform the compile are available. If pfn_notify is NULL, clCompileProgram does not return until the compiler has completed. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe.

        user_data

        Passed as an argument when pfn_notify is called. user_data can be NULL.

        Notes

        Compiles a program's source for all the devices or a specific device(s) in the OpenCL context associated with program. The pre-processor runs before the program sources are compiled. The compiled binary is built for all devices associated with program or the list of devices specified. The compiled binary can be queried using clGetProgramInfo(program, CL_PROGRAM_BINARIES, ...) and can be specified to clCreateProgramWithBinary to create a new program object.

        Compiler Options

        The compiler options are categorized as pre-processor options, options for math intrinsics, options that control optimization and miscellaneous options. This specification defines a standard set of options that must be supported by the OpenCL C compiler when building program executables online or offline. These may be extended by a set of vendor- or platform specific options.

        Preprocessor Options

        These options control the OpenCL C preprocessor which is run on each program source before actual compilation.

        -D options are processed in the order they are given in the options argument to clBuildProgram or or clCompileProgram.

        -D name

        Predefine name as a macro, with definition 1.

        -D name=definition

        The contents of definition are tokenized and processed as if they appeared during translation phase three in a `#define' directive. In particular, the definition will be truncated by embedded newline characters.

        -I dir

        Add the directory dir to the list of directories to be searched for header files.

        Math Intrinsics Options

        These options control compiler behavior regarding floating-point arithmetic. These options trade off between speed and correctness.
        -cl-single-precision-constant

        Treat double precision floating-point constant as single precision constant.

        -cl-denorms-are-zero

        This option controls how single precision and double precision denormalized numbers are handled. If specified as a build option, the single precision denormalized numbers may be flushed to zero; double precision denormalized numbers may also be flushed to zero if the optional extension for double precsion is supported. This is intended to be a performance hint and the OpenCL compiler can choose not to flush denorms to zero if the device supports single precision (or double precision) denormalized numbers.

        This option is ignored for single precision numbers if the device does not support single precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_SINGLE_FP_CONFIG.

        This option is ignored for double precision numbers if the device does not support double precision or if it does support double precison but CL_FP_DENORM bit is not set in CL_DEVICE_DOUBLE_FP_CONFIG.

        This flag only applies for scalar and vector single precision floating-point variables and computations on these floating-point variables inside a program. It does not apply to reading from or writing to image objects.

        -cl-fp32-correctly-rounded-divide-sqrt

        The -cl-fp32-correctly-rounded-divide-sqrt build option to clBuildProgram or clCompileProgram allows an application to specify that single precision floating-point divide (x/y and 1/x) and sqrt used in the program source are correctly rounded. If this build option is not specified, the minimum numerical accuracy of single precision floating-point divide and sqrt are as defined in section 7.4 of the OpenCL specification.

        This build option can only be specified if the CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT is set in CL_DEVICE_SINGLE_FP_CONFIG (as defined in in the table of allowed values for param_name for clGetDeviceInfo) for devices that the program is being build. clBuildProgram or clCompileProgram will fail to compile the program for a device if the -cl-fp32-correctly-rounded-divide-sqrt option is specified and CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT is not set for the device.

        Optimization Options

        These options control various sorts of optimizations. Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program.

        -cl-opt-disable

        This option disables all optimizations. The default is optimizations are enabled.

        The following options control compiler behavior regarding floating-point arithmetic. These options trade off between performance and correctness and must be specifically enabled. These options are not turned on by default since it can result in incorrect output for programs which depend on an exact implementation of IEEE 754 rules/specifications for math functions.

        -cl-mad-enable

        Allow a * b + c to be replaced by a mad. The mad computes a * b + c with reduced accuracy. For example, some OpenCL devices implement mad as truncate the result of a * b before adding it to c.

        -cl-no-signed-zeros

        Allow optimizations for floating-point arithmetic that ignore the signedness of zero. IEEE 754 arithmetic specifies the distinct behavior of +0.0 and -0.0 values, which then prohibits simplification of expressions such as x+0.0 or 0.0*x (even with -clfinite-math only). This option implies that the sign of a zero result isn't significant.

        -cl-unsafe-math-optimizations

        Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid, (b) may violate IEEE 754 standard and (c) may violate the OpenCL numerical compliance requirements as defined in section 7.4 for single precision and double precision floating-point, and edge case behavior in section 7.5. This option includes the -cl-no-signed-zeros and -cl-mad-enable options.

        -cl-finite-math-only

        Allow optimizations for floating-point arithmetic that assume that arguments and results are not NaNs or ∞. This option may violate the OpenCL numerical compliance requirements defined in section 7.4 for single precision and double precision floating point, and edge case behavior in section 7.5.

        -cl-fast-relaxed-math

        Sets the optimization options -cl-finite-math-only and -cl-unsafe-math-optimizations. This allows optimizations for floating-point arithmetic that may violate the IEEE 754 standard and the OpenCL numerical compliance requirements defined in the specification in section 7.4 for single-precision and double precision floating-point, and edge case behavior in section 7.5. This option causes the preprocessor macro __FAST_RELAXED_MATH__ to be defined in the OpenCL program.

        Options to Request or Suppress Warnings

        Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there may have been an error. The following languageindependent options do not enable specific warnings but control the kinds of diagnostics produced by the OpenCL compiler.
        -w

        Inhibit all warning messages.

        -Werror

        Make all warnings into errors.

        Options Controlling the OpenCL C Version

        The following option controls the version of OpenCL C that the compiler accepts.
        -cl-std=

        Determine the OpenCL C language version to use. A value for this option must be provided. Valid values are:

        CL1.1 - Support all OpenCL C programs that use the OpenCL C language features defined in section 6 of the OpenCL 1.1 specification.

        CL1.2 - Support all OpenCL C programs that use the OpenCL C language features defined in section 6 of the OpenCL 1.2 specification.

        Calls to clBuildProgram or clCompileProgram with the -cl-std=CL1.1 option will fail to compile the program for any devices with CL_DEVICE_OPENCL_C_VERSION = OpenCL C 1.0. Calls to clBuildProgram or clCompileProgram with the -cl-std=CL1.2 option will fail to compile the program for any devices with CL_DEVICE_OPENCL_C_VERSION = OpenCL C 1.0 or OpenCL C 1.1.

        If the -cl-std build option is not specified, the CL_DEVICE_OPENCL_C_VERSION is used to select the version of OpenCL C to be used when compiling the program for each device.

        Options for Querying Kernel Argument Information

        -cl-kernel-arg-info

        This option allows the compiler to store information about the arguments of a kernel(s) in the program executable. The argument information stored includes the argument name, its type, the address and access qualifiers used. Refer to description of clGetKernelArgInfo on how to query this information.

        Linker Options

        This specification defines a standard set of linker options that must be supported by the OpenCL C compiler when linking compiled programs online or offline. These linker options are categorized as library linking options and program linking options. These may be extended by a set of vendor- or platform-specific options.

        Library Linking Options

        The following options can be specified when creating a library of compiled binaries.
        -create-library

        Create a library of compiled binaries specified in input_programs argument to clLinkProgram.

        -enable-link-options

        Allows the linker to modify the library behavior based on one or more link options (described in Program Linking Options, below) when this library is linked with a program executable. This option must be specified with the -create-library option.

        Program Linking Options

        The following options can be specified when linking a program executable.
        • -cl-denorms-are-zero
        • -cl-no-signed-zeroes
        • -cl-unsafe-math-optimizations
        • -cl-finite-math-only
        • -cl-fast-relaxed-mat
        The linker may apply these options to all compiled program objects specified to clLinkProgram. The linker may apply these options only to libraries which were created with the -enable-link-option.

        Separate Compilation and Linking of Programs

        OpenCL 1.2 extends how programs are compiled and linked to support the following:

        • Separate compilation and link stages. Program sources can be compiled to generate a compiled binary object and linked in a separate stage with other compiled program objects to the program exectuable.
        • Embedded headers. In OpenCL 1.0 and 1.1, the -I build option could be used to specify the list of directories to be searched for headers files that are included by a program source(s). OpenCL 1.2 extends this by allowing the header sources to come from program objects instead of just header files.
        • Libraries. The linker can be used to link compiled objects and libraries into a program executable or to create a library of compiled binarie

        Errors

        clCompileProgram 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 num_input_headers is zero and header_include_names or input_headers are not NULL or if num_input_headers is not zero and header_include_names or input_headers are NULL.
        • 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_COMPILER_OPTIONS if the compiler options specified by options are invalid.
        • CL_INVALID_OPERATION if the compilation or build of a program executable for any of the devices listed in device_list by a previous call to clCompileProgram or clBuildProgram for program has not completed.
        • CL_COMPILER_NOT_AVAILABLE if a compiler is not available i.e. CL_DEVICE_COMPILER_AVAILABLE specified in in the table of allowed values for param_name for clGetDeviceInfo is set to CL_FALSE.
        • CL_COMPILE_PROGRAM_FAILURE if there is a failure to compile the program source. This error will be returned if clCompileProgram does not return until the compile has completed.
        • CL_INVALID_OPERATION if there are kernel objects attached to program.
        • CL_INVALID_OPERATION if program has no source i.e. it has not been created with clCreateProgramWithSource.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Example

        For example, consider the following program source:

        #include <foo.h> #include <mydir/myinc.h> __kernel void image_filter (int n, int m, __constant float *filter_weights, __read_only image2d_t src_image, __write_only image2d_t dst_image) { ... }

        This kernel includes two headers foo.h and mydir/myinc.h. The following describes how these headers can be passed as embedded headers in program objects:

        cl_program foo_pg = clCreateProgramWithSource(context, 1, &foo_header_src, NULL, &err); cl_program myinc_pg = clCreateProgramWithSource(context, 1, &myinc_header_src, NULL, &err); // let's assume the program source described above is given // by program_A and is loaded via clCreateProgramWithSource cl_program input_headers[2] = { foo_pg, myinc_pg }; char * input_header_names[2] = { "foo.h", "mydir/myinc.h" }; clCompileProgram(program_A, 0, NULL, // num_devices & device_list NULL, // compile_options 2, // num_input_headers input_headers, input_header_names, NULL, NULL); // pfn_notify & user_data
        Since:
        OpenCL 1.2
      • clCompileProgramNative

        private static int clCompileProgramNative​(cl_program program,
                                                  int num_devices,
                                                  cl_device_id[] device_list,
                                                  java.lang.String options,
                                                  int num_input_headers,
                                                  cl_program[] input_headers,
                                                  java.lang.String[] header_include_names,
                                                  BuildProgramFunction pfn_notify,
                                                  java.lang.Object user_data)
      • clLinkProgram

        public static cl_program clLinkProgram​(cl_context context,
                                               int num_devices,
                                               cl_device_id[] device_list,
                                               java.lang.String options,
                                               int num_input_programs,
                                               cl_program[] input_programs,
                                               BuildProgramFunction pfn_notify,
                                               java.lang.Object user_data,
                                               int[] errcode_ret)

        Links a set of compiled program objects and libraries for all the devices or a specific device(s) in the OpenCL context and creates an executable.

        cl_program clLinkProgram ( cl_contextcontext,
        cl_uintnum_devices,
        const cl_device_id*device_list,
        const char*options,
        cl_uintnum_input_programs,
        const cl_program*input_programs,
        void(CL_CALLBACK *pfn_notify) (cl_program program, void *user_data),
        void*user_data,
        cl_int*errcode_ret)

        Parameters

        context

        Must be a valid OpenCL context.

        device_list

        A pointer to a list of devices that are in context. If device_list is a NULL value, the link is performed for all devices associated with context for which a compiled object is available. If device_list is a non-NULL value, the compile is performed for devices specified in this list for which a source has been loaded.

        num_devices

        The number of devices listed in device_list.

        options

        A pointer to a null-terminated string of characters that describes the link options to be used for building the program executable. See clBuildProgram for a list of supported compiler and linker options.

        num_input_programs

        Specifies the number of programs in array referenced by input_programs.

        input_programs

        An array of program objects that are compiled binaries or libraries that are to be linked to create the program executable. For each device in device_list or if device_list is NULL the list of devices associated with context, the following cases occur:

        • All programs specified by input_programs contain a compiled binary or library for the device. In this case, a link is performed to generate a program executable for this device.

        • None of the programs contain a compiled binary or library for that device. In this case, no link is performed and there will be no program executable generated for this device.

        • All other cases will return a CL_INVALID_OPERATION error.

        pfn_notify

        A function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully).

        If pfn_notify is not NULL, clLinkProgram does not need to wait for the linker to complete and can return immediately once the linking operation can begin. Once the linker has completed, the pfn_notify callback function is called which returns the program object returned by clLinkProgram. The application can query the link status and log for this program object. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe.

        If pfn_notify is NULL, clLinkProgram does not return until the linker has completed.

        user_data

        Will be passed as an argument when pfn_notify is called. user_data can be NULL.

        Notes

        clLinkProgram creates a new program object which contains this executable. The executable binary can be queried using clGetProgramInfo(program, CL_PROGRAM_BINARIES, ...) and can be specified to clCreateProgramWithBinary to create a new program object.

        The devices associated with the returned program object will be the list of devices specified by device_list or if device_list is NULL it will be the list of devices associated with context.

        The linking operation can begin if the context, list of devices, input programs and linker options specified are all valid and appropriate host and device resources needed to perform the link are available. If the linking operation can begin, clLinkProgram returns a valid non-zero program object.

        Errors

        If pfn_notify is NULL, the errcode_ret will be set to CL_SUCCESS if the link operation was successful and CL_LINK_FAILURE if there is a failure to link the compiled binaries and/or libraries.

        If pfn_notify is not NULL, clLinkProgram does not have to wait until the linker to complete and can return CL_SUCCESS in errcode_ret if the linking operation can begin. The pfn_notify callback function will return a CL_SUCCESS or CL_LINK_FAILURE if the linking operation was successful or not.

        Otherwise clLinkProgram returns a NULL program object with an appropriate error in errcode_ret. The application should query the linker status of this program object to check if the link was successful or not. The list of errors that can be returned are:

        • CL_INVALID_CONTEXT if context is not a valid context.
        • 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 num_input_programs is zero and input_programs is NULL or if num_input_programs is zero and input_programs is not NULL or if num_input_programs is not zero and input_programs is NULL.
        • CL_INVALID_PROGRAM if programs specified in input_programs are not valid program objects.
        • 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 context.
        • CL_INVALID_LINKER_OPTIONS if the linker options specified by options are invalid
        • CL_INVALID_OPERATION if the compilation or build of a program executable for any of the devices listed in device_list by a previous call to clCompileProgram or clBuildProgram for program has not completed.
        • CL_INVALID_OPERATION if the rules for devices containing compiled binaries or libraries as described in input_programs argument above are not followed.
        • CL_LINKER_NOT_AVAILABLE if a linker is not available i.e. CL_DEVICE_LINKER_AVAILABLE specified in the table of allowed values for param_name for clGetDeviceInfo is set to CL_FALSE.
        • CL_LINK_PROGRAM_FAILURE if there is a failure to link the compiled binaries and/or libraries.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clUnloadPlatformCompiler

        public static int clUnloadPlatformCompiler​(cl_platform_id platform)

        Allows the implementation to release the resources allocated by the OpenCL compiler for <>platform.

        cl_int clUnloadPlatformCompiler ( cl_platform_idplatform)

        Notes

        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, clCompileProgram, or clLinkProgram after clUnloadPlatformCompiler will reload the compiler, if necessary, to build the appropriate program executable.

        Errors

        clUnloadPlatformCompiler returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_PLATFORM if platform is not a valid platform.
        Since:
        OpenCL 1.2
      • clUnloadPlatformCompilerNative

        private static int clUnloadPlatformCompilerNative​(cl_platform_id platform)
      • clUnloadCompiler

        public static int clUnloadCompiler()
        Deprecated.
        As of OpenCL 1.2

        Allows the implementation to release the resources allocated by the OpenCL compiler.

        cl_int clUnloadCompiler ( void)

        Notes

        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.

        Errors

        This call currently always returns CL_SUCCESS.

      • clUnloadCompilerNative

        private static int clUnloadCompilerNative()
      • clGetProgramInfo

        public static int clGetProgramInfo​(cl_program program,
                                           int param_name,
                                           long param_value_size,
                                           Pointer param_value,
                                           long[] param_value_size_ret)

        Returns information about the program object.

        cl_int clGetProgramInfo ( cl_programprogram,
        cl_program_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        program

        Specifies the program object being queried.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramInfo is described in the table below.

        cl_program_info Return Type and Info. returned in param_value
        CL_PROGRAM_REFERENCE_COUNT Return type: cl_uint

        Return the program reference count.

        The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

        CL_PROGRAM_CONTEXT Return type: cl_context

        Return the context specified when the program object is created

        CL_PROGRAM_NUM_DEVICES Return type: cl_uint

        Return the number of devices associated with program.

        CL_PROGRAM_DEVICES Return type: cl_device_id[]

        Return the list of devices associated with the program object. This can be the devices associated with context on which the program object has been created or can be a subset of devices that are specified when a progam object is created using clCreateProgramWithBinary.

        CL_PROGRAM_SOURCE Return type: char[]

        Return the program source code specified by clCreateProgramWithSource. The source string returned is a concatenation of all source strings specified to clCreateProgramWithSource with a null terminator. The concatenation strips any nulls in the original source strings.

        The actual number of characters that represents the program source code including the null terminator is returned in param_value_size_ret.

        CL_PROGRAM_BINARY_SIZES Return type: size_t[]

        Returns an array that contains the size in bytes of the program binary for each device associated with 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 Return type: 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 allocated by the caller, where n is 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-to-one correspondence between the array of n pointers returned by CL_PROGRAM_BINARIES and array of devices returned by CL_PROGRAM_DEVICES.

        If an entry value in the array is NULL, the implementation skips copying the program binary for the specific device identified by the array index.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table above.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_PROGRAM if program is not a valid program object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetProgramInfoNative

        private static int clGetProgramInfoNative​(cl_program program,
                                                  int param_name,
                                                  long param_value_size,
                                                  Pointer param_value,
                                                  long[] param_value_size_ret)
      • clGetProgramBuildInfo

        public static int clGetProgramBuildInfo​(cl_program program,
                                                cl_device_id device,
                                                int param_name,
                                                long param_value_size,
                                                Pointer param_value,
                                                long[] param_value_size_ret)

        Returns build information for each device in the program object.

        cl_int clGetProgramBuildInfo ( cl_program program,
        cl_device_id device,
        cl_program_build_info param_name,
        size_t param_value_size,
        void *param_value,
        size_t *param_value_size_ret)

        Parameters

        program

        Specifies the program object being queried.

        device

        Specifies the device for which build information is being queried. device must be a valid device associated with program.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramBuildInfo is described in the table below.

        cl_program_buid_info Return Type and Info. returned in param_value
        CL_PROGRAM_BUILD_STATUS Return type: cl_build_status

        Returns the build status of 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 returned 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 Return type: 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 Return type: 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.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table above.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise it returns the following:

        • 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 less than size of return type and param_value is not NULL.
        • Returns CL_INVALID_PROGRAM if program is a not a valid program object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetProgramBuildInfoNative

        private static int clGetProgramBuildInfoNative​(cl_program program,
                                                       cl_device_id device,
                                                       int param_name,
                                                       long param_value_size,
                                                       Pointer param_value,
                                                       long[] param_value_size_ret)
      • clCreateKernel

        public static cl_kernel clCreateKernel​(cl_program program,
                                               java.lang.String kernel_name,
                                               int[] errcode_ret)

        Creates a kernal object.

        cl_kernel clCreateKernel ( cl_program program,
        const char*kernel_name,
        cl_int*errcode_ret)

        Parameters

        program

        A program object with a successfully built executable.

        kernel_name

        A function name in the program declared with the __kernel qualifier

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        A kernel is a function declared in a program. A kernel is identified by the __kernel qualifier applied to any function in a program. A kernel object encapsulates the specific __kernel function declared in a program and the argument values to be used when executing this __kernel function.

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateKernelNative

        private static cl_kernel clCreateKernelNative​(cl_program program,
                                                      java.lang.String kernel_name,
                                                      int[] errcode_ret)
      • clCreateKernelsInProgram

        public static int clCreateKernelsInProgram​(cl_program program,
                                                   int num_kernels,
                                                   cl_kernel[] kernels,
                                                   int[] num_kernels_ret)

        Creates kernel objects for all kernel functions in a program object.

        cl_int clCreateKernelsInProgram ( cl_program program,
        cl_uintnum_kernels,
        cl_kernel*kernels,
        cl_uint*num_kernels_ret)

        Parameters

        program

        A program object with a successfully built executable.

        num_kernels

        The size of memory pointed to by kernels specified as the number of cl_kernel entries.

        kernels

        The buffer where the kernel objects for kernels in program will be returned. If kernels is NULL, it is ignored. If kernels is not NULL, num_kernels must be greater than or equal to the number of kernels in program.

        num_kernels_ret

        The number of kernels in program. If num_kernels_ret is NULL, it is ignored.

        Notes

        Creates kernel objects for all kernel functions in program. Kernel objects are not created for any __kernel functions in program that do not have the same function definition across all devices for which a program executable has been successfully built.

        Kernel objects can only be created once you have a program object with a valid program source or binary loaded into the program object and the program executable has been successfully built for one or more devices associated with program. No changes to the program executable are allowed while there are kernel objects associated with a program object. This means that calls to clBuildProgram return CL_INVALID_OPERATION if there are kernel objects attached to a program object. The OpenCL context associated with program will be the context associated with kernel. The list of devices associated with program are the devices associated with kernel. Devices associated with a program object for which a valid program executable has been built can be used to execute kernels declared in the program object.

        Errors

        Returns CL_SUCCESS if the kernel objects are successfully allocated. Otherwise, it returns one of the following errors:

        • CL_INVALID_PROGRAM if program is not a valid program object.
        • CL_INVALID_PROGRAM_EXECUTABLE if there is no successfully built executable for any device in program.
        • CL_INVALID_VALUE if kernels is not NULL and num_kernels is less than the number of kernels in program.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateKernelsInProgramNative

        private static int clCreateKernelsInProgramNative​(cl_program program,
                                                          int num_kernels,
                                                          cl_kernel[] kernels,
                                                          int[] num_kernels_ret)
      • clRetainKernel

        public static int clRetainKernel​(cl_kernel kernel)

        Increments the kernel object reference count.

        cl_int clRetainKernel ( cl_kernelkernel)

        Notes

        clCreateKernel or clCreateKernelsInProgram do an implicit retain.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_KERNEL if kernel is not a valid kernel object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainKernelNative

        private static int clRetainKernelNative​(cl_kernel kernel)
      • clReleaseKernel

        public static int clReleaseKernel​(cl_kernel kernel)

        Decrements the kernel reference count.

        cl_int clReleaseKernel ( cl_kernelkernel)

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the kernel objects are successfully alloctaed. Otherwise, it returns one of the following errors:

        • CL_INVALID_KERNEL if kernel is not a valid kernel object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clReleaseKernelNative

        private static int clReleaseKernelNative​(cl_kernel kernel)
      • clSetKernelArg

        public static int clSetKernelArg​(cl_kernel kernel,
                                         int arg_index,
                                         long arg_size,
                                         Pointer arg_value)

        Used to set the argument value for a specific argument of a kernel.

        cl_int clSetKernelArg ( cl_kernelkernel,
        cl_uintarg_index,
        size_targ_size,
        const void*arg_value)

        Parameters

        kernel

        A valid kernel object.

        arg_index

        The argument index. Arguments to the kernel are referred by indices that go from 0 for the leftmost argument to n - 1, where n is the total number of arguments declared by a kernel.

        arg_value

        A pointer to data that should be used as the argument value for argument specified by arg_index. The argument data pointed to by arg_value is copied and the arg_value pointer can therefore be reused by the application after clSetKernelArg returns. The argument value specified is the value used by all API calls that enqueue kernel (clEnqueueNDRangeKernel and clEnqueueTask) until the argument value is changed by a call to clSetKernelArg for kernel.

        If the argument is a memory object (buffer or image), the arg_value entry will be a pointer to the appropriate buffer or image object. The memory object must be created with the context associated with the kernel object. A NULL value can also be specified if the argument is a buffer object in which case a NULL value will be used as the value for the argument declared as a pointer to __global or __constant memory in the kernel. If the argument is declared with the __local qualifier, the arg_value entry must be NULL. If the argument is of type sampler_t, the arg_value entry must be a pointer to the sampler object.

        If the argument is declared to be a pointer of a built-in or user defined type with the __global or __constant qualifier, the memory object specified as argument value must be a buffer object (or NULL). If the argument is declared with the __constant qualifier, the size in bytes of the memory object cannot exceed CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE and the number of arguments declared with the __constant qualifier cannot exceed CL_DEVICE_MAX_CONSTANT_ARGS.

        The memory object specified as argument value must be a 2D image object if the argument is declared to be of type image2d_t. The memory object specified as argument value must be a 3D image object if argument is declared to be of type image3d_t.

        For all other kernel arguments, the arg_value entry must be a pointer to the actual data to be used as argument value.

        arg_size

        Specifies the size of the argument value. If the argument is a memory object, the size is the size of the buffer or image object type. For arguments declared with the __local qualifier, the size specified will be the size in bytes of the buffer that must be allocated for the __local argument. If the argument is of type sampler_t, the arg_size value must be equal to sizeof(cl_sampler). For all other arguments, the size will be the size of argument type.

        Notes

        A kernel object does not update the reference count for objects such as memory, sampler objects specified as argument values by clSetKernelArg. Users may not rely on a kernel object to retain objects specified as argument values to the kernel.

        Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership rights on kernel args, that would make it impossible for the user to tell with certainty when he may safely release user allocated resources associated with OpenCL objects such as the cl_mem backing store used with CL_MEM_USE_HOST_PTR.

        An OpenCL API call is considered to be thread-safe if the internal state as managed by OpenCL remains consistent when called simultaneously by multiple host threads. OpenCL API calls that are thread-safe allow an application to call these functions in multiple host threads without having to implement mutual exclusion across these host threads i.e. they are also re-entrant-safe.

        All OpenCL API calls are thread-safe except clSetKernelArg, which is safe to call from any host thread, and is safe to call re-entrantly so long as concurrent calls operate on different cl_kernel objects. However, the behavior of the cl_kernel object is undefined if clSetKernelArg is called from multiple host threads on the same cl_kernel object at the same time.

        There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with clEnqueueNDRangeKernel or clEnqueueTask. Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. Rather than attempt to share cl_kernel objects among multiple host threads, applications are strongly encouraged to make additional cl_kernel objects for kernel functions for each host thread.

        Errors

        clSetKernelArg returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • 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).
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Example

        __kernel void image_filter (int n, int m, __constant float *filter_weights, __read_only image2d_t src_image, __write_only image2d_t dst_image) { ... }

        Argument index values for image_filter will be 0 for n, 1 for m, 2 for filter_weights, 3 for src_image and 4 for dst_image.

      • clSetKernelArgNative

        private static int clSetKernelArgNative​(cl_kernel kernel,
                                                int arg_index,
                                                long arg_size,
                                                Pointer arg_value)
      • clSetKernelArgSVMPointer

        public static int clSetKernelArgSVMPointer​(cl_kernel kernel,
                                                   int arg_index,
                                                   Pointer arg_value)

        Used to set a SVM pointer as the argument value for a specific argument of a kernel.

        cl_int clSetKernelArgSVMPointer ( cl_kernel kernel,
        cl_uint arg_index,
        const void *arg_value)

        Parameters

        kernel

        A valid kernel object.

        arg_index

        The argument index. Arguments to the kernel are referred by indices that go from 0 for the leftmost argument to n - 1, where n is the total number of arguments declared by a kernel.

        arg_value

        A pointer to the SVM pointer that should be used as the argument value for argument specified by arg_index. The SVM pointer specified is the value used by all API calls that enqueue kernel (clEnqueueNDRangeKernel) until the argument value is changed by a call to clSetKernelArgSVMPointer for kernel. The SVM pointer can only be used for arguments that are declared to be a pointer to global or constant memory. The SVM pointer value must be aligned according to the argument’s type. For example, if the argument is declared to be global float4 *p, the SVM pointer value passed for p must be at a minimum aligned to a float4. The SVM pointer value specified as the argument value can be the pointer returned by clSVMAlloc or can be a pointer + offset into the SVM region.

        Notes

        All OpenCL API calls are thread-safe except clSetKernelArg and clSetKernelArgSVMPointer. clSetKernelArg and clSetKernelArgSVMPointer are safe to call from any host thread, and safe to call re-entrantly so long as concurrent calls operate on different cl_kernel objects. However, the behavior of the cl_kernel object is undefined if clSetKernelArg or clSetKernelArgSVMPointer are called from multiple host threads on the same cl_kernel object at the same time. Please note that there are additional limitations as to which OpenCL APIs may be called from OpenCL callback functions -- please see section 5.11. (Please refer to the OpenCL glossary for the OpenCL definition of thread-safe. This definition may be different from usage of the term in other contexts.)

        There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with clEnqueueNDRangeKernel. Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. Rather than attempt to share cl_kernel objects among multiple host threads, applications are strongly encouraged to make additional cl_kernel objects for kernel functions for each host thread.

        Errors

        clSetKernelArgSVMPointer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • 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 not a valid value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clSetKernelArg, clCreateKernel, clCreateKernelsInProgram, clReleaseKernel, clRetainKernel, clGetKernelInfo, clGetKernelWorkGroupInfo

      • clSetKernelArgSVMPointerNative

        private static int clSetKernelArgSVMPointerNative​(cl_kernel kernel,
                                                          int arg_index,
                                                          Pointer arg_value)
      • clSetKernelExecInfo

        public static int clSetKernelExecInfo​(cl_kernel kernel,
                                              int param_name,
                                              long param_value_size,
                                              Pointer param_value)

        Used to pass additional information other than argument values to a kernel.

        cl_int clSetKernelExecInfo ( cl_kernel kernel ,
        cl_kernel_exec_info param_name ,
        size_t param_value_size ,
        const void *param_value )

        Parameters

        kernel

        Specifies the kernel object being queried.

        param_name

        Specifies the information to be passed to kernel. The list of supported param_name types and the corresponding values passed in param_value is described in the table below.

        param_value_size

        Specifies the size in bytes of the memory pointed to by param_value.

        param_value

        A pointer to memory where the appropriate values determined by param_name are specified.

        cl_kernel_exec_info Type Description
        CL_KERNEL_EXEC_INFO_SVM_PTRS void *[]

        SVM pointers used by a kernel which are not passed as arguments to kernel. These addresses may be defined in SVM buffer(s) that are passed as arguments to kernel.

        These non-argument SVM pointers must be specified using clSetKernelExecInfo for coarse-grain and fine-grain buffer SVM allocations but not for fine-grain system SVM allocations.

        CL_KERNEL_EXEC_INFO_SVM_- FINE_GRAIN_SYSTEM cl_bool

        This flag indicates whether the kernel uses pointers that are fine grain system SVM allocations. These fine grain system SVM pointers may be passed as arguments or defined in SVM buffers that are passed as argumentsto kernel.

        Notes

        1. Coarse-grain or fine-grain buffer SVM pointers used by a kernel which are not passed as a kernel arguments must be specified using clSetKernelExecInfo with CL_KERNEL_EXEC_INFO_SVM_PTRS. For example, if SVM buffer A contains a pointer to another SVM buffer B, and the kernel dereferences that pointer, then a pointer to B must either be passed as an argument in the call to that kernel or it must be made available to the kernel using clSetKernelExecInfo. For example, we might pass extra SVM pointers as follows:


        clSetKernelExecInfo(kernel,
        CL_KERNEL_EXEC_INFO_SVM_PTRS,
        num_ptrs * sizeof(void *),
        extra_svm_ptr_list);

        Here num_ptrs specifies the number of additional SVM pointers while extra_svm_ptr_list specifies a pointer to memory containing those SVM pointers.

        When calling clSetKernelExecInfo with CL_KERNEL_EXEC_INFO_SVM_PTRS to specify pointers to non-argument SVM buffers as extra arguments to a kernel, each of these pointers can be the SVM pointer returned by clSVMAlloc or can be a pointer + offset into the SVM region. It is sufficient to provide one pointer for each SVM buffer used.

        2. CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM is used to indicate whether SVM pointers used by a kernel will refer to system allocations or not.

        CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM = CL_FALSE indicates that the OpenCL implementation may assume that system pointers are not passed as kernel arguments and are not stored inside SVM allocations passed as kernel arguments.

        CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM = CL_TRUE indicates that the OpenCL implementation must assume that system pointers might be passed as kernel arguments and/or stored inside SVM allocations passed as kernel arguments. In this case, if the device to which the kernel is enqueued does not support system SVM pointers, clEnqueueNDRangeKernel will return a CL_INVALID_OPERATION error. If none of the devices in the context associated with kernel support fine-grain system SVM allocations, clSetKernelExecInfo will return a CL_INVALID_OPERATION error.

        If clSetKernelExecInfo has not been called with a value for CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM the default value is used for this kernel attribute. The defaule value depends on whether the device on which the kernel is enqueued supports fine-grain system SVM allocations. If so, the default value used is CL_TRUE (system pointers might be passed); otherwise, the default is CL_FALSE.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_KERNEL if kernel is not a valid kernel object.
        • CL_INVALID_VALUE if param_name is not valid, if param_value is NULL or if the size specified by param_value_size is not valid.
        • CL_INVALID_OPERATION if param_name = CL_KERNEL_EXEC_INFO_SVM_FINE_GRAIN_SYSTEM and param_value = CL_TRUE but no devices in context associated with kernel support fine-grain system SVM allocations.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        clCreateKernel, clGetKernelInfo, clGetKernelArgInfo, clCreateKernelsInProgram, clSetKernelArg, clGetKernelWorkGroupInfo, clEnqueueNDRangeKernel

      • clSetKernelExecInfoNative

        private static int clSetKernelExecInfoNative​(cl_kernel kernel,
                                                     int param_name,
                                                     long param_value_size,
                                                     Pointer param_value)
      • clGetKernelInfo

        public static int clGetKernelInfo​(cl_kernel kernel,
                                          int param_name,
                                          long param_value_size,
                                          Pointer param_value,
                                          long[] param_value_size_ret)

        Returns information about the kernel object.

        cl_int clGetKernelInfo ( cl_kernelkernel,
        cl_kernel_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        kernel

        Specifies the kernel object being queried.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetKernelInfo is described in the table below.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to size of return type as described in the table below.

        cl_kernel_info Return Type Info. returned in param_value
        CL_KERNEL_FUNCTION_NAME char[] Return the kernel function name.
        CL_KERNEL_NUM_ARGS cl_uint Return the number of arguments to kernel.
        CL_KERNEL_REFERENCE_COUNT cl_uint

        Return the kernel reference count.

        The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

        CL_KERNEL_CONTEXT cl_context Return the context associated with kernel.
        CL_KERNEL_PROGRAM cl_program Return the program object associated with kernel.
        param_value_size_ret

        the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL
        • CL_INVALID_KERNEL if kernel is not a valid kernel object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetKernelInfoNative

        private static int clGetKernelInfoNative​(cl_kernel kernel,
                                                 int param_name,
                                                 long param_value_size,
                                                 Pointer param_value,
                                                 long[] param_value_size_ret)
      • clGetKernelArgInfo

        public static int clGetKernelArgInfo​(cl_kernel kernel,
                                             int arg_indx,
                                             int param_name,
                                             long param_value_size,
                                             Pointer param_value,
                                             long[] param_value_size_ret)

        Returns information about the arguments of a kernel.

        cl_int clGetKernelArgInfo ( cl_kernel kernel ,
        cl_uint arg_indx ,
        cl_kernel_arg_info param_name ,
        size_t param_value_size ,
        void *param_value ,
        size_t *param_value_size_ret )

        Parameters

        kernel

        Specifies the kernel object being queried.

        arg_indx

        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.

        param_name

        Specifies the argument information to query. The list of supported param_name types and the information returned in param_value by clGetKernelArgInfo is described in the table below.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be > size of return type as described in the table below.

        cl_kernel_arg_info Return Type Info. returned in param_value
        CL_KERNEL_ARG_ADDRESS_QUALIFIER cl_kernel_arg_- address_qualifier

        Returns the address qualifier specified for the argument given by arg_indx. This can be one of the following values:


        CL_KERNEL_ARG_ADDRESS_GLOBAL
        CL_KERNEL_ARG_ADDRESS_LOCAL
        CL_KERNEL_ARG_ADDRESS_CONSTANT
        CL_KERNEL_ARG_ADDRESS_PRIVATE

        If no address qualifier is specified, the default address qualifier which is CL_KERNEL_ARG_ADDRESS_PRIVATE is returned.

        CL_KERNEL_ARG_ACCESS_QUALIFIER cl_kernel_arg_- access_qualifier

        Returns the access qualifier specified for the argument given by arg_indx. This can be one of the following values:


        CL_KERNEL_ARG_ACCESS_READ_ONLY
        CL_KERNEL_ARG_ACCESS_WRITE_ONLY
        CL_KERNEL_ARG_ACCESS_READ_WRITE
        CL_KERNEL_ARG_ACCESS_NONE

        If argument is not an image type, CL_KERNEL_ARG_ACCESS_NONE is returned. If argument is an image type, the access qualifier specified or the default access qualifier is returned.

        CL_KERNEL_ARG_TYPE_NAME char[]

        Returns the type name specified for the argument given by arg_indx. The type name returned will be the argument type name as it was declared with any whitespace removed. If argument type name is an unsigned scalar type (i.e. unsigned char, unsigned short, unsigned int, unsigned long), uchar, ushort, uint and ulong will be returned. The argument type name returned does not include any type qualifiers.

        CL_KERNEL_ARG_TYPE_QUALIFIER cl_kernel_arg- type_qualifier

        Returns the type qualifier specified for the argument given by arg_indx. The returned value can be: CL_KERNEL_ARG_TYPE_CONST, CL_KERNEL_ARG_TYPE_RESTRICT, CL_KERNEL_ARG_TYPE_VOLATILE, a combination of the above enums or CL_KERNEL_ARG_TYPE_NONE.

        NOTE: CL_KERNEL_ARG_TYPE_VOLATILE is returned if the argument is a pointer and the pointer is declared with the volatile qualifier.

        CL_KERNEL_ARG_NAME char[]

        Returns the name specified for the argument given by arg_indx.

        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.

        Notes

        Kernel argument information is only available if the program object associated with kernel is created with clCreateProgramWithSource and the program executable is built with the -cl-kernel-arg-info option specified in options argument to clBuildProgram or clCompileProgram.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_ARG_INDEX if arg_indx is not a valid argument index.
        • 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 the table above and param_value is not NULL
        • CL_KERNEL_ARG_INFO_NOT_AVAILABLE if the argument information is not available for kernel.
        • CL_INVALID_KERNEL if kernel is not a valid kernel object.
        Since:
        OpenCL 1.2
      • clGetKernelArgInfoNative

        private static int clGetKernelArgInfoNative​(cl_kernel kernel,
                                                    int arg_indx,
                                                    int param_name,
                                                    long param_value_size,
                                                    Pointer param_value,
                                                    long[] param_value_size_ret)
      • clGetKernelWorkGroupInfo

        public static int clGetKernelWorkGroupInfo​(cl_kernel kernel,
                                                   cl_device_id device,
                                                   int param_name,
                                                   long param_value_size,
                                                   Pointer param_value,
                                                   long[] param_value_size_ret)

        Returns information about the kernel object that may be specific to a device.

        cl_int clGetKernelWorkGroupInfo ( cl_kernelkernel,
        cl_device_iddevice,
        cl_kernel_work_group_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        kernel

        Specifies the kernel object being queried.

        device

        Identifies a specific device in the list of devices associated with kernel. The list of devices is the list of devices in the OpenCL context that is associated with kernel. If the list of devices associated with kernel is a single device, device can be a NULL value.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetKernelWorkGroupInfo is described in the table below.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Used to specify the size in bytes of memory pointed to by param_value. This size must be greater than or equal to size of return type as described in the table below.

        cl_kernel_work_group_info Return Type Info. returned in param_value
        CL_KERNEL_WORK_GROUP_SIZE size_t This provides a mechanism for the application to query the maximum work-group size that can be used to execute a kernel on a specific device given by device. The OpenCL implementation uses the resource requirements of the kernel (register usage etc.) to determine what this work-group size should be.
        CL_KERNEL_COMPILE_WORK_GROUP_SIZE size_t[3] Returns the work-group size specified by the __attribute__((reqd_work_gr oup_size(X, Y, Z))) qualifier. See Function Qualifiers. If the work-group size is not specified using the above attribute qualifier (0, 0, 0) is returned.
        CL_KERNEL_LOCAL_MEM_SIZE cl_ulong

        Returns the amount of local memory in bytes being used by a kernel. This includes local memory that may be needed by an implementation to execute the kernel, variables declared inside the kernel with the __local address qualifier and local memory to be allocated for arguments to the kernel declared as pointers with the __local address qualifier and whose size is specified with clSetKernelArg.

        If the local memory size, for any pointer argument to the kernel declared with the __local address qualifier, is not specified, its size is assumed to be 0.

        CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE size_t Returns the preferred multiple of workgroup size for launch. This is a performance hint. Specifying a workgroup size that is not a multiple of the value returned by this query as the value of the local work size argument to clEnqueueNDRangeKernelwill not fail to enqueue the kernel for execution unless the work-group size specified is larger than the device maximum.
        CL_KERNEL_PRIVATE_MEM_SIZE cl_ulong Returns the minimum amount of private memory, in bytes, used by each workitem in the kernel. This value may include any private memory needed by an implementation to execute the kernel, including that used by the language built-ins and variable declared inside the kernel with the __private qualifier.
        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • 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.
        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_KERNEL if kernel is a not a valid kernel object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetKernelWorkGroupInfoNative

        private static int clGetKernelWorkGroupInfoNative​(cl_kernel kernel,
                                                          cl_device_id device,
                                                          int param_name,
                                                          long param_value_size,
                                                          Pointer param_value,
                                                          long[] param_value_size_ret)
      • clWaitForEvents

        public static int clWaitForEvents​(int num_events,
                                          cl_event[] event_list)

        Waits on the host thread for commands identified by event objects to complete.

        cl_int clWaitForEvents ( cl_uintnum_events,
        const cl_event*event_list)

        Parameters

        event_list

        The events specified in event_list act as synchronization points.

        Notes

        Waits on the host thread for commands identified by event objects in event_list to complete. A command is considered complete if its execution status is CL_COMPLETE or a negative value.

        If the cl_khr_gl_event extension is enabled, event objects can also be used to reflect the status of an OpenGL sync object. The sync object in turn refers to a fence command executing in an OpenGL command stream. This provides another method of coordinating sharing of buffers and images between OpenGL and OpenCL.

        Errors

        Returns CL_SUCCESS if the execution status of all events in event_list is CL_COMPLETE. Otherwise, it returns one of the following errors:

        • CL_INVALID_VALUE if num_events is zero or event_list is NULL..
        • CL_INVALID_CONTEXT if events specified in event_list do not belong to the same context.
        • CL_INVALID_EVENT if event objects specified in event_list are not valid event objects.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the execution status of any of the events in event_list is a negative integer value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clWaitForEventsNative

        private static int clWaitForEventsNative​(int num_events,
                                                 cl_event[] event_list)
      • clGetEventInfo

        public static int clGetEventInfo​(cl_event event,
                                         int param_name,
                                         long param_value_size,
                                         Pointer param_value,
                                         long[] param_value_size_ret)

        Returns information about the event object.

        cl_int clGetEventInfo ( cl_eventevent,
        cl_event_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        event

        Specifies the event object being queried.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of the return type as described in the table below.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        param_name

        Specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetEventInfo is described in the table below:

        cl_event_info Return Type Information returned in param_value
        CL_EVENT_COMMAND_QUEUE cl_command_queue Return the command-queue associated with event. For user event objects, a NULL value is returned.
        CL_EVENT_CONTEXT cl_context Return the context associated with event.
        CL_EVENT_COMMAND_TYPE cl_command_type Return the command associated with event. Can be one of the following values:

        CL_COMMAND_NDRANGE_KERNEL
        CL_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_COMMAND_READ_BUFFER_RECT
        CL_COMMAND_WRITE_BUFFER_RECT
        CL_COMMAND_COPY_BUFFER_RECT
        CL_COMMAND_USER
        CL_COMMAND_GL_FENCE_SYNC_OBJECT_KHR
        (ifcl_khr_gl_eventisenabled)
        CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR
        (ifcl_khr_d3d10_sharingisenabled)
        CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR
        (ifcl_khr_d3d10_sharingisenabled)

        CL_EVENT_COMMAND_ EXECUTION_STATUS cl_int Return the execution status of the command identified by event. The valid values are:

        CL_QUEUED (command has been enqueued in the command-queue),

        CL_SUBMITTED (enqueued command has been submitted by the host to the device associated with the command-queue),

        CL_RUNNING (device is currently executing this command),

        CL_COMPLETE (the command has completed), or

        Error code given by a negative integer value. (command was abnormally terminated – this may be caused by a bad memory access etc.)

        These error codes come from the same set of error codes that are returned from the platform or runtime API calls as return values or errcode_ret values.

        The error code values are negative, and event state values are positive. The event state values are ordered from the largest value (CL_QUEUED) for the first or initial state to the smallest value (CL_COMPLETE or negative integer value) for the last or complete state. The value of CL_COMPLETE and CL_SUCCESS are the same.

        CL_EVENT_REFERENCE_COUNT cl_uint Return the event reference count. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than size of return type as described in the table above and param_value is not NULL.
        • CL_INVALID_VALUE if information to query given in param_name cannot be queried for event.
        • CL_INVALID_EVENT if event is not a valid event object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetEventInfoNative

        private static int clGetEventInfoNative​(cl_event event,
                                                int param_name,
                                                long param_value_size,
                                                Pointer param_value,
                                                long[] param_value_size_ret)
      • clCreateUserEvent

        public static cl_event clCreateUserEvent​(cl_context context,
                                                 int[] errcode_ret)

        Creates a user event object.

        cl_event clCreateUserEvent ( cl_contextcontext,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context used to create the user event object.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        User events allow applications to enqueue commands that wait on a user event to finish before the command is executed by the device.

        The execution status of the user event object created is set to CL_SUBMITTED.

        Errors

        Returns a valid non-zero buffer object and errcode_ret is set to CL_SUCCESS if the user event object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

        • CL_INVALID_CONTEXT if context is not a valid context.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clCreateUserEventNative

        private static cl_event clCreateUserEventNative​(cl_context context,
                                                        int[] errcode_ret)
      • clRetainEvent

        public static int clRetainEvent​(cl_event event)

        Increments the event reference count.

        cl_int clRetainEvent ( cl_eventevent)

        Parameters

        event

        Event object being retained.

        Notes

        The OpenCL commands that return an event perform an implicit retain.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_EVENT if event is not a valid event object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clRetainEventNative

        private static int clRetainEventNative​(cl_event event)
      • clReleaseEvent

        public static int clReleaseEvent​(cl_event event)

        Decrements the event reference count.

        cl_int clReleaseEvent ( cl_eventevent)

        Parameters

        event

        Event object being released.

        Notes

        Decrements the event reference count. The event object is deleted once the reference count becomes zero, the specific command identified by this event has completed (or terminated) and there are no commands in the command-queues of a context that require a wait for this event to complete.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_EVENT if event is not a valid event object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clReleaseEventNative

        private static int clReleaseEventNative​(cl_event event)
      • clSetUserEventStatus

        public static int clSetUserEventStatus​(cl_event event,
                                               int execution_status)

        Sets the execution status of a user event object.

        cl_mem clSetUserEventStatus ( cl_eventevent,
        cl_intexecution_status)

        Parameters

        event

        A user event object created using clCreateUserEvent.

        execution_status

        Specifies the new execution status to be set and can be CL_COMPLETE or a negative integer value to indicate an error. A negative integer value causes all enqueued commands that wait on this user event to be terminated. clSetUserEventStatus can only be called once to change the execution status of event.

        Notes

        Enqueued commands that specify user events in the event_wait_list argument of clEnqueue*** commands must ensure that the status of these user events being waited on are set using clSetUserEventStatus before any OpenCL APIs that release OpenCL objects except for event objects are called; otherwise the behavior is undefined.

        Errors

        Returns CL_SUCCESS if the function was executed successfully. Otherwise, it returns one of the following errors

        • CL_INVALID_EVENT if event is not a valid user event.
        • CL_INVALID_VALUE if the execution_status is not CL_COMPLETE or a negative integer value.
        • CL_INVALID_OPERATION if the execution_status for event has already been changed by a previous call to clSetUserEventStatus.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Example

        For example, the following code sequence will result in undefined behavior of clReleaseMemObject.

        ev1 = clCreateUserEvent(ctx, NULL); clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., 1, &ev1, NULL; clEnqueueWriteBuffer(cq, buf2, CL_FALSE,...); clReleaseMemObject(buf2); clSetUserEventStatus(ev1, CL_COMPLETE);

        The following code sequence, however, works correctly.

        ev1 = clCreateUserEvent(ctx, NULL); clEnqueueWriteBuffer(cq, buf1, CL_FALSE, ..., 1, &ev1, NULL; clEnqueueWriteBuffer(cq, buf2, CL_FALSE,...); clSetUserEventStatus(ev1, CL_COMPLETE); clReleaseMemObject(buf2);
        Since:
        OpenCL 1.1
      • clSetUserEventStatusNative

        private static int clSetUserEventStatusNative​(cl_event event,
                                                      int execution_status)
      • clSetEventCallback

        public static int clSetEventCallback​(cl_event event,
                                             int command_exec_callback_type,
                                             EventCallbackFunction pfn_notify,
                                             java.lang.Object user_data)

        Registers a user callback function for a specific command execution status.

        cl_int clSetEventCallback ( cl_eventevent,
        cl_int command_exec_callback_type ,
        void (CL_CALLBACK *pfn_event_notify) (cl_event event, cl_int event_command_exec_status, void *user_data),
        void*user_data)

        Parameters

        event

        A valid event object.

        command_exec_callback_type

        The command execution status for which the callback is registered. The command execution callback value for which a callback can be registered is CL_COMPLETE. There is no guarantee that the callback functions registered for various execution status values for an event will be called in the exact order that the execution status of a command changes.

        The callback function registered for a command_exec_callback_type value of CL_COMPLETE will be called when the command has completed successfully or is abnormally terminated.

        pfn_event_notify

        The event callback function that can be registered by the application. This callback function may be called asynchronously by the OpenCL implementation. It is the application's responsibility to ensure that the callback function is thread-safe. The parameters to this callback function are:

        • event: the event object for which the callback function is invoked.
        • event_command_exec_status: the execution status of command for which this callback function is invoked. See the table of values for clGetEventInfoparam_value for the command execution status values. If the callback is called as the result of the command associated with event being abnormally terminated, an appropriate error code for the error that caused the termination will be passed to event_command_exec_status instead.
        • user_data: a pointer to user supplied data.
        user_data

        Will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.

        Notes

        The registered callback function will be called when the execution status of command associated with event changes to the execution status specified by command_exec_status.

        Each call to clSetEventCallback registers the specified user callback function on a callback stack associated with event. The order in which the registered user callback functions are called is undefined.

        All callbacks registered for an event object must be called. All enqueued callbacks shall be called before the event object is destroyed. Callbacks must return promptly. The behavior of calling expensive system routines, OpenCL API calls to create contexts or command-queues, or blocking OpenCL operations from the following list below, in a callback is undefined.

        • clFinish
        • clWaitForEvents
        • blocking calls to clEnqueueReadBuffer, clEnqueueReadBufferRect, clEnqueueWriteBuffer, and clEnqueueWriteBufferRect
        • blocking calls to clEnqueueReadImage and clEnqueueWriteImage
        • blocking calls to clEnqueueMapBuffer and clEnqueueMapImage
        • blocking calls to clBuildProgram

        If an application needs to wait for completion of a routine from the above l ist in a callback, please use the non-blocking form of the function, and assign a completion callback to it to do the remainder of your work. Note that when a callback (or other code) enqueues commands to a command-queue, the commands are not required to begin execution until the queue is flushed. In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a command queue should either call clFlush on the queue before returning or arrange for clFlush to be called later on another thread.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_EVENT if event is not a valid event object.
        • CL_INVALID_VALUE if pfn_event_notify is NULL or if command_exec_callback_type is not CL_COMPLETE.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clSetEventCallbackNative

        private static int clSetEventCallbackNative​(cl_event event,
                                                    int command_exec_callback_type,
                                                    EventCallbackFunction pfn_notify,
                                                    java.lang.Object user_data)
      • clGetEventProfilingInfo

        public static int clGetEventProfilingInfo​(cl_event event,
                                                  int param_name,
                                                  long param_value_size,
                                                  Pointer param_value,
                                                  long[] param_value_size_ret)

        Returns profiling information for the command associated with event if profiling is enabled.

        cl_int clGetEventProfilingInfo ( cl_eventevent,
        cl_profiling_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        event

        Specifies the event object.

        param_name

        Specifies the profiling data to query. The list of supported param_name types and the information returned in param_value by clGetEventProfilingInfo is described in the table of parameter queries below.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table bolow.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        The following is a table of clGetEventProfilingInfo parameter queries

        cl_profiling_info Return Type Info. returned in param_value
        CL_PROFILING_COMMAND_QUEUED cl_ulong A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event is enqueued in a command-queue by the host.
        CL_PROFILING_COMMAND_SUBMIT cl_ulong A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event that has been enqueued is submitted by the host to the device associated with the command-queue.
        CL_PROFILING_COMMAND_START cl_ulong A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event starts execution on the device.
        CL_PROFILING_COMMAND_END cl_ulong A 64-bit value that describes the current device time counter in nanoseconds when the command identified by event has finished execution on the device.

        Notes

        The unsigned 64-bit values returned can be used to measure the time in nano-seconds consumed by OpenCL commands.

        OpenCL devices are required to correctly track time across changes in device frequency and power states. The CL_DEVICE_PROFILING_TIMER_RESOLUTION specifies the resolution of the timer i.e. the number of nanoseconds elapsed before the timer is incremented.

        Event objects can be used to capture profiling information that measure execution time of a command. Profiling of OpenCL commands can be enabled either by using a command-queue created with CL_QUEUE_PROFILING_ENABLE flag set in properties argument to clCreateCommandQueue.

        Errors

        Returns CL_SUCCESS if the function is executed successfully and the profiling information has been recorded. Otherwise, it returns one of the following errors:

        • CL_PROFILING_INFO_NOT_AVAILABLE if the CL_QUEUE_PROFILING_ENABLE flag is not set for the command-queue, if the execution status of the command identified by event is not CL_COMPLETE or if event is a user event object.
        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the above table and param_value is not NULL.
        • CL_INVALID_EVENT if event is a not a valid event object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetEventProfilingInfoNative

        private static int clGetEventProfilingInfoNative​(cl_event event,
                                                         int param_name,
                                                         long param_value_size,
                                                         Pointer param_value,
                                                         long[] param_value_size_ret)
      • clFlush

        public static int clFlush​(cl_command_queue command_queue)

        Issues all previously queued OpenCL commands in a command-queue to the device associated with the command-queue.

        cl_int clFlush ( cl_command_queuecommand_queue)

        Notes

        Issues all previously queued OpenCL commands in command_queue to the device associated with command_queue.

        clFlush only guarantees that all queued commands to command_queue get issued to the appropriate device. There is no guarantee that they will be complete after clFlush returns.

        Any blocking commands queued in a command-queue perform an implicit flush of the command-queue. These blocking commands are clEnqueueReadBuffer, clEnqueueReadBufferRect, or clEnqueueReadImage with blocking_read set to CL_TRUE; clEnqueueWriteBuffer, clEnqueueWriteBufferRect, or clEnqueueWriteImage with blocking_write set to CL_TRUE; clEnqueueMapBuffer or clEnqueueMapImage with blocking_map set to CL_TRUE; or clWaitForEvents.

        To use event objects that refer to commands enqueued in a command-queue as event objects to wait on by commands enqueued in a different command-queue, the application must call a clFlush or any blocking commands that perform an implicit flush of the command-queue where the commands that refer to these event objects are enqueued.

        Errors

        Returns CL_SUCCESS if the function call was executed successfully. Otherwise, it returns one of the following:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • clFlushNative

        private static int clFlushNative​(cl_command_queue command_queue)
      • clFinish

        public static int clFinish​(cl_command_queue command_queue)

        Blocks until all previously queued OpenCL commands in a command-queue are issued to the associated device and have completed.

        cl_int clFinish ( cl_command_queuecommand_queue)

        Notes

        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.

        Errors

        Returns CL_SUCCESS if the function call was executed successfully. Otherwise, it returns one of the following:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
      • clFinishNative

        private static int clFinishNative​(cl_command_queue command_queue)
      • clEnqueueReadBuffer

        public static int clEnqueueReadBuffer​(cl_command_queue command_queue,
                                              cl_mem buffer,
                                              boolean blocking_read,
                                              long offset,
                                              long cb,
                                              Pointer ptr,
                                              int num_events_in_wait_list,
                                              cl_event[] event_wait_list,
                                              cl_event event)

        Enqueue commands to read from a buffer object to host memory.

        cl_int clEnqueueReadBuffer ( cl_command_queuecommand_queue,
        cl_membuffer,
        cl_boolblocking_read,
        size_toffset,
        size_tcb,
        void*ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the read command will be queued. command_queue and buffer must be created with the same OpenCL context.

        buffer

        Refers to a valid buffer object.

        blocking_read

        Indicates if the read operations are blocking or non-blocking. If blocking_read is CL_TRUE i.e. the read command is blocking, clEnqueueReadBuffer does not return until the buffer data has been read and copied into memory pointed to by ptr.

        If blocking_read is CL_FALSE i.e. the read command is non-blocking, clEnqueueReadBuffer queues a non-blocking read command and returns. The contents of the buffer that ptr points to cannot be used until the read command has completed. The event argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr points to can be used by the application.

        offset

        The offset in bytes in the buffer object to read from.

        cb

        The size in bytes of data being read.

        ptr

        The pointer to buffer in host memory where data is to be read into.

        event_wait_list , num_events_in_wait_list

        event_wait_list and num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular read command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        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:

        • All commands that use this buffer object or a memory object (buffer or image) created from this buffer object have finished execution before the read command begins execution.
        • The buffer object or memory objects created from this buffer object are not mapped.
        • The buffer object or memory objects created from this buffer object are not used by any command-queue until the read command has finished execution.

        Errors

        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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Note: For non-blocking read operations, the given Pointer must be a Pointer to a direct buffer. Otherwise, an IllegalArgumentException will be thrown.
        Throws:
        java.lang.IllegalArgumentException - If blocking_read==false and the given Pointer is not a Pointer to a direct buffer.
      • clEnqueueReadBufferNative

        private static int clEnqueueReadBufferNative​(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)
      • clEnqueueReadBufferRect

        public static int clEnqueueReadBufferRect​(cl_command_queue command_queue,
                                                  cl_mem buffer,
                                                  boolean blocking_read,
                                                  long[] buffer_offset,
                                                  long[] host_offset,
                                                  long[] region,
                                                  long buffer_row_pitch,
                                                  long buffer_slice_pitch,
                                                  long host_row_pitch,
                                                  long host_slice_pitch,
                                                  Pointer ptr,
                                                  int num_events_in_wait_list,
                                                  cl_event[] event_wait_list,
                                                  cl_event event)

        Enqueue commands to read from a rectangular region from a buffer object to host memory.

        cl_int clEnqueueReadBufferRect ( cl_command_queuecommand_queue,
        cl_membuffer,
        cl_boolblocking_read,
        const size_tbuffer_origin[3],
        const size_thost_origin[3],
        const size_tregion[3],
        size_tbuffer_row_pitch,
        size_tbuffer_slice_pitch,
        size_thost_row_pitch,
        size_thost_slice_pitch,
        void*ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the read command will be queued. command_queue and buffer must be created with the same OpenCL context.

        buffer

        Refers to a valid buffer object.

        blocking_read

        Indicates if the read operations are blocking or non-blocking. If blocking_read is CL_TRUE i.e. the read command is blocking, clEnqueueReadBufferRect does not return until the buffer data has been read and copied into memory pointed to by ptr.

        If blocking_read is CL_FALSE i.e. the read command is non-blocking, clEnqueueReadBufferRect queues a non-blocking read command and returns. The contents of the buffer that ptr points to cannot be used until the read command has completed. The event argument argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr points to can be used by the application.

        buffer_origin

        The (x, y, z) offset in the memory region associated with buffer. For a 2D rectangle region, the z value given by buffer_origin[2] should be 0. The offset in bytes is computed as buffer_origin[2] * buffer_slice_pitch + buffer_origin[1] * buffer_row_pitch + buffer_origin[0].

        host_origin

        The (x, y, z) offset in the memory region pointed to by ptr. For a 2D rectangle region, the z value given by host_origin[2] should be 0. The offset in bytes is computed as host_origin[2] * host_slice_pitch + host_origin[1] * host_row_pitch + host_origin[0].

        region

        The (width, height, depth) in bytes of the 2D or 3D rectangle being read or written. For a 2D rectangle copy, the depth value given by region[2] should be 1.

        buffer_row_pitch

        The length of each row in bytes to be used for the memory region associated with buffer. If buffer_row_pitch is 0, buffer_row_pitch is computed as region[0].

        buffer_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region associated with buffer. If buffer_slice_pitch is 0, buffer_slice_pitch is computed as region[1] * buffer_row_pitch.

        host_row_pitch

        The length of each row in bytes to be used for the memory region pointed to by ptr. If host_row_pitch is 0, host_row_pitch is computed as region[0].

        host_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region pointed to by ptr. If host_slice_pitch is 0, host_slice_pitch is computed as region[1] * host_row_pitch.

        ptr

        The pointer to buffer in host memory where data is to be read into.

        event_wait_list , num_events_in_wait_list

        event_wait_list and num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular read command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        Calling clEnqueueReadBufferRect to read a region of the buffer object with the ptr argument value set to host_ptr and host_origin, buffer_origin values are the same, where host_ptr is a pointer to the memory region specified when the buffer object being read is created with CL_MEM_USE_HOST_PTR, must meet the same requirements given for clEnqueueReadBuffer.

        Errors

        clEnqueueReadBufferRect 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 (buffer_origin, region) is out of bounds.
        • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Throws:
        java.lang.IllegalArgumentException - If blocking_read==false and the given Pointer is not a Pointer to a direct buffer.
        Since:
        OpenCL 1.1 Note: For non-blocking read operations, the given Pointer must be a Pointer to a direct buffer. Otherwise, an IllegalArgumentException will be thrown.
      • clEnqueueReadBufferRectNative

        private static int clEnqueueReadBufferRectNative​(cl_command_queue command_queue,
                                                         cl_mem buffer,
                                                         boolean blocking_read,
                                                         long[] buffer_offset,
                                                         long[] host_offset,
                                                         long[] region,
                                                         long buffer_row_pitch,
                                                         long buffer_slice_pitch,
                                                         long host_row_pitch,
                                                         long host_slice_pitch,
                                                         Pointer ptr,
                                                         int num_events_in_wait_list,
                                                         cl_event[] event_wait_list,
                                                         cl_event event)
      • clEnqueueWriteBuffer

        public static int clEnqueueWriteBuffer​(cl_command_queue command_queue,
                                               cl_mem buffer,
                                               boolean blocking_write,
                                               long offset,
                                               long cb,
                                               Pointer ptr,
                                               int num_events_in_wait_list,
                                               cl_event[] event_wait_list,
                                               cl_event event)

        Enqueue commands to write to a buffer object from host memory.

        cl_int clEnqueueWriteBuffer ( cl_command_queuecommand_queue,
        cl_membuffer,
        cl_boolblocking_write,
        size_toffset,
        size_tcb,
        const void*ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the write command will be queued. command_queue and buffer must be created with the same OpenCL context.

        buffer

        Refers to a valid buffer object.

        blocking_write

        Indicates if the write operations are blocking or nonblocking.

        If blocking_write is CL_TRUE, the OpenCL implementation copies the data referred to by ptr and enqueues the write operation in the command-queue. The memory pointed to by ptr can be reused by the application after the clEnqueueWriteBuffer call returns.

        If blocking_write is CL_FALSE, the OpenCL implementation will use ptr to perform a nonblocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr cannot be reused by the application after the call returns. The event argument returns an event object which can be used to query the execution status of the write command. When the write command has completed, the memory pointed to by ptr can then be reused by the application.

        offset

        The offset in bytes in the buffer object to write to.

        cb

        The size in bytes of data being written.

        ptr

        The pointer to buffer in host memory where data is to be written from.

        event_wait_list , num_events_in_wait_list

        event_wait_list and num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular write command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        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:

        • All commands that use this buffer object or a memory object (buffer or image) created from this buffer object have finished execution before the read command begins execution.
        • The buffer object or memory objects created from this buffer object are not mapped.
        • The buffer object or memory objects created from this buffer object are not used by any command-queue until the read command has finished execution.

        Errors

        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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Note: For non-blocking write operations, the given Pointer must be a Pointer to a direct buffer. Otherwise, an IllegalArgumentException will be thrown.
        Throws:
        java.lang.IllegalArgumentException - If blocking_write==false and the given Pointer is not a Pointer to a direct buffer.
      • clEnqueueWriteBufferNative

        private static int clEnqueueWriteBufferNative​(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)
      • clEnqueueWriteBufferRect

        public static int clEnqueueWriteBufferRect​(cl_command_queue command_queue,
                                                   cl_mem buffer,
                                                   boolean blocking_write,
                                                   long[] buffer_offset,
                                                   long[] host_offset,
                                                   long[] region,
                                                   long buffer_row_pitch,
                                                   long buffer_slice_pitch,
                                                   long host_row_pitch,
                                                   long host_slice_pitch,
                                                   Pointer ptr,
                                                   int num_events_in_wait_list,
                                                   cl_event[] event_wait_list,
                                                   cl_event event)

        Enqueue commands to write a rectangular region to a buffer object from host memory.

        cl_int clEnqueueWriteBufferRect ( cl_command_queuecommand_queue,
        cl_membuffer,
        cl_boolblocking_write,
        const size_tbuffer_origin[3],
        const size_thost_origin[3],
        const size_tregion[3],
        size_tbuffer_row_pitch,
        size_tbuffer_slice_pitch,
        size_thost_row_pitch,
        size_thost_slice_pitch,
        void*ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the write command will be queued. command_queue and buffer must be created with the same OpenCL context.

        buffer

        Refers to a valid buffer object.

        blocking_write

        Indicates if the write operations are blocking or non-blocking. If blocking_write is CL_TRUE, the OpenCL implementation copies the data referred to by ptr and enqueues the write operation in the command-queue. The memory pointed to by ptr can be reused by the application after the clEnqueueWriteBufferRect call returns.

        If blocking_write is CL_FALSE, the OpenCL implementation will use ptr to perform a nonblocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr cannot be reused by the application after the call returns. The event argument returns an event object which can be used to query the execution status of the write command. When the write command has completed, the memory pointed to by ptr can then be reused by the application.

        buffer_origin

        The (x, y, z) offset in the memory region associated with buffer. For a 2D rectangle region, the z value given by buffer_origin[2] should be 0. The offset in bytes is computed as buffer_origin[2] * buffer_slice_pitch + buffer_origin[1] * buffer_row_pitch + buffer_origin[0].

        host_origin

        The (x, y, z) offset in the memory region pointed to by ptr. For a 2D rectangle region, the z value given by host_origin[2] should be 0. The offset in bytes is computed as host_origin[2] * host_slice_pitch + host_origin[1] * host_row_pitch + host_origin[0].

        region

        The (width, height, depth) in bytes of the 2D or 3D rectangle being read or written. For a 2D rectangle copy, the depth value given by region[2] should be 1.

        buffer_row_pitch

        The length of each row in bytes to be used for the memory region associated with buffer. If buffer_row_pitch is 0, buffer_row_pitch is computed as region[0].

        buffer_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region associated with buffer. If buffer_slice_pitch is 0, buffer_slice_pitch is computed as region[1] * buffer_row_pitch.

        host_row_pitch

        The length of each row in bytes to be used for the memory region pointed to by ptr. If host_row_pitch is 0, host_row_pitch is computed as region[0].

        host_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region pointed to by ptr. If host_slice_pitch is 0, host_slice_pitch is computed as region[1] * host_row_pitch.

        ptr

        The pointer to buffer in host memory where data is to be written from.

        event_wait_list , num_events_in_wait_list

        event_wait_list and num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular write command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        Calling clEnqueueWriteBufferRect to update the latest bits in a region of the buffer object with the ptr argument value set to host_ptr and host_origin, buffer_origin values are the same, where host_ptr is a pointer to the memory region specified when the buffer object being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

        • The host memory region given by (buffer_origin region) contains the latest bits when the enqueued write command begins execution.
        • The buffer object or memory objects created from this buffer object are not mapped.
        • The buffer object or memory objects created from this buffer object are not used by any command-queue until the write command has finished execution.

        Errors

        clEnqueueWriteBufferRect 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 (buffer_origin, region) 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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clEnqueueWriteBufferRectNative

        private static int clEnqueueWriteBufferRectNative​(cl_command_queue command_queue,
                                                          cl_mem buffer,
                                                          boolean blocking_write,
                                                          long[] buffer_offset,
                                                          long[] host_offset,
                                                          long[] region,
                                                          long buffer_row_pitch,
                                                          long buffer_slice_pitch,
                                                          long host_row_pitch,
                                                          long host_slice_pitch,
                                                          Pointer ptr,
                                                          int num_events_in_wait_list,
                                                          cl_event[] event_wait_list,
                                                          cl_event event)
      • clEnqueueFillBuffer

        public static int clEnqueueFillBuffer​(cl_command_queue command_queue,
                                              cl_mem buffer,
                                              Pointer pattern,
                                              long pattern_size,
                                              long offset,
                                              long size,
                                              int num_events_in_wait_list,
                                              cl_event[] event_wait_list,
                                              cl_event event)

        Enqueues a command to fill a buffer object with a pattern of a given pattern size.

        cl_int clEnqueueFillBuffer ( cl_command_queue command_queue ,
        cl_mem buffer ,
        const void *pattern ,
        size_t pattern_size ,
        size_t offset ,
        size_t size ,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        Refers to the command-queue in which the fill command will be queued. The OpenCL context associated with command_queue and buffer must be the same.

        buffer

        A valid buffer object.

        pattern

        A pointer to the data pattern of size pattern_size in bytes. pattern will be used to fill a region in buffer starting at offset and is size bytes in size. The data pattern must be a scalar or vector integer or floating-point data type. For example, if buffer is to be filled with a pattern of float4 values, then pattern will be a pointer to a cl_float4 value and pattern_size will be sizeof(cl_float4). The maximum value of pattern_size is the size of the largest integer or floating-point vector data type supported by the OpenCL device. The memory associated with pattern can be reused or freed after the function returns.

        offset

        The location in bytes of the region being filled in buffer and must be a multiple of pattern_size.

        size

        The size in bytes of region being filled in buffer and must be a multiple of pattern_size.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

        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. clEnqueueBarrierWithWaitList can be used instead. 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.

        Notes

        Enqueues a command to fill a buffer object with a pattern of a given pattern size. The usage information which indicates whether the memory object can be read or written by a kernel and/or the host and is given by the cl_mem_flags argument value specified when buffer is created is ignored by clEnqueueFillBuffer.

        Errors

        clEnqueueFillBuffer 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 offset or offset + size require accessing elements outside the buffer buffer object respectively.
        • CL_INVALID_VALUE if pattern is NULL or if pattern_size is 0 or if pattern_size is not one of {1, 2, 4, 8, 16, 32, 64, 128}.
        • CL_INVALID_VALUE if offset and size are not a multiple of pattern_size.
        • 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_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with buffer.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clEnqueueFillBufferNative

        private static int clEnqueueFillBufferNative​(cl_command_queue command_queue,
                                                     cl_mem buffer,
                                                     Pointer pattern,
                                                     long pattern_size,
                                                     long offset,
                                                     long size,
                                                     int num_events_in_wait_list,
                                                     cl_event[] event_wait_list,
                                                     cl_event event)
      • clEnqueueCopyBuffer

        public static int clEnqueueCopyBuffer​(cl_command_queue command_queue,
                                              cl_mem src_buffer,
                                              cl_mem dst_buffer,
                                              long src_offset,
                                              long dst_offset,
                                              long cb,
                                              int num_events_in_wait_list,
                                              cl_event[] event_wait_list,
                                              cl_event event)

        Enqueues a command to copy from one buffer object to another.

        cl_int clEnqueueCopyBuffer ( cl_command_queuecommand_queue,
        cl_memsrc_buffer,
        cl_memdst_buffer,
        size_tsrc_offset,
        size_tdst_offset,
        size_tcb,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        The command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_buffer, and dst_buffer must be the same.

        src_offset

        The offset where to begin copying data from src_buffer.

        dst_offset

        The offset where to begin copying data into dst_buffer.

        cb

        Refers to the size in bytes to copy.

        event_wait_list, , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Errors

        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 src_buffer and dst_buffer buffer objects respectively.
        • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list is greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer object and the source and destination regions overlap.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if src_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if dst_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueCopyBufferNative

        private static int clEnqueueCopyBufferNative​(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)
      • clEnqueueCopyBufferRect

        public static int clEnqueueCopyBufferRect​(cl_command_queue command_queue,
                                                  cl_mem src_buffer,
                                                  cl_mem dst_buffer,
                                                  long[] src_origin,
                                                  long[] dst_origin,
                                                  long[] region,
                                                  long src_row_pitch,
                                                  long src_slice_pitch,
                                                  long dst_row_pitch,
                                                  long dst_slice_pitch,
                                                  int num_events_in_wait_list,
                                                  cl_event[] event_wait_list,
                                                  cl_event event)

        Enqueues a command to copy a rectangular region from the buffer object to another buffer object.

        cl_int clEnqueueCopyBufferRect ( cl_command_queuecommand_queue,
        cl_memsrc_buffer,
        cl_memdst_buffer,
        const size_tsrc_origin[3],
        const size_tdst_origin[3],
        const size_tregion[3],
        size_tsrc_row_pitch,
        size_tsrc_slice_pitch,
        size_tdst_row_pitch,
        size_tdst_slice_pitch,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        The command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_buffer, and dst_buffer must be the same.

        src_origin

        The (x, y, z) offset in the memory region associated with src_buffer. For a 2D rectangle region, the z value given by src_origin[2] should be 0. The offset in bytes is computed as src_origin[2] * src_slice_pitch + src_origin[1] * src_row_pitch + src_origin[0].

        dst_origin

        The (x, y, z) offset in the memory region associated with dst_buffer. For a 2D rectangle region, the z value given by dst_origin[2] should be 0. The offset in bytes is computed as dst_origin[2] * dst_slice_pitch + dst_origin[1] * dst_row_pitch + dst_origin[0].

        region

        The (width, height, depth) in bytes of the 2D or 3D rectangle being copied. For a 2D rectangle, the depth value given by region[2] should be 1.

        src_row_pitch

        The length of each row in bytes to be used for the memory region associated with src_buffer. If src_row_pitch is 0, src_row_pitch is computed as region[0].

        src_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region associated with src_buffer. If src_slice_pitch is 0, src_slice_pitch is computed as region[1] * src_row_pitch.

        dst_row_pitch

        The length of each row in bytes to be used for the memory region associated with dst_buffer. If dst_row_pitch is 0, dst_row_pitch is computed as region[0].

        dst_slice_pitch

        The length of each 2D slice in bytes to be used for the memory region associated with dst_buffer. If dst_slice_pitch is 0, dst_slice_pitch is computed as region[1] * dst_row_pitch.

        event_wait_list, , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Errors

        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, region) or (dst_offset, region) require accessing elements outside the src_buffer and dst_buffer objects respectively.
        • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list is greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MEM_COPY_OVERLAP if src_buffer and dst_buffer are the same buffer object and the source and destination regions overlap.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if src_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if dst_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.1
      • clEnqueueCopyBufferRectNative

        private static int clEnqueueCopyBufferRectNative​(cl_command_queue command_queue,
                                                         cl_mem src_buffer,
                                                         cl_mem dst_buffer,
                                                         long[] src_origin,
                                                         long[] dst_origin,
                                                         long[] region,
                                                         long src_row_pitch,
                                                         long src_slice_pitch,
                                                         long dst_row_pitch,
                                                         long dst_slice_pitch,
                                                         int num_events_in_wait_list,
                                                         cl_event[] event_wait_list,
                                                         cl_event event)
      • clEnqueueReadImage

        public static int clEnqueueReadImage​(cl_command_queue command_queue,
                                             cl_mem image,
                                             boolean blocking_read,
                                             long[] origin,
                                             long[] region,
                                             long row_pitch,
                                             long slice_pitch,
                                             Pointer ptr,
                                             int num_events_in_wait_list,
                                             cl_event[] event_wait_list,
                                             cl_event event)

        Enqueues a command to read from a 2D or 3D image object to host memory.

        cl_int clEnqueueReadImage ( cl_command_queuecommand_queue,
        cl_memimage,
        cl_boolblocking_read,
        const size_torigin[3],
        const size_tregion[3],
        size_trow_pitch,
        size_tslice_pitch,
        void*ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the read command will be queued. command_queue and image must be created with the same OpenCL context.

        image

        Refers to a valid 2D or 3D image object.

        blocking_read

        Indicates if the read operations are blocking or non-blocking.

        If blocking_read is CL_TRUE i.e. the read command is blocking, clEnqueueReadImage does not return until the buffer data has been read and copied into memory pointed to by ptr.

        If blocking_read is CL_FALSE i.e. map operation is non-blocking, clEnqueueReadImage queues a non-blocking read command and returns. The contents of the buffer that ptr points to cannot be used until the read command has completed. The event argument returns an event object which can be used to query the execution status of the read command. When the read command has completed, the contents of the buffer that ptr points to can be used by the application.

        origin

        Defines the (x, y, z) offset in pixels in the image from where to read. If image is a 2D image object, the z value given by origin[2] must be 0.

        region

        Defines the (width, height, depth) in pixels of the 2D or 3D rectangle being read. If image is a 2D image object, the depth value given by region[2] must be 1.

        row_pitch

        The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width. If row_pitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width.

        slice_pitch

        Size in bytes of the 2D slice of the 3D region of a 3D image being read. This must be 0 if image is a 2D image. This value must be greater than or equal to row_pitch * height. If slice_pitch is set to 0, the appropriate slice pitch is calculated based on the row_pitch * height.

        ptr

        The pointer to a buffer in host memory where image data is to be read from.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular read command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        Calling clEnqueueReadImage to read a region of the image with the ptr argument value set to host_ptr + (origin[2] * image slice pitch + origin[1] * image row pitch + origin[0] * bytes per pixel), where host_ptr is a pointer to the memory region specified when the image being read is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

        • All commands that use this image object have finished execution before the read command begins execution.
        • The row_pitch and slice_pitch argument values in clEnqueueReadImage must be set to the image row pitch and slice pitch.
        • The image object is not mapped.
        • The image object is not used by any command-queue until the read command has finished execution.

        Errors

        clEnqueueReadImage 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 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 the region being read specified by origin and region is out of bounds or if ptr is a NULL value.
        • 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 or slice_pitch is not equal to 0.
        • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by device associated with queue.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Note: For non-blocking read operations, the given Pointer must be a Pointer to a direct buffer. Otherwise, an IllegalArgumentException will be thrown.
        Throws:
        java.lang.IllegalArgumentException - If blocking_read==false and the given Pointer is not a Pointer to a direct buffer.
      • clEnqueueReadImageNative

        private static int clEnqueueReadImageNative​(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)
      • clEnqueueWriteImage

        public static int clEnqueueWriteImage​(cl_command_queue command_queue,
                                              cl_mem image,
                                              boolean blocking_write,
                                              long[] origin,
                                              long[] region,
                                              long input_row_pitch,
                                              long input_slice_pitch,
                                              Pointer ptr,
                                              int num_events_in_wait_list,
                                              cl_event[] event_wait_list,
                                              cl_event event)

        Enqueues a command to write to a 2D or 3D image object from host memory.

        cl_int clEnqueueWriteImage ( cl_command_queuecommand_queue,
        cl_memimage,
        cl_boolblocking_write,
        const size_torigin[3],
        const size_tregion[3],
        size_tinput_row_pitch,
        size_tinput_slice_pitch,
        const void* ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the write command will be queued. command_queue and image must be created with the same OpenCL context.

        image

        Refers to a valid 2D or 3D image object.

        blocking_write

        Indicates if the write operation is blocking or non-blocking.

        If blocking_write is CL_TRUE the OpenCL implementation copies the data referred to by ptr and enqueues the write command in the command-queue. The memory pointed to by ptr can be reused by the application after the clEnqueueWriteImage call returns.

        If blocking_write is CL_FALSE the OpenCL implementation will use ptr to perform a nonblocking write. As the write is non-blocking the implementation can return immediately. The memory pointed to by ptr cannot be reused by the application after the call returns. The event argument returns an event object which can be used to query the execution status of the write command. When the write command has completed, the memory pointed to by ptr can then be reused by the application.

        origin

        Defines the (x, y, z) offset in pixels in the image from where to write. If image is a 2D image object, the z value given by origin[2] must be 0.

        region

        Defines the (width, height, depth) in pixels of the 2D or 3D rectangle being written. If image is a 2D image object, the depth value given by region[2] must be 1.

        input_row_pitch

        The length of each row in bytes. This value must be greater than or equal to the element size in bytes * width. If input_row_pitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width.

        input_slice_pitch

        Size in bytes of the 2D slice of the 3D region of a 3D image being written. This must be 0 if image is a 2D image. This value must be greater than or equal to row_pitch * height. If input_slice_pitch is set to 0, the appropriate slice pitch is calculated based on the row_pitch * height.

        ptr

        The pointer to a buffer in host memory where image data is to be written to.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular write command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        Notes

        Calling clEnqueueWriteImage to update the latest bits in a region of the image with the ptr argument value set to host_ptr + (origin[2] * image slice pitch + origin[1] * image row pitch + origin[0] * bytes per pixel), where host_ptr is a pointer to the memory region specified when the image being written is created with CL_MEM_USE_HOST_PTR, must meet the following requirements in order to avoid undefined behavior:

        • The host memory region being written contains the latest bits when the enqueued write command begins execution.
        • The input_row_pitch and input_slice_pitch argument values in clEnqueueWriteImage must be set to the image row pitch and slice pitch.
        • The image object is not mapped.
        • The image object is not used by any command-queue until the write command has finished execution.

        Errors

        clEnqueueWriteImage return 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 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 the region being written specified by origin and region is out of bounds or if ptr is a NULL value.
        • 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 or slice_pitch is not equal to 0.
        • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by device associated with queue.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the read and write operations are blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueWriteImageNative

        private static int clEnqueueWriteImageNative​(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)
      • clEnqueueFillImage

        public static int clEnqueueFillImage​(cl_command_queue command_queue,
                                             cl_mem image,
                                             Pointer fill_color,
                                             long[] origin,
                                             long[] region,
                                             int num_events_in_wait_list,
                                             cl_event[] event_wait_list,
                                             cl_event event)

        Enqueues a command to fill an image object with a specified color.

        cl_int clEnqueueFillImage ( cl_command_queuecommand_queue,
        cl_memimage,
        const void*fill_color,
        const size_t*origin,
        const size_t*region,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the fill command will be queued. The OpenCL context associated with command_queue and image must be the same.

        image

        A valid image object.

        fill_color

        The fill color. The fill color is a four component RGBA floating-point color value if the image channel data type is not an unnormalized signed and unsigned integer type, is a four component signed integer value if the image channel data type is an unnormalized signed integer type and is a four component unsigned integer value if the image channel data type is an unormalized unsigned integer type. The fill color will be converted to the appropriate image channel format and order associated with image.

        origin

        Defines the (x, y, z) offset in pixels in the 1D, 2D, or 3D image, the (x, y) offset and the image index in the image array or the (x) offset and the image index in the 1D image array. If image is a 2D image object, origin[2] must be 0. If image is a 1D image or 1D image buffer object, origin[1] and origin[2] must be 0. If image is a 1D image array object, origin[2] must be 0. If image is a 1D image array object, origin[1] describes the image index in the 1D image array. If image is a 2D image array object, origin[2] describes the image index in the 2D image array.

        region

        Defines the (width, height, depth) in pixels of the 1D, 2D or 3D rectangle, the (width, height) in pixels of the 2D rectangle and the number of images of a 2D image array or the (width) in pixels of the 1D rectangle and the number of images of a 1D image array. If image is a 2D image object, region[2] must be 1. If image is a 1D image or 1D image buffer object, region[1] and region[2] must be 1. If image is a 1D image array object, region[2] must be 1.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

        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. clEnqueueBarrierWithWaitList can be used instead. 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.

        Notes

        The usage information which indicates whether the memory object can be read or written by a kernel and/or the host and is given by the cl_mem_flags argument value specified when image is created is ignored by clEnqueueFillImage.

        Errors

        clEnqueueFillImage return 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 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 fill_color is NULL.
        • CL_INVALID_VALUE if the region being written specified by origin and region is out of bounds or if ptr is a NULL value.
        • CL_INVALID_VALUE if values in origin and region do not follow rules described in the argument description for origin and region.
        • 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_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by device associated with queue.
        • CL_INVALID_IMAGE_FORMAT if image format (image channel order and data type) for image are not supported by device associated with queue.
        • CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for data store associated with image.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clEnqueueFillImageNative

        private static int clEnqueueFillImageNative​(cl_command_queue command_queue,
                                                    cl_mem image,
                                                    Pointer fill_color,
                                                    long[] origin,
                                                    long[] region,
                                                    int num_events_in_wait_list,
                                                    cl_event[] event_wait_list,
                                                    cl_event event)
      • clEnqueueCopyImage

        public static int clEnqueueCopyImage​(cl_command_queue command_queue,
                                             cl_mem src_image,
                                             cl_mem dst_image,
                                             long[] src_origin,
                                             long[] dst_origin,
                                             long[] region,
                                             int num_events_in_wait_list,
                                             cl_event[] event_wait_list,
                                             cl_event event)

        Enqueues a command to copy image objects.

        cl_int clEnqueueCopyImage ( cl_command_queuecommand_queue,
        cl_memsrc_image,
        cl_memdst_image,
        const size_tsrc_origin[3],
        const size_tdst_origin[3],
        const size_tregion[3],
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Refers to the command-queue in which the copy command will be queued. The OpenCL context associated with command_queue, src_image and dst_image must be the same.

        src_origin

        Defines the starting (x, y, z) location in pixels in src_image from where to start the data copy. If src_image is a 2D image object, the z value given by src_origin[2] must be 0.

        dst_origin

        Defines the starting (x, y, z) location in pixels in dst_image from where to start the data copy. If dst_image is a 2D image object, the z value given by dst_origin[2] must be 0.

        region

        Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If src_image or dst_image is a 2D image object, the depth value given by region[2] must be 1.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Notes

        It is currently a requirement that the src_image and dst_image image memory objects for clEnqueueCopyImage must have the exact same image format (i.e. the cl_image_format descriptor specified when src_image and dst_image are created must match).

        src_image and dst_image can be 2D or 3D image objects allowing us to perform the following actions:

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

        Errors

        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 src_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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for src_image are not supported by device associated with queue.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for dst_image are not supported by device associated with queue.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • CL_MEM_COPY_OVERLAP if src_image and dst_image are the same image object and the source and destination regions overlap.
      • clEnqueueCopyImageNative

        private static int clEnqueueCopyImageNative​(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)
      • clEnqueueCopyImageToBuffer

        public static int clEnqueueCopyImageToBuffer​(cl_command_queue command_queue,
                                                     cl_mem src_image,
                                                     cl_mem dst_buffer,
                                                     long[] src_origin,
                                                     long[] region,
                                                     long dst_offset,
                                                     int num_events_in_wait_list,
                                                     cl_event[] event_wait_list,
                                                     cl_event event)

        Enqueues a command to copy an image object to a buffer object.

        cl_int clEnqueueCopyImageToBuffer ( cl_command_queuecommand_queue,
        cl_memsrc_image,
        cl_mem dst_buffer,
        const size_tsrc_origin[3],
        const size_tregion[3],
        size_tdst_offset,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Must be a valid command-queue. The OpenCL context associated with command_queue, src_image, and dst_buffer must be the same.

        src_image

        A valid image object.

        dst_buffer

        A valid buffer object.

        src_origin

        Defines the (x, y, z) offset in pixels in the image from where to copy. If src_image is a 2D image object, the z value given by src_origin[2] must be 0.

        region

        Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If src_image is a 2D image object, the depth value given by region[2] must be 1.

        dst_offset

        The offset where to begin copying data into dst_buffer. The size in bytes of the region to be copied referred to as dst_cb is computed as width * height * depth * bytes/image element if src_image is a 3D image object and is computed as width * height * bytes/image element if src_image is a 2D image object.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Errors

        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 and 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 refers 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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if dst_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for src_image are not supported by device associated with queue.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueCopyImageToBufferNative

        private static int clEnqueueCopyImageToBufferNative​(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)
      • clEnqueueCopyBufferToImage

        public static int clEnqueueCopyBufferToImage​(cl_command_queue command_queue,
                                                     cl_mem src_buffer,
                                                     cl_mem dst_image,
                                                     long src_offset,
                                                     long[] dst_origin,
                                                     long[] region,
                                                     int num_events_in_wait_list,
                                                     cl_event[] event_wait_list,
                                                     cl_event event)

        Enqueues a command to copy a buffer object to an image object.

        cl_int clEnqueueCopyBufferToImage ( cl_command_queuecommand_queue,
        cl_memsrc_buffer,
        cl_mem dst_image,
        size_tsrc_offset,
        const size_tdst_origin[3],
        const size_tregion[3],
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue. The OpenCL context associated with command_queue, src_buffer, and dst_image must be the same.

        src_buffer

        A valid buffer object.

        dst_image

        A valid image object.

        src_offset

        The offset where to begin copying data from src_buffer.

        dst_origin

        The (x, y, z) offset in pixels where to begin copying data to dst_image. If dst_image is a 2D image object, the z value given by dst_origin[2] must be 0.

        region

        Defines the (width, height, depth) in pixels of the 2D or 3D rectangle to copy. If dst_image is a 2D image object, the depth value given by region[2] must be 1.

        The size in bytes of the region to be copied from src_buffer referred to as src_cb is computed as width * height * depth * bytes/image element if dst_image is a 3D image object and is computed as width * height * bytes/image element if dst_image is a 2D image object.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Errors

        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 and 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 refers to a region outside dst_origin, or if the region specified by src_offset and src_offset + src_cb refers to a region outside src_buffer.
        • 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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if src_buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for dst_image are not supported by device associated with queue.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_FALSE).
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueCopyBufferToImageNative

        private static int clEnqueueCopyBufferToImageNative​(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)
      • clEnqueueMapBuffer

        public static java.nio.ByteBuffer clEnqueueMapBuffer​(cl_command_queue command_queue,
                                                             cl_mem buffer,
                                                             boolean blocking_map,
                                                             long map_flags,
                                                             long offset,
                                                             long cb,
                                                             int num_events_in_wait_list,
                                                             cl_event[] event_wait_list,
                                                             cl_event event,
                                                             int[] errcode_ret)

        Enqueues a command to map a region of the buffer object given by buffer into the host address space and returns a pointer to this mapped region.

        void * clEnqueueMapBuffer ( cl_command_queuecommand_queue,
        cl_membuffer,
        cl_boolblocking_map,
        cl_map_flagsmap_flags,
        size_toffset,
        size_tcb,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event,
        cl_int*errcode_ret)

        Parameters

        command_queue

        Must be a valid command-queue.

        blocking_map

        Indicates if the map operation is blocking or non-blocking.

        If blocking_map is CL_TRUE, clEnqueueMapBuffer does not return until the specified region in buffer can be mapped.

        If blocking_map is CL_FALSE i.e. map operation is non-blocking, the pointer to the mapped region returned by clEnqueueMapBuffer cannot be used until the map command has completed. The event argument returns an event object which can be used to query the execution status of the map command. When the map command is completed, the application can access the contents of the mapped region using the pointer returned by clEnqueueMapBuffer.

        map_flags

        Is a bit-field and can be set to CL_MAP_READ to indicate that the region specified by (offset, cb) in the buffer object is being mapped for reading, and/or CL_MAP_WRITE to indicate that the region specified by (offset, cb) in the buffer object is being mapped for writing.

        buffer

        A valid buffer object. The OpenCL context associated with command_queue and buffer must be the same.

        offset, cb

        The offset in bytes and the size of the region in the buffer object that is being mapped.

        event_wait_list, num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        If the buffer object is created with CL_MEM_USE_HOST_PTR set in mem_flags, the host_ptr specified in clCreateBuffer is guaranteed to contain the latest bits in the region being mapped when the clEnqueueMapBuffer command has completed; and the pointer value returned by clEnqueueMapBuffer will be derived from the host_ptr specified when the buffer object is created.

        Mapped buffer objects are unmapped using clEnqueueUnmapMemObject.

        The contents of the regions of a memory object mapped for writing (i.e. CL_MAP_WRITE is set in map_flags argument to clEnqueueMapBuffer or clEnqueueMapImage) are considered to be undefined until this region is unmapped. Reads and writes by a kernel executing on a device to a memory region(s) mapped for writing are undefined.

        Multiple command-queues can map a region or overlapping regions of a memory object for reading (i.e. map_flags = CL_MAP_READ). The contents of the regions of a memory object mapped for reading can also be read by kernels executing on a device(s). The behavior of writes by a kernel executing on a device to a mapped region of a memory object is undefined. Mapping (and unmapping) overlapped regions of a buffer or image memory object for writing is undefined.

        The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.

        The pointer returned maps a region starting at offset and is at least cb bytes in size. The result of a memory access outside this region is undefined.

        Errors

        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 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 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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_MISALIGNED_SUB_BUFFER_OFFSET if buffer is a sub-buffer object and offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueMapBufferNative

        private static java.nio.ByteBuffer clEnqueueMapBufferNative​(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)
      • clEnqueueMapImage

        public static java.nio.ByteBuffer clEnqueueMapImage​(cl_command_queue command_queue,
                                                            cl_mem image,
                                                            boolean blocking_map,
                                                            long map_flags,
                                                            long[] origin,
                                                            long[] region,
                                                            long[] image_row_pitch,
                                                            long[] image_slice_pitch,
                                                            int num_events_in_wait_list,
                                                            cl_event[] event_wait_list,
                                                            cl_event event,
                                                            int[] errcode_ret)

        Enqueues a command to map a region of an image object into the host address space and returns a pointer to this mapped region.

        void * clEnqueueMapImage ( cl_command_queuecommand_queue,
        cl_memimage,
        cl_boolblocking_map,
        cl_map_flagsmap_flags,
        const size_torigin[3],
        const size_tregion[3],
        size_t*image_row_pitch,
        size_t*image_slice_pitch,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event,
        cl_int*errcode_ret)

        Parameters

        command_queue

        Must be a valid command-queue.

        image

        A valid image object. The OpenCL context associated with command_queue and image must be the same.

        blocking_map

        Indicates if the map operation is blocking or non-blocking. If blocking_map is CL_TRUE, clEnqueueMapImage does not return until the specified region in image can be mapped.

        If blocking_map is CL_FALSE i.e. map operation is non-blocking, the pointer to the mapped region returned by clEnqueueMapImage cannot be used until the map command has completed. The event argument returns an event object which can be used to query the execution status of the map command. When the map command is completed, the application can access the contents of the mapped region using the pointer returned by clEnqueueMapImage.

        map_flags

        Is a bit-field and can be set to CL_MAP_READ to indicate that the region specified by (origin, region) in the image object is being mapped for reading, and/or CL_MAP_WRITE to indicate that the region specified by (origin, region) in the image object is being mapped for writing.

        origin, region

        Define the (x, y, z) offset in pixels and (width, height, depth) in pixels of the 2D or 3D rectangle region that is to be mapped. If image is a 2D image object, the z value given by origin[2] must be 0 and the depth value given by region[2] must be 1.

        image_row_pitch

        Returns the scan-line pitch in bytes for the mapped region. This must be a non-NULL value.

        image_slice_pitch

        Returns the size in bytes of each 2D slice for the mapped region. For a 2D image, zero is returned if this argument is not NULL. For a 3D image, image_slice_pitch must be a non-NULL value.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before clEnqueueMapImage can be executed. If event_wait_list is NULL, then clEnqueueMapImage does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        errcode_ret

        Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

        Notes

        If the image object is created with CL_MEM_USE_HOST_PTR set in mem_flags, the following will be true:

        • The host_ptr specified in clCreateImage2d or clCreateImage3d is guaranteed to contain the latest bits in the region being mapped when the clEnqueueMapImage command has completed.
        • The pointer value returned by clEnqueueMapImage will be derived from the host_ptr specified when the image object is created.

        Mapped image objects are unmapped using clEnqueueUnmapMemObject.

        The contents of the regions of a memory object mapped for writing (i.e. CL_MAP_WRITE is set in map_flags argument to clEnqueueMapBuffer or clEnqueueMapImage) are considered to be undefined until this region is unmapped. Reads and writes by a kernel executing on a device to a memory region(s) mapped for writing are undefined.

        Multiple command-queues can map a region or overlapping regions of a memory object for reading (i.e. map_flags = CL_MAP_READ). The contents of the regions of a memory object mapped for reading can also be read by kernels executing on a device(s). The behavior of writes by a kernel executing on a device to a mapped region of a memory object is undefined. Mapping (and unmapping) overlapped regions of a memory object for writing is undefined.

        The behavior of OpenCL function calls that enqueue commands that write or copy to regions of a memory object that are mapped is undefined.

        The pointer returned maps a 2D or 3D region starting at origin and is at least (image_row_pitch * region[1]) pixels in size for a 2D image, and is at least (image_slice_pitch * region[2]) pixels in size for a 3D image. The result of a memory access outside this region is undefined.

        Errors

        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 the 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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_INVALID_IMAGE_SIZE if image dimensions (image width, height, specified or compute row and/or slice pitch) for image are not supported by device associated with queue.
        • 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 buffer.
        • CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_INVALID_OPERATION if the device associated with command_queue does not support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueMapImageNative

        private static java.nio.ByteBuffer clEnqueueMapImageNative​(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)
      • clEnqueueUnmapMemObject

        public static int clEnqueueUnmapMemObject​(cl_command_queue command_queue,
                                                  cl_mem memobj,
                                                  java.nio.ByteBuffer mapped_ptr,
                                                  int num_events_in_wait_list,
                                                  cl_event[] event_wait_list,
                                                  cl_event event)

        Enqueues a command to unmap a previously mapped region of a memory object.

        cl_int clEnqueueUnmapMemObject ( cl_command_queuecommand_queue,
        cl_memmemobj,
        void*mapped_ptr,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        Must be a valid command-queue.

        memobj

        A valid memory object. The OpenCL context associated with command_queue and memobj must be the same.

        mapped_ptr

        The host address returned by a previous call to clEnqueueMapBuffer or clEnqueueMapImage for memobj.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before clEnqueueUnmapMemObject can be executed. If event_wait_list is NULL, then clEnqueueUnmapMemObject does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular copy command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueBarrier can be used instead.

        Notes

        Reads or writes from the host using the pointer returned by clEnqueueMapBuffer or clEnqueueMapImage are considered to be complete.

        clEnqueueMapBuffer and clEnqueueMapImage increment the mapped count of the memory object. The initial mapped count value of a memory object is zero. Multiple calls to clEnqueueMapBuffer or clEnqueueMapImage on the same memory object will increment this mapped count by appropriate number of calls. clEnqueueUnmapMemObject decrements the mapped count of the memory object.

        clEnqueueMapBuffer and clEnqueueMapImage act as synchronization points for a region of the buffer object being mapped.

        Errors

        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 greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_INVALID_CONTEXT if the 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.
      • clEnqueueUnmapMemObjectNative

        private static int clEnqueueUnmapMemObjectNative​(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)
      • clEnqueueMigrateMemObjects

        public static int clEnqueueMigrateMemObjects​(cl_command_queue command_queue,
                                                     int num_mem_objects,
                                                     cl_mem[] mem_objects,
                                                     long flags,
                                                     int num_events_in_wait_list,
                                                     cl_event[] event_wait_list,
                                                     cl_event event)

        Enqueues a command to indicate which device a set of memory objects should be associated with.

        cl_int clEnqueueMigrateMemObjects ( cl_command_queue command_queue ,
        cl_uint num_mem_objects ,
        const cl_mem *mem_objects ,
        cl_mem_migration_flags flags ,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        A valid command-queue. The specified set of memory objects in mem_objects will be migrated to the OpenCL device associated with command_queue or to the host if the CL_MIGRATE_MEM_OBJECT_HOST has been specified.

        num_mem_objects

        The number of memory objects specified in mem_objects.

        mem_objects

        A pointer to a list of memory objects.

        flags

        A bit-field that is used to specify migration options. The table below describes the possible values for flags.

        cl_mem_migration flags Description
        CL_MIGRATE_MEM_OBJECT_HOST This flag indicates that the specified set of memory objects are to be migrated to the host, regardless of the target command-queue.
        CL_MIGRATE_MEM_OBJECT_- CONTENT_UNDEFINED This flag indicates that the contents of the set of memory objects are undefined after migration. The specified set of memory objects are migrated to the device associated with command_queue without incurring the overhead of migrating their contents.
        event_wait_list, num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

        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.

        Notes

        This section describes a mechanism for assigning which device an OpenCL memory object resides. A user may wish to have more explicit control over the location of their memory objects on creation. This could be used to:

        • Ensure that an object is allocated on a specific device prior to usage.
        • Preemptively migrate an object from one device to another.

        Typically, memory objects are implicitly migrated to a device for which enqueued commands, using the memory object, are targeted. clEnqueueMigrateMemObjects allows this migration to be explicitly performed ahead of the dependent commands. This allows a user to preemptively change the association of a memory object, through regular command queue scheduling, in order to prepare for another upcoming command. This also permits an application to overlap the placement of memory objects with other unrelated operations before these memory objects are needed potentially hiding transfer latencies. Once the event, returned from clEnqueueMigrateMemObjects, has been marked CL_COMPLETE the memory objects specified in mem_objects have been successfully migrated to the device associated with command_queue. The migrated memory object shall remain resident on the device until another command is enqueued that either implicitly or explicitly migrates it away.

        clEnqueueMigrateMemObjects can also be used to direct the initial placement of a memory object, after creation, possibly avoiding the initial overhead of instantiating the object on the first enqueued command to use it.

        The user is responsible for managing the event dependencies, associated with this command, in order to avoid overlapping access to memory objects. Improperly specified event dependencies passed to clEnqueueMigrateMemObjects could result in undefined results.

        Errors

        clEnqueueMigrateMemObjects 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 memory objects in memobj 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 any of the memory objects in mem_objs is not a valid memory object.
        • CL_INVALID_VALUE if num_mem_objects is zero or if mem_objects is NULL.
        • CL_INVALID_VALUE if flags is not 0 or is not any of the values described in the table above.
        • 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 the specified set of memory objects in mem_objects.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clEnqueueMigrateMemObjectsNative

        private static int clEnqueueMigrateMemObjectsNative​(cl_command_queue command_queue,
                                                            int num_mem_objects,
                                                            cl_mem[] mem_objects,
                                                            long flags,
                                                            int num_events_in_wait_list,
                                                            cl_event[] event_wait_list,
                                                            cl_event event)
      • clEnqueueNDRangeKernel

        public static int clEnqueueNDRangeKernel​(cl_command_queue command_queue,
                                                 cl_kernel kernel,
                                                 int work_dim,
                                                 long[] global_work_offset,
                                                 long[] global_work_size,
                                                 long[] local_work_size,
                                                 int num_events_in_wait_list,
                                                 cl_event[] event_wait_list,
                                                 cl_event event)

        Enqueues a command to execute a kernel on a device.

        cl_int clEnqueueNDRangeKernel ( cl_command_queuecommand_queue,
        cl_kernelkernel,
        cl_uintwork_dim,
        const size_t*global_work_offset,
        const size_t*global_work_size,
        const size_t*local_work_size,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue. The kernel will be queued for execution on the device associated with command_queue.

        kernel

        A valid kernel object. The OpenCL context associated with kernel and command_queue must be the same.

        work_dim

        The number of dimensions used to specify the global work-items and work-items in the work-group. work_dim must be greater than zero and less than or equal to CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS.

        global_work_offset

        global_work_offset can be used to specify an array of work_dim unsigned values that describe the offset used to calculate the global ID of a work-item. If global_work_offset is NULL, the global IDs start at offset (0, 0, ... 0).

        global_work_size

        Points to an array of work_dim unsigned values that describe the number of global work-items in work_dim dimensions that will execute the kernel function. The total number of global work-items is computed as global_work_size[0] *...* global_work_size[work_dim - 1].

        The values specified in global_work_size + corresponding values specified in global_work_offset cannot exceed the range given by the sizeof(size_t) for the device on which the kernel execution will be enqueued. The sizeof(size_t) for a device can be determined using CL_DEVICE_ADDRESS_BITS in the table of OpenCL Device Queries for clGetDeviceInfo. If, for example, CL_DEVICE_ADDRESS_BITS = 32, i.e. the device uses a 32-bit address space, size_t is a 32-bit unsigned integer and global_work_size values must be in the range 1 .. 2^32 - 1. Values outside this range return a CL_OUT_OF_RESOURCES error.

        local_work_size

        Points to an array of work_dim unsigned values that describe the number of work-items that make up a work-group (also referred to as the size of the work-group) that will execute the kernel specified by kernel. The total number of work-items in a work-group is computed as local_work_size[0] *... * local_work_size[work_dim - 1]. The total number of work-items in the work-group must be less than or equal to the CL_DEVICE_MAX_WORK_GROUP_SIZE value specified in table of OpenCL Device Queries for clGetDeviceInfo and the number of work-items specified in local_work_size[0],... local_work_size[work_dim - 1] must be less than or equal to the corresponding values specified by CL_DEVICE_MAX_WORK_ITEM_SIZES[0],.... CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim - 1]. The explicitly specified local_work_size will be used to determine how to break the global work-items specified by global_work_size into appropriate work-group instances. If local_work_size is specified, the values specified in global_work_size[0],... global_work_size[work_dim - 1] must be evenly divisible by the corresponding values specified in local_work_size[0],... local_work_size[work_dim - 1].

        The work-group size to be used for kernel can also be specified in the program source using the __attribute__((reqd_work_group_size(X, Y, Z)))qualifier. In this case the size of work group specified by local_work_size must match the value specified by the reqd_work_group_size __attribute__ qualifier.

        local_work_size can also be a NULL value in which case the OpenCL implementation will determine how to be break the global work-items into appropriate work-group instances.

        See note for more information.

        These work-group instances are executed in parallel across multiple compute units or concurrently on the same compute unit.

        Each work-item is uniquely identified by a global identifier. The global ID, which can be read inside the kernel, is computed using the value given by global_work_size and global_work_offset. In addition, a work-item is also identified within a work-group by a unique local ID. The local ID, which can also be read by the kernel, is computed using the value given by local_work_size. The starting local ID is always (0, 0, ... 0).

        event_wait_list and num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.

        Errors

        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_GLOBAL_WORK_SIZE if global_work_size is NULL, or if any of the values specified in global_work_size[0], ...global_work_size [work_dim - 1] are 0 or exceed the range given by the sizeof(size_t) for the device on which the kernel execution will be enqueued.
        • CL_INVALID_GLOBAL_OFFSET if the value specified in global_work_size + the corresponding values in global_work_offset for any dimensions is greater than the sizeof(size_t) for the device on which the kernel execution will be enqueued.
        • CL_INVALID_WORK_GROUP_SIZE if local_work_size is specified and number of work-items specified by global_work_size is not evenly divisable by size of work-group given by local_work_size or does not match the work-group size specified for kernel using the __attribute__ ((reqd_work_group_size(X, Y, Z))) qualifier in program source.
        • CL_INVALID_WORK_GROUP_SIZE if local_work_size is specified and the total number of work-items in the work-group computed as local_work_size[0] *... local_work_size[work_dim - 1] is greater than the value specified by CL_DEVICE_MAX_WORK_GROUP_SIZE in the table of OpenCL Device Queries for clGetDeviceInfo.
        • CL_INVALID_WORK_GROUP_SIZE if local_work_size is NULL and the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier is used to declare the work-group size for kernel in the program source.
        • 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_MISALIGNED_SUB_BUFFER_OFFSET if a sub-buffer object is specified as the value for an argument that is a buffer object and the offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_INVALID_IMAGE_SIZE if an image object is specified as an argument value and the image dimensions (image width, height, specified or compute row and/or slice pitch) are not supported by device associated with queue.
        • 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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the 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.
      • clEnqueueNDRangeKernelNative

        private static int clEnqueueNDRangeKernelNative​(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)
      • clEnqueueTask

        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)
        Deprecated.
        As of OpenCL 2.0

        Enqueues a command to execute a kernel on a device.

        cl_int clEnqueueTask ( cl_command_queuecommand_queue,
        cl_kernelkernel,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue. The kernel will be queued for execution on the device associated with command_queue.

        kernel

        A valid kernel object. The OpenCL context associated with kernel and command_queue must be the same.

        num_events_in_wait_list and event_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.

        Notes

        The kernel is executed using a single work-item.

        clEnqueueTask is equivalent to calling clEnqueueNDRangeKernel with work_dim = 1, global_work_offset = NULL, global_work_size[0] set to 1, and local_work_size[0] set to 1.

        Errors

        Returns CL_SUCCESS if the kernel execution was successfully queued, or one of the errors below:

        • 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_MISALIGNED_SUB_BUFFER_OFFSET if a sub-buffer object is specified as the value for an argument that is a buffer object and the offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN value for device associated with queue.
        • CL_INVALID_IMAGE_SIZE if an image object is specified as an argument value and the image dimensions (image width, height, specified or compute row and/or slice pitch) are not supported by device associated with queue.
        • 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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the 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 is greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueNativeKernel

        public static int clEnqueueNativeKernel​(cl_command_queue command_queue,
                                                EnqueueNativeKernelFunction user_func,
                                                java.lang.Object args,
                                                long cb_args,
                                                int num_mem_objects,
                                                cl_mem[] mem_list,
                                                Pointer[] args_mem_loc,
                                                int num_events_in_wait_list,
                                                cl_event[] event_wait_list,
                                                cl_event event)

        Enqueues a command to execute a native C/C++ function not compiled using the OpenCL compiler.

        cl_int clEnqueueNativeKernel ( cl_command_queuecommand_queue,
        void(*user_func)(void *),
        void*args,
        size_tcb_args,
        cl_uintnum_mem_objects,
        const cl_mem*mem_list,
        const void**args_mem_loc,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue. A native user function can only be executed on a command-queue created on a device that has CL_EXEC_NATIVE_KERNEL capability set in CL_DEVICE_EXECUTION_CAPABILITIES as specified in the table of OpenCL Device Queries for clGetDeviceInfo.

        user_func

        A pointer to a host-callable user function.

        args

        A pointer to the args list that user_func should be called with.

        cb_args

        The size in bytes of the args list that args points to.

        The data pointed to by args and cb_args bytes in size will be copied and a pointer to this copied region will be passed to user_func. The copy needs to be done because the memory objects (cl_mem values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When clEnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

        num_mem_objects

        The number of buffer objects that are passed in args.

        mem_list

        A list of valid buffer objects, if num_mem_objects is greater than 0. The buffer object values specified in mem_list are memory object handles (cl_mem values) returned by clCreateBuffer or NULL.

        args_mem_loc

        A pointer to appropriate locations that args points to where memory object handles (cl_mem values) are stored. Before the user function is executed, the memory object handles are replaced by pointers to global memory.

        event_wait_list and num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same.

        event

        Returns an event object that identifies this particular kernel execution instance. Event objects are unique and can be used to identify a particular kernel execution instance later on. If event is NULL, no event will be created for this kernel execution instance and therefore it will not be possible for the application to query or queue a wait for this particular kernel execution instance.

        Notes

        The data pointed to by args and cb_args bytes in size will be copied and a pointer to this copied region will be passed to user_func. The copy needs to be done because the memory objects (cl_mem values) that args may contain need to be modified and replaced by appropriate pointers to global memory. When clEnqueueNativeKernel returns, the memory region pointed to by args can be reused by the application.

        Errors

        Returns CL_SUCCESS if the user function execution instance was successfully queued, or one of the errors below:

        • 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 is greater than 0, or if args is a NULL value and num_mem_objects is greater than 0.
        • CL_INVALID_VALUE if args is not NULL and cb_args is 0.
        • CL_INVALID_VALUE if num_mem_objects is greater than 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 the device associated with command_queue 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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • 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 is greater than 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueMarkerWithWaitList

        public static int clEnqueueMarkerWithWaitList​(cl_command_queue command_queue,
                                                      int num_events_in_wait_list,
                                                      cl_event[] event_wait_list,
                                                      cl_event event)

        Enqueues a marker command which waits for either a list of events to complete, or all previously enqueued commands to complete.

        cl_int clEnqueueMarkerWithWaitList ( cl_command_queue command_queue ,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        A valid command-queue.

        event_wait_list num_events_in_wait_list

        These functions specify events that need to complete before this particular command can be executed.

        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. The memory associated with event_wait_list can be reused or freed after the function returns.

        If event_wait_list is NULL, then this particular command waits until all previous enqueued commands to command_queue have completed.

        event

        Returns an event object that identifies this particular command. Event objects are unique and can be used to identify this marker command later on. 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.

        Description

        Enqueues a marker command which waits for either a list of events to complete, or if the list is empty it waits for all commands previously enqueued in command_queue to complete before it completes. This command returns an event which can be waited on, i.e. this event can be waited on to insure that all events either in the event_wait_list or all previously enqueued commands, queued before this command to command_queue, have completed.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clEnqueueMarkerWithWaitListNative

        private static int clEnqueueMarkerWithWaitListNative​(cl_command_queue command_queue,
                                                             int num_events_in_wait_list,
                                                             cl_event[] event_wait_list,
                                                             cl_event event)
      • clEnqueueBarrierWithWaitList

        public static int clEnqueueBarrierWithWaitList​(cl_command_queue command_queue,
                                                       int num_events_in_wait_list,
                                                       cl_event[] event_wait_list,
                                                       cl_event event)

        A synchronization point that enqueues a barrier operation.

        cl_int clEnqueueBarrierWithWaitList ( cl_command_queue command_queue ,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        A valid command queue.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed.

        If event_wait_list is NULL, 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. The memory associated with event_wait_list can be reused or freed after the function returns.

        If event_wait_list is NULL, then this particular command waits until all previous enqueued commands to command_queue have completed.

        event

        Returns an event object that identifies this particular command. Event objects are unique and can be used to identify this barrier command later on. 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.

        Notes

        Enqueues a barrier command which waits for either a list of events to complete, or if the list is empty it waits for all commands previously enqueued in command_queue to complete before it completes. This command blocks command execution, that is, any following commands enqueued after it do not execute until it completes. This command returns an event which can be waited on, i.e. this event can be waited on to insure that all events either in the event_wait_list or all previously enqueued commands, queued before this command to command_queue, have completed.

        Errors

        Returns CL_SUCCESS if the function was successfully executed. Otherwise, it returns one of the following errors:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
        Since:
        OpenCL 1.2
      • clEnqueueBarrierWithWaitListNative

        private static int clEnqueueBarrierWithWaitListNative​(cl_command_queue command_queue,
                                                              int num_events_in_wait_list,
                                                              cl_event[] event_wait_list,
                                                              cl_event event)
      • clSetPrintfCallback

        public static int clSetPrintfCallback​(cl_context context,
                                              PrintfCallbackFunction pfn_notify,
                                              java.lang.Object user_data)
        Deprecated.
        As of OpenCL 2.0
        (Not documented in Khronos OpenCL registry)
      • clSetPrintfCallbackNative

        private static int clSetPrintfCallbackNative​(cl_context context,
                                                     PrintfCallbackFunction pfn_notify,
                                                     java.lang.Object user_data)
      • clEnqueueSVMFree

        public static int clEnqueueSVMFree​(cl_command_queue command_queue,
                                           int num_svm_pointers,
                                           Pointer[] svm_pointers,
                                           SVMFreeFunction pfn_free_func,
                                           java.lang.Object user_data,
                                           int num_events_in_wait_list,
                                           cl_event[] event_wait_list,
                                           cl_event event)

        Enqueues a command to free the shared virtual memory allocated using clSVMAlloc or a shared system memory pointer.

        cl_int clEnqueueSVMFree ( cl_command_queue command_queue,
        cl_uint num_svm_pointers ,
        void *svm_pointers[] ,
        void (CL_CALLBACK *pfn_free_func) ( cl_command_queue queue, cl_uint num_svm_pointers, void *svm_pointers[]),
        void *user_data),
        void *user_data,
        cl_uint num_events_in_wait_list,
        const cl_event *event_wait_list,
        cl_event *event)

        Parameters

        command_queue

        A valid host command-queue.

        svm_pointers and num_svm_pointers

        Specify shared virtual memory pointers to be freed. Each pointer in svm_pointers that was allocated using clSVMAlloc must have been allocated from the same context from which command_queue was created. The memory associated with svm_pointers can be reused or freed after the function returns.

        pfn_free_func

        Specifies the callback function to be called to free the SVM pointers. pfn_free_func takes four arguments: queue which is the command queue in which clEnqueueSVMFree was enqueued, the count and list of SVM pointers to free and user_data which is a pointer to user specified data. If pfn_free_func is NULL, all pointers specified in svm_pointers must be allocated using clSVMAlloc and the OpenCL implementation will free these SVM pointers. pfn_free_func must be a valid callback function if any SVM pointer to be freed is a shared system memory pointer i.e. not allocated using clSVMAlloc. If pfn_free_func is a valid callback function, the OpenCL implementation will call pfn_free_func to free all the SVM pointers specified in svm_pointers.

        user_data

        Will be passed as the user_data argument when pfn_free_func is called. user_data can be NULL.

        event_wait_list and num_events_in_wait_list

        Specify events that need to complete before clEnqueueSVMFree can be executed. If event_wait_list is NULL, then clEnqueueSVMFree 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. The memory associated with event_wait_list can be reused or freed after the function returns.

        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.

        Errors

        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 host command-queue.
        • CL_INVALID_VALUE if num_svm_pointers is 0 or if svm_pointers is NULL or if any of the pointers specified in svm_pointers array 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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        Shared Virtual Memory Functions

      • clEnqueueSVMFreeNative

        private static int clEnqueueSVMFreeNative​(cl_command_queue command_queue,
                                                  int num_svm_pointers,
                                                  Pointer[] svm_pointers,
                                                  SVMFreeFunction pfn_free_func,
                                                  java.lang.Object user_data,
                                                  int num_events_in_wait_list,
                                                  cl_event[] event_wait_list,
                                                  cl_event event)
      • clEnqueueSVMMemcpy

        public static int clEnqueueSVMMemcpy​(cl_command_queue command_queue,
                                             boolean blocking_copy,
                                             Pointer dst_ptr,
                                             Pointer src_ptr,
                                             long size,
                                             int num_events_in_wait_list,
                                             cl_event[] event_wait_list,
                                             cl_event event)

        Enqueues a command to do a memcpy operation.

        cl_int clEnqueueSVMMemcpy ( cl_command_queue command_queue,
        cl_bool blocking_copy ,
        void *dst_ptr ,
        const void *src_ptr ,
        size_t size ,
        cl_uint num_events_in_wait_list,
        const cl_event *event_wait_list,
        cl_event *event)

        Parameters

        command_queue

        Refers to the host command-queue in which the read / write command will be queued. command_queue and buffer must be created with the same OpenCL context.

        blocking_copy

        Indicates if the copy operation is blocking or non-blocking.

        If blocking_copy is CL_TRUE i.e. the copy command is blocking, clEnqueueSVMMemcpy does not return until the buffer data has been copied into memory pointed to by dst_ptr.

        If blocking_copy is CL_FALSE i.e. the copy command is non-blocking, clEnqueueSVMMemcpy queues a non-blocking copy command and returns. The contents of the buffer that dst_ptr point to cannot be used until the copy 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 copy command has completed, the contents of the buffer that dst_ptr points to can be used by the application.

        size

        The size in bytes of data being copied.

        dst_ptr

        The pointer to a memory region where data is copied to.

        src_ptr

        The pointer to a memory region where data is copied from.

        If dst_ptr and/or src_ptr are allocated using clSVMAlloc then they must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

        event_wait_list and num_events_in_wait_list

        Specify events that need to complete before clEnqueueSVMMemcpy can be executed. If event_wait_list is NULL, then clEnqueueSVMMemcpy 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. The memory associated with event_wait_list can be reused or freed after the function returns.

        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.

        Errors

        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 host command-queue.
        • CL_INVALID_CONTEXT if the context associated with command_queue and events in event_wait_list are not the same.
        • 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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the copy operation is blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_INVALID_VALUE if dst_ptr or src_ptr are NULL.
        • CL_INVALID_VALUE if size is 0.
        • CL_MEM_COPY_OVERLAP if the values specified for dst_ptr, src_ptr and size result in an overlapping copy.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        Shared Virtual Memory Functions

      • clEnqueueSVMMemcpyNative

        private static int clEnqueueSVMMemcpyNative​(cl_command_queue command_queue,
                                                    boolean blocking_copy,
                                                    Pointer dst_ptr,
                                                    Pointer src_ptr,
                                                    long size,
                                                    int num_events_in_wait_list,
                                                    cl_event[] event_wait_list,
                                                    cl_event event)
      • clEnqueueSVMMemFill

        public static int clEnqueueSVMMemFill​(cl_command_queue command_queue,
                                              Pointer svm_ptr,
                                              Pointer pattern,
                                              long pattern_size,
                                              long size,
                                              int num_events_in_wait_list,
                                              cl_event[] event_wait_list,
                                              cl_event event)

        Enqueues a command to fill a region in memory with a pattern of a given pattern size.

        cl_int clEnqueueSVMMemFill ( cl_command_queue command_queue ,
        void *svm_ptr ,
        const void *pattern ,
        size_t pattern_size ,
        size_t size ,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        Refers to the host command-queue in which the fill command will be queued. The OpenCL context associated with command_queue and SVM pointer referred to by svm_ptr must be the same.

        svm_ptr

        A pointer to a memory region that will be filled with pattern. It must be aligned to pattern_size bytes. If svm_ptr is allocated using clSVMAlloc then it must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

        pattern

        A pointer to the data pattern of size pattern_size in bytes. pattern will be used to fill a region in buffer starting at svm_ptr and is size bytes in size. The data pattern must be a scalar or vector integer or floating-point data type. For example, if region pointed to by svm_ptr is to be filled with a pattern of float4 values, then pattern will be a pointer to a cl_float4 value and pattern_size will be sizeof(cl_float4). The maximum value of pattern_size is the size of the largest integer or floating-point vector data type supported by the OpenCL device. The memory associated with pattern can be reused or freed after the function returns.

        size

        The size in bytes of region being filled starting with svm_ptr and must be a multiple of pattern_size.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

        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. clEnqueueBarrierWithWaitList can be used instead. 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.

        Errors

        clEnqueueSVMMemFill 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 host command-queue.
        • CL_INVALID_CONTEXT if the context associated with command_queue and events in event_wait_list are not the same.
        • CL_INVALID_VALUE if svm_ptr is NULL.
        • CL_INVALID_VALUE if svm_ptr is not aligned to pattern_size bytes.
        • CL_INVALID_VALUE if pattern is NULL or if pattern_size is 0 or if pattern_size is not one of {1, 2, 4, 8, 16, 32, 64, 128}.
        • CL_INVALID_VALUE if size is not a multiple of pattern_size.
        • 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        Shared Virtual Memory Functions

      • clEnqueueSVMMemFillNative

        private static int clEnqueueSVMMemFillNative​(cl_command_queue command_queue,
                                                     Pointer svm_ptr,
                                                     Pointer pattern,
                                                     long pattern_size,
                                                     long size,
                                                     int num_events_in_wait_list,
                                                     cl_event[] event_wait_list,
                                                     cl_event event)
      • clEnqueueSVMMap

        public static int clEnqueueSVMMap​(cl_command_queue command_queue,
                                          boolean blocking_map,
                                          long flags,
                                          Pointer svm_ptr,
                                          long size,
                                          int num_events_in_wait_list,
                                          cl_event[] event_wait_list,
                                          cl_event event)

        Enqueues a command that will allow the host to update a region of a SVM buffer.

        cl_int clEnqueueSVMMap ( cl_command_queue command_queue,
        cl_bool blocking_map,
        cl_map_flags map_flags,
        void *svm_ptr,
        size_t size,
        cl_uint num_events_in_wait_list,
        const cl_event *event_wait_list,
        cl_event *event)

        Parameters

        command_queue

        Must be a valid host command-queue.

        blocking_map

        Indicates if the map operation is blocking or non-blocking.

        If blocking_map is CL_TRUE, clEnqueueSVMMap does not return until the application can access the contents of the SVM region specified by svm_ptr and size on the host.

        If blocking_map is CL_FALSE i.e. map operation is non-blocking, the region specified by svm_ptr and size 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 region specified by svm_ptr and size.

        map_flags

        A bit-bield with the following supported values.

        cl_map_flags Description
        CL_MAP_READ

        This flag specifies that the region being mapped in the memory object is being mapped for reading.

        The pointer returned by clEnqueueMap{Buffer|Image} is guaranteed to contain the latest bits in the region being mapped when the clEnqueueMap{Buffer|Image} command has completed.

        CL_MAP_WRITE

        This flag specifies that the region being mapped in the memory object is being mapped for writing.

        The pointer returned by clEnqueueMap{Buffer|Image} is guaranteed to contain the latest bits in the region being mapped when the clEnqueueMap{Buffer|Image} command has completed.

        CL_MAP_WRITE_INVALIDATE_REGION

        This flag specifies that the region being mapped in the memory object is being mapped for writing.

        The contents of the region being mapped are to be discarded. This is typically the case when the region being mapped is overwritten by the host. This flag allows the implementation to no longer guarantee that the pointer returned by clEnqueueMap{Buffer|Image} contains the latest bits in the region being mapped which can be a significant performance enhancement.

        CL_MAP_READ or CL_MAP_WRITE and CL_MAP_WRITE_INVALIDATE_REGION are mutually exclusive.

        svm_ptr and size

        A pointer to a memory region and size in bytes that will be updated by the host. If svm_ptr is allocated using clSVMAlloc then it must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

        event_wait_list, num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

        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. clEnqueueBarrierWithWaitList can be used instead. 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.

        Notes

        Note that since we are enqueuing a command with a SVM buffer, the region is already mapped in the host address space.

        clEnqueueSVMMap, and clEnqueueSVMUnmap act as synchronization points for the region of the SVM buffer specified in these calls.

        Errors

        clEnqueueSVMMap 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 host command-queue.
        • CL_INVALID_CONTEXT if the context associated with command_queue and events in event_wait_list are not the same.
        • CL_INVALID_VALUE if svm_ptr is NULL.
        • CL_INVALID_VALUE if size is 0 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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the map operation is blocking and the execution status of any of the events in event_wait_list is a negative integer value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        Shared Virtual Memory Functions

      • clEnqueueSVMMapNative

        private static int clEnqueueSVMMapNative​(cl_command_queue command_queue,
                                                 boolean blocking_map,
                                                 long flags,
                                                 Pointer svm_ptr,
                                                 long size,
                                                 int num_events_in_wait_list,
                                                 cl_event[] event_wait_list,
                                                 cl_event event)
      • clEnqueueSVMUnmap

        public static int clEnqueueSVMUnmap​(cl_command_queue command_queue,
                                            Pointer svm_ptr,
                                            int num_events_in_wait_list,
                                            cl_event[] event_wait_list,
                                            cl_event event)

        Enqueues a command to indicate that the host has completed updating the region given by svm_ptr and which was specified in a previous call to clEnqueueSVMMap.

        cl_int clEnqueueSVMUnmap ( cl_command_queue command_queue ,
        void *svm_ptr,
        cl_uint num_events_in_wait_list ,
        const cl_event *event_wait_list ,
        cl_event *event )

        Parameters

        command_queue

        Must be a valid host command-queue.

        svm_ptr

        A pointer that was specified in a previous call to clEnqueueSVMMap. If svm_ptr is allocated using clSVMAlloc then it must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before clEnqueueSVMUnmap can be executed. If event_wait_list is NULL, then clEnqueueSVMUnmap 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. The memory associated with event_wait_list can be reused or freed after the function returns.

        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. clEnqueueBarrierWithWaitList can be used instead. 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.

        Notes

        clEnqueueSVMMap, and clEnqueueSVMUnmap act as synchronization points for the region of the SVM buffer specified in these calls.

        If a coarse-grained SVM buffer is currently mapped for writing, the application must ensure that the SVM buffer is unmapped before any enqueued kernels or commands that read from or write to this SVM buffer or any of its associated cl_mem buffer objects begin execution; otherwise the behavior is undefined.

        If a coarse-grained SVM buffer is currently mapped for reading, the application must ensure that the SVM buffer is unmapped before any enqueued kernels or commands that write to this memory object or any of its associated cl_mem buffer objects begin execution; otherwise the behavior is undefined.

        A SVM buffer is considered as mapped if there are one or more active mappings for the SVM buffer irrespective of whether the mapped regions span the entire SVM buffer.

        The above note does not apply to fine-grained SVM buffers (fine-grained buffers allocated using clSVMAlloc or fine-grained system allocations).

        Errors

        clEnqueueSVMUnmap 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 host 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 svm_ptr 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_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        Shared Virtual Memory Functions

      • clEnqueueSVMUnmapNative

        private static int clEnqueueSVMUnmapNative​(cl_command_queue command_queue,
                                                   Pointer svm_ptr,
                                                   int num_events_in_wait_list,
                                                   cl_event[] event_wait_list,
                                                   cl_event event)
      • clEnqueueMarker

        public static int clEnqueueMarker​(cl_command_queue command_queue,
                                          cl_event event)
        Deprecated.
        As of OpenCL 1.2

        Enqueues a marker command.

        cl_int clEnqueueMarker ( cl_command_queuecommand_queue,
        cl_event*event)

        Notes

        Enqueues a marker command to command_queue. The marker command is not completed until all commands enqueued before it have completed. The marker command returns an event which can be waited on, i.e. this event can be waited on to ensure that all commands which have been queued before the market command have been completed. complete.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_INVALID_VALUE if event is a NULL value.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueWaitForEvents

        public static int clEnqueueWaitForEvents​(cl_command_queue command_queue,
                                                 int num_events,
                                                 cl_event[] event_list)
        Deprecated.
        As of OpenCL 1.2

        Enqueues a wait for a specific event or a list of events to complete before any future commands queued in the command-queue are executed.

        cl_int clEnqueueWaitForEvents ( cl_command_queuecommand_queue,
        cl_uintnum_events,
        const cl_event*event_list)

        Parameters

        command_queue

        A valid command-queue.

        num_events

        Specifies the number of events given by event_list.

        event_list

        Events specified in event_list act as synchronization points. The context associated with events in event_list and command_queue must be the same. Each event in event_list must be a valid event object returned by a previous call to the following:

        • clEnqueueNDRangeKernel
        • clEnqueueTask
        • clEnqueueNativeKernel
        • clEnqueueReadImage
        • clEnqueueWriteImage
        • clEnqueueMapImage
        • clEnqueueReadBuffer
        • clEnqueueWriteBuffer
        • clEnqueueMapBuffer
        • clEnqueueUnmapMemObject
        • clEnqueueReadBufferRect
        • clEnqueueWriteBufferRect
        • clEnqueueCopyBuffer
        • clEnqueueCopyImage
        • clEnqueueCopyBufferRect
        • clEnqueueCopyBufferToImage
        • clEnqueueCopyImageToBuffer
        • clEnqueueMarker

        Notes

        The context associated with events in event_list and command_queue must be the same.

        Errors

        Returns CL_SUCCESS if the function was successfully executed, or one of the errors below:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_INVALID_CONTEXT if the context associated with command_queue and events in event_list are not the same.
        • CL_INVALID_VALUE if num_events is zero or event_list is NULL.
        • CL_INVALID_EVENT if event objects specified in event_list are not valid events.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueWaitForEventsNative

        private static int clEnqueueWaitForEventsNative​(cl_command_queue command_queue,
                                                        int num_events,
                                                        cl_event[] event_list)
      • clEnqueueBarrier

        public static int clEnqueueBarrier​(cl_command_queue command_queue)
        Deprecated.
        As of OpenCL 1.2

        A synchronization point that enqueues a barrier operation.

        cl_int clEnqueueBarrier ( cl_command_queuecommand_queue)

        Notes

        clEnqueueBarrier is a synchronization point that ensures that all queued commands in command_queue have finished execution before the next batch of commands can begin execution.

        Errors

        Returns CL_SUCCESS if the function was successfully executed, or one of the errors below:

        • CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueBarrierNative

        private static int clEnqueueBarrierNative​(cl_command_queue command_queue)
      • clCreateFromGLBuffer

        public static cl_mem clCreateFromGLBuffer​(cl_context context,
                                                  long flags,
                                                  int bufobj,
                                                  int[] errcode_ret)

        Creates an OpenCL buffer object from an OpenGL buffer object.

        cl_mem clCreateFromGLBuffer ( cl_contextcontext,
        cl_mem_flagsflags,
        GLuintbufobj,
        cl_int* errcode_ret)

        Parameters

        context

        A valid OpenCL context created from an OpenGL context.

        flags

        A bit-field that is used to specify usage information. Refer to the table for clCreateBuffer for a description of flags. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in the table at clCreateBuffer can be used.

        bufobj

        The name of a GL buffer object. The data store of the GL buffer object must have have been previously created by calling OpenGL function glBufferData, although its contents need not be initialized. The size of the data store will be used to determine the size of the CL buffer object.

        errcode_ret

        Returns an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

        Description

        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.

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateFromGLBufferNative

        private static cl_mem clCreateFromGLBufferNative​(cl_context context,
                                                         long flags,
                                                         int bufobj,
                                                         int[] errcode_ret)
      • clCreateFromGLTexture

        public static cl_mem clCreateFromGLTexture​(cl_context context,
                                                   long flags,
                                                   int target,
                                                   int miplevel,
                                                   int texture,
                                                   int[] errcode_ret)

        Creates an OpenCL image object, image array object, or image buffer object from an OpenGL texture object, texture array object, texture buffer object, or a single face of an OpenGL cubemap texture object.

        cl_mem clCreateFromGLTexture ( cl_context context,
        cl_mem_flags flags,
        GLenum texture_target,
        GLint miplevel,
        GLuint texture,
        cl_int * errcode_ret)

        Parameters

        context

        A valid OpenCL context created from an OpenGL context.

        flags

        A bit-field that is used to specify usage information. Refer to the table for clCreateBuffer for a description of flags. Only the values CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE can be used.

        texture_target

        texture_target This value must be one of GL_TEXTURE_1D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_BUFFER, GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D, 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. (GL_TEXTURE_RECTANGLE requires OpenGL 3.1. Alternatively, GL_TEXTURE_RECTANGLE_ARB may be specified if the OpenGL extension GL_ARB_texture_rectangle is supported.) 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.

        If the cl_khr_gl_msaa_sharing extension is enabled, texture_target may be GL_TEXTURE_2D_MULTISAMPLE or GL_TEXTURE_2D_MULTISAMPLE_ARRAY.

        If texture_target is GL_TEXTURE_2D_MULTISAMPLE, clCreateFromGLTexture creates an OpenCL 2D multi-sample image object from an OpenGL 2D multi-sample texture

        If texture_target is GL_TEXTURE_2D_MULTISAMPLE_ARRAY, clCreateFromGLTexture creates an OpenCL 2D multi-sample array image object from an OpenGL 2D multi-sample texture.

        miplevel

        The mipmap level to be used. If texture_target is GL_TEXTURE_BUFFER, miplevel must be 0. Implementations may return CL_INVALID_OPERATION for miplevel values > 0

        texture

        The name of a GL 1D, 2D, 3D, 1D array, 2D array, cubemap, rectangle or buffer 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 OpenCL image memory object. Only GL texture objects with an internal format that maps to appropriate image channel order and data type specified in tables 5.5 and 5.6 (see cl_image_format) may be used to create the OpenCL image memory object.

        errcode_ret

        Returns an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

        Notes

        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.

        The OpenCL specification in section 9.7 defines how to share data with texture and buffer objects in a parallel OpenGL implementation, but does not define how the association between an OpenCL context and an OpenGL context or share group is established. This extension defines optional attributes to OpenCL context creation routines which associate a GL context or share group object with a newly created OpenCL context. If this extension is supported by an implementation, the string "cl_khr_gl_sharing" will be present in the CL_DEVICE_EXTENSIONS string described in the table of allowed values for param_name for clGetDeviceInfo or in the CL_PLATFORM_EXTENSIONS string described in the table of allowed values for param_name for clGetPlatformInfo.

        This section discusses OpenCL functions that allow applications to use OpenGL buffer, texture, and renderbuffer objects as OpenCL memory objects. This allows efficient sharing of data between OpenCL and OpenGL. The OpenCL API may be used to execute kernels that read and/or write memory objects that are also OpenGL objects.

        An OpenCL image object may be created from an OpenGL texture or renderbuffer object. An OpenCL buffer object may be created from an OpenGL buffer object.

        OpenCL memory objects may be created from OpenGL objects if and only if the OpenCL context has been created from an OpenGL share group object or context. OpenGL share groups and contexts are created using platform specific APIs such as EGL, CGL, WGL, and GLX. On MacOS X, an OpenCL context may be created from an OpenGL share group object using the OpenCL platform extension cl_apple_gl_sharing. On other platforms including Microsoft Windows, Linux/Unix and others, an OpenCL context may be created from an OpenGL context using the Khronos platform extension cl_khr_gl_sharing. Refer to the platform documentation for your OpenCL implementation, or visit the Khronos Registry at http://www.khronos.org/registry/cl/ for more information.

        Any supported OpenGL object defined within the GL share group object, or the share group associated with the GL context from which the CL context is created, may be shared, with the exception of the default OpenGL objects (i.e. objects named zero), which may not be shared.

        OpenGL and Corresponding OpenCL Image Formats

        The table below (Table 9.4) describes the list of GL texture internal formats and the corresponding CL image formats. If a GL texture object with an internal format from the table below is successfully created by OpenGL, then there is guaranteed to be a mapping to one of the corresponding CL image format(s) in that table. Texture objects created with other OpenGL internal formats may (but are not guaranteed to) have a mapping to a CL image format; if such mappings exist, they are guaranteed to preserve all color components, data types, and at least the number of bits/component actually allocated by OpenGL for that format.

        GL internal format CL image format (channel order, channel data type)
        GL_RGBA8 CL_RGBA, CL_UNORM_INT8 or CL_BGRA, CL_UNORM_INT8
        GL_SRGBA8_ALPHA8 CL_sRGBA, CL_UNORM_INT8
        GL_RGBA, GL_UNSIGNED_INT_8_8_8_8_REV CL_RGBA, CL_UNORM_INT8
        GL_BGRA, GL_UNSIGNED_INT_8_8_8_8_REV CL_BGRA, CL_UNORM_INT8
        GL_RGBA8I, GL_RGBA8I_EXT CL_RGBA, CL_SIGNED_INT8
        GL_RGBA16I, GL_RGBA16I_EXT CL_RGBA, CL_SIGNED_INT16
        GL_RGBA32I, GL_RGBA32I_EXT CL_RGBA, CL_SIGNED_INT32
        GL_RGBA8UI, GL_RGBA8UI_EXT CL_RGBA, CL_UNSIGNED_INT8
        GL_RGBA16UI, GL_RGBA16UI_EXT CL_RGBA, CL_UNSIGNED_INT16
        GL_RGBA32UI, GL_RGBA32UI_EXT CL_RGBA, CL_UNSIGNED_INT32
        GL_RGBA8_SNORM CL_RGBA, CL_SNORM_INT8
        GL_RGBA16 CL_RGBA, CL_UNORM_INT16
        GL_RGBA16_SNORM CL_RGBA, CL_SNORM_INT166
        GL_RGBA16F, GL_RGBA16F_ARB CL_RGBA, CL_HALF_FLOAT
        GL_RGBA32F, GL_RGBA32F_ARB CL_RGBA, CL_FLOAT
        GL_R8 CL_R, CL_UNORM_INT8
        GL_R8_SNORM CL_R, CL_SNORM_INT8
        GL_R16 CL_R, CL_UNORM_INT16
        GL_R16_SNORM CL_R, CL_SNORM_INT16
        GL_R16F CL_R, CL_HALF_FLOAT
        GL_R32F CL_R, CL_FLOAT
        GL_R8I CL_R, CL_SIGNED_INT8
        GL_R16I CL_R, CL_SIGNED_INT16
        GL_R32I CL_R, CL_SIGNED_INT32
        GL_R8UI CL_R, CL_UNSIGNED_INT8
        GL_R16UI CL_R, CL_UNSIGNED_INT16
        GL_R32UI CL_R, CL_UNSIGNED_INT32
        GL_RG8 CL_RG, CL_UNORM_INT8
        GL_RG8_SNORM CL_RG, CL_SNORM_INT8
        GL_RG16 CL_RG, CL_UNORM_INT16
        GL_RG16_SNORM CL_RG, CL_SNORM_INT16
        GL_RG16F CL_RG, CL_HALF_FLOAT
        GL_RG32F CL_RG, CL_FLOAT
        GL_RG8I CL_RG, CL_SIGNED_INT8
        GL_RG16I CL_RG, CL_SIGNED_INT16
        GL_RG32I CL_RG, CL_SIGNED_INT32
        GL_RG8UI CL_RG, CL_UNSIGNED_INT8
        GL_RG16UI CL_RG, CL_UNSIGNED_INT16
        GL_RG32UI CL_RG, CL_UNSIGNED_INT32

        If the cl_khr_gl_depth_images extension is enabled, the following new image formats are added to table 9.4 in section 9.6.3.1 of the OpenCL 2.0 extension specification. If a GL texture object with an internal format from table 9.4 is successfully created by OpenGL, then there is guaranteed to be a mapping to one of the corresponding CL image format(s) in that table.

        GL internal format CL image format (channel order, channel data type)
        GL_DEPTH_COMPONENT32F CL_DEPTH, CL_FLOAT
        GL_DEPTH_COMPONENT16 CL_DEPTH, CL_UNORM_INT16
        GL_DEPTH24_STENCIL8 CL_DEPTH_STENCIL, CL_UNORM_INT24
        GL_DEPTH32F_STENCIL8 CL_DEPTH_STENCIL, CL_FLOAT

        Lifetime of [GL] Shared Objects

        An OpenCL memory object created from an OpenGL object (hereinafter refered to as a "shared CL/GL object") remains valid as long as the corresponding GL object has not been deleted. If the GL object is deleted through the GL API (e.g. glDeleteBuffers, glDeleteTextures, or glDeleteRenderbuffers), subsequent use of the CL buffer or image object will result in undefined behavior, including but not limited to possible CL errors and data corruption, but may not result in program termination.

        The CL context and corresponding command-queues are dependent on the existence of the GL share group object, or the share group associated with the GL context from which the CL context is created. If the GL share group object or all GL contexts in the share group are destroyed, any use of the CL context or command-queue(s) will result in undefined behavior, which may include program termination. Applications should destroy the CL command-queue(s) and CL context before destroying the corresponding GL share group or contexts.

        Synchronizing OpenCL and OpenGL Access

        In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/GL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.

        Prior to calling clEnqueueAcquireGLObjects, the application must ensure that any pending GL operations which access the objects specified in mem_objects have completed. This may be accomplished portably by issuing and waiting for completion of a glFinish command on all GL contexts with pending references to these objects. Implementations may offer more efficient synchronization methods; for example on some platforms calling glFlush may be sufficient, or synchronization may be implicit within a thread, or there may be vendor-specific extensions that enable placing a fence in the GL command stream and waiting for completion of that fence in the CL command queue. Note that no synchronization methods other than glFinish are portable between OpenGL implementations at this time.

        When the extension cl_khr_egl_event is supported: Prior to calling clEnqueueAcquireGLObjects, the application must ensure that any pending EGL or EGL client API operations which access the objects specified in mem_objects have completed. If the cl_khr_egl_event extension is supported and the EGL context in question supports fence sync objects, explicit synchronisation can be achieved as set out in section 5.7.1. If the cl_khr_egl_event extension is not supported, completion of EGL client API commands may be determined by issuing and waiting for completion of commands such as glFinish or vgFinish on all client API contexts with pending references to these objects. Some implementations may offer other efficient synchronization methods. If such methods exist they will be described in platform-specific documentation. Note that no synchronization methods other than glFinish and vgFinish are portable between all EGL client API implementations and all OpenCL implementations. While this is the only way to ensure completion that is portable to all platforms, these are expensive operation and their use should be avoided if the cl_khr_egl_event extension is supported on a platform.

        Similarly, after calling clEnqueueReleaseGLObjects, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in mem_objects have completed prior to executing subsequent GL commands which reference these objects. This may be accomplished portably by calling clWaitForEvents with the event object returned by clEnqueueReleaseGLObjects, or by calling clFinish. As above, some implementations may offer more efficient methods.

        The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.

        If a GL context is bound to a thread other than the one in which clEnqueueReleaseGLObjects is called, changes to any of the objects in mem_objects may not be visible to that context without additional steps being taken by the application. For an OpenGL 3.1 (or later) context, the requirements are described in Appendix D ("Shared Objects and Multiple Contexts") of the OpenGL 3.1 Specification. For prior versions of OpenGL, the requirements are implementation-dependent.

        Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.

        If the cl_khr_gl_event extension is supported, then the OpenCL implementation will ensure that any such pending OpenGL operations are complete for an OpenGL context bound to the same thread as the OpenCL context. This is referred to as implicit synchronization.

        Errors

        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_MIP_LEVEL if miplevel is less than the value of levelbase (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). levelbase and q are defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 specification and section 3.7.10 of the OpenGL ES 2.0.
        • CL_INVALID_MIP_LEVEL if miplevel is greater 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 or if the GL texture object is incomplete.
        • CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the OpenGL texture internal format does not map to a supported OpenCL image format.
        • CL_INVALID_OPERATION if texture is a GL texture object created with a border width value greater than zero.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

        Also see

        cl_khr_gl_sharing, clCreateBuffer, clCreateFromGLBuffer

      • clCreateFromGLTextureNative

        private static cl_mem clCreateFromGLTextureNative​(cl_context context,
                                                          long flags,
                                                          int target,
                                                          int miplevel,
                                                          int texture,
                                                          int[] errcode_ret)
      • clCreateFromGLTexture2D

        public static cl_mem clCreateFromGLTexture2D​(cl_context context,
                                                     long flags,
                                                     int target,
                                                     int miplevel,
                                                     int texture,
                                                     int[] errcode_ret)
        Deprecated.

        Creates an OpenCL 2D image object from an OpenGL 2D texture object, or a single face of an OpenGL cubemap texture object.

        cl_mem clCreateFromGLTexture2D ( cl_contextcontext,
        cl_mem_flagsflags,
        GLenumtexture_target,
        GLintmiplevel,
        GLuinttexture,
        cl_int*errcode_ret)

        Parameters

        context

        A valid OpenCL context created from an OpenGL context.

        flags

        A bit-field that is used to specify usage information. Refer to the table for clCreateBuffer for a description of flags. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE values specified in the table for clCreateBuffer may be used.

        texture_target

        Must be one of GL_TEXTURE_2D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, or GL_TEXTURE_RECTANGLE. texture_target is used only to define the image type of texture. No reference to a bound GL texture object is made or implied by this parameter.

        Using GL_TEXTURE_RECTANGLE for texture_target requires OpenGL 3.1. Alternatively, GL_TEXTURE_RECTANGLE_ARB may be specified if the OpenGL extension GL_ARB_texture_rectangle is supported.

        miplevel

        The mipmap level to be used. Implementations may return CL_INVALID_OPERATION for miplevel values greater than 0.

        texture

        The name of a GL 2D, cubemap or rectangle texture object. The texture object must be a complete texture as per OpenGL rules on texture completeness. The texture format and dimensions defined by OpenGL for the specified miplevel of the texture will be used to create the 2D image object. Only GL texture objects with an internal format that maps to appropriate image channel order and data type specified in the table of supported Image Channel Order Values and the table of supported Image Channel Data Types for cl_image_format may be used to create a 2D image object.

        errcode_ret

        Returns an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

        Errors

        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_MIP_LEVEL if miplevel is less than the value of levelbase (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). levelbase and q are defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 specification and section 3.7.10 of the OpenGL ES 2.0 specification.
        • CL_INVALID_MIP_LEVEL if miplevel is greater 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_INVALID_OPERATION if texture is a GL texture object created with a border width value greater than zero.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateFromGLTexture2DNative

        private static cl_mem clCreateFromGLTexture2DNative​(cl_context context,
                                                            long flags,
                                                            int target,
                                                            int miplevel,
                                                            int texture,
                                                            int[] errcode_ret)
      • clCreateFromGLTexture3D

        public static cl_mem clCreateFromGLTexture3D​(cl_context context,
                                                     long flags,
                                                     int target,
                                                     int miplevel,
                                                     int texture,
                                                     int[] errcode_ret)
        Deprecated.

        Creates an OpenCL 3D image object from an OpenGL 3D texture object.

        cl_mem clCreateFromGLTexture3D ( cl_contextcontext,
        cl_mem_flagsflags,
        GLenumtexture_target,
        GLintmiplevel,
        GLuinttexture,
        cl_int* errcode_ret)

        Parameters

        context

        A valid OpenCL context created from an OpenGL 3D context.

        flags

        A bit-field that is used to specify usage information. Refer to the table for clCreateBuffer for a description of flags. Only the valuesCL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE can be used.

        texture_target

        texture_target is used only to define the image type of texture. Must be GL_TEXTURE_3D. No reference to a bound GL texture object is made or implied by this parameter.

        miplevel

        The mipmap level to be used.

        texture

        The name of a GL 3D texture object. The texture object must be a complete texture as per OpenGL rules on texture completeness. The texture format and dimensions defined by OpenGL for the specified miplevel of the texture will be used to create the 3D image object. Only GL texture objects with an internal format that maps to appropriate image channel order and data type specified in the table of supported Image Channel Order Values and the table of supported Image Channel Data Types at cl_image_format can be used to create the 3D image object.

        errcode_ret

        Returns an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

        Description

        If the state of a GL texture object is modified through the GL API (e.g. the OpenGL functions glTexImage2D, glTexImage3D, or the values of the texture parameters GL_TEXTURE_BASE_LEVEL or GL_TEXTURE_MAX_LEVEL are modified) while there exists a corresponding CL image object, subsequent use of the CL image object will result in undefined behavior.

        The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the image objects.

        Errors

        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_MIP_LEVEL if miplevel is less than the value of levelbase (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). levelbase and q are defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 specification and section 3.7.10 of the OpenGL ES 2.0.
        • CL_INVALID_MIP_LEVEL if miplevel is greater 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_INVALID_OPERATION if texture is a GL texture object created with a border width value greater than zero.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateFromGLTexture3DNative

        private static cl_mem clCreateFromGLTexture3DNative​(cl_context context,
                                                            long flags,
                                                            int target,
                                                            int miplevel,
                                                            int texture,
                                                            int[] errcode_ret)
      • clCreateFromGLRenderbuffer

        public static cl_mem clCreateFromGLRenderbuffer​(cl_context context,
                                                        long flags,
                                                        int renderbuffer,
                                                        int[] errcode_ret)

        Creates an OpenCL 2D image object from an OpenGL renderbuffer object.

        cl_mem clCreateFromGLRenderbuffer ( cl_contextcontext,
        cl_mem_flagsflags,
        GLuintrenderbuffer,
        cl_int* errcode_ret)

        Parameters

        context

        A valid OpenCL context created from an OpenGL context.

        flags

        A bit-field that is used to specify usage information. Refer to the table at clCreateBuffer for a description of flags. Only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, and CL_MEM_READ_WRITE values specified in the table at clCreateBuffer can be used.

        renderbuffer

        The name of a GL renderbuffer object. The renderbuffer storage must be specified before the image object can be created. The renderbuffer format and dimensions defined by OpenGL will be used to create the 2D image object. Only GL renderbuffers with internal formats that map to appropriate image channel order and data type specified in the table of supported Image Channel Order Values and the table of supported Image Channel Data Types for cl_image_format can be used to create the 2D image object.

        errcode_ret

        Returns an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

        Description

        If the state of a GL renderbuffer object is modified through the GL API (i.e. changes to the dimensions or format used to represent pixels of the GL renderbuffer using appropriate GL API calls such as glRenderbufferStorage) while there exists a corresponding CL image object, subsequent use of the CL image object will result in undefined behavior.

        The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the image objects.

        The table below describes the list of GL renderbuffer internal formats and the corresponding CL image formats. If a GL renderbuffer object with an internal format from the table below is successfully created by OpenGL, then there is guaranteed to be a mapping to one of the corresponding CL image format(s) in that table. Renderbuffer objects created with other OpenGL internal formats may (but are not guaranteed to) have a mapping to a CL image format; if such mappings exist, they are guaranteed to preserve all color components, data types, and at least the number of bits/component actually allocated by OpenGL for that format.

        GL internal format CL image format (channel order, channel data type)
        GL_RGBA8 CL_RGBA, CL_UNORM_INT8 or CL_BGRA, CL_UNORM_INT8
        GL_RGBA16 CL_RGBA, CL_UNORM_INT16
        GL_RGBA8I, GL_RGBA8I_EXT CL_RGBA, CL_SIGNED_INT8
        GL_RGBA16I, GL_RGBA16I_EXT CL_RGBA, CL_SIGNED_INT16
        GL_RGBA32I, GL_RGBA32I_EXT CL_RGBA, CL_SIGNED_INT32
        GL_RGBA8UI, GL_RGBA8UI_EXT CL_RGBA, CL_UNSIGNED_INT8
        GL_RGBA16UI, GL_RGBA16UI_EXT CL_RGBA, CL_UNSIGNED_INT16
        GL_RGBA32UI, GL_RGBA32UI_EXT CL_RGBA, CL_UNSIGNED_INT32
        GL_RGBA16F, GL_RGBA16F_ARB CL_RGBA, CL_HALF_FLOAT
        GL_RGBA32F, GL_RGBA32F_ARB CL_RGBA, CL_FLOAT

        Errors

        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_INVALID_OPERATION if renderbuffer is a multi-sample GL renderbuffer object.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clCreateFromGLRenderbufferNative

        private static cl_mem clCreateFromGLRenderbufferNative​(cl_context context,
                                                               long flags,
                                                               int renderbuffer,
                                                               int[] errcode_ret)
      • clGetGLObjectInfo

        public static int clGetGLObjectInfo​(cl_mem memobj,
                                            int[] gl_object_type,
                                            int[] gl_object_name)

        Query an OpenGL memory object used to create an OpenCL memory object.

        cl_int clGetGLObjectInfo ( cl_memmemobj,
        cl_gl_object_type*gl_object_type,
        GLuint*gl_object_name)

        Parameters

        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.

        Description

        The OpenGL object used to create the OpenCL memory object and information about the object type i.e. whether it is a texture, renderbuffer, or buffer object can be queried using this function.

        Errors

        Returns CL_SUCCESS if the call was executed successfully. Otherwise, it returns one of the following errors:

        • CL_INVALID_MEM_OBJECT if memobj is not a valid OpenCL memory object
        • CL_INVALID_GL_OBJECT if there is no GL object associated with memobj.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetGLObjectInfoNative

        private static int clGetGLObjectInfoNative​(cl_mem memobj,
                                                   int[] gl_object_type,
                                                   int[] gl_object_name)
      • clGetGLTextureInfo

        public static int clGetGLTextureInfo​(cl_mem memobj,
                                             int param_name,
                                             long param_value_size,
                                             Pointer param_value,
                                             long[] param_value_size_ret)

        Returns additional information about the GL texture object associated with a memory object.

        cl_int clGetGLTextureInfo ( cl_memmemobj,
        cl_gl_texture_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret)

        Parameters

        param_name

        Specifies what additional information about the GL texture object associated with memobj to query. The list of supported param_name types and the information returned in param_value by clGetGLTextureInfo is described in the table below.

        param_value

        A pointer to memory where the result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be >= size of return type as described in the table below.

        param_value_size_ret

        Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored.

        cl_gl_texture_info Return Type Information returned in param_value
        CL_GL_TEXTURE_TARGET GLenum The texture_target argument specified in clCreateGLTexture2D or clCreateGLTexture3D.
        CL_GL_MIPMAP_LEVEL GLint The miplevel argument specified in clCreateGLTexture2D or clCreateGLTexture3D.

        Errors

        Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

        • 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.
        • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is less than the size of return type as described in the table above and param_value is not NULL, or if param_value and param_value_size_ret are NULL.
        • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clGetGLTextureInfoNative

        private static int clGetGLTextureInfoNative​(cl_mem memobj,
                                                    int param_name,
                                                    long param_value_size,
                                                    Pointer param_value,
                                                    long[] param_value_size_ret)
      • clEnqueueAcquireGLObjects

        public static int clEnqueueAcquireGLObjects​(cl_command_queue command_queue,
                                                    int num_objects,
                                                    cl_mem[] mem_objects,
                                                    int num_events_in_wait_list,
                                                    cl_event[] event_wait_list,
                                                    cl_event event)

        Acquire OpenCL memory objects that have been created from OpenGL objects.

        cl_int clEnqueueAcquireGLObjects ( cl_command_queuecommand_queue,
        cl_uintnum_objects,
        const cl_mem*mem_objects,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue. All devices used to create the OpenCL context associated with command_queue must support acquiring shared CL/GL objects. This constraint is enforced at context creation time.

        num_objects

        The number of memory objects to be acquired in mem_objects.

        mem_objects

        A pointer to a list of CL memory objects that correspond to GL objects.

        event_wait_list , num_events_in_wait_list

        Specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points.

        event

        Returns an event object that identifies this command and can be used to query or queue a wait for the command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        When the cl_khr_gl_event extension is enabled, If an OpenGL context is bound to the current thread, then any OpenGL commands which:

        • affect or access the contents of a memory object listed in the mem_objects list, and
        • were issued on that OpenGL context prior to the call to clEnqueueAcquireGLObjects

        will complete before execution of any OpenCL commands following the clEnqueueAcquireGLObjects which affect or access any of those memory objects. If a non-NULL event object is returned, it will report completion only after completion of such OpenGL commands.

        Description

        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.

        Notes

        In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/GL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.

        Prior to calling clEnqueueAcquireGLObjects, the application must ensure that any pending GL operations which access the objects specified in mem_objects have completed. This may be accomplished portably by issuing and waiting for completion of a glFinish command on all GL contexts with pending references to these objects. Implementations may offer more efficient synchronization methods; for example on some platforms calling glFlush may be sufficient, or synchronization may be implicit within a thread, or there may be vendor-specific extensions that enable placing a fence in the GL command stream and waiting for completion of that fence in the CL command queue. Note that no synchronization methods other than glFinish are portable between OpenGL implementations at this time.

        Similarly, after calling clEnqueueReleaseGLObjects, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in mem_objects have completed prior to executing subsequent GL commands which reference these objects. This may be accomplished portably by calling clWaitForEvents with the event object returned by clEnqueueReleaseGLObjects, or by calling glFinish. As above, some implementations may offer more efficient methods.

        The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.

        If a GL context is bound to a thread other than the one in which clEnqueueReleaseGLObjects is called, changes to any of the objects in mem_objects may not be visible to that context without additional steps being taken by the application. For an OpenGL 3.1 (or later) context, the requirements are described in Appendix G ("Shared Objects and Multiple Contexts") of the OpenGL 3.1 Specification. For prior versions of OpenGL, the requirements are implementationdependent.

        Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueAcquireGLObjectsNative

        private static int clEnqueueAcquireGLObjectsNative​(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)
      • clEnqueueReleaseGLObjects

        public static int clEnqueueReleaseGLObjects​(cl_command_queue command_queue,
                                                    int num_objects,
                                                    cl_mem[] mem_objects,
                                                    int num_events_in_wait_list,
                                                    cl_event[] event_wait_list,
                                                    cl_event event)

        Release OpenCL memory objects that have been created from OpenGL objects.

        cl_int clEnqueueReleaseGLObjects ( cl_command_queuecommand_queue,
        cl_uintnum_objects,
        const cl_mem*mem_objects,
        cl_uintnum_events_in_wait_list,
        const cl_event*event_wait_list,
        cl_event*event)

        Parameters

        command_queue

        A valid command-queue.

        num_objects

        The number of memory objects to be released in mem_objects.

        mem_objects

        A pointer to a list of CL memory objects that correspond to GL objects.

        event_wait_list , num_events_in_wait_list

        These parameters specify events that need to complete before this command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points.

        event

        Returns an event object that identifies this particular read/write command and can be used to query or queue a wait for the command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.

        When the cl_khr_gl_event extension is enabled, If an OpenGL context is bound to the current thread, then any OpenGL commands which:

        • affect or access the contents of the memory objects listed in the mem_objects list, and
        • are issued on that context prior to the call to clEnqueueReleaseGLObjects

        will not execute until after execution of any OpenCL commands preceding the clEnqueueReleaseGLObjects which affect or access any of those memory objects. If a non-NULL event object is returned, it will report completion before execution of such OpenGL commands.

        Description

        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.

        Notes

        In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/GL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.

        Prior to calling clEnqueueAcquireGLObjects, the application must ensure that any pending GL operations which access the objects specified in mem_objects have completed. This may be accomplished portably by issuing and waiting for completion of a glFinish command on all GL contexts with pending references to these objects. Implementations may offer more efficient synchronization methods; for example on some platforms calling glFlush may be sufficient, or synchronization may be implicit within a thread, or there may be vendor-specific extensions that enable placing a fence in the GL command stream and waiting for completion of that fence in the CL command queue. Note that no synchronization methods other than glFinish are portable between OpenGL implementations at this time.

        Similarly, after calling clEnqueueReleaseGLObjects, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in mem_objects have completed prior to executing subsequent GL commands which reference these objects. This may be accomplished portably by calling clWaitForEvents with the event object returned by clEnqueueReleaseGLObjects, or by calling glFinish. As above, some implementations may offer more efficient methods.

        The application is responsible for maintaining the proper order of operations if the CL and GL contexts are in separate threads.

        If a GL context is bound to a thread other than the one in which clEnqueueReleaseGLObjects is called, changes to any of the objects in mem_objects may not be visible to that context without additional steps being taken by the application. For an OpenGL 3.1 (or later) context, the requirements are described in Appendix G ("Shared Objects and Multiple Contexts") of the OpenGL 3.1 Specification. For prior versions of OpenGL, the requirements are implementationdependent.

        Attempting to access the data store of an OpenGL object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared CL/GL object from OpenCL before it has been acquired by the OpenCL command queue, or after it has been released, will result in undefined behavior.

        Errors

        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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
        • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
      • clEnqueueReleaseGLObjectsNative

        private static int clEnqueueReleaseGLObjectsNative​(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)
      • clGetGLContextInfoAPPLE

        public static int clGetGLContextInfoAPPLE​(cl_context context,
                                                  long platform_gl_ctx,
                                                  int param_name,
                                                  long param_value_size,
                                                  Pointer param_value,
                                                  long[] param_value_size_ret)

        Apple extension for retrieving OpenGL context information for a CL context.

        cl_int clGetGLContextInfoAPPLE ( cl_contextcontext,
        size_tplatform_gl_ctx,
        cl_gl_platform_infoparam_name,
        size_tparam_value_size,
        void*param_value,
        size_t*param_value_size_ret,

        Parameters

        context

        A valid cl_context created with CL_CONTEXT_PROPERTY_USE_CGL_SHAREGROUP_APPLE.

        platform_gl_ctx

        The CGL context provided to clCreateContext.

        param_name

        An enumeration constant that specifies the information to query. The valid values for param_name are:

        cl_gl_platform_info Return Type Information returned in param_value
        CL_CGL_DEVICE_FOR_CURRENT_VIRTUAL_SCREEN_APPLE cl_device_id Returns a cl_device_id for the CL device associated with the virtual screen for the given CGL context.
        CL_CGL_DEVICES_FOR_SUPPORTED_VIRTUAL_SCREENS_APPLE cl_device_id[] Returns an array of cl_device_ids for the CL device(s) corresponding to the virtual screen(s) for the given CGL context.
        param_size

        Specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the table above.

        param_value

        A pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

        param_value_size_ret

        Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

        Errors

        Returns CL_SUCCESS if the function executed successfully, or one of the errors below:

        • CL_INVALID_GL_CONTEXT_APPLE if platform_gl_ctx is invalid.
      • clGetGLContextInfoAPPLENative

        private static int clGetGLContextInfoAPPLENative​(cl_context context,
                                                         long platform_gl_ctx,
                                                         int param_name,
                                                         long param_value_size,
                                                         Pointer param_value,
                                                         long[] param_value_size_ret)
      • initMemoryManagementThread

        private static void initMemoryManagementThread()
        Creates and starts the daemon thread which will fetch the references to ByteBuffers that have been marked for garbage collection from the alignedByteBufferReferenceQueue, and free the associated aligned native pointers.
      • allocateAligned

        public static java.nio.ByteBuffer allocateAligned​(int size,
                                                          int alignment)
        Deprecated.
        This method is not intended (and should not be required) for public use, and will be removed in future releases.
        Creates an returns a new direct ByteBuffer with the given size, whose memory has the given alignment, in bytes. The memory associated with the returned buffer will be freed automatically soon after the ByteBuffer has been marked for garbage collection.
        Parameters:
        size - The size of the buffer
        alignment - The alignment, in bytes
        Returns:
        A new direct ByteBuffer
      • allocateAlignedNative

        private static java.nio.ByteBuffer allocateAlignedNative​(int size,
                                                                 int alignment,
                                                                 Pointer pointer)
      • freeAlignedNative

        private static void freeAlignedNative​(Pointer pointer)
        This method will free the memory of an aligned ByteBuffer which was allocated with allocateAligned(int, int).
        Parameters:
        pointer - The pointer whose nativePointer value is the address of the native, aligned byte buffer that was set in the native implementation of allocateAligned(int, int)
      • validateHostPointerFlags

        private static void validateHostPointerFlags​(long flags,
                                                     Pointer pointer)