MoltenVK

This document is written in Markdown format. For best results, use a Markdown reader.

About This Document
Introduction
Installing MoltenVK
Third-Party Libraries
- Updating the Third-Party Library Versions
Building MoltenVK
Running the MoltenVK Demo Applications
Using MoltenVK in Your Application
MoltenVK and Vulkan Compliance
Contributing to MoltenVK Development
Third-Party Credits

About This Document

This document describes how to use the MoltenVK open-source repository to build a MoltenVK runtime distribution package.

To learn how to integrate the MoltenVK runtime into a game or application, see the Docs/MoltenVK_Runtime_UserGuide.md document in the Docs directory.

Introduction

MoltenVK contains two products:

MoltenVK is an implementation of the Vulkan graphics and compute API, that runs on Apple's Metal graphics and compute framework on both iOS and macOS.
MoltenVKShaderConverter converts SPIR-V shader code to Metal Shading Language (MSL) shader source code, and converts GLSL shader source code to SPIR-V shader code and/or Metal Shading Language (MSL) shader source code, for use with MoltenVK. The converter can run at runtime as a component of the MoltenVK runtime, or it can be packaged into a stand-alone command-line macOS tool. The Xcode project contains several targets, reflecting this multi-use capability.

Installing MoltenVK

MoltenVK relies on several third-party open-source libraries, which are described in the next section. The easiest way to install MoltenVK is to recursively clone this MoltenVK repository, and then run the External/makeAll script to create necessary components within the third-party libraries.

Ensure you have cmake and python3 installed:

 brew install cmake
 brew install python3

Optional: If you want to generate a Vulkan specification document for inclusion in the final MoltenVK distribution package, ensure you have asciidoctor installed (you can skip this otherwise):
```
 brew install asciidoctor
```

Recursively clone the MoltenVK repository:

 git clone --recursive https://github.com/KhronosGroup/MoltenVK.git

Run the third-party build script:
```
 cd MoltenVK/External
 ./makeAll
```

See the next section for more information about the third-party libraries, and how to work with them within the MoltenVK development environment.

Third-Party Libraries

MoltenVK makes use of several third-party open-source libraries. Development of some of these components is managed separately, and are retrieved into MoltenVK as submodule repositories.

If you used the --recursive option when cloning this repository, as described above, all third party libraries will have been retrieved.

If you did not use the --recursive option when cloning this repository, you can retrieve and install these libraries into your MoltenVK repository environment as follows from within the MoltenVK repository:

git submodule update --init --recursive
cd External
./makeAll

Updating the Third-Party Library Versions

If you are developing enhancements to MoltenVK, you can update the versions of the Third-Party libraries used by MoltenVK to the latest versions available by re-cloning and re-building the submodules using the getLatestAll script:

cd External
./getLatestAll

The updated versions will then be "locked in" the next time the MoltenVK repository is committed to git.

This procdure updates all of the Third-Party library submodules. To update only a single submodule, or for more information about the various Third-Party libraries and submodules used by MoltenVK, please refer to the Docs/ThirdPartyConfig.md document.

Building MoltenVK

Note: Before attempting to build MoltenVK, be sure you have followed the instructions in the Third-Party Components section above to retrieve and install the required third-party components.

At development time, MoltenVK references advanced OS frameworks during building.

Xcode 9 or above is required to build and link MoltenVK projects.

Once built, MoltenVK can be run on iOS or macOS devices that support Metal.

MoltenVK requires at least macOS 10.11 or iOS 9.
Information on macOS devices that are compatible with Metal can be found in this article.
Information on compatible iOS devices that are compatible with Metal can be found in this article.

The MoltenVKPackaging.xcodeproj Xcode project contains targets and schemes to build and package the entire MoltenVK runtime distribution package, or to build individual MoltenVK or MoltenVKShaderConverter components.

To build a MoltenVK runtime distribution package, suitable for testing and integrating into an app, open MoltenVKPackaging.xcodeproj in Xcode, and use one of the following Xcode Schemes:

MoltenVK (Release) - build the entire MoltenVK runtime distribution package using the Release configuration.
MoltenVK (Debug) - build the entire MoltenVK runtime distribution package using the Debug configuration.

Each of theseMoltenVKPackaging.xcodeproj Xcode project Schemes puts the resulting packages in the Package directory, creating it if necessary. This directory contains separate Release and Debug directories, holding the most recent Release and Debug builds, respectively.

A separate Latest directory links to the most recent build, regardless of whether it was a Release or Debug build. Effectively, the Package/Latest directory points to whichever of the Package/Release or Package/Debug directories was most recently updated.

With this packaging structure, you can follow the instructions below to link your application to the MoltenVK frameworks in the Package/Latest directory, to provide the flexibility to test your app with either a Debug build, or a higher-performance Release build.

Once you have built the MoltenVK runtime distribution package, the MoltenVK demo apps can be accessed from the Demos/Demos.xcworkspace Xcode workspace. This is the same workspace that is included in the MoltenVK runtime distribution package, and you can use it to build and run the MoltenVK demo apps, or to add new demos to this MoltenVK repository.

Running the MoltenVK Demo Applications

Once you have compiled and built the MoltenVK runtime distribution package from this MoltenVK repository, as described in the Building MoltenVK section, you can explore how MoltenVK provides Vulkan support on iOS and macOS by investigating and running the demo applications that are included in MoltenVK.

The MoltenVK demo apps are located in the Demos folder. Each demo app is available as an Xcode project. To review and run the included demo apps, open the Demos/Demos.xcworkspace workspace in Xcode.

Please read the Demos/README.md document for a description of each demo app, and instructions on running the demo apps. Several of the demo apps allow you to explore a variety of Vulkan features by modifying Xcode build settings. Additional demos can be downloaded and built from external repositories, as described in the Demos/README.md document

Using MoltenVK in Your Application

Once you have compiled and built the MoltenVK runtime distribution package from this MoltenVK repository, as described in the Building MoltenVK section, follow the instructions in the Installation section of the Docs/MoltenVK_Runtime_UserGuide.md document in the Docs directory, to link the MoltenVK frameworks and libraries to your application.

The runtime distribution package in the Package/Latest directory is a stand-alone package, and you can copy the contents of that directory out of this MoltenVK repository into your own application building environment.

MoltenVK and Vulkan Compliance

MoltenVK is designed to be a Vulkan driver that runs on macOS and iOS platforms by mapping Vulkan capability to native Metal capability.

The fundamental design and development goal of MoltenVK is to provide this capability in a way that is both maximally compliant with the Vulkan specification, and maximally performant.

Such compliance and performance is inherently affected by the capability available through Metal, as the native driver on macOS and iOS platforms. Vulkan compliance may fall into one of the following categories:

Direct mapping between Vulkan capabilities and Metal capabilities. Within MoltenVK, almost all capability is the result of this type of direct mapping.
Synthesized compliance through alternate implementation. A very small amount of capability is provided using this mechanism, such as via an extra render or compute shader stage.
Non-compliance. This appears where the capabilities of Vulkan and Metal are sufficiently different, that there is no practical, or reasonably performant, mechanism to implement a Vulkan capability in Metal. Because of design differences between Vulkan and Metal, a very small amount of capability falls into this category, and at present MoltenVK is not fully compliant with the Vulkan specification. A list of known limitations is documented in the Docs/MoltenVK_Runtime_UserGuide.md document in the Docs directory.

The MoltenVK development team welcomes you to post Issues of non-compliance, and engage in discussions about how compliance can be improved, and non-compliant features can be implemented or worked around.

MoltenVK is a key component of the Khronos Vulkan Portability Initiative, whose intention is to provide specifications, resources, and tools to allow developers to understand and design their Vulkan apps for maximum cross-platform compatibility and portability, including on platforms, such as macOS and iOS, where a native Vulkan driver is not avaialble.

Contributing to MoltenVK Development

As a public open-source project, MoltenVK benefits from code contributions from a wide range of developers, and we encourage you to get involved and contribute code to this MoltenVK repository.

To contribute your code, submit a Pull Request to this repository. The first time you do this, you will be asked to agree to the MoltenVK Contributor License Agreement.

Licensing

MoltenVK is licensed under the Apache 2.0 license. All new source code files should include a copyright header at the top, containing your authorship copyright and the Apache 2.0 licensing stub. You may copy the text from an existing source code file as a template.

The Apache 2.0 license guarantees that code in the MoltenVK repository is free of Intellectual Property encumbrances. In submitting code to this repository, you are agreeing that the code is free of any Intellectual Property claims.

Code Formatting

When contirbuting code, please honour the code formatting style found in existing MoltenVK source code. In future, this will formally be enforced using clang-format.

Third-Party Credits

MoltenVK uses technology from the following open-source frameworks:

ndsol/MoltenVK