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## Controlling Function Prototypes
74
75By default, the OpenCL API headers in this repository declare function
76prototypes for every known core OpenCL API and OpenCL extension API. If this is
77not desired, the declared function prototypes can be controlled by the following
78preprocessor defines:
79
80* `CL_NO_PROTOTYPES`: No function prototypes will be declared. This control
81 applies to core OpenCL APIs and OpenCL extension APIs.
82* `CL_NO_CORE_PROTOTYPES`: No function prototypes will be declared for core
83 OpenCL APIs.
84* `CL_NO_EXTENSION_PROTOTYPES`: No function prototypes will be declared for
85 OpenCL extension APIs. This control applies to all OpenCL extension APIs.
86* `CL_NO_ICD_DISPATCH_EXTENSION_PROTOTYPES`: No function prototypes will be
87 declared for OpenCL extension APIs that are in the ICD dispatch table for
88 historical reasons.
89* `CL_NO_NON_ICD_DISPATCH_EXTENSION_PROTOTYPES`: No function prototypes will be
90 declared for OpenCL extension APIs that are not in the ICD dispatch table.
91
92For example, to declare function prototypes for core OpenCL 3.0 APIs only, you
93may include the OpenCL API headers as follows:
94
95```c
96#define CL_TARGET_OPENCL_VERSION 300
97#define CL_NO_EXTENSION_PROTOTYPES
98#include <CL/opencl.h>
99```
100
101## Compatibility Notes
102
103OpenCL values backward compatibility and in most cases an application using an
104older version of the OpenCL API headers can seamlessly update to a newer version
105of the OpenCL API headers. In rare cases, though, the OpenCL API headers may
106break backward compatibility:
107
108* Very rarely, there may be bugs or other issues in the OpenCL API headers that
109 cannot be fixed without breaking compatibility.
110* The OpenCL API headers for provisional features or provisional extensions may
111 be changed in a way that breaks compatibility.
112
113Applications or libraries that require stable OpenCL API headers are encouraged
114to use tagged or released OpenCL API headers. We will do our best to document
115any breaking changes in the description of each release. The OpenCL API headers
116are tagged at least as often as each OpenCL specification release.
117
118## Directory Structure
119
120```
121README.md This file
122LICENSE Source license for the OpenCL API headers
123CL/ Unified OpenCL API headers tree
124```
125
126## License
127
128See [LICENSE](LICENSE).
129
130---
131
132OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.
133
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