From c1f1dd09d54469ed6a4ae06b3645af5508b1aa77 Mon Sep 17 00:00:00 2001 From: Bill Hollings Date: Thu, 19 Mar 2020 18:01:05 -0400 Subject: [PATCH] Update documentation to clarify that MoltenVK is not a fully-compliant implementation of Vulkan. --- Docs/MoltenVK_Runtime_UserGuide.md | 28 ++++++++++++---------------- Docs/Whats_New.md | 2 ++ README.md | 12 +++++------- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/Docs/MoltenVK_Runtime_UserGuide.md b/Docs/MoltenVK_Runtime_UserGuide.md index 92f3d0be..826bfeee 100644 --- a/Docs/MoltenVK_Runtime_UserGuide.md +++ b/Docs/MoltenVK_Runtime_UserGuide.md @@ -53,13 +53,11 @@ distribution package, see the main [`README.md`](../README.md) document in the ` About **MoltenVK** ------------------ -**MoltenVK** is an implementation of the [*Vulkan 1.0*](https://www.khronos.org/vulkan) -graphics and compute API, that runs on Apple's [*Metal*](https://developer.apple.com/metal) -graphics and compute framework on both *iOS* and *macOS*. - -**MoltenVK** allows you to use the *Vulkan* graphics and compute API to develop modern, -cross-platform, high-performance graphical games and applications, and to run them across -many platforms, including both *iOS* and *macOS*. +**MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan) +graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) +graphics and compute framework on both *iOS* and *macOS*. **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 both *iOS* and *macOS*. *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders @@ -239,7 +237,7 @@ in your source code files as follows: #include -In addition to the core *Vulkan* API, **MoltenVK** also supports the following *Vulkan* extensions: +In addition to core *Vulkan* functionality, **MoltenVK** also supports the following *Vulkan* extensions: - `VK_KHR_16bit_storage` - `VK_KHR_8bit_storage` @@ -303,9 +301,9 @@ a convenient way to enable this extension automatically. ### MoltenVK `VK_MVK_moltenvk` Extension -The `VK_MVK_moltenvk` *Vulkan* extension provides functionality beyond the standard *Vulkan* API, to -support configuration options and behaviour that is specific to the **MoltenVK** implementation of *Vulkan*. -You can access this functionality by including the `vk_mvk_moltenvk.h` header file in your code. +The `VK_MVK_moltenvk` *Vulkan* extension provides functionality beyond standard *Vulkan* functionality, +to support configuration options and behaviour that is specific to the **MoltenVK** implementation of *Vulkan* +functionality. You can access this functionality by including the `vk_mvk_moltenvk.h` header file in your code. The `vk_mvk_moltenvk.h` file also includes the API documentation for this `VK_MVK_moltenvk` extension. The following API header files are included in the **MoltenVK** package, each of which @@ -545,11 +543,9 @@ Known **MoltenVK** Limitations This section documents the known limitations in this version of **MoltenVK**. -- **MoltenVK** is a Layer-0 driver implementation of *Vulkan 1.0* - Since it takes on the role of a driver in the Vulkan architecture, 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 - [LunarG Vulkan SDK](https://vulkan.lunarg.com). +- 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 [LunarG Vulkan SDK](https://vulkan.lunarg.com). - Application-controlled memory allocations using `VkAllocationCallbacks` are ignored. diff --git a/Docs/Whats_New.md b/Docs/Whats_New.md index 10aadf34..9555af76 100644 --- a/Docs/Whats_New.md +++ b/Docs/Whats_New.md @@ -26,6 +26,8 @@ Released 2020/03/30 - 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`. +- Update the `README.md` and `MoltenVK_Runtime_UserGuide.md` documents to clarify that + **MoltenVK** is not a fully-compliant implementation of *Vulkan*. diff --git a/README.md b/README.md index 0b8a531f..e9a815cb 100644 --- a/README.md +++ b/README.md @@ -57,13 +57,11 @@ document in the `Docs` directory. Introduction to MoltenVK ------------------------ -**MoltenVK** is a driver-level implementation of the [*Vulkan 1.0*](https://www.khronos.org/vulkan) -graphics and compute API, that runs on Apple's [*Metal*](https://developer.apple.com/metal) -graphics and compute framework on both *iOS* and *macOS*. - -**MoltenVK** allows you to use the *Vulkan* graphics and compute API to develop modern, -cross-platform, high-performance graphical games and applications, and to run them across -many platforms, including both *iOS* and *macOS*. +**MoltenVK** is a layered implementation of [*Vulkan 1.0*](https://www.khronos.org/vulkan) +graphics and compute functionality, that is built on Apple's [*Metal*](https://developer.apple.com/metal) +graphics and compute framework on both *iOS* and *macOS*. **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 both *iOS* and *macOS*. *Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than *Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders