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