Copyright (c) 2014-2017 The Brenwill Workshop Ltd. All rights reserved.
CAREFULLY READ THE Molten LICENSE AGREEMENT, FOUND IN THIS Molten DISTRIBUTION PACKAGE. BY INSTALLING OR OTHERWISE USING THIS Molten DISTRIBUTION PACKAGE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS AND CONDITIONS OF THE Molten LICENSE AGREEMENT. IF YOU DO NOT ACCEPT THE TERMS AND CONDITIONS OF THE Molten LICENSE AGREEMENT, DO NOT INSTALL OR USE THIS Molten DISTRIBUTION PACKAGE.
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.
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 Demos/README_MoltenVK_Demos.md 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.md document.
Note: MoltenVK can be run on iOS 9 and macOS 11.0 devices, but it does reference advanced OS frameworks during building. Xcode 9 or above is required to build and link MoltenVK projects.
Installation of MoltenVK is straightforward and easy!
For most applications, you can install MoltenVK as a static library framework that will be embedded directly in your application executable, or a component library within your application. This is simple and straightforward, and is the recommended installation approach for all applications.
To add MoltenVK as a static library framework 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.
Open your application in Xcode and select your application's target in the Project Navigator panel.
Open the Build Settings tab, and in the Framework Search Paths (aka FRAMEWORK_SEARCH_PATHS
)
setting:
MoltenVK/iOS
folder,
found in the Molten distribution package.MoltenVK/macOS
folder,
found in the Molten distribution package.On the Build Phases tab, open the Link Binary With Libraries list.
MoltenVK/iOS/MoltenVK.framework
or MoltenVK/macOS/MoltenVK.framework
folder,
found in the Molten distribution package, to the Link Binary With Libraries list.libc++.tbd
. CLANG_MODULES_AUTOLINK
) and
Enable Modules (C and Objective-C (aka CLANG_ENABLE_MODULES
) settings enabled, click the
+ button, and (selecting from the list of system frameworks) add Metal.framework
,
IOSurface.framework
, and QuartzCore.framework
.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:
For some applications, you may prefer to install MoltenVK as a dynamic library. This is only recommended for developers who are used to working with dynamic libraries, and even then, the preferred approach is to link the MoltenVK static library framework into a dynamic library of your own creation, in order to give you the most flexibility for organizing your dynamic libraries.
In order to install MoltenVK as its own dynamic library in your application, follow these instructions:
Open your application in Xcode and select your application's target in the Project Navigator panel.
On the Build Settings tab:
HEADER_SEARCH_PATHS
) setting, add an entry
that points to the MoltenVK/include
folder, found in the Molten distribution package.HEADER_SEARCH_PATHS
) setting, add an entry
that points to either the MoltenVK/iOS
or MoltenVK/macOS
folder, found in the
Molten distribution package.LD_RUNPATH_SEARCH_PATHS
) setting, add a path
that matches the library destination you established in Step 2 above. If the dynamic
library is to be embedded within your application, you would typically set this value to
either @executable_path
or @loader_path
. The libMoltenVK.dylib
library is internally
configured to be located at @rpath/libMoltenVK.dylib
.On the Build Phases tab, open the Link Binary With Libraries list.
MoltenVK/iOS/libMoltenVK.dylib
or MoltenVK/macOS/libMoltenVK.dylib
file,
found in the Molten distribution package, to the Link Binary With Libraries list.libc++.tbd
. CLANG_MODULES_AUTOLINK
) and
Enable Modules (C and Objective-C (aka CLANG_ENABLE_MODULES
) settings enabled, click the
+ button, and (selecting from the list of system frameworks) add Metal.framework
,
IOSurface.framework
, and QuartzCore.framework
.Arrange to install the libMoltenVK.dylib
file in your application environment:
To copy the libMoltenVK.dylib
file into your application or component library:
libMoltenVK.dylib
file.
Typically this will be Executables.MoltenVK/iOS/libMoltenVK.dylib
or MoltenVK/macOS/libMoltenVK.dylib
file to the Copy Files list in this new build phase.Alternately, you may create your own installation mechanism to install the
MoltenVK/iOS/libMoltenVK.dylib
or MoltenVK/macOS/libMoltenVK.dylib
file
into a standard iOS or macOS system library folder on the user's device.
The Cube-iOS
and Cube-macOS
MoltenVK demo apps, found in the Demos.xcworkspace
,
located in the MoltenVK/Demos
folder within the Molten distribution package, are simple
examples of installing MoltenVK as a dynamic library embedded within an iOS or macOS
application, respectively.
You programmatically configure and interact with the MoltenVK runtime through function
calls, enumeration values, and capabilities, in exactly the same way you do with other
Vulkan implementations. The MoltenVK.framework
contains several header files that define
access to Vulkan and MoltenVK function calls.
In your application code, you access Vulkan features through the API defined in the standard
vulkan.h
header file. This file is included in the MoltenVK framework, and can be included
in your source code files as follows:
#include <MoltenVK/vulkan/vulkan.h>
If you are linking MoltenVK as a dynamic library
(see Install as Dynamic Library), or if you prefer to have
exposed header files, add MoltenVK/include
to your header search path, and include the
vulkan.h
file as follows:
#include <vulkan/vulkan.h>
In addition to the core Vulkan API, MoltenVK also supports the following Vulkan extensions:
VK_KHR_swapchain
VK_KHR_surface
VK_MVK_ios_surface
VK_MVK_macos_surface
VK_MVK_moltenvk
VK_IMG_format_pvrtc
In order to visibly display your content on iOS or macOS, you must enable the
VK_MVK_ios_surface
or VK_MVK_macos_surface
extension, and use the functions defined
for those extensions to create a Vulkan rendering surface on iOS or macOS, respectively.
You can enable each of these extensions by defining the VK_USE_PLATFORM_IOS_MVK
or
VK_USE_PLATFORM_MACOS_MVK
guard macro in your compiler build settings. See the description
of the mvk_vulkan.h
file below for a convenient way to enable these extensions automatically.
The Vulkan API, including the VK_MVK_ios_surface
and VK_MVK_macos_surface
surface
extensions, and other Vulkan extensions supported by MoltenVK (except VK_MVK_moltenvk
),
is described in the
Vulkan 1.0 Spec with MoltenVK Extensions
document.
The VK_MVK_moltenvk
Vulkan extension provides functionality beyond the standard Vulkan
API, to support configuration options, license registration, and behaviour that is specific
to the MoltenVK implementation of Vulkan. You can access this functionality by including
the vk_mvk_moltenvk.h
header file in your code. The vk_mvk_moltenvk.h
file also includes
the API documentation for this VK_MVK_moltenvk
extension.
The following API header files are included in the MoltenVK package, each of which can be included in your application source code as follows:
#include <MoltenVK/HEADER_FILE>
where HEADER_FILE
is one of the following:
mvk_vulkan.h
- This is a convenience header file that loads the vulkan.h
header file
with the appropriate MoltenVK Vulkan platform surface extension automatically
enabled for iOS or macOS. Use this header file in place of the vulkan.h
header file,
where access to a MoltenVK platform surface extension is required.
mvk_vulkan.h
header file automatically enables the
VK_MVK_ios_surface
Vulkan extension.mvk_vulkan.h
header file automatically enables the
VK_MVK_macos_surface
Vulkan extension.vk_mvk_moltenvk.h
- Contains declarations and documenation for the functions, structures,
and enumerations that define the behaviour of the VK_MVK_moltenvk
Vulkan extension.
mvkDataTypes.h
- Contains helpful functions for converting between Vulkan and Metal data types.
mlnEnv.h
- Contains foundational environmental configuration, including the version of
MoltenVK, and build directives that help tell your application how to interact
with MoltenVK on various platforms. You generally don't use this file directly; it is
imported by the automatic other header files.
Note: Previous versions of MoltenVK included two further header files,
vk_mvk_ios_surface.h
andvk_mvk_macos_surface.h
. These header files are no longer available, as theVK_MVK_ios_surface
andVK_MVK_macos_surface
extensions are now part ofvulkan.h
. Use themvk_vulkan.h
header file in place of thevk_mvk_ios_surface.h
andvk_mvk_macos_surface.h
files.
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:
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:
MLN_LICENSE_ID and MLN_LICENSE_KEY
MLN_LICENSE_ID_1 and MLN_LICENSE_KEY_1
MLN_LICENSE_ID_2 and MLN_LICENSE_KEY_2
MLN_LICENSE_ID_3 and MLN_LICENSE_KEY_3
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:
MLN_LICENSE_ID=john.doe@example.com
MLN_LICENSE_KEY=NOVOT3NGHDZ6OQSCXX4VYNXGI3QLI6Z6
and if you purchase an additional feature set on a separate license, you can add a second pair of build settings:
MLN_LICENSE_ID_1=john.doe@example.com
MLN_LICENSE_KEY_1=MZ4T1Y2LDKBJHAL73JPOEJBHELRHEQJF
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:
MLN_LICENSE_ACCEPT_TERMS_AND_CONDITIONS=1
You can call the vkActivateMoltenVKLicensesMVK()
function at any time, but typically
you will call it during application startup.
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 'john.doe@example.com'. Not 'john.doe@example.com'? You can acquire your own license at http://www.moltengl.com.
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.
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.
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 use the Runtime Shader Conversion feature of MoltenVK to automatically and
transparently convert your SPIR-V shaders to MSL at runtime, by simply loading your
SPIR-V shaders as you always have, using the standard Vulkan vkCreateShaderModule()
function. MoltenVK will automatically convert the SPIR-V code to MSL at runtime.
You can use the standard Vulkan vkCreateShaderModule()
function to provide your own MSL
shader code. To do so, set the value of the magic number element of the SPIR-V stream to
one of the values in the MVKMSLMagicNumber
enumeration found in the mvkDataTypes.h
header file.
The magic number element of the SPIR-V stream is the first element of the stream,
and by setting the value of this element to either kMVKMagicNumberMSLSourceCode
or
kMVKMagicNumberMSLCompiledCode
, on SPIR-V code that you submit to the vkCreateShaderModule()
function, you are indicating that the remainder of the SPIR-V stream contains either
MSL source code, or MSL compiled code, respectively.
You can use the MoltenShaderConverter
command-line tool found in this Molten distribution
package to convert your SPIR-V shaders to MSL source code, offline at development time,
in order to create the appropriate MSL code to load at runtime. The section below
discusses how to use this tool in more detail.
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.
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:
The tool can be used to convert a single SPIR-V file to MSL, or an entire directory tree of SPIR-V files to MSL.
The tool can be used to convert a single OpenGL GLSL file, or an entire directory tree of GLSL files to either SPIR-V or MSL.
To see a complete list of options, run the MoltenShaderConverter
tool from the command
line with no arguments.
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:
Errors encountered during Runtime Shader Conversion are logged to the console.
To help understand conversion issues during Runtime Shader Conversion, you can enable the logging of the SPIR-V and MSL shader source code during conversion as follows:
#include <MoltenVK/vk_mvk_moltenvk.h>
...
MVKDeviceConfiguration mvkConfig;
vkGetMoltenVKDeviceConfigurationMVK(vkDevice, &mvkConfig);
mvkConfig.debugMode = true;
vkSetMoltenVKDeviceConfigurationMVK(vkDevice, &mvkConfig);
Performing these steps will enable debug mode in MoltenVK, which includes shader conversion logging, and causes both the incoming SPIR-V code and the converted MSL source code to be logged to the console (in human-readable form). This allows you to manually verify the conversions, and can help you diagnose issues that might occur during shader conversion.
For minor issues, you may be able to adjust your SPIR-V code so that it behaves the same under Vulkan, but is easier to automatically convert to MSL.
For more significant issues, you can use the MoltenShaderConverter
tool to convert the
shaders at development time, adjust the MSL code manually so that it compiles correctly,
and use the MSL shader code instead of the SPIR-V code, using the techniques described
in the Metal Shaders section above.
This section discusses various options for improving performance when using MoltenVK.
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.
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.
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.
This section documents the known limitations in this version of MoltenVK.
The following Vulkan features have not been implemented in this version of MoltenVK:
Tessellation and Geometry shader stages.
Events:
Application-controlled memory allocations:
Sparse memory:
Pipeline statistics query pool:
VkImageViewCreateInfo::VkComponentMapping supports only the following per-texture swizzles:
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.