README.OpenSource
README.md
1# OpenCL<sup>TM</sup> API Headers
2
3This repository contains C language headers for the OpenCL API.
4
5The authoritative public repository for these headers is located at:
6
7https://github.com/KhronosGroup/OpenCL-Headers
8
9Issues, proposed fixes for issues, and other suggested changes should be
10created using Github.
11
12## CMake Package
13While the headers may just be copied as-is, this repository also contains a
14CMake script with an install rule to allow for packaging the headers.
15
16```bash
17cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/chosen/install/prefix
18cmake --build build --target install
19```
20
21To consume the package:
22
23```bash
24cmake path/to/opencl/app -DOpenCLHeaders_ROOT=/chosen/install/prefix
25```
26
27```cmake
28cmake_minimum_required(VERSION 3.0)
29cmake_policy(VERSION 3.0...3.18.4)
30project(proj)
31add_executable(app main.cpp)
32find_package(OpenCLHeaders REQUIRED)
33target_link_libraries(app PRIVATE OpenCL::Headers)
34```
35
36## Branch Structure
37
38The OpenCL API headers in this repository are Unified headers and are designed
39to work with all released OpenCL versions. This differs from previous OpenCL
40API headers, where version-specific API headers either existed in separate
41branches, or in separate folders in a branch.
42
43## Compiling for a Specific OpenCL Version
44
45By default, the OpenCL API headers in this repository are for the latest
46OpenCL version (currently OpenCL 2.2). To use these API headers to target
47a different OpenCL version, an application may `#define` the preprocessor
48value `CL_TARGET_OPENCL_VERSION` before including the OpenCL API headers.
49The `CL_TARGET_OPENCL_VERSION` is a three digit decimal value representing
50the OpenCL API version.
51
52For example, to enforce usage of no more than the OpenCL 1.2 APIs, you may
53include the OpenCL API headers as follows:
54
55```c
56#define CL_TARGET_OPENCL_VERSION 120
57#include <CL/opencl.h>
58```
59
60## Directory Structure
61
62```
63README.md This file
64LICENSE Source license for the OpenCL API headers
65CL/ Unified OpenCL API headers tree
66```
67
68## License
69
70See [LICENSE](LICENSE).
71
72---
73
74OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
75
README_zh.md
1# OpenCL<sup>TM</sup> API Headers
2
3仓库包含C语言的OpenCL API。OpenCL扩展了GPU用于图形渲染之外的能力，将通用计算并行化。OpenCL可用于图像处理、AI、高性能计算等场景的加速。推荐在计算密集型的任务以及可以并行计算的场景使用OpenCL。
4
5例如在图像处理场景，CPU进行编解码、滤镜等特效处理较慢，使用OpenCL有十倍的加速效果。
6
7例如在AI推理场景，使用OpenCL可以将推理性能提高一倍。
8
9OpenHarmony引入后，新增了一层封装层，动态链接查找OpenCL库，以此进行解耦。目前仅支持native层调用OpenCL。
10
11## 目录结构
12
13```
14README.md 英文说明
15README_zh.md 中文说明
16LICENSE 证书文件
17CL/ 原CL头文件
18include/ 封装层CL头文件
19src/ 封装层CL实现
20```
21
22## OpenHarmony如何集成OpenCL
23### 1.头文件引入
24```c
25#define USE_OPENCL_WRAPPER
26#include "opencl_wrapper.h"
27```
28### 2.BUILD.gn添加引用
29```c
30deps += ["//third_party/openCL:libcl"]
31```
32### 3.调用OpenCL函数过程举例
33```c
34// 准备OpenCL的kernel程序
35const char* program_source =
36 "__kernel void test_main(read_only image2d_t inputImage) {\n"
37 " ...\n"
38 "}";
39```
40
41```c
42// 通过wrapper层的函数判断是否cl初始化成功
43// 如果返回false，说明没有实际的驱动
44bool cl_ok = OHOS::InitOpenCL();
45
46// 获取设备信息
47cl_int err;
48cl_platform_id platform_id;
49cl_device_id device_id;
50clGetPlatformIDs(1, &platform_id, NULL);
51clGetDeviceIDs(platform_id, CL_DEVICE_TYPE_GPU, 1, &device_id, NULL);
52// 创建OpenCL上下文
53context_ = clCreateContext(0, 1, &device_id, NULL, NULL, &err);
54queue_ = clCreateCommandQueueWithProperties(context_, device_id, 0, &err);
55// 使用上述源码创建OpenCL程序
56cl_program p = clCreateProgramWithSource(context, 1, &program_source, nullptr, nullptr);
57// 创建kernel程序，对应上述源码中的函数名
58kernel_ = clCreateKernel(program, "test_main", &err);
59// 创建OpenCL可以识别的图片
60cl_image_format image_format;
61image_format.image_channel_order = CL_RGBA;
62image_format.image_channel_data_type = CL_UNORM_INT8;
63cl_image_desc desc = {CL_MEM_OBJECT_IMAGE2D, width, height};
64cl_mem input_image = clCreateImage(context_, CL_MEM_READ_ONLY | CL_MEM_COPY_HOST_PTR, image_format, &desc, const_cast<void*(pixmap.addr()), &err);
65// 将该图片传入kernel程序
66err |= clSetKernelArg(kernel_, 0, sizeof(cl_mem), &input_image);
67// 在GPU上执行OpenCL程序
68err = clEnqueueNDRangeKernel(queue_, kernel_, 2, NULL, global,local, 0, NULL, NULL);
69// 等待执行结束
70clFinish(queue_);
71// 读取执行结果，从GPU传输回CPU
72err = clEnqueueReadBuffer(queue_, cl_errs, CL_TRUE, 0, pixmap.size(), errs, 0, NULL, NULL);
73// 使用完毕需要释放cl内存
74clReleaseMemObject(input_image);
75// 程序不再需要执行的时候需要释放GPU资源(OpenCL上下文)
76clReleaseKernel(kernel_);
77clReleaseCommandQueue(queue_);
78clReleaseContext(context_);
79```
80
81## OpenCL使用文档
82
83API官方文档 https://registry.khronos.org/OpenCL/
84
85API详细定义 https://registry.khronos.org/OpenCL/sdk/3.0/docs/man/html/
86
87API一张图的使用说明 https://www.khronos.org/files/opencl30-reference-guide.pdf
88
89## License
90
91见 [LICENSE](LICENSE).
92
93---
94
95OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
96