organicmaps/CMake-MetalShaderSupport
13
Fork 0
mirror of https://github.com/dpogue/CMake-MetalShaderSupport.git synced 2025-04-04 13:05:06 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

README updates

Browse source
This commit is contained in:
Darryl Pogue 2024-05-30 19:38:47 -07:00
parent 78dba464a8
commit f9c93befb2
No known key found for this signature in database
GPG key ID: CB824715C3E6FD41
1 changed files with 40 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
README.md
View file

@ -3,6 +3,7 @@
This project aims to allow compiling, linking, and embedding Apple Metal shader libraries in projects using CMake, without the need to write custom build steps or be restricted to only using the Xcode project generator.
Project Setup
-------------
@ -36,6 +37,7 @@ Project Setup
endif()
```
Shader Library Setup
--------------------
@ -45,33 +47,22 @@ There are a few different ways to compose shader library targets, including some
> **Shaders must be in their own CMake target!**
> You cannot mix them with C++ or Objective-C code sources in a library or executable target.
### Object Files (.air)
You can compile shaders to a loose collection of `.air` bitcode files by defining an object library, and then include those shader objects as part of another Metal shader library.
### Metal Libraries (.metallib)
Your final shader library will need to be a `.metallib` file that can be included in your application as a resource. You should define these as `MODULE` libraries rather than `SHARED` libraries because they do not expose symbols that can be linked with other targets.
```cmake
add_library(shader_base OBJECT
add_library(full_shader MODULE
shader1.metal
shader2.metal
)
```
You can then reference those objects to be linked as part of another target:
```cmake
add_library(full_shader MODULE
another_shader.metal
$<TARGET_OBJECTS:shader_base>
)
```
> [!CAUTION]
> TODO: Test and prove that this actually works for linking them up in later targets
### Static Archives (.metal-ar)
You can also compile shaders to a static archive as a `.metal-ar` file that can be linked together with other archives and shaders into a Metal library.
You can compile shaders to a static archive as a `.metal-ar` file that can be linked together with other archives and shaders into a Metal library.
```cmake
add_library(shader_base STATIC
@ -96,17 +87,30 @@ target_link_libraries(full_shader
> TODO: Test and prove that this actually works for linking them up in later targets
### Metal Libraries (.metallib)
### Object Files (.air)
Your final shader library will need to be a `.metallib` file that can be included in your application as a resource. You should define these as `MODULE` libraries rather than `SHARED` libraries because they do not expose symbols that can be linked with other targets.
You can also compile shaders to a loose collection of `.air` bitcode files by defining an object library, and then include those shader objects as part of another Metal shader library.
```cmake
add_library(full_shader MODULE
add_library(shader_base OBJECT
shader1.metal
shader2.metal
)
```
You can then reference those objects to be linked as part of another target:
```cmake
add_library(full_shader MODULE
another_shader.metal
$<TARGET_OBJECTS:shader_base>
)
```
> [!CAUTION]
> TODO: Test and prove that this actually works for linking them up in later targets
Embedding Shaders
-----------------
@ -144,3 +148,20 @@ As a final step to make your shader library available to your application, you w
> [!CAUTION]
> TODO: Test and prove that this actually works for linking them up in later targets
Remaining Work
--------------
* Handling the target and SDK parameters
* Handling extra flags
* Testing that this works with the Windows version of the Metal tools
Licence
-------
TBD, but probably matching CMake since so much of this is outright copied from their existing code.
The example project is based on sample code from Apple, under its own licence.