OpenCL Utility Library

The OpenCL Utility Library provides both C and C++ bindings with near feature parity. The utilities are broken into to libraries, OpenCLUtils and OpenCLUtilsCpp. To include them in your project, include <CL/Utils/Utils.h>/<CL/Utils/Utils.hpp> and link to their libraries respectively.

Platform utilities

bool cl::util::supports_extension(const cl::Platform& platform, const cl::string& extension);

Tells whether a platform supports a given extension.

platform is the platform to query.
extension is the extension string being searched for.

bool cl::util::platform_version_contains(const cl::Platform& platform, const cl::string& version_fragment);

Tells whether the platform version string contains a specific fragment.

platform is the platform to query.
version_fragment is the version string fragment to search for.

Device utilities

bool cl::util::opencl_c_version_contains(const cl::Device& device, const cl::string& version_fragment);

Tells whether the device OpenCL C version string contains a specific fragment.

device is the device to query.
version_fragment is the version string fragment to search for.

bool cl::util::supports_extension(const cl::Device& device, const cl::string& extension);

Tells whether a device supports a given extension.

device is the device to query.
extension is the extension string being searched for.

bool cl::util::supports_feature(const cl::Device& device, const cl::string& feature_name);

Tells whether a device supports any version of a feature.

device is the device to query.
feature_name is the feature name string being searched for.

(Note: this function is only available when both the Utility library and the using code defines minimally CL_VERSION_3_0.)

Context utilities

cl_context cl_util_get_context(int plat_id, int dev_id, cl_device_type type, cl_int* error);

cl::Context cl::util::get_context(int plat_id, int dev_id, cl_device_type type, cl_int* error = nullptr);

These functions create a context on the platform with id plat_id with a single device of type type and id dev_id.

If error is non-null or if CL_HPP_ENABLE_EXCEPTIONS is used, ordinary OpenCL error codes may be returned and the following library-specific error codes:

CL_UTIL_INDEX_OUT_OF_RANGE if the requested platform or device id is outside the range of available platforms or devices of the selected type on the platform.

Event utilities

template <cl_int From, cl_int To, typename Dur = std::chrono::nanoseconds>
auto cl::util::get_duration(cl::Event& ev);

This function template can be used to query an event for the duration of time measured in user-provided units between two state transitions. By default the return type is std::chrono::nanoseconds as that is the unit of measure of the OpenCL API.

Error handling utilities

class Error : public std::exception
{
private:
    int err_;
    const char * errStr_;
public:
    /*! \brief Create a new SDK error exception for a given error code
     *  and corresponding message.
     *
     *  \param err error code value.
     *
     *  \param errStr a descriptive string that must remain in scope until
     *                handling of the exception has concluded.  If set, it
     *                will be returned by what().
     */
    Error(cl_int err, const char * errStr = NULL) : err_(err), errStr_(errStr)
    {}

    ~Error() throw() {}

    /*! \brief Get error string associated with exception
     *
     * \return A memory pointer to the error message string.
     */
    virtual const char * what() const throw ()
    {
        if (errStr_ == NULL) {
            return "empty";
        }
        else {
            return errStr_;
        }
    }

    /*! \brief Get error code associated with exception
     *
     *  \return The error code.
     */
    cl_int err(void) const { return err_; }
};

This type is used as the exception type thrown by utilities when an error occurs and the compiling code defines CL_HPP_ENABLE_EXCEPTIONS

4.2 KiB Raw Blame History