122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
## List of utilities
|
|
|
|
- [Platform](#platform-utilities)
|
|
- [Device](#device-utilities)
|
|
- [Context](#context-utilities)
|
|
- [Event](#event-utilities)
|
|
- [Error](#error-handling-utilities)
|
|
|
|
### Platform utilities
|
|
|
|
```c++
|
|
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.
|
|
|
|
```c++
|
|
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
|
|
|
|
```c++
|
|
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.
|
|
|
|
```c++
|
|
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.
|
|
|
|
```c++
|
|
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
|
|
|
|
```c
|
|
cl_context cl_util_get_context(int plat_id, int dev_id, cl_device_type type, cl_int* error);
|
|
```
|
|
```c++
|
|
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
|
|
|
|
```c++
|
|
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
|
|
|
|
```c++
|
|
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`
|