## File: README.md MoltenVK ======== Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." Table of Contents ----------------- - [Introduction to **MoltenVK**](#intro) - [Developing Vulkan Applications on *macOS, iOS, tvOS, and visionOS*](#developing_vulkan) - [Using the *Vulkan SDK*](#sdk) - [Using MoltenVK Directly](#download) - [Fetching **MoltenVK** Source Code](#install) - [Building **MoltenVK**](#building) - [Building With _Xcode_](#xcode_build) - [Building From the Command Line](#command_line_build) - [Hiding _Vulkan_ API Symbols](#hiding_vulkan_symbols) - [Accessing _Metal_ Private API Calls](#metal_private_api) - [Install *MoltenVK* to Replace The _Vulkan SDK_ `libMoltenVK.dylib`](#install_vksdk) - [Running **MoltenVK** Demo Applications](#demos) - [Using **MoltenVK** in Your Application](#using) - [**MoltenVK** and *Vulkan* Compliance](#compliance) - [Getting Support](#support) - [Contributing to **MoltenVK** Development](#contributing) Introduction to MoltenVK ------------------------ **MoltenVK** is a layered implementation of [*Vulkan 1.4*](https://www.khronos.org/vulkan) graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) graphics and compute framework on *macOS*, *iOS*, *tvOS*, and *visionOS*. **MoltenVK** allows you to use *Vulkan* graphics and compute functionality to develop modern, cross-platform, high-performance graphical games and applications, and to run them across many platforms, including *macOS*, *iOS*, *tvOS*, *visionOS*, *Simulators*, and *Mac Catalyst*, and all *Apple* architectures, including *Apple Silicon*. *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders to their *MSL* equivalents. To provide *Vulkan* capability to the *macOS*, *iOS*, *tvOS*, and *visionOS* platforms, **MoltenVK** uses *Apple's* 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 channels, including *Apple's App Store*. The **MoltenVK** runtime package contains two products: - **MoltenVK** is a implementation of an almost-complete subset of the [*Vulkan 1.4*](https://www.khronos.org/vulkan) graphics and compute API. - **MoltenVKShaderConverter** converts *SPIR-V* shader code to *Metal Shading Language (MSL)* shader code. The converter is embedded in the **MoltenVK** runtime to automatically convert *SPIR-V* shaders to their *MSL* equivalents. In addition, the *SPIR-V* converter is packaged into a stand-alone command-line `MoltenVKShaderConverter` *macOS* tool for converting shaders at development time from the command line. Developing *Vulkan* Applications for *macOS, iOS, tvOS, and visionOS* --------------------------------------------------------------------- ### Using the *Vulkan SDK* The recommended method for developing a *Vulkan* application for *macOS* is to use the [*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home). The *Vulkan SDK* includes a **MoltenVK** runtime library for *macOS*. *Vulkan* is a layered architecture that allows applications to add additional functionality without modifying the application itself. The *Validation Layers* included in the *Vulkan SDK* are an essential debugging tool for application developers because they identify inappropriate use of the *Vulkan API*. 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. Refer to the *Vulkan SDK [Getting Started](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html)* document for more info. Because **MoltenVK** supports the `VK_KHR_portability_subset` extension, when using the *Vulkan Loader* from the *Vulkan SDK* to run **MoltenVK** on *macOS*, the *Vulkan Loader* will only include **MoltenVK** `VkPhysicalDevices` in the list returned by `vkEnumeratePhysicalDevices()` if the `VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR` flag is enabled in `vkCreateInstance()`. See the description of the `VK_KHR_portability_enumeration` extension in the *Vulkan* specification for more information about the use of the `VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR` flag. ### Using MoltenVK Directly If you are developing a *Vulkan* application for *iOS*, *tvOS*, or *visionOS*, or are developing a *Vulkan* application for *macOS* and want to use a different version or build of the **MoltenVK** runtime library than provided in the *macOS Vulkan SDK*, you can access a pre-built MoltenVK binary library from the **MoltenVK** repository, by [selecting a repository commit from the list](https://github.com/KhronosGroup/MoltenVK/actions), and downloading the associated **MoltenVK** runtime library artifact. Finally, if you want a customized build of **MoltenVK**, you can follow the [instructions below](#install) to create a **MoltenVK** runtime library by fetching and building the **MoltenVK** source code. 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) document in the `Docs` directory. Fetching **MoltenVK** Source Code --------------------------------- To fetch **MoltenVK** source code, clone this `MoltenVK` repository, and then run the `fetchDependencies` script to retrieve and build several external open-source libraries on which **MoltenVK** relies: 1. Ensure you have `cmake` and `python3` installed: brew install cmake brew install python3 For faster dependency builds, you can also optionally install `ninja`: brew install ninja 2. Clone the `MoltenVK` repository: git clone https://github.com/KhronosGroup/MoltenVK.git 3. Retrieve and build the external libraries: cd MoltenVK ./fetchDependencies [platform...] When running the `fetchDependencies` script, you must specify one or more platforms for which to build the external libraries. The platform choices include: --all --macos --ios --iossim --maccat --tvos --tvossim You can specify multiple of these selections. The result is a single `XCFramework` for each external dependency library, with each `XCFramework` containing binaries for each of the requested platforms. The `--all` selection is the same as entering all of the other platform choices, and will result in a single `XCFramework` for each external dependency library, with each `XCFramework` containing binaries for all supported platforms and simulators. Running `fetchDependencies` repeatedly with different platforms will accumulate targets in the `XCFramework`, if the `--keep-cache` option is used on each invocation. For more information about the external open-source libraries used by **MoltenVK**, see the [`ExternalRevisions/README.md`](ExternalRevisions/README.md) document. Building **MoltenVK** ------------------- 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*. MoltenVK currently supports being built with *Xcode 15.0.1* or later. Support is based on the earliest version of Xcode that can be verified in CI workflows. Once built, the **MoltenVK** libraries can be run on *macOS*, *iOS*, *tvOS*, or *visionOS* devices that support *Metal*,or on the *Xcode* *iOS Simulator*, *tvOS Simulator*, or *visionOS Simulator*. - The minimum runtime OS versions are indicated in the _Deployment Target_ build settings in `MoltenVK.xcodeproj`. - 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). - Information on *iOS* devices that are compatible with *Metal* can be found in [this article](https://developer.apple.com/library/content/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/HardwareGPUInformation/HardwareGPUInformation.html). ### Building With _Xcode_ 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*, depending on whether you want a **_Release_** or **_Debug_** configuration, and whether you want to build for all platforms, or just one platform (in **_Release_** configuration): - **MoltenVK Package** - **MoltenVK Package (Debug)** - **MoltenVK Package (macOS only)** - **MoltenVK Package (iOS only)** - **MoltenVK Package (tvOS only)** - **MoltenVK Package (visionOS only)** _(requires Xcode 15+)_ Each of these`MoltenVKPackaging.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. _**Note:**_ Due to technical limitations in the dynamic library build tools, dynamic frameworks and libraries cannot be created for the _tvOS Simulator_, or _MacCatalyst_ platforms. Static frameworks are created for these, and all other, platforms. 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](#using) to link your application to the **MoltenVK** libraries and 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. ### Building From the Command Line If you prefer to build **MoltenVK** from the command line, or to include the activity in a larger build script, you can do so by executing a command similar to the following command within the `MoltenVK` repository folder, and identifying one of the *Xcode Schemes* from the list above. For example, the following command will build **MoltenVK** in the **_Debug_** configuration for *macOS* only: xcodebuild build -quiet -project MoltenVKPackaging.xcodeproj -scheme "MoltenVK Package (macOS only)" -configuration "Debug" Alternately, you can use the basic `Makefile` in the `MoltenVK` repository folder to build **MoltenVK** from the command line. The following `make` targets are provided: make make all make macos make ios make iossim make maccat make tvos make tvossim make all-debug make macos-debug make ios-debug make iossim-debug make maccat-debug make tvos-debug make tvossim-debug make clean make install - Running `make` repeatedly with different targets will accumulate binaries for these different targets. - The `all` target executes all platform targets. - The `all` target is the default target. Running `make` with no arguments is the same as running `make all`. - The `*-debug` targets build the binaries using the **_Debug_** configuration. - The `install` target will copy the most recently built `Package/Latest/MoltenVK/dynamic/dylib/macOS/libMoltenVK.dylib` into the `/usr/local/lib` system directory on your computer. Since `/usr/local/lib` is protected, you will generally need to run it as `sudo make install` and enter your password. The `install` target does not build **MoltenVK**, and you need to run `make macos` or `make macos-debug` first. The `make` targets all require that *Xcode* is installed on your system. _**Note:**_ Due to technical limitations within _Xcode_, a dynamic framework is not created for the _MacCatalyst_ platform. Building from the command line creates the same `Package` folder structure described above when building from within *Xcode*. When building from the command line, you can set any of the build settings documented in the `MoltenVK_Configuration_Parameters.md` file, by passing them in the command line, as in the following examples: make MVK_CONFIG_LOG_LEVEL=0 or make macos MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS=1 ...etc. ### Hiding _Vulkan_ API Symbols You can optionally build **MoltenVK** with the _Vulkan_ API static call symbols (`vk*`) hidden, to avoid library linking conflicts when statically bound to a _Vulkan_ loader that also exports identical symbols. To do so, when building **MoltenVK**, set the build setting `MVK_HIDE_VULKAN_SYMBOLS=1`. This build setting can be set in the `MoltenVK.xcodeproj` *Xcode* project, or it can be included in any of the `make` command-line build commands [mentioned above](#command_line_build). With `MVK_HIDE_VULKAN_SYMBOLS=1`, the _Vulkan_ `vkGetInstanceProcAddr()` call remains statically bound, to provide the application with the ability to retrieve the remaining _Vulkan_ API calls as function pointers. ### Accessing _Metal_ Private API Calls You can optionally build **MoltenVK** with access to private _Metal_ API calls, also known as "Service Provider Interfaces" (SPIs). Doing so will allow **MoltenVK** to extend its functionality by using certain private _Metal_ API calls, but it will also disqualify the app from being distributed via _Apple_ App Stores. To do so, when building **MoltenVK**, set the build setting `MVK_USE_METAL_PRIVATE_API=1`. This build setting can be set in the `MoltenVK.xcodeproj` *Xcode* project, or it can be included in any of the `make` command-line build commands [mentioned above](#command_line_build). Functionality added with `MVK_USE_METAL_PRIVATE_API` enabled includes: - `VkPhysicalDeviceFeatures::wideLines` - `VkPhysicalDeviceFeatures::logicOp` - `VkGraphicsPipelineRasterizationCreateInfo::sampleMask`, using `MTLRenderPipelineDescriptor.sampleMask` instead of emulating it in the fragment shader ### Install **MoltenVK** to Replace the _Vulkan SDK_ `libMoltenVK.dylib` To replace the version of the **MoltenVK** installed on _macOS_ via the *[Vulkan SDK](https://vulkan.lunarg.com/sdk/home)* standard install process, perform the following steps: 1. Build a _macOS_ version of **MoltenVK**, as described [above](#building). The default config for command-line **MoltenVK** build has verbose logging info turned on. If you want **MoltenVK** to log like the original _Vulkan SDK_ install, use this command when building **MoltenVK**: ```bash $ make macos MVK_CONFIG_LOG_LEVEL=1 ``` 2. From a command line terminal, execute the following command: ```bash $ sudo make install ``` This will copy your latest _macOS_ build of **MoltenVK** into `/usr/local/lib/libMoltenVK.dylib`, overwriting the file installed by the _Vulkan SDK_ install process. Running **MoltenVK** Demo Applications -------------------------------------- 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* support on *macOS*, *iOS*, and *tvOS* by investigating and running the demo application that is included in **MoltenVK**. The **MoltenVK** _Cube_ demo app is located in the `Demos` folder. The demo app is available as an *Xcode* project. To review and run the included demo app, open the `Demos/Demos.xcworkspace` workspace in *Xcode*. Please read the [`Demos/README.md`](Demos/README.md) document for a description and instructions for running the included *Cube* demo app, and for external links to more sophisticated demo applications that can be run on **MoltenVK**. 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**](#building) section, follow the instructions in the Installation section of the [`Docs/MoltenVK_Runtime_UserGuide.md`](Docs/MoltenVK_Runtime_UserGuide.md#install) document in the `Docs` directory, to link the **MoltenVK** libraries and frameworks 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 an implementation of a *Vulkan 1.4* subset that runs on *macOS*, *iOS*, *tvOS*, and *visionOS* 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 1.4* specification, and maximally performant. Such compliance and performance is inherently affected by the capability available through *Metal*, as the native graphics driver on *macOS*, *iOS*, *tvOS*, and *visionOS* platforms. *Vulkan* compliance may fall into one of the following categories: - Direct mapping between *Vulkan* capabilities and *Metal* capabilities. Within **MoltenVK**, the vast majority of *Vulkan* capability is the result of this type of direct mapping. - 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. - 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 [`MoltenVK_Runtime_UserGuide.md`](Docs/MoltenVK_Runtime_UserGuide.md#limitations) document in the `Docs` directory. The **MoltenVK** development team welcomes you to [post Issues](https://github.com/KhronosGroup/MoltenVK/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*](https://www.khronos.org/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*, *iOS*, *tvOS*, and *visionOS*, where a native *Vulkan* driver is not available. Getting Support ---------------- - If you have a question about using **MoltenVK**, you can ask it in [*MoltenVK Discussions*](https://github.com/KhronosGroup/MoltenVK/discussions). This forum is monitored by **MoltenVK** contributors and users. - If you encounter an issue with the behavior of **MoltenVK**, or want to request an enhancement, you can report it in the [*MoltenVK Issues List*](https://github.com/KhronosGroup/MoltenVK/issues). - If you encounter an issue with the *Vulkan SDK*, including the *Validation Layers*, you can report it in the [*Vulkan SDK Issues List*](https://vulkan.lunarg.com/issue/home). - If you explore **MoltenVK** and determine that it does not meet your requirements at this time, we would appreciate hearing why that is so, in [*MoltenVK Discussions*](https://github.com/KhronosGroup/MoltenVK/discussions). The goal of **MoltenVK** is to increase the value of *Vulkan* as a true cross-platform ecosystem, by providing *Vulkan* on *Apple* platforms. Hearing why this is currently not working for you will help us in that goal. 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](https://github.com/KhronosGroup/MoltenVK/pulls) to this repository. The first time you do this, you will be asked to agree to the **MoltenVK** [Contributor License Agreement](https://cla-assistant.io/KhronosGroup/MoltenVK). ### 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. ### *Vulkan* Validation Despite running on top of *Metal*, **MoltenVK** operates as a *Vulkan* core layer. As such, as per the error handling guidelines of the [*Vulkan* specification](https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#fundamentals-errors), **MoltenVK** should not perform *Vulkan* validation. When adding functionality to **MoltenVK**, avoid adding unnecessary validation code. Validation and error generation **_is_** appropriate within **MoltenVK** in cases where **MoltenVK** deviates from behavior defined by the *Vulkan* specification. This most commonly occurs when required behavior cannot be mapped to functionality available within *Metal*. In that situation, it is important to provide feedback to the application developer to that effect, by performing the necessary validation, and reporting an error. Currently, there is some excess *Vulkan* validation and error reporting code within **MoltenVK**, added before this guideline was introduced. You are encouraged to remove such code if you encounter it while performing other **MoltenVK** development. Do not remove validation and error reporting code that is covering a deviation in behavior from the *Vulkan* specification. ### Memory Management *Metal*, and other *Objective-C* objects in *Apple's SDK* frameworks, use reference counting for memory management. As a contributor to **MoltenVK**, when instantiating *Objective-C* objects, it is important that you do not rely on the app providing *autorelease pools* to do memory management for you. Because many *Vulkan* games and apps may be ported from other platforms, they will often not automatically include autorelease pools in their threading models. As a contributor to **MoltenVK**, avoid the use of the *Metal* `autorelease` method, or any object *Metal* creation methods that imply internal use of `autorelease`, (eg- `[NSString stringWithFormat: ]`, etc). Instead, favor object creation methods that return a retained object (eg- `[[NSString alloc] initWithFormat: ]`, etc), and manually track and release those objects. If you need to use autoreleased objects, wrap your code in an `@autoreleasepool {...}` block. ### Code Formatting When contributing code, please honour the code formatting style found in existing **MoltenVK** source code. In future, this will formally be enforced using `clang-format`. --- ## File: Demos/README.md #MoltenVK Demo Projects Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." Table of Contents ----------------- - [*Cube*](#vulkan-tools-cube) - [Khronos Vulkan-Samples](#khronos-vulkan-samples) *Cube* ------ The basic canonical *Cube* sample app from the [*Vulkan-Tools* repository](https://github.com/KhronosGroup/Vulkan-Tools) is included in this **MoltenVK** package. This demo renders a basic textured cube that spins in place. The demo can be found in the `Cube` folder, and in the `Cube` group in the *Xcode Project Navigator* in the `Demos.xcworkspace` *Xcode* workspace. To run this demo, run the `Cube-macOS`, `Cube-iOS`, or `Cube-tvOS` *Scheme* from within *Xcode*. In addition to devices, this demo will also run on an `iOS Simulator` destination. This demo is not supported on a `tvOS Simulator` destination. The `Cube` demo is a simple example of installing **MoltenVK** as a `libMoltenVK.dylib` library that is dynamically linked to the application, and the _Vulkan_ calls all use _Volk_ to dynamically access function pointers, retrieved from **MoltenVK** using `vkGetInstanceProcAddr()` and `vkGetDeviceProcAddr()`. It supports all platforms, including _Mac Catalyst_, _iOSSimulator_ and _tvOS Simulator_. *Khronos Vulkan Samples* ---------------------- *Khronos Group* provides a [repository](https://github.com/KhronosGroup/Vulkan-Samples) containing a full suite of standard *Vulkan* samples that run on **MoltenVK** on *macOS*. --- ## File: Docs/MoltenVK_Configuration_Parameters.md MoltenVK Configuration Parameters ================================= Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." **MoltenVK** provides the ability to configure and optimize **MoltenVK** for your particular application runtime requirements and development-time needs. At runtime, configuration can be helpful in situtations where _Metal_ behavior is different than _Vulkan_ behavior, and the results or performance you receive can depend on how **MoltenVK** works around those differences, which, in turn, may depend on how you are using _Vulkan_. Different apps might benefit differently in this handling. Additional configuration parameters can be helpful at development time by providing you with additional tracing, debugging, and performance measuring capabilities. Each configuration parameter has a *name* and *value*, and can be passed to **MoltenVK** via any of the following mechanisms: - The standard _Vulkan_ `VK_EXT_layer_settings` extension. - Application runtime environment variables. - Build settings at **MoltenVK** build time. Parameter values configured by build settings at **MoltenVK** build time can be overridden by values set by environment variables, which, in turn, can be overridden during `VkInstance` creation via the _Vulkan_ `VK_EXT_layer_settings` extension. Using the `VK_EXT_layer_settings` extension is the preferred mechanism, as it is a standard _Vulkan_ extension, and is supported by the _Vulkan_ loader and layers. When using the `VK_EXT_layer_settings` extension, set `VkLayerSettingEXT::pLayerName` to the value of `kMVKMoltenVKDriverLayerName` found in the `mvk_vulkan.h` header (or simply to `"MoltenVK"`). Using environment variables can be a convinient mechanism to modify configuration parameters during runtime debugging in the field (if the settings are *not* overridden during `VkInstance` creation via the _Vulkan_ `VK_EXT_layer_settings` extension). --------------------------------------- #### MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE ##### Type: Enumeration - `0`: Log repeatedly every number of frames configured by the `MVK_CONFIG_PERFORMANCE_LOGGING_FRAME_COUNT` parameter. - `1`: Log immediately after each performance measurement. - `2`: Log at the end of the `VkDevice` lifetime. This is useful for one-shot apps such as testing frameworks. - `3`: Log at the end of the `VkDevice` lifetime, but continue to accumulate across mulitiple `VkDevices` throughout the app process. This is useful for testing frameworks that create many `VkDevices` serially. ##### Default: `0` If the `MVK_CONFIG_PERFORMANCE_TRACKING` parameter is enabled, this parameter controls when **MoltenVK** should log activity performance events. --------------------------------------- #### MVK_CONFIG_ADVERTISE_EXTENSIONS ##### Type: UInt32 ##### Default: `1` Controls which extensions **MoltenVK** should advertise it supports in `vkEnumerateInstanceExtensionProperties()` and `vkEnumerateDeviceExtensionProperties()`. This can be useful when testing **MoltenVK** against specific limited functionality. The value of this parameter is a `Bitwise-OR` of the following values: - `1`: All supported extensions. - `2`: WSI extensions supported on the platform. - `4`: _Vulkan_ Portability Subset extensions. Any prerequisite extensions are also advertised. If bit `1` is included, all supported extensions will be advertised. A value of zero means no extensions will be advertised. --------------------------------------- #### MVK_CONFIG_API_VERSION_TO_ADVERTISE ##### Type: UInt32 ##### Default: `4210688` (decimal number for `VK_API_VERSION_1_4`) Controls the _Vulkan_ API version that **MoltenVK** should advertise in `vkEnumerateInstanceVersion()`, after **MoltenVK** adds the `VK_HEADER_VERSION` component. Set this value to one of: - `4210688` (decimal number for `VK_API_VERSION_1_4`) - `4206592` (decimal number for `VK_API_VERSION_1_3`) - `4202496` (decimal number for `VK_API_VERSION_1_2`) - `4198400` (decimal number for `VK_API_VERSION_1_1`) - `4194304` (decimal number for `VK_API_VERSION_1_0`) or one of the shorthand versions: - `14` (`VK_API_VERSION_1_4`) - `13` (`VK_API_VERSION_1_3`) - `12` (`VK_API_VERSION_1_2`) - `11` (`VK_API_VERSION_1_1`) - `10` (`VK_API_VERSION_1_0`) The shorthand versions are a user convenience, and **MoltenVK** will convert the shorthand value to the actual Vulkan version value upon setting. --------------------------------------- #### MVK_CONFIG_AUTO_GPU_CAPTURE_OUTPUT_FILE ##### Type: String ##### Default: `""` _(The default value is an empty string)._ If `MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE` is any value other than `0`, this is the path to a file where the automatic GPU capture will be saved. If this parameter is an empty string (the default), automatic GPU capture will be handled by the _Xcode_ user interface. If this parameter is set to a valid file path, the _Xcode_ scheme need not have _Metal_ GPU capture enabled, and in fact the app need not be run under _Xcode_'s control at all. This is useful in case the app cannot be run under _Xcode_'s control. A path starting with '~' can be used to place it in a user's home directory. --------------------------------------- #### MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE ##### Type: Enumeration - `0`: No automatic GPU capture. - `1`: Automatically capture all GPU activity during the lifetime of a `VkDevice`. - `2`: Automatically capture all GPU activity during the rendering and presentation of the first frame. - `3`: Automatically capture all GPU activity while signaled on a temporary named pipe. Automatically begins recording whenever the pipe is not empty, and records as many frames as the pipe contains bytes. ##### Default: `0` Controls whether _Metal_ should run an automatic GPU capture without the user having to trigger it manually via the _Xcode_ user interface, and controls the scope under which that GPU capture will occur. This is useful when trying to capture a one-shot GPU trace, such as when running a _Vulkan_ CTS test case, or for triggering the capture via an IPC on a temporary named pipe. For values `2` and `3`, the queue for which the frames are captured is identifed by the values of the `MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_FAMILY_INDEX` and `MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_INDEX` configuration parameters. For the automatic GPU capture to occur, the environment variable `MTL_CAPTURE_ENABLED` must be enabled, or, if running the app from _Xcode_, the _GPU Frame Capture_ option can be set to _Metal_. To manually trigger a GPU capture via the _Xcode_ user interface, leave this parameter at `0`. --------------------------------------- #### MVK_CONFIG_DEBUG ##### Type: Boolean ##### Default: `0` _(The default value is `1` if **MoltenVK** was built in Debug mode)._ If enabled, debugging capabilities will be enabled, including logging shader code during runtime shader conversion. --------------------------------------- #### MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_FAMILY_INDEX ##### Type: UInt32 ##### Default: `0` The index of the queue family whose presentation submissions will be used as the default GPU Capture Scope, when GPU Capture is active. --------------------------------------- #### MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_INDEX ##### Type: UInt32 ##### Default: `0` The index of the queue, within the queue family identified by the `MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_FAMILY_INDEX` parameter, whose presentation submissions will be used as the default GPU Capture Scope, when GPU Capture is active. --------------------------------------- #### MVK_CONFIG_DISPLAY_WATERMARK ##### Type: Boolean ##### Default: `0` If enabled, a **MoltenVK** logo watermark will be rendered on top of the scene. This can be enabled for publicity during demos. --------------------------------------- #### MVK_CONFIG_FAST_MATH_ENABLED ##### Type: Enumeration - `0`: _Metal_ shaders will never be compiled with the fast math option. - `1`: _Metal_ shaders will always be compiled with the fast math option. - `2`: _Metal_ shaders will be compiled with the fast math option. However, each shader can limit the types of fast-math used, through the `VK_KHR_shader_float_controls2` extension, or by enabling execution capabilities, such as `SignedZeroInfNanPreserve` or `ContractionOff`. ##### Default: `2` Identifies when _Metal_ shaders will be compiled with the _Metal_ fast math option enabled. Shaders compiled with the _Metal_ fast math option enabled perform floating point math significantly faster, but may optimize floating point operations in ways that violate the IEEE 754 standard. Enabling _Metal_ fast math can dramatically improve shader performance, and has little practical effect on the numerical accuracy of most shaders. As such, disabling fast math should be done carefully and deliberately. For most applications, always enabling fast math is the preferred choice. Apps that have specific accuracy and handling needs for particular shaders, may elect to set the value of this property to `2`, which compiles shaders with fast math, but allows each shader to limit the types of fast-math used, as described in the value description above. --------------------------------------- #### MVK_CONFIG_FORCE_LOW_POWER_GPU ##### Type: Boolean ##### Default: `0` Forces **MoltenVK** to only advertise the low-power GPUs, if availble on the device. --------------------------------------- #### MVK_CONFIG_LOG_LEVEL ##### Type: Enumeration - `0`: No logging. - `1`: Log errors only. - `2`: Log errors and warning messages. - `3`: Log errors, warnings and informational messages. - `4`: Log errors, warnings, infos and debug messages. ##### Default: `3` Controls the level of logging performed by **MoltenVK**. --------------------------------------- #### MVK_CONFIG_MAX_ACTIVE_METAL_COMMAND_BUFFERS_PER_QUEUE ##### Type: UInt32 ##### Default: `64` The maximum number of _Metal_ command buffers that can be concurrently active per _Vulkan_ queue. The number of active _Metal_ command buffers required depends on the `MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS` parameter. If `MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS` is set to anything other than `0`, one _Metal_ command buffer is required per _Vulkan_ command buffer, otherwise one _Metal_ command buffer is required per command buffer queue submission, which will typically be significantly less than the number of _Vulkan_ command buffers. --------------------------------------- #### MVK_CONFIG_METAL_COMPILE_TIMEOUT ##### Type: UInt64 ##### Default: `INT64_MAX` The maximum amount of time, in nanoseconds, to wait for a _Metal_ library, function, or pipeline state object to be compiled and created by the _Metal_ compiler. An internal error within the _Metal_ compiler may stall the thread for up to 30 seconds. Setting this value limits that delay to a specified amount of time, allowing shader compilations to fail fast. --------------------------------------- #### MVK_CONFIG_PERFORMANCE_LOGGING_FRAME_COUNT ##### Type: UInt32 ##### Default: `0` If the `MVK_CONFIG_PERFORMANCE_TRACKING` parameter is enabled, and this parameter is non-zero, performance and frame-based statistics will be logged, on a repeating cycle, once per this many frames. If this parameter is zero, or the `MVK_CONFIG_PERFORMANCE_TRACKING` parameter is disabled, no frame-based performance statistics will be logged. --------------------------------------- #### MVK_CONFIG_PERFORMANCE_TRACKING ##### Type: Boolean ##### Default: `0` If enabled, performance statistics, as defined by the `MVKPerformanceStatistics` structure, are collected, and can be retrieved via the private-API `vkGetPerformanceStatisticsMVK()` function. You can also use the `MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE` and `MVK_CONFIG_PERFORMANCE_LOGGING_FRAME_COUNT` parameters to configure when to log the performance statistics collected by this parameter. --------------------------------------- #### MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS ##### Type: Enumeration - `0`: During _Vulkan_ command buffer filling, do not prefill a _Metal_ command buffer for each _Vulkan_ command buffer. A single _Metal_ command buffer will be created and encoded for all the _Vulkan_ command buffers included when `vkQueueSubmit()` is called. **MoltenVK** automatically creates and drains a single _Metal_ object autorelease pool when `vkQueueSubmit()` is called. This is the fastest option, but potentially has the largest memory footprint. - `1`: During _Vulkan_ command buffer filling, encode to the _Metal_ command buffer when `vkEndCommandBuffer()` is called. **MoltenVK** automatically creates and drains a single _Metal_ object autorelease pool when `vkEndCommandBuffer()` is called. This option has the fastest performance, and the largest memory footprint, of the prefilling options using autorelease pools. - `2`: During _Vulkan_ command buffer filling, as each command is submitted to the _Vulkan_ command buffer, immediately encode it to the _Metal_ command buffer, and do not retain any command content in the _Vulkan_ command buffer. **MoltenVK** automatically creates and drains a _Metal_ object autorelease pool for each and every command added to the _Vulkan_ command buffer. This option has the smallest memory footprint, and the slowest performance, of the prefilling options using autorelease pools. - `3`: During _Vulkan_ command buffer filling, as each command is submitted to the _Vulkan_ command buffer, immediately encode it to the _Metal_ command buffer, do not retain any command content in the _Vulkan_ command buffer, and assume the app will ensure that each thread that fills commands into a _Vulkan_ command buffer has a _Metal_ autorelease pool. **MoltenVK** will not create and drain any autorelease pools during encoding. This is the fastest prefilling option, and generally has a small memory footprint, depending on when the app-provided autorelease pool drains. ##### Default: `0` For any value other than `0`, be aware of the following: - One _Metal_ command buffer is required for each _Vulkan_ command buffer. Depending on the number of command buffers that you use, you may also need to change the value of the `MVK_CONFIG_MAX_ACTIVE_METAL_COMMAND_BUFFERS_PER_QUEUE` parameter. - Prefilling of a _Metal_ command buffer will not occur during the filling of secondary command buffers (`VK_COMMAND_BUFFER_LEVEL_SECONDARY`), or for primary command buffers that are intended to be submitted to multiple queues concurrently (`VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT`). - For primary command buffers that are intended to be reused (`VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT` is not set), prefilling will only apply to the first submission. Later submissions of the same command buffer will behave as if this configuration parameter is set to `0`. - If you have recorded commands to a _Vulkan_ command buffer, and then choose to reset that command buffer instead of submitting it, the corresponding prefilled _Metal_ command buffer will still be submitted. This is because _Metal_ command buffers do not support the concept of being reset after being filled. Depending on when and how often you do this, it may cause unexpected visual artifacts and unnecessary GPU load. - This configuration is incompatible with updating descriptors after binding. If any of the _UpdateAfterBind_ feature flags of `VkPhysicalDeviceDescriptorIndexingFeatures` or `VkPhysicalDeviceInlineUniformBlockFeatures` have been enabled, the value of this parameter will be ignored and treated as if it is `0`. --------------------------------------- #### MVK_CONFIG_RESUME_LOST_DEVICE ##### Type: Boolean ##### Default: `0` Controls whether **MoltenVK** should treat a lost `VkDevice` as resumable, unless the corresponding `VkPhysicalDevice` has also been lost. The `VK_ERROR_DEVICE_LOST` error has a broad definitional range, and can mean anything from a GPU hiccup on the current command buffer submission, to a physically removed GPU. In the case where this error does not impact the `VkPhysicalDevice`, _Vulkan_ requires that the app destroy and re-create a new `VkDevice`. However, not all apps (including CTS) respect that requirement, leading to what might be a transient command submission failure causing an unexpected catastrophic app failure. If this parameter is enabled, in the case of a `VK_ERROR_DEVICE_LOST` error that does NOT impact the `VkPhysicalDevice`, **MoltenVK** will log the error, but will not mark the `VkDevice` as lost, allowing the `VkDevice` to continue to be used. If this parameter is disabled, **MoltenVK** will mark the `VkDevice` as lost, and subsequent use of that `VkDevice` will be reduced or prohibited. --------------------------------------- #### MVK_CONFIG_SHADER_COMPRESSION_ALGORITHM ##### Type: Enumeration - `0`: No compression. - `1`: `LZFSE`: Apple proprietary. Good balance of high performance and small compression size, particularly for larger data content. - `2`: `ZLib`: Open cross-platform format. For smaller data content, has better performance and smaller size than `LZFSE`. - `3`: `LZ4`: Fastest performance. Largest compression size. - `4`: `LZMA`: Slowest performance. Smallest compression size, particular with larger content. ##### Default: `0` Controls the type of compression to use on the MSL source code that is stored in memory for use in a pipeline cache. After being converted from SPIR-V, or loaded directly into a `VkShaderModule`, and then compiled into a `MTLLibrary`, the MSL source code is no longer needed for operation, but it is retained so it can be written out as part of a pipeline cache export. When a large number of shaders are loaded, this can consume significant memory. In such a case, this parameter can be used to compress the MSL source code that is awaiting export as part of a pipeline cache. --------------------------------------- #### MVK_CONFIG_SHADER_CONVERSION_FLIP_VERTEX_Y ##### Type: Boolean ##### Default: `1` If enabled, MSL vertex shader code created during runtime shader conversion will flip the Y-axis of each vertex, as the _Vulkan_ Y-axis is the inverse of *OpenGL*. An alternate way to reverse the Y-axis is to employ a negative Y-axis value on the viewport, in which case this parameter can be disabled. --------------------------------------- #### MVK_CONFIG_SHADER_DUMP_DIR ##### Type: String ##### Default: `""` _(The default value is an empty string)._ If not empty, **MoltenVK** will dump all SPIR-V shaders, compiled MSL shaders, and pipeline shader lists to the given directory. The directory will be non-recursively created if it doesn't already exist. --------------------------------------- #### MVK_CONFIG_SHADER_LOG_ESTIMATED_GLSL ##### Type: Boolean ##### Default: `0` If the `MVK_CONFIG_DEBUG` parameter is enabled, and this parameter is enabled, when SPIR-V code is converted to MSL, an estimate of the equivalent GLSL shader will be logged. --------------------------------------- #### MVK_CONFIG_SHOULD_MAXIMIZE_CONCURRENT_COMPILATION ##### Type: Boolean ##### Default: `0` Maximize the concurrent executing compilation tasks. To have effect, this parameter requires _macOS 13.3+_, and has no effect on _iOS_ or _tvOS_. --------------------------------------- #### MVK_CONFIG_SPECIALIZED_QUEUE_FAMILIES ##### Type: Boolean ##### Default: `0` _Metal_ does not distinguish functionality between queues, which would normally mean only a single general-purpose queue family with multiple queues is needed. However, _Vulkan_ associates command buffers with a queue family, whereas _Metal_ associates command buffers with a specific _Metal_ queue. In order to allow a _Metal_ command buffer to be prefilled before it is formally submitted to a _Vulkan_ queue, each _Vulkan_ queue family can support only a single _Metal_ queue. As a result, in order to provide parallel queue operations, **MoltenVK** provides multiple queue families, each with a single queue. If this parameter is disabled, all queue families will be advertised as having general-purpose graphics + compute + transfer functionality, which is how the actual _Metal_ queues behave. If this parameter is enabled, one queue family will be advertised as having general-purpose graphics + compute + transfer functionality, and the remaining queue families will be advertised as having specialized graphics *or* compute *or* transfer functionality, to make it easier for some apps to select a queue family with the appropriate requirements. --------------------------------------- #### MVK_CONFIG_SWAPCHAIN_MIN_MAG_FILTER_USE_NEAREST ##### Type: Boolean ##### Default: `1` If enabled, swapchain images will use simple _Nearest_ sampling when minifying or magnifying the swapchain image to fit a physical display surface. If disabled, swapchain images will use _Linear_ sampling when magnifying the swapchain image to fit a physical display surface. Enabling this setting avoids smearing effects when swapchain images are simple interger multiples of display pixels (eg- _macOS Retina_, and typical of graphics apps and games), but may cause aliasing effects when using non-integer display scaling. --------------------------------------- #### MVK_CONFIG_SWITCH_SYSTEM_GPU ##### Type: Boolean ##### Default: `1` If enabled, when the app creates a `VkDevice` from a `VkPhysicalDevice` (GPU) that is neither headless nor low-power, and is different than the GPU used by the windowing system, the windowing system will be forced to switch to use the GPU selected by the _Vulkan_ app. When the _Vulkan_ app is ended, the windowing system will automatically switch back to using the previous GPU, depending on the usage requirements of other running apps. If disabled, the _Vulkan_ app will render using its selected GPU, and if the windowing system uses a different GPU, the windowing system compositor will automatically copy framebuffer content from the app GPU to the windowing system GPU. The value of this parmeter has no effect on systems with a single GPU, or when the _Vulkan_ app creates a `VkDevice` from a low-power or headless `VkPhysicalDevice` (GPU). Switching the windowing system GPU to match the _Vulkan_ app GPU maximizes app performance, because it avoids the windowing system compositor from having to copy framebuffer content between GPUs on each rendered frame. However, doing so forces the entire system to potentially switch to using a GPU that may consume more power while the app is running. Some _Vulkan_ apps may want to render using a high-power GPU, but leave it up to the system window compositor to determine how best to blend content with the windowing system, and as a result, may want to disable this parameter. --------------------------------------- #### MVK_CONFIG_SYNCHRONOUS_QUEUE_SUBMITS ##### Type: Boolean ##### Default: `1` If enabled, queue command submissions `vkQueueSubmit()` and `vkQueuePresentKHR()` will be processed on the thread that called the submission function. If disabled, processing will be dispatched to a GCD `dispatch_queue` whose priority is determined by `VkDeviceQueueCreateInfo::pQueuePriorities` during `vkCreateDevice()`. --------------------------------------- #### MVK_CONFIG_TEXTURE_1D_AS_2D ##### Type: Boolean ##### Default: `1` Controls whether **MoltenVK** should use a _Metal_ 2D texture with a height of 1 for a _Vulkan_ 1D image, or use a native _Metal_ 1D texture. _Metal_ imposes significant restrictions on native 1D textures, including not being renderable, clearable, or permitting mipmaps. Using a _Metal_ 2D texture allows _Vulkan_ 1D textures to support this additional functionality. --------------------------------------- #### MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA ##### Type: Float32 ##### Default: `1.0` This parameter is ignored on Apple Silicon (Apple GPU) devices. Non-Apple GPUs can have a dynamic timestamp period, which varies over time according to GPU workload. Depending on how often the app samples the `VkPhysicalDeviceLimits::timestampPeriod` value using `vkGetPhysicalDeviceProperties()`, the app may want up-to-date, but potentially volatile values, or it may find average values more useful. The value of this parameter sets the alpha `(A)` value of a simple lowpass filter on the `timestampPeriod` value, of the form: TPout = (1 - A)TPout + (A * TPin) The alpha value can be set to a float between `0.0` and `1.0`. Values of alpha closer to `0.0` cause the value of `timestampPeriod` to vary slowly over time and be less volatile, and values of alpha closer to `1.0` cause the value of `timestampPeriod` to vary quickly and be more volatile. Apps that query the `timestampPeriod` value infrequently will prefer low volatility, whereas apps that query frequently may prefer higher volatility, to track more recent changes. --------------------------------------- #### MVK_CONFIG_TRACE_VULKAN_CALLS ##### Type: Enumeration - `0`: No _Vulkan_ call logging. - `1`: Log the name of each _Vulkan_ call when the call is entered. - `2`: Log the name and thread ID of each _Vulkan_ call when the call is entered. - `3`: Log the name of each _Vulkan_ call when the call is entered and exited. This effectively brackets any other logging activity within the scope of the _Vulkan_ call. - `4`: Log the name and thread ID of each _Vulkan_ call when the call is entered, and name when exited. This effectively brackets any other logging activity within the scope of the _Vulkan_ call. - `5`: Same as `3`, plus logs the time spent inside the _Vulkan_ function. - `6`: Same as `4`, plus logs the time spent inside the _Vulkan_ function. ##### Default: `0` Controls the information **MoltenVK** logs for each _Vulkan_ call made by the application. --------------------------------------- #### MVK_CONFIG_USE_COMMAND_POOLING ##### Type: Boolean ##### Default: `1` Controls whether **MoltenVK** should use pools to manage memory used when adding commands to command buffers. If this setting is enabled, **MoltenVK** will use a pool to hold command resources for reuse during command execution. If this setting is disabled, command memory is allocated and destroyed each time a command is executed. This is a classic time-space trade off. When command pooling is active, the memory in the pool can be cleared via a call to the `vkTrimCommandPoolKHR()` command. --------------------------------------- #### MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS ##### Type: Boolean ##### Default: `1` Controls whether **MoltenVK** should use _Metal_ argument buffers for resources defined in descriptor sets, if _Metal_ argument buffers are supported on the platform. Using _Metal_ argument buffers dramatically increases the number of buffers, textures and samplers that can be bound to a pipeline shader, and in most cases improves performance. --------------------------------------- #### MVK_CONFIG_USE_METAL_PRIVATE_API ##### Type: Boolean ##### Default: Value of `MVK_USE_METAL_PRIVATE_API` If enabled, **MoltenVK** will _use_ private interfaces exposed by _Metal_ to implement _Vulkan_ features that are difficult to support otherwise. Unlike `MVK_USE_METAL_PRIVATE_API`, this setting may be overridden at run time. This option is not available unless **MoltenVK** was built with `MVK_USE_METAL_PRIVATE_API` set to `1`. --------------------------------------- #### MVK_CONFIG_USE_MTLHEAP ##### Type: Enumeration - `0`: Do not use `MTLHeap` for allocating resources. - `1`: Use `MTLHeap` for allocating resources, where safe to do so. On AMD GPUs, this is the same as `0`, due to potential challenges with `MTLHeap` usage on those platforms. On other GPUs this is the same as `2`. - `2`: Use `MTLHeap` for allocating resources. ##### Default: `1` Controls whether **MoltenVK** should use `MTLHeap` for allocating textures and buffers from device memory. If this setting is active, **MoltenVK** will allocate a placement `MTLHeap` for each `VkDeviceMemory` instance, and allocate textures and buffers from that placement heap. If this parameter is not active, **MoltenVK** will allocate textures and buffers from general device memory. Vulkan extension `VK_EXT_image_2d_view_of_3d` requires this parameter to be active, to allow aliasing of texture memory between the 3D image and the 2D view. `VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT` also requires this parameter to be active, to allow aliasing of texture memory between the compressed image and the uncompressed view. Note that this is only compatible with Apple GPUs. To force `MTLHeap` to be used on AMD GPUs, set this parameter to `2`. To disable the use of `MTLHeap` on any GPU, set this parameter to `0`. --------------------------------------- #### MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE ##### Type: Enumeration - `0`: Limit _Vulkan_ to a single queue, with no explicit semaphore synchronization, and use _Metal's_ implicit guarantees that all operations submitted to a queue will give the same result as if they had been run in submission order. - `1`: Use _Metal_ events (`MTLEvent`) when available on the platform, and where safe. This will revert to the same as `0` on some _NVIDIA_ GPUs and _Rosetta2_, due to potential challenges with `MTLEvents` on those platforms, or in older environments where `MTLEvents` are not supported. - `2`: Always use _Metal_ events (`MTLEvent`) when available on the platform. This will revert to the same as `0` in older environments where `MTLEvents` are not supported. - `3`: Use CPU callbacks upon GPU submission completion. This is the slowest technique, but allows multiple queues, compared to `0`. ##### Default: `1` Determines the style used to implement _Vulkan_ semaphore (`VkSemaphore`) functionality in _Metal_. In the special case of `VK_SEMAPHORE_TYPE_TIMELINE` semaphores, **MoltenVK** will always use `MTLSharedEvent`, regardless of the value of this parameter. --------------------------------------- #### MVK_CONFIG_LIVE_CHECK_ALL_RESOURCES ##### Type: Boolean ##### Default: `0` Makes MoltenVK treat all descriptors as if they had `VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT` set. Versions of MoltenVK with this flag are less forgiving of applications that bind descriptors that point to destroyed objects, so this option can be used to temporarily work around any breakage that may have caused. --- ## File: Docs/MoltenVK_Runtime_UserGuide.md MoltenVK Runtime User Guide =========================== Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." Table of Contents ----------------- - [About This Document](#about_this) - [About **MoltenVK**](#about_moltenvk) - [Installing **MoltenVK** in Your *Vulkan* Application](#install) - [Install *MoltenVK* as a Universal `XCFramework`](#install_xcfwk) - [Install *MoltenVK* as a Dynamic Library on _macOS_](#install_dylib) - [Optionally Link to Required System Libraries](#system_libs) - [Build and Runtime Requirements](#requirements) - [Interacting with the **MoltenVK** Runtime](#interaction) - [MoltenVK Header Files](#moltenvk_headers) - [Configuring MoltenVK](#moltenvk_config) - [Debugging Your **MoltenVK** Application using _Metal Frame Capture_](#gpu-capture) - [*Metal Shading Language* Shaders](#shaders) - [Troubleshooting Shader Conversion](#spv_vs_msl) - [Performance Considerations](#performance) - [Shader Loading Time](#shader_load_time) - [Swapchains](#swapchains) - [Timestamping](#timestamping) - [Xcode Configuration](#xcode_config) - [Metal System Trace Tool](#trace_tool) - [Known **MoltenVK** Limitations](#limitations) About This Document ------------------- This document describes how to integrate the **MoltenVK** runtime distribution package into a game or 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 distribution package, see the main [`README.md`](../README.md) document in the `MoltenVK` repository. About **MoltenVK** ------------------ **MoltenVK** is a layered implementation of [*Vulkan 1.4*](https://www.khronos.org/vulkan) graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) graphics and compute framework on *macOS*, *iOS*, and *tvOS*. **MoltenVK** allows you to use *Vulkan* graphics and compute functionality to develop modern, cross-platform, high-performance graphical games and applications, and to run them across many platforms, including *macOS*, *iOS*, *tvOS*, *Simulators*, and *Mac Catalyst*. *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders to their *MSL* equivalents. 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 undocumented API calls or features unless configured to do so at build time, so your app will be compatible with all standard distribution channels, including *Apple's App Store*. Installing **MoltenVK** in Your *Vulkan* Application ---------------------------------------------------- Installation of **MoltenVK** in your application is straightforward and easy! Depending on your build and deployment needs, you can link **MoltenVK** to your application either as either a static or dynamic universal `XCFramework`, or on _macOS_, as a *dynamic library* (`.dylib`). ### Install *MoltenVK* as a Universal `XCFramework` > ***Note:*** *Xcode 14* introduced a new static linkage model that is not compatible with previous versions of *Xcode*. If you link to a `MoltenVK.xcframework` that was built with *Xcode 14* or later, also use *Xcode 14* or later to link it to your app or game. > > If you need to use *Xcode 13* or earlier to link `MoltenVK.xcframework` to your app or game, first [build](../README.md#building) **MoltenVK** with *Xcode 13* or earlier. > > Or, if you want to use *Xcode 14* or later to [build](../README.md#building) **MoltenVK**, in order to be able to use the latest *Metal* capabilities, but need to use *Xcode 13* or earlier to link `MoltenVK.xcframework` to your app or game, first add the value `-fno-objc-msgsend-selector-stubs` to the `OTHER_CFLAGS` *Xcode* build setting in the `MoltenVK.xcodeproj` and `MoltenVKShaderConverter.xcodeproj` *Xcode* projects, [build](../README.md#building) **MoltenVK** with *Xcode 14* or later, and then link `MoltenVK.xcframework`to your app or game using *Xcode 13* or earlier. To link **MoltenVK** to your application as either a static or dynamic `XCFramework`, follow these steps: 1. Open your application in *Xcode* and select your application's target in the *Project Navigator* panel. 2. Open the *Build Settings* tab. 1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting, add an entry that points to the `MoltenVK/include` folder. 2. _(**Note:** This step is not required if linking to the static XCFramework)_ If linking to the _dynamic XCFramework_, in the **Runpath Search Paths** (aka `LD_RUNPATH_SEARCH_PATHS`) setting, add entries that match where the framework will be located in your runtime environment. If the dynamic library is to be embedded within your application, you would typically add one or both of the following entries for a _macOS_ platform target: ``` @executable_path/../Frameworks @executable_path/../Frameworks/MoltenVK.framework ``` or for a platform target other than _macOS_ add one or both of the following entries: ``` @executable_path/Frameworks @executable_path/Frameworks/MoltenVK.framework ``` `MoltenVK.framework` is internally configured to be located at `@rpath/MoltenVK.framework/MoltenVK`. 3. Open the *General* tab and drag either `Package/Latest/MoltenVK/static/MoltenVK.xcframework` or `Package/Latest/MoltenVK/dynamic/MoltenVK.xcframework` to the *Embed Frameworks* (sometimes labeled *Frameworks, Libraries, and Embedded Content*) list, and ensure the _Embed & Sign_ options is selected. ### Install *MoltenVK* as a Dynamic Library on _macOS_ To link **MoltenVK** to your _macOS_ application as a dynamic library (`.dylib`), follow these steps: 1. Open your application in *Xcode* and select your application's target in the *Project Navigator* panel. 2. Open the *Build Settings* tab. 1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting, add an entry that points to the `MoltenVK/include` folder. 2. In the **Runpath Search Paths** (aka `LD_RUNPATH_SEARCH_PATHS`) setting, add an entry that matches where the dynamic library will be located in your runtime environment. If the dynamic library is to be embedded within your application, you would typically set this to `@executable_path/../Frameworks`. The `libMoltenVK.dylib` library in `MoltenVK.framework` is internally configured to be located at `@rpath/libMoltenVK.dylib`. 3. Open the *General* tab and drag `Package/Latest/MoltenVK/dynamic/dylib/macOS/libMoltenVK.dylib` to the *Embed Frameworks* (sometimes labeled *Frameworks, Libraries, and Embedded Content*) list, and ensure the _Embed & Sign_ options is selected. ### Optionally Link to Required System Libraries Open the *Build Phases* tab and open the *Link Binary With Libraries* list. 1. If your application does **_not_** use use `C++`, click the **+** button, and add `libc++.tbd` by selecting it from the list of system frameworks. This is needed because **MoltenVK** uses `C++` system libraries internally. 2. If you do **_not_** have the **Link Frameworks Automatically** (aka `CLANG_MODULES_AUTOLINK`) and **Enable Modules (C and Objective-C)** (aka `CLANG_ENABLE_MODULES`) settings enabled, click the **+** button, and add the following items by selecting them from the list of system frameworks: - `Metal.framework` - `Foundation.framework`. - `QuartzCore.framework` - `CoreGraphics.framework` - `IOSurface.framework` - `IOKit.framework` (*macOS*) - `AppKit.framework` (*macOS*) - `UIKit.framework` (*iOS* or *tvOS*) ### Build and Runtime Requirements **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*. Once built, your app integrating 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 12.0*, *iOS 15*, or *tvOS 15*. - This support policy is based on the earliest deployment target [officially supported](https://developer.apple.com/support/xcode/) by the latest version of Xcode. - 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). - Information on *iOS* devices that are compatible with *Metal* can be found in [this article](https://developer.apple.com/library/content/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/HardwareGPUInformation/HardwareGPUInformation.html). When a *Metal* app is running from *Xcode*, the default ***Scheme*** settings may 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](https://developer.apple.com/library/ios/documentation/Miscellaneous/Conceptual/MetalProgrammingGuide/Dev-Technique/Dev-Technique.html#//apple_ref/doc/uid/TP40014221-CH8-SW3) section of Apple's *Metal Programming Guide* documentation. 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 other *Vulkan* implementations. **MoltenVK** 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 In addition to core *Vulkan* functionality, **MoltenVK** also supports the following *Vulkan* extensions: - `VK_KHR_16bit_storage` - `VK_KHR_8bit_storage` - `VK_KHR_bind_memory2` - `VK_KHR_buffer_device_address` - *Requires GPU Tier 2 argument buffers support.* - `VK_KHR_calibrated_timestamp` - *Requires Metal 2.2.* - `VK_KHR_copy_commands2` - `VK_KHR_create_renderpass2` - `VK_KHR_dedicated_allocation` - `VK_KHR_deferred_host_operations` - `VK_KHR_depth_stencil_resolve` - `VK_KHR_descriptor_update_template` - `VK_KHR_device_group` - `VK_KHR_device_group_creation` - `VK_KHR_draw_indirect_count` - `VK_KHR_driver_properties` - `VK_KHR_dynamic_rendering` - `VK_KHR_dynamic_rendering_local_read` - `VK_KHR_external_fence` - `VK_KHR_external_fence_capabilities` - `VK_KHR_external_memory` - `VK_KHR_external_memory_capabilities` - `VK_KHR_external_semaphore` - `VK_KHR_external_semaphore_capabilities` - `VK_KHR_format_feature_flags2` - `VK_KHR_fragment_shader_barycentric` - *Requires Metal 2.2 on Mac or Metal 2.3 on iOS.* - `VK_KHR_get_memory_requirements2` - `VK_KHR_get_physical_device_properties2` - `VK_KHR_get_surface_capabilities2` - `VK_KHR_global_priority` - `VK_KHR_image_format_list` - `VK_KHR_imageless_framebuffer` - `VK_KHR_incremental_present` - `VK_KHR_index_type_uint8` - `VK_KHR_line_rasterization` - `VK_KHR_load_store_op_none` - `VK_KHR_maintenance1` - `VK_KHR_maintenance2` - `VK_KHR_maintenance3` - `VK_KHR_maintenance4` - `VK_KHR_maintenance5` - `VK_KHR_maintenance6` - `VK_KHR_maintenance7` - `VK_KHR_maintenance8` - `VK_KHR_maintenance9` - `VK_KHR_map_memory2` - `VK_KHR_multiview` - `VK_KHR_portability_subset` - `VK_KHR_present_id` - `VK_KHR_present_id2` - `VK_KHR_present_wait` - `VK_KHR_present_wait2` - `VK_KHR_push_descriptor` - `VK_KHR_relaxed_block_layout` - `VK_KHR_robustness2` - `VK_KHR_sampler_mirror_clamp_to_edge` - *Requires a Mac GPU or Apple family 7 GPU.* - `VK_KHR_sampler_ycbcr_conversion` - `VK_KHR_separate_depth_stencil_layouts` - `VK_KHR_shader_atomic_int64` - `VK_KHR_shader_draw_parameters` - `VK_KHR_shader_expect_assume` - `VK_KHR_shader_float_controls` - `VK_KHR_shader_float_controls2` - `VK_KHR_shader_float16_int8` - `VK_KHR_shader_fma` - `VK_KHR_shader_integer_dot_product` - `VK_KHR_shader_maximal_reconvergence` - `VK_KHR_shader_non_semantic_info` - `VK_KHR_shader_quad_control` - `VK_KHR_shader_relaxed_extended_instruction` - `VK_KHR_shader_subgroup_extended_types` - *Requires Metal 2.1 on Mac or Metal 2.2 and Apple family 4 on iOS.* - `VK_KHR_shader_subgroup_rotate` - *Requires Metal 2.1 on Mac or Metal 2.2 and Apple family 4 on iOS.* - `VK_KHR_shader_subgroup_uniform_control_flow` - `VK_KHR_shader_terminate_invocation` - `VK_KHR_spirv_1_4` - `VK_KHR_storage_buffer_storage_class` - `VK_KHR_surface` - `VK_KHR_surface_maintenance1` - `VK_KHR_surface_protected_capabilities` - `VK_KHR_swapchain` - `VK_KHR_swapchain_maintenance1` - `VK_KHR_swapchain_mutable_format` - `VK_KHR_synchronization2` - `VK_KHR_timeline_semaphore` - `VK_KHR_uniform_buffer_standard_layout` - `VK_KHR_variable_pointers` - `VK_KHR_vertex_attribute_divisor` - `VK_KHR_vulkan_memory_model` - `VK_KHR_zero_initialize_workgroup_memory` - `VK_EXT_4444_formats` - *Requires 16-bit formats and either native texture swizzling or manual swizzling to be enabled.* - `VK_EXT_buffer_device_address` - *Requires GPU Tier 2 argument buffers support.* - `VK_EXT_calibrated_timestamps` - *Requires Metal 2.2.* - `VK_EXT_debug_marker` - `VK_EXT_debug_report` - `VK_EXT_debug_utils` - `VK_EXT_depth_clip_control` - `VK_EXT_descriptor_indexing` - *Initial release limited to Metal Tier 1: 96/128 textures, 16 samplers, except macOS 11.0 (Big Sur) or later, or on older versions of macOS using an Intel GPU, and if Metal argument buffers enabled in config.* - `VK_EXT_extended_dynamic_state` - *Requires Metal 3.1 for `VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE`.* - `VK_EXT_extended_dynamic_state2` - *Primitive restart is always enabled, as Metal does not support disabling it (`VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT`).* - `VK_EXT_extended_dynamic_state3` - *Metal does not support `VK_POLYGON_MODE_POINT`* - `VK_EXT_external_memory_host` - `VK_EXT_external_memory_metal` - `VK_EXT_fragment_shader_interlock` - *Requires Metal 2.0 and Raster Order Groups.* - `VK_EXT_global_priority` - `VK_EXT_global_priority_query` - `VK_EXT_hdr_metadata` - *macOS only.* - `VK_EXT_headless_surface` - `VK_EXT_host_image_copy` - `VK_EXT_host_query_reset` - `VK_EXT_image_2d_view_of_3d` - *Requires `MVK_CONFIG_USE_MTLHEAP` to be active.* - `VK_EXT_image_robustness` - `VK_EXT_index_type_uint8` - `VK_EXT_inline_uniform_block` - `VK_EXT_layer_settings` - `VK_EXT_legacy_dithering` - *Requires a build of MoltenVK with `MVK_USE_METAL_PRIVATE_API` enabled.* - `VK_EXT_line_rasterization` - `VK_EXT_load_store_op_none` - `VK_EXT_memory_budget` - *Requires Metal 2.0.* - `VK_EXT_metal_objects` - `VK_EXT_metal_surface` - `VK_EXT_multi_draw` - `VK_EXT_nested_command_buffer` - `VK_EXT_non_seamless_cube_map` - *Requires a build of MoltenVK with `MVK_USE_METAL_PRIVATE_API` enabled.* - `VK_EXT_pipeline_creation_cache_control` - `VK_EXT_pipeline_creation_feedback` - `VK_EXT_pipeline_robustness` - `VK_EXT_post_depth_coverage` - *iOS and macOS, requires family 4 (A11) or better Apple GPU.* - `VK_EXT_primitive_topology_list_restart` - *Requires a build of MoltenVK with `MVK_USE_METAL_PRIVATE_API` enabled.* - `VK_EXT_private_data ` - `VK_EXT_provoking_vertex` - *Requires a build of MoltenVK with `MVK_USE_METAL_PRIVATE_API` enabled.* - `VK_EXT_robustness2` - `VK_EXT_sample_locations` - `VK_EXT_sampler_filter_minmax` - *Requires Apple GPU family 10 and macOS 26 or iOS 26.* - `VK_EXT_scalar_block_layout` - `VK_EXT_separate_stencil_usage` - `VK_EXT_shader_atomic_float` - *Requires Metal 3.0.* - `VK_EXT_shader_demote_to_helper_invocation` - *Requires Metal Shading Language 2.3.* - `VK_EXT_shader_stencil_export` - *Requires Mac GPU family 2 or iOS GPU family 5.* - `VK_EXT_shader_subgroup_ballot` - *Requires Mac GPU family 2 or Apple GPU family 4.* - `VK_EXT_shader_subgroup_vote` - *Requires Mac GPU family 2 or Apple GPU family 4.* - `VK_EXT_shader_viewport_index_layer` - `VK_EXT_subgroup_size_control` - *Requires Metal 2.1 on Mac or Metal 2.2 and Apple family 4 on iOS.* - `VK_EXT_surface_maintenance1` - `VK_EXT_swapchain_colorspace` - `VK_EXT_swapchain_maintenance1` - `VK_EXT_texel_buffer_alignment` - *Requires Metal 2.0.* - `VK_EXT_texture_compression_astc_hdr` - *iOS and macOS, requires family 6 (A13) or better Apple GPU.* - `VK_EXT_tooling_info` - `VK_EXT_vertex_attribute_divisor` - `VK_EXT_ycbcr_2plane_444_formats` - `VK_AMD_gpu_shader_half_float` - `VK_AMD_negative_viewport_height` - `VK_AMD_shader_image_load_store_lod` - *Requires Apple GPU.* - `VK_AMD_shader_trinary_minmax` - *Requires Metal 2.1.* - `VK_GOOGLE_display_timing` - `VK_IMG_format_pvrtc` - *Requires Apple GPU.* - `VK_INTEL_shader_integer_functions2` - `VK_MVK_ios_surface` - *Obsolete. Use `VK_EXT_metal_surface` instead.* - `VK_MVK_macos_surface` - *Obsolete. Use `VK_EXT_metal_surface` instead.* - `VK_NV_fragment_shader_barycentric` - *Requires Metal 2.2 on Mac or Metal 2.3 on iOS.* In order to visibly display your content on *macOS*, *iOS*, or *tvOS*, you must enable the `VK_EXT_metal_surface` extension, and use the function defined in that extension to create a *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 the `mvk_vulkan.h` file below for a convenient way to enable this extension automatically. When creating a `CAMetalLayer` to underpin the *Vulkan* surface to render to, it is strongly recommended that you ensure the `delegate` of the `CAMetalLayer` is the `NSView/UIView` in which the layer is contained, to ensure correct and optimized *Vulkan* swapchain and refresh timing behavior across multiple display screens that might have different properties. The view will automatically be the `delegate` of the layer when the view creates the `CAMetalLayer`, as per Apple's documentation: >If the layer object was created by a view, the view typically assigns itself as the layer’s delegate automatically, and you should not change that relationship. For layers you create yourself, you can assign a delegate object and use that object to provide the contents of the layer dynamically and perform other tasks. But in the case where you create the `CAMetalLayer` yourself and assign it to the view, you should also assign the view as the `delegate` of the layer. Because **MoltenVK** supports the `VK_KHR_portability_subset` extension, when using the *Vulkan Loader* from the *Vulkan SDK* to run **MoltenVK** on *macOS*, the *Vulkan Loader* will only include **MoltenVK** `VkPhysicalDevices` in the list returned by `vkEnumeratePhysicalDevices()` if the `VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR` flag is enabled in `vkCreateInstance()`. See the description of the `VK_KHR_portability_enumeration` extension in the *Vulkan* specification for more information about the use of the `VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR` flag. ### MoltenVK Header Files **MoltenVK** provides additional functionality beyond standard *Vulkan* functionality, to support configuration options and query behaviour that is specific to the **MoltenVK** implementation of *Vulkan* functionality. 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 where `HEADER_FILE` is one of the following: - `mvk_vulkan.h` - This is a convenience header file that loads the `` header file with platform settings to enable the appropriate _Vulkan_ WSI surface and portability extensions. - `mvk_private_api.h` - Contains private structures and functions to query **MoltenVK** about **MoltenVK** version and configuration, runtime performance information, and available _Metal_ capabilities. > _**NOTE:**_ THE FUNCTIONS in `mvk_private_api.h` ARE NOT SUPPORTED BY THE _Vulkan Loader and Layers_, AND CAN ONLY BE USED WHEN **MoltenVK** IS LINKED DIRECTLY TO YOUR APPLICATION. - `mvk_datatypes.h` - Contains helpful functions for converting between *Vulkan* and *Metal* data types. You do not need to use this functionality to use **MoltenVK**, as **MoltenVK** converts between *Vulkan* and *Metal* datatypes automatically (using the functions declared in this header). These functions are exposed in this header as a convienience for your own purposes such as interacting with *Metal* directly, or simply logging data values. ### Configuring MoltenVK **MoltenVK** provides the ability to configure and optimize **MoltenVK** for your particular application runtime requirements and development-time needs. At runtime, configuration can be helpful in situtations where _Metal_ behavior is different than _Vulkan_ behavior, and the results or performance you receive can depend on how **MoltenVK** works around those differences, which, in turn, may depend on how you are using _Vulkan_. Different apps might benefit differently in this handling. Additional configuration parameters can be helpful at development time by providing you with additional tracing, debugging, and performance measuring capabilities. Each configuration parameter has a *name* and *value*, and can be passed to **MoltenVK** via any of the following mechanisms: - The standard _Vulkan_ `VK_EXT_layer_settings` extension. - Application runtime environment variables. - Build settings at **MoltenVK** build time. Parameter values configured by build settings at **MoltenVK** build time can be overridden by values set by environment variables, which, in turn, can be overridden during `VkInstance` creation via the _Vulkan_ `VK_EXT_layer_settings` extension. Using the `VK_EXT_layer_settings` extension is the preferred mechanism, as it is a standard _Vulkan_ extension, and is supported by the _Vulkan_ loader and layers. When using the `VK_EXT_layer_settings` extension, set `VkLayerSettingEXT::pLayerName` to the value of `kMVKMoltenVKDriverLayerName` found in the `mvk_vulkan.h` header (or simply to `"MoltenVK"`). Using environment variables can be a convinient mechanism to modify configuration parameters during runtime debugging in the field (if the settings are *not* overridden during `VkInstance` creation via the _Vulkan_ `VK_EXT_layer_settings` extension). A description of each configuration parameter supported by **MoltenVK** can be found in the [`MoltenVK_Configuration_Parameters.md`](MoltenVK_Configuration_Parameters.md) document in the `Docs` directory. Debugging Your MoltenVK Application using _Metal Frame Capture_ ----------------------------------------------------------------- Since **MoltenVK** translates _Vulkan API_ calls to _Metal_, you can use _Apple's_ [Metal Frame Capture](https://developer.apple.com/documentation/xcode/capturing-a-metal-workload-in-xcode) to help debug your application. You can configure **MoltenVK** to automatically write to a GPU trace file, without manual intervention, by using the following environment variables and configuration parameters: 1. `METAL_CAPTURE_ENABLED=1`, to enable Metal GPU capture. This must be set as an environment variable, or in _Xcode_ as an _Option_ in the _Scheme_ you use to launch your app from _Xcode_. 2. `MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE=n`, this defines the scope of the capture. You can set `n` to: - `0` to disable capturing, - `1` to capture all frames created between the creation of a `VkDevice` to its destruction, or - `2` to capture only the first frame. 3. `MVK_CONFIG_AUTO_GPU_CAPTURE_OUTPUT_FILE=filename.gputrace`, to set where the capture file should be saved to. Note that `filename.gputrace` must not already exist, otherwise the file will not be written, and an error will be logged. Except for `METAL_CAPTURE_ENABLED=1`, the other parameters can be set as configuration parameters, as described in the [Configuring MoltenVK](#moltenvk_config) section above (including as environment variables). The created capture file can then be opened with _Xcode_ for investigation. You do not need to launch your app from _Xcode_ to capture and generate the trace file. *Metal Shading Language* 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** uses **Runtime Shader Conversion** to automatically convert your *SPIR-V* shaders to their *MSL* equivalents, during loading your *SPIR-V* shaders, using the standard *Vulkan* `vkCreateShaderModule()` function. ### 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: - Errors encountered during **Runtime Shader Conversion** are logged to the console. - To help understand conversion issues during **Runtime Shader Conversion**, you can enable logging the *SPIR-V* and *MSL* shader source code during shader conversion, by enabing the `MVK_CONFIG_DEBUG` configuration parameter. See the [*MoltenVK Configuration*](#moltenvk_config) description above. Enabling debug mode in **MoltenVK** includes shader conversion logging, which 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 some 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*. - You are also encouraged to report issues with shader conversion to the [*SPIRV-Cross*](https://github.com/KhronosGroup/SPIRV-Cross/issues) project. **MoltenVK** and **MoltenVKShaderConverter** make use of *SPIRV-Cross* to convert *SPIR-V* shaders to *MSL* shaders. Performance Considerations -------------------------- This section discusses various options for improving performance when using **MoltenVK**. ### Shader Loading Time A number of steps is required to load and compile *SPIR-V* shaders into a form that *Metal* can use. Although the overall process is fast, the slowest step involves converting shaders from *SPIR-V* to *MSL* source code format. If you have a lot of shaders, you can dramatically improve shader loading time by using the standard *Vulkan pipeline cache* feature, to serialize shaders and store them in *MSL* form offline. Loading *MSL* shaders via the pipeline cache serializing mechanism can be significantly faster than converting from *SPIR-V* to *MSL* each time. In *Vulkan*, pipeline cache serialization for offline storage is available through the `vkGetPipelineCacheData()` and `vkCreatePipelineCache()` functions. Loading the pipeline cache from offline storage at app start-up time can dramatically improve both shader loading performance, and performance glitches and hiccups during runtime code if shader loading is performed then. When using pipeline caching, nothing changes about how you load *SPIR-V* shader code. **MoltenVK** automatically detects that the *SPIR-V* was previously converted to *MSL*, and stored offline via the *Vulkan* pipeline cache serialization mechanism, and does not invoke the relatively expensive step of converting the *SPIR-V* to *MSL* again. ### Swapchains *Metal* supports a very small number (3) of concurrent swapchain images. In addition, *Metal* can sometimes hold onto these images during surface presentation. **MoltenVK** supports using either 2 or 3 swapchain images. For best performance, it is recommended that you use 3 swapchain images (triple-buffering), to ensure that at least one swapchain image will be available when you need to render to it. Using 3 swapchain images is particularly important when rendering to a full-screen surface, because in that situation, *Metal* uses its *Direct to Display* feature, and avoids compositing the swapchain image onto a separate composition surface before displaying it. Although *Direct to Display* can improve performance throughput, it also means that *Metal* may hold onto each swapchain image a little longer than when using an internal compositor, which increases the risk that a swapchain image will not be a vailable when you request it, resulting in frame delays and visual stuttering. ### Timestamping On non-Apple GPUs (older Mac devices), the GPU can switch power and performance states as required by usage. This affects the GPU timestamps retrievable through the Vulkan API. As a result, the value of `VkPhysicalDeviceLimits::timestampPeriod` can vary over time. Consider calling `vkGetPhysicalDeviceProperties()`, when needed, and retrieve the current value of `VkPhysicalDeviceLimits::timestampPeriod`, to help you calibrate recent GPU timestamps queried through the Vulkan API. This is not needed on Apple Silicon devices, where all GPU timestamps are always returned as nanoseconds, regardless of variations in power and performance states as the app runs. ### 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](#install) section above. ### Metal System Trace Tool To help you get the best performance from your graphics app, the *Xcode 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**. - See [above](#interaction) for known limitations for specific Vulkan extensions. - Image content in `PVRTC` compressed formats must be loaded directly into a `VkImage` using host-visible memory mapping. Loading via a staging buffer will result in malformed image content. - Pipeline statistics query pool using `VK_QUERY_TYPE_PIPELINE_STATISTICS` is not supported. - Application-controlled memory allocations using `VkAllocationCallbacks` are ignored. - Since **MoltenVK** is an implementation of *Vulkan* functionality, it does not load *Vulkan Layers* on its own. In order to use *Vulkan Layers*, such as the validation layers, use the *Vulkan Loader and Layers* from the *[Vulkan SDK](https://vulkan.lunarg.com/sdk/home)*. Refer to the *Vulkan SDK [Getting Started](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html)* document for more info. --- ## File: Docs/Whats_New.md # What's New in MoltenVK Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." MoltenVK 1.4.3 -------------- Released TBD - Add support for the following extensions: - `VK_EXT_multi_draw` - `VK_EXT_nested_command_buffer` - `VK_EXT_ycbcr_2plane_444_formats` - Fix inconsistent image `memoryTypeBits` when `VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT` is used. - Fix shader stage interface matching of 16-bit floating point variables. MoltenVK 1.4.2 -------------- Released 2026-07-20 - Add support for the following extensions: - `VK_EXT_sampler_filter_minmax` on Apple10 GPUs with macOS 26 or iOS 26 - Add gl_DrawID / DrawIndex support for MacOS. - Add native sampler min/max filtering. - Fix buffer and heap out-of-sync in `initExternalMemory()`. - Fix incorrect varable usage in `MVKImagePlane::getMTLTexture()`. - Fix incorrect placement heap check in `MVKImagePlane::getMTLTexture()`. - Fix device loss when using imported `MTLTexture` objects with Metal argument buffers. - Raise minimum target to _macOS 12.0 / iOS 15.0 / tvOS 15.0_ - Fix desync in primitive restart enable state tracking. - Fix inverted return logic in MVKBitArray::areAnyBitsSet(). - Fix imported MTLTexture residency tracking. - Fix swapchain recreation giving 1x1 drawables. - Fix variable descriptor count query. - Fix channel corruption on Apple Silicon for color RTs used as transfer sources. - Fix behavior of VK_REMAINING_ARRAY_LAYERS with 2D array views of 3D images. - Fix invalidation of cached metal textures - Fix AMD subgroup size (64→32) and disable Intel UHD 630 simdReduction. - Fix incorrect placement heap check in `MVKImagePlane::getMTLTexture()`. - Fix regressions and crashes on Mac 1 (NVIDIA/Intel) GPUs. - Disable 64-bit float control properties. - Disable non-working quad control flow. - Emulate reversed-depth viewports on affected AMD Mac GPUs. - Do not rely on extension enable for vkGetPhysicalDeviceToolPropertiesEXT procaddr. - Do not convert UINT8 indices until draw time. - Do not enable blending when unsupported by format. - Null-check pColorAttachmentInputIndices before reading. - Make imported `MTLBuffer` resident in `MVKDeviceMemory`. - Include Metal constant buffer alignment in argument buffer gpuAlign calculation. - Use max of pointer and constant buf alignments for arg buffer uniform.align field. - Only apply Metal Constant Buffer alignment to Aux Buffers and Combined Textures. - Apply Metal constant buffer alignment padding for each descriptor set. - MVKRenderPass: encode barriers for subpass dependencies. - Occlusion queries: wrap detection uses stale baseline, crashes when visibility buffer starts near end of pass. - Prevent null dereference in MVKPixelFormats. - Improve handling of draw ID buffer binding. - Restore some checks for Mac1 GPUs. - Update copyright notices to year 2026. - Update to latest SPIRV-Cross: - MSL: add `gl_DrawID` (DrawIndex) support for macOS. - MSL: Add reversed depth viewport emulation. - MSL: Fix `subgroupBallotExclusiveBitCount()` is not available for task shader and mesh shader. - MSL: `thread_execution_width` is deprecated as of Metal 3.0 , use `threads_per_simdgroup` instead. - MSL: Add `msl3.0` variant for subgroup builtin. - MSL: Fix handling of variable pointer arguments which are not BDA. - MSL: Fix variable pointer buffer arguments. - MSL: Handle variable pointer argument to SSBO array. - MSL: Fix handling of forced temporary row-major matrices. - MSL: Additional MSL specific keywords(`signed`). - MSL: Deal with std140 layouts when copying arrays between storage class. - MSL: Rewrite std140 struct padding. - MSL: BlockIO in vertex is captured as thread storage. - MSL: Add initial cooperative matrix support. - MSL: Fix ptr-cast prepass and coopmat typed load/store. - MSL: Handle array type writes to builtin clip/cull better. - MSL: Fix some extremely bizarre tess access chain bugs. - MSL: Use pointer expression when dealing with atomics. - Parser: support SPIR-V library modules without OpEntryPoint MoltenVK 1.4.1 -------------- Released 2025-11-24 - Add support for the following extensions: - `VK_KHR_maintenance9` - `VK_KHR_shader_fma` - `VK_KHR_surface_maintenance1` - `VK_KHR_swapchain_maintenance1` - Add support for new features and extensions when using `MVK_USE_METAL_PRIVATE_API`: - Disabling primitive restart - `VK_EXT_legacy_dithering` - `VK_EXT_non_seamless_cube_map` - `VK_EXT_primitive_topology_list_restart` - `VK_EXT_provoking_vertex` - Improved occlusion query support: - Add support for occlusion queries across multiple renderpasses. - Improve performance by accumulating occlusion quieries in parallel, and using untracked buffers to avoid encoder serialization. - New descriptor state tracker implementation to improve performance. - New descriptor set/pool implementation: - The new implementation is less forgiving of applications that don't properly manage the lifetime of their descriptors (and bind them after the objects they point to have been destroyed). Use `MVK_CONFIG_LIVE_CHECK_ALL_RESOURCES=1` to revert any crashes this might cause, or mark potentially-destroyed descriptors with `VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT`. - Add CMake build support. - Added working demo target for VisionOS in Cube Demo. - Raise minimum target to _macOS 11.0 / iOS 14.0 / tvOS 14.0_ - Add support for `VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT`. - Reject image usages whose format features are not supported. - Return `VK_ERROR_OUT_OF_POOL_MEMORY` when running out of descriptor sets. - Make vkGetPhysicalDeviceToolProperties() an instance function. - Enable sample LOD bias for Xcode 26. - Update robustness support levels for different GPU types. - Update max texture dimensions for Apple10 GPU. - Allow host-coherent optimal tiling images on macOS with Apple GPU. - Add Metal4 and Apple10 GPU family logs. - Fix depth bounds test and logic op implementations. - Fix VkExternalMemory*CreateInfo not allowing host memory handle types. - Fix improper boundary error when requesting exactly the number of variable descriptors allocated. - Fix regression on functions used by multiple extensions. - Fix improper use of dynamic depth/stencil attachment. - Fix out-of-bound access when using multiview with multiple subpasses. - Fix vertexStrideAlignment value without Apple5. - Fix tvOS ASTC HDR formats. - Add base GPU family for `samplerMipLodBias` support. - Deprecate configuration parameter `MVKConfiguration::supportLargeQueryPools` and corresponding environment variable `MVK_CONFIG_SUPPORT_LARGE_QUERY_POOLS`, as obsolete and ignored. Large query pools are now supported always. - Disable Mac Catalyst builds from `all` and `all-debug` in `Makefile`, due to unresolved issues with Mac Catalyst builds. - Add CI job for building for macOS with private API. - Update to latest SPIRV-Cross: - MSL: Support image cube atomics on MSL 4.0+. - MSL: Fix array copy to array inside stage IO Blocks. - MSL: Fix boolean spec const as_type<> invalid output. - MSL: Don't emit const device for readonly SSBO. - MSL: Add some extra reserved function names. - MSL: Support 64-bit subgroup shuffles. - MSL: Get rid of obsolete buffer_aliases_argument vector. - MSL: Ensure dynamic buffer offsets get a unique name. - MSL: Fix missing use of add_local_variable_name for dynamic offset resources. - MSL: Rethink how discrete variable count descriptor arrays are emitted. - MSL: Throw on attempting to alias unrolled discrete descriptors. - MSL: Fix mesh shader with no vertex outputs. - MSL: Fix writing default gl_PointSize in tessellation shaders. - MSL: Rethink "const device" handling. - MSL: Narrow down which analysis passes need deep ID mapping. - MSL: Support OpFmaKHR. MoltenVK 1.4.0 -------------- Released 2025-08-20 - Add support for _Vulkan 1.4_. - Add support for extensions: - `VK_KHR_dynamic_rendering_local_read` - `VK_KHR_global_priority` - `VK_KHR_line_rasterization` - `VK_KHR_maintenance5` - `VK_KHR_maintenance8` - `VK_KHR_present_id` - `VK_KHR_present_id2` - `VK_KHR_present_wait` - `VK_KHR_present_wait2` - `VK_KHR_shader_float_controls2` - `VK_KHR_shader_maximal_reconvergence` - `VK_KHR_shader_quad_control` - `VK_KHR_shader_relaxed_extended_instruction` - `VK_KHR_shader_subgroup_uniform_control_flow` - `VK_KHR_surface_protected_capabilities` - `VK_EXT_line_rasterization` - `vkDeviceWaitIdle()` & `vkQueueWaitIdle()` now wait even when `VK_ERROR_DEVICE_LOST` error is encountered. - For behaviouraly consistency, require deprecated unofficial extension `VK_MVK_moltenvk` be enabled to access the proc addrs for functions `vkSetMoltenVKConfigurationMVK()` and `vkGetPhysicalDeviceMetalFeaturesMVK()`. - Fix missed supported usage in image format properties checks. - Fix high latency on present wait. - Fix shader cache misses within pipeline cache. - Fix misalignment between pipeline pixel formats and dynamic rendering attachments. - Fix attempting to add memoryless images to residency sets. - Fix color-depth image copies and image copies using buffer with multiple layers. - Enable `shaderRoundingModeRTEFloat16/32`. - Move `vkGetPhysicalDeviceMetalFeaturesMVK()` from `mvk_private_api.h` to `mvk_deprecated_api.h`. - Re-expose proc addr for deprecated `VK_MVK_moltenvk` extension functions. - Add the AMD Radeon PRO W6800X as a device with 32-wide SIMD-groups. - Apple, AMD, and Intel devices use parallelograms for lines. - Fix counter set memory leak on workaround to AMD RDNA devices - Update to latest SPIRV-Cross: - MSL: Add support for `DebugPrintf`. - MSL: Fix crash due to regression caused by recent changes to location calculations. - MSL: Add option to provide a default point size. - MSL: Implement clustered subgroup operations for sizes other than 4. - MSL: Fix generation of the `WorkgroupSize` built-in. - MSL: Implement accurate `OpSMod`. - MSL: Always emit gl_Layer for multiview. - MSL: Don't emit const for BDA pointers. - MSL: Fix loading BDA from `std140` UBO. - MSL: Fix issues with `fp16` trancendentals. - MSL: Fix edge case where a reference is taken of packed vector element. - MSL: Fix crash when using force-native-arrays in some cases. - MSL: Don't use fast::normalize for half at all. - MSL: Implement `atomic_thread_fence` for MSL 3.2+. - MSL: Always emit access qualifier when emitting coherency. - MSL: Support SPIR-V Fast Math execution modes and decorations. - MSL: Deal with spec constant arrays which depend on composite extract. - MSL: Attempt to deal with float controls and trancendentals. - MSL: Rethink `add_pragma_line()` and `add_typedef_line()`. - GLSL/MSL: Add support for `SPV_KHR_quad_control`. MoltenVK 1.3.0 -------------- Released 2025-04-27 - Add support for _Vulkan 1.3_. - Add support for extensions: - `VK_KHR_index_type_uint8` - `VK_KHR_load_store_op_none` - `VK_KHR_maintenance4` - `VK_KHR_maintenance6` - `VK_KHR_maintenance7` - `VK_KHR_robustness2` - `VK_KHR_shader_expect_assume` - `VK_KHR_shader_subgroup_rotate` - `VK_KHR_shader_terminate_invocation` - `VK_KHR_vulkan_memory_model` - `VK_KHR_zero_initialize_workgroup_memory` - `VK_EXT_depth_clip_control` - `VK_EXT_external_memory_metal`. - `VK_EXT_image_2d_view_of_3d` - `VK_EXT_index_type_uint8` - `VK_EXT_load_store_op_none` - `VK_EXT_pipeline_robustness` - `VK_EXT_tooling_info` - Add support for `B5G6R5_UNORM_PACK16` `B5G5R5A1_UNORM_PACK16`, and `B8G8R8A8` formats using swizzle. - Convert `MVK_CONFIG_USE_MTLHEAP` to enumeration, and set active by default to support `VK_EXT_image_2d_view_of_3d`, except on _AMD_ devices. - Remove `glslang` as dependency library. - `MoltenVKShaderConverter` no longer accepts GLSL` shaders as input. - Fixes to managing descriptor set allocation in a Metal argument buffer. - Fix _SPIRV-Cross_ namespace build error on some alternate build environments. - Fix recent failure of `CI.yml` to upload release build artifacts to GitHub. - Fix memory management issue in `MVKSwapchain`. - Fix indirect index for triangle fan topology. - Fix crash when shader validation is enabled. - Fix dynamic vertex stride with tessellation. - Fix Metal API violation when using `VK_KHR_swapchain_mutable_format`. - Fix designation of `vkGetPhysicalDeviceToolProperties` as a device entry-point. - Fix memory leak of `CAEDRMetadata` in `MVKSwapchain`. - Fix not saving `shouldFixupClipSpace` when serializing a pipeline. - Fix header namespace pollution. - Revert use of size 1 for variable length arrays in shader. - Add `MTLHeaps` export/import for emulated textures. - `MTLHeaps` on Apple Device Simulator must use private storage. - Remove atomic usage for `RG32Uint`. - Handle shader specializtion with macros. - Use Metal residency sets when available. - Implement barriers using Metal fences. - `vkCmdWaitEvents` end current encoder before `encodeWait`. - Remove support for deprecated `VK_NV_glsl_shader` extension, and GLSL conversions using _**MoltenVKShaderConverter**_. - Remove use of `VK_ERROR_INVALID_SHADER_NV` error code. - Reduce number of unused pipeline bindings reserved for argument buffers. - Disable unsupported Metal Pixel formats for _iOS/tvOS Simulator_. - Revert to fixed number of argument buffer binding reservations. - Ignore allowed bad `pViewportState` pointer if rasterization is disabled. - Improved estimation of vertex attribute buffer count when reserving for implicit buffer. - Fix header-hygiene warning violations. - `MVKCmdWaitEvents`: end current encoder before `encodeWait`. - Add missing `depthClamp` and `shaderTessellationAndGeometryPointSize` features to _tvOS_. - Update features overrides to all Simulators: _iOS, tvOS, visionOS_. - Fix a crash when searching the first enabled bit in a completely disabled bit array. - When shader specifies both WorkgroupSize builtin and LocalSizeId, the builtin takes precedence. - When logging a pipeline layout, log contained descriptor set layouts. - Add debug labels to barrier fences. - Allow the proc address of `vkGetMoltenVKConfigurationMVK()` to be retrieved before a `VkInstance` has been created. - Work around 10.15 AMD driver's broken blit encoder timestamp sampling. - GitHub CI update legacy build to _macOS 13 / Xcode 14_. - Fix compile with `MVK_USE_CEREAL=0`. - Update copyright notices to year 2025. - Update to latest SPIRV-Cross: - MSL: Support broader tessellation I/O matching for `VK_KHR_maintenance4`. - MSL: Add support for `SPV_KHR_expect_assume`. - GLSL/MSL: Implement `SPV_KHR_subgroup_rotate`. - MSL: Implement subgroup clustered rotate. - MSL: Pad array elements in Metal argument buffer when shader declares scalar. - MSL: Expose information about specialization constants - macro mapping - MSL: Use unpacked arguments in texture arguments. - MSL: Fix emission of bindless helper template for bindless SSBO. - MSL: Use actual result type member as cast type for mulhi. - MSL: Terminate function with return value using return if ending in unreachable. - MSL: Add option to disable rasterization depending on usage. - MSL: Always pass BDA by value into functions. - MSL: Apply input override on all flattened members in interface block. - GLSL/MSL: Support `VK_KHR_zero_initialize_workgroup_memory` - MSL: Treat pointer to vector as scalar type when bitcasting. - MSL: Use the more proper pointer typing. - MSL: Use decltype for getting return of gather. - MSL: Remove `spvForward()`. - MSL: Fix gather functions on Sequoia. - MSL: Fix crash when per-primitive variables are not used. MoltenVK 1.2.11 --------------- Released 2024-10-01 - Support dynamically allocating descriptors when pool is exhausted. - Deprecate `MVKConfiguration::preallocateDescriptors` and `MVK_CONFIG_PREALLOCATE_DESCRIPTORS` environment variable. - `vkAllocateDescriptorSets()`: Per Vulkan spec, if any descriptor set allocation fails, populate all descriptor set pointers with `VK_NULL_HANDLE`. In addition, return `VK_ERROR_FRAGMENTED_POOL` if failure was due to pool fragmentation. - `vkUpdateDescriptorSets()`: Per Vulkan spec, allow write or copy beyond the end of a descriptor binding count, including inline uniform block descriptors. - Update `VkFormat` capabilities based on latest Metal docs. - Ensure all MoltenVK config info set by `VK_EXT_layer_settings` is used. - Advertise `VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT` and `VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT` for storage texel buffers. - Support storage images in Metal argument buffers on _iOS_. - `vkUpdateDescriptorSets()`: Support writing beyond descriptor binding size if subsequent bindings are of same type. - Fix rendering issue with render pass that immediately follows a kernel dispatch. - Fix occasional GPU crash when a smaller descriptor set replaces a larger one. - Fix race condition when `VkImage` destroyed while used by descriptor. - Fix crash in `vkCmdPushDescriptorSetWithTemplateKHR()` when entries in `VkDescriptorUpdateTemplateCreateInfo` are not sorted by offset. - Fix issue where `vkQueueWaitIdle()` and `vkDeviceWaitIdle()` were not waiting for all commands to be enqueued before enqueuing wait operation. - Fix occassional incorrect detection of available descriptor sets during `vkAllocateDescriptorSets()`. - Fix shader conversion failure when using storage images on _iOS_ & _tvOS_ with Tier 1 argument buffer support. - Fix occasional memory leak where spurious texel buffer was accidentally created during image-memory unbinding. - Fix memory leak in debug utils messenger. - Fix crash when `VkDescriptorSetLayout` is destroyed while descriptor set is in use. - Fix build failure on _VisionOS 2.0_ platform. - Support `VK_FORMAT_A2B10G10R10_UNORM_PACK32` and `VK_FORMAT_A2R10G10B10_UNORM_PACK32` formats as surface formats on all platforms. - Add `MTLStoreAction` mapping for `VK_ATTACHMENT_STORE_OP_NONE`. - Add estimate of `presentMargin` in returned data from `vkGetPastPresentationTimingGOOGLE()`. - Update value of `minSubgroupSize` on _AMD RX6600_ to `32`. - Fix support for running on `tvOS 13`. - Only add present handler if `VK_GOOGLE_display_timing` info is available during presentation. - Move primitive-restart-disabled warning from renderpass to pipeline creation, to reduce voluminous log noise. - iOS: Support storage images in _Metal_ argument buffers. - Add `MVKConfiguration::shaderLogEstimatedGLSL`, and environment variable `MVK_CONFIG_SHADER_LOG_ESTIMATED_GLSL`, to enable or disable the logging of estimated _GLSL_ code, and disable it by default - Fix endless loop in `fetchDependencies` when `--` is missing on platform names. - Update dependency libraries to match _Vulkan SDK 1.3.296_. - Update `MVK_PRIVATE_API_VERSION` to version `43`. - Update to latest SPIRV-Cross: - Various non-feature maintenance updates. MoltenVK 1.2.10 --------------- Released 2024-07-15 - Improvements to bindless resources and descriptor indexing: - Add support for _Metal 3_ argument buffers. - Support argument buffers on all platforms, when _Metal 3_ is available. - Support argument buffers on _macOS_ when _Metal 3_ is not available. - Use Metal argument buffers by default when they are available. - Revert `MVKConfiguration::useMetalArgumentBuffers` and env var `MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS` to a boolean value, and enable it by default. - Support multiplanar images in _Metal_ argument buffers. - Support a descriptor pool with less descriptors than the descriptor set layout, as long as the pool has enough descriptors for the variable descriptor count, - Update max number of bindless buffers and textures per stage to 1M, per Apple Docs. - Track `OpArrayLength` buffer-sizes buffer as an auxiliary buffer in each descriptor set argument buffer, as this is how SPIRV-Cross expects it. - Add option to generate a GPU capture via a temporary named pipe from an external process. - Fix shader conversion failure when using native texture atomics. - MSL shader conversion, only pass resource bindings that apply to current shader stage. - Graphics pipeline better support dynamic patch control points. - Fix crash when `VkPipelineShaderStageCreateInfo::pTessellationState` is null. - Update documentation for minimum runtime OS requirements to indicate _macOS 10.15_, _iOS 13_, or _tvOS 13_. - Add support for _Xcode 16_, _macOS 15 SDK_, _iOS 18 SDK_, and _MSL 3.2_. - Enforce barrier when sampling timestamps. - Update Github CI versions to use Github's latest _macOS_ and default _Xcode_, and update legacy CI support to _macOS 12_ and _Xcode 13.4.1_. - Update dependency libraries to match _Vulkan SDK 1.3.290_. - Update `MVK_PRIVATE_API_VERSION` to version `42`. - Update to latest SPIRV-Cross: - MSL: Add option to force depth write in fragment shaders - MSL: Improve handling of padded descriptors with argument buffers - MSL: Support `ConstOffsets` on image gather. - MSL: Image gather `ConstOffsets` supports multiple address spaces. - MSL: Support a runtime array with dynamic offset in an argument buffer. - MSL: Support descriptor sets with recursive content when using argument buffers. - MSL: Don't bother supporting invalid multi-dimensional dynamic buffers. - MSL: Do not overwrite `rez_bind` when padding. - MSL: Only consider padding for non-aliased resources. - MSL: Always use layout-declared array size for argument buffers. - MSL: Allow UBO/SSBO resources to get the layout-derived size as well. - MSL: Improve handling of padded descriptors with argument buffers. - MSL: Fix invalid packing for pointer-to-vector. - MSL: Handle `OpPtrAccessChain` with ArrayStride - MSL: Consider pointer arithmetic for `OpPtrAccessChain`. - MSL: Cast to packed format when using unexpected stride. - MSL: Minor fix to resource type of `spvBufferSizeConstants` array indexes. MoltenVK 1.2.9 -------------- Released 2024/05/07 - Add support for extensions: - `VK_EXT_host_image_copy` - To support legacy apps, restore `MoltenVK/dylib` directory via symlink to `MoltenVK/dynamic/dylib`. - Enhancements to `MVKPerformanceStatistics`. Add `MVKPerformanceTracker::previous`, `MVKQueuePerformance::waitSubmitCommandBuffers`, and `MVKQueuePerformance::waitPresentSwapchains`. - Add `MVK_CONFIG_SHADER_DUMP_DIR` configuration parameter to optionally dump shaders to files. - Return **MoltenVK** log level string in `pMessageIdName` field of debug utils callback data. - Fix crash when using `VK_EXT_metal_objects` under _ARC_. - Fix deadlock when creating a swapchain on a thread other than the main thread. - Fix potential memory leak in `vkQueueWaitIdle()`. - Fix argument buffer padding on shader conversion. - Avoid atomic image usage if native atomics are not supported on the platform. - Ensure buffer bindings are actually used to avoid potential overrun on Metal buffer indexes. - Update dependency libraries to match _Vulkan SDK 1.3.283_. - Update `MVK_PRIVATE_API_VERSION` to `41`. - Update to latest SPIRV-Cross: - MSL: Add support for overlapping bindings. - MSL: Use recursive template for `spvArrayCopy()`. - MSL: Improve argument buffer descriptor aliasing implementation. - MSL: Workaround compiler issue with image fence when used as reference. - MSL: Fix SUMulExtended for 64-bit inputs. - MSL: Handle Atomic{S,U}{Min,Max} with mismatched image sign. - MSL: Handle missing FP16 trancendental overloads. - MSL: Remove pointer wrapper stored in `spvDescriptorArray()` to avoid potential Metal compiler bug. - MSL: Fix argument buffer padding. MoltenVK 1.2.8 -------------- Released 2024/03/12 - Add support for extensions: - `VK_KHR_shader_integer_dot_product` - Improve support for _iOS App Store_ rules by using dynamic _XCFramework_, instead of naked `dylib`. - Static _XCFramework_ now available in `Package/Latest/MoltenVK/static/MoltenVK.xcframework`. - Dynamic _XCFramework_ now available in `Package/Latest/MoltenVK/dynamic/MoltenVK.xcframework`. - _macOS_ dynamic library now available in `Package/Latest/MoltenVK/dynamic/dylib/macOS/libMoltenVK.dylib`. - Add `MVK_USE_METAL_PRIVATE_API` build setting to allow **MoltenVK** to be built with access to _Metal_ private API calls. - `VkPhysicalDeviceFeatures::wideLines` enabled when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build. - `VkPhysicalDeviceFeatures::logicOp` enabled when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build. - `VkPhysicalDeviceFeatures::depthBounds` enabled on AMD GPUs when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build. - `VkPhysicalDevicePortabilitySubsetFeaturesKHR::samplerMipLodBias` enabled when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build. - _Metal_ native pipeline sample masks supported when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build. - Enable use of native texture atomics where supported. - Fix potential crash when using multi-planar images. - Fix translation of fully remapped multi vertex attribute bindings. - Fix unresolvable layered compute resolve. - Fix visionOS build. - Handle depth/stencil swizzle sample correctly. - Ensure buffers available for buffer addresses in push constants. - Don't update `currentExtent` of headless surface when swapchain attached. - Don't return `VK_SUBOPTIMAL_KHR` for headless surfaces. - `runcts` script also output a file containing a list of the failed CTS tests. - Add documentation for using Metal GPU capture with **MoltenVK**. - Update minimum _macOS_ deployment target to 10.15. - Update minimum _iOS/tvOS_ deployment target to 13.0. - Update dependency libraries to match _Vulkan SDK 1.3.280_. - Update `MVK_PRIVATE_API_VERSION` to `40`. - Update to latest SPIRV-Cross: - MSL: Plumb through member state to image/sampler types. - MSL: Support variable sized descriptor array in argument buffer. - MSL: Implement `spvDescriptorArray` path for SSBO/UBO. - MSL: Add support for SPV_EXT_integer_dot_product. - MSL: Fix misc sign issues with dot product impl and add more coverage. - MSL: Handle volatile properly for emulated image atomics. - MSL: OpCopyObject declare a temp var of base type, not pointer type. - MSL: Pass texture array index separately to atomic texture operations. - MSL: Test image atomic for image2DArray. - MSL: Improve handling of BDA + atomics. - MSL: Fix type hierarchy for extended vectors. - MSL: Fix type hierarchy for extended vectors. - MSL: `atomic_compare_exchange_weak()` support `CompilerMSL:msl_options.texture_1D_as_2D`. MoltenVK 1.2.7 -------------- Released 2024/01/08 - Add support for extensions: - `VK_KHR_calibrated_timestamp` - `VK_KHR_format_feature_flags2` - `VK_KHR_vertex_attribute_divisor` - `VK_EXT_extended_dynamic_state3` *(Metal does not support `VK_POLYGON_MODE_POINT`)* - `VK_EXT_headless_surface` - `VK_EXT_layer_settings` - Add support for format `VK_FORMAT_B4G4R4A4_UNORM_PACK16`. - Add support for vertex formats `VK_FORMAT_B10G11R11_UFLOAT_PACK32` & `VK_FORMAT_E5B9G9R9_UFLOAT_PACK32`. - Fix regression that broke `VK_POLYGON_MODE_LINE`. - Fix regression in marking rendering state dirty after `vkCmdClearAttachments()`. - Fix regression error in argument buffer runtime arrays. - Fix rare deadlock during launch via `dlopen()`. - Fix initial value of `VkPhysicalDeviceLimits::timestampPeriod` on non-Apple Silicon GPUs. - Fix swapchain and surface bugs when windowing system is accessed from off the main thread. - Fix system memory size of _tvOS_. - Fix `heapUsage` query for non-unified memory devices. - Add a defensive guard to ensure `heapUsage[0]` calculation is correct. - Clamp max per-set descriptor limit to minimum `1024`. - Enable the cube texture gradient workaround for Apple Silicon. - Ensure `lineWidthGranularity` is zero if the `wideLines` feature isn't supported. - Ensure `maxDrawIndexedIndexValue` set to `UINT32_MAX`. - Ignore no external handle types specified for buffers and images. - Expose `VK_EXT_debug_utils` device functions as device functions, not instance functions. - Emit `primitiveRestartEnable` disabled warning only for strip topology. - Enable mandatory `VK_EXT_descriptor_indexing` features, and don't advertise extension if they are not supported. - Reduce disk space consumed after running `fetchDependencies` script by removing intermediate file caches. - Deprecate `vkSetMoltenVKConfigurationMVK()`. - Deprecate `mvk_config.h` and move content to `mvk_private_api.h` and `mvk_deprecated_api.h`. - The _Cube_ demo is now based on _Volk_, with dynamic library linking, and dynamic function pointer calls. - Update copyright notices to year 2024. - Update dependency libraries to match _Vulkan SDK 1.3.275_. - Update `MVK_CONFIGURATION_API_VERSION` and `MVK_PRIVATE_API_VERSION` to `39`. - Update to latest SPIRV-Cross: - MSL: Fix regression error in argument buffer runtime arrays. - MSL: Work around broken cube texture gradients on Apple Silicon. - MSL: Ensure discrete runtime arrays of buffers have known length. - MSL: Implement Metal 3.1 image atomics natively. - MSL: Fix patch vertex count with raw buffer tese input. - MSL: Improve handling of sample masks. - MSL: Add divide to reserved function names. - MSL: Support std140 half matrices and arrays. - MSL: Use more appropriate padded types. - MSL: Don't use swizzle if we have wrapper. - MSL: Add ray-cull mask - MSL: Consider PtrAccessChain on array types. - MSL: Use LHS expression to determine whether or not to do array copy. - MSL: Only do address-of expression when needed. - MSL: Improve PtrAccessChain handling. - MSL: Use powr instead of pow. - MSL: Remove special case for threadgroup array wrapper. - MSL: Added an `Op` field to `SPIRType` and refactor. MoltenVK 1.2.6 -------------- Released 2023/10/17 - Add support for extensions: - `VK_KHR_synchronization2` - `VK_EXT_extended_dynamic_state` *(requires Metal 3.1 for `VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE`)* - `VK_EXT_extended_dynamic_state2` - Fix rare case where vertex attribute buffers are not bound to Metal when no other bindings change between pipelines. - Ensure objects retained for life of `MTLCommandBuffer` during `vkCmdBlitImage()` & `vkQueuePresentKHR()`. - Fix case where a `CAMetalDrawable` with invalid pixel format causes onscreen flickering. - Fix deadlock when reporting debug message on `MVKInstance` destruction. - Fix MSL code used in `vkCmdBlitImage()` on depth-stencil formats. - Improve behavior of swapchain image presentation stalls caused by Metal regression. - `VkPhysicalDeviceLimits::timestampPeriod` set to 1.0 on Apple GPUs, and calculated dynamically on non-Apple GPUs. - Add `MVKConfiguration::timestampPeriodLowPassAlpha` and environment variable `MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA`, to add a configurable lowpass filter for varying `VkPhysicalDeviceLimits::timestampPeriod` on non-Apple GPUs. - Add several additional performance trackers, available via logging, or the `mvk_private_api.h` API. - Deprecate `MVK_DEBUG` env var, and add `MVK_CONFIG_DEBUG` env var to replace it. - Update `MVK_CONFIGURATION_API_VERSION` and `MVK_PRIVATE_API_VERSION` to `38`. - Update dependency libraries to match _Vulkan SDK 1.3.268_. - Update to latest SPIRV-Cross: - MSL: Workaround Metal 3.1 regression bug on recursive input structs. - MSL: fix extraction of global variables, in case of atomics. - MSL: Workaround bizarre crash on macOS. - MSL: runtime array over argument buffers. - MSL: Make rw texture fences optional. - MSL: Prevent RAW hazards on read_write textures. MoltenVK 1.2.5 -------------- Released 2023/08/15 - Add support for extensions: - `VK_KHR_deferred_host_operations` - `VK_KHR_incremental_present` - `VK_KHR_shader_non_semantic_info` - `VK_EXT_4444_formats` - `VK_EXT_calibrated_timestamps` - `VK_EXT_pipeline_creation_feedback` - `VK_EXT_shader_demote_to_helper_invocation` - `VK_EXT_shader_subgroup_ballot` - `VK_EXT_shader_subgroup_vote` - Add support for `VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN`. - Support building MoltenVK for visionOS. - Ensure non-dispatch compute commands don't interfere with compute encoding state used by dispatch commands. - Support maximizing the concurrent executing compilation tasks via `MVKConfiguration::shouldMaximizeConcurrentCompilation` - Support `VK_PRESENT_MODE_IMMEDIATE_KHR` if `VkPresentTimeGOOGLE::desiredPresentTime` is zero. - Add support for `VK_PRESENT_MODE_IMMEDIATE_KHR` to macOS Cube demo. - Allow both `renderPass` and `VkPipelineRenderingCreateInfo` to be missing. - Fix sync delay between calls to `vkQueueSubmit()` on non-Apple-Silicon devices. - Ensure Xcode simulator always uses 256B buffer alignment. - Don't attempt to force the window system to use the same high-power GPU as the app, on every swapchain creation. - Log more info about SPIR-V to MSL conversion errors. - Implement Deferred Host Operations. - Support _MSL Version 3.1_. - Drop official support for using *Xcode 11* to build MoltenVK. - To allow building MoltenVK without an internet connection, don't fetch a submodule if the commit is already known. - Update dependency libraries to match _Vulkan SDK 1.3.261_. - Update to latest SPIRV-Cross: - MSL: Fix argument buffer padding when content includes arrays. - MSL: ray-query intersection params - MSL: Support `SPV_KHR_shader_ballot` and `SPV_KHR_subgroup_vote`. - Skip line directives when emitting loop condition blocks. - MSL: Consider changed array types for array-of-constant-bool in struct. - MSL: Consider bool-short remapping for constant expressions as well. - Minor cleanup in constant_expression(). - MSL: Add test for bool-in-struct edge cases. - MSL: Handle more complex array copy scenarios with bool <-> short. - MSL: Handle stores to struct bool[]. - MSL: Consider bool/short remapping when dealing with composites. - MSL: fix function constant deduplication misfire MoltenVK 1.2.4 -------------- Released 2023/05/23 - Add support for extensions: - `VK_KHR_map_memory2` - Deprecate the obsolete and non-standard `VK_MVK_moltenvk` extension. - Add `mvk_config.h`, `mvk_private_api.h`, and `mvk_deprecated_api.h`, and deprecate `vk_mvk_moltenvk.h`. - Support BC compression on iOS/tvOS where available (iOS/tvOS 16.4 and above and supported by the GPU). - Support separate depth and stencil attachments during dynamic rendering. - Fix memory leak when waiting on timeline semaphores. - Fix race condition when updating values in `VkPastPresentationTimingGOOGLE`, and ensure swapchain image presented time is always populated when requested. - Report error, but do not fail on request for timestamp query pool that is too large for `MTLCounterSampleBuffer`, and fall back to emulation via CPU timestamps. - Ensure shaders that use `PhysicalStorageBufferAddresses` encode the use of the associated `MTLBuffer`. - Disable pipeline cache compression prior to macOS 10.15 and iOS/tvOS 13.0. - Accumulate render stages when a resource is used by multiple descriptor bindings. - Respect the bind point supplied to `vkCmdBindDescriptorSets()` / `vkCmdPushDescriptorSets()`. - Check if shader compiled before adding it to a pipeline, to avoid Metal validation error. - Identify each unsupported device feature flag that the app attempts to enable. - Populate `deviceUUID` from `MTLDevice` location and peer group info, which should be unique, and constant across OS reboots. - Populate `deviceLUID` from `MTLDevice.registryID`. - Avoid Metal validation warning when depth component swizzled away. - Fix depth clamp and texture swizzle feature discovery on simulator builds. - Advertise `VK_KHR_depth_stencil_resolve` extension on all devices. - For correctness, set `VkPhysicalDeviceLimits::lineWidthGranularity` to `1`. - Improve GitHub CI production of binary artifacts on submission and release. - Update dependency libraries to match _Vulkan SDK 1.3.250_. - Update to latest SPIRV-Cross: - MSL: Fix for argument buffer index compare when invalid. - MSL: Fix dref lod workaround on combined texture/samplers. - MSL: Do not override variable name with v_ identifier. - MSL: Use name_id consistently in argument declaration. - MSL: Don't hit array copy path for pointer to array. - MSL: Use templated array type when emitting BDA to arrays. MoltenVK 1.2.3 -------------- Released 2023/03/22 - Add support for extensions: - `VK_EXT_external_memory_host` - `VK_EXT_pipeline_creation_cache_control` - `VK_EXT_shader_atomic_float` - `VK_EXT_surface_maintenance1` - `VK_EXT_swapchain_maintenance1` - Fix crash when `VkCommandBufferInheritanceInfo::renderPass` is `VK_NULL_HANDLE` during dynamic rendering. - Do not clear attachments when dynamic rendering is resumed. - Allow ending dynamic rendering to trigger next multiview pass if needed. - Fix premature caching of occlusion query results during tessellation rendering. - `vkCmdCopyQueryPoolResults()`: Fix loss of queries when query count is not a multiple of GPU threadgroup execution width. - Disable occlusion recording while clearing attachments or render area. - Fix issue where extension `VK_KHR_fragment_shader_barycentric` was sometimes incorrectly disabled due to a Metal driver bug. - Detect when size of surface has changed under the covers. - Change rounding of surface size provided by Metal from truncation to rounding-with-half-to-even. - Queue submissions retain wait semaphores until `MTLCommandBuffer` finishes. - Use a different visibility buffer for each `MTLCommandBuffer` in a queue submit. - Work around problems with using explicit LoD with arrayed depth images on Apple Silicon. - Fix issue when `VkPipelineVertexInputDivisorStateCreateInfoEXT::vertexBindingDivisorCount` doesn't match `VkPipelineVertexInputStateCreateInfo::vertexBindingDescriptionCount`. - Support Apple Silicon pixel formats on a MoltenVK `x86_64` build that is running on Apple Silicon using Rosetta2. - Reduce memory footprint of MSL source code retained in pipeline cache. - Add `MVKConfiguration::shaderSourceCompressionAlgorithm` and env var `MVK_CONFIG_SHADER_COMPRESSION_ALGORITHM` to support compressing MSL shader source code held in a pipeline cache. - Add `MVKShaderCompilationPerformance::mslCompress` and `mslDecompress` to allow performance of MSL compression to be tracked and queried. - Add support for logging performance stats accumulated in a `VkDevice`, when it is destroyed. - Change `MVKConfiguration::logActivityPerformanceInline` boolean to `activityPerformanceLoggingStyle` enumeration value. - Add `MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE` environment variable and build setting to set `MVKConfiguration::activityPerformanceLoggingStyle` value. - Expand `MVK_CONFIG_TRACE_VULKAN_CALLS` to log thread ID only if requested. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version `37`. - Update dependency libraries to match _Vulkan SDK 1.3.243_. - Update to latest SPIRV-Cross: - MSL: Add support for `OpAtomicFAddEXT` atomic add on float types - MSL: Add a workaround for broken `level()` arguments. - MSL: Deduplicate function constants. MoltenVK 1.2.2 -------------- Released 2023/01/23 - Fix Metal validation error caused by `CAMetalDrawable` released before `MTLCommandBuffer` is finished using it. - Fix memory leak of `MVKFences` and `MVKSemaphores` when a swapchain image is acquired more than it is presented. - Fix issue where fragment shader was not run when no render attachment is available. - Ensure Vulkan public symbols are not stripped from the library when statically linked to an app that calls all Vulkan functions dynamically. - Per Vulkan 1.2 spec, support calling `vkGetInstanceProcAddr()` with a null instance, when `vkGetInstanceProcAddr` itself is the function name. - Update `VkPhysicalDeviceLimits` members `maxClipDistances` and `maxCombinedClipAndCullDistances` to more accurate values. - Update `VkPhysicalDeviceLimits::maxDrawIndexedIndexValue` to acknowledge automatic primitive restart. - Update copyright notices to year 2023. - Update dependency libraries to match _Vulkan SDK 1.3.239_. - Update to latest SPIRV-Cross: - MSL: Add support for writable images in iOS Tier2 argument buffers. - MSL: Fix potentially uninitialized warnings. MoltenVK 1.2.1 -------------- Released 2022/12/08 - Add support for extensions: - `VK_KHR_copy_commands2` - Fix crash on descriptor update with out-of-bounds descriptor count data. - Fix Metal buffer index binding overrides for push constants and attachment clearing. - Fix crash when buffer binding updates only offset while it is overridden. - Fix app performance regression triggered by the previous introduction of `VK_KHR_shader_float_controls`. - Work around `MTLCounterSet` crash on additional Intel Iris Plus Graphics devices. - Fix mistaken YCBCR format support indication. - Fix invalid blit offsets. - Wait on emulated semaphores only once to prevent freezing when using prefilled command buffers. - `MVKPipeline`: Stop using vertex-style input for tessellation evaluation shaders. - `MVKPipeline`: Force extra checks for stores after fragment discard. - `MVKImage`: Always use a texel buffer for atomic storage images. - `MVKDevice`: Fix backwards attribution of storage/uniform texel buffer alignments. - Document new linkage model used by *Xcode 14* and later, and how to link **MoltenVK** to an app or game using *Xcode 13* or earlier. - Support *Xcode 14.1* build settings. - Upgrade GitHub CI to use *Xcode 14.1* on *macOS 12*. - Update dependency libraries to match _Vulkan SDK 1.3.236_. - Update to latest SPIRV-Cross: - MSL: Implement `CompositeInsert` `OpSpecConstantOp`. - MSL: Support "raw" buffer input in tessellation evaluation shaders. - MSL: Don't flatten arrayed per-patch output blocks in tessellation shaders. - MSL: Account for composite types when assigning locations. - MSL: Handle partial access chains with array-of-UBO/SSBO. - MSL: Fix restrict vs __restrict incompatibility. - MSL: Handle implicit integer promotion rules. - MSL: Manually update `BuiltInHelperInvocation` when a fragment is discarded. - MSL: Add missing casts to `Op?MulExtended`. - MSL: Prevent stores to storage resources in discarded fragments. - MSL: Don't dereference forwarded copies of `OpVariable` pointers. - MSL: Refactor member reference in terms of one boolean. - Fix MSL Access Chain. MoltenVK 1.2.0 -------------- Released 2022/10/17 - Add support for _Vulkan 1.2_. - Add support for extensions: - `VK_KHR_shader_float_controls` - `VK_KHR_spirv_1_4` - Vulkan semaphore functional improvements: - Replace use of `MTLFence` with an option to limit to a single Vulkan queue and use Metal's implicit submisison order guarantees. - Support option to force use of `MTLEvents` for Vulkan semaphores on NVIDIA and Rosetta2. - `MVKConfiguration` replace booleans `semaphoreUseMTLEvent` and `semaphoreUseMTLFence` with enumerated `semaphoreSupportStyle`. - Support config option to automatically use Metal argument buffers when `VK_EXT_descriptor_indexing` extension is enabled. `MVKConfiguration::useMetalArgumentBuffers` (`MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS`) is now an enum field. The use of Metal argument buffers is still disabled by default (`MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_NEVER`). - Fix memory leaks when configured for prefilling Metal command buffers. - `MVKConfiguration` replace boolean `prefillMetalCommandBuffers` with enumeration. - `MVKPipeline`: Add builtins that are read but not written to tessellation pipelines. - Fix occassional crash from retention of `MVKSwapchain` for future drawable presentations. - Fix crash in `vkCreateSwapchainKHR()` on macOS 10.14 and earlier - Fix undefined reference to `vkGetBufferDeviceAddressEXT` when building with `MVK_HIDE_VULKAN_SYMBOLS=1`. - Update `Makefile` to forward any build setting declared on the command line to Xcode. - Add _**non-functional** Vulkan 1.3_ core function **_stubs_**, to avoid link errors with some external libraries that assume _Vulkan 1.3_ linkages from the standard _Vulkan_ header files included with **MoltenVK**. - Add `MVK_USE_CEREAL` build setting to avoid use of Cereal external library (for pipeline caching). - `MoltenVKShaderConverter` tool automatically maps bindings when converting _GLSL_. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version `36`. - Update to latest SPIRV-Cross: - MSL: Support `OpPtrEqual`, `OpPtrNotEqual`, and `OpPtrDiff`. - MSL: Emit correct address space when casting during `OpStore`. - MSL: Add a mechanism to fix up shader outputs. - MSL: Handle descriptor aliasing of raw buffer descriptors. - MSL: Do not attempt to alias push constants. - MSL: only fix up `gl_FragCoord` if really necessary. - MSL: Expose way to query if a buffer needs array length. - MSL: Report unsupported 64-bit atomics. - Don't rename remapped variables like `gl_LastFragDepthARM` MoltenVK 1.1.11 -------------- Released 2022/08/15 - Add support for extensions: - `VK_EXT_metal_objects` - `VK_KHR_buffer_device_address` and `VK_EXT_buffer_device_address` *(available on GPUs with Tier 2 argument buffers support)*. - Reducing redundant state changes to improve command encoding performance. - Improve performance of `vkResetDescriptorPool()`. - Update minimum Xcode deployment targets to macOS 10.13, iOS 11, and tvOS 11, to avoid Xcode build warnings in Xcode 14. - Work around `MTLCounterSet` crash on additional Intel Iris Plus Graphics drivers. - Check `MTLDevice` to enable support for `VK_KHR_fragment_shader_barycentric` and `VK_NV_fragment_shader_barycentric` extensions. - Ignore sampler update in descriptor set bindings that use immutable samplers. - Fix query pool wait block when query is not encoded to be written to. - Fix `vkUpdateDescriptorSetWithTemplate()` for inline block descriptors. - Fix retrieval of accurate `vkGetRefreshCycleDurationGOOGLE()` across multiple display screens. - Fix occasional missing Metal buffer binding when only offset changes. - Fix crash creating compute pipelines on macOS versions < 10.14. - Apply Apple fix to `MTLCaptureScope` retention bug to macOS 12.4 and iOS 15.4 and later. - Report appropriate values of `VkDebugUtilsMessageTypeFlagsEXT` for debug util messages generated within MoltenVK. - Update _macOS Cube_ demo to demonstrate optimizing the swapchain across multiple display screens. - Support building in Xcode 14. - Allow building on removable volumes with a space in their name. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version `35`. - Update to latest SPIRV-Cross: - MSL: Add support for `SPV_KHR_physical_storage_buffer` extension. - MSL: Use a wrapper type for matrices in workgroup storage. - MSL: Fix various bugs with Ptr/U bitcasts. - Fix control flow bug with missed continue statement. - Handle PHI in collapsed switch constructs. - Handle collapsed loops similar to collapsed selections. - Handle multiple breaks out of switches. - Do not optimize `OpCompositeInsert` for hoisted temporaries. MoltenVK 1.1.10 -------------- Released 2022/06/06 - Add support for extensions: - `VK_KHR_portability_enumeration` support added to `MoltenVK_icd.json`, and documentation updated to indicate the impact of the `VK_KHR_portability_enumeration` extension during runtime loading on *macOS* via the *Vulkan Loader*. - `VK_KHR_dynamic_rendering` - `VK_KHR_fragment_shader_barycentric` and `VK_NV_fragment_shader_barycentric` - `VK_KHR_separate_depth_stencil_layouts` - `VK_EXT_separate_stencil_usage` - Implement `vkGetRefreshCycleDurationGOOGLE()` for _macOS_. - Support attachment clearing when some clearing formats are not specified. - Fix regression error where previously bound push constants can override a descriptor buffer binding used by a subsequent pipeline that does not use push constants. - Fix error on some Apple GPU's where a `vkCmdTimestampQuery()` after a renderpass was writing timestamp before renderpass activity was complete. - Fix regression error in vertex buffer binding counts when establishing implicit buffers binding indexes. - Fix `vkSetMoltenVKConfigurationMVK()` function pointer typedef. - Work around zombie memory bug in Intel Iris Plus Graphics driver when repeatedly retrieving GPU counter sets. - Fix reorder-ctor warnings and add Xcode clang -Wreorder warning to catch future misalignments. - Update build settings to support Xcode 13.4. - Update to latest SPIRV-Cross: - MSL: Emit interface block members of array length 1 as arrays instead of scalars. - MSL: Potentially cast loaded Input variables. - Emit KHR barycentrics if source enables the KHR extension. - Handle early reads from loop variables with initializers. - Attempt more optimal codegen for `OpCompositeInsert`. MoltenVK 1.1.9 -------------- Released 2022/04/11 - Add support for extensions: - `VK_EXT_sample_locations` _(Custom locations settable via_ `vkCmdBeginRenderPass()` _only, since_ `VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations` _is `false`)_. - Fixes to pipeline layout compatibility between sequentially bound pipelines. - Reinstate memory barriers on non-Apple GPUs, which were inadvertently disabled in an earlier update. - Support base vertex instance support in shader conversion. - Fix alignment between outputs and inputs between shader stages when using nested structures. - Fix issue where the depth component of a stencil-only renderpass attachment was incorrectly attempting to be stored. - Fix deletion of GPU counter `MTLFence` while it is being used by `MTLCommandBuffer`. - Fix crash in `vkGetMTLCommandQueueMVK()`. - Fix leak of `CoreFoundation` objects during calls to `vkUseIOSurfaceMVK()`. - Remove limit on `VkPhysicalDeviceLimits::maxSamplerAllocationCount` when not using Metal argument buffers. - Avoid adjusting SRGB clear color values by half-ULP on GPUs that round float clear colors down. - Fixes to optimize resource objects retained by descriptors beyond their lifetimes. - Optimize behavior for `VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT` when `MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS` is used - `MoltenVKShaderConverter` tool defaults to the highest MSL version supported on runtime OS. - Update *glslang* version, to use `python3` in *glslang* scripts, to replace missing `python` on *macOS 12.3*. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version `34`. - Update to latest SPIRV-Cross: - MSL: Support input/output blocks containing nested struct arrays. - MSL: Use var name instead of var-type name for flattened interface members. - MSL: Handle aliased variable names for resources placed in IB struct. - MSL: Handle awkward mix and match of `Offset` / `ArrayStride` in constants. - MSL: Append entry point args to local variable names to avoid conflicts. - MSL: Consider that `gl_IsHelperInvocation` can be `Volatile`. - MSL: Refactor and fix use of quadgroup vs simdgroup. - Handle `OpTerminateInvocation`. - Fixup names of anonymous inner structs. - Fix regression from adding 64-bit switch support. MoltenVK 1.1.8 -------------- Released 2022/02/22 - Remove logged warning if MoltenVK does not support `VkApplicationInfo::apiVersion` value. MoltenVK 1.1.7 -------------- Released 2022/02/07 - Add `MVK_HIDE_VULKAN_SYMBOLS` env var to support building MoltenVK with static Vulkan linkage symbols hidden. - Improve accuracy of `VkPhysicalDeviceLimits::timestampPeriod`. - Do not use `MTLEvent` for `VkSemaphore` under *Rosetta2*. - On *Apple Silicon (iOS, tvOS & macOS)*, set `VkPhysicalDeviceProperties::deviceID` from GPU capabilities. - Support compiling *MSL 2.4* in runtime pipelines and `MoltenVKShaderConverterTool`. - Fix issue where *MSL 2.3* only available on *Apple Silicon*, even on *macOS*. - Fix memory leak of dummy `MTLTexture` in render subpasses that use no attachments. - Fix Metal object retain-release errors in assignment operators. - Fix use of GPU counter sets on older versions of iOS running on the simulator. - `mvk::getShaderOutputs()` in `SPRIVReflection.h` support flattening nested structures. - Replaced ASL logging levels with `MVKConfigLogLevel`. - `MoltenVKShaderConverter` tool support loading tessellation shader files. - `MoltenVKShaderConverter` tool update to *MSL 2.4* by default. - Upgrade to *Vulkan 1.3* headers. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version `33`. - Update copyright notices to year 2022. - Update to latest SPIRV-Cross: - MSL: Add 64 bit support for `OpSwitch`. - MSL: Don't output depth and stencil values with explicit early fragment tests. - MSL: Fix incorrect MSL `gl_TessCoord` variable type. - MSL: Allow copy array from `UniformConstant` storage. - MSL: Handle signed `atomic min/max`. - Fix `normalize` on `half3/half2`. - MSL: Handle constant construct of block-like array types. - MSL: Rethink how opaque descriptors are passed to leaf functions. - Rework how loop iteration counts are validated. - Clamp vector element access to vector size. - Handle aliased names in spec constants. - Add support for `LocalSizeId`. MoltenVK 1.1.6 -------------- Released 2021/11/15 - Set maximum point primitive size based on GPU vendor ID, which can now be as large as `511`. - Improved checks for timestamp GPU counter support on older devices. - Fix incorrect validation error on multilayer `VkImage` marked for rendering, when multilayered-rendering is not supported on platform, but app doesn't actually attempt to render to multiple layers. - Fix dynamic pipeline state such as `vkCmdSetDepthBias()` sometimes ignoring pipeline dynamic state flags when called before `vkCmdBindPipeline()`. - Fix incorrect validation of multilayer-rendering validation when `MVKImageView` does not actually perform multilayer-rendering. - Fix issue where dynamic pipeline flags were sometimes read from previously bound pipeline. - Fix issue where correct base layer and mipmap for attachment was sometimes not being used. - Add `MTLFence` between Metal encoders and timestamp stage counter BLIT encoder to ensure previous work is finished before being timestamped. - Fix issue with `BC1_RGB` compressed format where incorrect alpha value returned. - Add `vkGetMTLCommandQueueMVK()` function to expose underlying `MTLCommandQueue` object. - Add `vkSetWorkgroupSizeMVK()` function. - Add unsupported `VkApplicationInfo::apiVersion` warning. - Update to latest SPIRV-Cross version: - MSL: Add support for `OpSpecConstantOp` ops `OpQuantizeToF16` and `OpSRem`. - MSL: Return fragment function value even when last SPIR-V Op is discard (`OpKill`). - MSL: Fix location and component variable matching between shader stages. - MSL: Fix type redirection when struct members are reordered to align with offsets. - MSL: Remove over-zealous check for struct packing compatibility. - MSL: Correctly emit user(`clip/cullN`) for clip/cull builtins in tess output struct. - MSL: Don't output depth and stencil values with explicit early fragment tests. - MSL: Track location component to match `vecsize` between shader stages. - MSL: Selectively enable `fast-math` in MSL code to match Vulkan CTS results. - MSL: Honor `DecorationNoContraction` when compiling using `fast-math`. - MSL: Honor infinities in `OpQuantizeToF16` when compiling using `fast-math`. - MSL: Support synthetic functions in function constants. - MSL: Improve handling of `INT_MIN/INT64_MIN` literals. - MSL: Consolidate `spvQuantizeToF16()` functions into a single template function. - MSL: Use `vec` in template `SpvHalfTypeSelector` for function `spvQuantizeToF16()`. - MSL: Support more usecases for unpacked vectors. - MSL: Workaround compiler crashes when using `threadgroup bool`. - MSL: Handle non-thread storage class in `Modf/Frexp` pointer versions. - Improve handling of `INT_MIN/INT64_MIN` literals. - Per spec, support undefined behavior for out-of-bounds swizzles. - Correctly reflect declared buffer size for out of order members. - Separate (partially) the tracking of depth images from depth compare ops. MoltenVK 1.1.5 -------------- Released 2021/08/30 - Changes to how `VkSemaphore` is supported: - Revert to prefer `MTLEvent` for `VkSemaphore`, except on NVIDIA, where emulation on CPU is preferred. - Set default value of the `MVK_ALLOW_METAL_FENCES` environment variable to `0 (false)`, - Vulkan timestamp query pools use Metal GPU counters when available. - Support resolving attachments with formats that Metal does not natively resolve. - Support stencil-only partial attachment clearing. - Support alpha-to-coverage without a color attachment. - Fix issue where swapchain images were acquired out of order under heavy load. - Fix issue with `vkCmdBlitImage()` from compressed textures. - Fix incorrect translation of clear color values on Apple Silicon. - Fix swizzle of depth and stencil values into RGBA (`float4`) variable in shaders. - Fix occasional crash when swizzling used but shader swizzling not enabled. - Fix pipeline barriers not working inside self-dependent subpasses on Apple GPUs. - Fix GPU race condition when clearing a renderpass input attachment on Apple GPUs. - Disable `VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT` for `VK_FORMAT_E5B9G9R9_UFLOAT_PACK32` on macOS Apple Silicon. - Fix execution order of `encodeBindings` for `bufferBindings`. - Properly ignore non-null pipeline creation pointers that should be ignored. - Add queue and queue family indices to `MTLCommandBuffer` label. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `32`. - Update to latest SPIRV-Cross version: - MSL: Adjust `gl_SampleMaskIn` for sample-shading and/or fixed sample mask. - MSL: Remove redundant path for `SampleMask`. - MSL: Fix setting `SPIRVCrossDecorationInterpolantComponentExpr` decoration. - MSL: Support row-major transpose when storing matrix from constant RHS matrix. - MSL: Fix casting in constant expressions with different sizes. - MSL: Fix duplicate `gl_Position` outputs when `gl_Position` defined but unused. - MSL: Simplify `spvSubgroupBallot()`. - MSL: Consider that function/private variables can be block-like. - Track temporary access for `OpArrayLength` result. MoltenVK 1.1.4 -------------- Released 2021/06/28 - Add support for extensions: - `VK_KHR_imageless_framebuffer` - Advertise Vulkan extension functions only from enabled extensions. - Make `vkGetPastPresentationTimingGOOGLE()` queuing behavior compliant with Vulkan spec. - Expose `vkGetIOSurfaceMVK()` and `vkUseIOSurfaceMVK()` without requiring _Objective-C_. - Default MoltenVK build using `C++17` and compiler optimization setting `-O2`. - API fix to remove `#include "SPIRVReflection.h"` from `SPIRVToMSLConverter.h` header. - Support _Xcode 12.5_ build settings, build warnings, and SDK change to availability of `[MTLDevice supportsBCTextureCompression]` on _Mac Catalyst_. - Add support for new AMD devices supporting 32 lanes. - Improve handling of sampler border color and mirror edge clamp. - Improve cache hits when matching `SPIRVToMSLConversionConfiguration` structs to each other to find a cached shader, by only considering resources from the current shader stage. - Rename `kMVKShaderStageMax` to `kMVKShaderStageCount`. - Fix crash when requesting `MTLCommandBuffer` logs in runtime debug mode on older OS versions. - Fix synchronization issue with locking `MTLArgumentEncoder` for Metal Argument Buffers. - Fix race condition on submission fence during device loss. - Fix crash due to incorrect number of attachments when clearing. - Fix crash using memoryless storage for input attachments on Apple Silicon. - Fix issue where M1 GPU does not support reusing Metal visibility buffer offsets across separate render encoders within a single Metal command buffer (Vulkan submit). - On command buffer submission failure, if `MVKConfiguration::resumeLostDevice` enabled, do not release waits on `VkDevice`, and do not return `VK_ERROR_DEVICE_LOST`, unless `VkPhysicalDevice` is also lost. - Fix inconsistent handling of linear attachment decisions on Apple Silicon. - Fix small memory leak during swapchain creation. - Fix stencil clear incorrectly using using the depth `loadOp`, when stencil is smaller than render area. - Reorganize coherent texture flushing on memory map and unmap`. - Fix issues where data in temporary internal buffers are discarded while in use. - Protect against crash when retrieving `MTLTexture` when `VkImage` has no `VkDeviceMemory` bound. - Adjust some `VkPhysicalDeviceLimits` values for Vulkan and Metal compliance. - Fix internal reference from `SPIRV_CROSS_NAMESPACE_OVERRIDE` to `SPIRV_CROSS_NAMESPACE`. - Add label strings to `MTLCommandBuffers`, based on use type, for GPU Capture debugging. - Add `Scripts/runcts` script as a convenience for running Vulkan CTS tests. - Support _Xcode 13_ SDK APIs and build settings. - Update dependency libraries to match _Vulkan SDK 1.2.182_. - Update to latest SPIRV-Cross version: - MSL: Handle array of IO variable with Component decoration. - MSL: Handle array with component when we cannot rely on `user()` attrib. - MSL: Improve handling of split tessellation access chains. - MSL: Always enable support for base vertex/index on _iOS_. MoltenVK 1.1.3 -------------- Released 2021/04/27 - Add beta support for using Metal argument buffers for shader resources on _macOS_, by setting `MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS` environment variable (disabled by default). This dramatically expands the number of resources that can be submitted to a pipeline stage, per the Vulkan `VK_EXT_descriptor_indexing` extension. **Currently available on _macOS 11.0 (Big Sur)_ or later, and on earlier _macOS_ versions on _Intel_ GPU's**. - Add support for `HDR10` colorspace via `VK_COLOR_SPACE_HDR10_HLG_EXT` and `VK_COLOR_SPACE_HDR10_ST2084_EXT`. - Always explicitly set `CAMetalLayer` colorspace property based on _Vulkan_ parameters, and don't rely on _Metal_ default values. - Add `MVKConfiguration::resumeLostDevice` and `MVK_CONFIG_RESUME_LOST_DEVICE` env var, to allow `VkDevice` to resume after non-fatal `VK_ERROR_DEVICE_LOST` error. - `MVKDescriptorPool` pools its descriptor sets. - Enable `MVKConfiguration::preallocateDescriptors` and `MVK_CONFIG_PREALLOCATE_DESCRIPTORS` environment variable by default to preallocate descriptors when a `VkDescriptorPool` is created. - Avoid use of _Metal_ renderpass load and store actions on memoryless attachments. - Fix memory leak on swapchain destruction. - Fix `MVKPhysicalDevice::getSurfaceFormats()` returning `VK_FORMAT_UNDEFINED`. - Fix memory leak where swapchains and images were not destroyed due to a retention loop. - Fix advertising single-texel alignment capability for texel buffers. - Fix time and space inefficiencies caused by missed shader cache lookup hits in `MVKShaderLibraryCache`. - Log enhanced command buffer errors in debug mode. - Ensure queue submission message logging occurs before submission object is destroyed. - Remove project qualifiers from references to `SPIRV-Cross` header files. - Only perform automatic GPU capture on queue identified by `MVKConfiguration::defaultGPUCaptureScopeQueueIndex` and `defaultGPUCaptureScopeQueueFamilyIndex`. - Introduce `MVKConfigLogLevelBits`, `MVKConfigAutoGPUCaptureScopeBits`, and `MVKConfigTraceVulkanCallsBits` enums to specify config API values in a Vulkan-friendly manner, while automatically documenting the same values for env vars. - Add `MVKConfiguration::apiVersionToAdvertise` and `MVK_CONFIG_API_VERSION_TO_ADVERTISE` env var to configure **MoltenVK** to advertise a particular _Vulkan_ version. - Add `MVKConfiguration::advertiseExtensions` and `MVK_CONFIG_ADVERTISE_EXTENSIONS` env var to configure **MoltenVK** to force advertising support for no, or minimally few, _Vulkan_ extensions. - Remove the `Hologram` and `API-Samples` demo apps, and remove `LunarG/VulkanSamples` as a dependency library. - Add `NDEBUG` macro to all Release builds to remove `assert()` calls. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `31`. - Update dependency libraries to match _Vulkan SDK 1.2.176_. - Update to latest SPIRV-Cross version: - MSL: Support long `ulong` types in buffers in 2.3+. - MSL: Support padding Metal argument buffer entries based on argument index. - Add interfaces to aid with LTO-style optimization - Handle edge cases in `OpCopyMemory`. MoltenVK 1.1.2 -------------- Released 2021/02/22 - Advertise support for `shaderInt64` feature. - Support fast math on MSL compiler via `MVKConfiguration::fastMathEnabled` configuration setting and `MVK_CONFIG_FAST_MATH_ENABLED` environment variable (enabled by default). - Support compiling MSL with position invariance if indicated in SPIRV shader. - `vkGetMoltenVKConfigurationMVK()` and `vkSetMoltenVKConfigurationMVK()` functions can now be used with a `VkInstance` from another Vulkan layer, or with a `VK_NULL_HANDLE VkInstance`. - `MVKConfiguration` extended to cover all MoltenVK environment variables. - Report accurate value of 8 for `VkPhysicalDeviceLimits::maxBoundDescriptorSets`. - Advertise macOS M1 GPU as `VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU`. - For Vulkan semaphores, prefer using `MTLFence` over `MTLEvent`. - Support `immmutableSamplers` with sampler arrays. - Query pools write to dedicated temporary internal buffer to span multiple render passes and support larger query counts. - Fixes for race conditions in CTS multithread tests, guarding `MTLDevice` on cross-thread syncing. - Set Metal buffer alignment to 256 on non-Apple Silicon iOS/tvOS simulators. - `MVKMTLBufferAllocation`: Support device-local temp buffers for tessellation, indirect multiview, or occlusion queries buffer usage. - `MVKPixelFormats`: Enable `RenderTarget` usage for linear textures on Apple GPUs. - `MVKRenderPass`: Use a non-trivial granularity for TBDR GPUs. - Don't use barriers in render passes on Apple GPUs. - `MVKGraphicsPipeline`: Fix color write mask with `RGB9E5` RTs. - `MVKImagePlane`: When sync'ing, create the texture if it doesn't exist. - `MVKRenderPass`: Don't use `Load/Store` actions for memoryless. - `MVKRenderPass`: Only use `MTLStorageModeMemoryless` where available. - `MVKDeviceMemory`: Don't consider Memoryless host-accessible on *macOS/tvOS*. - `MVKCmdResolveImage` fix incorrectly changing first resolve layer's src/dst base layer. - `MVKPhysicalDevice`: Require Mac family 2 for render without attachments. - `MVKPhysicalDevice`: Disable SIMD-group permutation for Mac family 1. - `MVKPhysicalDevice`: Clamp maximum buffer range to 4 GiB - 1. - `MVKMTLBufferAllocation`: Mark temp buffers as volatile. - `SPIRVReflection`: Multiple entry point support for `getShaderOutputs()`. - Remove obsolete `MVKVector`, which was long ago replaced with `MVKSmallVector`. - Remove official support for submitting shaders directly containing MSL source code or compiled MSL code. MSL shaders may still be directly submitted, and may work, but it is not officially supported at this time. Future versions of **MoltenVK** may support direct MSL submission again. - Remove `ONLY_ACTIVE_ARCH` from Debug builds. **MoltenVK _Debug_** builds now build for all platform architectures. - Add ability to automatically capture first GPU frame by setting `MVKConfiguration::autoGPUCaptureScope` (or environment variable `MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE`) to `2`. - Support _GitHub Actions_ for CI builds on pull requests. - Support pre-built binary artifacts from _GitHub Actions_ CI builds. - `Makefile` and `fetchDependencies` support `xcpretty`, if available. - Remove support for _Travis-CI_. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `30`. - Update copyright notices to year 2021. - Update Xcode build settings check to _Xcode 12.4_. - Support legacy building on _Xcode 11.7_. - Update dependency libraries to match *Vulkan SDK 1.2.170*. - Update to latest SPIRV-Cross version: - MSL: Gracefully assign automatic input locations to builtin attributes. - MSL: Refactor out location consumption count computation. - MSL: Always return `[[position]]` when required. - MSL: Fix some edge cases in input attachment handling. - MSL: Fix various bugs with framebuffer fetch on macOS and argument buffers. - MSL: Always use input_attachment_index for framebuffer fetch binding. - MSL: Make sure initialized output builtins are considered active. - MSL: Always enable Outputs in vertex stages. - MSL: Only consider builtin variables and flatten builtin arrays if they are part of IO interface. - MSL: Handle load and store to TessLevel array in TESC. - MSL: Fixup type when using tessellation levels in TESC functions. - MSL: Fix automatic assign of builtin attributes in tessellation. - GLSL/MSL: Handle more complicated tessellation Output initializers. - MSL: Emit correct initializer for tessellation control points. - MSL: Handle initializers for tess levels. - MSL: Fix initializer for tess level outputs. - MSL: Fix broken reserved identifier handling for entry points. - MSL: Handle reserved identifiers for entry point. - Fix pathological complexity explosion for certain shaders. - Improve handling of complex variable initialization. - Expose position invariance. MoltenVK 1.1.1 -------------- Released 2020/12/09 - Add support for extensions: - `VK_KHR_sampler_mirror_clamp_to_edge` (iOS) - `VK_KHR_timeline_semaphore` - `VK_EXT_descriptor_indexing` (initial release limited to Metal Tier 1: 96/128 textures, 16 samplers) - `VK_EXT_post_depth_coverage` (macOS) - `VK_EXT_private_data` - `VK_EXT_subgroup_size_control` - `VK_EXT_texture_compression_astc_hdr` - `VK_AMD_shader_image_load_store` (macOS) - `VK_IMG_format_pvrtc` (macOS) - Support the *Mac Catalyst* platform for *iOS* apps on *macOS 11.0+*, under both `x86_64` and `arm64` architectures. - Re-enable `MTLEvent`-based semaphores and fix several `MVKSync` issues. - Use `VK_KHR_image_format_list` to disable `MTLTextureUsagePixelFormatView` if only swizzles or `sRGB` conversion will be used for image views, improving performance on *iOS* by allowing Metal to use lossless texture compression. - Handle device loss. - Fix crash in `vkUpdateDescriptorSets()` when copying inline block descriptors. - Fix Metal validation error when unused elements in an array of sampler are not populated by descriptors. - Fix crashes in `vkUseIOSurfaceMVK()` on chroma sampling and double releasing of`MTLTexture`. - Fix potential drawable present race conditions. - Fix crash in `vkUpdateDescriptorSets()` when copying inline block descriptors. - Fix Metal validation error when unused elements in an array of sampler are not populated by descriptors. - Move *Metal* drawable presentation from `MTLCommandBuffer` to `MTLDrawable` to improve performance and reduce blocking. - Allow binding descriptor set using layout different than it was created with. - Report `VkPhysicalDeviceLimits::maxPerStageDescriptorStorageImages` as Metal limit of `8`. - Increase per-stage texture count to `96` for A11 SoC's and above. - Use variable descriptor count when determining descriptor binding count. - Support setting sizes of SPIR-V unsized arrays. - Support `MTLStorageTypeMemoryless` for Apple Silicon on Mac. - Support Apple GPU pixel formats with Apple Silicon on Mac. - Allow linear images on Apple GPUs in Blit and Clear commands. - Apple family 7 GPUs (A14) on iOS support multisample layered rendering, as well as sampler border colors and the mirror clamp to edge sampler address mode. - Set fill mode, depth bias, viewport, and scissor states before clearing attachments - Disable culling for the duration of `vkCmdClearAttachments()` - `MVKDevice` increase minimum OS for shared-storage textures. - `MVKDevice` set properties for Apple Silicon GPUs on macOS. - `MVKQueue` only create one `GPUCaptureScope` per queue. - `MVKSamplerYcbcrConversion` always make sure there is one plane. - `MVKPhysicalDevice` correct fragment input component limit. - `MVKPhysicalDevice` set max visibility buffer size to 256 kiB where supported. - `MVKPhysicalDevice` expose support for interpolation functions. - `MVKPhysicalDevice` enable 3D compressed textures on *iOS/tvOS*, and forbid ETC2 and EAC 3D textures on all platforms. Apple GPUs do not support 3D for those. - `MVKPhysicalDevice` enable Apple family 7 features on *iOS*. - `MVKPhysicalDevice` remove need to call `initGPUInfoProperties()` twice. - `MVKPhysicalDevice` correct max descriptor set resources. - `MVKPhysicalDevice` reduce maximum point size to 64. - `MVKPhysicalDevice` enable strictLines for Intel and NVIDIA. - `MVKPhysicalDevice` enable `shaderResourceMinLod` on *iOS*. - `MVKPhysicalDevice` set correct subgroup properties. - `MVKPhysicalDevice` enable texture swizzle on all Apple GPUs. - `MVKPipelineLayout` only set configuration result if validating. - `MVKPipeline` fix calculation of atomic image buffer addresses. - `MVKPipeline` disable rasterization if culling both sides and don't try to add a fragment shader. - `MVKPipeline` shorten vertex attribute format's length when `stride` < `size`. - `MVKGraphicsPipeline` handle `minSampleShading`. - `MVKImage` always use texel buffers for linear images in `MTLHeaps`. - `MVKImage` make sure plane heap offsets are properly aligned. - `MVKImage` always set the depth plane when rendering to a 3D image. - `MVKImage` avoid swizzling storage and/or attachment image views. - `MVKImage` avoid texel buffer for atomics if view format list exists and does not include either `R32_UINT` or `R32_SINT` format. - `MVKImageView` always ignore transfer usages. - `MVKBufferView` avoid triggering `bytesPerRow` validation warning. - `MVKDescriptorSetLayout` speed up lookup of descriptor index and streamline binding access. - `MVKCmdBlitImage` use layered draws when possible. - `MVKCmdBlitImage` add 0.5 to layer index before interpolating. - `MVKCmdBlitImage` support depth/stencil blits with inversion and scaling. - `MVKSwapchain` allow images whose size doesn't match the `CAMetalLayer`. - `MVKPixelFormats` add 0.5 ULP to clear values for normalized formats. - `MVKCommandEncoder` don't set `renderTargetArrayLength` for mixed 2D/3D renders. - `MVKExtensions` add missing *tvOS* case for unsupported extensions. - `MVKDescriptorSetLayout` sort and hold bindings by binding number. - `MVKDescriptor` simplify subclass implementations. - `MVKComputePipeline` override max threads per threadgroup. - `MVKGPUCapture` make sure the `MTLCaptureScope` has only one reference. - `MoltenShaderConverter` fix *tvOS* build to support *tvOS 9.0*. - Support building external libraries and dylibs against sanitizers. - Clarify documentation on mapping limitations for host-coherent image memory on *macOS*. - Add validation policy for MoltenVK development to `README.md` document. - Update Xcode build settings check to Xcode 12.2. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `29`. - Update dependency libraries to match *Vulkan SDK 1.2.162*. - Update to latest SPIRV-Cross version: - MSL: Support `SPV_EXT_demote_to_helper_invocation` for MSL 2.3. - MSL: Support run-time sized image and sampler arrays (`GL_EXT_nonuniform_qualifier/SPV_EXT_descriptor_indexing`). - MSL: Support atomic access to images from argument buffers. - MSL: Add missing interlock handling to atomic image buffers. - MSL: Fix calculation of atomic image buffer address. - MSL: Support querying and modifying generated combined sampler suffix. - MSL: Don't use a bitcast for tessellation levels in tesc shaders. - MSL: Handle Offset and Grad operands for 1D-as-2D textures. - MSL: Don't remove periods from swizzle buffer index exprs. - MSL: Correct definitions of subgroup ballot mask variables. - MSL: Extract global variables from subgroup ballot operations. - MSL: Mask ballots passed to ballot bit ops. - MSL: Don't mask off inactive bits in ballot masks. - MSL: Support vectors with `OpGroupNonUniformAllEqual`. - MSL: Cast broadcast booleans to `ushort`. - MSL: Do not use `component::x` gather for `depth2d` textures. - MSL: For 2.1+, don't disable rasterization for vertex writes. - MSL: Allow post-depth coverage on Mac in MSL 2.3. - MSL: Allow framebuffer fetch on Mac in MSL 2.3. - MSL: Allow Bias and Grad arguments with comparison on Mac in MSL 2.3. - MSL: Support pull-model interpolation on MSL 2.3+ - MSL: Expand subgroup support. - MSL: Adjust `FragCoord` for sample-rate shading. - MSL: Expose some more features on iOS: `min_lod_clamp()`, `simd_is_helper_thread()`, `barycentric_coord`, and `primitive_id`. - MSL: Don't add fixup hooks for builtin variables if they're unused. - MSL: Don't try to use `[[thread_index_in_simdgroup]]` in vertex shaders. - Handle case where block is loop header, continue AND break block. - MSL: Added `fmin3` and `fmax3` library functions to the illegal name list. - Added Metal keyword: `level`. - Parser: Don't assume `OpTypePointer` will always take a `SPIRType`. - Add MIT dual license for the SPIRV-Cross API and CLI. MoltenVK 1.1.0 -------------- Released 2020/09/28 >**_Note:_** This release contains changes to library paths and framework linking options. - Add support for Vulkan 1.1, including: - The `vkEnumerateInstanceVersion()` function - The `vkGetDeviceQueue2()` function - Protected memory (non-functional) - A feature struct for `VK_KHR_shader_draw_parameters` - All extensions that were promoted to core in Vulkan 1.1 - Add support for extensions: - `VK_KHR_portability_subset` - `VK_KHR_create_renderpass2` - `VK_KHR_depth_stencil_resolve` - `VK_KHR_external_fence` (non-functional groundwork for future extensions, including support for GCD and Mach semaphores) - `VK_KHR_external_fence_capabilities` (non-functional groundwork for future extensions, including support for GCD and Mach semaphores) - `VK_KHR_external_semaphore` (non-functional groundwork for future `MTLSharedEvent` Vulkan extension) - `VK_KHR_external_semaphore_capabilities` (non-functional groundwork for future `MTLSharedEvent` Vulkan extension) - `VK_KHR_multiview` - `VK_KHR_shader_subgroup_extended_types` - Remove support for obsolete `VK_EXTX_portability_subset` extension. - Redesign build and linking options that leverage newer framework technology: - Add comprehensive support for multi-platform, multi-architecture `XCFrameworks`. - Build fat single-platform, multi-architecture `dylibs`. - Add support for *Apple Silicon* builds for *macOS* and *Simulators*. - Remove support for distinct legacy frameworks and static libraries. - Remove support for fat libraries and frameworks that span device and simulators. - Combine `MoltenVKSPIRVToMSLConverter` and `MoltenVKGLSLToSPIRVConverter` frameworks into a single `MoltenVKShaderConverter` framework. - Support copying between 3D and 2D images. - Support clearing 3D images. - Support linear images and buffer views in shared memory on *macOS 10.15.5+*. - Support `VK_IMAGE_CREATE_EXTENDED_USAGE_BIT`. - Support multiple aliased images for dedicated image memory allocations. - Improve performance of tessellation control pipeline stage by processing multiple patches per workgroup. - `vkCmdBindDescriptorSets` order `pDynamicOffsets` by descriptor binding number within each descriptor set. - `vkCmdCopyImage` on macOS flush non-coherent image memory before copy operation. - Process multiple patches per workgroup in a tessellation control shader. - Initialize tessellation related variables conditionally in indirect draws. - Fix build errors on Simulator not supporting `MTLDrawable` present time options. - Fix `dynamicOffsets` ordering based on binding index. - Ensure the base texture is created when creating a view texture. - Fix features, alignment, and image properties of chroma subsampled formats. - Disable `variableMultisampleRate` feature. - Permit renderpass to have no attachments. - Clear linear images using a compute shader. - Reject attempts to create compressed linear images. - Always use a texel buffer for atomic linear storage images. - Use deferred store actions instead of tracking multi-pass draws. - Use `MTLRenderPassDescriptor renderTargetWidth` and `renderTargetHeight` on macOS 10.15 and newer. - Use a 2D non-arrayed view for 2D non-arrayed attachments. - Use arrayed textures for layered subpass input. - Use layered rendering when clearing or resolving images whenever possible, and take `renderArea` into account. - Streamline image copying when the entire source is being copied to the entire destination. - Don't set `renderTargetArrayLength` on devices that don't support it. - Don't attempt to clear unused attachments and fix vertex count for clearing multiple layers. - Don't encode commands that draw zero vertices. - Ignore `addressModeW` on samplers with unnormalized coordinates. - Flip GPU when swapchain is created, not when device object is created, to optimize this condition if it is not needed. - Flush source image of a transfer on *macOS*. - Fix offset for texel buffers and heaps for multi-planar images. - Fix memory leak when object create fails. - Fix several use-after-freed errors. - Fix applying divisors to instanced vertex attributes. - Fix issue in accessing `MTLTexture` for swapchain image planes. - Fix occasional crash on vertex stage indirect draws. - Fix reported image format properties for 1D images as 2D. - `VK_EXT_vertex_attribute_divisor` fix issues with zero divisors. - Re-add support for bitcode generation on *iOS* and *tvOS*. - `fetchDependencies` builds serially by default for better build script integration. - Combine `MoltenVKSPIRVToMSLConverter` and `MoltenVKGLSLToSPIRVConverter` frameworks into a single `MoltenVKShaderConverter` framework. - Fix Metal validation error when occlusion query and renderpass are in separate Vulkan command buffers. - Fix a crash on starting a query outside a render pass. - Fix Metal validation error that forbids rendering to an image of zero size. - Fix issue where descriptor pool releasing descriptor sets it doesn't own. - Fix issue where load/store actions not set in renderpass that includes compute stage. - Prevent accidental `setColorStoreAction` for non-color attachments. - Fix image copy destination extent of compressed images. - Fix image resolve sub-region extent. - Fix owner of merged `MVKShaderLibraries`. - Fix rounding of buffer sizing when `VK_WHOLE_SIZE` is used. - Fix detection of indexed draw calls. - `vkSetMTLTextureMVK()` Fix crash if incoming `MTLTexture` does not have an associated `IOSurface`. - Update dependency libraries to match *Vulkan SDK 1.2.154*. - Update to latest SPIRV-Cross version: - MSL: Fix handling of matrices and structs in the output control point array. - MSL: Enclose args when convert `distance(a,b)` to `abs(a-b)`. - MSL: Fix multiview view index calculation with a non-zero base instance. - MSL: Don't set the layer for multiview if the device doesn't support it. - MSL: Fix `OpCompositeInsert` and `OpVectorInsertDynamic`. - MSL: Support layered input attachments. - Ensure that we use primary alias type when emitting flattened members. - Only rewrite type aliases for the base type. - Overhaul how we deal with reserved identifiers. - Implement a simple evaluator of specialization constants. - Deal with case where a selection construct conditionally merges/breaks. - Allow `flip_vert_y` in all relevant stages. - Clean up conditional branch codegen. MoltenVK 1.0.44 --------------- Released 2020/07/28 - Add support for extensions: - `VK_KHR_driver_properties` - `VK_KHR_sampler_ycbcr_conversion` - `VK_EXT_image_robustness` - `VK_EXT_robustness2` - Add native support for `VK_FORMAT_D16_UNORM` on **_iOS 13.0+_** and **_tvOS 13.0+_**. - 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. - `vkCmdBlitImage()` returns error if scaling or inverting to linear image on *macOS*. - Support `VK_FORMAT_A2B10G10R10_UNORM_PACK32` as a surface format. - Support `VkPipelineMultisampleStateCreateInfo::pSampleMask`. - Support `VkPhysicalDeviceSubgroupProperties`. - Fix memory layout of inline uniform blocks. - Fix issue where mapped host-coherent device memory not updated from image contents on *macOS*. - Fix image memory sizing and offsets. - Fix small memory leak when setting swapchain color space. - Fix new and unexpected App Store failure on newly deprecated color space values. - Fix intermittent concurrent shader specialization race condition. - Fix offsets when flushing buffer data to GPU. - Fix issue where expected buffer-sizes buffer not bound to Metal compute encoder. - Ensure fragment shader inputs to have as many components as vertex shader outputs. - Include vertex attribute size when testing whether attribute offset exceeds stride. - Add support for `USCALED/SSCALED` vertex formats. - Add host-coherent texel buffer caching just for buffer views. - Include MoltenVK Git revision hash in `VkPhysicalDeviceProperties::pipelineCacheUUID`. - Add `MVKPhysicalDeviceMetalFeatures::vertexStrideAlignment` to track Metal vertex binding stride alignment. - Add `MVKPhysicalDeviceMetalFeatures::indirectTessellationDrawing` to track if indirect tessellation drawing is supported. - Remove use of `@available()` directive as it was causing issues in some build environments. - Pass pipeline sample mask, if present, to SPIRV-Cross. - Refactor **MoltenVK** *Xcode* build architectures. - Demo `API-Samples generateSPIRVShaders` no longer builds `MoltenVKShaderController` tool. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `27`. - Update dependency libraries to match *Vulkan SDK 1.2.148*. - Update to latest SPIRV-Cross version: - MSL: Add support for processing more than one patch per workgroup. - MSL: Workaround broken scalar access chain behavior in MSL LLVM IR / AIR. - MSL: Do not emit swizzled writes in packing fixups. - MSL: Ensure `OpStore` source operands are marked for inclusion in function arguments. - MSL: Enabling setting an additional fixed `sampleMask` in fragment shaders. - MSL: Remove obsolete `MSLVertexAttr` and `MSLShaderInput` members. - MSL: Fix up input variables' vector lengths in all stages. - MSL: Improve handling of array types in buffer objects. - MSL: Deal with loading non-value-type arrays. - MSL: Deal with array load-store in buffer-block structs. - MSL: Use input attachment index directly for resource index fallback. - Fix missing switch cases in `Y'CbCr` conversion. - Implement context-sensitive expression read tracking. MoltenVK 1.0.43 --------------- Released 2020/06/09 - Fix issue in reporting properties of substitutable `VkFormats`. - Fix vertex attribute offset adjustments when vertex buffer stride is zero. - Update `fetchDependencies` script to use pre-built `spirv-tools` files by default. - Update `maxVertexInputBindingStride` and `maxVertexInputAttributeOffset` to minimum Vulkan values. - Numerous documentation typo corrections. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `26`. - Update Travis CI to Xcode 11.5. MoltenVK 1.0.42 --------------- Released 2020/06/01 - Add support for extensions: - `VK_GOOGLE_display_timing` - `VK_KHR_external_memory` (non-functional groundwork for future Metal-resource Vulkan extension). - `VK_KHR_external_memory_capabilities` (non-functional groundwork for future Metal-resource Vulkan extension). - Memory consumption improvements in command handling and vector pre-allocation optimizations. - `vkQueuePresentKHR()` returns a `VkResult` for each swapchain. - `MVKPipeline` disable fragment shader outputs for unused attachments. - `MVKBuffer` support texel buffers in host-coherent memory on Mac. - `MVKDescriptor` pass buffers to shaders that do atomic image accesses. - Support vertex attribute offsets larger than the vertex buffer stride. - Fix crash when more than two GPUs. - Fix issue where `vkGetPhysicalDeviceFormatProperties()` incorrectly returned properties for unsupported formats. - Fix stack overflow in when logging and reporting very long messages. - Fix situation where compute pipeline state not retained across copy and renderpass operations. - Fix buffer offset calculation. - Fixes to maximum FPS calculations. - Fix buffer size passed to shaders when `VkDescriptorBufferInfo.range` set to `VK_WHOLE_SIZE`. - Update maximum number of framebuffer layers to 2048. - Support stencil only image formats in identity swizzle case. - Enables format atomic capabilities only when format supports it. - Add `MVKSmallVector` as a more memory efficient substitute of `MVKVector`. - Reinstate `VulkanSamples API-Samples` demo apps and add `input_attachment` and `push_descriptors` demos. - Add `MVK_CONFIG_AUTO_GPU_CAPTURE_OUTPUT_FILE` environment variable to support capturing GPU traces to a file. - Consolidate frame and non-frame performance reporting. - Remove `vkGetSwapchainPerformanceMVK()` from API. - Swapchain performance can be retrieved with other activity performance through `vkGetPerformanceStatisticsMVK()`. - Add `MVK_CONFIG_PERFORMANCE_LOGGING_INLINE` env var to enable/disable logging of performance of each activity when it happens. - Reduce thread locking on performance statistics collection. - Numerous documentation typo corrections. - Support Xcode 11.5. - Update dependency libraries to match *Vulkan SDK 1.2.141*. - Update to latest SPIRV-Cross version: - MSL: mark `BuiltInFragCoord` as implicitly used for subpass reads. - MSL: Deal with cases where builtin is implicitly needed, declared, but unused. - MSL: Do not use base expression with PhysicalTypeID `OpCompositeExtract`. - MSL: Add options to control emission of fragment outputs. - MSL: Force disabled fragment builtins to have the right name. - MSL: Allow removing clip distance user varyings. - MSL: Support edge case with DX layout in scalar block layout. - MSL: Deal correctly with initializers on Private variables. - MSL: Fix case where `subpassInput` is passed to leaf functions. - MSL: Redirect member indices when buffer has been sorted by Offset. - MSL: If the packed type is scalar, don't emit "pack_" prefix. - MSL: Avoid packed arrays in more cases. - Do not add NonWritable/NonReadable decorations for regular images. - Expose a query if samplers or images are comparison resources. MoltenVK 1.0.41 --------------- Released 2020/04/05 - Accurately populate Vulkan `VkFormatProperties` from `MTLPixelFormat` capabilities, taking into consideration variations across `MTLDevice` Features Sets. - Validate format capabilities for MSAA, renderpass attachments, and `vkCmdResolveImage()`. - Fix issue where immutable samplers are removed during descriptor update. - Guard against Metal validation assertion from reuse of query number within a single `MTLRenderEncoder`. - Increase value of `VkPhysicalDeviceLimits::minStorageBufferOffsetAlignment` to `16` to avoid Metal validation assertions. - Add ability to disable command memory pooling using `MVK_CONFIG_USE_COMMAND_POOLING` environment variable. - Fix memory leak when pre-filling `MTLCommandBuffers` using `MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS`. - Fix issue causing screen captures from swapchain image to deadlock. - Fix memory estimates for iOS 13+. - Broaden conditions for host read sync for image memory barriers on macOS. - Fix issue of reseting `CAMetalDrawable` and `MTLTexture` of peer swapchain images. - Fix occasional missing Metal buffer binding when only offset changes. - Fix the `make install` build command to overwrite the existing framework in the system framework library, and update `README.md` to clarify the instructions for using `make install`. - Update the `README.md` and `MoltenVK_Runtime_UserGuide.md` documents to clarify that **MoltenVK** is not a fully-compliant implementation of *Vulkan*. - Support Xcode 11.4. - Disable `API-Samples` demos and document in `Demos/README.md`. - Update dependency libraries to match *Vulkan SDK 1.2.135*. - Update to latest SPIRV-Cross version: - MSL: Support inline uniform blocks in argument buffers. - MSL: Move inline uniform blocks to the end of the argument buffer. - MSL: Fix access chain for deep struct hierarchy on array of buffers. - MSL: Remove old memory_scope flag from iOS barriers. - MSL: Fixes to array handling. MoltenVK 1.0.40 --------------- Released 2020/01/22 - Refactor descriptor management to reduce memory footprint and fix caching leak. - Add `MVK_CONFIG_PREALLOCATE_DESCRIPTORS` environment variable to support preallocated descriptor pooling within a `VkDescriptorPool` via the `VkDescriptorPoolSize` values. - Fix crash when app does not use queue family zero. - Fix buffer offset in `vkCmdPushDescriptorSet()` for non-dedicated buffer memory. - Fix Metal validation error on push constant sizing differences between C and MSL structs. - Use `MTLBuffer` when inline uniform block descriptor is written to instead of copying host-side bytes. - Fix `EXT_inline_uniform_block` when using push descriptor sets. - Merge buffer and inline unions to fix issue where binding inline descriptor would interfere with future binds on the same set index in the same command buffer (now only used in push case anyway). - Track performance of `CAMetalLayer nextDrawable` call. - Document recommendation to use 3 swapchain images, particularly with full-screen rendering. - Update `MoltenVK_Runtime_UserGuide.md` to better explain runtime environment variables. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `24`. - Update copyright notices to year 2020. - Update dependency libraries to match *Vulkan SDK 1.2.131*. - Update to latest SPIRV-Cross version: - MSL: Support `ClipDistance` as an input stage variable. - MSL: Fix automatic binding allocation for image atomic buffers. - MSL: Deal with packing vectors for vertex input/fragment output. - MSL: Don't set `OrigID` when emitting component packed vectors. - MSL: Add trivial tests for `Component` decoration. - MSL: Deal with padded fragment output + `Component` decoration. - MSL: Partially implement support for Component decoration in complex scenarios. - MSL: Explicitly don't support component packing for tessellation. - MSL: Deal with sign on wave `min/max`. - MSL: Add support for force-activating IAB resources. - Deal with illegal names in types as well. - Basic implementation of `OpCopyLogical`. - Fix sign handling for `S/UToF`. - Fix uninitialized memory issue. - Roll custom versions of `isalpha/isalnum`. - Update license headers to year 2020. MoltenVK 1.0.39 --------------- Released 2019/12/16 - Add support for extensions: - `VK_EXT_inline_uniform_block` - Support linear filtering when using `vkCmdBlitImage()`. - Clamp image copy extents to image extent. - Fix crash in `fetchDependencies` on build paths containing spaces. - Fix image subresource sizing calculations for heap-based textures. - Fix `MTLHeap` memory leak in `MVKDeviceMemory`. - Fix tessellation break when control stage declares but does not use position builtin. - Fix inconsistency in reporting device local memory between type and heap on macOS. - Fix bug where dynamic shader buffers are overflowing. - Avoid reading env vars inside library constructor functions. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `23`. - Cube demo use `VK_EXT_metal_surface` extension. - Support *Xcode 11.3*. - Update dependency libraries to match *Vulkan SDK 1.1.130*. - Update to latest SPIRV-Cross version: - MSL: Rewrite `tessellation_access_chain()`. - MSL: Report tess input array failures more accurately. - MSL: Deal with chained access chains for tessellation IO variables. - MSL: Fix array of array declaration. - MSL: Declare struct type explicitly. - MSL: Declare arrays with proper type wrapper. - MSL: Remove workaround for passing constant arrays to functions. - MSL: Fix unpacking of column from padded matrix. - MSL: Fix integer cast. - MSL: Add missing reference output. - MSL: Ensure stable output for access chain CFG workarounds. - MSL: Remove stray `allow_id_rewrite()`. - MSL: Do read-only lookups of access_chain_children. - MSL: Do not declare variables which will not be unflattened. - MSL: Rewrite propagated depth comparison state handling. - MSL: Do not declare array of UBO/SSBO as `spvUnsafeArray`. - MSL: Remove dubious workaround code in `unpack_expression()`. - MSL: Remove hacky workaround for patch constant passing. - MSL: Revert hack with `kBufferSizeBufferBinding`. - MSL: Remove stale code for texture swizzle. - MSL: Avoid some fallthrough warnings. - Expose as public `Compiler::update_active_builtins()` and `has_active_builtin()`. - Implement constant empty struct correctly on all backends. - Mark loop headers as complex as early as possible. - Clean up call to `builtin_translates_to_nonarray()`. - Fix broken access tracking for `OpFunctionCall` results. - Avoid including stdexcept in no-exception environment. - Add `spvc_type_get_base_type_id()`. MoltenVK 1.0.38 --------------- Released 2019/10/30 - Add support for Metal 3.0 capabilities. - Add support for extensions: - `VK_EXT_swapchain_colorspace` (*iOS*, already supported on *macOS*). - `VK_EXT_hdr_metadata` (*macOS*) - Use native texture swizzling when available. - Set default value of the `MVK_ALLOW_METAL_FENCES` environment variable to `1 (true)`, to enable use of `MTLFence` for Vulkan semaphores, by default. - Support additional capabilities in 1D images, including rendering, clearing, and mipmaps. Add `MVK_CONFIG_TEXTURE_1D_AS_2D` environment variable to enable/disable these capabilities. - Use placement `MTLHeaps` for `VkDeviceMemory` when possible. - Report heap sizes accurately when possible. - Add support for additional colorspace options. - Add support for the `VkPhysicalDeviceFeatures::shaderResourceMinLod` feature. - Add support for compressed 3D images on *macOS*. - Update `MoltenVK_Runtime_UserGuide.md` about embedding `libMoltenVK.dylib` in an application. - Clarify static linking as the recommended linking approach for *iOS* app store distribution. - Add request for feedback from people who reject **MoltenVK** to `README.md` document. - Allow `MVK_CONFIG_SYNCHRONOUS_QUEUE_SUBMITS` build setting to be overridden. - Fix memory leaks of system classes during `VkInstance` and `VkQueue` creation. - Fix memory leaks when compiling shaders and pipelines without default OS autorelease pool. - Fix severe FPS degradation caused by certain swapchain recreation situations. - Log format substitution error when `MTLPixelFormatDepth24Unorm_Stencil8` is not supported. - Reduce memory usage by adjusting default memory allocs for many `MVKVectorInline` uses and replacing use of `MVKVectorDefault` with `std::vector` in descriptor set bindings. - Set value of `VkPhysicalDeviceLimits::maxTexelBufferElements` to more realistic value. - Add linking separate shader texts to `GLSLToSPRIVConverter`. - Move generation of `SPIRV-Cross/mvkSpirvCrossRevisionDerived.h` to separate script. - Support *Xcode 11.1*. - Update dependency libraries to match *Vulkan SDK 1.1.126*. - Update to latest SPIRV-Cross version: - MSL: Support option for treating 1D textures as 2D textures of height 1. - MSL: Fix array copies to/from interpolators. - MSL: Fix 16-bit integer literals. - MSL: Fix regression with `OpCompositeConstruct` from `std140 float[]`. - Fixes cases where discard and demote are called in pure functions and the function result is not consumed. - Do not consider aliased struct types if the master is not a block. - Fix `OpVectorExtractDynamic` with spec constant op index. - Update SPIR-V headers to SPIR-V 1.5. MoltenVK 1.0.37 --------------- Released 2019/09/10 - Add support for extensions: - `VK_KHR_device_group` - `VK_EXT_fragment_shader_interlock` - Add support for `VkEvent`, using either native `MTLEvent` or emulation when `MTLEvent` not available. - `vkInvalidateMappedMemoryRanges()` synchronizes managed device memory to CPU. - Track supported instance and device extensions correctly. - Revert to supporting host-coherent memory for linear images on macOS. - Report limit of 64KB for constant buffer bindings on macOS. - Disable depth and/or stencil testing if corresponding attachment is missing. - Ensure Vulkan loader magic number is set every time before returning any dispatchable Vulkan handle. - Fix crash when `VkDeviceCreateInfo` specifies queue families out of numerical order. - Fix crash in `vkDestroyPipelineLayout()`. - Fix crash when signalling swapchain semaphore using `MTLEvent`. - Fix crash when determining alignment of invalid pixel formats. - `vkCmdBlitImage():` Support format component swizzling. - `vkCmdClearImage():` Set error if attempt made to clear 1D image, and fix validation of depth attachment formats. - `vkCreateRenderPass():` Return `VK_ERROR_FORMAT_NOT_SUPPORTED` if format not supported. - `vkCmdFillBuffer():` Improve performance 150x by using parallelism more effectively. - Support optional use of `MTLFence` for Vulkan semaphores via the `MVK_ALLOW_METAL_FENCES` environment variable. - Remove error logging on `VK_TIMEOUT` of `VkSemaphore` and `VkFence`. - Remove log message warning of obsolescence of `vkCreateMacOSSurfaceMVK()` and `vkCreateIOSSurfaceMVK()` functions. - Report error only on the first time a format substitution is made. - Streamline design and use of `MVKSemaphore`. - Consolidate the various linkable objects into a `MVKLinkableMixin` template base class. - Use `MVKVector` whenever possible in MoltenVK, especially within render loop. - No longer prefer dedicated allocations for buffer memory, including buffer-backed images. - Handle the `compositeAlpha` member of `VkSwapchainCreateInfoKHR`. - `VkPhysicalDevicePortabilitySubsetFeaturesEXTX::events` set to `true`. - Always submit surface presentations using `MTLCommandBuffer`. `MVKConfiguration::presentWithCommandBuffer` is now obsolete. - Don't use `MTLCommandBuffer push/popDebugGroup` if not available. - `MVKSwapchain::signalWhenAvailable()` add autoreleasepool around `MTLCommandBuffer` use. - Add ability to automatically cause an *Xcode* GPU capture without developer intervention. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to version 22. - Update to renaming of `VK_INTEL_shader_integer_functions2` enums and structs in latest Vulkan headers. - Update dependency libraries to match *Vulkan SDK 1.1.121*. - Update to latest SPIRV-Cross version: - Support the `SPV_EXT_fragment_shader_interlock` extension. - MSL: Deal with array copies from and to threadgroup. - MSL: Deal with `Modf/Frexp` where output is access chain to scalar. - MSL: Inline all emitted functions. - MSL: Inline all non-entry-point functions. - MSL: Add `{Base,}{Vertex,Instance}{,Index}` to `bitcast_from_builtin_load`. - MSL: Add support for sampler Y'CbCr conversion. - MSL: Force storage images on iOS to use discrete descriptors. - MSL: Support dynamic offsets for buffers in argument buffers. - MSL: Cleanup temporary use with `emit_uninitialized_temporary`. - MSL: Unify the `get_*_address_space()` methods. - Assume image and sampler can be `RelaxedPrecision`. - Fix post-depth coverage for ESSL. - Fix variable scope when switch block exits multiple times. - Fix severe performance issue with invariant expression invalidation. - Fix `ParsedIR::mark_used_as_array_length(uint32_t id)` - Deal correctly with sign on bitfield operations. - Elide branches to continue block when continue block is also a merge. - Move branchless analysis to CFG. - Deal with `ldexp` taking `uint` input. - Do not allow base expressions for non-native row-major matrices. - Do not force temporary unless continue-only for loop dominates. - Fix `ParsedIR::mark_used_as_array_length(uint32_t id)`. - Refactor into stronger types in public API. MoltenVK 1.0.36 --------------- Released 2019/07/25 - Add support for extensions: - `VK_KHR_device_group_creation` - `VK_KHR_swapchain_mutable_format` - `VK_KHR_uniform_buffer_standard_layout` - `VK_EXT_metal_surface` - `VK_EXT_post_depth_coverage` - `VK_EXT_scalar_block_layout` - `VK_EXT_shader_stencil_export` - `VK_EXT_swapchain_colorspace` (*macOS*) - `VK_EXT_texel_buffer_alignment` - `VK_AMD_shader_image_load_store_lod` - `VK_AMD_shader_trinary_minmax` - `VK_INTEL_shader_integer_functions2` - Support `VK_FORMAT_A2R10G10B10_UNORM_PACK32` as a surface format and view format. - For shaders created directly from MSL, set function name from `VkPipelineShaderStageCreateInfo::pName`. - On iOS GPU family 2 and earlier, support immutable depth-compare samplers as `constexpr` samplers hardcoded in MSL. - `vkCmdCopyImage()` support copying between compressed and uncompressed formats and validate that formats are compatible for copying. - `vkCmdBufferImageCopy()` fix crash when setting bytes per image in non-arrayed images. - `vkCmdBlitImage()` supports blit between different texture formats, and multisampled images. - `vkCmdResolveImage()` supports textures of different sizes. - `vkCmdClearImage()` returns error if texture is not renderable. - Move push constant binding to `vkCmdBindPipeline()` from `vkCmdBindDescriptorSet()`. - `MVKDeviceMemory` keep `MTLResourceOptions` aligned with `MTLStorageMode` & `MTLCPUCacheMode`. - Texture memory requirements don't use shared storage on macOS. - Add `MTLCommandBuffer` completion timing performance tracking option. - Expand `MVK_CONFIG_TRACE_VULKAN_CALLS` to optionally log Vulkan call timings. - Skip `SPIRV-Tools` build in Travis because Travis does not support the required Python 3. - Separate `SPIRVToMSLConverterContext` into input config and output results. - Use native Metal texture buffers when available. - Fix issue with push constants used across multiple draw calls not being applied. - Fix memory leak in debug marker and debug utils labelling. - Reduce memory leaks when autorelease pools are not available. - Fix pipeline cache lookups. - Fix race condition between swapchain image destruction and presentation completion callback. - Set Metal texture usage to allow texture copy via view. - Fix memory leak in debug marker and debug utils labelling. - Fix issue with push constants used across multiple draw calls not being applied. - Fix crash when binding descriptor set to layout that has been destroyed and recreated. - Return error when `MVKImage` created as 1D attachment. - Reduce use of autoreleased Obj-C objects, and ensure those remaining are covered by deliberate autorelease pools. - Document that the functions in `vk_mvk_moltenvk.h` cannot be used with objects retrieved through the *Vulkan SDK Loader and Layers* framework. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 21. - Update dependency libraries to match Vulkan SDK 1.1.114. - Update to latest SPIRV-Cross version: - MSL: Support `SPV_KHR_multiview` extension. - MSL: Support the `SPV_KHR_post_depth_coverage` extension. - MSL: Support the `SPV_AMD_shader_trinary_minmax` extension. - MSL: Support the `SPV_KHR_device_group` extension. - MSL: Support the `SPV_INTEL_shader_integer_functions2` extension. - MSL: Support `SubgroupSize` / `SubgroupInvocationID` in fragment. - MSL: Support `OpImageQueryLod`. - MSL: Support `MinLod` operand. - MSL: Support `PrimitiveID` in fragment and barycentrics. - MSL: Support 64-bit integers. - MSL: Support `OpOuterProduct`. - MSL: Support `SubgroupLocalInvocationId` and `SubgroupSize` in all stages. - MSL: Support scalar reflect and refract. - MSL: Support scalar block layout. - MSL: Use the `select()` function for `OpSelect`. - MSL: Handle `coherent`, `volatile`, and `restrict`. - MSL: Refactor buffer packing logic from ground up. - MSL: Fix alignment of packed types. - MSL: Handle packed matrices. - MSL: Conditionally validate MSL 2.2 shaders. - MSL: Rewrite how resource indices are fallback-assigned. - MSL: Support custom bindings for argument buffers. - MSL: Fix sampling with `FP16` coordinates. - MSL: Deal with scalar input values for distance/length/normalize. - MSL: Error out on `int64_t/uint64_t` buffer members as unsupported by Metal. - MSL: Deal with scalar input values for distance/length/normalize. - MSL: Re-roll array expressions in initializers. - MSL: New SDK errors out on cull distance. - Rewrite how switch block case labels are emitted. - Fixes to handling of `OpPhi` and case fallthrough. - Fix declaration of loop variables with a `OpPhi` helper copy. - Handle more cases with FP16 and texture sampling. - Fix variable scope when an `if` or `else` block dominates a variable. - Fall back to complex loop if non-trivial continue block is found. - Remove unreasonable assertion for `OpTypeImage Sampled` parameter. - Propagate NonUniformEXT to dependent expressions. - Deal correctly with return sign of bitscan operations. MoltenVK 1.0.35 --------------- Released 2019/06/13 - Add support for extensions: - `VK_EXT_debug_report` - `VK_EXT_debug_marker` - `VK_EXT_debug_utils` - `VK_NV_glsl_shader` - Support setting workgroup size for shader modules that use MSL directly instead of converting from SPIR-V. - Tessellation fixes: - Don't use `setVertexBytes()` for passing tessellation vertex counts. - Fix intermediate Metal renderpasses load and store actions maintaining attachments appropriately. - Use empty depth state for tessellation vertex pre-pass. - Fix tessellated indirect draws using wrong kernels to map parameters. - Work around potential Metal bug with stage-in indirect buffers. - Fix zero local threadgroup size in indirect tessellated rendering. - Fix `[[attribute]]` assignment for tessellation evaluation shaders. - `VkSemaphore` optionally uses `MTLEvent`, if available and `MVK_ALLOW_METAL_EVENTS` environment variable is enabled. - Add `vkSetWorkgroupSizeMVK()` to set compute kernel workgroup size when using MSL source code or MSL compiled code. - Allow zero count of viewports and scissors. - Report image layer limits for attachments in `vkGetPhysicalDeviceImageFormatProperties()`. - Change log indication of error in logs from `[***MoltenVK ERROR***]` to `[mvk-error]`, for consistency with other log level indications. - Allow `mvkMTLRenderStagesFromVkPipelineStageFlags()` to map to all Vulkan stages, by indicating whether the pipeline barrier should come before or after the stages. - Automatically update `VkPhysicalDeviceProperties::pipelineCacheUUID` when SPIRV-Cross revision changes. - Fix crash when clearing attachments using layered rendering on older macOS devices. - Fixes to Metal renderpass layered rendering settings. - `vkCmdClearAttachments()` returns encoder to previous pipeline, depth-stencil & resource state after execution. - Fix issue clearing stencil attachment via renderpass when depth attachment is not being cleared. - Fix sporadic crash on `vkDestroySwapchainKHR()`. - `MoltenVKShaderConverter` tool: Add MSL version and platform command-line options. - Fix crash on pipeline cache merge after `VkShaderModule` destroyed. - Fix case where viewport/scissor doesn't get set properly when mixing dynamic and static-configured pipelines in the same command buffer. - Fix a race condition between sync objects and queries. - Fix unused attachments terminating loop early. - Fix offset of buffer view relative to buffer offset within device memory. - Guard against missing Metal pipeline states when pipeline compilation fails. - `MVKBuffer`: Force managed storage for linear textures on shared buffers. - Use device address space when decompressing DXT image data. - Added missing `texelBufferTextureWidth` setting in `MVKComputePipeline::getMTLFunction()`. - Fixes and consolidation of external library header references. - Allow building external dependency libraries in `Debug` mode. - Enable AMD and NV GLSL extensions when building `glslang` for `MoltenVKGLSLToSPIRVConverter`. - Make external library header references consistent and add `MVK_EXCLUDE_SPIRV_TOOLS` option. - MVKVector improvements. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 20. - Update to latest SPIRV-Cross version: - MSL: Add support for subgroup operations. - MSL: Support argument buffers and image swizzling. - MSL: Add support for `OpArrayLength`. - MSL: Only use constant address space for tessellation control shader. - MSL: Support native texture_buffer type, throw error on atomics. - MSL: Add native texture buffer support. - MSL: Deal with texture swizzle on arrays of images. - MSL: Fix complex type alias declaration order. - MSL: Fix declaration of unused input variables. - MSL: Use correct address space when passing array-of-buffers. - MSL: Deal correctly with nonuniformEXT qualifier. - MSL: Cast texture_buffer index to uint. - MSL: Fix nonuniform test. - MSL: Fix regression with Private parameter declaration. - MSL: Support remapping constexpr samplers by set/binding. - MSL: Support Invariant qualifier on position. - MSL: Support stencil export. - Deal with case where a block is somehow emitted in a duplicated fashion. - Fix infinite loop when `OpAtomic*` temporaries are used in other blocks. - Fix tests for device->constant address space change in MSL tessellation control shader generation. - Accept SPIR-V 1.4 version. MoltenVK 1.0.34 --------------- Released 2019-04-12 - Add support for tessellation. - Add correct function entry point handling. - Add support for `VK_KHR_get_surface_capabilities2` extension. - Implement newer `VK_KHR_swapchain` extension functions. - Support the `VK_EXT_host_query_reset` extension. - Add support for tracking device features enabled during `vkCreateDevice()`. - Handle surface loss due to window moved between screens or a window style change. - Allow zero offset and stride combo in `VkVertexInputBindingDescription`. - API: Add `MVKPhysicalDeviceMetalFeatures::depthSampleCompare`. - Fix conditions under which functions return `VK_INCOMPLETE`. - Fix potential memory leak on synchronous command buffer submission. - Increase shader float constant accuracy beyond 6 digits of precision. - `fetchDependencies`: Stop on first error. - Clean up behaviour of sparse binding functions. - Fix a possible race condition around `MVKMTLBufferAllocation`. - Fix memory overrun if no vertex buffer found with same binding as a vertex attribute. - Fix PVRTC texture content loading via memory mapping. - Fix wrong offset for `vkCmdFillBuffer()` on `VK_WHOLE_SIZE`. - Fixed crash within `MVKPushConstantsCommandEncoderState` when accessing absent graphics pipeline during a compute stage. - Fixed crash when `MTLRenderPassDescriptor renderTargetWidth` & `renderTargetHeight` set on older devices. - Renderpass width/height clamped to the `renderArea` includes `offset`, not just `extent`, and are set only when layered rendering is supported on device. - Set options properly on a buffer view's `MTLTextureDescriptor`. - Don't set `MTLSamplerDescriptor.compareFunction` on devices that don't support it. - Disable the `shaderStorageImageArrayDynamicIndexing` feature on iOS. - Debug build mode includes `dSYM` file for each `dylib` file. - Explicitly build dSYM files in `BUILT_PRODUCTS_DIR` to avoid conflict between macOS and iOS build locations. - `Makefile` supports `install` target to install `MoltenVK.framework`. into `/Library/Frameworks/`. - Add `MVK_CONFIG_TRACE_VULKAN_CALLS` env var and build setting to log Vulkan calls made by application. - Log shader performance statistics in any runtime if `MVKConfiguration::performanceLoggingFrameCount` non-zero. - Suppress visibility warning spam when building Debug macOS from SPIRV-Cross Release build. - Support Xcode 10.2. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 19. - MoltenVKShaderConverter tool: - Support `cs` & `csh` for compute shader file extensions. - Validate converted MSL with a test compilation. - Add option to log shader conversion performance. - Update to latest SPIRV-Cross version: - MSL: Add support for Metal 2 indirect argument buffers. - MSL: Add support for tessellation control & evaluation shaders. - MSL: Support `VK_KHR_push_descriptor`. - MSL: Force unnamed array builtin attributes to have a name. - MSL: Set location of builtins based on client input. - MSL: Ignore duplicate builtin vertex attributes. - MSL: Fix crash where variable storage buffer pointers are passed down. - MSL: Fix infinite CAS loop on atomic_compare_exchange_weak_explicit(). - MSL: Fix `depth2d` 4-component fixup. - MSL: Expand quad `gl_TessCoord` to a float3. - MSL: Fix depth textures which are sampled and compared against. - MSL: Emit proper name for optimized UBO/SSBO arrays. - MSL: Support emit two layers of address space. - MSL: Declare `gl_WorkGroupSize` constant with `[[maybe_unused]]`. - MSL: Fix OpLoad of array which is forced to a temporary. - Add stable C API and ABI. - Performance improvements & reduce pressure on global allocation. - Fix case where a struct is loaded which contains a row-major matrix. - Fix edge case where opaque types can be declared on stack. - Ensure locale handling is safe for multi-threading. - Add support for sanitizing address and threads. - Add support for `SPV_NV_ray_tracing`. - Support -1 index in `OpVectorShuffle`. - Deal more flexibly with for-loop & while-loop variations. - Detect invalid DoWhileLoop early. - Force complex loop in certain rare access chain scenarios. - Make locale handling threadsafe. - Support do-while where test is negative. - Emit loop header variables even for while and dowhile. - Properly deal with sign-dependent GLSL opcodes. - Deal with mismatched signs in S/U/F conversion opcodes. - Rewrite how we deal with locales and decimal point. - Fix crash when `backend.int16_t_literal_suffix` set to null. - Introduce customizable SPIRV-Cross namespaces and use `MVK_spirv_cross` in MoltenVK. MoltenVK 1.0.33 --------------- Released 2019/02/28 - Support the `VK_EXT_memory_budget` extension. - Support 8-bit part of `VK_KHR_shader_float16_int8`. - Disable the `shaderStorageImageMultisample` feature. - Modify README.md to direct developers to Vulkan SDK. - Clarify Xcode version requirements in documentation. - Use the `MTLDevice registryID` property to locate the GPU in `IOKit`. - Add GPU device ID for *iOS A12* SoC. - Allow logging level to be controlled with `MVK_CONFIG_LOG_LEVEL` runtime environment variable. - Allow forcing use of low-power GPU using `MVK_CONFIG_FORCE_LOW_POWER_GPU` runtime environment variable. Set MSL version for shader compiling from Metal feature set. - Don't warn on identity swizzles when `fullImageViewSwizzle` config setting is enabled. - Track version of spvAux buffer struct in SPIRV-Cross and fail build if different than version expected by MoltenVK. - Add static and dynamic libraries to MoltenVKShaderConverter project. - Fix crash from use of MTLDevice registryID on early OS versions. - `fetchDependencies`: Fix issue loading from `Vulkan-Portability_repo_revision`. - `fetchDependencies`: Clean MoltenVK build to ensure using latest dependency libs. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 18. - Update to latest dependency libraries to support SDK 1.1.101. - Update to latest SPIRV-Cross version: - MSL: Implement 8-bit part of `VK_KHR_shader_float16_int8`. - MSL: Add a setting to capture vertex shader output to a buffer. - MSL: Stop passing the aux buffer around. - Support LUTs in single-function CFGs on Private storage class. MoltenVK 1.0.32 --------------- Released 2019/01/28 - Add support for `VK_EXTX_portability_subset` extension. - iOS: Support dual-source blending with iOS 11. - iOS: Support cube arrays with A11. - iOS: Support layered rendering and multiple viewports with A12. - Use combined store-resolve ops when supported and requested in renderpass. - Fixes to values returned from `vkGetPhysicalDeviceImageFormatProperties()` and `vkGetPhysicalDeviceImageFormatProperties2KHR()`. - Log and return `VK_ERROR_FEATURE_NOT_PRESENT` error if `vkCreateImageView()` requires shader swizzling but it is not enabled. - Log and return `VK_ERROR_FEATURE_NOT_PRESENT` error if array of textures or array of samplers requested but not supported. - Treat all attributes & resources as used by shader when using pre-converted MSL. - Allow default GPU Capture scope to be assigned to any queue in any queue family. - VkPhysicalDevice: Correct some features and limits. - Stop advertising atomic image support. - `vkSetMTLTextureMVK()` function retains texture object. - Log to stderr instead of stdout. - `fetchDependencies`: build `spirv-tools` when attached via symlink. - Enhancements to `MVKVector`, and set appropriate inline sizing usages. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 17. - Update to latest SPIRV-Cross version: - MSL: Use correct size and alignment rules for structs. - MSL: Fix texture projection with Dref. - MSL: Deal with resource name aliasing. MoltenVK 1.0.31 --------------- Released 2019/01/17 - Support runtime config via runtime environment variables - Add full ImageView swizzling to config, and disable it by default. - Add GPU switching to config, and enable it by default. - Add queue family specialization to config, and disable it by default. - Enable synchronous queue submits as config default. - Support 4 queue families. - Pad fragment shader output to 4 components when needed. - Add support for copying to and from PVRTC images. - Log Vulkan versions in human readable form when reporting version error. - Update `VK_MVK_MOLTENVK_SPEC_VERSION` to 16. - Update copyright to 2019. - Advertise the `VK_AMD_gpu_shader_half_float` extension. - Support the `VK_KHR_variable_pointers` extension. - MoltenVKShaderConverter tool exit with fail code on any file conversion fail. - Update to latest dependency libraries for Vulkan SDK 1.1.97. - Update to latest SPIRV-Cross version: - MSL: Support SPV_KHR_variable_pointers. - MSL: Workaround missing gradient2d() on macOS for typical cascaded shadow mapping. - MSL: Fix mapping of identity-swizzled components. - MSL: Support composites inside I/O blocks. - MSL: Fix case where we pass arrays to functions by value. - MSL: Add option to pad fragment outputs. - MSL: Fix passing a sampled image to a function. - MSL: Support std140 packing rules for float[] and float2[]. - MSL: Fix image load/store for short vectors. - Performance improvements on iterating internal constructs. - Update copyright to 2019. MoltenVK 1.0.30 --------------- Released 2018/12/31 - Allow 2 or 3 swapchain images to support both double and triple buffering. - Force display to switch to GPU selected by vkCreateDevice() to avoid system view compositor having to copy from that GPU to display GPU. - Use inline buffer for pipeline auxiliary buffer. - vkCmdCopyImage: Cast source image to the destination format. - Result of vkGetPhysicalDeviceFormatProperties2KHR match vkGetPhysicalDeviceFormatProperties. - MVKImage: Return error for BLOCK_TEXEL_VIEW. - MVKDescriptorSet: Fix handling of immutable samplers. - MVKPipeline: Forbid vertex attribute offsets >= stride. - Fix handling of case where vertex bindings and binding indices don't match up. - Return VK_TIMEOUT even on zero wait if fences not signalled. - Support iOS builds for arm64e architecture. - Improvements to building external libraries. - Print Vulkan semantics when logging converted GLSL. - Support uploading S3TC-compressed 3D images. MoltenVK 1.0.29 --------------- Released 2018/12/15 - Replace use of std::vector with MVKVector to support allocations on stack. - Add missing include MVKEnvironment.h to MVKImage.mm for IOSurfaces. - vkCmdClearAttachments apply [[render_target_array_index]] more carefully. - vkCmdPushDescriptorSet: Fix mapping of binding numbers to descriptor layouts. - Forbid depth/stencil formats on anything but 2D images. - MVKCommandPool: Destroy transfer images using the device. - MVKPipeline: Reject non-multiple-of-4 vertex buffer strides. - MVKPipeline: Set auxiliary buffer offsets once, on layout creation. - MVKSampler: Support border colors. - MVKImage: Round up byte alignment to the nearest power of 2. - MVKImage: Don't set MTLTextureUsageRenderTarget for non-blittable formats. - MVKImage: Support image views of 2D multisample array images. - MVKGraphicsPipeline: Add dummy attachments even when rasterization is off. - MVKDeviceMemory: Try creating an MTLBuffer before allocating heap memory. - Add support for VK_FORMAT_A2R10G10B10_UNORM_PACK32. - Support A8B8G8R8_PACK32 formats. - Add new formats and fix existing ones. - On macOS, VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 can only be filtered. - On macOS, linear textures cannot be blitted to. - Depth formats cannot be used for a VkBufferView. - Give every image format we support the BLIT_SRC feature. - Correct supported features of compressed formats. - Correct mapping of packed 16-bit formats. - Add some more vertex formats. - Don't use char/uchar for clearing/copying 8-bit formats. - Explicitly set number of sparse image property/requirement info sets to 0. - Retrieve linear image memory alignment requirements from Metal device. - For each GPU, log MSL version and updated list of feature sets. - Cube demo on iOS support Portrait and Landscape device orientation. - Build the dylib with -fsanitize=address when asan is enabled. - Fix name of generated dSYM file. - Update to latest SPIRV-Cross version: - MSL don't emit `memory_scope` after MSL 2.0. MoltenVK 1.0.28 --------------- Released 2018/12/06 - Add support for extensions: - VK_KHR_bind_memory2 - VK_KHR_swapchain_mutable_format - VK_KHR_shader_float16_int8 - VK_KHR_8bit_storage - VK_KHR_16bit_storage - VK_KHR_relaxed_block_layout - VK_KHR_maintenance3 - VK_KHR_storage_buffer_storage_class - Add support for 2D multisample array textures. - Ignore fragment shader if raster discard is enabled. - Force signedness of shader vertex attributes to match the host. - In debug configurations, create a dSYM bundle for libMoltenVK.dylib. - MVKImage: Take lock when setting the MTLTexture manually. - Optimize MVKFenceSitter. - Support parallel builds of fetchDependencies to improve build times. - Change internal header references to increase header path flexibility. - Update to latest SPIRV-Cross version: - MSL: Use an enum instead of two mutually exclusive booleans. - MSL: Force signedness of shader vertex attributes to match the host. - Support gl_HelperInvocation on GLSL and MSL. MoltenVK 1.0.27 --------------- Released 2018/11/15 - Remove destroyed resources from descriptor sets. - Forbid compressed formats on non-2D images. - Update to latest dependency libraries for Vulkan SDK 1.1.92. - Update to latest SPIRV-Cross version: - MSL: Print early_fragment_tests specifier before fragment shader declaration. - MSL: Also pack members at unaligned offsets. - MSL: Also pack 2- and 4- element vectors when necessary. - MSL: Emit wrapper for SSign (sign() for int types). - MSL: Support extended arithmetic opcodes. - Handle opcode OpSourceContinued. - Handle group decorations. MoltenVK 1.0.26 --------------- Released 2018/11/06 - Fix memoryTypes order to match Vulkan spec. - Allow linear images to use host-coherent memory. - Generate Bitcode in iOS libraries. - Allow all pipeline attachements to be unused. - Perform usage checks on 3D images. - Enhancements to dylib generation script. - Update to latest SPIRV-Cross version: - MSL: Support 8 & 16 bit types. - MSL: Updated spec constant support. MoltenVK 1.0.25 --------------- Released 2018/10/31 - Refactor the build environment. - Support creation of static library and build framework and dynamic library from it. - Add Makefile to better support command line or script building integration. - Update demos to each use one of framework, static library, and dynamic library. - Refactor and rename the build scripts. - Refactor and rename the Xcode Schemes. - Update build and runtime documentation. - Update shader caching for compatibility with texture swizzling. - Support polygonMode VK_POLYGON_MODE_POINT. - vkCreateInstance returns VK_ERROR_INCOMPATIBLE_DRIVER if Metal not available. MoltenVK 1.0.24 --------------- Released 2018/10/16 - Support arbitrary swizzles of image data. - Include struct size parameter in VK_MVK_moltenvk extension functions that pass structs that might change size across extension versions. - Remove vkGetMoltenVKDeviceConfigurationMVK() & vkSetMoltenVKDeviceConfigurationMVK() functions. - Allocate MVKDescriptorSets from a pool within MVKDescriptorPool - Support copying between textures of compatible-sized formats - Support VK_FORMAT_A2B10G10R10_UNORM_PACKED vertex format - Build scripts support SRCROOT path containing spaces. MoltenVK 1.0.23 --------------- Released 2018/09/28 - Add support for features: - shaderStorageImageMultisample - shaderStorageImageReadWithoutFormat - shaderStorageImageWriteWithoutFormat - shaderUniformBufferArrayDynamicIndexing - shaderSampledImageArrayDynamicIndexing - shaderStorageBufferArrayDynamicIndexing - shaderStorageImageArrayDynamicIndexing - Support reduced render area - Support rasterization to missing attachment - Allocate MVKCommandBuffers from a pool within MVKCommandPool. - Update glslang version - Update to latest SPIRV-Cross version: - MSL: Improve coordinate handling for buffer reads. - MSL: Expand arrays of buffers passed as input. MoltenVK 1.0.22 --------------- Released 2018/09/25 - Add support for extensions: - VK_KHR_maintenance2 - VK_EXT_vertex_attribute_divisor - VK_KHR_sampler_mirror_clamp_to_edge - VK_KHR_image_format_list - VK_KHR_dedicated_allocation - VK_KHR_get_memory_requirements2 - VK_EXT_shader_viewport_index_layer - Support multiple viewports and scissor rectangles. - Support sampleRateShading. - Support pre-filling Metal command buffer on same thread as Vulkan command buffer. - Support passing either a CAMetalLayer or an NSView/UIView in the pView member when creating a surface. - Support views of the stencil aspect of depth/stencil images. - Improvements to subviews on 3D textures. - Enforce single queue per queue family to improve Metal command buffer handling. - Set Metal render target sizes on iOS. - Fix potential deadlocks on query results and fences. - Fix memory leak on SPIRV conversion. - Update to Vulkan header 1.1.85 and latest version of library dependencies. - Update to latest SPIRV-Cross version: - MSL: Handle the ViewportIndex builtin. - MSL: Handle the SamplePosition builtin. - MSL: Fix OpAtomicIIncrement and OpAtomicIDecrement. - MSL: Support array of arrays composites and copying. - MSL: Fix issues with casting of builtin integer vectors. MoltenVK 1.0.21 --------------- Released 2018/09/08 - Add support for extensions: - VK_KHR_descriptor_update_template - Create 3D MTLTextureViews for 2D image views of 3D textures. - Allow building and packaging MoltenVK for of only iOS or only macOS. - Move packaging scripts out of Xcode projects and into script files. - vkUpdateDescriptorSet: Handle copies of uninitialized descriptors. - vkCmdFillBuffer & vkCmdCopyBuffers: Use dispatch call that supports older OS versions. - Update to latest SPIRV-Cross version: - MSL: Emit F{Min,Max,Clamp} as fast:: and N{Min,Max,Clamp} as precise - MSL: Implement multisampled array textures. - MSL: Emit spvTexelBufferCoord() on ImageWrite to a Buffer. - MSL: Handle interpolation qualifiers. - MSL: Account for components when assigning locations to varyings. - MSL: Do not emit function constants for version < 1.2. MoltenVK 1.0.20 --------------- Released 2018/09/01 - Add support for extensions: - VK_KHR_maintenance1 - VK_KHR_shader_draw_parameters - VK_KHR_get_physical_device_properties2 - VK_KHR_push_descriptor - Add ability to track and access supported and enabled extensions. - Update to latest SPIRV-Cross version. MoltenVK 1.0.19 --------------- Released 2018/08/23 - Move MoltenVK config to instance instead of device. - Add MVKConfiguration and deprecate MVKDeviceConfiguration. - Add vkGetMoltenVKConfigurationMVK() and deprecate vkGetMoltenVKDeviceConfigurationMVK(). - Add vkSetMoltenVKConfigurationMVK() and deprecate vkSetMoltenVKDeviceConfigurationMVK(). - Add build setting overrides for all initial MVKConfiguration member values. - Support Xcode 10: Explicitly specify MoltenVKSPIRVToMSLConverter as prelink library. - Update to Vulkan header 1.1.83 and latest version of library dependencies. MoltenVK 1.0.18 --------------- Released 2018/08/15 - vkCmdFullBuffer() fills buffer using compute shader. - Fix API for updating MVKDeviceConfiguration::synchronousQueueSubmits. - vkGetPhysicalDeviceFormatProperties() return VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT if supported, even if other format properties are not. - Support Metal GPU capture scopes. - Update to latest SPIRV-Cross, glslang & SPIRV-Tools. MoltenVK 1.0.17 --------------- Released 2018/07/31 - Disable rasterization and return void from vertex shaders that write to resources. - Add SPIRVToMSLConversionOptions::isRasterizationDisabled to allow pipeline and vertex shader to communicate rasterization status. - Track layered rendering capability. - Add MVKPhysicalDeviceMetalFeatures::layeredRendering. - Add mvkStaticCmdShaderSource() to generate static MSL shader source for commands. - Add MVKDevice::getMTLCompileOptions() to consolidate shader compilation options. - CreatePipelines return error when fragment MSL translation fails. - Add new vertex format VK_FORMAT_A2B10G10R10_SNORM_PACK32. - Fix watermark timing. - Update MoltenVK spec version to 6. - Remove obsolete deprecated licensing functions. - Rename folders and project for Cube demo. - Update What's New document for earlier releases. - Update to latest library dependencies. - Update to latest SPIRV-Cross version. MoltenVK 1.0.16 --------------- Released 2018/07/24 - Fixes to attachment and image clearing to pass CTS tests. - MVKCmdClearAttachments support clearing multiple attachment layers. - MVKCmdClearImage use renderpass clear, and support clearning multiple image layers. - Rename mvkCmdClearImage() to mvkCmdClearColorImage(). - MVKDevice add getFormatIsSupported() to allow devices to test for format support. - MVKFramebuffer support multiple layers. - mvk_datatypes.h support both 2D and 3D mipmap calculations and allow mvkMTLPrimitiveTopologyClassFromVkPrimitiveTopology() in iOS. - Remove support for VK_FORMAT_B10G11R11_UFLOAT_PACK32 & VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 since format components are reversed on Metal. - Report correct workgroup sizes from MTLDevice. - Retrieve VkPhysicalDeviceLimits::maxComputeWorkGroupSize & maxComputeWorkGroupInvocations & maxComputeSharedMemorySize from MTLDevice. - Move OS extension source files to new OS directory. - Update to latest SPIRV-Cross version. MoltenVK 1.0.15 --------------- Released 2018/07/12 - Link IOSurface on iOS only if IPHONEOS_DEPLOYMENT_TARGET is at least iOS 11.0. - Update to latest SPIRV-Cross. MoltenVK 1.0.14 --------------- Released 2018/07/04 - vkGetPhysicalDeviceImageFormatProperties() indicate 1D texture limitations. - Fix compute shader workgroup size specialization. - Support separate specialization for each workgroup dimension. - Support zero as a specialization ID value. - Set correct value for VkPhysicalDeviceLimits::maxPerStageDescriptorInputAttachments. - Cleanup MoltenVKShaderConverterTool. - Update to latest SPIRV-Cross. MoltenVK 1.0.13 --------------- Released 2018/06/28 - Support larger VkBufferViews by using 2D Metal textures. - Swapchain return VK_ERROR_OUT_OF_DATE_KHR when window resized. - Improve crispness of visuals on macOS Retina displays. - Set CAMetalLayer magnificationFilter property to Nearest by default. - Add MVKDeviceConfiguration::swapchainMagFilterUseNearest member to allow overrides. - Update to latest SPIRV-Cross. MoltenVK 1.0.12 --------------- Released 2018/06/22 - Sorting Metal devices in the list of physicalDevices by whether they are headless. - vkCmdBlitImage() support texture arrays as source and destination targets. - vkCmdBlitImage() remove broken support for depth/stencil scaling. - vkCmdClearImage() fixes to clearing depth and stencil formats and avoid Metal validation errors. - Fix slice index when rendering to cube maps. - Fix texture file copy in Cube Demo. - fetchDeps: Add flags for pre-built repos. - Update to latest library dependencies to match Vulkan SDK 1.1.77. - Update to latest SPIRV-Cross. MoltenVK 1.0.11 --------------- Released 2018/06/12 - Avoid fragment shader tracking interacting with vertex attributes. - Restrict allowed linear tiling features for pixel formats. - Fix bad logic when testing allowed linear tiling usage. - Fix copying 4-byte 32-bit depth/stencil formats between buffers and textures. - Fix MSL compilation failures on macOS 10.14 Mojave Beta. - Update to latest SPIRV-Cross. MoltenVK 1.0.10 --------------- Released 2018/06/05 - Support mapping and filling device memory before binding an image to it. - Fix vsync not being enabled in IMMEDIATE present mode. MVK_MACOS was not being defined. - Avoid Metal validation error on MTLBuffer.contents access from private storage. - Support using Metal texel buffer for linear images to increase host coherency. - MVKDeviceMemory track MVKImages and MVKBuffers separately. - Per Vulkan spec, restrict linear images to 2D, non-array, single mipmap. - Use texel buffer if possible for texture on coherent device memory. - Only flush MVKImages (not MVKBuffers) when device memory mapped. - Do not flush texel buffer images. - Replace dependency on Vulkan-LoaderAndValidationLayers with Vulkan-Headers and Vulkan-Tools. - Update to latest SPIRV-Cross. MoltenVK 1.0.9 -------------- Released 2018/05/23 - Fix an issue where the depth format in MVKCmdClearImage was not getting set correctly. - Move surface access to UI components to main thread. - Fix deadlock possibility between MVKFence and MVKFenceSitter. - Fix handling of locking on deferred-destruction objects. - vkGetPhysicalDeviceImageFormatProperties returns VK_ERROR_FORMAT_NOT_SUPPORTED if the format is not supported. - Default value of MVKDeviceConfiguration::metalCompileTimeout set to infinite. - Update to latest SPIRV-Cross. MoltenVK 1.0.8 -------------- Released 2018/05/18 - Allow queue processing to be optionally handled on the submitting (render) thread. - Update to latest SPIRV-Cross. MoltenVK 1.0.7 -------------- Released 2018/05/14 - Cache MTLCommandQueues for reuse to handle long delays in creating new VkDevices and VkQueues. - Handle multiple MVKResources mapped to the same region of a single MVKDeviceMemory. - Add Metal library, function and pipeline compilation timeout limits. - Create copies of MVKShaderLibraries when merging pipeline caches. - Handle NULLs when freeing command buffers. - Replace delete with call to destroy() for all MVK objects. - Handle null pointers in vkDestroy...() functions. - Set default value of MVKDeviceConfiguration::supportLargeQueryPools to true by default. - Fixes to run Vulkan CTS without crashes. - Remove mutex locks on MVKDescriptorPool. - Update to latest SPIRV-Cross. MoltenVK 1.0.5 -------------- Released 2018/05/04 - Add features to support Vulkan CTS. - Dynamically create frag shaders for clearning attachments and images. - Dynamically create frag shaders for blitting scaled images. - MVKGraphicsPipeline don't create MTLRenderPipelineState if vertex function conversion fails. - MVKComputePipeline don't create MTLComputePipelineState if compute function conversion fails. - Handle SPIRV-Cross errors thrown during SPIR-V parsing in compiler construction. - Set undefined property limits to large, but not max, values to avoid casting issues in app. - Mark multiDrawIndirect features as available. - Support VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. - Separate categories from MVKOSExtensions. - Update to latest SPIRV-Cross. MoltenVK 1.0.4 -------------- Released 2018/04/22 - Support depth clip mode only from MTLFeatureSet_iOS_GPUFamily2_v4 onwards. - MVKCmdClearAttachments & MVKCmdClearImage support multisampled attachments and images. - Don't use CAMetalLayer displaySyncEnabled property if it is not available. - Update python brew install command. - Update to latest SPIRV-Cross. MoltenVK 1.0.3 -------------- Released 2018/04/18 - Add support for VK_PRESENT_MODE_IMMEDIATE_KHR swapchain presentation mode. - Round up row and layer byte counts when copying compressed images with sizes that are not integer multiples of block size. - Queue and device wait idle handled by internal fence instead of semaphore. - vkCmdCopyBufferToImage() & vkCmdCopyImageToBuffer() support a VkBuffer that is bound to an offseted position in a VkDeviceMemory. - MVKImage::getArrayLayers() reports only layer count and excludes depth. - Add workaround for apps that use one semaphore for all swapchain images. - Support deferred secondary signaling of semaphore & fence acquired while image is free. - Update to latest cube.c version. - Use ninja if available to build dependencies. - Build the demos in Travis-CI. - Update to latest V-LVL, glslang & SPIRV-Tools. - Update to latest SPIRV-Cross. MoltenVK 1.0.2 -------------- Released 2018/04/02 - Add support for caching converted MSL shader code offline from pipeline cache via vkGetPipelineCacheData(), vkCreatePipelineCache() & vkMergePipelineCaches(). - Present using command buffer by default. - Support SPIR-V containing multiple entry points. - Add option for per-frame performance logging via un-commentable logging code. - VkPhysicalDeviceProperties::pipelineCacheUUID value derived from MoltenVK version and highest supported Metal feature set. - vkCmdClearAttachments() don't attempt to clear non-existing depth & stencil attachments. - Always clamp scissors to render area to avoid Metal validation error. - Move fetchDependencies to top directory. - Turn caching of Externals off in .travis.yml. - Add instructions in README.md about building MoltenVK via the command line. - Update to latest SPIRV-Cross. MoltenVK 1.0.1 -------------- Released 2018/03/19 - Add support for Vulkan Loader and Validation Layer API version 5. - Add support for LunarG Vulkan Loader ICD API. - Add Vulkan Loader and Validation Layer ICD JSON file. - Fix vkGetInstanceProcAddr to work with 1.1 loader. - Use fetchDependencies script instead of submodules. - Align versioning of external libraries with those used by LunarG SDK. - Combine multiple VkCommandBuffers into a single MTLCommandBuffer. - On command buffer submission, defer waiting on semaphores until just before MTLCommandBuffer is committed. - Retrieve heap size from MTLDevice on macOS and from free shared system memory on iOS. - Allow color attachment on depth-only rendering. - Allow color attachment when clearing depth only. - Support DXT1 RGB texture compression. - Support VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT on VkFormats that are not supported as texture formats under Metal. - Don't check if texture is coherent on macOS, since it never is. - Setup push constants for compute shaders. - Check if storage mode is not shared when checking if synchronize is needed. - Log which GPU is attached to a VkDevice. - Sort multiple GPU's to put higher-power GPU's at front of list. - Populate VkPhysicalDeviceProperties vendorID, deviceID and pipelineCacheUUID. - Ensure scissors fit inside renderpass area to avoid Metal validation assertions. - Consolidate setting of viewport and scissors by pipeline and command. - Make MVKBuffer::getMTLBuffer() thread-safe. - Fix Metal validation error with a renderpass with no depth attachment. - Use pipelineStatisticsQuery feature to determine whether pipeline stats are available. - Modify MVKImageView to fix MTLTexture used for renderpasses. - Fix vkBindImageMemory crash when multiple simultaneous threads are binding to different offsets in the of the same VkDeviceMemory. - Don't align push constant buffer. - Fix vkCmdCopyBuffer when copying unaligned regions. - Added workgroup size specialization constants - Fix SPIRV-Cross OOM conditions with multiple consecutive two-vector OpVectorShuffles. - Support non-square row-major matrix conversions. - Fix vkCmdBlitImage between images of different sizes. - Add ability to write SPIR-V to file for debugging purposes. - Update ThirdPartyConfig.md to latest use of SPIRV-Cross testability. - Fixes to compute workgroup sizes and barriers. - Improved extraction of entry point name and workgroup size from SPIR-V. - Consolidate to a single ThirdPartyConfig.md document. - MSL enhancements to nested function use of globals. - Support customizing MSL based on iOS or macOS platform. - MSL threadgroup barrier memory scope only on iOS MSL 2.0. - MVKBufferView add lock when creating MTLTexture. - MVKDeviceMemory add lock when creating MTLBuffer during memory mapping. - MVKMTLBufferAllocator does not need to be threadsafe. - Cleanup syntax on other lock handling to add consistency. - Consolidate timestamps and performance tracking. - Derive vkCmdCopyBuffer() alignment requirement at runtime. - Don't log error from vkGetPhysicalDeviceFormatProperties() if format not supported. - Add printf-like macros to MVKLogImpl and mvkNotifyErrorWithText. - Updates to dylib building process. Use clang instead of libtool. - Allow MoltenVK to be installed and built without asciidoctor. - Add CI support using Travis CI. - Automatically install demo apps. - Cube demo generate SPIR-V as part of demo project build. - Disable watermark in debug builds. - Add build and runtime OS and device requirements to documentation. - Add Compliance and Contribution sections to README.md. - Remove executable permissions from non-executable files. - Update to latest SPIRV-Cross. - Update copyright dates to 2018. MoltenVK 1.0.0 -------------- Released 2018/02/26 Initial open-source release! --- ## File: ExternalRevisions/README.md #MoltenVK External Dependencies Copyright (c) 2015-2026 [The Brenwill Workshop Ltd.](http://www.brenwill.com) [comment]: # "This document is written in Markdown (http://en.wikipedia.org/wiki/Markdown) format." [comment]: # "For best results, use a Markdown reader." Table of Contents ----------------- - [Fetching and Building External Libraries](#fetching) - [Updating External Library Versions](#updating) - [Adding the *cereal* Library to the *MoltenVK Xcode* Project](#add_cereal) - [Adding the *SPIRV-Tools* Library to the *ExternalDependencies Xcode* Project](#add_spirv-tools) - [Adding the *SPIRV-Cross* Library to the *ExternalDependencies Xcode* Project](#add_spirv-cross) Fetching and Building External Libraries ---------------------------------------- **MoltenVK** uses technology from the following external open-source libraries: - [*cereal*](https://github.com/USCiLab/cereal) - [*SPIRV-Cross*](https://github.com/KhronosGroup/SPIRV-Cross) - [*SPIRV-Headers*](https://github.com/KhronosGroup/SPIRV-Headers) - [*SPIRV-Tools*](https://github.com/KhronosGroup/SPIRV-Tools) - [*volk*](https://github.com/zeux/volk) - [*Vulkan-Headers*](https://github.com/KhronosGroup/Vulkan-Headers) - [*Vulkan-Tools*](https://github.com/KhronosGroup/Vulkan-Tools) These external open-source libraries are maintained in the `External` directory. To retrieve and build these libraries from their sources, run the `fetchDependencies` script in the main repository directory: ./fetchDependencies --all [--debug] The `--debug` option will build the external libraries in Debug mode, which may be useful when debugging and tracing calls into those libraries. Updating External Library Versions ---------------------------------- To maintain consistency between the libraries, **MoltenVK** retrieves specific versions of each external library. The version of each external library is determined as follows: - **_cereal_**: a GitHub repository commit identifier found in the `ExternalRevisions/cereal_repo_revision` file. - **_SPIRV-Cross_**: a GitHub repository commit identifier found in the `ExternalRevisions/SPIRV-Cross_repo_revision` file. - **_SPIRV-Headers_**: a GitHub repository commit identifier found in the `ExternalRevisions/SPIRV-Headers_repo_revision` file. - **_SPIRV-Tools_**: a GitHub repository commit identifier found in the `ExternalRevisions/_SPIRV-Tools__repo_revision` file. - **_volk_**: a GitHub repository commit identifier found in the `ExternalRevisions/Volk_repo_revision` file. - **_Vulkan-Headers_**: a GitHub repository commit identifier found in the `ExternalRevisions/Vulkan-Headers_repo_revision` file. - **_Vulkan-Tools_**: a GitHub repository commit identifier found in the `ExternalRevisions/Vulkan-Tools_repo_revision` file. You can update which versions of the external libraries are retrieved by changing the value held in the corresponding `*_repo_revision` file listed above. Once you have made changes to the `*_repo_revision` files, you can retrieve the updated library versions by running the `fetchDependencies` script, as described above, again. >***Note:*** If, after updating to new versions of the external libraries, you encounter >build errors when building **MoltenVK**, review the instructions in the sections below >to ensure all necessary external library files are included in the **MoltenVK** builds. >***Note:*** _Vulkan-Tools_ and _volk_ are not used by **MoltenVK** itself, but are used >by the _Cube_ demo app included in the **MoltenVK** repository. Adding the *cereal* Library to the *MoltenVK Xcode* Project ----------------------------------------------------------- The `MoltenVK` *Xcode* project is already configured to use the *cereal* library. However, after updating the version of *cereal*, as described [above](#updating), if you encounter any building errors, you may need to re-add the *cereal* library to the `MoltenVK` *Xcode* project as follows: 1. In the *Project Navigator* panel, select the `MoltenVK` *Xcode* project, then the `MoltenVK` project target, and open the *Build Settings* tab. Locate the build setting entry **Header Search Paths** (`HEADER_SEARCH_PATHS`) and add the following paths: "$(SRCROOT)/../External/cereal/include" Adding the *SPIRV-Tools* Library to the *ExternalDependencies Xcode* Project ---------------------------------------------------------------------------- The `ExternalDependencies` *Xcode* project is already configured to use the *SPIRV-Tools* library. However, after updating the version of *SPIRV-Tools*, as described [above](#updating), if you encounter any building errors, you may need to re-add the *SPIRV-Tools* library to the `ExternalDependencies` *Xcode* project as follows: 1. In the *Project Navigator* panel, select the `ExternalDependencies` *Xcode* project, then select the `SPIRV-Tools-macOS` target, and open the *Build Settings* tab. Locate the build setting entry **Header Search Paths** (`HEADER_SEARCH_PATHS`) and add the following paths: $(inherited) "$(SRCROOT)/External/SPIRV-Tools/" "$(SRCROOT)/External/SPIRV-Tools/include" "$(SRCROOT)/External/SPIRV-Tools/external/spirv-headers/include" "$(SRCROOT)/External/SPIRV-Tools/build" 2. Repeat *Step 1* for the `SPIRV-Tools-iOS`, `SPIRV-Tools-tvOS`, and ` `SPIRV-Tools-xrOS` targets within the `ExternalDependencies` *Xcode* project 3. In the *Project Navigator*, remove the *Group* named `source` from under the *Group* named `External/SPIRV-Tools`. 4. Drag the `External/SPIRV-Tools/source` file folder to the `External/SPIRV-Tools` group in the *Project Navigator* panel. In the _**Choose options for adding these files**_ dialog that opens, select the _**Create groups**_ option, add the files to *all* of the `SPIRV-Tools-macOS`, `SPIRV-Tools-iOS`, `SPIRV-Tools-tvOS`, and `SPIRV-Tools-xrOS` targets, and click the ***Finish*** button. 5. Remove the following *Groups* from under the *Group* named `External/SPIRV-Tools/source`: - `fuzz` - `wasm` 6. To avoid compilation warnings, remove the following *Files* from under the *Group* named `External/SPIRV-Tools/source`: - `mimalloc.cpp` - `pch_source.cpp` - `opt/pch_source_opt.cpp` - `reduce/pch_source_reduce.cpp` - `util/timer.cpp` 7. In the `Scripts` folder, run `./packagePregenSpirvToolsHeaders`, which will fetch and build the full `SPIRV-Tools` library and will update `Templates/spirv-tools/build.zip` from the `*.h` and `*.inc` files in `External/SPIRV-Tools/build`. Test by running `./fetchDependencies --all` and a **MoltenVK** build. Adding the *SPIRV-Cross* Library to the *ExternalDependencies Xcode* Project ---------------------------------------------------------------------------- The `ExternalDependencies` *Xcode* project is already configured to use the *SPIRV-Cross* library. However, after updating the version of *SPIRV-Cross*, as described [above](#updating), if you encounter any building errors, you may need to re-add the *SPIRV-Cross* library to the `ExternalDependencies` *Xcode* project as follows: 1. In the *Project Navigator*, remove all of the files under the *Group* named `External/SPIRV-Cross`. 2. Drag the following files from the `External/SPIRV-Cross` directory to the `External/SPIRV-Cross` group in the *Project Navigator* panel: spirv_cfg.cpp spirv_cfg.hpp spirv_common.hpp spirv_cross_containers.hpp spirv_cross_error_handling.hpp spirv_cross_parsed_ir.cpp spirv_cross_parsed_ir.hpp spirv_cross_util.hpp spirv_cross.cpp spirv_cross.hpp spirv_glsl.cpp spirv_glsl.hpp spirv_msl.cpp spirv_msl.hpp spirv_parser.cpp spirv_parser.hpp spirv_reflect.cpp spirv_reflect.hpp spirv.hpp In the ***Choose options for adding these files*** dialog that opens, select the ***Create groups*** option, add the files to *all* of the `SPIRV-Cross-macOS`, `SPIRV-Cross-iOS`, and `SPIRV-Cross-tvOS` targets, and click the ***Finish*** button. ### Regression Testing Your Changes to *SPIRV-Cross* The *SPIRV-Cross* library plays an important part in providing features for **_MoltenVK_**, and if you are developing features for **_MoltenVK_**, you may end up making changes to *SPIRV-Cross*. If you make changes to the `SPIRV-Cross` repository, you can build a new version of the `libSPIRVCross.a` static library by opening the `ExternalDependencies.xcodeproj` *Xcode* project, and running the **_ExternalDependencies_** *Xcode* scheme. You can then rebuild **MoltenVK** to include the new library. While makng changes to the `SPIRV-Cross` repository, you can regression test your changes using the following steps: cd External/SPIRV-Cross ./checkout_glslang_spirv_tools.sh ./build_glslang_spirv_tools.sh ./test_shaders.sh