Update documentation for the VK_EXT_layer_settings extension.
- Add MoltenVK_Configuration_Parameters.md to document the MoltenVK configuration parameters. - Deprecate vkSetMoltenVKConfigurationMVK(). - Deprecate mvk_config.h and move content to mvk_private_api.h and mvk_deprecated_api.h. - Streamline lock on retrieval of MVKLayerManager singleton (unrelated).
This commit is contained in:
Bill Hollings
parent
ac46188bba
commit
0fc9657bbd
656
Docs/MoltenVK_Configuration_Parameters.md
Normal file
656
Docs/MoltenVK_Configuration_Parameters.md
Normal file
@ -0,0 +1,656 @@
|
||||
<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.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
#### 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.
|
||||
|
||||
@ -483,18 +483,15 @@ can be included in your application source code as follows:
|
||||
|
||||
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_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
|
||||
@ -505,30 +502,36 @@ where `HEADER_FILE` is one of the following:
|
||||
<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. 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).
|
||||
|
||||
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.
|
||||
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>
|
||||
@ -552,19 +555,9 @@ you can address the issue as follows:
|
||||
|
||||
- Errors encountered during **Runtime Shader Conversion** are logged to the console.
|
||||
|
||||
<<<<<<< HEAD
|
||||
- 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 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.
|
||||
>>>>>>> e6a3886313a270e93a327cdb822f856fb75393b2
|
||||
- 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
|
||||
|
||||
@ -28,6 +28,8 @@ Released TBD
|
||||
- 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.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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.
|
||||
* - Application runtime environment variables.
|
||||
* - Build settings at MoltenVK build time.
|
||||
*/
|
||||
VKAPI_ATTR [[deprecated("Use the VK_EXT_layer_settings extension 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.
|
||||
|
||||
@ -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.
|
||||
* - 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
|
||||
|
||||
@ -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_
|
||||
|
||||
@ -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.
|
||||
* - 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>
|
||||
|
||||
@ -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>
|
||||
@ -1063,7 +1062,7 @@ 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. The intance may be a nullptr.
|
||||
* array will only include low-power devices. The instance may be a nullptr.
|
||||
*/
|
||||
NSArray<id<MTLDevice>>* mvkGetAvailableMTLDevicesArray(MVKInstance* instance);
|
||||
|
||||
|
||||
@ -372,7 +372,8 @@ void MVKInstance::initMVKConfig(const VkInstanceCreateInfo* pCreateInfo) {
|
||||
|
||||
#define STR(name) #name
|
||||
#define MVK_CONFIG_MEMBER(member, mbrType, name) \
|
||||
if(mvkStringsAreEqual(pSetting->pSettingName, STR(MVK_CONFIG_##name))) { \
|
||||
if(mvkStringsAreEqual(pSetting->pLayerName, getDriverLayer()->getName()) && \
|
||||
mvkStringsAreEqual(pSetting->pSettingName, STR(MVK_CONFIG_##name))) { \
|
||||
_mvkConfig.member = *(mbrType*)(pSetting->pValues); \
|
||||
continue; \
|
||||
}
|
||||
@ -494,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);
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
|
||||
|
||||
@ -22,7 +22,6 @@
|
||||
#include "MVKFoundation.h"
|
||||
#include "MVKOSExtensions.h"
|
||||
#include "MVKStrings.h"
|
||||
#include <MoltenVK/mvk_config.h>
|
||||
|
||||
using namespace std;
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@
|
||||
|
||||
#include "MVKCommonEnvironment.h"
|
||||
#include "mvk_vulkan.h"
|
||||
#include "mvk_config.h"
|
||||
#include "mvk_private_api.h"
|
||||
#include "MVKLogging.h"
|
||||
#include <string>
|
||||
|
||||
|
||||
@ -18,7 +18,6 @@
|
||||
|
||||
|
||||
#include "MVKEnvironment.h"
|
||||
#include "mvk_private_api.h"
|
||||
#include "mvk_deprecated_api.h"
|
||||
#include "MVKInstance.h"
|
||||
#include "MVKSwapchain.h"
|
||||
@ -53,7 +52,7 @@ 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,
|
||||
@ -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
|
||||
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 = mvkConfig();
|
||||
VkResult rslt = mvkCopyGrowingStruct(&mvkCfg, pConfiguration, pConfigurationSize);
|
||||
mvkSetConfig(mvkCfg);
|
||||
return rslt;
|
||||
}
|
||||
|
||||
|
||||
#pragma mark -
|
||||
#pragma mark mvk_private_api.h
|
||||
|
||||
MVK_PUBLIC_VULKAN_SYMBOL VkResult vkGetPhysicalDeviceMetalFeaturesMVK(
|
||||
VkPhysicalDevice physicalDevice,
|
||||
MVKPhysicalDeviceMetalFeatures* pMetalFeatures,
|
||||
|
||||
@ -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;
|
||||
};
|
||||
|
||||
@ -284,7 +284,7 @@ Building from the command line creates the same `Package` folder structure descr
|
||||
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,
|
||||
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
|
||||
@ -343,7 +343,6 @@ the contents of that directory out of this **MoltenVK** repository into your own
|
||||
|
||||
|
||||
<a name="compliance"></a>
|
||||
|
||||
**MoltenVK** and *Vulkan* Compliance
|
||||
------------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user