DOCSEARCHbyAlgolia
Submit Docs

MoltenVK Documentation

repository·main·Indexed 26 days ago

https://github.com/khronosgroup/moltenvk

MoltenVK is a Vulkan 1.4 implementation layer that maps Vulkan graphics and compute calls to Apple's Metal framework, enabling cross-platform development on macOS, iOS, tvOS, and visionOS. This documentation covers building the library via Xcode or command line, managing external dependencies like SPIRV-Cross and SPIRV-Tools, and configuring runtime behavior using environment variables, build settings, or the VK_EXT_layer_settings extension.

Tokens
16.2K
Snippets
24
Records
171
Agent score
88%

What's inside MoltenVK

  1. Build MoltenVK with Xcode

    main

    Open MoltenVKPackaging.xcodeproj in Xcode (version 15.0.1 or later is supported). You can build the entire runtime distribution or individual components using various schemes.

    Resulting packages are placed in the Package directory, with subdirectories for Release, Debug, and a Latest symlink.

    Available Schemes:

    • MoltenVK Package (Release)
    • MoltenVK Package (Debug)
    • MoltenVK Package (macOS only)
    • MoltenVK Package (iOS only)
    • MoltenVK Package (tvOS only)
    • MoltenVK Package (visionOS only) (requires Xcode 15+)

  2. Configure MoltenVK via VK_EXT_layer_settings

    main

    The preferred way to configure MoltenVK at runtime is using the standard Vulkan VK_EXT_layer_settings extension. This allows you to override build-time and environment variable settings during VkInstance creation.

    To use this mechanism, set VkLayerSettingEXT::pLayerName to the value of kMVKMoltenVKDriverLayerName (found in mvk_vulkan.h) or simply use the string "MoltenVK".

  3. Develop Vulkan applications for macOS using the Vulkan SDK

    main

    The recommended method for macOS development is using the official Vulkan SDK, which includes a MoltenVK runtime library.

    Because MoltenVK supports the VK_KHR_portability_subset extension, the Vulkan Loader will only enumerate MoltenVK VkPhysicalDevices if you enable the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR flag in your vkCreateInstance() call.

  5. Fetch MoltenVK source code and dependencies

    main

    To build a customized version of MoltenVK, clone the repository and use the fetchDependencies script to build required external libraries. You must specify target platforms for the build.

    Prerequisites:

    • cmake and python3 (via brew install cmake python3)
    • Optional: ninja for faster builds (brew install ninja)

    Steps:

    1. Clone the repository: git clone https://github.com/KhronosGroup/MoltenVK.git
    2. Run the dependency script: ./fetchDependencies [platform...]

    Supported Platform Flags:

    • --all: Builds for all supported platforms and simulators.
    • --macos
    • --ios
    • --iossim
    • --maccat
    • --tvos
    • --tvossim

  7. Configure MoltenVK via runtime environment variables

    main
    MoltenVK supports runtime configuration using environment variables. This allows you to modify behavior such as ImageView swizzling, GPU switching, and queue family specialization without recompiling. Note that some features like ImageView swizzling are disabled by default.

  8. Regression test changes to SPIRV-Cross

    main

    If you are developing features for MoltenVK that require modifying the SPIRV-Cross repository, you can build a new libSPIRVCross.a static library by running the ExternalDependencies Xcode scheme in the ExternalDependencies.xcodeproj project.

    To regression test your changes, run the following commands from the External/SPIRV-Cross directory:

    cd External/SPIRV-Cross
./checkout_glslang_spirv_tools.sh
./build_glslang_spirv_tools.sh
./test_shaders.sh

  9. Replace the Vulkan SDK libMoltenVK.dylib on macOS

    main

    To use your own build of MoltenVK instead of the one provided by the Vulkan SDK:

    1. Build macOS MoltenVK. To match the Vulkan SDK's logging level, use: make macos MVK_CONFIG_LOG_LEVEL=1
    2. Install it to the system directory: sudo make install

    This overwrites /usr/local/lib/libMoltenVK.dylib.

    make macos MVK_CONFIG_LOG_LEVEL=1
sudo make install

  10. Optimize iOS Image Performance with VK_KHR_image_format_list

    main
    To improve performance on iOS, you can use VK_KHR_image_format_list to disable MTLTextureUsagePixelFormatView if your image views only utilize swizzles or sRGB conversion. This allows Metal to use lossless texture compression.

  11. Update external library versions

    main

    MoltenVK uses specific versions of external libraries determined by GitHub commit identifiers stored in the ExternalRevisions directory. To update a library version:

    1. Locate the corresponding *_repo_revision file for the library (e.g., ExternalRevisions/cereal_repo_revision for *cereal`).
    2. Change the value in that file to the new commit identifier.
    3. Run the ./fetchDependencies script again to retrieve the updated versions.