commit | e482ac95dfdca9935c7fcfe3fd4f9ddf5e601036 | [log] [tgz] |
---|---|---|
author | Bill Hollings <bill.hollings@brenwill.com> | Wed Jul 07 13:09:40 2021 -0400 |
committer | Bill Hollings <bill.hollings@brenwill.com> | Wed Jul 07 13:09:40 2021 -0400 |
tree | 089337276db9549dc1653f9980c3bab5dc399aa9 | |
parent | 53a2223abdc87a10050abcef6b978e8512a25129 [diff] |
Use unswizzled MTLTexture for attachments. Depth/stencil attachments that are also sampled might have an artificially forced swizzled texture view. The original unswizzled texture must be used for attachments. Add MVKImageViewPlane::getUnswizzledMTLTexture().
Copyright (c) 2015-2021 The Brenwill Workshop Ltd.
The recommended method for developing a Vulkan application for macOS is to use the Vulkan SDK.
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 and the MoltenVK library included in it. Refer to the Vulkan SDK Getting Started document for more info.
If you are developing a Vulkan application for iOS or tvOS, or are developing a Vulkan application for macOS and want to use a different version of the MoltenVK runtime library provided in the macOS Vulkan SDK, you can use this document to learn how to build a MoltenVK runtime library from source code.
To learn how to integrate the MoltenVK runtime library into a game or application, see the MoltenVK_Runtime_UserGuide.md
document in the Docs
directory.
MoltenVK is a layered implementation of Vulkan 1.1 graphics and compute functionality, that is built on Apple's 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 on macOS 11.0+, 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, 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, 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.1 graphics and compute API.
MoltenVKShaderConverter converts SPIR-V shader code to Metal Shading Language (MSL) shader code, and converts GLSL shader source code to SPIR-V shader code and/or 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, both the SPIR-V and GLSL converters are packaged into a stand-alone command-line MoltenVKShaderConverter
macOS tool for converting shaders at development time from the command line.
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:
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
Clone the MoltenVK
repository:
git clone https://github.com/KhronosGroup/MoltenVK.git
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
.
For more information about the external open-source libraries used by MoltenVK, see the ExternalRevisions/README.md
document.
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.
Note: To support
IOSurfaces
on iOS or tvOS, MoltenVK, and any app that uses MoltenVK, must be built with a minimum iOS Deployment Target (akaIPHONEOS_DEPLOYMENT_TARGET
) build setting ofiOS 11.0
or greater, or a minimum tvOS Deployment Target (akaTVOS_DEPLOYMENT_TARGET
) build setting oftvOS 11.0
or greater.
Once built, the MoltenVK libraries can be run on macOS, iOS or tvOS devices that support Metal, or on the Xcode iOS Simulator or tvOS Simulator.
IOSurfaces
).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):
Each of theseMoltenVKPackaging.xcodeproj
Xcode project Schemes puts the resulting packages in the Package
directory, creating it if necessary. This directory contains separate Release
and Debug
directories, holding the most recent Release and Debug builds, respectively.
A separate Latest
directory links to the most recent build, regardless of whether it was a Release or Debug build. Effectively, the Package/Latest
directory points to whichever of the Package/Release
or Package/Debug
directories was most recently updated.
With this packaging structure, you can follow the instructions below to link your application to the MoltenVK 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.
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
make
repeatedly with different targets will accumulate binaries for these different targets.all
target executes all platform targets.all
target is the default target. Running make
with no arguments is the same as running make all
.*-debug
targets build the binaries using the Debug configuration.install
target will copy the most recently built MoltenVK.xcframework
into the /Library/Frameworks
folder of your computer. Since /Library/Frameworks
is protected, you will generally need to run it as sudo make install
and enter your password. The install
target just installs the built framework, it does not first build the framework. You will first need to at least run make macos
first.The make
targets all require that Xcode is installed on your system.
Building from the command line creates the same Package
folder structure described above when building from within Xcode.
Once you have compiled and built the MoltenVK runtime distribution package from this MoltenVK repository, as described in the Building MoltenVK section, you can explore how MoltenVK provides Vulkan support on 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
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.
Once you have compiled and built the MoltenVK runtime distribution package from this MoltenVK repository, as described in the Building MoltenVK section, follow the instructions in the Installation section of the Docs/MoltenVK_Runtime_UserGuide.md
document in the Docs
directory, to link the MoltenVK 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 is designed to be an implementation of a Vulkan 1.1 subset that runs on macOS, iOS, and tvOS platforms by mapping Vulkan capability to native Metal capability.
The fundamental design and development goal of MoltenVK is to provide this capability in a way that is both maximally compliant with the Vulkan 1.1 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, and tvOS 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
document in the Docs
directory.
The MoltenVK development team welcomes you to post Issues of non-compliance, and engage in discussions about how compliance can be improved, and non-compliant features can be implemented or worked around.
MoltenVK is a key component of the Khronos Vulkan Portability Initiative, whose intention is to provide specifications, resources, and tools to allow developers to understand and design their Vulkan apps for maximum cross-platform compatibility and portability, including on platforms, such as macOS, iOS, and tvOS, where a native Vulkan driver is not available.
If you have a question about using MoltenVK, you can ask it in 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.
If you encounter an issue with the Vulkan SDK, including the Validation Layers, you can report it in the Vulkan SDK Issues List.
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. 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.
As a public open-source project, MoltenVK benefits from code contributions from a wide range of developers, and we encourage you to get involved and contribute code to this MoltenVK repository.
To contribute your code, submit a Pull Request to this repository. The first time you do this, you will be asked to agree to the MoltenVK Contributor License Agreement.
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.
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, 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.
Metal, and other Objective-C objects in Apple's SDK frameworks, use reference counting for memory management. When instantiating Objective-C objects, it is important that you do not rely on implied autorelease pools to do memory management for you. Because many Vulkan games and apps may be ported from other platforms, they will typically not include autorelease pools in their threading models.
Avoid the use of the autorelease
method, or any object creation methods that imply use of autorelease
, (eg- [NSString stringWithFormat: ]
, etc). Instead, favour 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 code blocks in an @autoreleasepool {...}
block.
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
.