Copyright © 2015-2022 LunarG, Inc.

VK_LAYER_KHRONOS_profiles

Overview

Vulkan capabilities test coverage with the Khronos Profiles Layer

The Khronos Profiles Layer helps test across a wide range of hardware capabilities without requiring a physical copy of every device. It can be applied without modifying any application binaries, and in a fully automated fashion. The Profiles layer is a Vulkan layer that can override the values returned by your application's queries of the GPU. Profiles layer uses a JSON text configuration file to make your application see a different driver/GPU than is actually in your system. This capability is useful to verify that your application both a) properly queries the limits from Vulkan, and b) obeys those limits.

The Profiles layer is available pre-built in the Vulkan Configurator included with the Vulkan SDK.

The role of the Profiles layer is to "simulate" a Vulkan implementation by modifying the features and resources of a more-capable implementation. The Profiles layer does not add capabilities to your existing Vulkan implementation by "emulating" additional capabilities with software; e.g. the Profiles layer cannot add geometry shader capability to an actual device that doesn't already provide it. Also, the Profiles layer does not "enforce" the features being simulated. You can use the Validation Layer in conjunction with the Profiles Layer to identify where your application is not adhering to the features being simulated by the Profiles Layer.

Configuring the Profiles Layer

For an overview of how to configure layers, refer to the Layers Overview and Configuration document.

The Profiles Layer settings are documented in detail in the VK_LAYER_KHRONOS_profiless document.

The Profiles Layer can also be enabled and configured using Vulkan Configurator. See the Vulkan Configurator documentation for more information.

Using the Profiles layer with Vulkan Configurator

The Profiles Layer can be controlled using environment variables or more intuitively using the Vulkan Configurator GUI application.

The built-in Portability layers configurations in Vulkan Configurator using the Validation and the Profiles layers

The Portability layers configuration in Vulkan Configurator checks that a Vulkan application follows the requirements of a Vulkan Profile. This layers configuration relies on the Vulkan Profiles layer to override the Vulkan device capabilities and the Vulkan Validation Layer to check that the Vulkan application doesn't rely on capabilities not supported by the selected profile.

The input to the Profiles layer is a profiles file that is using the flexible JSON syntax. The profiles file format is defined by a formal JSON schema, so any profiles file may be verified to be correct using freely available JSON validators. Examination of the schema file reveals the extent of parameters that are available for configuration.

To use the Profiles Layer Vulkan version 1.1 is required.

Example of a Profiles layer JSON profiles file: VP_LUNARG_test_structure_simple.json

Android

To enable, use a system property with the path of the profiles file to load:

adb shell setprop debug.vulkan.khronos_profiles.profile_file <path/to/profiles/JSON/file>

Optional: use system properties to enable debugging output and exit-on-error:

adb shell setprop debug.vulkan.khronos_profiles.debug_reports DEBUG_REPORT_DEBUG_BIT
adb shell setprop debug.vulkan.khronos_profiles.debug_fail_on_error true

Settings File

Layer options may also be specified through a layer settings file on Android using the debug.vulkan.khronos_profiles.settings_path system property.

adb shell setprop debug.vulkan.khronos_profiles.settings_path </path/to/vk_layer_settings.txt>

Technical Details

The Profiles Layer is a Vulkan layer that can modify the results of Vulkan PhysicalDevice queries based on a profiles file (JSON format), thus simulating some of the capabilities of a device by overriding the capabilities of the actual device under test.

Please note that this device simulation layer "simulates", rather than "emulates". By that we mean that the layer cannot add emulated capabilities that do not already exist in the system's underlying actual device. The Profiles layer will not enable a less-capable device to emulate a more-capable device.

Application code can be tested to verify it responds correctly to the capabilities reported by the simulated device. That could include:

• Properly querying the capabilities of the device.
• Properly complying with the limits reported from the device.
• Verifying all necessary capabilities are reported present, rather than assuming they are available.
• Exercising fall-back code paths, if optional capabilities are not available.

The fail_on_error option can be used to make sure the device supports the requested capabilities. In this case if an application erroneously attempts to overcommit a resource, or use a disabled feature, the Profiles layer will return VK_ERROR_INITIALIZATION_FAILED from vkEnumeratePhysicalDevices().

The Profiles layer will work together with other Vulkan layers, such as the Validation layer. When configuring the order of the layers, the Profiles layer should be "last"; i.e.: closest to the driver, furthest from the application. That allows the Validation layer to see the results of the Profiles layer, and enable Validation to flag incorrect API usage beyond the simulated capabilities.

If you find issues, please report to Khronos' Vulkan-Profiles GitHub repository.

Profiles Layer operation and profiles file

At application startup, during vkEnumeratePhysicalDevices(), the Profiles layer initializes its internal tables from the actual physical device in the system, then loads the profiles file, which specifies override values to apply to those internal tables.

JSON file formats consumed by the Profiles layer are specified by the following JSON schemas.

The schema permits additional top-level sections to be optionally included in profiles files; any additional top-level sections will be ignored by the Profiles layer.

The schemas define basic range checking for common Vulkan data types, but they cannot detect whether a particular profile is illogical. If a profile defines capabilities beyond what the actual device is natively capable of providing and the fail_on_error option is not used, the results are undefined. The Profiles layer has some simple checking of profile values and writes debug messages (if enabled) for values that are incompatible with the capabilities of the actual device.

This version of the Profiles layer currently supports Vulkan v1.3 and below including all Vulkan extensions. If the application requests an unsupported version of the Vulkan API, the Profiles layer will emit an error message.

When a Vulkan extension gets promoted so can the structures it defines. It is invalid for a profile to specify a structure and its promoted version at the same time. In this case the Profiles layer will use the promoted version of the structure and emit a warning.

VK_KHR_portability_subset Emulation

The Profiles layer provides the ability to emulate the VK_KHR_portability_subset extension on devices that do not implement this extension. This feature allows users to test their application with limitations found on non-conformant Vulkan implementations. To turn on this feature, enable it as described below.

Layer Details

Layer Properties

• API Version: 1.3.280
• Implementation Version: 1.2.0
• Layer Manifest: VkLayer_khronos_profiles.json
  • File Format: 1.2.1
  • Layer Binary: libVkLayer_khronos_profiles.so
• Platforms: WINDOWS, LINUX, MACOS
• Number of Layer Settings: 9
• Number of Layer Presets: 3

Layer Settings Overview

Layer Settings Details

Force Device

On system with multiple physical devices, force the use of one specific physical device.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.force_device
• Environment Variable: VK_KHRONOS_PROFILES_FORCE_DEVICE
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: ENUM
• Setting Default Value: FORCE_DEVICE_OFF

Device UUID

Device UUID of the forced physical devices

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.force_device_uuid
• Environment Variable: VK_KHRONOS_PROFILES_FORCE_DEVICE_UUID
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: STRING
• Setting Default Value: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Device Name

Device Name of the forced physical devices

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.force_device_name
• Environment Variable: VK_KHRONOS_PROFILES_FORCE_DEVICE_NAME
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: ENUM
• Setting Default Value: ${VP_PHYSICAL_DEVICES}

Emulate a Vulkan Profile

Emulate a Vulkan Profile on the Developer System

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.profile_emulation
• Environment Variable: VK_KHRONOS_PROFILES_PROFILE_EMULATION
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: true

Profiles Directories

Select the location all the profiles.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.profile_dirs
• Environment Variable: VK_KHRONOS_PROFILES_PROFILE_DIRS
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: LOAD_FOLDER
• Setting Default Value:

Profile Name

Name of the profile specified by the profile file to use. If set to ${VP_DEFAULT}, the layer will load the first profile in the file.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.profile_name
• Environment Variable: VK_KHRONOS_PROFILES_PROFILE_NAME
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: ENUM
• Setting Default Value: ${VP_DEFAULT}

Schema Validation

Validate the profile files against the Vulkan SDK profile schema if the file is found.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.profile_validation
• Environment Variable: VK_KHRONOS_PROFILES_PROFILE_VALIDATION
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: false

Simulate Profile Capabilities

Control of the simulated capabilities of the Vulkan physical device from the selected Vulkan Profile.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.simulate_capabilities
• Environment Variable: VK_KHRONOS_PROFILES_SIMULATE_CAPABILITIES
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: FLAGS
• Setting Default Value: SIMULATE_API_VERSION_BIT, SIMULATE_FEATURES_BIT, SIMULATE_PROPERTIES_BIT

Unspecified Features

Feature values when not specified in the select Vulkan profiles.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.default_feature_values
• Environment Variable: VK_KHRONOS_PROFILES_DEFAULT_FEATURE_VALUES
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: ENUM
• Setting Default Value: DEFAULT_FEATURE_VALUES_DEVICE

Emulate VK_KHR_portability_subset

Emulate the VK_KHR_portability_subset extension on the device.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.emulate_portability
• Environment Variable: VK_KHRONOS_PROFILES_EMULATE_PORTABILITY
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

constantAlphaColorBlendFactors

Indicates whether this implementation supports constant alpha Blend Factors used as source or destination color Blending.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.constantAlphaColorBlendFactors
• Environment Variable: VK_KHRONOS_PROFILES_CONSTANTALPHACOLORBLENDFACTORS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

events

Indicates whether this implementation supports synchronization using Events

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.events
• Environment Variable: VK_KHRONOS_PROFILES_EVENTS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

imageViewFormatReinterpretation

Indicates whether this implementation supports a VkImageView being created with a texel format containing a different number of components, or a different number of bits in each component, than the texel format of the underlying VkImage.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.imageViewFormatReinterpretation
• Environment Variable: VK_KHRONOS_PROFILES_IMAGEVIEWFORMATREINTERPRETATION
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

imageViewFormatSwizzle

Indicates whether this implementation supports remapping format components using VkImageViewCreateInfo::components.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.imageViewFormatSwizzle
• Environment Variable: VK_KHRONOS_PROFILES_IMAGEVIEWFORMATSWIZZLE
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

imageView2DOn3DImage

Indicates whether this implementation supports a VkImage being created with the VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT flag set, permitting a 2D or 2D array image view to be created on a 3D VkImage.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.imageView2DOn3DImage
• Environment Variable: VK_KHRONOS_PROFILES_IMAGEVIEW2DON3DIMAGE
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

multisampleArrayImage

Indicates whether this implementation supports a VkImage being created as a 2D array with multiple samples per texel.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.multisampleArrayImage
• Environment Variable: VK_KHRONOS_PROFILES_MULTISAMPLEARRAYIMAGE
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

mutableComparisonSamplers

Indicates whether this implementation allows descriptors with comparison samplers to be updated.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.mutableComparisonSamplers
• Environment Variable: VK_KHRONOS_PROFILES_MUTABLECOMPARISONSAMPLERS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

pointPolygons

Indicates whether this implementation supports Rasterization using a point Polygon Mode.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.pointPolygons
• Environment Variable: VK_KHRONOS_PROFILES_POINTPOLYGONS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

samplerMipLodBias

Indicates whether this implementation supports setting a mipmap LOD bias value when creating a sampler.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.samplerMipLodBias
• Environment Variable: VK_KHRONOS_PROFILES_SAMPLERMIPLODBIAS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

separateStencilMaskRef

Indicates whether this implementation supports separate front and back Stencil Test reference values.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.separateStencilMaskRef
• Environment Variable: VK_KHRONOS_PROFILES_SEPARATESTENCILMASKREF
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

shaderSampleRateInterpolationFunctions

Indicates whether this implementation supports fragment shaders which use the InterpolationFunction capability.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.shaderSampleRateInterpolationFunctions
• Environment Variable: VK_KHRONOS_PROFILES_SHADERSAMPLERATEINTERPOLATIONFUNCTIONS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

tessellationIsolines

Indicates whether this implementation supports isoline output from the Tessellation stage of a graphics pipeline. This member is only meaningful if tessellationShader are supported.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.tessellationIsolines
• Environment Variable: VK_KHRONOS_PROFILES_TESSELLATIONISOLINES
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

triangleFans

Indicates whether this implementation supports Triangle Fans primitive topology.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.triangleFans
• Environment Variable: VK_KHRONOS_PROFILES_TRIANGLEFANS
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

vertexAttributeAccessBeyondStride

Indicates whether this implementation supports accessing a vertex input attribute beyond the stride of the corresponding vertex input binding.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.vertexAttributeAccessBeyondStride
• Environment Variable: VK_KHRONOS_PROFILES_VERTEXATTRIBUTEACCESSBEYONDSTRIDE
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

minVertexInputBindingStrideAlignment

Indicates whether this implementation supports accessing a vertex input attribute beyond the stride of the corresponding vertex input binding.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.minVertexInputBindingStrideAlignment
• Environment Variable: VK_KHRONOS_PROFILES_MINVERTEXINPUTBINDINGSTRIDEALIGNMENT
• Platforms: WINDOWS, LINUX
• Setting Type: INT
• Setting Default Value: 4

Exclude Device Extensions

Removes the listed device extensions from being reported by the Vulkan physical device.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.exclude_device_extensions
• Environment Variable: VK_KHRONOS_PROFILES_EXCLUDE_DEVICE_EXTENSIONS
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: LIST
• Setting Default Value:

Exclude Formats

Removes the format feature flags from being reported by the Vulkan physical device.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.exclude_formats
• Environment Variable: VK_KHRONOS_PROFILES_EXCLUDE_FORMATS
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: LIST
• Setting Default Value:

Debug Actions

This indicates what action is to be taken when a layer wants to report information

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.debug_actions
• Environment Variable: VK_KHRONOS_PROFILES_DEBUG_ACTIONS
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: FLAGS
• Setting Default Value: DEBUG_ACTION_STDOUT_BIT

Log Filename

Specifies the output filename

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.debug_filename
• Environment Variable: VK_KHRONOS_PROFILES_DEBUG_FILENAME
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: SAVE_FILE
• Setting Default Value: profiles_layer_log.txt

Clear Log at Launch

Discard the content of the log file between each layer run

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.debug_file_clear
• Environment Variable: VK_KHRONOS_PROFILES_DEBUG_FILE_CLEAR
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: true

Fail on Error

If the device doesn't support the capabilities of the selected Profile, the layer fail to load. When enabled, vkEnumeratePhysicalDevices will fail when the selected Profile is not supported.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.debug_fail_on_error
• Environment Variable: VK_KHRONOS_PROFILES_DEBUG_FAIL_ON_ERROR
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: false

Message Types

This is a comma-delineated list of options telling the layer what types of messages it should report back

Setting Properties:

• vk_layer_settings.txt Variable: khronos_profiles.debug_reports
• Environment Variable: VK_KHRONOS_PROFILES_DEBUG_REPORTS
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: FLAGS
• Setting Default Value: DEBUG_REPORT_NOTIFICATION_BIT, DEBUG_REPORT_WARNING_BIT, DEBUG_REPORT_ERROR_BIT

Layer Presets

Force Physical Device Only

Use the Profiles layer to force a specific physical device

Preset Setting Values:

• Force Device: FORCE_DEVICE_WITH_NAME
• Emulate a Vulkan Profile: false
• Simulate Profile Capabilities:
• Emulate VK_KHR_portability_subset: false

Emulate a Vulkan Conformant Profile

Emulate a Conformant Vulkan Profile

Preset Setting Values:

• Force Device: FORCE_DEVICE_OFF
• Emulate a Vulkan Profile: true
• Profiles Directories: VK_LAYER_KHRONOS_profiles
• Profile Name: VP_LUNARG_desktop_baseline_2023
• Simulate Profile Capabilities: SIMULATE_API_VERSION_BIT, SIMULATE_FEATURES_BIT, SIMULATE_PROPERTIES_BIT
• Emulate VK_KHR_portability_subset: false

Emulate a Vulkan Portability Profile

Emulate a Vulkan Profile with Vulkan Portability

Preset Setting Values:

• Force Device: FORCE_DEVICE_OFF
• Emulate a Vulkan Profile: true
• Profiles Directories: VK_LAYER_KHRONOS_profiles
• Profile Name: VP_LUNARG_desktop_baseline_2023
• Simulate Profile Capabilities: SIMULATE_API_VERSION_BIT, SIMULATE_FEATURES_BIT, SIMULATE_PROPERTIES_BIT
• Emulate VK_KHR_portability_subset: true
• vertexAttributeAccessBeyondStride: true
• separateStencilMaskRef: true
• mutableComparisonSamplers: true
• multisampleArrayImage: true
• imageViewFormatSwizzle: true
• imageViewFormatReinterpretation: true
• events: true
• constantAlphaColorBlendFactors: true