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

Merge pull request #2095 from billhollings/VK_EXT_layer_settings

Browse Source 
Add support for VK_EXT_layer_settings extension
This commit is contained in:
Bill Hollings 2023-12-19 18:22:02 -05:00 committed by GitHub
commit 76233bc654
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
42 changed files with 1662 additions and 1587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Common/MVKCommonEnvironment.h
View File

@ -31,8 +31,8 @@ extern "C" {
* Compiler build setting that ensures a definite value for whether this
* build is a debug build or not.
*
* If the standard DEBUG build setting is defined, MVK_DEBUG is set to true,
* otherwise, it is set to false.
* If the standard DEBUG build setting is defined, MVK_CONFIG_DEBUG is
* set to true, otherwise, it is set to false.
*/
#ifndef MVK_DEBUG
# ifdef DEBUG
@ -41,6 +41,9 @@ extern "C" {
# define MVK_DEBUG 0
# endif
#endif
#ifndef MVK_CONFIG_DEBUG
# define MVK_CONFIG_DEBUG MVK_DEBUG
#endif
/** Building for macOS. */
#ifndef MVK_MACOS

12
Demos/README.md
View File

@ -24,19 +24,19 @@ Table of Contents
*Cube*
------
The basic canonical *Cube* sample app from the
[*Vulkan-Tools* repository](https://github.com/KhronosGroup/Vulkan-Tools)
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
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-iOS`, `Cube-tvOS`, or `Cube-macOS` *Scheme* from within *Xcode*.
To run this demo, run the `Cube-iOS`, `Cube-tvOS`, or `Cube-macOS` *Scheme* from within *Xcode*.
In addition to devices, this demo will also run on the `iOS Simulator` or `tvOS Simulator` destinations.
The `Cube` demo is a simple example of installing **MoltenVK** as an `XCFramework` that is
The `Cube` demo is a simple example of installing **MoltenVK** as an `XCFramework` that is
statically linked to the application. It supports all platforms, including _Mac Catalyst_, _iOS
Simulator_ and _tvOS Simulator_, and all architectures including _Apple Silicon_.
@ -46,5 +46,5 @@ Simulator_ and _tvOS Simulator_, and all architectures including _Apple Silicon_
*Khronos Vulkan Samples*
----------------------
*Khronos Group* provides a [repository](https://github.com/KhronosGroup/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*.

665
Docs/MoltenVK_Configuration_Parameters.md Normal file
View File

@ -0,0 +1,665 @@
<a class="site-logo" href="https://github.com/KhronosGroup/MoltenVK" title="MoltenVK">
<img src="images/MoltenVK-Logo-Banner.png" alt="MoltenVK" style="width:256px;height:auto">
</a>
MoltenVK Configuration Parameters
=================================
Copyright (c) 2015-2023 [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: `4202496`
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:
- `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`)
---------------------------------------
#### 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. This feature requires _Metal 2.2 (macOS 10.15+, iOS/tvOS 13+)_.
---------------------------------------
#### 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.
The queue for which the frame is 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.
##### 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. For the automatic GPU capture to occur, the
_Xcode_ scheme under which the app is run must have the _Metal_ GPU capture option enabled.
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, unless the shader includes execution
capabilities, such as `SignedZeroInfNanPreserve`, that require it to be compiled without fast math.
##### Default: `1`
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`, so that fast math will be disabled when compiling shaders
that request specific math accuracy and precision capabilities, such as `SignedZeroInfNanPreserve`.
---------------------------------------
#### 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_FULL_IMAGE_VIEW_SWIZZLE
##### Type: Boolean
##### Default: `0`
If _Metal_ supports native per-texture swizzling (_macOS 10.15+ with Mac 2 GPU_, _ios/tvOS 13+_),
this parameter is ignored.
When running on an older version of _Metal_ that does not support native per-texture swizzling,
if this parameter is enabled, `VkImageView` swizzling is automatically performed in the converted
_Metal_ shader code during all texture sampling and reading operations. This occurs regardless
of whether a swizzle is required for the `VkImageView` associated with the _Metal_ texture,
which may result in reduced performance.
If disabled, and native _Metal_ per-texture swizzling is not available on the platform, the
following very limited set of `VkImageView` component swizzles is supported via format substitutions:
```
Texture format Swizzle
-------------- -------
VK_FORMAT_R8_UNORM ZERO, ANY, ANY, RED
VK_FORMAT_A8_UNORM ALPHA, ANY, ANY, ZERO
VK_FORMAT_R8G8B8A8_UNORM BLUE, GREEN, RED, ALPHA
VK_FORMAT_R8G8B8A8_SRGB BLUE, GREEN, RED, ALPHA
VK_FORMAT_B8G8R8A8_UNORM BLUE, GREEN, RED, ALPHA
VK_FORMAT_B8G8R8A8_SRGB BLUE, GREEN, RED, ALPHA
VK_FORMAT_D32_SFLOAT_S8_UINT RED, ANY, ANY, ANY (stencil only)
VK_FORMAT_D24_UNORM_S8_UINT RED, ANY, ANY, ANY (stencil only)
```
If native per-texture swizzling is not available, and this feature is not enabled,
an error is logged and returned in the following situations:
- `VkImageView` creation if that `VkImageView` requires full image view swizzling.
- A pipeline that was not compiled with full image view swizzling uses a `VkImageView` that is expecting a swizzle.
- `VkPhysicalDeviceImageFormatInfo2KHR` is passed in a call to `vkGetPhysicalDeviceImageFormatProperties2KHR()`
to query for an `VkImageView` format that will require full swizzling.
---------------------------------------
#### 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_PREALLOCATE_DESCRIPTORS
##### Type: Boolean
##### Default: `1`
Controls whether **MoltenVK** should preallocate memory in each `VkDescriptorPool` according
to the values of the `VkDescriptorPoolSize` parameters. Doing so may improve descriptor set
allocation performance and memory stability at a cost of preallocated application memory.
If this setting is disabled, the descriptors required for a descriptor set will be individually
dynamically allocated in application memory when the descriptor set itself is allocated.
---------------------------------------
#### 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`
Pipeline cache compression is available for _macOS 10.15+_, and _iOS/tvOS 13.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_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_SUPPORT_LARGE_QUERY_POOLS
##### Type: Boolean
##### Default: `1`
Depending on the GPU, _Metal_ allows 8,192 or 32,768 occlusion queries per `MTLBuffer`.
If enabled, **MoltenVK** allocates a `MTLBuffer` for each query pool, allowing each query
pool to support that permitted number of queries. This may slow performance or cause
unexpected behaviour if the query pool is not established prior to a _Metal_ renderpass,
or if the query pool is changed within a renderpass. If disabled, one `MTLBuffer` will
be shared by all query pools, which improves performance, but limits the total device
queries to the permitted number.
---------------------------------------
#### 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`
_(The default value is `0` for OS versions prior to macOS 10.14+/iOS 12+)._
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: Enumeration
- `0`: Don't use _Metal_ Argument Buffers.
- `1`: Use _Metal_ Argument Buffers for all pipelines.
- `2`: Use _Metal_ Argument Buffers only if the `VK_EXT_descriptor_indexing` extension is enabled.
##### Default: `0`
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.
_**NOTE:**_ Currently, _Metal_ argument buffer support is in beta stage, and is only supported on _macOS 11.0+_,
or on older versions of _macOS_ using an _Intel_ GPU. _Metal_ argument buffers support is not available on _iOS_ or _tvOS_.
Development to support _iOS_ and _tvOS_ and a wider combination of GPU's on older _macOS_ versions is under way.
---------------------------------------
#### MVK_CONFIG_USE_MTLHEAP
##### Type: Boolean
##### Default: `0`
Controls whether **MoltenVK** should use `MTLHeaps` for allocating textures and buffers from device memory.
If this setting is enabled, and placement `MTLHeaps` are available on the platform, **MoltenVK** will allocate a
placement `MTLHeap` for each `VkDeviceMemory` instance, and allocate textures and buffers from that placement heap.
If this parameter is disabled, **MoltenVK** will allocate textures and buffers from general device memory.
Apple recommends that `MTLHeaps` should only be used for specific requirements such as aliasing or hazard tracking,
and **MoltenVK** testing has shown that allocating multiple textures of different types or usages from one `MTLHeap`
can occassionally cause corruption issues under certain circumstances.
---------------------------------------
#### 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` if it is available on the platform, regardless of the value of this parameter.

401
Docs/MoltenVK_Runtime_UserGuide.md
View File

@ -46,7 +46,7 @@ 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
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.
@ -55,20 +55,20 @@ distribution package, see the main [`README.md`](../README.md) document in the `
About **MoltenVK**
------------------
**MoltenVK** is a layered implementation of [*Vulkan 1.2*](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
**MoltenVK** is a layered implementation of [*Vulkan 1.2*](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* on *macOS 11.0+*.
*Metal* uses a different shading language, the *Metal Shading Language (MSL)*, than
*Vulkan*, which uses *SPIR-V*. **MoltenVK** automatically converts your *SPIR-V* shaders
*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
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*.
@ -78,56 +78,56 @@ 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 a universal `XCFramework` or as a *dynamic library* (`.dylib`). Distributing an app containing
a dynamic library via the *iOS App Store* or *tvOS App Store* can require specialized bundling.
If you are unsure about which linking and deployment option you need, or on *iOS* or *tvOS*,
unless you have specific needs for dynamic libraries, follow the steps for linking **MoltenVK**
Depending on your build and deployment needs, you can link **MoltenVK** to your application either
as a universal `XCFramework` or as a *dynamic library* (`.dylib`). Distributing an app containing
a dynamic library via the *iOS App Store* or *tvOS App Store* can require specialized bundling.
If you are unsure about which linking and deployment option you need, or on *iOS* or *tvOS*,
unless you have specific needs for dynamic libraries, follow the steps for linking **MoltenVK**
as an `XCFramework`, as it is the simpler option, and encompasses the largest set of supported platforms.
<a name="install_xcfwk"></a>
### 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.
> ***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.
> 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`
> 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 an `XCFramework`, follow these steps:
1. Open your application in *Xcode* and select your application's target in the
1. Open your application in *Xcode* and select your application's target in the
*Project Navigator* panel.
2. Open the *Build Settings* tab.
1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
add an entry that points to the `MoltenVK/include` folder.
2. If using `IOSurfaces` on *iOS*, open the **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET`)
setting, and ensure it is set to a value of `iOS 11.0` or greater, or if using `IOSurfaces` on *tvOS*,
2. If using `IOSurfaces` on *iOS*, open the **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET`)
setting, and ensure it is set to a value of `iOS 11.0` or greater, or if using `IOSurfaces` on *tvOS*,
open the **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET`) setting, and ensure it is set to a
value of `tvOS 11.0` or greater.
3. Open the *Build Phases* tab and open the *Link Binary With Libraries* list.
1. Drag `MoltenVK/MoltenVK.xcframework` to the *Link Binary With Libraries* list.
2. If your application does **_not_** use use `C++`, click the **+** button,
and add `libc++.tbd` by selecting it from the list of system frameworks.
2. 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.
3. 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
3. 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:
- `libc++.tbd` *(if not already done in Step 2)*
- `Metal.framework`
@ -135,7 +135,7 @@ To link **MoltenVK** to your application as an `XCFramework`, follow these steps
- `QuartzCore.framework`
- `IOKit.framework` (*macOS*)
- `UIKit.framework` (*iOS* or *tvOS*)
- `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`,
- `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`,
or *tvOS* if `TVOS_DEPLOYMENT_TARGET` is at least `tvOS 11.0`)
@ -145,50 +145,50 @@ To link **MoltenVK** to your application as an `XCFramework`, follow these steps
To link **MoltenVK** to your application as a dynamic library (`.dylib`), follow these steps:
1. Open your application in *Xcode* and select your application's target in the
1. Open your application in *Xcode* and select your application's target in the
*Project Navigator* panel.
2. Open the *Build Settings* tab.
1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
1. In the **Header Search Paths** (aka `HEADER_SEARCH_PATHS`) setting,
add an entry that points to the `MoltenVK/include` folder.
2. In the **Library Search Paths** (aka `LIBRARY_SEARCH_PATHS`) setting,
2. In the **Library Search Paths** (aka `LIBRARY_SEARCH_PATHS`) setting,
add an entry that points to **_one_** of the following folders:
- `MoltenVK/dylib/macOS` *(macOS)*
- `MoltenVK/dylib/iOS` *(iOS)*
- `MoltenVK/dylib/tvOS` *(tvOS)*
3. In the **Runpath Search Paths** (aka `LD_RUNPATH_SEARCH_PATHS`) setting,
3. 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,
environment. If the dynamic library is to be embedded within your application,
you would typically set this to **_one_** of these values:
- `@executable_path/../Frameworks` *(macOS)*
- `@executable_path/Frameworks` *(iOS or tvOS)*
The `libMoltenVK.dylib` library is internally configured to be located at
The `libMoltenVK.dylib` library is internally configured to be located at
`@rpath/libMoltenVK.dylib`.
3. If using `IOSurfaces` on *iOS*, open the **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET`)
setting, and ensure it is set to a value of `iOS 11.0` or greater, or if using `IOSurfaces` on *tvOS*,
3. If using `IOSurfaces` on *iOS*, open the **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET`)
setting, and ensure it is set to a value of `iOS 11.0` or greater, or if using `IOSurfaces` on *tvOS*,
open the **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET`) setting, and ensure it is set to a
value of `tvOS 11.0` or greater.
3. Open the *Build Phases* tab and open the *Link Binary With Libraries* list.
1. Drag **_one_** of the following files to the *Link Binary With Libraries* list:
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
2. If your application does **_not_** use use `C++`, click the **+** button,
and add `libc++.tbd` by selecting it from the list of system frameworks.
2. 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.
3. 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
3. 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:
- `libc++.tbd` *(if not already done in Step 2)*
- `Metal.framework`
@ -196,30 +196,30 @@ To link **MoltenVK** to your application as a dynamic library (`.dylib`), follow
- `QuartzCore.framework`
- `IOKit.framework` (*macOS*)
- `UIKit.framework` (*iOS* or *tvOS*)
- `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`,
- `IOSurface.framework` (*macOS*, or *iOS* if `IPHONEOS_DEPLOYMENT_TARGET` is at least `iOS 11.0`,
or *tvOS* if `TVOS_DEPLOYMENT_TARGET` is at least `tvOS 11.0`)
4. Arrange to install the `libMoltenVK.dylib` file in your application environment:
- To copy the `libMoltenVK.dylib` file into your application or component library:
1. On the *Build Phases* tab, add a new *Copy Files* build phase.
2. Set the *Destination* into which you want to place the `libMoltenVK.dylib` file.
Typically this will be *Frameworks* (and it should match the **Runpath Search Paths**
Typically this will be *Frameworks* (and it should match the **Runpath Search Paths**
(aka `LD_RUNPATH_SEARCH_PATHS`) build setting you added above).
3. Drag **_one_** of the following files to the *Copy Files* list in this new build phase:
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
- Alternately, you may create your own installation mechanism to install one of the following
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
- Alternately, you may create your own installation mechanism to install one of the following
files into a standard *macOS*, *iOS*, or *tvOS* system library folder on the user's device:
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
- `MoltenVK/dylib/macOS/libMoltenVK.dylib` *(macOS)*
- `MoltenVK/dylib/iOS/libMoltenVK.dylib` *(iOS)*
- `MoltenVK/dylib/tvOS/libMoltenVK.dylib` *(tvOS)*
<a name="install_vksdk"></a>
### Install *MoltenVK* replacing the Vulkan SDK `libMoltenVK.dylib`
@ -261,33 +261,33 @@ $ make macos MVK_CONFIG_LOG_LEVEL=1
**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*.
>***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, any app that uses **MoltenVK** must be
built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `) build setting
>***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, any app that uses **MoltenVK** must be
built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `) build setting
of `iOS 11.0` or greater, or a minimum **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET `)
build setting of `tvOS 11.0` or greater.
Once built, your app integrating the **MoltenVK** libraries can be run on *macOS*, *iOS* or *tvOS*
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 10.11*, *iOS 9*, or *tvOS 9*
- At runtime, **MoltenVK** requires at least *macOS 10.11*, *iOS 9*, or *tvOS 9*
(or *iOS 11* or *tvOS 11* if using `IOSurfaces`).
- Information on *macOS* devices that are compatible with *Metal* can be found in
- Information on *macOS* devices that are compatible with *Metal* can be found in
[this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible).
- Information on *iOS* devices that are compatible with *Metal* can be found in
- Information on *iOS* devices that are compatible with *Metal* can be found in
[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.
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
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
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)
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.
@ -296,13 +296,13 @@ To improve performance and gain the benefits of *Metal*, perform the following i
Interacting with the **MoltenVK** Runtime
-----------------------------------------
You programmatically configure and interact with the **MoltenVK** runtime through function
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
*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 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 <vulkan/vulkan.h>
@ -367,9 +367,9 @@ In addition to core *Vulkan* functionality, **MoltenVK** also supports the foll
- `VK_EXT_debug_marker`
- `VK_EXT_debug_report`
- `VK_EXT_debug_utils`
- `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
- `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`.*
@ -386,26 +386,27 @@ In addition to core *Vulkan* functionality, **MoltenVK** also supports the foll
- `VK_EXT_host_query_reset`
- `VK_EXT_image_robustness`
- `VK_EXT_inline_uniform_block`
- `VK_EXT_layer_settings`
- `VK_EXT_memory_budget`
- *Requires Metal 2.0.*
- `VK_EXT_metal_objects`
- `VK_EXT_metal_surface`
- `VK_EXT_pipeline_creation_cache_control`
- `VK_EXT_pipeline_creation_feedback`
- `VK_EXT_post_depth_coverage`
- `VK_EXT_post_depth_coverage`
- *iOS and macOS, requires family 4 (A11) or better Apple GPU.*
- `VK_EXT_private_data `
- `VK_EXT_robustness2`
- `VK_EXT_sample_locations`
- `VK_EXT_scalar_block_layout`
- `VK_EXT_separate_stencil_usage`
- `VK_EXT_shader_atomic_float`
- `VK_EXT_shader_atomic_float`
- *Requires Metal 3.0.*
- `VK_EXT_shader_demote_to_helper_invocation`
- `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`
- `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.*
@ -420,9 +421,9 @@ In addition to core *Vulkan* functionality, **MoltenVK** also supports the foll
- *Requires Metal 2.0.*
- `VK_EXT_texture_compression_astc_hdr`
- *iOS and macOS, requires family 6 (A13) or better Apple GPU.*
- `VK_MVK_ios_surface`
- `VK_MVK_ios_surface`
- *Obsolete. Use `VK_EXT_metal_surface` instead.*
- `VK_MVK_macos_surface`
- `VK_MVK_macos_surface`
- *Obsolete. Use `VK_EXT_metal_surface` instead.*
- `VK_AMD_gpu_shader_half_float`
- `VK_AMD_negative_viewport_height`
@ -438,106 +439,112 @@ In addition to core *Vulkan* functionality, **MoltenVK** also supports the foll
- `VK_NV_glsl_shader`
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
`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
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
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
>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.
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
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.
<a name="moltenvk_headers"></a>
### MoltenVK Header Files
**MoltenVK** provides additional functionality beyond standard *Vulkan* functionality,
to support configuration options and query behaviour that is specific to the **MoltenVK**
**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
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 <MoltenVK/HEADER_FILE>
where `HEADER_FILE` is one of the following:
- `mvk_vulkan.h` - This is a convenience header file that loads the `<vulkan/vulkan.h>` header file
with platform settings to enable the appropriate platform-surface and portability extensions.
- `mvk_config.h` - Contains public functions and structures to allow you to configure and
optimize **MoltenVK** for your particular application runtime requirements. For more
information, see the [Configuring MoltenVK](#moltenvk_config) section just below.
- `mvk_private_api.h` - Contains functions and structures to allow you to query **MoltenVK**
performance activity, and Metal capabilities on the platform. _**NOTE:**_ THESE
FUNCTIONS 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
- `mvk_vulkan.h` - This is a convenience header file that loads the `<vulkan/vulkan.h>` 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.
<a name="moltenvk_config"></a>
### Configuring MoltenVK
The `mvk_config.h` header file provides the ability to configure and optimize **MoltenVK**
for your particular application runtime requirements. This 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.
**MoltenVK** provides the ability to configure and optimize **MoltenVK** for your particular
application runtime requirements and development-time needs.
There are three mechanisms for setting the values of the **MoltenVK** configuration parameters:
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.
- Runtime API via the `vkGetMoltenVKConfigurationMVK()/vkSetMoltenVKConfigurationMVK()` functions.
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.
To change some of the **MoltenVK** configuration settings at runtime using a programmatic API,
use the `vkGetMoltenVKConfigurationMVK()` and `vkSetMoltenVKConfigurationMVK()` functions to
retrieve, modify, and set a copy of the `MVKConfiguration` structure.
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.
The initial value of each of the configuration settings can be established at runtime
by a corresponding environment variable, or if the environment variable is not set,
by a corresponding build setting at the time **MoltenVK** is compiled. The environment
variable and build setting for each configuration parameter share the same name.
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"`).
See the description of the `MVKConfiguration` structure parameters and corresponding
environment variables in the `mvk_config.h` file for more info about configuring and
optimizing **MoltenVK** at runtime or build time.
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.
<a name="shaders"></a>
*Metal Shading Language* Shaders
--------------------------------
*Metal* uses a different shader language than *Vulkan*. *Vulkan* uses the new
*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*
**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.
@ -545,29 +552,27 @@ to their *MSL* equivalents, during loading your *SPIR-V* shaders, using the stan
<a name="spv_vs_msl"></a>
### 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,
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 the
logging of the *SPIR-V* and *MSL* shader source code during shader conversion, by turning on the
`MVKConfiguration::debugMode` configuration parameter, or setting the value of the `MVK_CONFIG_DEBUG`
runtime environment variable to `1`. See the [*MoltenVK Configuration*](#moltenvk_config)
description above.
- 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
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
- 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.
- 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.
@ -581,22 +586,22 @@ This section discusses various options for improving performance when using **Mo
<a name="shader_load_time"></a>
### Shader Loading Time
A number of steps is required to load and compile *SPIR-V* shaders into a form that *Metal* can use.
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
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,
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
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.
@ -608,13 +613,13 @@ step of converting the *SPIR-V* to *MSL* again.
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.
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
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
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.
@ -622,21 +627,21 @@ vailable when you request it, resulting in frame delays and visual stuttering.
<a name="timestamping"></a>
### 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.
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
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
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.
<a name="xcode_config"></a>
### Xcode Configuration
When a *Metal* app is running from *Xcode*, the default ***Scheme*** settings reduce performance.
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.
@ -644,7 +649,7 @@ found in the in the [installation](#install) section above.
<a name="trace_tool"></a>
### Metal System Trace Tool
To help you get the best performance from your graphics app, the *Xcode Instruments* profiling 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*.
@ -656,28 +661,28 @@ Known **MoltenVK** Limitations
------------------------------
This section documents the known limitations in this version of **MoltenVK**.
- See [above](#interaction) for known limitations for specific Vulkan extensions.
- On *macOS* versions prior to *macOS 10.15.6*, native host-coherent image device memory is not available.
Because of this, changes made to `VkImage VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` device memory by the CPU
or GPU will not be available to the GPU or CPU, respectively, until the memory is flushed or unmapped by
the application. Applications using `vkMapMemory()` with `VkImage VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
Because of this, changes made to `VkImage VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` device memory by the CPU
or GPU will not be available to the GPU or CPU, respectively, until the memory is flushed or unmapped by
the application. Applications using `vkMapMemory()` with `VkImage VK_MEMORY_PROPERTY_HOST_COHERENT_BIT`
device memory on *macOS* versions prior to *macOS 10.15.6* must call either `vkUnmapMemory()`, or
`vkFlushMappedMemoryRanges()` / `vkInvalidateMappedMemoryRanges()` to ensure memory changes are coherent
between the CPU and GPU. This limitation does **_not_** apply to `VKImage` device memory on *macOS*
starting with *macOS 10.15.6*, does not apply to `VKImage` device memory on any version of *iOS* or *tvOS*,
`vkFlushMappedMemoryRanges()` / `vkInvalidateMappedMemoryRanges()` to ensure memory changes are coherent
between the CPU and GPU. This limitation does **_not_** apply to `VKImage` device memory on *macOS*
starting with *macOS 10.15.6*, does not apply to `VKImage` device memory on any version of *iOS* or *tvOS*,
and does **_not_** apply to `VKBuffer` device memory on any platform.
- 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.
- 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)*
- 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.

3
Docs/Whats_New.md
View File

@ -21,12 +21,15 @@ Released TBD
- Add support for extensions:
- `VK_EXT_extended_dynamic_state3` *(Metal does not support `VK_POLYGON_MODE_POINT`)*
- `VK_EXT_headless_surface`
- `VK_EXT_layer_settings`
- Fix regression that broke `VK_POLYGON_MODE_LINE`.
- Fix regression in marking rendering state dirty after `vkCmdClearAttachments()`.
- Reduce disk space consumed after running `fetchDependencies` script by removing intermediate file caches.
- 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.
- Deprecate `vkSetMoltenVKConfigurationMVK()`.
- Deprecate `mvk_config.h` and move content to `mvk_private_api.h` and `mvk_deprecated_api.h`.
- Update to latest SPIRV-Cross:
- MSL: Fix regression error in argument buffer runtime arrays.
- MSL: Work around broken cube texture gradients on Apple Silicon.

2
ExternalRevisions/Vulkan-Headers_repo_revision
View File

@ -1 +1 @@
7b3466a1f47a9251ac1113efbe022ff016e2f95b
19a863ccce773ff393b186329478b1eb1a519fd3

1072
MoltenVK/MoltenVK/API/mvk_config.h
View File

File diff suppressed because it is too large Load Diff

18
MoltenVK/MoltenVK/API/mvk_deprecated_api.h
View File

@ -24,7 +24,7 @@
extern "C" {
#endif // __cplusplus
#include <MoltenVK/mvk_config.h>
#include <MoltenVK/mvk_private_api.h>
#include <IOSurface/IOSurfaceRef.h>
@ -34,6 +34,7 @@ extern "C" {
/**
* This header contains obsolete and deprecated MoltenVK functions, that were originally
* part of the obsolete and deprecated non-standard VK_MVK_moltenvk extension.
* This header is provided for legacy compatibility only.
*
* NOTE: USE OF THE FUNCTIONS BELOW IS NOT RECOMMENDED. THE VK_MVK_moltenvk EXTENSION,
* AND THE FUNCTIONS BELOW ARE NOT SUPPORTED BY THE VULKAN LOADER AND LAYERS.
@ -49,6 +50,7 @@ extern "C" {
#pragma mark -
#pragma mark Function types
typedef VkResult (VKAPI_PTR *PFN_vkSetMoltenVKConfigurationMVK)(VkInstance ignored, const MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
typedef void (VKAPI_PTR *PFN_vkGetVersionStringsMVK)(char* pMoltenVersionStringBuffer, uint32_t moltenVersionStringBufferLength, char* pVulkanVersionStringBuffer, uint32_t vulkanVersionStringBufferLength);
typedef void (VKAPI_PTR *PFN_vkSetWorkgroupSizeMVK)(VkShaderModule shaderModule, uint32_t x, uint32_t y, uint32_t z);
typedef VkResult (VKAPI_PTR *PFN_vkUseIOSurfaceMVK)(VkImage image, IOSurfaceRef ioSurface);
@ -72,6 +74,20 @@ typedef void (VKAPI_PTR *PFN_vkGetMTLCommandQueueMVK)(VkQueue queue, id<MTLComma
#define MVK_DEPRECATED_USE_MTL_OBJS VKAPI_ATTR [[deprecated("Use the VK_EXT_metal_objects extension instead.")]]
/**
* DEPRECATED.
* To set configuration values, use one of the following mechansims:
*
* - The standard Vulkan VK_EXT_layer_settings extension (layer name "MoltenVK").
* - Application runtime environment variables.
* - Build settings at MoltenVK build time.
*/
VKAPI_ATTR [[deprecated("Use the VK_EXT_layer_settings extension, or environment variables, instead.")]]
VkResult VKAPI_CALL vkSetMoltenVKConfigurationMVK(
VkInstance instance,
const MVKConfiguration* pConfiguration,
size_t* pConfigurationSize);
/**
* DEPRECATED.
* Returns a human readable version of the MoltenVK and Vulkan versions.

292
MoltenVK/MoltenVK/API/mvk_private_api.h
View File

@ -34,8 +34,8 @@ typedef unsigned long MTLArgumentBuffersTier;
/**
* This header contains functions to query MoltenVK about
* available Metal features, and runtime performance information.
* This header contains private structures and functions to query MoltenVK about MoltenVK version
* and configuration, runtime performance information, and available Metal capabilities.
*
* NOTE: THE FUNCTIONS BELOW SHOULD BE USED WITH CARE. THESE FUNCTIONS ARE
* NOT PART OF VULKAN, AND ARE NOT SUPPORTED BY THE VULKAN LOADER AND LAYERS.
@ -44,9 +44,213 @@ typedef unsigned long MTLArgumentBuffersTier;
*/
#define MVK_PRIVATE_API_VERSION 38
#define MVK_PRIVATE_API_VERSION 39
#pragma mark -
#pragma mark MoltenVK version
/**
* The version number of MoltenVK is a single integer value, derived from the Major, Minor,
* and Patch version values, where each of the Major, Minor, and Patch components is allocated
* two decimal digits, in the format MjMnPt. This creates a version number that is both human
* readable and allows efficient computational comparisons to a single integer number.
*
* The following examples illustrate how the MoltenVK version number is built from its components:
* - 002000 (version 0.20.0)
* - 010000 (version 1.0.0)
* - 030104 (version 3.1.4)
* - 401215 (version 4.12.15)
*/
#define MVK_VERSION_MAJOR 1
#define MVK_VERSION_MINOR 2
#define MVK_VERSION_PATCH 7
#define MVK_MAKE_VERSION(major, minor, patch) (((major) * 10000) + ((minor) * 100) + (patch))
#define MVK_VERSION MVK_MAKE_VERSION(MVK_VERSION_MAJOR, MVK_VERSION_MINOR, MVK_VERSION_PATCH)
#pragma mark -
#pragma mark MoltenVK configuration
/**
* 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 (layer name "MoltenVK").
* - 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.
*/
/** Identifies the level of logging MoltenVK should be limited to outputting. */
typedef enum MVKConfigLogLevel {
MVK_CONFIG_LOG_LEVEL_NONE = 0, /**< No logging. */
MVK_CONFIG_LOG_LEVEL_ERROR = 1, /**< Log errors only. */
MVK_CONFIG_LOG_LEVEL_WARNING = 2, /**< Log errors and warning messages. */
MVK_CONFIG_LOG_LEVEL_INFO = 3, /**< Log errors, warnings and informational messages. */
MVK_CONFIG_LOG_LEVEL_DEBUG = 4, /**< Log errors, warnings, infos and debug messages. */
MVK_CONFIG_LOG_LEVEL_MAX_ENUM = 0x7FFFFFFF
} MVKConfigLogLevel;
/** Identifies the level of Vulkan call trace logging MoltenVK should perform. */
typedef enum MVKConfigTraceVulkanCalls {
MVK_CONFIG_TRACE_VULKAN_CALLS_NONE = 0, /**< No Vulkan call logging. */
MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER = 1, /**< Log the name of each Vulkan call when the call is entered. */
MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_THREAD_ID = 2, /**< Log the name and thread ID of each Vulkan call when the call is entered. */
MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT = 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. */
MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT_THREAD_ID = 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. */
MVK_CONFIG_TRACE_VULKAN_CALLS_DURATION = 5, /**< Same as MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT, plus logs the time spent inside the Vulkan function. */
MVK_CONFIG_TRACE_VULKAN_CALLS_DURATION_THREAD_ID = 6, /**< Same as MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT_THREAD_ID, plus logs the time spent inside the Vulkan function. */
MVK_CONFIG_TRACE_VULKAN_CALLS_MAX_ENUM = 0x7FFFFFFF
} MVKConfigTraceVulkanCalls;
/** Identifies the scope for Metal to run an automatic GPU capture for diagnostic debugging purposes. */
typedef enum MVKConfigAutoGPUCaptureScope {
MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_NONE = 0, /**< No automatic GPU capture. */
MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_DEVICE = 1, /**< Automatically capture all GPU activity during the lifetime of a VkDevice. */
MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_FRAME = 2, /**< Automatically capture all GPU activity during the rendering and presentation of the first frame. */
MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_MAX_ENUM = 0x7FFFFFFF
} MVKConfigAutoGPUCaptureScope;
/** Identifies extensions to advertise as part of MoltenVK configuration. */
typedef enum MVKConfigAdvertiseExtensionBits {
MVK_CONFIG_ADVERTISE_EXTENSIONS_ALL = 0x00000001, /**< All supported extensions. */
MVK_CONFIG_ADVERTISE_EXTENSIONS_WSI = 0x00000002, /**< WSI extensions supported on the platform. */
MVK_CONFIG_ADVERTISE_EXTENSIONS_PORTABILITY = 0x00000004, /**< Vulkan Portability Subset extensions. */
MVK_CONFIG_ADVERTISE_EXTENSIONS_MAX_ENUM = 0x7FFFFFFF
} MVKConfigAdvertiseExtensionBits;
typedef VkFlags MVKConfigAdvertiseExtensions;
/** Identifies the use of Metal Argument Buffers. */
typedef enum MVKUseMetalArgumentBuffers {
MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_NEVER = 0, /**< Don't use Metal Argument Buffers. */
MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_ALWAYS = 1, /**< Use Metal Argument Buffers for all pipelines. */
MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_DESCRIPTOR_INDEXING = 2, /**< Use Metal Argument Buffers only if VK_EXT_descriptor_indexing extension is enabled. */
MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_MAX_ENUM = 0x7FFFFFFF
} MVKUseMetalArgumentBuffers;
/** Identifies the Metal functionality used to support Vulkan semaphore functionality (VkSemaphore). */
typedef enum MVKVkSemaphoreSupportStyle {
MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_SINGLE_QUEUE = 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. */
MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_METAL_EVENTS_WHERE_SAFE = 1, /**< Use Metal events (MTLEvent) when available on the platform, and where safe. This will revert to same as MVK_CONFIG_VK_SEMAPHORE_USE_SINGLE_QUEUE on some NVIDIA GPUs and Rosetta2, due to potential challenges with MTLEvents on those platforms, or in older environments where MTLEvents are not supported. */
MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_METAL_EVENTS = 2, /**< Always use Metal events (MTLEvent) when available on the platform. This will revert to same as MVK_CONFIG_VK_SEMAPHORE_USE_SINGLE_QUEUE in older environments where MTLEvents are not supported. */
MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_CALLBACK = 3, /**< Use CPU callbacks upon GPU submission completion. This is the slowest technique, but allows multiple queues, compared to MVK_CONFIG_VK_SEMAPHORE_USE_SINGLE_QUEUE. */
MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_MAX_ENUM = 0x7FFFFFFF
} MVKVkSemaphoreSupportStyle;
/** Identifies the style of Metal command buffer pre-filling to be used. */
typedef enum MVKPrefillMetalCommandBuffersStyle {
MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_NO_PREFILL = 0, /**< During Vulkan command buffer filling, do not prefill a Metal command buffer for each Vulkan command buffer. A single Metal command buffer is 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. */
MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_DEFERRED_ENCODING = 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. */
MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_IMMEDIATE_ENCODING = 2, /**< During Vulkan command buffer filling, immediately encode to the Metal command buffer, as each command is submitted to the Vulkan 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. */
MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_IMMEDIATE_ENCODING_NO_AUTORELEASE = 3, /**< During Vulkan command buffer filling, immediately encode to the Metal command buffer, as each command is submitted to the Vulkan 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. */
MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_MAX_ENUM = 0x7FFFFFFF
} MVKPrefillMetalCommandBuffersStyle;
/** Identifies when Metal shaders will be compiled with the fast math option. */
typedef enum MVKConfigFastMath {
MVK_CONFIG_FAST_MATH_NEVER = 0, /**< Metal shaders will never be compiled with the fast math option. */
MVK_CONFIG_FAST_MATH_ALWAYS = 1, /**< Metal shaders will always be compiled with the fast math option. */
MVK_CONFIG_FAST_MATH_ON_DEMAND = 2, /**< Metal shaders will be compiled with the fast math option, unless the shader includes execution modes that require it to be compiled without fast math. */
MVK_CONFIG_FAST_MATH_MAX_ENUM = 0x7FFFFFFF
} MVKConfigFastMath;
/** Identifies available system data compression algorithms. */
typedef enum MVKConfigCompressionAlgorithm {
MVK_CONFIG_COMPRESSION_ALGORITHM_NONE = 0, /**< No compression. */
MVK_CONFIG_COMPRESSION_ALGORITHM_LZFSE = 1, /**< Apple proprietary. Good balance of high performance and small compression size, particularly for larger data content. */
MVK_CONFIG_COMPRESSION_ALGORITHM_ZLIB = 2, /**< Open cross-platform ZLib format. For smaller data content, has better performance and smaller size than LZFSE. */
MVK_CONFIG_COMPRESSION_ALGORITHM_LZ4 = 3, /**< Fastest performance. Largest compression size. */
MVK_CONFIG_COMPRESSION_ALGORITHM_LZMA = 4, /**< Slowest performance. Smallest compression size, particular with larger content. */
MVK_CONFIG_COMPRESSION_ALGORITHM_MAX_ENUM = 0x7FFFFFFF,
} MVKConfigCompressionAlgorithm;
/** Identifies the style of activity performance logging to use. */
typedef enum MVKConfigActivityPerformanceLoggingStyle {
MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_FRAME_COUNT = 0, /**< Repeatedly log performance after a configured number of frames. */
MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_IMMEDIATE = 1, /**< Log immediately after each performance measurement. */
MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_DEVICE_LIFETIME = 2, /**< Log at the end of the VkDevice lifetime. This is useful for one-shot apps such as testing frameworks. */
MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_DEVICE_LIFETIME_ACCUMULATE = 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. */
MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_MAX_ENUM = 0x7FFFFFFF,
} MVKConfigActivityPerformanceLoggingStyle;
/**
* MoltenVK configuration. You can retrieve a copy of this structure using the vkGetMoltenVKConfigurationMVK() function.
*
* This structure may be extended as new configuration options are added to MoltenVK.
* If you are linking to an implementation of MoltenVK that was compiled from a different
* MVK_PRIVATE_API_VERSION than your app was, the size of this structure in your app
* may be larger or smaller than the struct in MoltenVK. See the description of the
* vkGetMoltenVKConfigurationMVK() function for information about how to handle this.
*
* TO SUPPORT DYNAMIC LINKING TO THIS STRUCTURE AS DESCRIBED ABOVE, THIS STRUCTURE SHOULD NOT
* BE CHANGED EXCEPT TO ADD ADDITIONAL MEMBERS ON THE END. EXISTING MEMBERS, AND THEIR ORDER,
* SHOULD NOT BE CHANGED.
*/
typedef struct {
VkBool32 debugMode; /**< MVK_CONFIG_DEBUG */
VkBool32 shaderConversionFlipVertexY; /**< MVK_CONFIG_SHADER_CONVERSION_FLIP_VERTEX_Y */
VkBool32 synchronousQueueSubmits; /**< MVK_CONFIG_SYNCHRONOUS_QUEUE_SUBMITS */
MVKPrefillMetalCommandBuffersStyle prefillMetalCommandBuffers; /**< MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS */
uint32_t maxActiveMetalCommandBuffersPerQueue; /**< MVK_CONFIG_MAX_ACTIVE_METAL_COMMAND_BUFFERS_PER_QUEUE */
VkBool32 supportLargeQueryPools; /**< MVK_CONFIG_SUPPORT_LARGE_QUERY_POOLS */
VkBool32 presentWithCommandBuffer; /**< Obsolete, deprecated, and ignored. */
VkBool32 swapchainMinMagFilterUseNearest; /**< MVK_CONFIG_SWAPCHAIN_MIN_MAG_FILTER_USE_NEAREST */
uint64_t metalCompileTimeout; /**< MVK_CONFIG_METAL_COMPILE_TIMEOUT */
VkBool32 performanceTracking; /**< MVK_CONFIG_PERFORMANCE_TRACKING */
uint32_t performanceLoggingFrameCount; /**< MVK_CONFIG_PERFORMANCE_LOGGING_FRAME_COUNT */
VkBool32 displayWatermark; /**< MVK_CONFIG_DISPLAY_WATERMARK */
VkBool32 specializedQueueFamilies; /**< MVK_CONFIG_SPECIALIZED_QUEUE_FAMILIES */
VkBool32 switchSystemGPU; /**< MVK_CONFIG_SWITCH_SYSTEM_GPU */
VkBool32 fullImageViewSwizzle; /**< MVK_CONFIG_FULL_IMAGE_VIEW_SWIZZLE */
uint32_t defaultGPUCaptureScopeQueueFamilyIndex; /**< MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_FAMILY_INDEX */
uint32_t defaultGPUCaptureScopeQueueIndex; /**< MVK_CONFIG_DEFAULT_GPU_CAPTURE_SCOPE_QUEUE_INDEX */
MVKConfigFastMath fastMathEnabled; /**< MVK_CONFIG_FAST_MATH_ENABLED */
MVKConfigLogLevel logLevel; /**< MVK_CONFIG_LOG_LEVEL */
MVKConfigTraceVulkanCalls traceVulkanCalls; /**< MVK_CONFIG_TRACE_VULKAN_CALLS */
VkBool32 forceLowPowerGPU; /**< MVK_CONFIG_FORCE_LOW_POWER_GPU */
VkBool32 semaphoreUseMTLFence; /**< Obsolete, deprecated, and ignored. */
MVKVkSemaphoreSupportStyle semaphoreSupportStyle; /**< MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE */
MVKConfigAutoGPUCaptureScope autoGPUCaptureScope; /**< MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE */
const char* autoGPUCaptureOutputFilepath; /**< MVK_CONFIG_AUTO_GPU_CAPTURE_OUTPUT_FILE */
VkBool32 texture1DAs2D; /**< MVK_CONFIG_TEXTURE_1D_AS_2D */
VkBool32 preallocateDescriptors; /**< MVK_CONFIG_PREALLOCATE_DESCRIPTORS */
VkBool32 useCommandPooling; /**< MVK_CONFIG_USE_COMMAND_POOLING */
VkBool32 useMTLHeap; /**< MVK_CONFIG_USE_MTLHEAP */
MVKConfigActivityPerformanceLoggingStyle activityPerformanceLoggingStyle; /**< MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE */
uint32_t apiVersionToAdvertise; /**< MVK_CONFIG_API_VERSION_TO_ADVERTISE */
MVKConfigAdvertiseExtensions advertiseExtensions; /**< MVK_CONFIG_ADVERTISE_EXTENSIONS */
VkBool32 resumeLostDevice; /**< MVK_CONFIG_RESUME_LOST_DEVICE */
MVKUseMetalArgumentBuffers useMetalArgumentBuffers; /**< MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS */
MVKConfigCompressionAlgorithm shaderSourceCompressionAlgorithm; /**< MVK_CONFIG_SHADER_COMPRESSION_ALGORITHM */
VkBool32 shouldMaximizeConcurrentCompilation; /**< MVK_CONFIG_SHOULD_MAXIMIZE_CONCURRENT_COMPILATION */
float timestampPeriodLowPassAlpha; /**< MVK_CONFIG_TIMESTAMP_PERIOD_LOWPASS_ALPHA */
} MVKConfiguration;
// Legacy support for renamed struct elements.
#define swapchainMagFilterUseNearest swapchainMinMagFilterUseNearest
#define semaphoreUseMTLEvent semaphoreSupportStyle
#define logActivityPerformanceInline activityPerformanceLoggingStyle
#pragma mark -
#pragma mark VkPhysicalDevice Metal capabilities
/** Identifies the type of rounding Metal uses for float to integer conversions in particular calculatons. */
typedef enum MVKFloatRounding {
MVK_FLOAT_ROUNDING_NEAREST = 0, /**< Metal rounds to nearest. */
@ -155,6 +359,10 @@ typedef struct {
VkBool32 needsCubeGradWorkaround; /**< If true, sampling from cube textures with explicit gradients is broken and needs a workaround. */
} MVKPhysicalDeviceMetalFeatures;
#pragma mark -
#pragma mark Performance statistics
/**
* MoltenVK performance of a particular type of activity.
* Durations are recorded in milliseconds. Memory sizes are recorded in kilobytes.
@ -229,6 +437,7 @@ typedef struct {
#pragma mark -
#pragma mark Function types
typedef VkResult (VKAPI_PTR *PFN_vkGetMoltenVKConfigurationMVK)(VkInstance ignored, MVKConfiguration* pConfiguration, size_t* pConfigurationSize);
typedef VkResult (VKAPI_PTR *PFN_vkGetPhysicalDeviceMetalFeaturesMVK)(VkPhysicalDevice physicalDevice, MVKPhysicalDeviceMetalFeatures* pMetalFeatures, size_t* pMetalFeaturesSize);
typedef VkResult (VKAPI_PTR *PFN_vkGetPerformanceStatisticsMVK)(VkDevice device, MVKPerformanceStatistics* pPerf, size_t* pPerfSize);
@ -238,6 +447,37 @@ typedef VkResult (VKAPI_PTR *PFN_vkGetPerformanceStatisticsMVK)(VkDevice device,
#ifndef VK_NO_PROTOTYPES
/**
* Populates the pConfiguration structure with the current global MoltenVK configuration settings.
*
* The VkInstance object you provide here is ignored, and a VK_NULL_HANDLE value can be provided.
* This function can be called before the VkInstance has been created. It is safe to call this function
* with a VkInstance retrieved from a different layer in the Vulkan SDK Loader and Layers framework.
*
* If you are linking to an implementation of MoltenVK that was compiled from a different
* MVK_PRIVATE_API_VERSION than your app was, the size of the MVKConfiguration structure
* in your app may be larger or smaller than the same struct as expected by MoltenVK.
*
* When calling this function, set the value of *pConfigurationSize to sizeof(MVKConfiguration),
* to tell MoltenVK the limit of the size of your MVKConfiguration structure. Upon return from
* this function, the value of *pConfigurationSize will hold the actual number of bytes copied
* into your passed MVKConfiguration structure, which will be the smaller of what your app
* thinks is the size of MVKConfiguration, and what MoltenVK thinks it is. This represents the
* safe access area within the structure for both MoltenVK and your app.
*
* If the size that MoltenVK expects for MVKConfiguration is different than the value passed in
* *pConfigurationSize, this function will return VK_INCOMPLETE, otherwise it will return VK_SUCCESS.
*
* Although it is not necessary, you can use this function to determine in advance the value
* that MoltenVK expects the size of MVKConfiguration to be by setting the value of pConfiguration
* to NULL. In that case, this function will set *pConfigurationSize to the size that MoltenVK
* expects MVKConfiguration to be.
*/
VKAPI_ATTR VkResult VKAPI_CALL vkGetMoltenVKConfigurationMVK(
VkInstance ignored,
MVKConfiguration* pConfiguration,
size_t* pConfigurationSize);
/**
* Populates the pMetalFeatures structure with the Metal-specific features
* supported by the specified physical device.
@ -303,6 +543,52 @@ VKAPI_ATTR VkResult VKAPI_CALL vkGetPerformanceStatisticsMVK(
#endif // VK_NO_PROTOTYPES
#pragma mark -
#pragma mark Shaders
/**
* NOTE: Shader code should be submitted as SPIR-V. Although some simple direct MSL shaders may work,
* direct loading of MSL source code or compiled MSL code is not officially supported at this time.
* Future versions of MoltenVK may support direct MSL submission again.
*
* Enumerates the magic number values to set in the MVKMSLSPIRVHeader when
* submitting a SPIR-V stream that contains either Metal Shading Language source
* code or Metal Shading Language compiled binary code in place of SPIR-V code.
*/
typedef enum {
kMVKMagicNumberSPIRVCode = 0x07230203, /**< SPIR-V stream contains standard SPIR-V code. */
kMVKMagicNumberMSLSourceCode = 0x19960412, /**< SPIR-V stream contains Metal Shading Language source code. */
kMVKMagicNumberMSLCompiledCode = 0x19981215, /**< SPIR-V stream contains Metal Shading Language compiled binary code. */
} MVKMSLMagicNumber;
/**
* NOTE: Shader code should be submitted as SPIR-V. Although some simple direct MSL shaders may work,
* direct loading of MSL source code or compiled MSL code is not officially supported at this time.
* Future versions of MoltenVK may support direct MSL submission again.
*
* Describes the header at the start of an SPIR-V stream, when it contains either
* Metal Shading Language source code or Metal Shading Language compiled binary code.
*
* To submit MSL source code to the vkCreateShaderModule() function in place of SPIR-V
* code, prepend a MVKMSLSPIRVHeader containing the kMVKMagicNumberMSLSourceCode magic
* number to the MSL source code. The MSL source code must be null-terminated.
*
* To submit MSL compiled binary code to the vkCreateShaderModule() function in place of
* SPIR-V code, prepend a MVKMSLSPIRVHeader containing the kMVKMagicNumberMSLCompiledCode
* magic number to the MSL compiled binary code.
*
* In both cases, the pCode element of VkShaderModuleCreateInfo should pointer to the
* location of the MVKMSLSPIRVHeader, and the MSL code should start at the byte immediately
* after the MVKMSLSPIRVHeader.
*
* The codeSize element of VkShaderModuleCreateInfo should be set to the entire size of
* the submitted code memory, including the additional sizeof(MVKMSLSPIRVHeader) bytes
* taken up by the MVKMSLSPIRVHeader, and, in the case of MSL source code, including
* the null-terminator byte.
*/
typedef uint32_t MVKMSLSPIRVHeader;
#ifdef __cplusplus
}
#endif // __cplusplus

5
MoltenVK/MoltenVK/API/mvk_vulkan.h
View File

@ -24,7 +24,7 @@
*
* When building for iOS, this header also automatically enables the obsolete VK_MVK_ios_surface Vulkan extension.
* When building for macOS, this header also automatically enables the obsolete VK_MVK_macos_surface Vulkan extension.
* Both of these extensions are obsolete. Consider using the portable VK_EXT_metal_surface extension instead.
* Both of these extensions are deprecated. Use the portable VK_EXT_metal_surface extension instead.
*/
#ifndef __mvk_vulkan_h_
@ -47,4 +47,7 @@
#include <vulkan/vulkan.h>
/** The name of the MoltenVK driver layer. */
static const char* kMVKMoltenVKDriverLayerName = "MoltenVK";
#endif

29
MoltenVK/MoltenVK/API/vk_mvk_moltenvk.h
View File

@ -17,24 +17,31 @@
*/
/**
* This header is provided for legacy compatibility only. This header contains obsolete and
* deprecated MoltenVK functions, that were originally part of the obsolete and deprecated
* non-standard VK_MVK_moltenvk extension, and use of this header is not recommended.
*
* This header contains obsolete and deprecated MoltenVK functions, that were originally
* part of the obsolete and deprecated non-standard VK_MVK_moltenvk extension.
* This header is provided for legacy compatibility only.
* Instead, in your application, use the following header file:
*
* #include <MoltenVK/mvk_vulkan.h>
*
* And if you require the MoltenVK Configuration API, also include the following header file:
* To configure MoltenVK, use one of the following mechanisms,
* as documented in MoltenVK_Configuration_Parameters.md:
*
* #include <MoltenVK/mvk_config.h>
* - The standard Vulkan VK_EXT_layer_settings extension (layer name "MoltenVK").
* - Application runtime environment variables.
* - Build settings at MoltenVK build time.
*
* If you require access to private structures and functions to query MoltenVK about MoltenVK
* version and configuration, runtime performance information, and available Metal capabilities,
* use the following header file:
*
* #include <MoltenVK/mvk_private_api.h>
*
* If you require access to Metal objects underlying equivalent Vulkan objects,
* use the standard Vulkan VK_EXT_metal_objects extension.
*/
#include "mvk_vulkan.h"
#include "mvk_config.h"
#include "mvk_private_api.h"
#include "mvk_deprecated_api.h"
#include <MoltenVK/mvk_vulkan.h>
#include <MoltenVK/mvk_private_api.h>
#include <MoltenVK/mvk_deprecated_api.h>

4
MoltenVK/MoltenVK/Commands/MVKCommandBuffer.mm
View File

@ -121,7 +121,7 @@ VkResult MVKCommandBuffer::begin(const VkCommandBufferBeginInfo* pBeginInfo) {
if(_device->shouldPrefillMTLCommandBuffers() && !(_isSecondary || _supportsConcurrentExecution)) {
@autoreleasepool {
_prefilledMTLCmdBuffer = [_commandPool->getMTLCommandBuffer(kMVKCommandUseBeginCommandBuffer, 0) retain]; // retained
auto prefillStyle = mvkConfig().prefillMetalCommandBuffers;
auto prefillStyle = getMVKConfig().prefillMetalCommandBuffers;
if (prefillStyle == MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_IMMEDIATE_ENCODING ||
prefillStyle == MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_IMMEDIATE_ENCODING_NO_AUTORELEASE ) {
_immediateCmdEncodingContext = new MVKCommandEncodingContext;
@ -193,7 +193,7 @@ VkResult MVKCommandBuffer::end() {
}
void MVKCommandBuffer::checkDeferredEncoding() {
if (mvkConfig().prefillMetalCommandBuffers == MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_DEFERRED_ENCODING) {
if (getMVKConfig().prefillMetalCommandBuffers == MVK_CONFIG_PREFILL_METAL_COMMAND_BUFFERS_STYLE_DEFERRED_ENCODING) {
@autoreleasepool {
MVKCommandEncodingContext encodingContext;
MVKCommandEncoder encoder(this);

2
MoltenVK/MoltenVK/GPUObjects/MVKDescriptorSet.mm
View File

@ -710,7 +710,7 @@ size_t MVKDescriptorPool::getPoolSize(const VkDescriptorPoolCreateInfo* pCreateI
MVKDescriptorPool::MVKDescriptorPool(MVKDevice* device, const VkDescriptorPoolCreateInfo* pCreateInfo) :
MVKVulkanAPIDeviceObject(device),
_hasPooledDescriptors(mvkConfig().preallocateDescriptors), // Set this first! Accessed by MVKDescriptorSet constructor and getPoolSize() in following lines.
_hasPooledDescriptors(getMVKConfig().preallocateDescriptors), // Set this first! Accessed by MVKDescriptorSet constructor and getPoolSize() in following lines.
_descriptorSets(pCreateInfo->maxSets, MVKDescriptorSet(this)),
_descriptorSetAvailablility(pCreateInfo->maxSets, true),
_inlineBlockMTLBufferAllocator(device, device->_pMetalFeatures->dynamicMTLBufferSize, true),

9
MoltenVK/MoltenVK/GPUObjects/MVKDevice.h
View File

@ -26,7 +26,6 @@
#include "MVKSmallVector.h"
#include "MVKPixelFormats.h"
#include "MVKOSExtensions.h"
#include "mvk_private_api.h"
#include "mvk_datatypes.hpp"
#include <string>
#include <mutex>
@ -357,8 +356,8 @@ public:
bool mslVersionIsAtLeast(MTLLanguageVersion minVer) { return _metalFeatures.mslVersionEnum >= minVer; }
/** Returns whether this physical device supports Metal argument buffers. */
bool supportsMetalArgumentBuffers() const {
return _metalFeatures.argumentBuffers && mvkConfig().useMetalArgumentBuffers != MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_NEVER;
bool supportsMetalArgumentBuffers() {
return _metalFeatures.argumentBuffers && getMVKConfig().useMetalArgumentBuffers != MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_NEVER;
};
@ -1063,9 +1062,9 @@ protected:
* sorted according to power, with higher power GPU's at the front of the array.
* This ensures that a lazy app that simply grabs the first GPU will get a high-power
* one by default. If MVKConfiguration::forceLowPowerGPU is enabled, the returned
* array will only include low-power devices.
* array will only include low-power devices. The instance may be a nullptr.
*/
NSArray<id<MTLDevice>>* mvkGetAvailableMTLDevicesArray();
NSArray<id<MTLDevice>>* mvkGetAvailableMTLDevicesArray(MVKInstance* instance);
/** Returns the registry ID of the specified device, or zero if the device does not have a registry ID. */
uint64_t mvkGetRegistryID(id<MTLDevice> mtlDevice);

58
MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm
View File

@ -361,7 +361,7 @@ void MVKPhysicalDevice::getFeatures(VkPhysicalDeviceFeatures2* features) {
portabilityFeatures->events = true;
portabilityFeatures->imageViewFormatReinterpretation = true;
portabilityFeatures->imageViewFormatSwizzle = (_metalFeatures.nativeTextureSwizzle ||
mvkConfig().fullImageViewSwizzle);
getMVKConfig().fullImageViewSwizzle);
portabilityFeatures->imageView2DOn3DImage = false;
portabilityFeatures->multisampleArrayImage = _metalFeatures.multisampleArrayTextures;
portabilityFeatures->mutableComparisonSamplers = _metalFeatures.depthSampleCompare;
@ -379,7 +379,7 @@ void MVKPhysicalDevice::getFeatures(VkPhysicalDeviceFeatures2* features) {
auto* formatFeatures = (VkPhysicalDevice4444FormatsFeaturesEXT*)next;
bool canSupport4444 = _metalFeatures.tileBasedDeferredRendering &&
(_metalFeatures.nativeTextureSwizzle ||
mvkConfig().fullImageViewSwizzle);
getMVKConfig().fullImageViewSwizzle);
formatFeatures->formatA4R4G4B4 = canSupport4444;
formatFeatures->formatA4B4G4R4 = canSupport4444;
break;
@ -533,7 +533,7 @@ void MVKPhysicalDevice::getProperties(VkPhysicalDeviceProperties2* properties) {
supportedProps12.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_PROPERTIES;
supportedProps12.pNext = nullptr;
supportedProps12.driverID = VK_DRIVER_ID_MOLTENVK;
strcpy(supportedProps12.driverName, "MoltenVK");
strcpy(supportedProps12.driverName, kMVKMoltenVKDriverLayerName);
strcpy(supportedProps12.driverInfo, mvkGetMoltenVKVersionString(MVK_VERSION).c_str());
supportedProps12.conformanceVersion.major = 0;
supportedProps12.conformanceVersion.minor = 0;
@ -945,7 +945,7 @@ VkResult MVKPhysicalDevice::getImageFormatProperties(VkFormat format,
case VK_IMAGE_TYPE_1D:
maxExt.height = 1;
maxExt.depth = 1;
if (!mvkConfig().texture1DAs2D) {
if (!getMVKConfig().texture1DAs2D) {
maxExt.width = pLimits->maxImageDimension1D;
maxLevels = 1;
sampleCounts = VK_SAMPLE_COUNT_1_BIT;
@ -1535,7 +1535,7 @@ VkResult MVKPhysicalDevice::getPresentRectangles(MVKSurface* surface,
MVKArrayRef<MVKQueueFamily*> MVKPhysicalDevice::getQueueFamilies() {
if (_queueFamilies.empty()) {
VkQueueFamilyProperties qfProps;
bool specialize = mvkConfig().specializedQueueFamilies;
bool specialize = getMVKConfig().specializedQueueFamilies;
uint32_t qfIdx = 0;
qfProps.queueCount = kMVKQueueCountPerQueueFamily;
@ -1630,7 +1630,7 @@ void MVKPhysicalDevice::updateTimestampPeriod() {
// Basic lowpass filter TPout = (1 - A)TPout + (A * TPin).
// The lower A is, the slower TPout will change over time.
auto& vkTsp = _properties.limits.timestampPeriod;
float a = mvkConfig().timestampPeriodLowPassAlpha;
float a = getMVKConfig().timestampPeriodLowPassAlpha;
float tsPeriod = elapsedCPUNanos / elapsedGPUTicks;
vkTsp = ((1.0 - a) * vkTsp) + (a * tsPeriod);
}
@ -1700,8 +1700,8 @@ MVKPhysicalDevice::MVKPhysicalDevice(MVKInstance* mvkInstance, id<MTLDevice> mtl
void MVKPhysicalDevice::initMTLDevice() {
#if MVK_XCODE_14_3 && MVK_MACOS && !MVK_MACCAT
if ([_mtlDevice respondsToSelector: @selector(setShouldMaximizeConcurrentCompilation:)]) {
[_mtlDevice setShouldMaximizeConcurrentCompilation: mvkConfig().shouldMaximizeConcurrentCompilation];
MVKLogInfoIf(mvkConfig().debugMode, "maximumConcurrentCompilationTaskCount %lu", _mtlDevice.maximumConcurrentCompilationTaskCount);
[_mtlDevice setShouldMaximizeConcurrentCompilation: getMVKConfig().shouldMaximizeConcurrentCompilation];
MVKLogInfoIf(getMVKConfig().debugMode, "maximumConcurrentCompilationTaskCount %lu", _mtlDevice.maximumConcurrentCompilationTaskCount);
}
#endif
}
@ -1710,7 +1710,7 @@ void MVKPhysicalDevice::initMTLDevice() {
void MVKPhysicalDevice::initProperties() {
mvkClear(&_properties); // Start with everything cleared
_properties.apiVersion = mvkConfig().apiVersionToAdvertise;
_properties.apiVersion = getMVKConfig().apiVersionToAdvertise;
_properties.driverVersion = MVK_VERSION;
initGPUInfoProperties();
@ -1817,7 +1817,7 @@ void MVKPhysicalDevice::initMetalFeatures() {
if ( mvkOSVersionIsAtLeast(13.0) ) {
_metalFeatures.mslVersionEnum = MTLLanguageVersion2_2;
_metalFeatures.placementHeaps = mvkConfig().useMTLHeap;
_metalFeatures.placementHeaps = getMVKConfig().useMTLHeap;
_metalFeatures.nativeTextureSwizzle = true;
if (supportsMTLGPUFamily(Apple3)) {
_metalFeatures.native3DCompressedTextures = true;
@ -1925,7 +1925,7 @@ void MVKPhysicalDevice::initMetalFeatures() {
if ( mvkOSVersionIsAtLeast(13.0) ) {
_metalFeatures.mslVersionEnum = MTLLanguageVersion2_2;
_metalFeatures.placementHeaps = mvkConfig().useMTLHeap;
_metalFeatures.placementHeaps = getMVKConfig().useMTLHeap;
#if MVK_OS_SIMULATOR
_metalFeatures.nativeTextureSwizzle = false;
#else
@ -2042,7 +2042,7 @@ void MVKPhysicalDevice::initMetalFeatures() {
}
if (supportsMTLGPUFamily(Mac2)) {
_metalFeatures.nativeTextureSwizzle = true;
_metalFeatures.placementHeaps = mvkConfig().useMTLHeap;
_metalFeatures.placementHeaps = getMVKConfig().useMTLHeap;
_metalFeatures.renderWithoutAttachments = true;
}
}
@ -3272,7 +3272,7 @@ void MVKPhysicalDevice::initVkSemaphoreStyle() {
// Default to single queue if other options unavailable.
_vkSemaphoreStyle = MVKSemaphoreStyleSingleQueue;
switch (mvkConfig().semaphoreSupportStyle) {
switch (getMVKConfig().semaphoreSupportStyle) {
case MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_METAL_EVENTS_WHERE_SAFE: {
bool isNVIDIA = _properties.vendorID == kNVVendorId;
bool isRosetta2 = _properties.vendorID == kAppleVendorId && !MVK_APPLE_SILICON;
@ -4109,7 +4109,7 @@ void MVKDevice::destroyRenderPass(MVKRenderPass* mvkRP,
MVKCommandPool* MVKDevice::createCommandPool(const VkCommandPoolCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator) {
return new MVKCommandPool(this, pCreateInfo, mvkConfig().useCommandPooling);
return new MVKCommandPool(this, pCreateInfo, getMVKConfig().useCommandPooling);
}
void MVKDevice::destroyCommandPool(MVKCommandPool* mvkCmdPool,
@ -4268,7 +4268,7 @@ void MVKDevice::updateActivityPerformance(MVKPerformanceTracker& activity, doubl
double total = (activity.average * activity.count++) + currentValue;
activity.average = total / activity.count;
if (_isPerformanceTracking && mvkConfig().activityPerformanceLoggingStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_IMMEDIATE) {
if (_isPerformanceTracking && getMVKConfig().activityPerformanceLoggingStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_IMMEDIATE) {
logActivityInline(activity, _performanceStatistics);
}
}
@ -4533,8 +4533,8 @@ id<MTLBuffer> MVKDevice::getDummyBlitMTLBuffer() {
MTLCompileOptions* MVKDevice::getMTLCompileOptions(bool requestFastMath, bool preserveInvariance) {
MTLCompileOptions* mtlCompOpt = [MTLCompileOptions new];
mtlCompOpt.languageVersion = _pMetalFeatures->mslVersionEnum;
mtlCompOpt.fastMathEnabled = (mvkConfig().fastMathEnabled == MVK_CONFIG_FAST_MATH_ALWAYS ||
(mvkConfig().fastMathEnabled == MVK_CONFIG_FAST_MATH_ON_DEMAND && requestFastMath));
mtlCompOpt.fastMathEnabled = (getMVKConfig().fastMathEnabled == MVK_CONFIG_FAST_MATH_ALWAYS ||
(getMVKConfig().fastMathEnabled == MVK_CONFIG_FAST_MATH_ON_DEMAND && requestFastMath));
#if MVK_XCODE_12
if ([mtlCompOpt respondsToSelector: @selector(setPreserveInvariance:)]) {
[mtlCompOpt setPreserveInvariance: preserveInvariance];
@ -4545,7 +4545,7 @@ MTLCompileOptions* MVKDevice::getMTLCompileOptions(bool requestFastMath, bool pr
// Can't use prefilled Metal command buffers if any of the resource descriptors can be updated after binding.
bool MVKDevice::shouldPrefillMTLCommandBuffers() {
return (mvkConfig().prefillMetalCommandBuffers &&
return (getMVKConfig().prefillMetalCommandBuffers &&
!(_enabledDescriptorIndexingFeatures.descriptorBindingUniformBufferUpdateAfterBind ||
_enabledDescriptorIndexingFeatures.descriptorBindingSampledImageUpdateAfterBind ||
_enabledDescriptorIndexingFeatures.descriptorBindingStorageImageUpdateAfterBind ||
@ -4557,7 +4557,7 @@ bool MVKDevice::shouldPrefillMTLCommandBuffers() {
void MVKDevice::startAutoGPUCapture(MVKConfigAutoGPUCaptureScope autoGPUCaptureScope, id mtlCaptureObject) {
if (_isCurrentlyAutoGPUCapturing || (mvkConfig().autoGPUCaptureScope != autoGPUCaptureScope)) { return; }
if (_isCurrentlyAutoGPUCapturing || (getMVKConfig().autoGPUCaptureScope != autoGPUCaptureScope)) { return; }
_isCurrentlyAutoGPUCapturing = true;
@ -4569,7 +4569,7 @@ void MVKDevice::startAutoGPUCapture(MVKConfigAutoGPUCaptureScope autoGPUCaptureS
captureDesc.captureObject = mtlCaptureObject;
captureDesc.destination = MTLCaptureDestinationDeveloperTools;
const char* filePath = mvkConfig().autoGPUCaptureOutputFilepath;
const char* filePath = getMVKConfig().autoGPUCaptureOutputFilepath;
if (strlen(filePath)) {
if ([captureMgr respondsToSelector: @selector(supportsDestination:)] &&
[captureMgr supportsDestination: MTLCaptureDestinationGPUTraceDocument] ) {
@ -4605,7 +4605,7 @@ void MVKDevice::startAutoGPUCapture(MVKConfigAutoGPUCaptureScope autoGPUCaptureS
}
void MVKDevice::stopAutoGPUCapture(MVKConfigAutoGPUCaptureScope autoGPUCaptureScope) {
if (_isCurrentlyAutoGPUCapturing && mvkConfig().autoGPUCaptureScope == autoGPUCaptureScope) {
if (_isCurrentlyAutoGPUCapturing && getMVKConfig().autoGPUCaptureScope == autoGPUCaptureScope) {
[[MTLCaptureManager sharedCaptureManager] stopCapture];
_isCurrentlyAutoGPUCapturing = false;
}
@ -4681,8 +4681,8 @@ MVKDevice::MVKDevice(MVKPhysicalDevice* physicalDevice, const VkDeviceCreateInfo
return;
}
initPerformanceTracking();
initPhysicalDevice(physicalDevice, pCreateInfo);
initPerformanceTracking();
enableExtensions(pCreateInfo);
enableFeatures(pCreateInfo);
initQueues(pCreateInfo);
@ -4694,7 +4694,7 @@ MVKDevice::MVKDevice(MVKPhysicalDevice* physicalDevice, const VkDeviceCreateInfo
// In a multi-GPU system, if we are using the high-power GPU and want the window system
// to also use that GPU to avoid copying content between GPUs, force the window system
// to use the high-power GPU by calling the MTLCreateSystemDefaultDevice() function.
if (_enabledExtensions.vk_KHR_swapchain.enabled && mvkConfig().switchSystemGPU &&
if (_enabledExtensions.vk_KHR_swapchain.enabled && getMVKConfig().switchSystemGPU &&
!(_physicalDevice->_mtlDevice.isLowPower || _physicalDevice->_mtlDevice.isHeadless) ) {
MTLCreateSystemDefaultDevice();
}
@ -4704,8 +4704,8 @@ MVKDevice::MVKDevice(MVKPhysicalDevice* physicalDevice, const VkDeviceCreateInfo
// Use Metal arg buffs if available, and either config wants them always,
// or config wants them with descriptor indexing and descriptor indexing has been enabled.
_isUsingMetalArgumentBuffers = (_physicalDevice->supportsMetalArgumentBuffers() &&
(mvkConfig().useMetalArgumentBuffers == MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_ALWAYS ||
(mvkConfig().useMetalArgumentBuffers == MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_DESCRIPTOR_INDEXING &&
(getMVKConfig().useMetalArgumentBuffers == MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_ALWAYS ||
(getMVKConfig().useMetalArgumentBuffers == MVK_CONFIG_USE_METAL_ARGUMENT_BUFFERS_DESCRIPTOR_INDEXING &&
(_enabledVulkan12FeaturesNoExt.descriptorIndexing || _enabledExtensions.vk_EXT_descriptor_indexing.enabled))));
_commandResourceFactory = new MVKCommandResourceFactory(this);
@ -4720,7 +4720,7 @@ MVKDevice::MVKDevice(MVKPhysicalDevice* physicalDevice, const VkDeviceCreateInfo
static MVKPerformanceStatistics _processPerformanceStatistics = {};
void MVKDevice::initPerformanceTracking() {
_isPerformanceTracking = mvkConfig().performanceTracking;
_isPerformanceTracking = getMVKConfig().performanceTracking;
_performanceStatistics = _processPerformanceStatistics;
}
@ -5019,7 +5019,7 @@ void MVKDevice::reservePrivateData(const VkDeviceCreateInfo* pCreateInfo) {
MVKDevice::~MVKDevice() {
if (_isPerformanceTracking) {
auto perfLogStyle = mvkConfig().activityPerformanceLoggingStyle;
auto perfLogStyle = getMVKConfig().activityPerformanceLoggingStyle;
if (perfLogStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_DEVICE_LIFETIME) {
MVKLogInfo("Device activity performance summary:");
logPerformanceSummary();
@ -5052,12 +5052,12 @@ MVKDevice::~MVKDevice() {
#pragma mark -
#pragma mark Support functions
NSArray<id<MTLDevice>>* mvkGetAvailableMTLDevicesArray() {
NSArray<id<MTLDevice>>* mvkGetAvailableMTLDevicesArray(MVKInstance* instance) {
NSMutableArray* mtlDevs = [NSMutableArray array]; // autoreleased
#if MVK_MACOS
NSArray* rawMTLDevs = [MTLCopyAllDevices() autorelease];
bool forceLowPower = mvkConfig().forceLowPowerGPU;
bool forceLowPower = mvkGetMVKConfig(instance).forceLowPowerGPU;
// Populate the array of appropriate MTLDevices
for (id<MTLDevice> md in rawMTLDevs) {

4
MoltenVK/MoltenVK/GPUObjects/MVKImage.mm
View File

@ -1025,7 +1025,7 @@ VkSampleCountFlagBits MVKImage::validateSamples(const VkImageCreateInfo* pCreate
if (validSamples == VK_SAMPLE_COUNT_1_BIT) { return validSamples; }
// Don't use getImageType() because it hasn't been set yet.
if ( !((pCreateInfo->imageType == VK_IMAGE_TYPE_2D) || ((pCreateInfo->imageType == VK_IMAGE_TYPE_1D) && mvkConfig().texture1DAs2D)) ) {
if ( !((pCreateInfo->imageType == VK_IMAGE_TYPE_2D) || ((pCreateInfo->imageType == VK_IMAGE_TYPE_1D) && getMVKConfig().texture1DAs2D)) ) {
setConfigurationResult(reportError(VK_ERROR_FEATURE_NOT_PRESENT, "vkCreateImage() : Under Metal, multisampling can only be used with a 2D image type. Setting sample count to 1."));
validSamples = VK_SAMPLE_COUNT_1_BIT;
}
@ -1872,7 +1872,7 @@ VkResult MVKImageViewPlane::initSwizzledMTLPixelFormat(const VkImageViewCreateIn
// Enable either native or shader swizzling, depending on what is available, preferring native, and return whether successful.
bool MVKImageViewPlane::enableSwizzling() {
_useNativeSwizzle = _device->_pMetalFeatures->nativeTextureSwizzle;
_useShaderSwizzle = !_useNativeSwizzle && mvkConfig().fullImageViewSwizzle;
_useShaderSwizzle = !_useNativeSwizzle && getMVKConfig().fullImageViewSwizzle;
return _useNativeSwizzle || _useShaderSwizzle;
}

6
MoltenVK/MoltenVK/GPUObjects/MVKInstance.h
View File

@ -71,6 +71,9 @@ public:
/** Returns a pointer to the Vulkan instance. */
MVKInstance* getInstance() override { return this; }
/** Return the MoltenVK configuration info for this VkInstance. */
const MVKConfiguration& getMVKConfig() override { return _enabledExtensions.vk_EXT_layer_settings.enabled ? _mvkConfig : getGlobalMVKConfig(); }
/** Returns the maximum version of Vulkan the application supports. */
inline uint32_t getAPIVersion() { return _appInfo.apiVersion; }
@ -186,6 +189,7 @@ protected:
void propagateDebugName() override {}
void initProcAddrs();
void initMVKConfig(const VkInstanceCreateInfo* pCreateInfo);
void initDebugCallbacks(const VkInstanceCreateInfo* pCreateInfo);
VkDebugReportFlagsEXT getVkDebugReportFlagsFromLogLevel(MVKConfigLogLevel logLevel);
VkDebugUtilsMessageSeverityFlagBitsEXT getVkDebugUtilsMessageSeverityFlagBitsFromLogLevel(MVKConfigLogLevel logLevel);
@ -194,11 +198,13 @@ protected:
void logVersions();
VkResult verifyLayers(uint32_t count, const char* const* names);
MVKConfiguration _mvkConfig;
VkApplicationInfo _appInfo;
MVKSmallVector<MVKPhysicalDevice*, 2> _physicalDevices;
MVKSmallVector<MVKDebugReportCallback*> _debugReportCallbacks;
MVKSmallVector<MVKDebugUtilsMessenger*> _debugUtilMessengers;
std::unordered_map<std::string, MVKEntryPoint> _entryPoints;
std::string _mvkConfigStringHolders[kMVKConfigurationStringCount] = {};
std::mutex _dcbLock;
bool _hasDebugReportCallbacks;
bool _hasDebugUtilsMessengers;

43
MoltenVK/MoltenVK/GPUObjects/MVKInstance.mm
View File

@ -295,7 +295,7 @@ MVKInstance::MVKInstance(const VkInstanceCreateInfo* pCreateInfo) : _enabledExte
// This effort creates a number of autoreleased instances of Metal
// and other Obj-C classes, so wrap it all in an autorelease pool.
@autoreleasepool {
NSArray<id<MTLDevice>>* mtlDevices = mvkGetAvailableMTLDevicesArray();
NSArray<id<MTLDevice>>* mtlDevices = mvkGetAvailableMTLDevicesArray(this);
_physicalDevices.reserve(mtlDevices.count);
for (id<MTLDevice> mtlDev in mtlDevices) {
_physicalDevices.push_back(new MVKPhysicalDevice(this, mtlDev));
@ -316,6 +316,7 @@ MVKInstance::MVKInstance(const VkInstanceCreateInfo* pCreateInfo) : _enabledExte
setConfigurationResult(pWritableExtns->enable(pCreateInfo->enabledExtensionCount,
pCreateInfo->ppEnabledExtensionNames,
getDriverLayer()->getSupportedInstanceExtensions()));
initMVKConfig(pCreateInfo);
MVKLogInfo("Created VkInstance for Vulkan version %s, as requested by app, with the following %d Vulkan extensions enabled:%s",
mvkGetVulkanVersionString(_appInfo.apiVersion).c_str(),
@ -345,6 +346,42 @@ void MVKInstance::initDebugCallbacks(const VkInstanceCreateInfo* pCreateInfo) {
}
}
// If the VK_EXT_layer_settings extension is enabled, initialize the local
// MVKConfiguration from the global version built from environment variables.
void MVKInstance::initMVKConfig(const VkInstanceCreateInfo* pCreateInfo) {
if ( !_enabledExtensions.vk_EXT_layer_settings.enabled ) { return; }
_mvkConfig = getGlobalMVKConfig();
VkLayerSettingsCreateInfoEXT* pLSCreateInfo = nil;
for (const auto* next = (VkBaseInStructure*)pCreateInfo->pNext; next; next = next->pNext) {
switch (next->sType) {
case VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT:
pLSCreateInfo = (VkLayerSettingsCreateInfoEXT*)next;
break;
default:
break;
}
}
if ( !pLSCreateInfo ) { return; }
for (uint32_t lsIdx = 0; lsIdx < pLSCreateInfo->settingCount; lsIdx++) {
const auto* pSetting = &pLSCreateInfo->pSettings[lsIdx];
#define STR(name) #name
#define MVK_CONFIG_MEMBER(member, mbrType, name) \
if(mvkStringsAreEqual(pSetting->pLayerName, getDriverLayer()->getName()) && \
mvkStringsAreEqual(pSetting->pSettingName, STR(MVK_CONFIG_##name))) { \
_mvkConfig.member = *(mbrType*)(pSetting->pValues); \
continue; \
}
#include "MVKConfigMembers.def"
}
mvkSetConfig(_mvkConfig, _mvkConfig, _mvkConfigStringHolders);
}
#define ADD_ENTRY_POINT_MAP(name, func, api, ext1, ext2, isDev) \
_entryPoints[""#name] = { (PFN_vkVoidFunction)&func, api, ext1, ext2, isDev }
@ -458,13 +495,13 @@ void MVKInstance::initProcAddrs() {
// MoltenVK-specific instannce functions, not tied to a Vulkan API version or an extension.
ADD_INST_OPEN_ENTRY_POINT(vkGetMoltenVKConfigurationMVK);
ADD_INST_OPEN_ENTRY_POINT(vkSetMoltenVKConfigurationMVK);
ADD_INST_OPEN_ENTRY_POINT(vkGetPhysicalDeviceMetalFeaturesMVK);
ADD_INST_OPEN_ENTRY_POINT(vkGetPerformanceStatisticsMVK);
// For deprecated MoltenVK-specific functions, suppress compiler deprecation warning.
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-declarations"
ADD_INST_OPEN_ENTRY_POINT(vkSetMoltenVKConfigurationMVK);
ADD_INST_EXT_ENTRY_POINT(vkGetVersionStringsMVK, MVK_MOLTENVK);
ADD_INST_EXT_ENTRY_POINT(vkGetMTLDeviceMVK, MVK_MOLTENVK);
ADD_INST_EXT_ENTRY_POINT(vkSetMTLTextureMVK, MVK_MOLTENVK);
@ -734,7 +771,7 @@ void MVKInstance::logVersions() {
MVKExtensionList allExtns(this, true);
MVKLogInfo("MoltenVK version %s, supporting Vulkan version %s.\n\tThe following %d Vulkan extensions are supported:%s",
mvkGetMoltenVKVersionString(MVK_VERSION).c_str(),
mvkGetVulkanVersionString(mvkConfig().apiVersionToAdvertise).c_str(),
mvkGetVulkanVersionString(getMVKConfig().apiVersionToAdvertise).c_str(),
allExtns.getEnabledCount(),
allExtns.enabledNamesString("\n\t\t", true).c_str());
}

8
MoltenVK/MoltenVK/GPUObjects/MVKPipeline.mm
View File

@ -215,7 +215,7 @@ MVKPipeline::MVKPipeline(MVKDevice* device, MVKPipelineCache* pipelineCache, MVK
_pipelineCache(pipelineCache),
_flags(flags),
_descriptorSetCount(layout->getDescriptorSetCount()),
_fullImageViewSwizzle(mvkConfig().fullImageViewSwizzle) {
_fullImageViewSwizzle(getMVKConfig().fullImageViewSwizzle) {
// Establish descriptor counts and push constants use.
for (uint32_t stage = kMVKShaderStageVertex; stage < kMVKShaderStageCount; stage++) {
@ -1727,11 +1727,11 @@ void MVKGraphicsPipeline::initShaderConversionConfig(SPIRVToMSLConversionConfigu
}
shaderConfig.options.mslOptions.ios_support_base_vertex_instance = getDevice()->_pMetalFeatures->baseVertexInstanceDrawing;
shaderConfig.options.mslOptions.texture_1D_as_2D = mvkConfig().texture1DAs2D;
shaderConfig.options.mslOptions.texture_1D_as_2D = getMVKConfig().texture1DAs2D;
shaderConfig.options.mslOptions.enable_point_size_builtin = isRenderingPoints(pCreateInfo) || reflectData.pointMode;
shaderConfig.options.mslOptions.enable_frag_depth_builtin = pixFmts->isDepthFormat(pixFmts->getMTLPixelFormat(pRendInfo->depthAttachmentFormat));
shaderConfig.options.mslOptions.enable_frag_stencil_ref_builtin = pixFmts->isStencilFormat(pixFmts->getMTLPixelFormat(pRendInfo->stencilAttachmentFormat));
shaderConfig.options.shouldFlipVertexY = mvkConfig().shaderConversionFlipVertexY;
shaderConfig.options.shouldFlipVertexY = getMVKConfig().shaderConversionFlipVertexY;
shaderConfig.options.mslOptions.swizzle_texture_samples = _fullImageViewSwizzle && !getDevice()->_pMetalFeatures->nativeTextureSwizzle;
shaderConfig.options.mslOptions.tess_domain_origin_lower_left = pTessDomainOriginState && pTessDomainOriginState->domainOrigin == VK_TESSELLATION_DOMAIN_ORIGIN_LOWER_LEFT;
shaderConfig.options.mslOptions.multiview = mvkIsMultiview(pRendInfo->viewMask);
@ -2117,7 +2117,7 @@ MVKMTLFunction MVKComputePipeline::getMTLFunction(const VkComputePipelineCreateI
shaderConfig.options.mslOptions.swizzle_texture_samples = _fullImageViewSwizzle && !getDevice()->_pMetalFeatures->nativeTextureSwizzle;
shaderConfig.options.mslOptions.texture_buffer_native = _device->_pMetalFeatures->textureBuffers;
shaderConfig.options.mslOptions.dispatch_base = _allowsDispatchBase;
shaderConfig.options.mslOptions.texture_1D_as_2D = mvkConfig().texture1DAs2D;
shaderConfig.options.mslOptions.texture_1D_as_2D = getMVKConfig().texture1DAs2D;
shaderConfig.options.mslOptions.fixed_subgroup_size = mvkIsAnyFlagEnabled(pSS->flags, VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT) ? 0 : _device->_pMetalFeatures->maxSubgroupSize;
bool useMetalArgBuff = isUsingMetalArgumentBuffers();

4
MoltenVK/MoltenVK/GPUObjects/MVKPixelFormats.mm
View File

@ -1492,7 +1492,7 @@ void MVKPixelFormats::modifyMTLFormatCapabilities() {
modifyMTLFormatCapabilities(_physicalDevice->getMTLDevice());
} else {
@autoreleasepool {
auto* mtlDevs = mvkGetAvailableMTLDevicesArray();
auto* mtlDevs = mvkGetAvailableMTLDevicesArray(nullptr);
if (mtlDevs.count) { modifyMTLFormatCapabilities(mtlDevs[0]); }
}
}
@ -2022,7 +2022,7 @@ void MVKPixelFormats::buildVkFormatMaps() {
#if MVK_IOS || MVK_TVOS
bool supportsNativeTextureSwizzle = mtlDev && mvkOSVersionIsAtLeast(13.0);
#endif
if (!supportsNativeTextureSwizzle && !mvkConfig().fullImageViewSwizzle) {
if (!supportsNativeTextureSwizzle && !getMVKConfig().fullImageViewSwizzle) {
vkDesc.mtlPixelFormat = vkDesc.mtlPixelFormatSubstitute = MTLPixelFormatInvalid;
}
}

2
MoltenVK/MoltenVK/GPUObjects/MVKQueryPool.mm
View File

@ -307,7 +307,7 @@ void MVKOcclusionQueryPool::beginQueryAddedTo(uint32_t query, MVKCommandBuffer*
MVKOcclusionQueryPool::MVKOcclusionQueryPool(MVKDevice* device,
const VkQueryPoolCreateInfo* pCreateInfo) : MVKQueryPool(device, pCreateInfo, 1) {
if (mvkConfig().supportLargeQueryPools) {
if (getMVKConfig().supportLargeQueryPools) {
_queryIndexOffset = 0;
// Ensure we don't overflow the maximum number of queries

16
MoltenVK/MoltenVK/GPUObjects/MVKQueue.mm
View File

@ -39,7 +39,7 @@ id<MTLCommandQueue> MVKQueueFamily::getMTLCommandQueue(uint32_t queueIndex) {
id<MTLCommandQueue> mtlQ = _mtlQueues[queueIndex];
if ( !mtlQ ) {
@autoreleasepool { // Catch any autoreleased objects created during MTLCommandQueue creation
uint32_t maxCmdBuffs = mvkConfig().maxActiveMetalCommandBuffersPerQueue;
uint32_t maxCmdBuffs = getMVKConfig().maxActiveMetalCommandBuffersPerQueue;
mtlQ = [_physicalDevice->getMTLDevice() newCommandQueueWithMaxCommandBufferCount: maxCmdBuffs]; // retained
_mtlQueues[queueIndex] = mtlQ;
}
@ -160,7 +160,7 @@ id<MTLCommandBuffer> MVKQueue::getMTLCommandBuffer(MVKCommandUse cmdUse, bool re
if ([_mtlQueue respondsToSelector: @selector(commandBufferWithDescriptor:)]) {
MTLCommandBufferDescriptor* mtlCmdBuffDesc = [MTLCommandBufferDescriptor new]; // temp retain
mtlCmdBuffDesc.retainedReferences = retainRefs;
if (mvkConfig().debugMode) {
if (getMVKConfig().debugMode) {
mtlCmdBuffDesc.errorOptions |= MTLCommandBufferErrorOptionEncoderExecutionStatus;
}
mtlCmdBuff = [_mtlQueue commandBufferWithDescriptor: mtlCmdBuffDesc];
@ -223,7 +223,7 @@ void MVKQueue::handleMTLCommandBufferError(id<MTLCommandBuffer> mtlCmdBuff) {
// If the error is local to this command buffer, optionally mark the device (but not the
// physical device) as lost, depending on the value of MVKConfiguration::resumeLostDevice.
VkResult vkErr = VK_ERROR_UNKNOWN;
bool markDeviceLoss = !mvkConfig().resumeLostDevice;
bool markDeviceLoss = !getMVKConfig().resumeLostDevice;
bool markPhysicalDeviceLoss = false;
switch (mtlCmdBuff.error.code) {
case MTLCommandBufferErrorBlacklisted:
@ -303,7 +303,7 @@ void MVKQueue::initName() {
void MVKQueue::initExecQueue() {
_execQueue = nil;
if ( !mvkConfig().synchronousQueueSubmits ) {
if ( !getMVKConfig().synchronousQueueSubmits ) {
// Determine the dispatch queue priority
dispatch_qos_class_t dqQOS = MVK_DISPATCH_QUEUE_QOS_CLASS;
int dqPriority = (1.0 - _priority) * QOS_MIN_RELATIVE_PRIORITY;
@ -319,8 +319,8 @@ void MVKQueue::initMTLCommandQueue() {
_mtlQueue = _queueFamily->getMTLCommandQueue(_index); // not retained (cached in queue family)
_submissionCaptureScope = new MVKGPUCaptureScope(this);
if (_queueFamily->getIndex() == mvkConfig().defaultGPUCaptureScopeQueueFamilyIndex &&
_index == mvkConfig().defaultGPUCaptureScopeQueueIndex) {
if (_queueFamily->getIndex() == getMVKConfig().defaultGPUCaptureScopeQueueFamilyIndex &&
_index == getMVKConfig().defaultGPUCaptureScopeQueueIndex) {
getDevice()->startAutoGPUCapture(MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_FRAME, _mtlQueue);
_submissionCaptureScope->makeDefault();
}
@ -715,8 +715,8 @@ void MVKQueuePresentSurfaceSubmission::finish() {
auto cs = _queue->_submissionCaptureScope;
cs->endScope();
cs->beginScope();
if (_queue->_queueFamily->getIndex() == mvkConfig().defaultGPUCaptureScopeQueueFamilyIndex &&
_queue->_index == mvkConfig().defaultGPUCaptureScopeQueueIndex) {
if (_queue->_queueFamily->getIndex() == getMVKConfig().defaultGPUCaptureScopeQueueFamilyIndex &&
_queue->_index == getMVKConfig().defaultGPUCaptureScopeQueueIndex) {
getDevice()->stopAutoGPUCapture(MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE_FRAME);
}

6
MoltenVK/MoltenVK/GPUObjects/MVKShaderModule.mm
View File

@ -156,7 +156,7 @@ void MVKShaderLibrary::setWorkgroupSize(uint32_t x, uint32_t y, uint32_t z) {
void MVKShaderLibrary::compressMSL(const string& msl) {
MVKDevice* mvkDev = _owner->getDevice();
uint64_t startTime = mvkDev->getPerformanceTimestamp();
_compressedMSL.compress(msl, mvkConfig().shaderSourceCompressionAlgorithm);
_compressedMSL.compress(msl, getMVKConfig().shaderSourceCompressionAlgorithm);
mvkDev->addPerformanceInterval(mvkDev->_performanceStatistics.shaderCompilation.mslCompress, startTime);
}
@ -354,7 +354,7 @@ MVKMTLFunction MVKShaderModule::getMTLFunction(SPIRVToMSLConversionConfiguration
bool MVKShaderModule::convert(SPIRVToMSLConversionConfiguration* pShaderConfig,
SPIRVToMSLConversionResult& conversionResult) {
bool shouldLogCode = mvkConfig().debugMode;
bool shouldLogCode = getMVKConfig().debugMode;
bool shouldLogEstimatedGLSL = shouldLogCode;
// If the SPIR-V converter does not have any code, but the GLSL converter does,
@ -509,7 +509,7 @@ id<MTLLibrary> MVKShaderLibraryCompiler::newMTLLibrary(NSString* mslSourceCode,
@synchronized (mtlDev) {
auto mtlCompileOptions = _owner->getDevice()->getMTLCompileOptions(shaderConversionResults.entryPoint.supportsFastMath,
shaderConversionResults.isPositionInvariant);
MVKLogInfoIf(mvkConfig().debugMode, "Compiling Metal shader%s.", mtlCompileOptions.fastMathEnabled ? " with FastMath enabled" : "");
MVKLogInfoIf(getMVKConfig().debugMode, "Compiling Metal shader%s.", mtlCompileOptions.fastMathEnabled ? " with FastMath enabled" : "");
[mtlDev newLibraryWithSource: mslSourceCode
options: mtlCompileOptions
completionHandler: ^(id<MTLLibrary> mtlLib, NSError* error) {

14
MoltenVK/MoltenVK/GPUObjects/MVKSwapchain.mm
View File

@ -144,7 +144,7 @@ bool MVKSwapchain::hasOptimalSurface() {
// Renders the watermark image to the surface.
void MVKSwapchain::renderWatermark(id<MTLTexture> mtlTexture, id<MTLCommandBuffer> mtlCmdBuff) {
if (mvkConfig().displayWatermark) {
if (getMVKConfig().displayWatermark) {
if ( !_licenseWatermark ) {
_licenseWatermark = new MVKWatermarkRandom(getMTLDevice(),
__watermarkTextureContent,
@ -173,7 +173,7 @@ void MVKSwapchain::markFrameInterval() {
_device->updateActivityPerformance(_device->_performanceStatistics.queue.frameInterval, mvkGetElapsedMilliseconds(prevFrameTime, _lastFrameTime));
auto& mvkCfg = mvkConfig();
auto& mvkCfg = getMVKConfig();
bool shouldLogOnFrames = mvkCfg.performanceTracking && mvkCfg.activityPerformanceLoggingStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_FRAME_COUNT;
if (shouldLogOnFrames && (mvkCfg.performanceLoggingFrameCount > 0) && (++_currentPerfLogFrameCount >= mvkCfg.performanceLoggingFrameCount)) {
_currentPerfLogFrameCount = 0;
@ -181,7 +181,7 @@ void MVKSwapchain::markFrameInterval() {
mvkCfg.performanceLoggingFrameCount,
(1000.0 / _device->_performanceStatistics.queue.frameInterval.average),
mvkGetElapsedMilliseconds() / 1000.0);
if (mvkConfig().activityPerformanceLoggingStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_FRAME_COUNT) {
if (getMVKConfig().activityPerformanceLoggingStyle == MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_FRAME_COUNT) {
_device->logPerformanceSummary();
}
}
@ -470,7 +470,7 @@ void MVKSwapchain::initCAMetalLayer(const VkSwapchainCreateInfoKHR* pCreateInfo,
auto* mtlLayer = getCAMetalLayer();
if ( !mtlLayer || getIsSurfaceLost() ) { return; }
auto minMagFilter = mvkConfig().swapchainMinMagFilterUseNearest ? kCAFilterNearest : kCAFilterLinear;
auto minMagFilter = getMVKConfig().swapchainMinMagFilterUseNearest ? kCAFilterNearest : kCAFilterLinear;
mtlLayer.drawableSize = mvkCGSizeFromVkExtent2D(_imageExtent);
mtlLayer.device = getMTLDevice();
mtlLayer.pixelFormat = getPixelFormats()->getMTLPixelFormat(pCreateInfo->imageFormat);
@ -480,9 +480,9 @@ void MVKSwapchain::initCAMetalLayer(const VkSwapchainCreateInfoKHR* pCreateInfo,
mtlLayer.magnificationFilter = minMagFilter;
mtlLayer.contentsGravity = getCALayerContentsGravity(pScalingInfo);
mtlLayer.framebufferOnly = !mvkIsAnyFlagEnabled(pCreateInfo->imageUsage, (VK_IMAGE_USAGE_TRANSFER_SRC_BIT |
VK_IMAGE_USAGE_TRANSFER_DST_BIT |
VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_STORAGE_BIT));
VK_IMAGE_USAGE_TRANSFER_DST_BIT |
VK_IMAGE_USAGE_SAMPLED_BIT |
VK_IMAGE_USAGE_STORAGE_BIT));
// Because of a regression in Metal, the most recent one or two presentations may not
// complete and call back. Changing the CAMetalLayer drawableSize will force any incomplete

4
MoltenVK/MoltenVK/GPUObjects/MVKSync.mm
View File

@ -576,13 +576,13 @@ void MVKMetalCompiler::compile(unique_lock<mutex>& lock, dispatch_block_t block)
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ @autoreleasepool { block(); } });
// Limit timeout to avoid overflow since wait_for() uses wait_until()
chrono::nanoseconds nanoTimeout(min(mvkConfig().metalCompileTimeout, kMVKUndefinedLargeUInt64));
chrono::nanoseconds nanoTimeout(min(getMVKConfig().metalCompileTimeout, kMVKUndefinedLargeUInt64));
_blocker.wait_for(lock, nanoTimeout, [this]{ return _isCompileDone; });
if ( !_isCompileDone ) {
@autoreleasepool {
NSString* errDesc = [NSString stringWithFormat: @"Timeout after %.3f milliseconds. Likely internal Metal compiler error", (double)nanoTimeout.count() / 1e6];
_compileError = [[NSError alloc] initWithDomain: @"MoltenVK" code: 1 userInfo: @{NSLocalizedDescriptionKey : errDesc}]; // retained
_compileError = [[NSError alloc] initWithDomain: @(kMVKMoltenVKDriverLayerName) code: 1 userInfo: @{NSLocalizedDescriptionKey : errDesc}]; // retained
}
}

1
MoltenVK/MoltenVK/Layers/MVKExtensions.def
View File

@ -113,6 +113,7 @@ MVK_EXTENSION(EXT_headless_surface, EXT_HEADLESS_SURFACE,
MVK_EXTENSION(EXT_host_query_reset, EXT_HOST_QUERY_RESET, DEVICE, 10.11, 8.0, 1.0)
MVK_EXTENSION(EXT_image_robustness, EXT_IMAGE_ROBUSTNESS, DEVICE, 10.11, 8.0, 1.0)
MVK_EXTENSION(EXT_inline_uniform_block, EXT_INLINE_UNIFORM_BLOCK, DEVICE, 10.11, 8.0, 1.0)
MVK_EXTENSION(EXT_layer_settings, EXT_LAYER_SETTINGS, INSTANCE, 10.11, 8.0, 1.0)
MVK_EXTENSION(EXT_memory_budget, EXT_MEMORY_BUDGET, DEVICE, 10.13, 11.0, 1.0)
MVK_EXTENSION(EXT_metal_objects, EXT_METAL_OBJECTS, DEVICE, 10.11, 8.0, 1.0)
MVK_EXTENSION(EXT_metal_surface, EXT_METAL_SURFACE, INSTANCE, 10.11, 8.0, 1.0)

2
MoltenVK/MoltenVK/Layers/MVKExtensions.mm
View File

@ -50,7 +50,7 @@ static bool mvkIsSupportedOnPlatform(VkExtensionProperties* pProperties) {
// If the config indicates that not all supported extensions should be advertised,
// only advertise those supported extensions that have been specifically configured.
auto advExtns = mvkConfig().advertiseExtensions;
auto advExtns = getGlobalMVKConfig().advertiseExtensions;
if ( !mvkIsAnyFlagEnabled(advExtns, MVK_CONFIG_ADVERTISE_EXTENSIONS_ALL) ) {
#define MVK_NA kMVKOSVersionUnsupported
if (mvkIsAnyFlagEnabled(advExtns, MVK_CONFIG_ADVERTISE_EXTENSIONS_WSI)) {

16
MoltenVK/MoltenVK/Layers/MVKLayers.mm
View File

@ -40,10 +40,10 @@ MVKLayer::MVKLayer() : _supportedInstanceExtensions(nullptr, true) {
// The core driver layer
mvkClear(_layerProperties.layerName, VK_MAX_EXTENSION_NAME_SIZE);
strcpy(_layerProperties.layerName, "MoltenVK");
strcpy(_layerProperties.layerName, kMVKMoltenVKDriverLayerName);
mvkClear(_layerProperties.description, VK_MAX_DESCRIPTION_SIZE);
strcpy(_layerProperties.description, "MoltenVK driver layer");
_layerProperties.specVersion = mvkConfig().apiVersionToAdvertise;
_layerProperties.specVersion = getMVKConfig().apiVersionToAdvertise;
_layerProperties.implementationVersion = MVK_VERSION;
((MVKExtensionList*)&_supportedInstanceExtensions)->disableAllButEnabledInstanceExtensions();
@ -100,10 +100,14 @@ MVKLayerManager::MVKLayerManager() {
static mutex _lock;
static MVKLayerManager* _globalManager = VK_NULL_HANDLE;
// Test first and lock only if we need to create it.
// Test again after lock established to ensure it wasn't added by another thread between test and lock.
MVKLayerManager* MVKLayerManager::globalManager() {
lock_guard<mutex> lock(_lock);
if ( !_globalManager ) { _globalManager = new MVKLayerManager(); }
if ( !_globalManager ) {
lock_guard<mutex> lock(_lock);
if ( !_globalManager ) {
_globalManager = new MVKLayerManager();
}
}
return _globalManager;
}

19
MoltenVK/MoltenVK/Utility/MVKBaseObject.h
View File

@ -42,6 +42,13 @@ public:
/** Returns the Vulkan API opaque object controlling this object. */
virtual MVKVulkanAPIObject* getVulkanAPIObject() = 0;
/**
* If getVulkanAPIObject() does not return NULL, this function returns the MoltenVK
* configuration info for the VkInstance that created the API object, otherwise
* this function returns the global configuration info.
*/
virtual const MVKConfiguration& getMVKConfig();
/**
* Report a message. This includes logging to a standard system logging stream,
* and some subclasses will also forward the message to their VkInstance for
@ -205,3 +212,15 @@ public:
protected:
VkResult _configurationResult = VK_SUCCESS;
};
#pragma mark -
#pragma mark Support functions
/**
* If the object is not a nullptr, returns the MoltenVK configuration info for the
* VkInstance that created the object, otherwise returns the global configuration info.
*/
static inline const MVKConfiguration& mvkGetMVKConfig(MVKBaseObject* mvkObj) {
return mvkObj ? mvkObj->getMVKConfig() : getGlobalMVKConfig();
}

8
MoltenVK/MoltenVK/Utility/MVKBaseObject.mm
View File

@ -41,6 +41,12 @@ static const char* getReportingLevelString(MVKConfigLogLevel logLevel) {
string MVKBaseObject::getClassName() { return mvk::getTypeName(this); }
const MVKConfiguration& MVKBaseObject::getMVKConfig() {
MVKVulkanAPIObject* mvkAPIObj = getVulkanAPIObject();
MVKInstance* mvkInst = mvkAPIObj ? mvkAPIObj->getInstance() : nullptr;
return mvkGetMVKConfig(mvkInst);
}
void MVKBaseObject::reportMessage(MVKConfigLogLevel logLevel, const char* format, ...) {
va_list args;
va_start(args, format);
@ -61,7 +67,7 @@ void MVKBaseObject::reportMessage(MVKBaseObject* mvkObj, MVKConfigLogLevel logLe
MVKVulkanAPIObject* mvkAPIObj = mvkObj ? mvkObj->getVulkanAPIObject() : nullptr;
MVKInstance* mvkInst = mvkAPIObj ? mvkAPIObj->getInstance() : nullptr;
bool hasDebugCallbacks = mvkInst && mvkInst->hasDebugCallbacks();
bool shouldLog = logLevel <= mvkConfig().logLevel;
bool shouldLog = logLevel <= mvkGetMVKConfig(mvkInst).logLevel;
// Fail fast to avoid further unnecessary processing.
if ( !(shouldLog || hasDebugCallbacks) ) { return; }

9
MoltenVK/MoltenVK/Utility/MVKConfigMembers.def
View File

@ -20,9 +20,12 @@
// When a new member is added to the MVKConfiguration struct, a corresponding description
// must be added here.
//
// To use this file, define the macros:
// To use this file, define the macro:
//
// MVK_CONFIG_MEMBER(member, mbrType, name)
//
// and if strings are handled differently:
//
// MVK_CONFIG_MEMBER_STRING(member, mbrType, name)
//
// then #include this file inline with your code.
@ -37,7 +40,7 @@
#endif
#ifndef MVK_CONFIG_MEMBER_STRING
#error MVK_CONFIG_MEMBER_STRING must be defined before including this file
# define MVK_CONFIG_MEMBER_STRING(member, mbrType, name) MVK_CONFIG_MEMBER(member, mbrType, name)
#endif
MVK_CONFIG_MEMBER(debugMode, VkBool32, DEBUG)
@ -66,7 +69,7 @@ MVK_CONFIG_MEMBER(forceLowPowerGPU, VkBool32,
MVK_CONFIG_MEMBER(semaphoreUseMTLFence, VkBool32, ALLOW_METAL_FENCES) // Deprecated legacy
MVK_CONFIG_MEMBER(semaphoreSupportStyle, MVKVkSemaphoreSupportStyle, VK_SEMAPHORE_SUPPORT_STYLE)
MVK_CONFIG_MEMBER(autoGPUCaptureScope, MVKConfigAutoGPUCaptureScope, AUTO_GPU_CAPTURE_SCOPE)
MVK_CONFIG_MEMBER_STRING(autoGPUCaptureOutputFilepath, char*, AUTO_GPU_CAPTURE_OUTPUT_FILE)
MVK_CONFIG_MEMBER_STRING(autoGPUCaptureOutputFilepath, const char*, AUTO_GPU_CAPTURE_OUTPUT_FILE)
MVK_CONFIG_MEMBER(texture1DAs2D, VkBool32, TEXTURE_1D_AS_2D)
MVK_CONFIG_MEMBER(preallocateDescriptors, VkBool32, PREALLOCATE_DESCRIPTORS)
MVK_CONFIG_MEMBER(useCommandPooling, VkBool32, USE_COMMAND_POOLING)

108
MoltenVK/MoltenVK/Utility/MVKEnvironment.cpp
View File

@ -20,20 +20,73 @@
#include "MVKOSExtensions.h"
#include "MVKFoundation.h"
#pragma mark Support functions
// Return the expected size of MVKConfiguration, based on contents of MVKConfigMembers.def.
static constexpr uint32_t getExpectedMVKConfigurationSize() {
#define MVK_CONFIG_MEMBER_STRING(member, mbrType, name) MVK_CONFIG_MEMBER(member, mbrType, name)
#define MVK_CONFIG_MEMBER(member, mbrType, name) cfgSize += sizeof(mbrType);
uint32_t cfgSize = 0;
#include "MVKConfigMembers.def"
return cfgSize;
}
static bool _mvkConfigInitialized = false;
static void mvkInitConfigFromEnvVars() {
// Return the expected number of string members in MVKConfiguration, based on contents of MVKConfigMembers.def.
static constexpr uint32_t getExpectedMVKConfigurationStringCount() {
#define MVK_CONFIG_MEMBER(member, mbrType, name)
#define MVK_CONFIG_MEMBER_STRING(member, mbrType, name) strCnt++;
uint32_t strCnt = 0;
#include "MVKConfigMembers.def"
return strCnt;
}
#pragma mark Set configuration values
// Sets destination config content from the source content, validates content,
// and ensures the content of any string members of MVKConfiguration are copied locally.
void mvkSetConfig(MVKConfiguration& dstMVKConfig, const MVKConfiguration& srcMVKConfig, std::string* stringHolders) {
dstMVKConfig = srcMVKConfig;
// Ensure the API version is supported, and add the VK_HEADER_VERSION.
dstMVKConfig.apiVersionToAdvertise = std::min(dstMVKConfig.apiVersionToAdvertise, MVK_VULKAN_API_VERSION);
dstMVKConfig.apiVersionToAdvertise = VK_MAKE_VERSION(VK_VERSION_MAJOR(dstMVKConfig.apiVersionToAdvertise),
VK_VERSION_MINOR(dstMVKConfig.apiVersionToAdvertise),
VK_HEADER_VERSION);
// Deprecated legacy support for specific case where both legacy semaphoreUseMTLEvent
// (now aliased to semaphoreSupportStyle) and legacy semaphoreUseMTLFence are explicitly
// disabled by the app. In this case the app had been using CPU emulation, so use
// MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_CALLBACK.
if ( !dstMVKConfig.semaphoreUseMTLEvent && !dstMVKConfig.semaphoreUseMTLFence ) {
dstMVKConfig.semaphoreSupportStyle = MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_CALLBACK;
}
// Clamp timestampPeriodLowPassAlpha between 0.0 and 1.0.
dstMVKConfig.timestampPeriodLowPassAlpha = mvkClamp(dstMVKConfig.timestampPeriodLowPassAlpha, 0.0f, 1.0f);
// For each string member of the destination MVKConfiguration, store the contents
// in a std::string, then repoint the member to the contents of the std::string.
#define MVK_CONFIG_MEMBER(member, mbrType, name)
#define MVK_CONFIG_MEMBER_STRING(member, mbrType, name) \
if (dstMVKConfig.member) { stringHolders[strIdx] = dstMVKConfig.member; } \
dstMVKConfig.member = stringHolders[strIdx++].c_str();
static_assert(getExpectedMVKConfigurationStringCount() == kMVKConfigurationStringCount, "Each string member in MVKConfiguration needs a separate std::string to hold its content.");
uint32_t strIdx = 0;
#include "MVKConfigMembers.def"
assert(strIdx == kMVKConfigurationStringCount); // Ensure all string members of MVKConfiguration were stored in separate std::strings.
}
#pragma mark Load global configuration from environment variables
static bool _mvkGlobalConfigInitialized = false;
static void mvkInitGlobalConfigFromEnvVars() {
static_assert(getExpectedMVKConfigurationSize() == sizeof(MVKConfiguration), "MVKConfigMembers.def does not match the members of MVKConfiguration.");
_mvkConfigInitialized = true;
_mvkGlobalConfigInitialized = true;
MVKConfiguration evCfg;
std::string evGPUCapFileStrObj;
@ -59,7 +112,7 @@ static void mvkInitConfigFromEnvVars() {
// Legacy MVK_ALLOW_METAL_EVENTS is covered by MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE,
// but for backwards compatibility, if legacy MVK_ALLOW_METAL_EVENTS is explicitly
// disabled, disable semaphoreUseMTLEvent (aliased as semaphoreSupportStyle value
// MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_SINGLE_QUEUE), and let mvkSetConfig()
// MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_SINGLE_QUEUE), and let mvkSetGlobalConfig()
// further process legacy behavior of MVK_ALLOW_METAL_FENCES.
if ( !mvkGetEnvVarNumber("MVK_CONFIG_ALLOW_METAL_EVENTS", 1.0) ) {
evCfg.semaphoreUseMTLEvent = (MVKVkSemaphoreSupportStyle)false; // Disabled. Also semaphoreSupportStyle MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_SINGLE_QUEUE.
@ -74,48 +127,23 @@ static void mvkInitConfigFromEnvVars() {
evCfg.activityPerformanceLoggingStyle = MVK_CONFIG_ACTIVITY_PERFORMANCE_LOGGING_STYLE_IMMEDIATE;
}
mvkSetConfig(evCfg);
mvkSetGlobalConfig(evCfg);
}
static MVKConfiguration _mvkConfig;
static std::string _autoGPUCaptureOutputFile;
static MVKConfiguration _globalMVKConfig;
static std::string _globalMVKConfigStringHolders[kMVKConfigurationStringCount] = {};
// Returns the MoltenVK config, lazily initializing it if necessary.
// We initialize lazily instead of in a library constructor function to
// ensure the NSProcessInfo environment is available when called upon.
const MVKConfiguration& mvkConfig() {
if ( !_mvkConfigInitialized ) {
mvkInitConfigFromEnvVars();
const MVKConfiguration& getGlobalMVKConfig() {
if ( !_mvkGlobalConfigInitialized ) {
mvkInitGlobalConfigFromEnvVars();
}
return _mvkConfig;
return _globalMVKConfig;
}
// Sets config content, and updates any content that needs baking, including copying the contents
// of strings from the incoming MVKConfiguration member to a corresponding std::string, and then
// repointing the MVKConfiguration member to the contents of the std::string.
void mvkSetConfig(const MVKConfiguration& mvkConfig) {
_mvkConfig = mvkConfig;
// Ensure the API version is supported, and add the VK_HEADER_VERSION.
_mvkConfig.apiVersionToAdvertise = std::min(_mvkConfig.apiVersionToAdvertise, MVK_VULKAN_API_VERSION);
_mvkConfig.apiVersionToAdvertise = VK_MAKE_VERSION(VK_VERSION_MAJOR(_mvkConfig.apiVersionToAdvertise),
VK_VERSION_MINOR(_mvkConfig.apiVersionToAdvertise),
VK_HEADER_VERSION);
// Deprecated legacy support for specific case where both legacy semaphoreUseMTLEvent
// (now aliased to semaphoreSupportStyle) and legacy semaphoreUseMTLFence are explicitly
// disabled by the app. In this case the app had been using CPU emulation, so use
// MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_CALLBACK.
if ( !_mvkConfig.semaphoreUseMTLEvent && !_mvkConfig.semaphoreUseMTLFence ) {
_mvkConfig.semaphoreSupportStyle = MVK_CONFIG_VK_SEMAPHORE_SUPPORT_STYLE_CALLBACK;
}
// Set capture file path string
if (_mvkConfig.autoGPUCaptureOutputFilepath) {
_autoGPUCaptureOutputFile = _mvkConfig.autoGPUCaptureOutputFilepath;
}
_mvkConfig.autoGPUCaptureOutputFilepath = (char*)_autoGPUCaptureOutputFile.c_str();
// Clamp timestampPeriodLowPassAlpha between 0.0 and 1.0.
_mvkConfig.timestampPeriodLowPassAlpha = mvkClamp(_mvkConfig.timestampPeriodLowPassAlpha, 0.0f, 1.0f);
void mvkSetGlobalConfig(const MVKConfiguration& srcMVKConfig) {
mvkSetConfig(_globalMVKConfig, srcMVKConfig, _globalMVKConfigStringHolders);
}

22
MoltenVK/MoltenVK/Utility/MVKEnvironment.h
View File

@ -21,8 +21,9 @@
#include "MVKCommonEnvironment.h"
#include "mvk_vulkan.h"
#include "mvk_config.h"
#include "mvk_private_api.h"
#include "MVKLogging.h"
#include <string>
// Expose MoltenVK Apple surface extension functionality
@ -69,20 +70,29 @@
#endif
#if MVK_TVOS
# define MVK_SUPPORT_IOSURFACE_BOOL (__TV_OS_VERSION_MIN_REQUIRED >= __TVOS_11_0)
# define MVK_SUPPORT_IOSURFACE_BOOL (__TV_OS_VERSION_MIN_REQUIRED >= __TVOS_11_0)
#endif
#pragma mark -
#pragma mark Global Configuration
#pragma mark MoltenVK Configuration
/** The number of members of MVKConfiguration that are strings. */
static constexpr uint32_t kMVKConfigurationStringCount = 1;
/** Global function to access MoltenVK configuration info. */
const MVKConfiguration& mvkConfig();
const MVKConfiguration& getGlobalMVKConfig();
/** Global function to update MoltenVK configuration info. */
void mvkSetConfig(const MVKConfiguration& mvkConfig);
/** Sets the MoltenVK global configuration content. */
void mvkSetGlobalConfig(const MVKConfiguration& srcMVKConfig);
/**
* Sets the content from the source config into the destination
* config, while using the string object to retain string content.
*/
void mvkSetConfig(MVKConfiguration& dstMVKConfig, const MVKConfiguration& srcMVKConfig, std::string* stringHolders);
/**
* Enable debug mode.
* By default, disabled for Release builds and enabled for Debug builds.
*/

3
MoltenVK/MoltenVK/Utility/MVKFoundation.h
View File

@ -379,9 +379,6 @@ static constexpr bool mvkVkComponentMappingsMatch(VkComponentMapping cm1, VkComp
mvkVKComponentSwizzlesMatch(cm1.a, cm2.a, VK_COMPONENT_SWIZZLE_A));
}
/** Print the size of the type. */
#define mvkPrintSizeOf(type) printf("Size of " #type " is %lu.\n", sizeof(type))
#pragma mark Math

2
MoltenVK/MoltenVK/Utility/MVKLogging.h
View File

@ -128,7 +128,7 @@ extern "C" {
# define MVK_LOG_LEVEL_INFO MVK_LOGGING_ENABLED
#endif
#ifndef MVK_LOG_LEVEL_DEBUG
# define MVK_LOG_LEVEL_DEBUG (MVK_LOGGING_ENABLED && MVK_DEBUG)
# define MVK_LOG_LEVEL_DEBUG (MVK_LOGGING_ENABLED && MVK_CONFIG_DEBUG)
#endif
#ifndef MVK_LOG_LEVEL_TRACE
# define MVK_LOG_LEVEL_TRACE 0

16
MoltenVK/MoltenVK/Vulkan/mvk_api.mm
View File

@ -18,7 +18,6 @@
#include "MVKEnvironment.h"
#include "mvk_private_api.h"
#include "mvk_deprecated_api.h"
#include "MVKInstance.h"
#include "MVKSwapchain.h"
@ -53,14 +52,14 @@ VkResult mvkCopyGrowingStruct(S* pDst, const S* pSrc, size_t* pCopySize) {
#pragma mark -
#pragma mark mvk_config.h
#pragma mark mvk_private_api.h
MVK_PUBLIC_VULKAN_SYMBOL VkResult vkGetMoltenVKConfigurationMVK(
VkInstance ignored,
MVKConfiguration* pConfiguration,
size_t* pConfigurationSize) {
return mvkCopyGrowingStruct(pConfiguration, &mvkConfig(), pConfigurationSize);
return mvkCopyGrowingStruct(pConfiguration, &getGlobalMVKConfig(), pConfigurationSize);
}
MVK_PUBLIC_VULKAN_SYMBOL VkResult vkSetMoltenVKConfigurationMVK(
@ -69,16 +68,13 @@ MVK_PUBLIC_VULKAN_SYMBOL VkResult vkSetMoltenVKConfigurationMVK(
size_t* pConfigurationSize) {
// Start with copy of current config, in case incoming is not fully copied
MVKConfiguration mvkCfg = mvkConfig();
MVKBaseObject::reportMessage(nullptr, MVK_CONFIG_LOG_LEVEL_WARNING, "vkSetMoltenVKConfigurationMVK() is deprecated. To set MoltenVK configuration parameters, the VK_EXT_layer_settings extension, or environment variables.");
MVKConfiguration mvkCfg = getGlobalMVKConfig();
VkResult rslt = mvkCopyGrowingStruct(&mvkCfg, pConfiguration, pConfigurationSize);
mvkSetConfig(mvkCfg);
mvkSetGlobalConfig(mvkCfg);
return rslt;
}
#pragma mark -
#pragma mark mvk_private_api.h
MVK_PUBLIC_VULKAN_SYMBOL VkResult vkGetPhysicalDeviceMetalFeaturesMVK(
VkPhysicalDevice physicalDevice,
MVKPhysicalDeviceMetalFeatures* pMetalFeatures,
@ -114,7 +110,7 @@ MVK_PUBLIC_VULKAN_SYMBOL void vkGetVersionStringsMVK(
len = mvkVer.copy(pMoltenVersionStringBuffer, moltenVersionStringBufferLength - 1);
pMoltenVersionStringBuffer[len] = 0; // terminator
string vkVer = mvkGetVulkanVersionString(mvkConfig().apiVersionToAdvertise);
string vkVer = mvkGetVulkanVersionString(getGlobalMVKConfig().apiVersionToAdvertise);
len = vkVer.copy(pVulkanVersionStringBuffer, vulkanVersionStringBufferLength - 1);
pVulkanVersionStringBuffer[len] = 0; // terminator
}

6
MoltenVK/MoltenVK/Vulkan/mvk_datatypes.hpp
View File

@ -47,6 +47,12 @@ class MVKPixelFormats;
* of an MVKBaseObject subclass, which is true for all but static calling functions.
*/
MTLTextureType mvkMTLTextureTypeFromVkImageTypeObj(VkImageType vkImageType, uint32_t arraySize, bool isMultisample, MVKBaseObject* mvkObj);
#define mvkMTLTextureTypeFromVkImageType(vkImageType, arraySize, isMultisample) mvkMTLTextureTypeFromVkImageTypeObj(vkImageType, arraySize, isMultisample, this)
MTLTextureType mvkMTLTextureTypeFromVkImageViewTypeObj(VkImageViewType vkImageViewType, bool isMultisample, MVKBaseObject* mvkObj);
#define mvkMTLTextureTypeFromVkImageViewType(vkImageViewType, isMultisample) mvkMTLTextureTypeFromVkImageViewTypeObj(vkImageViewType, isMultisample, this)
MTLPrimitiveType mvkMTLPrimitiveTypeFromVkPrimitiveTopologyInObj(VkPrimitiveTopology vkTopology, MVKBaseObject* mvkObj);
#define mvkMTLPrimitiveTypeFromVkPrimitiveTopology(vkTopology) mvkMTLPrimitiveTypeFromVkPrimitiveTopologyInObj(vkTopology, this)

23
MoltenVK/MoltenVK/Vulkan/mvk_datatypes.mm
View File

@ -144,12 +144,21 @@ MVK_PUBLIC_SYMBOL bool mvkMTLPixelFormatIsPVRTCFormat(MTLPixelFormat mtlFormat)
return getPlatformPixelFormats()->isPVRTCFormat(mtlFormat);
}
#undef mvkMTLTextureTypeFromVkImageType
MVK_PUBLIC_SYMBOL MTLTextureType mvkMTLTextureTypeFromVkImageType(VkImageType vkImageType,
uint32_t arraySize,
bool isMultisample) {
return mvkMTLTextureTypeFromVkImageTypeObj(vkImageType, arraySize, isMultisample, nullptr);
}
MTLTextureType mvkMTLTextureTypeFromVkImageTypeObj(VkImageType vkImageType,
uint32_t arraySize,
bool isMultisample,
MVKBaseObject* mvkObj) {
switch (vkImageType) {
case VK_IMAGE_TYPE_3D: return MTLTextureType3D;
case VK_IMAGE_TYPE_1D: return (mvkConfig().texture1DAs2D
case VK_IMAGE_TYPE_1D: return (mvkGetMVKConfig(mvkObj).texture1DAs2D
? mvkMTLTextureTypeFromVkImageType(VK_IMAGE_TYPE_2D, arraySize, isMultisample)
: (arraySize > 1 ? MTLTextureType1DArray : MTLTextureType1D));
case VK_IMAGE_TYPE_2D:
@ -175,14 +184,22 @@ MVK_PUBLIC_SYMBOL VkImageType mvkVkImageTypeFromMTLTextureType(MTLTextureType mt
return VK_IMAGE_TYPE_2D;
}
}
#undef mvkMTLTextureTypeFromVkImageViewType
MVK_PUBLIC_SYMBOL MTLTextureType mvkMTLTextureTypeFromVkImageViewType(VkImageViewType vkImageViewType,
bool isMultisample) {
return mvkMTLTextureTypeFromVkImageViewTypeObj(vkImageViewType, isMultisample, nullptr);
}
MTLTextureType mvkMTLTextureTypeFromVkImageViewTypeObj(VkImageViewType vkImageViewType,
bool isMultisample,
MVKBaseObject* mvkObj) {
switch (vkImageViewType) {
case VK_IMAGE_VIEW_TYPE_3D: return MTLTextureType3D;
case VK_IMAGE_VIEW_TYPE_CUBE: return MTLTextureTypeCube;
case VK_IMAGE_VIEW_TYPE_CUBE_ARRAY: return MTLTextureTypeCubeArray;
case VK_IMAGE_VIEW_TYPE_1D: return mvkConfig().texture1DAs2D ? mvkMTLTextureTypeFromVkImageViewType(VK_IMAGE_VIEW_TYPE_2D, isMultisample) : MTLTextureType1D;
case VK_IMAGE_VIEW_TYPE_1D_ARRAY: return mvkConfig().texture1DAs2D ? mvkMTLTextureTypeFromVkImageViewType(VK_IMAGE_VIEW_TYPE_2D_ARRAY, isMultisample) : MTLTextureType1DArray;
case VK_IMAGE_VIEW_TYPE_1D: return mvkGetMVKConfig(mvkObj).texture1DAs2D ? mvkMTLTextureTypeFromVkImageViewType(VK_IMAGE_VIEW_TYPE_2D, isMultisample) : MTLTextureType1D;
case VK_IMAGE_VIEW_TYPE_1D_ARRAY: return mvkGetMVKConfig(mvkObj).texture1DAs2D ? mvkMTLTextureTypeFromVkImageViewType(VK_IMAGE_VIEW_TYPE_2D_ARRAY, isMultisample) : MTLTextureType1DArray;
case VK_IMAGE_VIEW_TYPE_2D_ARRAY:
#if MVK_MACOS

6
MoltenVK/MoltenVK/Vulkan/vulkan.mm
View File

@ -55,7 +55,7 @@ static inline uint64_t MVKTraceVulkanCallStartImpl(const char* funcName) {
bool includeExit = false;
bool includeDuration = false;
switch (mvkConfig().traceVulkanCalls) {
switch (getGlobalMVKConfig().traceVulkanCalls) {
case MVK_CONFIG_TRACE_VULKAN_CALLS_DURATION:
includeDuration = true; // fallthrough
case MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT:
@ -94,7 +94,7 @@ static inline uint64_t MVKTraceVulkanCallStartImpl(const char* funcName) {
// Optionally log end of function calls and timings to stderr
static inline void MVKTraceVulkanCallEndImpl(const char* funcName, uint64_t startTime) {
switch(mvkConfig().traceVulkanCalls) {
switch(getGlobalMVKConfig().traceVulkanCalls) {
case MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT:
case MVK_CONFIG_TRACE_VULKAN_CALLS_ENTER_EXIT_THREAD_ID:
fprintf(stderr, "[mvk-trace] } %s\n", funcName);
@ -2021,7 +2021,7 @@ MVK_PUBLIC_VULKAN_SYMBOL VkResult vkEnumerateInstanceVersion(
uint32_t* pApiVersion) {
MVKTraceVulkanCallStart();
*pApiVersion = mvkConfig().apiVersionToAdvertise;
*pApiVersion = getGlobalMVKConfig().apiVersionToAdvertise;
MVKTraceVulkanCallEnd();
return VK_SUCCESS;
}

25
MoltenVKPackaging.xcodeproj/project.pbxproj
View File

@ -126,6 +126,13 @@
remoteGlobalIDString = A9CBED861B6299D800E45FDC;
remoteInfo = "MoltenVK-macOS";
};
A97D77552B24FBDF00E36932 /* PBXContainerItemProxy */ = {
isa = PBXContainerItemProxy;
containerPortal = A92DB40E1CE0F89600FBC835 /* MoltenVKShaderConverter.xcodeproj */;
proxyType = 2;
remoteGlobalIDString = DCFD7F882A45BDA0007BBBF7;
remoteInfo = "MoltenVKShaderConverter-xrOS";
};
A981498A1FB6B566005F00B4 /* PBXContainerItemProxy */ = {
isa = PBXContainerItemProxy;
containerPortal = A92DB40E1CE0F89600FBC835 /* MoltenVKShaderConverter.xcodeproj */;
@ -213,6 +220,7 @@
A93ED4DE24F59CDB00FEB018 /* copy_lib_to_staging.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; path = copy_lib_to_staging.sh; sourceTree = "<group>"; };
A93ED4E324F59CDB00FEB018 /* copy_to_staging.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; path = copy_to_staging.sh; sourceTree = "<group>"; };
A975D55C213F25D700D4834F /* create_dylib.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; path = create_dylib.sh; sourceTree = "<group>"; };
A97D77502B24FBDF00E36932 /* MoltenVK_Configuration_Parameters.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = MoltenVK_Configuration_Parameters.md; path = Docs/MoltenVK_Configuration_Parameters.md; sourceTree = "<group>"; };
A980A25F24C628F3007A8F6F /* gen_moltenvk_rev_hdr.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; path = gen_moltenvk_rev_hdr.sh; sourceTree = "<group>"; };
A98149E51FB78829005F00B4 /* MoltenVK_Runtime_UserGuide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = MoltenVK_Runtime_UserGuide.md; path = Docs/MoltenVK_Runtime_UserGuide.md; sourceTree = "<group>"; };
A9A15AA625D6D884004EEBE9 /* CI.yml */ = {isa = PBXFileReference; lastKnownFileType = text.yaml; name = CI.yml; path = .github/workflows/CI.yml; sourceTree = "<group>"; };
@ -241,10 +249,11 @@
A92DB3E11CE0F34500FBC835 /* Docs */ = {
isa = PBXGroup;
children = (
A92DB3E51CE0F37D00FBC835 /* LICENSE */,
A98149E51FB78829005F00B4 /* MoltenVK_Runtime_UserGuide.md */,
A92DB3E41CE0F37D00FBC835 /* README.md */,
A92DB3E61CE0F37D00FBC835 /* Whats_New.md */,
A92DB3E41CE0F37D00FBC835 /* README.md */,
A98149E51FB78829005F00B4 /* MoltenVK_Runtime_UserGuide.md */,
A97D77502B24FBDF00E36932 /* MoltenVK_Configuration_Parameters.md */,
A92DB3E51CE0F37D00FBC835 /* LICENSE */,
);
name = Docs;
sourceTree = "<group>";
@ -291,6 +300,7 @@
A98149911FB6B566005F00B4 /* libMoltenVKShaderConverter.a */,
A9FC5F5D249D2547003CB086 /* libMoltenVKShaderConverter.a */,
A98149931FB6B566005F00B4 /* libMoltenVKShaderConverter.a */,
A97D77562B24FBDF00E36932 /* libMoltenVKShaderConverter.a */,
);
name = Products;
sourceTree = "<group>";
@ -371,6 +381,13 @@
remoteRef = A92DB3F61CE0F72500FBC835 /* PBXContainerItemProxy */;
sourceTree = BUILT_PRODUCTS_DIR;
};
A97D77562B24FBDF00E36932 /* libMoltenVKShaderConverter.a */ = {
isa = PBXReferenceProxy;
fileType = archive.ar;
path = libMoltenVKShaderConverter.a;
remoteRef = A97D77552B24FBDF00E36932 /* PBXContainerItemProxy */;
sourceTree = BUILT_PRODUCTS_DIR;
};
A981498B1FB6B566005F00B4 /* MoltenVKShaderConverter */ = {
isa = PBXReferenceProxy;
fileType = "compiled.mach-o.executable";
@ -402,7 +419,7 @@
DCFD7F662A45BC7D007BBBF7 /* libMoltenVK.a */ = {
isa = PBXReferenceProxy;
fileType = archive.ar;
path = "libMoltenVK.a";
path = libMoltenVK.a;
remoteRef = DCFD7F652A45BC7D007BBBF7 /* PBXContainerItemProxy */;
sourceTree = BUILT_PRODUCTS_DIR;
};

287
README.md
View File

@ -36,33 +36,33 @@ Table of Contents
Introduction to MoltenVK
------------------------
**MoltenVK** is a layered implementation of [*Vulkan 1.2*](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* on *macOS 11.0+*,
**MoltenVK** is a layered implementation of [*Vulkan 1.2*](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* 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
*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
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
- **MoltenVK** is a implementation of an almost-complete subset of the
[*Vulkan 1.2*](https://www.khronos.org/vulkan) 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
*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.
@ -74,32 +74,32 @@ Developing *Vulkan* Applications for *macOS, iOS, tvOS, and visionOS*
<a name="sdk"></a>
### Using the *Vulkan SDK*
The recommended method for developing a *Vulkan* application for *macOS* is to use the
The recommended method for developing a *Vulkan* application for *macOS* is to use the
[*Vulkan SDK*](https://vulkan.lunarg.com/sdk/home).
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
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*.
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)*
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
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.
<a name="download"></a>
### 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*,
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.
@ -108,8 +108,8 @@ Finally, if you want a customized build of **MoltenVK**, you can follow the [ins
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.
see the [`MoltenVK_Runtime_UserGuide.md `](Docs/MoltenVK_Runtime_UserGuide.md)
document in the `Docs` directory.
@ -117,8 +117,8 @@ 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
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:
@ -139,26 +139,26 @@ on which **MoltenVK** relies:
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:
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
--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.
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.
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
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**,
@ -169,83 +169,83 @@ see the [`ExternalRevisions/README.md`](ExternalRevisions/README.md) document.
Building **MoltenVK**
-------------------
During building, **MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks,
During building, **MoltenVK** references the latest *Apple SDK* frameworks. To access these frameworks,
and to avoid build errors, be sure to use the latest publicly available version of *Xcode*.
> ***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.
> ***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 **MoltenVK** with *Xcode 13* or earlier.
> If you need to use *Xcode 13* or earlier to link `MoltenVK.xcframework` to your app or game,
first build **MoltenVK** with *Xcode 13* or earlier.
>
> Or, if you want to use *Xcode 14* or later to build **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 **MoltenVK** with *Xcode 14* or later, and then link `MoltenVK.xcframework`
> Or, if you want to use *Xcode 14* or later to build **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 **MoltenVK** with *Xcode 14* or later, and then link `MoltenVK.xcframework`
to your app or game using *Xcode 13* or earlier.
**MoltenVK** can be built to support at least *macOS 10.11*, *iOS 9*, or *tvOS 9*, but the default
_Xcode_ build settings in the included _Xcode_ projects are set to a minimum deployment target of
*macOS 10.13*, *iOS 11*, and *tvOS 11*, which are the oldest OS versions supported by the current
_Xcode_ version. If you require support for earlier OS versions, modify the `MACOSX_DEPLOYMENT_TARGET`,
**MoltenVK** can be built to support at least *macOS 10.11*, *iOS 9*, or *tvOS 9*, but the default
_Xcode_ build settings in the included _Xcode_ projects are set to a minimum deployment target of
*macOS 10.13*, *iOS 11*, and *tvOS 11*, which are the oldest OS versions supported by the current
_Xcode_ version. If you require support for earlier OS versions, modify the `MACOSX_DEPLOYMENT_TARGET`,
`IPHONEOS_DEPLOYMENT_TARGET`, or `TVOS_DEPLOYMENT_TARGET` build settings in _Xcode_ before building **MoltenVK**.
>***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, **MoltenVK**, and any app that uses
**MoltenVK**, must be built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `)
build setting of `iOS 11.0` or greater, or a minimum **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET `)
>***Note:*** To support `IOSurfaces` on *iOS* or *tvOS*, **MoltenVK**, and any app that uses
**MoltenVK**, must be built with a minimum **iOS Deployment Target** (aka `IPHONEOS_DEPLOYMENT_TARGET `)
build setting of `iOS 11.0` or greater, or a minimum **tvOS Deployment Target** (aka `TVOS_DEPLOYMENT_TARGET `)
build setting of `tvOS 11.0` or greater.
Once built, the **MoltenVK** libraries can be run on *macOS*, *iOS*, *tvOS*, or *visionOS* devices
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*.
- At runtime, **MoltenVK** requires at least *macOS 10.11*, *iOS 9.0*, *tvOS 9.0*,
- At runtime, **MoltenVK** requires at least *macOS 10.11*, *iOS 9.0*, *tvOS 9.0*,
or *visionOS 1.0* (or *iOS 11* or *tvOS 11* if using `IOSurfaces`).
- Information on *macOS* devices that are compatible with *Metal* can be found in
- Information on *macOS* devices that are compatible with *Metal* can be found in
[this article](http://www.idownloadblog.com/2015/06/22/how-to-find-mac-el-capitan-metal-compatible).
- Information on *iOS* devices that are compatible with *Metal* can be found in
- Information on *iOS* devices that are compatible with *Metal* can be found in
[this article](https://developer.apple.com/library/content/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/HardwareGPUInformation/HardwareGPUInformation.html).
The `MoltenVKPackaging.xcodeproj` *Xcode* project contains targets and schemes to build
and package the entire **MoltenVK** runtime distribution package, or to build individual
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,
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
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**
- **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`
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.
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`
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
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
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**
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
@ -272,19 +272,19 @@ from the command line. The following `make` targets are provided:
- 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 `MoltenVK.xcframework` into the
`/Library/Frameworks` folder of your computer. Since `/Library/Frameworks` is protected,
- The `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.
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 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 `mvk_config.h` file for `MVKConfiguration`, by passing them in the command line,
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
@ -301,7 +301,7 @@ You can optionally build MoltenVK with the Vulkan API static call symbols (`vk*`
to avoid library linking conflicts when 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,
This build setting can be set in the `MoltenVK.xcodeproj` *Xcode* project,
or it can be included in any of the `make` build commands. For example:
make MVK_HIDE_VULKAN_SYMBOLS=1
@ -316,14 +316,14 @@ or
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*
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
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**.
@ -332,53 +332,52 @@ included *Cube* demo app, and for external links to more sophisticated demo appl
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
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 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.
<a name="compliance"></a>
**MoltenVK** and *Vulkan* Compliance
------------------------------------
**MoltenVK** is designed to be an implementation of a *Vulkan 1.2* subset that runs on *macOS*, *iOS*,
**MoltenVK** is designed to be an implementation of a *Vulkan 1.2* 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
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.2* 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*
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.
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)
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
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.
**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.
@ -387,19 +386,19 @@ their *Vulkan* apps for maximum cross-platform compatibility and portability, in
Getting Support
----------------
- If you have a question about using **MoltenVK**, you can ask it in
[*MoltenVK Discussions*](https://github.com/KhronosGroup/MoltenVK/discussions).
- 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,
- 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
- 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
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.
@ -409,52 +408,52 @@ Getting Support
Contributing to **MoltenVK** Development
----------------------------------------
As a public open-source project, **MoltenVK** benefits from code contributions from a wide range of developers,
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**
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.
**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.
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/1.2/html/vkspec.html#fundamentals-errors), **MoltenVK** should not perform *Vulkan* validation. When adding functionality
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/1.2/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
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
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
*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
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.

10
Scripts/runcts
View File

@ -84,13 +84,12 @@ fi
# -------------- MoltenVK configuration --------------------
# As documented above, the portability option restricts to Vulkan 1.0 and a very limited set of extensions.
# The values used here are documented in mvk_config.h.
# - MVK_CONFIG_API_VERSION_TO_ADVERTISE = VK_API_VERSION_1_0 (4194304)
# - MVK_CONFIG_ADVERTISE_EXTENSIONS selects support for a very limited set of extensions,
# using a bit-or of values in MVKConfigAdvertiseExtensions (extension list documented above).
# The values used here are documented in MoltenVK_Configuration_Parameters.md.
# - MVK_CONFIG_API_VERSION_TO_ADVERTISE = 4194304 (VK_API_VERSION_1_0).
# - MVK_CONFIG_ADVERTISE_EXTENSIONS = 4 (VK_KHR_portability_subset and prerequistes).
if [ "${is_portability}" != "" ]; then
export MVK_CONFIG_API_VERSION_TO_ADVERTISE=4194304
export MVK_CONFIG_ADVERTISE_EXTENSIONS=0xA
export MVK_CONFIG_ADVERTISE_EXTENSIONS=4
fi
# ----- System settings ------
@ -106,6 +105,7 @@ export MVK_CONFIG_LOG_LEVEL=1 #(1 = Errors only, 3 = Info)
export MVK_CONFIG_DEBUG=0
# Additional MoltenVK configuration can be set here by editing below.
# The values used here are documented in MoltenVK_Configuration_Parameters.md.
export MVK_CONFIG_RESUME_LOST_DEVICE=1
export MVK_CONFIG_FAST_MATH_ENABLED=1
export MVK_CONFIG_FORCE_LOW_POWER_GPU=0