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## Build instructions
13
14> While the OpenCL Headers can be built and installed in isolation, it is part of the [OpenCL SDK](https://github.com/KhronosGroup/OpenCL-SDK). If looking for streamlined build experience and a complete development package, refer to the SDK build instructions instead of the following guide.
15
16### Dependencies
17
18- The OpenCL Headers CMake package support uses CMake for its build system.
19If CMake is not provided by your build system or OS package manager, please consult the [CMake website](https://cmake.org).
20
21### Example Build
22While the headers may just be copied as-is, this repository also contains a
23CMake script with an install rule to allow for packaging the headers.
24
25```bash
26cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/chosen/install/prefix
27cmake --build build --target install
28```
29
30### Example Use
31
32Example CMake invocation
33
34```bash
35cmake -D CMAKE_PREFIX_PATH=/chosen/install/prefix /path/to/opencl/app
36```
37
38and sample `CMakeLists.txt`
39
40```cmake
41cmake_minimum_required(VERSION 3.0)
42cmake_policy(VERSION 3.0...3.18.4)
43project(proj)
44add_executable(app main.cpp)
45find_package(OpenCLHeaders REQUIRED)
46target_link_libraries(app PRIVATE OpenCL::Headers)
47```
48
49## Branch Structure
50
51The OpenCL API headers in this repository are Unified headers and are designed
52to work with all released OpenCL versions. This differs from previous OpenCL
53API headers, where version-specific API headers either existed in separate
54branches, or in separate folders in a branch.
55
56## Compiling for a Specific OpenCL Version
57
58By default, the OpenCL API headers in this repository are for the latest
59OpenCL version (currently OpenCL 3.0). To use these API headers to target
60a different OpenCL version, an application may `#define` the preprocessor
61value `CL_TARGET_OPENCL_VERSION` before including the OpenCL API headers.
62The `CL_TARGET_OPENCL_VERSION` is a three digit decimal value representing
63the OpenCL API version.
64
65For example, to enforce usage of no more than the OpenCL 1.2 APIs, you may
66include the OpenCL API headers as follows:
67
68```c
69#define CL_TARGET_OPENCL_VERSION 120
70#include <CL/opencl.h>
71```
72
73## Directory Structure
74
75```
76README.md This file
77LICENSE Source license for the OpenCL API headers
78CL/ Unified OpenCL API headers tree
79```
80
81## License
82
83See [LICENSE](LICENSE).
84
85---
86
87OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
88
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