MoltenVK 0.13.0 User Guide

Copyright (c) 2014-2016 The Brenwill Workshop Ltd. All rights reserved.

Table of Contents

Molten License Agreement


About MoltenVK

MoltenVK is an implementation of the Vulkan graphics API, that runs on Apple's Metal graphics framework on both iOS and macOS.

MoltenVK allows you to use the Vulkan graphics API to develop modern, cross-platform, high-performance graphical games and applications, and to run them across many platforms, including both iOS and macOS.

Metal uses a different shading language, the Metal Shading Language (MSL), than Vulkan, which uses SPIR-V. However, fear not, as MoltenVK will automatically convert your SPIR-V shaders to their MSL equivalents. This can be performed transparently at run time, using the Runtime Shader Conversion feature of MoltenVK, or at development time using the MoltenShaderConverter tool provided with this Molten distribution package.

Running the MoltenVK Demo Applications

You can explore how MoltenVK provides Vulkan support on iOS and macOS by investigating and running the demo applications that come with this Molten distribution package.

The MoltenVK demo apps are located in the MoltenVK/Demos folder within the Molten distribution package. Each demo app is available as an Xcode project.

To review and run all of the available demo apps, open the Demos/Demos.xcworkspace workspace in Xcode.

Please read the README_MoltenVK_Demos document for a description of each demo app, and instructions on downloading and running the demo apps. Many of the MoltenVK demos make use of third-party demo examples, which must be downloaded from an external repository. Many of the demo apps allow you to explore a variety of Vulkan features by modifying Xcode build settings. All of this is explained in the README_MoltenVK_Demos document.

Installing MoltenVK in Your Vulkan Application

Installation of MoltenVK is straightforward and easy! To add MoltenVK to your existing Vulkan application, follow the steps in this section. If you're new to MoltenVK, it is recommended that you start with a smaller project to help you understand the transition, and to reduce the possibility of needing to make modifications to your shaders to ensure their compatibility with the Metal environment.

  1. Open your application in Xcode and select your application's target in the Project Navigator panel.

  2. Open the Build Settings tab, and in the Framework Search Paths (aka FRAMEWORK_SEARCH_PATHS) setting:

  3. In your application code, you can access the Vulkan header files through the MoltenVK framework (added in the previous step) as follows:

    #include <MoltenVK/vulkan/vulkan.h>

    Alternately, you can expose the Vulkan headers directly, and access them as follows:

    #include <vulkan/vulkan.h>

    For this second option, to expose the Vulkan header files directly, in the Header Search Paths (aka HEADER_SEARCH_PATHS) setting, add an entry that points to the MoltenVK/include folder, found in the Molten distribution package.

  4. Select the Build Phases tab, and open the Link Binary With Libraries list.

  5. In the Link Binary With Libraries list, click the + button, and (selecting from the list of system frameworks) add the libc++.tbd framework. If you do not have the Link Frameworks Automatically (aka CLANG_MODULES_AUTOLINK) setting enabled, repeat this step for the Metal.framework as well.

  6. When a Metal app is running from Xcode, the default Scheme settings reduce performance. To improve performance and gain the benefits of Metal, perform the following in Xcode:

    1. Open the Scheme Editor for building your main application. You can do this by selecting Edit Scheme... from the Scheme drop-down menu, or select Product -> Scheme -> Edit Scheme... from the main menu.
    2. On the Info tab, set the Build Configuration to Release, and disable the Debug executable check-box.
    3. On the Options tab, disable both the Metal API Validation and GPU Frame Capture options. For optimal performance, you may also consider disabling the other simulation and debugging options on this tab. For further information, see the Xcode Scheme Settings and Performance section of Apple's Metal Programming Guide documentation.
  7. Build and run your application.

Activating Your MoltenVK License

MoltenVK is provided under a commercial paid license. You must purchase licenses covering the MoltenVK features you are using before releasing MoltenVK as part of a production game or application.

During evaluation, you can run MoltenVK without purchasing a license. The same MoltenVK distribution package can be used for both evaluation and production games and applications, and the features and performance are identical in both modes. During evaluation, you will see the MoltenVK logo displayed as a watermark overlay on your graphics scene. Once valid licenses have been purchased and activated to cover the MoltenVK features you are using, this watermark will disappear.

Licenses may be purchased for one or more MoltenVK feature sets. Depending on whether you purchased a single license that covers all the features you are using, or purchased individual licenses for each features set, you may need to activate one or more licenses within MoltenVK.

Each license is composed of two parts, a license ID and a license key, both of which are provided to you when you purchase the license. There are two ways to activate a license within MoltenVK:

  1. The preferred method is to enter your license ID and key as compiler build settings in your development environment, and call the vkActivateMoltenVKLicensesMVK() function to activate them. If you have multiple licenses, covering multiple MoltenVK feature sets, you can configure up to four licenses using the following pairs of build settings:


    Each element of each pair is a single string defined as a build setting, and should not include quote marks. For example, you might configure the following build settings:

    and if you purchase an additional feature set on a separate license, you can add a second pair of build settings:

    In addition to the license ID and key, for any license activation to take place, you must also set the following build setting to indicate that you accept the terms and conditions of the Molten License Agreement:


    You can call the vkActivateMoltenVKLicensesMVK() function at any time, but typically you will call it during application startup.

  2. If you are unable to use build settings to enter license information, you can call the vkActivateMoltenVKLicenseMVK(licenseID, licenseKey, acceptLicenseTermsAndConditions) function from within your application, passing a license ID and key directly as a pair of null-terminated strings, as well as a boolean affirmation that you accept the terms and conditions of the Molten License Agreement.

    You can call this function at any time, but typically you will call this function during application startup. You can call this function multiple times to accommodate licenses purchased for multiple individual feature sets. Until a valid license is applied covering each feature set used by your application, MoltenVK will operate in evaluation mode.

    Using the vkActivateMoltenVKLicenseMVK(licenseID, licenseKey, acceptLicenseTermsAndConditions) function is not the preferred method for activating licenses because, in a team environment, it is more difficult to enter valid licenses for each developer from your application code. Instead, consider using the vkActivateMoltenVKLicensesMVK() function (discussed above), which allows you to specify the license information through compiler build settings. Using compiler build settings allows you to more easily specify the license information for each developer.

The vkActivateMoltenVKLicensesMVK() and vkActivateMoltenVKLicenseMVK(licenseID, licenseKey, acceptLicenseTermsAndConditions) functions are found in the vk_mvk_moltenvk.h header file. Include the following header line to your source code file that calls one of these functions:

#include <MoltenVK/vk_mvk_moltenvk.h>

If your Molten license is part of a multi-user pack, you must verify the user count with your license purchaser or administrator.

Once you have activated one or more licenses to cover the MoltenVK features you are using, an information message will appear in the console logs for each activated feature set:

[mvk-info] Activated MoltenVK Vulkan Core license for ''. Not ''? You can acquire your own license at

and the MoltenVK logo watermark will no longer be displayed on top of your graphic scene. If the watermark remains, ensure that you have indicated acceptance of the terms and conditions of the Molten License Agreement, as described above, and check the console logs to ensure that your license covers all of the MoltenVK features that you are using, as described in the following sub-section.

MoltenVK Product Support

Support for MoltenVK is readily available through the MoltenVK Support Forum. This forum is actively and professionally managed by the staff at MoltenVK, as well as the community of MoltenVK users like you. For more advanced support requirements, you can contact us to learn more about professional services available to help you integrate MoltenVK into your application.

Interacting with the MoltenVK Runtime

You programmatically configure and interact with the MoltenVK runtime through function calls, enumeration values, and capabilities, in exactly the same way you do with Vulkan. The MoltenVK.framework contains several header files that define access to MoltenVK configuration, capabilities, behaviour, and components:

Metal Shaders

Metal uses a different shader language than Vulkan. Vulkan uses the new SPIR-V Shading Language (SPIR-V), whereas Metal uses the Metal Shading Language (MSL).

MoltenVK provides several options for creating and running MSL versions of your existing SPIR-V shaders. The following options are presented in order of increasing sophistication and difficulty:

You can mix and match these options in your application. For example, a convenient approach is to use Runtime Shader Conversion for most SPIR-V shaders, and provide pre-converted MSL shader source code for the odd SPIR-V shader that proves problematic for runtime conversion.

MoltenShaderConverter Shader Converter Tool

The Molten distribution package includes the MoltenShaderConverter command line tool, which allows you to convert your SPIR-V shader source code to MSL at development time, and then supply the MSL code to MoltenVK using one of the methods described in the Metal Shaders section above.

The MoltenShaderConverter tool uses the same conversion technology as the Runtime Shader Conversion feature of MoltenVK.

The MoltenShaderConverter tool has a number of options available from the command line:

To see a complete list of options, run the MoltenShaderConverter tool from the command line with no arguments.

Troubleshooting Shader Conversion

The shader converter technology in MoltenVK is quite robust, and most SPIR-V shaders can be converted to MSL without any problems. In the case where a conversion issue arises, you can address the issue as follows:

Performance Considerations

This section discusses various options for improving performance when using MoltenVK.

Shader Loading Time

Metal supports pre-compiled shaders, which can improve shader loading and set-up performance, allowing you to reduce your scene loading time. See the Metal Shaders and MoltenShaderConverter Shader Converter Tool sections above for more information about how to use the MoltenShaderConverter Shader Converter Tool to create and load pre-compiled Metal shaders into MoltenVK.

Xcode Configuration

When a Metal app is running from Xcode, the default Scheme settings reduce performance. Be sure to follow the instructions for configuring your application's Scheme within Xcode, found in the in the installation section above.

Metal System Trace Tool

To help you get the best performance from your graphics app, in addition to the GPU Driver template, starting with Xcode 7 and iOS 9, the Instruments profiling tool includes the Metal System Trace template. This template can be used to provide detailed tracing of the CPU and GPU behaviour of your application, allowing you unprecedented performance measurement and tuning capabilities for apps using Metal.

Known MoltenVK Limitations

This section documents the known limitations in this version of MoltenVK.

The following Vulkan features have not been implemented in this version of MoltenVK:

MoltenVK and the Molten Shader Converter use technology from the open-source SPIRV-Cross and SPIR-V-Tools projects to perform SPIR-V to MSL shader conversion during Runtime Shader Conversion and in the MoltenShaderConverter tool.

The Molten Shader Converter uses technology from the open-source glslang project to help convert GLSL shaders to SPIR-V or MSL shader code in the MoltenShaderConverter tool.