Ryujinx/moltenvk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation to cover tvOS, iOS Simulator, and tvOS Simulator.

Browse Source
This commit is contained in:
Bill Hollings 2020-06-23 23:06:08 -04:00
parent 5419d229d0
commit 5e5d6439da
4 changed files with 100 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Demos/README.md
View File

@ -50,10 +50,11 @@ The demo can be found in the `LunarG-VulkanSamples/Cube` folder, and in the
`LunarG-VulkanSamples/Cube` group in the *Xcode Project Navigator* in the `LunarG-VulkanSamples/Cube` group in the *Xcode Project Navigator* in the
`Cube.xcworkspace` *Xcode* workspace. `Cube.xcworkspace` *Xcode* workspace.
To run this demo, run either the `Cube-iOS` or `Cube-macOS` *Scheme* from within *Xcode*. To run this demo, run the `Cube-iOS`, `Cube-tvOS`, or `Cube-macOS` *Scheme* from within *Xcode*.
In addition to devices, this demo will also run on the `iOS Simulator` or `tvOS Simulator` destinations.
This demo includes a sizable window, and represents an example of how to detect, within your The *macOS* version of this demo includes a sizable window, and represents an example of how to detect,
*Vulkan* code, when a window has been resized, and to modify the *Vulkan* swapchain accordingly. within your *Vulkan* code, when a window has been resized, and to modify the *Vulkan* swapchain accordingly.
The `Cube` demo is a simple example of installing **MoltenVK** as a *dynamic library*. In this demo, The `Cube` demo is a simple example of installing **MoltenVK** as a *dynamic library*. In this demo,
the **MoltenVK** *dynamic library* is embedded in the application, but it could have been installed the **MoltenVK** *dynamic library* is embedded in the application, but it could have been installed

84
Docs/MoltenVK_Runtime_UserGuide.md
View File

@ -41,8 +41,8 @@ Table of Contents
About This Document About This Document
------------------- -------------------
This document describes how to integrate the **MoltenVK** runtime distribution package into a game This document describes how to integrate the **MoltenVK** runtime distribution package into a game or
or application, once **MoltenVK** has been built into a framework or library for *iOS* or *macOS*. application, once **MoltenVK** has been built into a framework or library for *macOS*, *iOS*, or *tvOS*.
To learn how to use the **MoltenVK** open-source repository to build a **MoltenVK** runtime To learn how to use the **MoltenVK** open-source repository to build a **MoltenVK** runtime
distribution package, see the main [`README.md`](../README.md) document in the `MoltenVK` repository. distribution package, see the main [`README.md`](../README.md) document in the `MoltenVK` repository.
@ -55,9 +55,9 @@ About **MoltenVK**
**MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan) **MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan)
graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal)
graphics and compute framework on both *iOS* and *macOS*. **MoltenVK** allows you to use *Vulkan* graphics graphics and compute framework on *macOS*, *iOS*, and *tvOS*. **MoltenVK** allows you to use *Vulkan*
and compute functionality to develop modern, cross-platform, high-performance graphical games and applications, graphics and compute functionality to develop modern, cross-platform, high-performance graphical games
and to run them across many platforms, including both *iOS* and *macOS*. and applications, and to run them across many platforms, including both *macOS*, *iOS*, and *tvOS*.
*Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than
*Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders
@ -66,10 +66,10 @@ to their *MSL* equivalents. This can be performed transparently at run time, usi
[**MoltenVKShaderConverter**](#shader_converter_tool) tool provided with this **MoltenVK** [**MoltenVKShaderConverter**](#shader_converter_tool) tool provided with this **MoltenVK**
distribution package. distribution package.
To provide *Vulkan* capability to the *iOS* and *macOS* platforms, **MoltenVK** uses *Apple's* To provide *Vulkan* capability to the*macOS*, *iOS*, and *tvOS* platforms, **MoltenVK** uses
publicly available API's, including *Metal*. **MoltenVK** does **_not_** use any private or *Apple's* publicly available API's, including *Metal*. **MoltenVK** does **_not_** use any
undocumented API calls or features, so your app will be compatible with all standard distribution private or undocumented API calls or features, so your app will be compatible with all
channels, including *Apple's App Store*. standard distribution channels, including *Apple's App Store*.
<a name="install"></a> <a name="install"></a>
@ -82,13 +82,16 @@ Installing **MoltenVK** in Your *Vulkan* Application
**MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks when building **MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks when building
your app, and to avoid build errors, be sure to use the latest publicly available version of *Xcode*. your app, and to avoid build errors, be sure to use the latest publicly available version of *Xcode*.
>***Note:*** To support `IOSurfaces`, any app that uses **MoltenVK**, must be built with a minimum >***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, any app that uses **MoltenVK** must be
**iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `) build setting of `iOS 11.0` or greater. built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `) build setting
of `iOS 11.0` or greater, or a minimum **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET `)
build setting of `tvOS 11.0` or greater.
Once built, your app integrating the **MoltenVK** libraries can be run on *iOS* or *macOS* devices Once built, your app integrating the **MoltenVK** libraries can be run on *macOS*, *iOS* or *tvOS*
that support *Metal*. devices that support *Metal*, or on the *Xcode* *iOS Simulator* or *tvOS Simulator*.
- At runtime, **MoltenVK** requires at least *macOS 10.11* or *iOS 9* (or *iOS 11* if using `IOSurfaces`). - At runtime, **MoltenVK** requires at least *macOS 10.11*, *iOS 9*, or *tvOS 9*
(or *iOS 11* or *tvOS 11* if using `IOSurfaces`).
- Information on *macOS* devices that are compatible with *Metal* can be found in - Information on *macOS* devices that are compatible with *Metal* can be found in
[this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible). [this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible).
- Information on *iOS* devices that are compatible with *Metal* can be found in - Information on *iOS* devices that are compatible with *Metal* can be found in
@ -106,10 +109,11 @@ Depending on your build and deployment needs, you can install **MoltenVK** as a
about which linking and deployment option you need, follow the steps for installing a about which linking and deployment option you need, follow the steps for installing a
*static framework*, as it is the simplest to install. *static framework*, as it is the simplest to install.
>**_Note:_** Distributing an app containing a dynamic library via the *iOS App Store* can require >**_Note:_** Distributing an app containing a dynamic library via the *iOS App Store* or
specialized bundling. Unless you have specific needs for dynamic libraries, the recommended *tvOS App Store* can require specialized bundling. Unless you have specific needs for
approach on *iOS* is to link **MoltenVK** to your app as a static library. dynamic libraries, the recommended approach on *iOS* or *tvOS* is to link **MoltenVK**
to your app as a static library or framework.
1. Open your application in *Xcode* and select your application's target in the 1. Open your application in *Xcode* and select your application's target in the
*Project Navigator* panel. *Project Navigator* panel.
@ -122,12 +126,14 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
setting, add an entry that points to **_one_** of the following folders: setting, add an entry that points to **_one_** of the following folders:
- `MoltenVK/macOS/framework` *(macOS)* - `MoltenVK/macOS/framework` *(macOS)*
- `MoltenVK/iOS/framework` *(iOS)* - `MoltenVK/iOS/framework` *(iOS)*
- `MoltenVK/tvOS/framework` *(tvOS)*
- If installing **MoltenVK** as a *static library* in your application: - If installing **MoltenVK** as a *static library* in your application:
1. In the **Library Search Paths** (aka `LIBRARY_SEARCH_PATHS`) setting, 1. In the **Library Search Paths** (aka `LIBRARY_SEARCH_PATHS`) setting,
add an entry that points to **_one_** of the following folders: add an entry that points to **_one_** of the following folders:
- `MoltenVK/macOS/static` *(macOS)* - `MoltenVK/macOS/static` *(macOS)*
- `MoltenVK/iOS/static` *(iOS)* - `MoltenVK/iOS/static` *(iOS)*
- `MoltenVK/tvOS/static` *(tvOS)*
2. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting, 2. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
add an entry that points to the `MoltenVK/include` folder. add an entry that points to the `MoltenVK/include` folder.
@ -137,6 +143,7 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
add an entry that points to **_one_** of the following folders: add an entry that points to **_one_** of the following folders:
- `MoltenVK/macOS/dynamic` *(macOS)* - `MoltenVK/macOS/dynamic` *(macOS)*
- `MoltenVK/iOS/dynamic` *(iOS)* - `MoltenVK/iOS/dynamic` *(iOS)*
- `MoltenVK/tvOS/dynamic` *(tvOS)*
2. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting, 2. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
add an entry that points to the `MoltenVK/include` folder. add an entry that points to the `MoltenVK/include` folder.
@ -146,13 +153,15 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
you would typically set this value to either: you would typically set this value to either:
- `@executable_path/../Frameworks` *(macOS)* - `@executable_path/../Frameworks` *(macOS)*
- `@executable_path/Frameworks` *(iOS)* - `@executable_path/Frameworks` *(iOS or tvOS)*
The `libMoltenVK.dylib` library is internally configured to be located at The `libMoltenVK.dylib` library is internally configured to be located at
`@rpath/libMoltenVK.dylib`. `@rpath/libMoltenVK.dylib`.
3. With the *Build Settings* tab open, if using `IOSurfaces` on *iOS*, open the **iOS Deployment Target** 3. With the *Build Settings* tab open, if using `IOSurfaces` on *iOS*, open the **iOS Deployment Target**
(aka `IPHONEOS_DEPLOYMENT_TARGET`) setting, and ensure it is set to a value of `iOS 11.0` or greater. (aka `IPHONEOS_DEPLOYMENT_TARGET`) setting, and ensure it is set to a value of `iOS 11.0` or greater,
or if using `IOSurfaces` on *tvOS*, open the **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET`)
setting, and ensure it is set to a value of `tvOS 11.0` or greater.
4. On the *Build Phases* tab, open the *Link Binary With Libraries* list. 4. On the *Build Phases* tab, open the *Link Binary With Libraries* list.
@ -166,6 +175,11 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
- `MoltenVK/iOS/static/libMoltenVK.a` *(static library)* - `MoltenVK/iOS/static/libMoltenVK.a` *(static library)*
- `MoltenVK/iOS/dynamic/libMoltenVK.dylib` *(dynamic library)* - `MoltenVK/iOS/dynamic/libMoltenVK.dylib` *(dynamic library)*
- For *tvOS*, drag **_one_** of the following files to the *Link Binary With Libraries* list:
- `MoltenVK/tvOS/framework/MoltenVK.framework ` *(static framework)*
- `MoltenVK/tvOS/static/libMoltenVK.a` *(static library)*
- `MoltenVK/tvOS/dynamic/libMoltenVK.dylib` *(dynamic library)*
5. While in the *Link Binary With Libraries* list on the *Build Phases* tab, if you do **_not_** 5. While in the *Link Binary With Libraries* list on the *Build Phases* tab, if you do **_not_**
have the **Link Frameworks Automatically** (aka `CLANG_MODULES_AUTOLINK`) and have the **Link Frameworks Automatically** (aka `CLANG_MODULES_AUTOLINK`) and
**Enable Modules (C and Objective-C)** (aka `CLANG_ENABLE_MODULES`) settings enabled, click **Enable Modules (C and Objective-C)** (aka `CLANG_ENABLE_MODULES`) settings enabled, click
@ -175,8 +189,9 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
- `Foundation.framework`. - `Foundation.framework`.
- `QuartzCore.framework` - `QuartzCore.framework`
- `IOKit.framework` (*macOS*) - `IOKit.framework` (*macOS*)
- `UIKit.framework` (*iOS*) - `UIKit.framework` (*iOS* or *tvOS*)
- `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`) - `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`,
or *tvOS* if `TVOS_DEPLOYMENT_TARGET` is at least `tvOS 11.0`)
6. If installing **MoltenVK** as a *dynamic library* in your application, arrange to install 6. If installing **MoltenVK** as a *dynamic library* in your application, arrange to install
the `libMoltenVK.dylib` file in your application environment: the `libMoltenVK.dylib` file in your application environment:
@ -192,10 +207,12 @@ approach on *iOS* is to link **MoltenVK** to your app as a static library.
3. Drag **_one_** of the following files to the *Copy Files* list in this new build phase: 3. Drag **_one_** of the following files to the *Copy Files* list in this new build phase:
- `MoltenVK/macOS/dynamic/libMoltenVK.dylib` *(macOS)* - `MoltenVK/macOS/dynamic/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/iOS/dynamic/libMoltenVK.dylib` *(iOS)* - `MoltenVK/iOS/dynamic/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/tvOS/dynamic/libMoltenVK.dylib` *(tvOS)*
- Alternately, you may create your own installation mechanism to install either the - Alternately, you may create your own installation mechanism to install one of the
`MoltenVK/macOS/dynamic/libMoltenVK.dylib` or `MoltenVK/iOS/dynamic/libMoltenVK.dylib` `MoltenVK/macOS/dynamic/libMoltenVK.dylib`, `MoltenVK/iOS/dynamic/libMoltenVK.dylib`,
file into a standard *macOS* or *iOS* system library folder on the user's device. or `MoltenVK/tvOS/dynamic/libMoltenVK.dylib` file into a standard *macOS*, *iOS*, or
*tvOS* system library folder on the user's device.
7. When a *Metal* app is running from *Xcode*, the default ***Scheme*** settings reduce 7. 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 performance. To improve performance and gain the benefits of *Metal*, perform the
@ -287,17 +304,16 @@ In addition to core *Vulkan* functionality, **MoltenVK** also supports the foll
- `VK_MVK_moltenvk` - `VK_MVK_moltenvk`
- `VK_AMD_gpu_shader_half_float` - `VK_AMD_gpu_shader_half_float`
- `VK_AMD_negative_viewport_height` - `VK_AMD_negative_viewport_height`
- `VK_AMD_shader_image_load_store_lod` *(iOS)* - `VK_AMD_shader_image_load_store_lod` *(iOS and tvOS)*
- `VK_AMD_shader_trinary_minmax` *(requires Metal 2.1)* - `VK_AMD_shader_trinary_minmax` *(requires Metal 2.1)*
- `VK_IMG_format_pvrtc` *(iOS)* - `VK_IMG_format_pvrtc` *(iOS and tvOS)*
- `VK_INTEL_shader_integer_functions2` - `VK_INTEL_shader_integer_functions2`
- `VK_NV_glsl_shader` - `VK_NV_glsl_shader`
In order to visibly display your content on *iOS* or *macOS*, you must enable the `VK_EXT_metal_surface` In order to visibly display your content on *macOS*, *iOS*, or *tvOS*, you must enable the
extension, and use the function defined in that extension to create a *Vulkan* rendering surface. `VK_EXT_metal_surface` extension, and use the function defined in that extension to create a
You can enable the `VK_EXT_metal_surface` extension by defining the `VK_USE_PLATFORM_METAL_EXT` *Vulkan* rendering surface. You can enable the `VK_EXT_metal_surface` extension by defining the `VK_USE_PLATFORM_METAL_EXT` guard macro in your compiler build settings. See the description of
guard macro in your compiler build settings. See the description of the `mvk_vulkan.h` file below for the `mvk_vulkan.h` file below for a convenient way to enable this extension automatically.
a convenient way to enable this extension automatically.
<a name="moltenvk_extension"></a> <a name="moltenvk_extension"></a>
@ -320,8 +336,8 @@ where `HEADER_FILE` is one of the following:
- `mvk_vulkan.h` - This is a convenience header file that loads the `vulkan.h` header file - `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 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, enabled for *macOS*, *iOS*, or *tvOS*. Use this header file in place of the `vulkan.h`
where access to a **MoltenVK** platform surface extension is required. header file, where access to a **MoltenVK** platform surface extension is required.
The `mvk_vulkan.h` header file automatically enables the `VK_USE_PLATFORM_METAL_EXT` The `mvk_vulkan.h` header file automatically enables the `VK_USE_PLATFORM_METAL_EXT`
build setting and `VK_EXT_metal_surface` *Vulkan* extension. build setting and `VK_EXT_metal_surface` *Vulkan* extension.

7
Docs/Whats_New.md
View File

@ -21,7 +21,12 @@ Released TBD
- Add support for extensions: - Add support for extensions:
- VK_KHR_sampler_ycbcr_conversion - VK_KHR_sampler_ycbcr_conversion
- VK_EXT_robustness2 - VK_EXT_robustness2
- `fetchDependencies` script supports platform build selection. - Add support for **_tvOS_** platform.
- Add support for **_iOS Simulator_** and **_tvOS Simulator_** build destinations.
- Cube demo runs on **_tvOS_**, **_iOS Simulator_**, and **_tvOS Simulator_**.
- **_MoltenVK_** Xcode schemes support building fat *Platform+Simulator* binaries.
- `Makefile` supports building fat *Platform+Simulator* binaries, plus *Debug* builds.
- `fetchDependencies` script supports platform build selection, plus parallel builds.
- Fix issue where mapped host-coherent device memory not updated from image contents on *macOS*. - Fix issue where mapped host-coherent device memory not updated from image contents on *macOS*.
- Remove use of `@available()` directive as it was causing issues in some build environments. - Remove use of `@available()` directive as it was causing issues in some build environments.
- Refactor **MoltenVK** *Xcode* build architectures. - Refactor **MoltenVK** *Xcode* build architectures.

73
README.md
View File

@ -17,7 +17,7 @@ For best results, use a Markdown reader.*
Table of Contents Table of Contents
----------------- -----------------
- [Developing Vulkan Applications on macOS and iOS](#developing_vulkan) - [Developing Vulkan Applications on *macOS, iOS, and tvOS*](#developing_vulkan)
- [Introduction to **MoltenVK**](#intro) - [Introduction to **MoltenVK**](#intro)
- [Fetching **MoltenVK** Source Code](#install) - [Fetching **MoltenVK** Source Code](#install)
- [Building **MoltenVK**](#building) - [Building **MoltenVK**](#building)
@ -30,8 +30,8 @@ Table of Contents
<a name="developing_vulkan"></a> <a name="developing_vulkan"></a>
Developing Vulkan Applications for macOS and iOS Developing Vulkan Applications for *macOS, iOS, and tvOS*
------------------------------------------------ ---------------------------------------------------------
The recommended method for developing a *Vulkan* application for *macOS* is to use the The recommended method for developing a *Vulkan* application for *macOS* is to use the
[*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home). [*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home).
@ -43,9 +43,10 @@ tool for application developers because they identify inappropriate use of the *
If you are developing a *Vulkan* application for *macOS*, it is highly recommended that you use the If you are developing a *Vulkan* application for *macOS*, it is highly recommended that you use the
[*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home) and the **MoltenVK** library included in it. [*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home) and the **MoltenVK** library included in it.
If you are developing a *Vulkan* application for *iOS*, or are developing a *Vulkan* application for If you are developing a *Vulkan* application for *iOS* or *tvOS*, or are developing a *Vulkan*
*macOS* and want to use a different **MoltenVK** runtime library than provided in the *macOS Vulkan SDK*, application for *macOS* and want to use a different version of the **MoltenVK** runtime library
you can use this document to learn how to build a **MoltenVK** runtime library from source code. provided in the *macOS Vulkan SDK*, you can use this document to learn how to build a **MoltenVK**
runtime library from source code.
To learn how to integrate the **MoltenVK** runtime library into a game or application, To learn how to integrate the **MoltenVK** runtime library into a game or application,
see the [`MoltenVK_Runtime_UserGuide.md `](Docs/MoltenVK_Runtime_UserGuide.md) see the [`MoltenVK_Runtime_UserGuide.md `](Docs/MoltenVK_Runtime_UserGuide.md)
@ -59,30 +60,31 @@ Introduction to MoltenVK
**MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan) **MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan)
graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal)
graphics and compute framework on both *iOS* and *macOS*. **MoltenVK** allows you to use *Vulkan* graphics graphics and compute framework on *macOS*, *iOS*, and *tvOS*. **MoltenVK** allows you to use *Vulkan*
and compute functionality to develop modern, cross-platform, high-performance graphical games and applications, graphics and compute functionality to develop modern, cross-platform, high-performance graphical
and to run them across many platforms, including both *iOS* and *macOS*. games and applications, and to run them across many platforms, including *macOS*, *iOS*, and *tvOS*.
*Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than
*Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders
to their *MSL* equivalents. to their *MSL* equivalents.
To provide *Vulkan* capability to the *iOS* and *macOS* platforms, **MoltenVK** uses *Apple's* To provide *Vulkan* capability to the *macOS*, *iOS*, and *tvOS* platforms, **MoltenVK** uses *Apple's*
publicly available API's, including *Metal*. **MoltenVK** does **_not_** use any private or publicly available API's, including *Metal*. **MoltenVK** does **_not_** use any private or
undocumented API calls or features, so your app will be compatible with all standard distribution undocumented API calls or features, so your app will be compatible with all standard distribution
channels, including *Apple's App Store*. channels, including *Apple's App Store*.
The **MoltenVK** runtime package contains two products: The **MoltenVK** runtime package contains two products:
- **MoltenVK** is a driver-level implementation of the [*Vulkan 1.0*](https://www.khronos.org/vulkan) - **MoltenVK** is a implementation of an almost-complete subset of the
graphics and compute API. [*Vulkan 1.0*](https://www.khronos.org/vulkan) graphics and compute API.
- **MoltenVKShaderConverter** converts *SPIR-V* shader code to *Metal Shading Language (MSL)* - **MoltenVKShaderConverter** converts *SPIR-V* shader code to *Metal Shading Language (MSL)*
shader code, and converts *GLSL* shader source code to *SPIR-V* shader code and/or shader code, and converts *GLSL* shader source code to *SPIR-V* shader code and/or
*Metal Shading Language (MSL)* shader code. The *SPIR-V* converter is included in the *Metal Shading Language (MSL)* shader code. The *SPIR-V* portion of the converter is also
**MoltenVK** runtime to automatically convert *SPIR-V* shaders to their *MSL* equivalents. embedded in the **MoltenVK** runtime to automatically convert *SPIR-V* shaders to their *MSL*
In addition, both the *SPIR-V* and *GLSL* converters can be be packaged into a stand-alone equivalents. In addition, both the *SPIR-V* and *GLSL* converters are packaged into a
command-line *macOS* tool for converting shaders at development time. stand-alone command-line `MoltenVKShaderConverter` *macOS* tool for converting shaders
at development time from the command line.
@ -115,13 +117,13 @@ on which **MoltenVK** relies:
When running the `fetchDependencies` script, you must specify one or more platforms When running the `fetchDependencies` script, you must specify one or more platforms
for which to build the external libraries. The platform choices include: for which to build the external libraries. The platform choices include:
--ios --iosfat --tvos --tvosfat --macos --all --all --macos --ios --iosfat --tvos --tvosfat
You can specify multiple of these selections. The `--iosfat` and `--tvosfat` selection builds one You can specify multiple of these selections. The `--iosfat` and `--tvosfat` selection builds one
binary for each external library, with each binary including code for both *iOS* and *iOS Simulator* binary for each external library, with each binary including code for both *iOS* and *iOS Simulator*
platforms, or *tvOS* and *tvOS Simulator* platforms, respectively. The `--all` selection is the same platforms, or *tvOS* and *tvOS Simulator* platforms, respectively. The `--all` selection is the same
as selecting `--iosfat --tvosfat --macos` and results in three binaries for each external library: as selecting `--macos --iosfat --tvosfat` and results in three binaries for each external library:
a *fat iOS* binary, a *fat tvOS* binary, and a *macOS* binary. The more selections you include, a *macOS* binary, a *fat iOS* binary, and a *fat tvOS* binary. The more selections you include,
the longer the build time. the longer the build time.
For more information about the external open-source libraries used by **MoltenVK**, For more information about the external open-source libraries used by **MoltenVK**,
@ -135,13 +137,16 @@ Building **MoltenVK**
During building, **MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks, During building, **MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks,
and to avoid build errors, be sure to use the latest publicly available version of *Xcode*. and to avoid build errors, be sure to use the latest publicly available version of *Xcode*.
>***Note:*** To support `IOSurfaces` on *iOS*, **MoltenVK**, and any app that uses **MoltenVK**, >***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, **MoltenVK**, and any app that uses
must be built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `) build **MoltenVK**, must be built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `)
setting of `iOS 11.0` or greater. build setting of `iOS 11.0` or greater, or a minimum **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET `)
build setting of `tvOS 11.0` or greater.
Once built, the **MoltenVK** libraries can be run on *iOS* or *macOS* devices that support *Metal*. Once built, the **MoltenVK** libraries can be run on *macOS*, *iOS* or *tvOS* devices that support *Metal*,
or on the *Xcode* *iOS Simulator* or *tvOS Simulator*.
- At runtime, **MoltenVK** requires at least *macOS 10.11* or *iOS 9* (or *iOS 11* if using `IOSurfaces`). - At runtime, **MoltenVK** requires at least *macOS 10.11*, *iOS 9*, or *tvOS 9*
(or *iOS 11* or *tvOS 11* if using `IOSurfaces`).
- Information on *macOS* devices that are compatible with *Metal* can be found in - Information on *macOS* devices that are compatible with *Metal* can be found in
[this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible). [this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible).
- Information on *iOS* devices that are compatible with *Metal* can be found in - Information on *iOS* devices that are compatible with *Metal* can be found in
@ -229,7 +234,7 @@ Running the **MoltenVK** Demo Applications
Once you have compiled and built the **MoltenVK** runtime distribution package from this **MoltenVK** repository, Once you have compiled and built the **MoltenVK** runtime distribution package from this **MoltenVK** repository,
as described in the [Building **MoltenVK**](#building) section, you can explore how **MoltenVK** provides *Vulkan* as described in the [Building **MoltenVK**](#building) 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**. support on *macOS*, *iOS*, and *tvOS* 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. 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*. To review and run the included demo apps, open the `Demos/Demos.xcworkspace` workspace in *Xcode*.
@ -260,19 +265,20 @@ the contents of that directory out of this **MoltenVK** repository into your own
**MoltenVK** and *Vulkan* Compliance **MoltenVK** and *Vulkan* Compliance
------------------------------------ ------------------------------------
**MoltenVK** is designed to be a *Vulkan 1.0* driver that runs on *macOS* and *iOS* platforms by mapping *Vulkan* **MoltenVK** is designed to be an implementation of a *Vulkan 1.0* subset that runs on *macOS*, *iOS*,
capability to native *Metal* capability. and *tvOS* 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 The fundamental design and development goal of **MoltenVK** is to provide this capability in a way that
is both maximally compliant with the *Vulkan 1.0* specification, and maximally performant. is both maximally compliant with the *Vulkan 1.0* specification, and maximally performant.
Such compliance and performance is inherently affected by the capability available through *Metal*, as the 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: native graphics driver on *macOS*, *iOS*, and *tvOS* platforms. *Vulkan* compliance may fall into one of
the following categories:
- Direct mapping between *Vulkan* capabilities and *Metal* capabilities. Within **MoltenVK**, almost all capability - Direct mapping between *Vulkan* capabilities and *Metal* capabilities. Within **MoltenVK**, the vast
is the result of this type of direct mapping. majority of *Vulkan* capability is the result of this type of direct mapping.
- Synthesized compliance through alternate implementation. A very small amount of capability is provided using - Synthesized compliance through alternate implementation. A small amount of capability is provided using
this mechanism, such as via an extra render or compute shader stage. 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 - Non-compliance. This appears where the capabilities of *Vulkan* and *Metal* are sufficiently different, that
@ -286,10 +292,11 @@ The **MoltenVK** development team welcomes you to [post Issues](https://github.c
of non-compliance, and engage in discussions about how compliance can be improved, and non-compliant features can of non-compliance, and engage in discussions about how compliance can be improved, and non-compliant features can
be implemented or worked around. be implemented or worked around.
**MoltenVK** is a key component of the [*Khronos Vulkan Portability Initiative*](https://www.khronos.org/vulkan/portability-initiative), **MoltenVK** is a key component of the
[*Khronos Vulkan Portability Initiative*](https://www.khronos.org/vulkan/portability-initiative),
whose intention is to provide specifications, resources, and tools to allow developers to understand and design 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 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 available. *macOS*, *iOS*, and *tvOS*, where a native *Vulkan* driver is not available.