Skip to content

Commit 040f601

Browse files
bashbaugbashbaug
committed
improve README
1 parent ae87963 commit 040f601

File tree

2 files changed

+66
-6
lines changed

2 files changed

+66
-6
lines changed

‎CMakeLists.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright (c) 2021 Ben Ashbaugh
1+
# Copyright (c) 2022 Ben Ashbaugh
22
#
33
# Permission is hereby granted, free of charge, to any person obtaining a copy
44
# of this software and associated documentation files (the "Software"), to deal
@@ -26,7 +26,7 @@ set_property(GLOBAL PROPERTY USE_FOLDERS ON)
2626
set(CMAKE_CXX_STANDARD 11)
2727

2828
project(OpenCLExtensionLoader
29-
VERSION 0.9
29+
VERSION 1.0.220515
3030
LANGUAGES C CXX)
3131

3232
option (BUILD_SHARED_LIBS "Build shared libs" ON)
@@ -43,7 +43,7 @@ option (OPENCL_EXTENSION_LOADER_INCLUDE_VA_API "Include VA_API Extension APIs"
4343
if (CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
4444
include(CTest)
4545
find_package(Python3 COMPONENTS Interpreter)
46-
set(OPENCL_EXTENSION_LOADER_XML_PATH CACHE FILEPATH "Path to cl.xml for OpenCL Extension Loader genereration")
46+
set(OPENCL_EXTENSION_LOADER_XML_PATH CACHE FILEPATH "Path to cl.xml for OpenCL Extension Loader generation")
4747
set(OPENCL_EXTENSION_LOADER_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/generated)
4848
add_custom_target(extension_loader_generate
4949
COMMAND ${CMAKE_COMMAND} -E make_directory ${OPENCL_EXTENSION_LOADER_OUTPUT_DIRECTORY}
@@ -91,7 +91,7 @@ else()
9191
endif()
9292
add_library(OpenCL::OpenCLExt ALIAS OpenCLExt)
9393
set_target_properties(OpenCLExt PROPERTIES FOLDER "OpenCLExtensionLoader")
94-
set_target_properties(OpenCLExt PROPERTIES VERSION "0.9" SOVERSION "0")
94+
set_target_properties(OpenCLExt PROPERTIES VERSION ${PROJECT_VERSION} SOVERSION ${PROJECT_VERSION_MAJOR})
9595
target_include_directories(OpenCLExt PRIVATE ${OPENCL_EXTENSION_LOADER_INCLUDE_DIRS})
9696
target_compile_definitions(OpenCLExt PRIVATE CL_TARGET_OPENCL_VERSION=300)
9797
if (OPENCL_EXTENSION_LOADER_SINGLE_PLATFORM_ONLY)

‎README.md

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,68 @@ GitHub Actions: [![GitHub Actions Build Status](https://github.com/bashbaug/open
33

44
This repository contains an extension loader library for OpenCL extension APIs.
55

6-
This library is a work in progress.
7-
Check back soon for updates!
6+
The extension loader library provides function definitions for all known OpenCL extension APIs and code to query the extension APIs, allowing them to be called just like core OpenCL APIs.
7+
8+
## How to Build the OpenCL Extension Loader
9+
10+
The OpenCL Extension Loader uses CMake to generate build files.
11+
It is regularly used and tested on Windows and Linux.
12+
13+
The OpenCL Extension Loader requires the following external dependencies: OpenCL headers and an OpenCL library to link with.
14+
These dependencies can be provided via several different methods:
15+
16+
1. Via CMake's `find_package(OpenCL)`.
17+
For many operating systems, if OpenCL packages or vendor-specific SDKs are installed in standard locations, they will be found automatically.
18+
Updated CMake packages may also be provided by the Khronos [OpenCL-SDK](https://github.com/KhronosGroup/OpenCL-SDK).
19+
20+
1. Specified manually via the CMake variables `OpenCL_INCLUDE_DIRS` and `OPENCL_LIBRARIES`.
21+
22+
The OpenCL Extension Loader may also be used as a CMake sub-project, in which case it will inherit the CMake variables `OpenCL_INCLUDE_DIRS` and `OPENCL_LIBRARIES` if set, and will `find_package(OpenCL)` otherwise.
23+
24+
## How to Use the OpenCL Extension Loader
25+
26+
After building the OpenCL Extension Loader, simply link with it as you would link to the standard OpenCL libraries.
27+
This will satisfy build dependencies for OpenCL extension APIs, allowing them to be called just like core OpenCL APIs.
28+
29+
For example usage, please see [SimpleOpenCLSamples](https://github.com/bashbaug/SimpleOpenCLSamples).
30+
31+
## How to Generate Support for New Extensions
32+
33+
The OpenCL Extension Loader is generated from API definitions in the [OpenCL XML File](https://github.com/KhronosGroup/OpenCL-Docs/blob/main/xml/cl.xml) and several [Python Mako Templates](https://www.makotemplates.org/).
34+
To add support for many new extensions, simply run the `gen_openclext.py` script in the `scripts` directory.
35+
To simplify generation, there is also a CMake target `extension_loader_generate`, which will invoke the script.
36+
37+
After generation, examine the generated files to ensure everything looks correct, then copy the generated files to the OpenCL Extension Loader source directories.
38+
This can be done manually, or via the CMake target `extension_loader_copy`.
39+
40+
In some cases, the scripts themselves may need to be modified.
41+
This typically happens when an extension adds a new type.
42+
When an extension adds a new type:
43+
44+
* The OpenCL Extension Loader template file `openclext.cpp.mako` may need to add a function to get the OpenCL Extension Loader dispatch table from an object of the new type.
45+
* The OpenCL Extension Loader template file may also need to be modified if new extension functions are atypical and the OpenCL Extension Loader dispatch table should not be queried from the first function parameter.
46+
* The OpenCL Extension Loader test generation template file may need to be updated to add default values for the new type.
47+
48+
The OpenCL Extension Loader is most commonly used with the upstream OpenCL XML File, but it can also be used with a fork of the upstream OpenCL XML File, say to generate functions for a private or as-yet unreleased extension.
49+
50+
## CMake Variables
51+
52+
The following CMake variables are supported. To specify one of these variables
53+
via the command line generator, use the CMake syntax `-D<option name>=<value>`.
54+
See your CMake documentation for more details.
55+
56+
| Variable | Type | Description |
57+
|:---------|:-----|:------------|
58+
|OPENCL\_EXTENSION\_LOADER\_FORCE\_STATIC\_LIB | BOOL | Unconditionally Build a Static OpenCL Extension Loader. A static library can simplify building and distribution. Default: `TRUE`
59+
|OPENCL\_EXTENSION\_LOADER\_SINGLE\_PLATFORM\_ONLY | BOOL | Only Support Extensions from a Single OpenCL Platform. This may improve performance by simplifying dispatch table lookups. Default: `FALSE`
60+
|OPENCL\_EXTENSION\_LOADER\_INSTALL | BOOL | Generate a CMake Installation Target for the OpenCL Extension Loader. Default: `FALSE`
61+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_GL | BOOL | Include OpenGL Interop Extension APIs. Requires OpenGL Headers. Default: `TRUE`
62+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_EGL | BOOL | Include EGL Interop Extension APIs. Requires EGL Headers. Default: `TRUE`
63+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_DX9 | BOOL | Include DirectX 9 Interop Extension APIs. Requires DirectX 9 Headers. Default: `FALSE`
64+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_D3D10 | BOOL | Include Direct3D 10 Interop Extension APIs. Requires DirectX 10 Headers. Default: `FALSE`
65+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_D3D11 | BOOL | Include Direct3D 11 Interop Extension APIs. Required DirectX 11 Headers. Default: `FALSE`
66+
|OPENCL\_EXTENSION\_LOADER\_INCLUDE\_VA\_API | BOOL | Include VA_API Interop Extension APIs. Requires support for VA_API Headers. Default: `FALSE`
67+
|OPENCL\_EXTENSION\_LOADER\_XML\_PATH | PATH | Path to cl.xml for OpenCL Extension Loader generation. Default: None.
868

969
---
1070

0 commit comments

Comments
 (0)