LunarG

Copyright © 2015-2022 LunarG, Inc.

Creative Commons

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.

Vulkan Configurator 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:

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

Layer Settings Overview

Setting Type Default Value vk_layer_settings.txt Variable Environment Variable Platforms
Force Device ENUM FORCE_DEVICE_OFF khronos_profiles.force_device VK_KHRONOS_PROFILES_FORCE_DEVICE WINDOWS, LINUX, MACOS
Device UUID STRING XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX khronos_profiles.force_device_uuid VK_KHRONOS_PROFILES_FORCE_DEVICE_UUID WINDOWS, LINUX, MACOS
Device Name ENUM ${VP_PHYSICAL_DEVICES} khronos_profiles.force_device_name VK_KHRONOS_PROFILES_FORCE_DEVICE_NAME WINDOWS, LINUX, MACOS
Emulate a Vulkan Profile BOOL true khronos_profiles.profile_emulation VK_KHRONOS_PROFILES_PROFILE_EMULATION WINDOWS, LINUX, MACOS
Loading Directory LOAD_FOLDER khronos_profiles.profile_dirs VK_KHRONOS_PROFILES_PROFILE_DIRS WINDOWS, LINUX, MACOS
Name ENUM ${VP_DEFAULT} khronos_profiles.profile_name VK_KHRONOS_PROFILES_PROFILE_NAME WINDOWS, LINUX, MACOS
Schema Validation BOOL false khronos_profiles.profile_validation VK_KHRONOS_PROFILES_PROFILE_VALIDATION WINDOWS, LINUX, MACOS
Simulate Profile Capabilities FLAGS SIMULATE_API_VERSION_BIT, SIMULATE_FEATURES_BIT, SIMULATE_PROPERTIES_BIT khronos_profiles.simulate_capabilities VK_KHRONOS_PROFILES_SIMULATE_CAPABILITIES WINDOWS, LINUX, MACOS
Unspecified Features ENUM DEFAULT_FEATURE_VALUES_DEVICE khronos_profiles.default_feature_values VK_KHRONOS_PROFILES_DEFAULT_FEATURE_VALUES WINDOWS, LINUX, MACOS
Emulate VK_KHR_portability_subset BOOL true khronos_profiles.emulate_portability VK_KHRONOS_PROFILES_EMULATE_PORTABILITY WINDOWS, LINUX
constantAlphaColorBlendFactors BOOL false khronos_profiles.constantAlphaColorBlendFactors VK_KHRONOS_PROFILES_CONSTANTALPHACOLORBLENDFACTORS WINDOWS, LINUX
events BOOL false khronos_profiles.events VK_KHRONOS_PROFILES_EVENTS WINDOWS, LINUX
imageViewFormatReinterpretation BOOL false khronos_profiles.imageViewFormatReinterpretation VK_KHRONOS_PROFILES_IMAGEVIEWFORMATREINTERPRETATION WINDOWS, LINUX
imageViewFormatSwizzle BOOL false khronos_profiles.imageViewFormatSwizzle VK_KHRONOS_PROFILES_IMAGEVIEWFORMATSWIZZLE WINDOWS, LINUX
imageView2DOn3DImage BOOL false khronos_profiles.imageView2DOn3DImage VK_KHRONOS_PROFILES_IMAGEVIEW2DON3DIMAGE WINDOWS, LINUX
multisampleArrayImage BOOL false khronos_profiles.multisampleArrayImage VK_KHRONOS_PROFILES_MULTISAMPLEARRAYIMAGE WINDOWS, LINUX
mutableComparisonSamplers BOOL false khronos_profiles.mutableComparisonSamplers VK_KHRONOS_PROFILES_MUTABLECOMPARISONSAMPLERS WINDOWS, LINUX
pointPolygons BOOL false khronos_profiles.pointPolygons VK_KHRONOS_PROFILES_POINTPOLYGONS WINDOWS, LINUX
samplerMipLodBias BOOL false khronos_profiles.samplerMipLodBias VK_KHRONOS_PROFILES_SAMPLERMIPLODBIAS WINDOWS, LINUX
separateStencilMaskRef BOOL false khronos_profiles.separateStencilMaskRef VK_KHRONOS_PROFILES_SEPARATESTENCILMASKREF WINDOWS, LINUX
shaderSampleRateInterpolationFunctions BOOL false khronos_profiles.shaderSampleRateInterpolationFunctions VK_KHRONOS_PROFILES_SHADERSAMPLERATEINTERPOLATIONFUNCTIONS WINDOWS, LINUX
tessellationIsolines BOOL false khronos_profiles.tessellationIsolines VK_KHRONOS_PROFILES_TESSELLATIONISOLINES WINDOWS, LINUX
triangleFans BOOL false khronos_profiles.triangleFans VK_KHRONOS_PROFILES_TRIANGLEFANS WINDOWS, LINUX
vertexAttributeAccessBeyondStride BOOL false khronos_profiles.vertexAttributeAccessBeyondStride VK_KHRONOS_PROFILES_VERTEXATTRIBUTEACCESSBEYONDSTRIDE WINDOWS, LINUX
minVertexInputBindingStrideAlignment INT 4 khronos_profiles.minVertexInputBindingStrideAlignment VK_KHRONOS_PROFILES_MINVERTEXINPUTBINDINGSTRIDEALIGNMENT WINDOWS, LINUX
Exclude Device Extensions LIST khronos_profiles.exclude_device_extensions VK_KHRONOS_PROFILES_EXCLUDE_DEVICE_EXTENSIONS WINDOWS, LINUX, MACOS
Exclude Formats LIST khronos_profiles.exclude_formats VK_KHRONOS_PROFILES_EXCLUDE_FORMATS WINDOWS, LINUX, MACOS
Debug Actions FLAGS DEBUG_ACTION_STDOUT_BIT khronos_profiles.debug_actions VK_KHRONOS_PROFILES_DEBUG_ACTIONS WINDOWS, LINUX, MACOS
Log Filename SAVE_FILE profiles_layer_log.txt khronos_profiles.debug_filename VK_KHRONOS_PROFILES_DEBUG_FILENAME WINDOWS, LINUX, MACOS
Clear Log at Launch BOOL true khronos_profiles.debug_file_clear VK_KHRONOS_PROFILES_DEBUG_FILE_CLEAR WINDOWS, LINUX, MACOS
Fail on Error BOOL false khronos_profiles.debug_fail_on_error VK_KHRONOS_PROFILES_DEBUG_FAIL_ON_ERROR WINDOWS, LINUX, MACOS
Message Types FLAGS DEBUG_REPORT_NOTIFICATION_BIT, DEBUG_REPORT_WARNING_BIT, DEBUG_REPORT_ERROR_BIT khronos_profiles.debug_reports VK_KHRONOS_PROFILES_DEBUG_REPORTS WINDOWS, LINUX, MACOS

Layer Settings Details

Force Device

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

Setting Properties:
Enum Value Label Description Platforms
FORCE_DEVICE_OFF Off Let the Vulkan Loader list all the Physical Device. WINDOWS, LINUX, MACOS
FORCE_DEVICE_WITH_UUID Using Device UUID Force the Physical Device identified by the device UUID. WINDOWS, LINUX, MACOS
FORCE_DEVICE_WITH_NAME Using Device Name Force the Physical Device identified by the device UUID. WINDOWS, LINUX, MACOS

Device UUID

Device UUID of the forced physical devices

Setting Properties:

Device Name

Device Name of the forced physical devices

Setting Properties:

Emulate a Vulkan Profile

Emulate a Vulkan Profile on the Developer System

Setting Properties:

Loading Directory

Select the location all the profiles.

Setting Properties:

Name

Name of the profile specified by the profile file to use.

Setting Properties:

Schema Validation

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

Setting Properties:

Simulate Profile Capabilities

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

Setting Properties:
Flags Label Description Platforms
SIMULATE_API_VERSION_BIT Version The Vulkan device will report the API version from the selected Profile. It also overrides the api-version set in VkPhysicalDeviceProperties. WINDOWS, LINUX, MACOS
SIMULATE_FEATURES_BIT Features The Vulkan device will report the features from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_PROPERTIES_BIT Properties The Vulkan device will report the properties from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_EXTENSIONS_BIT Device Extensions The Vulkan device will report the extensions from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_FORMATS_BIT Formats The Vulkan device will report the formats from the selected Profile. WINDOWS, LINUX, MACOS

Unspecified Features

Feature values when not specified in the select Vulkan profiles.

Setting Properties:
Enum Value Label Description Platforms
DEFAULT_FEATURE_VALUES_DEVICE Use Device Values When a feature is not mentionned in the select Vulkan profiles, set is to the physical device value. WINDOWS, LINUX, MACOS
DEFAULT_FEATURE_VALUES_FALSE Use False When a feature is not mentionned in the select Vulkan profiles, set it to false. WINDOWS, LINUX, MACOS

Emulate VK_KHR_portability_subset

Emulate the VK_KHR_portability_subset extension on the device.

Setting Properties:

constantAlphaColorBlendFactors

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

Setting Properties:

events

Indicates whether this implementation supports synchronization using Events

Setting Properties:

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:

imageViewFormatSwizzle

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

Setting Properties:

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:

multisampleArrayImage

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

Setting Properties:

mutableComparisonSamplers

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

Setting Properties:

pointPolygons

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

Setting Properties:

samplerMipLodBias

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

Setting Properties:

separateStencilMaskRef

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

Setting Properties:

shaderSampleRateInterpolationFunctions

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

Setting Properties:

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:

triangleFans

Indicates whether this implementation supports Triangle Fans primitive topology.

Setting Properties:

vertexAttributeAccessBeyondStride

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

Setting Properties:

minVertexInputBindingStrideAlignment

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

Setting Properties:

Exclude Device Extensions

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

Setting Properties:

Exclude Formats

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

Setting Properties:

Debug Actions

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

Setting Properties:
Flags Label Description Platforms
DEBUG_ACTION_STDOUT_BIT Log to stdout Log messages using the stdout. WINDOWS, LINUX, MACOS
DEBUG_ACTION_OUTPUT_BIT Log to OutputDebugString Log messages using the Windows OutputDebugString for Vulkan Studio output display. WINDOWS
DEBUG_ACTION_FILE_BIT Log to File Log messages to a file. WINDOWS, LINUX, MACOS
DEBUG_ACTION_BREAKPOINT_BIT Break Trigger a breakpoint if a debugger is in use. WINDOWS, LINUX, MACOS

Log Filename

Specifies the output filename

Setting Properties:

Clear Log at Launch

Discard the content of the log file between each layer run

Setting Properties:

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:

Message Types

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

Setting Properties:
Flags Label Description Platforms
DEBUG_REPORT_NOTIFICATION_BIT Notification Report notifications. WINDOWS, LINUX, MACOS
DEBUG_REPORT_WARNING_BIT Warning Report warnings from using the API in a manner which may lead to undefined behavior or to warn the user of common trouble spots. A warning does NOT necessarily signify illegal application behavior. WINDOWS, LINUX, MACOS
DEBUG_REPORT_ERROR_BIT Error Report errors in API usage. WINDOWS, LINUX, MACOS
DEBUG_REPORT_DEBUG_BIT Debug Report debug information for the Profiles Layer development. WINDOWS, LINUX, MACOS

Layer Presets

Force Physical Device Only

Use the Profiles layer to force a specific physical device

Preset Setting Values:

Emulate a Vulkan Conformant Profile

Emulate a Conformant Vulkan Profile

Preset Setting Values:

Emulate a Vulkan Portability Profile

Emulate a Vulkan Profile with Vulkan Portability

Preset Setting Values: