Appendix E: Layers & Extensions (Informative)
Extensions to the Vulkan API can be defined by authors, groups of authors, and the Khronos Vulkan Working Group. In order not to compromise the readability of the Vulkan Specification, the core Specification does not incorporate most extensions. The online Registry of extensions is available at URL
and allows generating versions of the Specification incorporating different extensions.
Most of the content previously in this appendix does not specify use of specific Vulkan extensions and layers, but rather specifies the processes by which extensions and layers are created. As of version 1.0.21 of the Vulkan Specification, this content has been migrated to the Vulkan Documentation and Extensions document. Authors creating extensions and layers must follow the mandatory procedures in that document.
The remainder of this appendix documents a set of extensions chosen when this document was built. Versions of the Specification published in the Registry include:
-
Core API + mandatory extensions required of all Vulkan implementations.
-
Core API + all registered and published Khronos (
KHR
) extensions. -
Core API + all registered and published extensions.
Extensions are grouped as Khronos KHR
, multivendor EXT
, and then
alphabetically by author ID.
Within each group, extensions are listed in alphabetical order by their
name.
Note
As of the initial Vulkan 1.1 public release, the Some vendors may use an alternate author ID ending in |
List of Current Extensions
VK_KHR_acceleration_structure
- Name String
-
VK_KHR_acceleration_structure
- Extension Type
-
Device extension
- Registered Extension Number
-
151
- Revision
-
11
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_EXT_descriptor_indexing
-
Requires
VK_KHR_buffer_device_address
-
Requires
VK_KHR_deferred_host_operations
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Contributors
-
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Ricardo Garcia, Igalia
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
In order to be efficient, rendering techniques such as ray tracing need a quick way to identify which primitives may be intersected by a ray traversing the geometries. Acceleration structures are the most common way to represent the geometry spatially sorted, in order to quickly identify such potential intersections.
This extension adds new functionalities:
-
Acceleration structure objects and build commands
-
Structures to describe geometry inputs to acceleration structure builds
-
Acceleration structure copy commands
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
VK_KHR_ACCELERATION_STRUCTURE_EXTENSION_NAME
-
VK_KHR_ACCELERATION_STRUCTURE_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR
-
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR
-
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
-
-
Extending VkDebugReportObjectTypeEXT:
-
VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT
-
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR
-
-
Extending VkIndexType:
-
VK_INDEX_TYPE_NONE_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR
-
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR
-
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR
-
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR
-
VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR
-
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ACCELERATION_STRUCTURE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR
-
Issues
(1) How does this extension differ from VK_NV_ray_tracing?
DISCUSSION:
The following is a summary of the main functional differences between VK_KHR_acceleration_structure and VK_NV_ray_tracing:
-
added acceleration structure serialization / deserialization (
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR
,VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR
, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR) -
document inactive primitives and instances
-
added VkPhysicalDeviceAccelerationStructureFeaturesKHR structure
-
added indirect and batched acceleration structure builds (vkCmdBuildAccelerationStructuresIndirectKHR)
-
added host acceleration structure commands
-
reworked geometry structures so they could be better shared between device, host, and indirect builds
-
explicitly made VkAccelerationStructureKHR use device addresses
-
added acceleration structure compatibility check function (vkGetDeviceAccelerationStructureCompatibilityKHR)
-
add parameter for requesting memory requirements for host and/or device build
-
added format feature for acceleration structure build vertex formats (
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR
)
(2) Can you give a more detailed comparision of differences and similarities between VK_NV_ray_tracing and VK_KHR_acceleration_structure?
DISCUSSION:
The following is a more detailed comparision of which commands, structures, and enums are aliased, changed, or removed.
-
Aliased functionality — enums, structures, and commands that are considered equivalent:
-
VkAccelerationStructureTypeNV ↔ VkAccelerationStructureTypeKHR
-
VkCopyAccelerationStructureModeNV ↔ VkCopyAccelerationStructureModeKHR
-
VkGeometryInstanceFlagBitsNV ↔ VkGeometryInstanceFlagBitsKHR
-
VkBuildAccelerationStructureFlagsNV ↔ VkBuildAccelerationStructureFlagsKHR
-
VkBuildAccelerationStructureFlagBitsNV ↔ VkBuildAccelerationStructureFlagBitsKHR
-
VkTransformMatrixNV ↔ VkTransformMatrixKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
VkAabbPositionsNV ↔ VkAabbPositionsKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
VkAccelerationStructureInstanceNV ↔ VkAccelerationStructureInstanceKHR (added to VK_NV_ray_tracing for descriptive purposes)
-
Changed enums, structures, and commands:
-
renamed
VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV
→VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR
in VkGeometryInstanceFlagBitsKHR -
VkGeometryTrianglesNV → VkAccelerationStructureGeometryTrianglesDataKHR (device or host address instead of buffer+offset)
-
VkGeometryAABBNV → VkAccelerationStructureGeometryAabbsDataKHR (device or host address instead of buffer+offset)
-
VkGeometryDataNV → VkAccelerationStructureGeometryDataKHR (union of triangle/aabbs/instances)
-
VkGeometryNV → VkAccelerationStructureGeometryKHR (changed type of geometry)
-
VkAccelerationStructureCreateInfoNV → VkAccelerationStructureCreateInfoKHR (reshuffle geometry layout/info)
-
VkPhysicalDeviceRayTracingPropertiesNV → VkPhysicalDeviceAccelerationStructurePropertiesKHR (for acceleration structure properties, renamed
maxTriangleCount
tomaxPrimitiveCount
, added per stage and update after bind limits) and VkPhysicalDeviceRayTracingPipelinePropertiesKHR (for ray tracing pipeline properties) -
VkAccelerationStructureMemoryRequirementsInfoNV (deleted - replaced by allocating on top of VkBuffer)
-
VkWriteDescriptorSetAccelerationStructureNV → VkWriteDescriptorSetAccelerationStructureKHR (different acceleration structure type)
-
vkCreateAccelerationStructureNV → vkCreateAccelerationStructureKHR (device address, different geometry layout/info)
-
vkGetAccelerationStructureMemoryRequirementsNV (deleted - replaced by allocating on top of VkBuffer)
-
vkCmdBuildAccelerationStructureNV → vkCmdBuildAccelerationStructuresKHR (params moved to structs, layout differences)
-
vkCmdCopyAccelerationStructureNV → vkCmdCopyAccelerationStructureKHR (params to struct, extendable)
-
vkGetAccelerationStructureHandleNV → vkGetAccelerationStructureDeviceAddressKHR (device address instead of handle)
-
VkAccelerationStructureMemoryRequirementsTypeNV → size queries for scratch space moved to vkGetAccelerationStructureBuildSizesKHR
-
vkDestroyAccelerationStructureNV → vkDestroyAccelerationStructureKHR (different acceleration structure types)
-
vkCmdWriteAccelerationStructuresPropertiesNV → vkCmdWriteAccelerationStructuresPropertiesKHR (different acceleration structure types)
-
-
Added enums, structures and commands:
-
VK_GEOMETRY_TYPE_INSTANCES_KHR
to VkGeometryTypeKHR enum -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR
,VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR
to VkCopyAccelerationStructureModeKHR enum -
VkDeviceOrHostAddressKHR and VkDeviceOrHostAddressConstKHR unions
-
vkBuildAccelerationStructuresKHR command (host build)
-
vkCopyAccelerationStructureKHR command (host copy)
-
vkCopyAccelerationStructureToMemoryKHR (host serialize)
-
vkCopyMemoryToAccelerationStructureKHR (host deserialize)
-
vkWriteAccelerationStructuresPropertiesKHR (host properties)
-
vkCmdCopyAccelerationStructureToMemoryKHR (device serialize)
-
vkCmdCopyMemoryToAccelerationStructureKHR (device deserialize)
-
vkGetDeviceAccelerationStructureCompatibilityKHR (serialization)
-
(3) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?
-
added
geometryFlags
toVkAccelerationStructureCreateGeometryTypeInfoKHR
(later reworked to obsolete this) -
added
minAccelerationStructureScratchOffsetAlignment
property to VkPhysicalDeviceRayTracingPropertiesKHR -
fix naming and return enum from vkGetDeviceAccelerationStructureCompatibilityKHR
-
renamed
VkAccelerationStructureVersionKHR
to VkAccelerationStructureVersionInfoKHR -
renamed
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_KHR
toVK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_INFO_KHR
-
removed
VK_ERROR_INCOMPATIBLE_VERSION_KHR
-
added VkAccelerationStructureCompatibilityKHR enum
-
remove return value from vkGetDeviceAccelerationStructureCompatibilityKHR and added return enum parameter
-
-
Require Vulkan 1.1
-
added creation time capture and replay flags
-
added VkAccelerationStructureCreateFlagBitsKHR and VkAccelerationStructureCreateFlagsKHR
-
renamed the
flags
member of VkAccelerationStructureCreateInfoKHR tobuildFlags
(later removed) and added thecreateFlags
member
-
-
change vkCmdBuildAccelerationStructuresIndirectKHR to use buffer device address for indirect parameter
-
make VK_KHR_deferred_host_operations an interaction instead of a required extension (later went back on this)
-
renamed
VkAccelerationStructureBuildOffsetInfoKHR
to VkAccelerationStructureBuildRangeInfoKHR-
renamed the
ppOffsetInfos
parameter of vkCmdBuildAccelerationStructuresKHR toppBuildRangeInfos
-
-
Re-unify geometry description between build and create
-
remove
VkAccelerationStructureCreateGeometryTypeInfoKHR
andVK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_GEOMETRY_TYPE_INFO_KHR
-
added
VkAccelerationStructureCreateSizeInfoKHR
structure (later removed) -
change type of the
pGeometryInfos
member of VkAccelerationStructureCreateInfoKHR fromVkAccelerationStructureCreateGeometryTypeInfoKHR
to VkAccelerationStructureGeometryKHR (later removed) -
added
pCreateSizeInfos
member to VkAccelerationStructureCreateInfoKHR (later removed)
-
-
Fix ppGeometries ambiguity, add pGeometries
-
remove
geometryArrayOfPointers
member of VkAccelerationStructureBuildGeometryInfoKHR -
disambiguate two meanings of
ppGeometries
by explicitly addingpGeometries
to the VkAccelerationStructureBuildGeometryInfoKHR structure and require one of them beNULL
-
-
added nullDescriptor support for acceleration structures
-
changed the
update
member of VkAccelerationStructureBuildGeometryInfoKHR from a bool to themode
VkBuildAccelerationStructureModeKHR enum which allows future extensibility in update types -
Clarify deferred host ops for pipeline creation
-
VkDeferredOperationKHR is now a top-level parameter for vkBuildAccelerationStructuresKHR, vkCreateRayTracingPipelinesKHR, vkCopyAccelerationStructureToMemoryKHR, vkCopyAccelerationStructureKHR, and vkCopyMemoryToAccelerationStructureKHR
-
removed
VkDeferredOperationInfoKHR
structure -
change deferred host creation/return parameter behavior such that the implementation can modify such parameters until the deferred host operation completes
-
VK_KHR_deferred_host_operations is required again
-
-
Change acceleration structure build to always be sized
-
de-alias VkAccelerationStructureMemoryRequirementsTypeNV and
VkAccelerationStructureMemoryRequirementsTypeKHR
and removeVkAccelerationStructureMemoryRequirementsTypeKHR
-
add vkGetAccelerationStructureBuildSizesKHR command and VkAccelerationStructureBuildSizesInfoKHR structure and
VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR
enum to query sizes for acceleration structures and scratch storage -
move size queries for scratch space to vkGetAccelerationStructureBuildSizesKHR
-
remove
compactedSize
,buildFlags
,maxGeometryCount
,pGeometryInfos
,pCreateSizeInfos
members of VkAccelerationStructureCreateInfoKHR and add thesize
member -
add
maxVertex
member to VkAccelerationStructureGeometryTrianglesDataKHR structure -
remove
VkAccelerationStructureCreateSizeInfoKHR
structure
-
(4) What are the changes between the internal provisional (VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure v11) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure (for acceleration structure operations)
-
VK_KHR_ray_tracing_pipeline (for ray tracing pipeline and shader stages)
-
VK_KHR_ray_query (for ray queries in existing shader stages)
-
-
clarify buffer usage flags for ray tracing
-
VK_BUFFER_USAGE_RAY_TRACING_BIT_NV
is left alone in VK_NV_ray_tracing (required onscratch
andinstanceData
) -
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR
is added as an alias ofVK_BUFFER_USAGE_RAY_TRACING_BIT_NV
in VK_KHR_ray_tracing_pipeline and is required on shader binding table buffers -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR
is added in VK_KHR_acceleration_structure for all vertex, index, transform, aabb, and instance buffer data referenced by device build commands -
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT
is used forscratchData
-
-
add max primitive counts (
ppMaxPrimitiveCounts
) to vkCmdBuildAccelerationStructuresIndirectKHR -
Allocate acceleration structures from
VkBuffers
and add a mode to constrain the device address-
de-alias VkBindAccelerationStructureMemoryInfoNV, vkBindAccelerationStructureMemoryNV, and remove
VkBindAccelerationStructureMemoryInfoKHR
,VkAccelerationStructureMemoryRequirementsInfoKHR
, andvkGetAccelerationStructureMemoryRequirementsKHR
-
acceleration structures now take a VkBuffer and offset at creation time for memory placement
-
add a new
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
buffer usage such buffers -
add a new
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
acceleration structure type for layering
-
-
move
VK_GEOMETRY_TYPE_INSTANCES_KHR
to main enum instead of being added via extension -
make build commands more consistent - all now build multiple acceleration structures and are named plurally (vkCmdBuildAccelerationStructuresIndirectKHR, vkCmdBuildAccelerationStructuresKHR, vkBuildAccelerationStructuresKHR)
-
add interactions with
VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT
for acceleration structures, including a new feature (descriptorBindingAccelerationStructureUpdateAfterBind
) and 3 new properties (maxPerStageDescriptorAccelerationStructures
,maxPerStageDescriptorUpdateAfterBindAccelerationStructures
,maxDescriptorSetUpdateAfterBindAccelerationStructures
) -
extension is no longer provisional
-
define synchronization requirements for builds, traces, and copies
-
define synchronization requirements for AS build inputs and indirect build buffer
(5) What is VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR
for?
RESOLVED: It is primarily intended for API layering. In DXR, the acceleration structure is basically just a buffer in a special layout, and you don’t know at creation time whether it will be used as a top or bottom level acceleration structure. We thus added a generic acceleration structure type whose type is unknown at creation time, but is specified at build type instead. Applications which are written directly for Vulkan should not use it.
Version History
-
Revision 1, 2019-12-05 (Members of the Vulkan Ray Tracing TSG)
-
Internal revisions (forked from VK_NV_ray_tracing)
-
-
Revision 2, 2019-12-20 (Daniel Koch, Eric Werness)
-
Add const version of DeviceOrHostAddress (!3515)
-
Add VU to clarify that only handles in the current pipeline are valid (!3518)
-
Restore some missing VUs and add in-place update language (#1902, !3522)
-
rename VkAccelerationStructureInstanceKHR member from accelerationStructure to accelerationStructureReference to better match its type (!3523)
-
Allow VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS for pipeline creation if shader group handles cannot be re-used. (!3523)
-
update documentation for the VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error code and add missing documentation for new return codes from VK_KHR_deferred_host_operations (!3523)
-
list new query types for VK_KHR_ray_tracing (!3523)
-
Fix VU statements for VkAccelerationStructureGeometryKHR referring to correct union members and update to use more current wording (!3523)
-
-
Revision 3, 2020-01-10 (Daniel Koch, Jon Leech, Christoph Kubisch)
-
Fix 'instance of' and 'that/which contains/defines' markup issues (!3528)
-
factor out VK_KHR_pipeline_library as stand-alone extension (!3540)
-
Resolve Vulkan-hpp issues (!3543)
-
add missing require for VkGeometryInstanceFlagsKHR
-
de-alias VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV since the KHR structure is no longer equivalent
-
add len to pDataSize attribute for vkWriteAccelerationStructuresPropertiesKHR
-
-
Revision 4, 2020-01-23 (Daniel Koch, Eric Werness)
-
Improve vkWriteAccelerationStructuresPropertiesKHR, add return value and VUs (#1947)
-
Clarify language to allow multiple raygen shaders (#1959)
-
Various editorial feedback (!3556)
-
Add language to help deal with looped self-intersecting fans (#1901)
-
Change vkCmdTraceRays{Indirect}KHR args to pointers (!3559)
-
Add scratch address validation language (#1941, !3551)
-
Fix definition and add hierarchy information for shader call scope (#1977, !3571)
-
-
Revision 5, 2020-02-04 (Eric Werness, Jeff Bolz, Daniel Koch)
-
remove vestigial accelerationStructureUUID (!3582)
-
update definition of repack instructions and improve memory model interactions (#1910, #1913, !3584)
-
Fix wrong sType for VkPhysicalDeviceRayTracingFeaturesKHR (#1988)
-
Use provisional SPIR-V capabilities (#1987)
-
require rayTraversalPrimitiveCulling if rayQuery is supported (#1927)
-
Miss shaders do not have object parameters (!3592)
-
Fix missing required types in XML (!3592)
-
clarify matching conditions for update (!3592)
-
add goal that host and device builds be similar (!3592)
-
clarify that
maxPrimitiveCount
limit should apply to triangles and AABBs (!3592) -
Require alignment for instance arrayOfPointers (!3592)
-
Zero is a valid value for instance flags (!3592)
-
Add some alignment VUs that got lost in refactoring (!3592)
-
Recommend TMin epsilon rather than culling (!3592)
-
Get angle from dot product not cross product (!3592)
-
Clarify that AH can access the payload and attributes (!3592)
-
Match DXR behavior for inactive primitive definition (!3592)
-
Use a more generic term than degenerate for inactive to avoid confusion (!3592)
-
-
Revision 6, 2020-02-20 (Daniel Koch)
-
fix some dangling NV references (#1996)
-
rename VkCmdTraceRaysIndirectCommandKHR to VkTraceRaysIndirectCommandKHR (!3607)
-
update contributor list (!3611)
-
use uint64_t instead of VkAccelerationStructureReferenceKHR in VkAccelerationStructureInstanceKHR (#2004)
-
-
Revision 7, 2020-02-28 (Tobias Hector)
-
remove HitTKHR SPIR-V builtin (spirv/spirv-extensions#7)
-
-
Revision 8, 2020-03-06 (Tobias Hector, Dae Kim, Daniel Koch, Jeff Bolz, Eric Werness)
-
explicitly state that Tmax is updated when new closest intersection is accepted (#2020,!3536)
-
Made references to min and max t values consistent (!3644)
-
finish enumerating differences relative to VK_NV_ray_tracing in issues (1) and (2) (#1974,!3642)
-
fix formatting in some math equations (!3642)
-
Restrict the Hit Kind operand of
OpReportIntersectionKHR
to 7-bits (spirv/spirv-extensions#8,!3646) -
Say ray tracing 'should' be watertight (#2008,!3631)
-
Clarify memory requirements for ray tracing buffers (#2005,!3649)
-
Add callable size limits (#1997,!3652)
-
-
Revision 9, 2020-04-15 (Eric Werness, Daniel Koch, Tobias Hector, Joshua Barczak)
-
Add geometry flags to acceleration structure creation (!3672)
-
add build scratch memory alignment (minAccelerationStructureScratchOffsetAlignment) (#2065,!3725)
-
fix naming and return enum from vkGetDeviceAccelerationStructureCompatibilityKHR (#2051,!3726)
-
require SPIR-V 1.4 (#2096,!3777)
-
added creation time capture/replay flags (#2104,!3774)
-
require Vulkan 1.1 (#2133,!3806)
-
use device addresses instead of VkBuffers for ray tracing commands (#2074,!3815)
-
add interactions with Vulkan 1.2 and VK_KHR_vulkan_memory_model (#2133,!3830)
-
make VK_KHR_pipeline_library an interaction instead of required (#2045,#2108,!3830)
-
make VK_KHR_deferred_host_operations an interaction instead of required (#2045,!3830)
-
removed maxCallableSize and added explicit stack size management for ray pipelines (#1997,!3817,!3772,!3844)
-
improved documentation for VkAccelerationStructureVersionInfoKHR (#2135,3835)
-
rename VkAccelerationStructureBuildOffsetInfoKHR to VkAccelerationStructureBuildRangeInfoKHR (#2058,!3754)
-
Re-unify geometry description between build and create (!3754)
-
Fix ppGeometries ambiguity, add pGeometries (#2032,!3811)
-
add interactions with VK_EXT_robustness2 and allow nullDescriptor support for acceleration structures (#1920,!3848)
-
added future extensibility for AS updates (#2114,!3849)
-
Fix VU for dispatchrays and add a limit on the size of the full grid (#2160,!3851)
-
Add shaderGroupHandleAlignment property (#2180,!3875)
-
Clarify deferred host ops for pipeline creation (#2067,!3813)
-
Change acceleration structure build to always be sized (#2131,#2197,#2198,!3854,!3883,!3880)
-
-
Revision 10, 2020-07-03 (Mathieu Robart, Daniel Koch, Eric Werness, Tobias Hector)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_acceleration_structure (#1918,!3912)
-
clarify buffer usage flags for ray tracing (#2181,!3939)
-
add max primitive counts to build indirect command (#2233,!3944)
-
Allocate acceleration structures from VkBuffers and add a mode to constrain the device address (#2131,!3936)
-
Move VK_GEOMETRY_TYPE_INSTANCES_KHR to main enum (#2243,!3952)
-
make build commands more consistent (#2247,!3958)
-
add interactions with UPDATE_AFTER_BIND (#2128,!3986)
-
correct and expand build command VUs (!4020)
-
fix copy command VUs (!4018)
-
added various alignment requirements (#2229,!3943)
-
fix valid usage for arrays of geometryCount items (#2198,!4010)
-
define what is allowed to change on RTAS updates and relevant VUs (#2177,!3961)
-
-
Revision 11, 2020-11-12 (Eric Werness, Josh Barczak, Daniel Koch, Tobias Hector)
-
de-alias NV and KHR acceleration structure types and associated commands (#2271,!4035)
-
specify alignment for host copy commands (#2273,!4037)
-
document
VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR
-
specify that acceleration structures are non-linear (#2289,!4068)
-
add several missing VUs for strides, vertexFormat, and indexType (#2315,!4069)
-
restore VUs for VkAccelerationStructureBuildGeometryInfoKHR (#2337,!4098)
-
ban multi-instance memory for host operations (#2324,!4102)
-
allow dstAccelerationStructure to be null for vkGetAccelerationStructureBuildSizesKHR (#2330,!4111)
-
more build VU cleanup (#2138,#4130)
-
specify host endianness for AS serialization (#2261,!4136)
-
add invertible transform matrix VU (#1710,!4140)
-
require geometryCount to be 1 for TLAS builds (!4145)
-
improved validity conditions for build addresses (#4142)
-
add single statement SPIR-V VUs, build limit VUs (!4158)
-
document limits for vertex and aabb strides (#2390,!4184)
-
specify that
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
applies to AS copies (#2382,#4173) -
define sync for AS build inputs and indirect buffer (#2407,!4208)
-
VK_KHR_android_surface
- Name String
-
VK_KHR_android_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
9
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2016-01-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_android_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an
ANativeWindow
, Android’s native surface type.
The ANativeWindow
represents the producer endpoint of any buffer
queue, regardless of consumer endpoint.
Common consumer endpoints for ANativeWindows
are the system window
compositor, video encoders, and application-specific compositors importing
the images through a SurfaceTexture
.
New Enum Constants
-
VK_KHR_ANDROID_SURFACE_EXTENSION_NAME
-
VK_KHR_ANDROID_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Android need a way to query for compatibility between a particular physical device (and queue family?) and a specific Android display?
RESOLVED: No. Currently on Android, any physical device is expected to be able to present to the system compositor, and all queue families must support the necessary image layout transitions and synchronization operations.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft.
-
-
Revision 2, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_android_surface to VK_KHR_android_surface.
-
-
Revision 3, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to surface creation function.
-
-
Revision 4, 2015-11-10 (Jesse Hall)
-
Removed VK_ERROR_INVALID_ANDROID_WINDOW_KHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
VK_KHR_copy_commands2
- Name String
-
VK_KHR_copy_commands2
- Extension Type
-
Device extension
- Registered Extension Number
-
338
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Leger jackohound
-
Other Extension Metadata
- Last Modified Date
-
2020-07-06
- Interactions and External Dependencies
-
-
None
-
- Contributors
-
-
Jeff Leger, Qualcomm
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Description
This extension provides extensible versions of the Vulkan buffer and image copy commands. The new commands are functionally identical to the core commands, except that their copy parameters are specified using extensible structures that can be used to pass extension-specific information.
The following extensible copy commands are introduced with this extension:
vkCmdCopyBuffer2KHR, vkCmdCopyImage2KHR,
vkCmdCopyBufferToImage2KHR, vkCmdCopyImageToBuffer2KHR,
vkCmdBlitImage2KHR, and vkCmdResolveImage2KHR.
Each command contain*Info2KHR
structure parameter that includes
sType
/pNext
members.
Lower level structures that describe each region to be copied are also
extended with sType
/pNext
members.
New Enum Constants
-
VK_KHR_COPY_COMMANDS_2_EXTENSION_NAME
-
VK_KHR_COPY_COMMANDS_2_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_BUFFER_COPY_2_KHR
-
VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2_KHR
-
VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2_KHR
-
VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2_KHR
-
VK_STRUCTURE_TYPE_IMAGE_BLIT_2_KHR
-
VK_STRUCTURE_TYPE_IMAGE_COPY_2_KHR
-
VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2_KHR
-
VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2_KHR
-
VK_KHR_deferred_host_operations
- Name String
-
VK_KHR_deferred_host_operations
- Extension Type
-
Device extension
- Registered Extension Number
-
269
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Josh Barczak jbarczak
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Barczak, Intel
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Slawek Grajewski, Intel
-
Tobias Hector, AMD
-
Yuriy O’Donnell, Epic
-
Eric Werness, NVIDIA
-
Baldur Karlsson, Valve
-
Jesse Barker, Unity
-
Contributors to VK_KHR_acceleration_structure, VK_KHR_ray_tracing_pipeline
-
Description
The VK_KHR_deferred_host_operations extension defines the infrastructure and usage patterns for deferrable commands, but does not specify any commands as deferrable. This is left to additional dependent extensions. Commands must not be deferred unless the deferral is specifically allowed by another extension which depends on VK_KHR_deferred_host_operations.
New Enum Constants
-
VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME
-
VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR
-
-
Extending VkResult:
-
VK_OPERATION_DEFERRED_KHR
-
VK_OPERATION_NOT_DEFERRED_KHR
-
VK_THREAD_DONE_KHR
-
VK_THREAD_IDLE_KHR
-
Code Examples
The following examples will illustrate the concept of deferrable operations
using a hypothetical example.
The command vkDoSomethingExpensiveEXT
denotes a deferrable command.
The structure VkExpensiveOperationArgsEXT
represents the arguments
which it would normally accept.
The following example illustrates how a vulkan application might request deferral of an expensive operation:
// create a deferred operation
VkDeferredOperationKHR hOp;
VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
assert(result == VK_SUCCESS);
result = vkDoSomethingExpensive(device, hOp, ...);
assert( result == VK_OPERATION_DEFERRED_KHR );
// operation was deferred. Execute it asynchronously
std::async::launch(
[ hOp ] ( )
{
vkDeferredOperationJoinKHR(device, hOp);
result = vkGetDeferredOperationResultKHR(device, hOp);
// deferred operation is now complete. 'result' indicates success or failure
vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
}
);
The following example shows a subroutine which guarantees completion of a deferred operation, in the presence of multiple worker threads, and returns the result of the operation.
VkResult FinishDeferredOperation(VkDeferredOperationKHR hOp)
{
// Attempt to join the operation until the implementation indicates that we should stop
VkResult result = vkDeferredOperationJoinKHR(device, hOp);
while( result == VK_THREAD_IDLE_KHR )
{
std::this_thread::yield();
result = vkDeferredOperationJoinKHR(device, hOp);
}
switch( result )
{
case VK_SUCCESS:
{
// deferred operation has finished. Query its result
result = vkGetDeferredOperationResultKHR(device, hOp);
}
break;
case VK_THREAD_DONE_KHR:
{
// deferred operation is being wrapped up by another thread
// wait for that thread to finish
do
{
std::this_thread::yield();
result = vkGetDeferredOperationResultKHR(device, hOp);
} while( result == VK_NOT_READY );
}
break;
default:
assert(false); // other conditions are illegal.
break;
}
return result;
}
Issues
-
Should this entension have a VkPhysicalDevice*FeaturesKHR structure?
RESOLVED: No. This extension does not add any functionality on its own and requires a dependent extension to actually enable functionality and thus there is no value in adding a feature structure. If necessary, any dependent extension could add a feature boolean if it wanted to indicate that it is adding optional deferral support.
Version History
-
Revision 1, 2019-12-05 (Josh Barczak, Daniel Koch)
-
Initial draft.
-
-
Revision 2, 2020-03-06 (Daniel Koch, Tobias Hector)
-
Add missing VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR enum
-
fix sample code
-
Clarified deferred operation parameter lifetimes (#2018,!3647)
-
-
Revision 3, 2020-05-15 (Josh Barczak)
-
Clarify behavior of vkGetDeferredOperationMaxConcurrencyKHR, allowing it to return 0 if the operation is complete (#2036,!3850)
-
-
Revision 4, 2020-11-12 (Tobias Hector, Daniel Koch)
-
Remove VkDeferredOperationInfoKHR and change return value semantics when deferred host operations are in use (#2067,3813)
-
clarify return value of vkGetDeferredOperationResultKHR (#2339,!4110)
-
VK_KHR_display
- Name String
-
VK_KHR_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
3
- Revision
-
23
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
Other Extension Metadata
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Norbert Nopper, Freescale
-
Jeff Vigil, Qualcomm
-
Daniel Rakos, AMD
-
Description
This extension provides the API to enumerate displays and available modes on a given device.
New Enum Constants
-
VK_KHR_DISPLAY_EXTENSION_NAME
-
VK_KHR_DISPLAY_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DISPLAY_KHR
-
VK_OBJECT_TYPE_DISPLAY_MODE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR
-
Issues
1) Which properties of a mode should be fixed in the mode info vs. settable in some other function when setting the mode? E.g., do we need to double the size of the mode pool to include both stereo and non-stereo modes? YUV and RGB scanout even if they both take RGB input images? BGR vs. RGB input? etc.
PROPOSED RESOLUTION: Many modern displays support at most a handful of resolutions and timings natively. Other “modes” are expected to be supported using scaling hardware on the display engine or GPU. Other properties, such as rotation and mirroring should not require duplicating hardware modes just to express all combinations. Further, these properties may be implemented on a per-display or per-overlay granularity.
To avoid the exponential growth of modes as mutable properties are added, as
was the case with EGLConfig
/WGL pixel formats/GLXFBConfig
, this
specification should separate out hardware properties and configurable state
into separate objects.
Modes and overlay planes will express capabilities of the hardware, while a
separate structure will allow applications to configure scaling, rotation,
mirroring, color keys, LUT values, alpha masks, etc.
for a given swapchain independent of the mode in use.
Constraints on these settings will be established by properties of the
immutable objects.
Note the resolution of this issue may affect issue 5 as well.
2) What properties of a display itself are useful?
PROPOSED RESOLUTION: This issue is too broad. It was meant to prompt general discussion, but resolving this issue amounts to completing this specification. All interesting properties should be included. The issue will remain as a placeholder since removing it would make it hard to parse existing discussion notes that refer to issues by number.
3) How are multiple overlay planes within a display or mode enumerated?
PROPOSED RESOLUTION: They are referred to by an index. Each display will report the number of overlay planes it contains.
4) Should swapchains be created relative to a mode or a display?
PROPOSED RESOLUTION: When using this extension, swapchains are created relative to a mode and a plane. The mode implies the display object the swapchain will present to. If the specified mode is not the display’s current mode, the new mode will be applied when the first image is presented to the swapchain, and the default operating system mode, if any, will be restored when the swapchain is destroyed.
5) Should users query generic ranges from displays and construct their own modes explicitly using those constraints rather than querying a fixed set of modes (Most monitors only have one real “mode” these days, even though many support relatively arbitrary scaling, either on the monitor side or in the GPU display engine, making “modes” something of a relic/compatibility construct).
PROPOSED RESOLUTION: Expose both. Display info structures will expose a set of predefined modes, as well as any attributes necessary to construct a customized mode.
6) Is it fine if we return the display and display mode handles in the structure used to query their properties?
PROPOSED RESOLUTION: Yes.
7) Is there a possibility that not all displays of a device work with all of the present queues of a device? If yes, how do we determine which displays work with which present queues?
PROPOSED RESOLUTION: No known hardware has such limitations, but
determining such limitations is supported automatically using the existing
VK_KHR_surface
and VK_KHR_swapchain
query mechanisms.
8) Should all presentation need to be done relative to an overlay plane, or can a display mode + display be used alone to target an output?
PROPOSED RESOLUTION: Require specifying a plane explicitly.
9) Should displays have an associated window system display, such as an
HDC
or Display
*?
PROPOSED RESOLUTION: No.
Displays are independent of any windowing system in use on the system.
Further, neither HDC
nor Display
* refer to a physical display
object.
10) Are displays queried from a physical GPU or from a device instance?
PROPOSED RESOLUTION: Developers prefer to query modes directly from the physical GPU so they can use display information as an input to their device selection algorithms prior to device creation. This avoids the need to create placeholder device instances to enumerate displays.
This preference must be weighed against the extra initialization that must be done by driver vendors prior to device instance creation to support this usage.
11) Should displays and/or modes be dispatchable objects? If functions are to take displays, overlays, or modes as their first parameter, they must be dispatchable objects as defined in Khronos bug 13529. If they are not added to the list of dispatchable objects, functions operating on them must take some higher-level object as their first parameter. There is no performance case against making them dispatchable objects, but they would be the first extension objects to be dispatchable.
PROPOSED RESOLUTION: Do not make displays or modes dispatchable. They will dispatch based on their associated physical device.
12) Should hardware cursor capabilities be exposed?
PROPOSED RESOLUTION: Defer. This could be a separate extension on top of the base WSI specs.
if they are one physical display device to an end user, but may internally be implemented as two side-by-side displays using the same display engine (and sometimes cabling) resources as two physically separate display devices.
RESOLVED: Tiled displays will appear as a single display object in this API.
14) Should the raw EDID data be included in the display information?
RESOLVED: No. A future extension could be added which reports the EDID if necessary. This may be complicated by the outcome of issue 13.
15) Should min and max scaling factor capabilities of overlays be exposed?
RESOLVED: Yes. This is exposed indirectly by allowing applications to query the min/max position and extent of the source and destination regions from which image contents are fetched by the display engine when using a particular mode and overlay pair.
16) Should devices be able to expose planes that can be moved between displays? If so, how?
RESOLVED: Yes. Applications can determine which displays a given plane supports using vkGetDisplayPlaneSupportedDisplaysKHR.
17) Should there be a way to destroy display modes? If so, does it support destroying “built in” modes?
RESOLVED: Not in this extension. A future extension could add this functionality.
18) What should the lifetime of display and built-in display mode objects be?
RESOLVED: The lifetime of the instance. These objects cannot be destroyed. A future extension may be added to expose a way to destroy these objects and/or support display hotplug.
19) Should persistent mode for smart panels be enabled/disabled at swapchain creation time, or on a per-present basis.
RESOLVED: On a per-present basis.
Examples
Note
The example code for the |
Version History
-
Revision 1, 2015-02-24 (James Jones)
-
Initial draft
-
-
Revision 2, 2015-03-12 (Norbert Nopper)
-
Added overlay enumeration for a display.
-
-
Revision 3, 2015-03-17 (Norbert Nopper)
-
Fixed typos and namings as discussed in Bugzilla.
-
Reordered and grouped functions.
-
Added functions to query count of display, mode and overlay.
-
Added native display handle, which is maybe needed on some platforms to create a native Window.
-
-
Revision 4, 2015-03-18 (Norbert Nopper)
-
Removed primary and virtualPostion members (see comment of James Jones in Bugzilla).
-
Added native overlay handle to info structure.
-
Replaced , with ; in struct.
-
-
Revision 6, 2015-03-18 (Daniel Rakos)
-
Added WSI extension suffix to all items.
-
Made the whole API more "Vulkanish".
-
Replaced all functions with a single vkGetDisplayInfoKHR function to better match the rest of the API.
-
Made the display, display mode, and overlay objects be first class objects, not subclasses of VkBaseObject as they do not support the common functions anyways.
-
Renamed *Info structures to *Properties.
-
Removed overlayIndex field from VkOverlayProperties as there is an implicit index already as a result of moving to a "Vulkanish" API.
-
Displays are not get through device, but through physical GPU to match the rest of the Vulkan API. Also this is something ISVs explicitly requested.
-
Added issue (6) and (7).
-
-
Revision 7, 2015-03-25 (James Jones)
-
Added an issues section
-
Added rotation and mirroring flags
-
-
Revision 8, 2015-03-25 (James Jones)
-
Combined the duplicate issues sections introduced in last change.
-
Added proposed resolutions to several issues.
-
-
Revision 9, 2015-04-01 (Daniel Rakos)
-
Rebased extension against Vulkan 0.82.0
-
-
Revision 10, 2015-04-01 (James Jones)
-
Added issues (10) and (11).
-
Added more straw-man issue resolutions, and cleaned up the proposed resolution for issue (4).
-
Updated the rotation and mirroring enums to have proper bitmask semantics.
-
-
Revision 11, 2015-04-15 (James Jones)
-
Added proposed resolution for issues (1) and (2).
-
Added issues (12), (13), (14), and (15)
-
Removed pNativeHandle field from overlay structure.
-
Fixed small compilation errors in example code.
-
-
Revision 12, 2015-07-29 (James Jones)
-
Rewrote the guts of the extension against the latest WSI swapchain specifications and the latest Vulkan API.
-
Address overlay planes by their index rather than an object handle and refer to them as "planes" rather than "overlays" to make it slightly clearer that even a display with no "overlays" still has at least one base "plane" that images can be displayed on.
-
Updated most of the issues.
-
Added an "extension type" section to the specification header.
-
Re-used the VK_EXT_KHR_surface surface transform enumerations rather than redefining them here.
-
Updated the example code to use the new semantics.
-
-
Revision 13, 2015-08-21 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.
-
-
Revision 14, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 15, 2015-09-08 (James Jones)
-
Added alpha flags enum.
-
Added premultiplied alpha support.
-
-
Revision 16, 2015-09-08 (James Jones)
-
Added description section to the spec.
-
Added issues 16 - 18.
-
-
Revision 17, 2015-10-02 (James Jones)
-
Planes are now a property of the entire device rather than individual displays. This allows planes to be moved between multiple displays on devices that support it.
-
Added a function to create a VkSurfaceKHR object describing a display plane and mode to align with the new per-platform surface creation conventions.
-
Removed detailed mode timing data. It was agreed that the mode extents and refresh rate are sufficient for current use cases. Other information could be added back2 in as an extension if it is needed in the future.
-
Added support for smart/persistent/buffered display devices.
-
-
Revision 18, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_display to VK_KHR_display.
-
-
Revision 19, 2015-11-02 (James Jones)
-
Updated example code to match revision 17 changes.
-
-
Revision 20, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to creation functions.
-
-
Revision 21, 2015-11-10 (Jesse Hall)
-
Added VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR, and use VkDisplayPlaneAlphaFlagBitsKHR for VkDisplayPlanePropertiesKHR::alphaMode instead of VkDisplayPlaneAlphaFlagsKHR, since it only represents one mode.
-
Added reserved flags bitmask to VkDisplayPlanePropertiesKHR.
-
Use VkSurfaceTransformFlagBitsKHR instead of obsolete VkSurfaceTransformKHR.
-
Renamed vkGetDisplayPlaneSupportedDisplaysKHR parameters for clarity.
-
-
Revision 22, 2015-12-18 (James Jones)
-
Added missing "planeIndex" parameter to vkGetDisplayPlaneSupportedDisplaysKHR()
-
-
Revision 23, 2017-03-13 (James Jones)
-
Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.
-
Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.
-
VK_KHR_display_swapchain
- Name String
-
VK_KHR_display_swapchain
- Extension Type
-
Device extension
- Registered Extension Number
-
4
- Revision
-
10
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-03-13
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Vigil, Qualcomm
-
Jesse Hall, Google
-
Description
This extension provides an API to create a swapchain directly on a device’s display without any underlying window system.
New Structures
-
Extending VkPresentInfoKHR:
New Enum Constants
-
VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME
-
VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION
-
Extending VkResult:
-
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
-
Issues
1) Should swapchains sharing images each hold a reference to the images, or should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting?
RESOLVED: Take a reference. The lifetime of presentable images is already complex enough.
2) Should the srcRect
and dstRect
parameters be specified as
part of the present command, or at swapchain creation time?
RESOLVED: As part of the presentation command. This allows moving and scaling the image on the screen without the need to respecify the mode or create a new swapchain and presentable images.
3) Should srcRect
and dstRect
be specified as rects, or separate
offset/extent values?
RESOLVED: As rects. Specifying them separately might make it easier for hardware to expose support for one but not the other, but in such cases applications must just take care to obey the reported capabilities and not use non-zero offsets or extents that require scaling, as appropriate.
4) How can applications create multiple swapchains that use the same images?
RESOLVED: By calling vkCreateSharedSwapchainsKHR.
An earlier resolution used vkCreateSwapchainKHR, chaining multiple
VkSwapchainCreateInfoKHR structures through pNext
.
In order to allow each swapchain to also allow other extension structs, a
level of indirection was used: VkSwapchainCreateInfoKHR::pNext
pointed to a different structure, which had both sType
and pNext
members for additional extensions, and also had a pointer to the next
VkSwapchainCreateInfoKHR structure.
The number of swapchains to be created could only be found by walking this
linked list of alternating structures, and the pSwapchains
out
parameter was reinterpreted to be an array of VkSwapchainKHR handles.
Another option considered was a method to specify a “shared” swapchain when creating a new swapchain, such that groups of swapchains using the same images could be built up one at a time. This was deemed unusable because drivers need to know all of the displays an image will be used on when determining which internal formats and layouts to use for that image.
Examples
Note
The example code for the |
Version History
-
Revision 1, 2015-07-29 (James Jones)
-
Initial draft
-
-
Revision 2, 2015-08-21 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.
-
-
Revision 3, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 4, 2015-09-08 (James Jones)
-
Allow creating multiple swap chains that share the same images using a single call to vkCreateSwapChainKHR().
-
-
Revision 5, 2015-09-10 (Alon Or-bach)
-
Removed underscores from SWAP_CHAIN in two enums.
-
-
Revision 6, 2015-10-02 (James Jones)
-
Added support for smart panels/buffered displays.
-
-
Revision 7, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.
-
-
Revision 8, 2015-11-03 (Daniel Rakos)
-
Updated sample code based on the changes to VK_KHR_swapchain.
-
-
Revision 9, 2015-11-10 (Jesse Hall)
-
Replaced VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
-
-
Revision 10, 2017-03-13 (James Jones)
-
Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.
-
Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.
-
VK_KHR_external_fence_fd
- Name String
-
VK_KHR_external_fence_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
116
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_fence
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_fd
-
Description
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from POSIX file descriptors.
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_FD_EXTENSION_NAME
-
VK_KHR_EXTERNAL_FENCE_FD_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FENCE_GET_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_IMPORT_FENCE_FD_INFO_KHR
-
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_fd
.
That extension’s issues apply equally to this extension.
VK_KHR_external_fence_win32
- Name String
-
VK_KHR_external_fence_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
115
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_fence
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2017-05-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Cass Everitt, Oculus
-
Contributors to
VK_KHR_external_semaphore_win32
-
Description
An application using external memory may wish to synchronize access to that memory using fences. This extension enables an application to export fence payload to and import fence payload from Windows handles.
New Enum Constants
-
VK_KHR_EXTERNAL_FENCE_WIN32_EXTENSION_NAME
-
VK_KHR_EXTERNAL_FENCE_WIN32_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_FENCE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_FENCE_GET_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_IMPORT_FENCE_WIN32_HANDLE_INFO_KHR
-
Issues
This extension borrows concepts, semantics, and language from
VK_KHR_external_semaphore_win32
.
That extension’s issues apply equally to this extension.
1) Should D3D12 fence handle types be supported, like they are for semaphores?
RESOLVED: No.
Doing so would require extending the fence signal and wait operations to
provide values to signal / wait for, like VkD3D12FenceSubmitInfoKHR
does.
A D3D12 fence can be signaled by importing it into a VkSemaphore
instead of a VkFence, and applications can check status or wait on the
D3D12 fence using non-Vulkan APIs.
The convenience of being able to do these operations on VkFence
objects doesn’t justify the extra API complexity.
VK_KHR_external_memory_fd
- Name String
-
VK_KHR_external_memory_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
75
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export POSIX file descriptor handles from Vulkan memory objects and to import Vulkan memory objects from POSIX file descriptor handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME
-
VK_KHR_EXTERNAL_MEMORY_FD_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_FD_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR
-
Issues
1) Does the application need to close the file descriptor returned by vkGetMemoryFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the memory. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original memory object will not close the file descriptor or remove its reference to the underlying memory resource associated with it.
2) Do drivers ever need to expose multiple file descriptors per memory object?
RESOLVED: No. This would indicate there are actually multiple memory objects, rather than a single memory object.
3) How should the valid size and memory type for POSIX file descriptor memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size will be specified by future extensions that introduce such external memory handle types.
VK_KHR_external_memory_win32
- Name String
-
VK_KHR_external_memory_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
74
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application may wish to reference device memory in multiple Vulkan logical devices or instances, in multiple processes, and/or in multiple APIs. This extension enables an application to export Windows handles from Vulkan memory objects and to import Vulkan memory objects from Windows handles exported from other Vulkan memory objects or from similar resources in other APIs.
New Enum Constants
-
VK_KHR_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME
-
VK_KHR_EXTERNAL_MEMORY_WIN32_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_GET_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_MEMORY_WIN32_HANDLE_PROPERTIES_KHR
-
Issues
1) Do applications need to call CloseHandle
() on the values returned
from vkGetMemoryWin32HandleKHR when handleType
is
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR
?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) How should the valid size and memory type for windows memory handles created outside of Vulkan be specified?
RESOLVED: The valid memory types are queried directly from the external handle. The size is determined by the associated image or buffer memory requirements for external handle types that require dedicated allocations, and by the size specified when creating the object from which the handle was exported for other external handle types.
VK_KHR_external_semaphore_fd
- Name String
-
VK_KHR_external_semaphore_fd
- Extension Type
-
Device extension
- Registered Extension Number
-
80
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_semaphore
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from POSIX file descriptors.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME
-
VK_KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR
-
Issues
1) Does the application need to close the file descriptor returned by vkGetSemaphoreFdKHR?
RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the file descriptor or remove its reference to the underlying semaphore resource associated with it.
VK_KHR_external_semaphore_win32
- Name String
-
VK_KHR_external_semaphore_win32
- Extension Type
-
Device extension
- Registered Extension Number
-
79
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_semaphore
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from Windows handles.
New Enum Constants
-
VK_KHR_EXTERNAL_SEMAPHORE_WIN32_EXTENSION_NAME
-
VK_KHR_EXTERNAL_SEMAPHORE_WIN32_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_D3D12_FENCE_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_EXPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_IMPORT_SEMAPHORE_WIN32_HANDLE_INFO_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_GET_WIN32_HANDLE_INFO_KHR
-
Issues
1) Do applications need to call CloseHandle
() on the values returned
from vkGetSemaphoreWin32HandleKHR when handleType
is
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR
?
RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application. Destroying the semaphore object will not destroy the handle or the handle’s reference to the underlying semaphore resource.
2) Should the language regarding KMT/Windows 7 handles be moved to a separate extension so that it can be deprecated over time?
RESOLVED: No. Support for them can be deprecated by drivers if they choose, by no longer returning them in the supported handle types of the instance level queries.
3) Should applications be allowed to specify additional object attributes for shared handles?
RESOLVED: Yes. Applications will be allowed to provide similar attributes to those they would to any other handle creation API.
4) How do applications communicate the desired fence values to use with
D3D12_FENCE
-based Vulkan semaphores?
RESOLVED: There are a couple of options. The values for the signaled and reset states could be communicated up front when creating the object and remain static for the life of the Vulkan semaphore, or they could be specified using auxiliary structures when submitting semaphore signal and wait operations, similar to what is done with the keyed mutex extensions. The latter is more flexible and consistent with the keyed mutex usage, but the former is a much simpler API.
Since Vulkan tends to favor flexibility and consistency over simplicity, a new structure specifying D3D12 fence acquire and release values is added to the vkQueueSubmit function.
VK_KHR_fragment_shading_rate
- Name String
-
VK_KHR_fragment_shading_rate
- Extension Type
-
Device extension
- Registered Extension Number
-
227
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-05-06
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_fragment_shading_rate
.
-
- Contributors
-
-
Tobias Hector, AMD
-
Guennadi Riguer, AMD
-
Matthaeus Chajdas, AMD
-
Pat Brown, Nvidia
-
Matthew Netsch, Qualcomm
-
Slawomir Grajewski, Intel
-
Jan-Harald Fredriksen, Arm
-
Jeff Bolz, Nvidia
-
Contributors to the VK_NV_shading_rate_image specification
-
Contributors to the VK_EXT_fragment_density_map specification
-
Description
This extension adds the ability to change the rate at which fragments are shaded. Rather than the usual single fragment invocation for each pixel covered by a primitive, multiple pixels can be shaded by a single fragment shader invocation.
Up to three methods are available to the application to change the fragment shading rate:
-
Pipeline Fragment Shading Rate, which allows the specification of a rate per-draw.
-
Primitive Fragment Shading Rate, which allows the specification of a rate per primitive, specified during shading.
-
Attachment Fragment Shading Rate, which allows the specification of a rate per-region of the framebuffer, specified in a specialized image attachment.
Additionally, these rates can all be specified and combined in order to adjust the overall detail in the image at each point.
This functionality can be used to focus shading efforts where higher levels of detail are needed in some parts of a scene compared to others. This can be particularly useful in high resolution rendering, or for XR contexts.
This extension also adds support for the SPV_KHR_fragment_shading_rate
extension which enables setting the
primitive fragment shading
rate, and allows querying the final shading rate from a fragment shader.
New Structures
-
Extending VkGraphicsPipelineCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkSubpassDescription2:
New Enum Constants
-
VK_KHR_FRAGMENT_SHADING_RATE_EXTENSION_NAME
-
VK_KHR_FRAGMENT_SHADING_RATE_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FRAGMENT_SHADING_RATE_ATTACHMENT_INFO_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_STATE_CREATE_INFO_KHR
-
VK_KHR_get_display_properties2
- Name String
-
VK_KHR_get_display_properties2
- Extension Type
-
Instance extension
- Registered Extension Number
-
122
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-02-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
Description
This extension provides new entry points to query device display properties
and capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_display
equivalent of the
VK_KHR_get_physical_device_properties2
extension.
New Enum Constants
-
VK_KHR_GET_DISPLAY_PROPERTIES_2_EXTENSION_NAME
-
VK_KHR_GET_DISPLAY_PROPERTIES_2_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR
-
VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR
-
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_display_properties2
.
Other alternatives:
-
VK_KHR_display2
-
One extension, combined with
VK_KHR_surface_capabilites2
.
2) Should extensible input structs be added for these new functions:
RESOLVED:
-
vkGetPhysicalDeviceDisplayProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs wouldn’t make sense.
-
vkGetPhysicalDeviceDisplayPlaneProperties2KHR: No. The only current input is a VkPhysicalDevice. Other inputs wouldn’t make sense.
-
vkGetDisplayModeProperties2KHR: No. The only current inputs are a VkPhysicalDevice and a VkDisplayModeKHR. Other inputs wouldn’t make sense.
3) Should additional display query functions be extended?
RESOLVED:
-
vkGetDisplayPlaneSupportedDisplaysKHR: No. Extensions should instead extend vkGetDisplayPlaneCapabilitiesKHR().
VK_KHR_get_surface_capabilities2
- Name String
-
VK_KHR_get_surface_capabilities2
- Extension Type
-
Instance extension
- Registered Extension Number
-
120
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2017-02-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
James Jones, NVIDIA
-
Alon Or-bach, Samsung
-
Description
This extension provides new entry points to query device surface
capabilities in a way that can be easily extended by other extensions,
without introducing any further entry points.
This extension can be considered the VK_KHR_surface
equivalent of the
VK_KHR_get_physical_device_properties2
extension.
New Enum Constants
-
VK_KHR_GET_SURFACE_CAPABILITIES_2_EXTENSION_NAME
-
VK_KHR_GET_SURFACE_CAPABILITIES_2_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_KHR
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_KHR
-
VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR
-
Issues
1) What should this extension be named?
RESOLVED: VK_KHR_get_surface_capabilities2
.
Other alternatives:
-
VK_KHR_surface2
-
One extension, combining a separate display-specific query extension.
2) Should additional WSI query functions be extended?
RESOLVED:
-
vkGetPhysicalDeviceSurfaceCapabilitiesKHR: Yes. The need for this motivated the extension.
-
vkGetPhysicalDeviceSurfaceSupportKHR: No. Currently only has boolean output. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceSurfacePresentModesKHR: No. Recent discussion concluded this introduced too much variability for applications to deal with. Extensions should instead extend vkGetPhysicalDeviceSurfaceCapabilities2KHR.
-
vkGetPhysicalDeviceXlibPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceXcbPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWaylandPresentationSupportKHR: Not in this extension.
-
vkGetPhysicalDeviceWin32PresentationSupportKHR: Not in this extension.
VK_KHR_incremental_present
- Name String
-
VK_KHR_incremental_present
- Extension Type
-
Device extension
- Registered Extension Number
-
85
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2016-11-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Alon Or-bach, Samsung
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Mika Isojarvi, Google
-
Jeff Juliano, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This device extension extends vkQueuePresentKHR, from the
VK_KHR_swapchain
extension, allowing an application to specify a list
of rectangular, modified regions of each image to present.
This should be used in situations where an application is only changing a
small portion of the presentable images within a swapchain, since it enables
the presentation engine to avoid wasting time presenting parts of the
surface that have not changed.
This extension is leveraged from the EGL_KHR_swap_buffers_with_damage
extension.
New Enum Constants
-
VK_KHR_INCREMENTAL_PRESENT_EXTENSION_NAME
-
VK_KHR_INCREMENTAL_PRESENT_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR
-
Issues
1) How should we handle steroescopic-3D swapchains? We need to add a layer
for each rectangle.
One approach is to create another struct containing the VkRect2D plus
layer, and have VkPresentRegionsKHR point to an array of that struct.
Another approach is to have two parallel arrays, pRectangles
and
pLayers
, where pRectangles
[i] and pLayers
[i] must be used
together.
Which approach should we use, and if the array of a new structure, what
should that be called?
RESOLVED: Create a new structure, which is a VkRect2D plus a layer, and will be called VkRectLayerKHR.
2) Where is the origin of the VkRectLayerKHR?
RESOLVED: The upper left corner of the presentable image(s) of the swapchain, per the definition of framebuffer coordinates.
3) Does the rectangular region, VkRectLayerKHR, specify pixels of the swapchain’s image(s), or of the surface?
RESOLVED: Of the image(s). Some presentation engines may scale the pixels of a swapchain’s image(s) to the size of the surface. The size of the swapchain’s image(s) will be consistent, where the size of the surface may vary over time.
4) What if all of the rectangles for a given swapchain contain a width and/or height of zero?
RESOLVED: The application is indicating that no pixels changed since the last present. The presentation engine may use such a hint and not update any pixels for the swapchain. However, all other semantics of vkQueuePresentKHR must still be honored, including waiting for semaphores to signal.
VK_KHR_performance_query
- Name String
-
VK_KHR_performance_query
- Extension Type
-
Device extension
- Registered Extension Number
-
117
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Alon Or-bach alonorbach
-
Other Extension Metadata
- Last Modified Date
-
2019-10-08
- IP Status
-
No known IP claims.
- Contributors
-
-
Jesse Barker, Unity Technologies
-
Kenneth Benzie, Codeplay
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm
-
Jesse Hall, Google
-
Tobias Hector, AMD
-
Neil Henning, Codeplay
-
Baldur Karlsson
-
Lionel Landwerlin, Intel
-
Peter Lohrmann, AMD
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Niklas Smedberg, Unity Technologies
-
Igor Ostrowski, Intel
-
Description
The VK_KHR_performance_query
extension adds a mechanism to allow querying
of performance counters for use in applications and by profiling tools.
Each queue family may expose counters that can be enabled on a queue of that family. We extend VkQueryType to add a new query type for performance queries, and chain a structure on VkQueryPoolCreateInfo to specify the performance queries to enable.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkQueryPoolCreateInfo:
-
Extending VkSubmitInfo, VkSubmitInfo2KHR:
New Enum Constants
-
VK_KHR_PERFORMANCE_QUERY_EXTENSION_NAME
-
VK_KHR_PERFORMANCE_QUERY_SPEC_VERSION
-
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_DESCRIPTION_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_COUNTER_KHR
-
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PERFORMANCE_QUERY_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR
-
Issues
1) Should this extension include a mechanism to begin a query in command buffer A and end the query in command buffer B?
RESOLVED No - queries are tied to command buffer creation and thus have to be encapsulated within a single command buffer.
2) Should this extension include a mechanism to begin and end queries globally on the queue, not using the existing command buffer commands?
RESOLVED No - for the same reasoning as the resolution of 1).
3) Should this extension expose counters that require multiple passes?
RESOLVED Yes - users should re-submit a command buffer with the same commands in it multiple times, specifying the pass to count as the query parameter in VkPerformanceQuerySubmitInfoKHR.
4) How to handle counters across parallel workloads?
RESOLVED In the spirit of Vulkan, a counter description flag
VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR
denotes that the accuracy of a counter result is affected by parallel
workloads.
5) How to handle secondary command buffers?
RESOLVED Secondary command buffers inherit any counter pass index specified in the parent primary command buffer. Note: this is no longer an issue after change from issue 10 resolution
6) What commands does the profiling lock have to be held for?
RESOLVED For any command buffer that is being queried with a performance query pool, the profiling lock must be held while that command buffer is in the recording, executable, or pending state.
7) Should we support vkCmdCopyQueryPoolResults?
RESOLVED Yes.
8) Should we allow performance queries to interact with multiview?
RESOLVED Yes, but the performance queries must be performed once for each pass per view.
9) Should a queryCount > 1
be usable for performance queries?
RESOLVED Yes.
Some vendors will have costly performance counter query pool creation, and
would rather if a certain set of counters were to be used multiple times
that a queryCount > 1
can be used to amortize the instantiation cost.
10) Should we introduce an indirect mechanism to set the counter pass index?
RESOLVED Specify the counter pass index at submit time instead to avoid requiring re-recording of command buffers when multiple counter passes needed.
Examples
The following example shows how to find what performance counters a queue family supports, setup a query pool to record these performance counters, how to add the query pool to the command buffer to record information, and how to get the results from the query pool.
// A previously created physical device
VkPhysicalDevice physicalDevice;
// One of the queue families our device supports
uint32_t queueFamilyIndex;
uint32_t counterCount;
// Get the count of counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
NULL,
NULL);
VkPerformanceCounterKHR* counters =
malloc(sizeof(VkPerformanceCounterKHR) * counterCount);
VkPerformanceCounterDescriptionKHR* counterDescriptions =
malloc(sizeof(VkPerformanceCounterDescriptionKHR) * counterCount);
// Get the counters supported
vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR(
physicalDevice,
queueFamilyIndex,
&counterCount,
counters,
counterDescriptions);
// Try to enable the first 8 counters
uint32_t enabledCounters[8];
const uint32_t enabledCounterCount = min(counterCount, 8));
for (uint32_t i = 0; i < enabledCounterCount; i++) {
enabledCounters[i] = i;
}
// A previously created device that had the performanceCounterQueryPools feature
// set to VK_TRUE
VkDevice device;
VkQueryPoolPerformanceCreateInfoKHR performanceQueryCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_CREATE_INFO_KHR,
NULL,
// Specify the queue family that this performance query is performed on
queueFamilyIndex,
// The number of counters to enable
enabledCounterCount,
// The array of indices of counters to enable
enabledCounters
};
// Get the number of passes our counters will require.
uint32_t numPasses;
vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR(
physicalDevice,
&performanceQueryCreateInfo,
&numPasses);
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&performanceQueryCreateInfo,
0,
// Using our new query type here
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A queue from queueFamilyIndex
VkQueue queue;
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
0,
NULL
};
VkAcquireProfilingLockInfoKHR lockInfo = {
VK_STRUCTURE_TYPE_ACQUIRE_PROFILING_LOCK_INFO_KHR,
NULL,
0,
UINT64_MAX // Wait forever for the lock
};
// Acquire the profiling lock before we record command buffers
// that will use performance queries
result = vkAcquireProfilingLockKHR(device, &lockInfo);
assert(VK_SUCCESS == result);
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
// ...
// Perform a barrier to ensure all previous commands were complete before
// ending the query
vkCmdPipelineBarrier(commandBuffer,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
0,
0,
NULL,
0,
NULL,
0,
NULL);
vkCmdEndQuery(
commandBuffer,
queryPool,
0);
result = vkEndCommandBuffer(commandBuffer);
assert(VK_SUCCESS == result);
for (uint32_t counterPass = 0; counterPass < numPasses; counterPass++) {
VkPerformanceQuerySubmitInfoKHR performanceQuerySubmitInfo = {
VK_STRUCTURE_TYPE_PERFORMANCE_QUERY_SUBMIT_INFO_KHR,
NULL,
counterPass
};
// Submit the command buffer and wait for its completion
// ...
}
// Release the profiling lock after the command buffer is no longer in the
// pending state.
vkReleaseProfilingLockKHR(device);
result = vkResetCommandBuffer(commandBuffer, 0);
assert(VK_SUCCESS == result);
// Create an array to hold the results of all counters
VkPerformanceCounterResultKHR* recordedCounters = malloc(
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount);
result = vkGetQueryPoolResults(
device,
queryPool,
0,
1,
sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount,
recordedCounters,
sizeof(VkPerformanceCounterResultKHR),
NULL);
// recordedCounters is filled with our counters, we'll look at one for posterity
switch (counters[0].storage) {
case VK_PERFORMANCE_COUNTER_STORAGE_INT32:
// use recordCounters[0].int32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_INT64:
// use recordCounters[0].int64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT32:
// use recordCounters[0].uint32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_UINT64:
// use recordCounters[0].uint64 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32:
// use recordCounters[0].float32 to get at the counter result!
break;
case VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64:
// use recordCounters[0].float64 to get at the counter result!
break;
}
VK_KHR_pipeline_executable_properties
- Name String
-
VK_KHR_pipeline_executable_properties
- Extension Type
-
Device extension
- Registered Extension Number
-
270
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Jason Ekstrand jekstrand
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Jason Ekstrand, Intel
-
Ian Romanick, Intel
-
Kenneth Graunke, Intel
-
Baldur Karlsson, Valve
-
Jesse Hall, Google
-
Jeff Bolz, Nvidia
-
Piers Daniel, Nvidia
-
Tobias Hector, AMD
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Daniel Koch, Nvidia
-
Spencer Fricke, Samsung
-
Description
When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. This extension adds a mechanism to query properties and statistics about the different executables produced by the pipeline compilation process. This is intended to be used by debugging and performance tools to allow them to provide more detailed information to the user. Certain compile-time shader statistics provided through this extension may be useful to developers for debugging or performance analysis.
New Enum Constants
-
VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_EXTENSION_NAME
-
VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_SPEC_VERSION
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
-
VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR
-
VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR
-
Issues
1) What should we call the pieces of the pipeline which are produced by the compilation process and about which you can query properties and statistics?
RESOLVED: Call them "executables". The name "binary" was used in early drafts of the extension but it was determined that "pipeline binary" could have a fairly broad meaning (such as a binary serialized form of an entire pipeline) and was too big of a namespace for the very specific needs of this extension.
VK_KHR_pipeline_library
- Name String
-
VK_KHR_pipeline_library
- Extension Type
-
Device extension
- Registered Extension Number
-
291
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Christoph Kubisch pixeljetstream
-
Other Extension Metadata
- Last Modified Date
-
2020-01-08
- IP Status
-
No known IP claims.
- Contributors
-
-
See contributors to
VK_KHR_ray_tracing
-
Description
A pipeline library is a special pipeline that cannot be bound, instead it defines a set of shaders and shader groups which can be linked into other pipelines. This extension defines the infrastructure for pipeline libraries, but does not specify the creation or usage of pipeline libraries. This is left to additional dependent extensions.
New Enum Constants
-
VK_KHR_PIPELINE_LIBRARY_EXTENSION_NAME
-
VK_KHR_PIPELINE_LIBRARY_SPEC_VERSION
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR
-
VK_KHR_push_descriptor
- Name String
-
VK_KHR_push_descriptor
- Extension Type
-
Device extension
- Registered Extension Number
-
81
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2017-09-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Michael Worcester, Imagination Technologies
-
Description
This extension allows descriptors to be written into the command buffer, while the implementation is responsible for managing their memory. Push descriptors may enable easier porting from older APIs and in some cases can be more efficient than writing descriptors into descriptor sets.
New Enum Constants
-
VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME
-
VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION
-
Extending VkDescriptorSetLayoutCreateFlagBits:
-
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR
-
If VK_KHR_descriptor_update_template is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
If Version 1.1 is supported:
-
Extending VkDescriptorUpdateTemplateType:
-
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
-
Version History
-
Revision 1, 2016-10-15 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-09-12 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
VK_KHR_ray_query
- Name String
-
VK_KHR_ray_query
- Extension Type
-
Device extension
- Registered Extension Number
-
349
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_KHR_spirv_1_4
-
Requires
VK_KHR_acceleration_structure
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_ray_query
-
This extension provides API support for
GLSL_EXT_ray_query
-
- Contributors
-
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Spencer Fricke, Samsung
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
Ray queries are available to all shader types, including graphics, compute and ray tracing pipelines. Ray queries are not able to launch additional shaders, instead returning traversal results to the calling shader.
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_ray_query
New Enum Constants
-
VK_KHR_RAY_QUERY_EXTENSION_NAME
-
VK_KHR_RAY_QUERY_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_QUERY_FEATURES_KHR
-
Sample Code
Example of ray query in a GLSL shader
rayQueryEXT rq;
rayQueryInitializeEXT(rq, accStruct, gl_RayFlagsNoneEXT, 0, origin, tMin, direction, tMax);
while(rayQueryProceedEXT(rq)) {
if (rayQueryGetIntersectionTypeEXT(rq, false) == gl_RayQueryCandidateIntersectionTriangleEXT) {
//...
rayQueryConfirmIntersectionEXT(rq);
}
}
if (rayQueryGetIntersectionTypeEXT(rq, true) == gl_RayQueryCommittedIntersectionNoneEXT) {
//...
}
Issues
(1) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the final (VK_KHR_acceleration_structure v11 / VK_KHR_ray_query v1) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure (for acceleration structure operations)
-
VK_KHR_ray_tracing_pipeline (for ray tracing pipeline and shader stages)
-
VK_KHR_ray_query (for ray queries in existing shader stages)
-
-
Update SPIRV capabilities to use
RayQueryKHR
-
extension is no longer provisional
Version History
-
Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Andrew Garrard)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_ray_query (#1918,!3912)
-
update to use
RayQueryKHR
SPIR-V capability -
add numerical limits for ray parameters (#2235,!3960)
-
relax formula for ray intersection candidate determination (#2322,!4080)
-
restrict traces to TLAS (#2239,!4141)
-
require
HitT
to be in ray interval forOpRayQueryGenerateIntersectionKHR
(#2359,!4146) -
add ray query shader stages for AS read bit (#2407,!4203)
-
VK_KHR_ray_tracing_pipeline
- Name String
-
VK_KHR_ray_tracing_pipeline
- Extension Type
-
Device extension
- Registered Extension Number
-
348
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_KHR_spirv_1_4
-
Requires
VK_KHR_acceleration_structure
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2020-11-12
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_ray_tracing
-
This extension provides API support for
GLSL_EXT_ray_tracing
-
This extension interacts with Vulkan 1.2 and VK_KHR_vulkan_memory_model, adding the shader-call-related relation of invocations, shader-call-order partial order of dynamic instances of instructions, and the
ShaderCallKHR
scope. -
This extension interacts with VK_KHR_pipeline_library, enabling pipeline libraries to be used with ray tracing pipelines and enabling usage of VkRayTracingPipelineInterfaceCreateInfoKHR.
-
- Contributors
-
-
Matthäus Chajdas, AMD
-
Greg Grebe, AMD
-
Nicolai Hähnle, AMD
-
Tobias Hector, AMD
-
Dave Oldcorn, AMD
-
Skyler Saleh, AMD
-
Mathieu Robart, Arm
-
Marius Bjorge, Arm
-
Tom Olson, Arm
-
Sebastian Tafuri, EA
-
Henrik Rydgard, Embark
-
Juan Cañada, Epic Games
-
Patrick Kelly, Epic Games
-
Yuriy O’Donnell, Epic Games
-
Michael Doggett, Facebook/Oculus
-
Andrew Garrard, Imagination
-
Don Scorgie, Imagination
-
Dae Kim, Imagination
-
Joshua Barczak, Intel
-
Slawek Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Pascal Gautron, NVIDIA
-
Daniel Koch, NVIDIA
-
Christoph Kubisch, NVIDIA
-
Ashwin Lele, NVIDIA
-
Robert Stepinski, NVIDIA
-
Martin Stich, NVIDIA
-
Nuno Subtil, NVIDIA
-
Eric Werness, NVIDIA
-
Jon Leech, Khronos
-
Jeroen van Schijndel, OTOY
-
Juul Joosten, OTOY
-
Alex Bourd, Qualcomm
-
Roman Larionov, Qualcomm
-
David McAllister, Qualcomm
-
Spencer Fricke, Samsung
-
Lewis Gordon, Samsung
-
Ralph Potter, Samsung
-
Jasper Bekkers, Traverse Research
-
Jesse Barker, Unity
-
Baldur Karlsson, Valve
-
Description
Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.
To enable ray tracing, this extension adds a few different categories of new functionality:
-
A new ray tracing pipeline type with new shader domains: ray generation, intersection, any-hit, closest hit, miss, and callable
-
A shader binding indirection table to link shader groups with acceleration structure items
-
Trace ray commands which initiates the ray pipeline traversal and invocation of the various new shader domains depending on which traversal conditions are met
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_ray_tracing
New Enum Constants
-
VK_KHR_RAY_TRACING_PIPELINE_EXTENSION_NAME
-
VK_KHR_RAY_TRACING_PIPELINE_SPEC_VERSION
-
VK_SHADER_UNUSED_KHR
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR
-
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
-
-
Extending VkPipelineBindPoint:
-
VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
-
VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR
-
-
Extending VkShaderStageFlagBits:
-
VK_SHADER_STAGE_ANY_HIT_BIT_KHR
-
VK_SHADER_STAGE_CALLABLE_BIT_KHR
-
VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR
-
VK_SHADER_STAGE_INTERSECTION_BIT_KHR
-
VK_SHADER_STAGE_MISS_BIT_KHR
-
VK_SHADER_STAGE_RAYGEN_BIT_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_FEATURES_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_PROPERTIES_KHR
-
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR
-
Issues
(1) How does this extension differ from VK_NV_ray_tracing?
DISCUSSION:
The following is a summary of the main functional differences between VK_KHR_ray_tracing_pipeline and VK_NV_ray_tracing:
-
added support for indirect ray tracing (vkCmdTraceRaysIndirectKHR)
-
uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing
-
refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are functionally equivalent and aliased to the same values).
-
added
RayGeometryIndexKHR
built-in
-
-
removed vkCompileDeferredNV compilation functionality and replaced with deferred host operations interactions for ray tracing
-
added VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure
-
extended VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure
-
renamed
maxRecursionDepth
tomaxRayRecursionDepth
and it has a minimum of 1 instead of 31 -
require
shaderGroupHandleSize
to be 32 bytes -
added
maxRayDispatchInvocationCount
,shaderGroupHandleAlignment
andmaxRayHitAttributeSize
-
-
reworked geometry structures so they could be better shared between device, host, and indirect builds
-
changed SBT parameters to a structure and added size (VkStridedDeviceAddressRegionKHR)
-
add parameter for requesting memory requirements for host and/or device build
-
added pipeline library support for ray tracing
-
added no-null-shader pipeline flags (
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR
) -
added memory model interactions with ray tracing and define how subgroups work and can be repacked
(2) Can you give a more detailed comparision of differences and similarities between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline?
DISCUSSION:
The following is a more detailed comparision of which commands, structures, and enums are aliased, changed, or removed.
-
Aliased functionality — enums, structures, and commands that are considered equivalent:
-
Changed enums, structures, and commands:
-
VkRayTracingShaderGroupCreateInfoNV → VkRayTracingShaderGroupCreateInfoKHR (added
pShaderGroupCaptureReplayHandle
) -
VkRayTracingPipelineCreateInfoNV → VkRayTracingPipelineCreateInfoKHR (changed type of
pGroups
, addedlibraries
,pLibraryInterface
, andpDynamicState
) -
VkPhysicalDeviceRayTracingPropertiesNV → VkPhysicalDeviceRayTracingPropertiesKHR (renamed
maxTriangleCount
tomaxPrimitiveCount
, addedshaderGroupHandleCaptureReplaySize
) -
vkCmdTraceRaysNV → vkCmdTraceRaysKHR (params to struct)
-
vkCreateRayTracingPipelinesNV → vkCreateRayTracingPipelinesKHR (different struct, changed functionality)
-
-
Added enums, structures and commands:
-
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
,VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
,VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
,VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
,VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
to VkPipelineCreateFlagBits -
VkDeviceOrHostAddressKHR and VkDeviceOrHostAddressConstKHR unions
-
vkCmdTraceRaysIndirectKHR command and VkTraceRaysIndirectCommandKHR struct
-
vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group capture/replay)
-
vkCmdSetRayTracingPipelineStackSizeKHR and vkGetRayTracingShaderGroupStackSizeKHR commands for stack size control
-
-
Functionality removed:
-
VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
-
vkCompileDeferredNV command (replaced with VK_KHR_deferred_host_operations)
-
(3) What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?
-
Require Vulkan 1.1 and SPIR-V 1.4
-
Added interactions with Vulkan 1.2 and VK_KHR_vulkan_memory_model
-
added creation time capture and replay flags
-
added
VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
to VkPipelineCreateFlagBits
-
-
replace
VkStridedBufferRegionKHR
with VkStridedDeviceAddressRegionKHR and change vkCmdTraceRaysKHR, vkCmdTraceRaysIndirectKHR, to take these for the shader binding table and use device addresses instead of buffers. -
require the shader binding table buffers to have the
VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR
set -
make VK_KHR_pipeline_library an interaction instead of required extension
-
rename the
libraries
member of VkRayTracingPipelineCreateInfoKHR topLibraryInfo
and make it a pointer -
make VK_KHR_deferred_host_operations an interaction instead of a required extension (later went back on this)
-
added explicit stack size management for ray tracing pipelines
-
removed the
maxCallableSize
member of VkRayTracingPipelineInterfaceCreateInfoKHR -
added the
pDynamicState
member to VkRayTracingPipelineCreateInfoKHR -
added
VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
dynamic state for ray tracing pipelines -
added vkGetRayTracingShaderGroupStackSizeKHR and vkCmdSetRayTracingPipelineStackSizeKHR commands
-
added VkShaderGroupShaderKHR enum
-
-
Added
maxRayDispatchInvocationCount
limit to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Added
shaderGroupHandleAlignment
property to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Added
maxRayHitAttributeSize
property to VkPhysicalDeviceRayTracingPipelinePropertiesKHR -
Clarify deferred host ops for pipeline creation
-
VkDeferredOperationKHR is now a top-level parameter for vkCreateRayTracingPipelinesKHR
-
removed
VkDeferredOperationInfoKHR
structure -
change deferred host creation/return parameter behavior such that the implementation can modify such parameters until the deferred host operation completes
-
VK_KHR_deferred_host_operations is required again
-
(4) What are the changes between the internal provisional (VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure v11 / VK_KHR_ray_tracing_pipeline v1) release?
-
refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:
-
VK_KHR_acceleration_structure (for acceleration structure operations)
-
VK_KHR_ray_tracing_pipeline (for ray tracing pipeline and shader stages)
-
VK_KHR_ray_query (for ray queries in existing shader stages)
-
-
Require
Volatile
for the following builtins in the ray generation, closest hit, miss, intersection, and callable shader stages:-
SubgroupSize
,SubgroupLocalInvocationId
,SubgroupEqMask
,SubgroupGeMask
,SubgroupGtMask
,SubgroupLeMask
,SubgroupLtMask
-
SMIDNV
,WarpIDNV
-
-
clarify buffer usage flags for ray tracing
-
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR
is added as an alias ofVK_BUFFER_USAGE_RAY_TRACING_BIT_NV
and is required on shader binding table buffers -
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT
is used in VK_KHR_acceleration_structure forscratchData
-
-
rename
maxRecursionDepth
tomaxRayPipelineRecursionDepth
(pipeline creation) andmaxRayRecursionDepth
(limit) to reduce confusion -
Add queryable
maxRayHitAttributeSize
limit and rename members of VkRayTracingPipelineInterfaceCreateInfoKHR tomaxPipelineRayPayloadSize
andmaxPipelineRayHitAttributeSize
for clarity -
Update SPIRV capabilities to use
RayTracingKHR
-
extension is no longer provisional
-
define synchronization requirements for indirect trace rays and indirect buffer
(5) This extension adds gl_InstanceID for the intersection, any-hit, and closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced with gl_InstanceIndex. Which should be used for Vulkan in this extension?
RESOLVED: This extension uses gl_InstanceID and maps it to InstanceId
in SPIR-V.
It is acknowledged that this is different than other shader stages in
Vulkan.
There are two main reasons for the difference here:
-
symmetry with gl_PrimitiveID which is also available in these shaders
-
there is no "baseInstance" relevant for these shaders, and so ID makes it more obvious that this is zero-based.
Sample Code
Example ray generation GLSL shader
#version 450 core
#extension GL_EXT_ray_tracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureEXT as;
layout(location = 0) rayPayloadEXT float payload;
void main()
{
vec4 col = vec4(0, 0, 0, 1);
vec3 origin = vec3(float(gl_LaunchIDEXT.x)/float(gl_LaunchSizeEXT.x), float(gl_LaunchIDEXT.y)/float(gl_LaunchSizeEXT.y), 1.0);
vec3 dir = vec3(0.0, 0.0, -1.0);
traceRayEXT(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);
col.y = payload;
imageStore(image, ivec2(gl_LaunchIDEXT.xy), col);
}
Version History
-
Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness, Tobias Hector)
-
Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_ray_tracing_pipeline (#1918,!3912)
-
require certain subgroup and sm_shader_builtin shader builtins to be decorated as volatile in the ray generation, closest hit, miss, intersection, and callable stages (#1924,!3903,!3954)
-
clarify buffer usage flags for ray tracing (#2181,!3939)
-
rename maxRecursionDepth to maxRayPipelineRecursionDepth and maxRayRecursionDepth (#2203,!3937)
-
add queriable maxRayHitAttributeSize and rename members of VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966)
-
update to use
RayTracingKHR
SPIR-V capability -
add VUs for matching hit group type against geometry type (#2245,!3994)
-
require
RayTMaxKHR
be volatile in intersection shaders (#2268,!4030) -
add numerical limits for ray parameters (#2235,!3960)
-
fix SBT indexing rules for device addresses (#2308,!4079)
-
relax formula for ray intersection candidate determination (#2322,!4080)
-
add more details on
ShaderRecordBufferKHR
variables (#2230,!4083) -
clarify valid bits for
InstanceCustomIndexKHR
(GLSL/GLSL#19,!4128) -
allow at most one
IncomingRayPayloadKHR
,IncomingCallableDataKHR
, andHitAttributeKHR
(!4129) -
add minimum for maxShaderGroupStride (#2353,!4131)
-
require VK_KHR_pipeline_library extension to be supported (#2348,!4135)
-
clarify meaning of 'geometry index' (#2272,!4137)
-
restrict traces to TLAS (#2239,!4141)
-
add note about maxPipelineRayPayloadSize (#2383,!4172)
-
do not require raygen shader in pipeline libraries (!4185)
-
define sync for indirect trace rays and indirect buffer (#2407,!4208)
-
VK_KHR_shader_clock
- Name String
-
VK_KHR_shader_clock
- Extension Type
-
Device extension
- Registered Extension Number
-
182
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Aaron Hagan ahagan
-
Other Extension Metadata
- Last Modified Date
-
2019-4-25
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_shader_clock
. -
This extension provides API support for
ARB_shader_clock
andEXT_shader_realtime_clock
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Koch, NVIDIA
-
Description
This extension advertises the SPIR-V ShaderClockKHR
capability for
Vulkan, which allows a shader to query a real-time or monotonically
incrementing counter at the subgroup level or across the device level.
The two valid SPIR-V scopes for OpReadClockKHR
are Subgroup
and
Device
.
When using GLSL source-based shading languages, the
clockRealtime
*EXT
() timing functions map to the
OpReadClockKHR
instruction with a scope of Device
, and the
clock
*ARB
() timing functions map to the OpReadClockKHR
instruction with a scope of Subgroup
.
New Enum Constants
-
VK_KHR_SHADER_CLOCK_EXTENSION_NAME
-
VK_KHR_SHADER_CLOCK_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CLOCK_FEATURES_KHR
-
VK_KHR_shader_non_semantic_info
- Name String
-
VK_KHR_shader_non_semantic_info
- Extension Type
-
Device extension
- Registered Extension Number
-
294
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Baldur Karlsson baldurk
-
Other Extension Metadata
- Last Modified Date
-
2019-10-16
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_non_semantic_info
-
- Contributors
-
-
Baldur Karlsson, Valve
-
Description
This extension allows the use of the SPV_KHR_non_semantic_info
extension
in SPIR-V shader modules.
New Enum Constants
-
VK_KHR_SHADER_NON_SEMANTIC_INFO_EXTENSION_NAME
-
VK_KHR_SHADER_NON_SEMANTIC_INFO_SPEC_VERSION
VK_KHR_shader_terminate_invocation
- Name String
-
VK_KHR_shader_terminate_invocation
- Extension Type
-
Device extension
- Registered Extension Number
-
216
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jesse Hall critsec
-
- Last Modified Date
-
2020-08-11
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Requires the
SPV_KHR_terminate_invocation
SPIR-V extension.
-
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Ralph Potter, Samsung
-
Tom Olson, Arm
-
Description
This extension adds Vulkan support for the
SPV_KHR_terminate_invocation
SPIR-V extension.
That SPIR-V extension provides a new instruction,
OpTerminateInvocation
, which causes a shader invocation to immediately
terminate and sets the coverage of shaded samples to 0
; only previously
executed instructions will have observable effects.
The OpTerminateInvocation
instruction, along with the
OpDemoteToHelperInvocation
instruction from the
VK_EXT_shader_demote_to_helper_invocation extension, together replace
the OpKill
instruction, which could behave like either of these
instructions.
OpTerminateInvocation
provides the behavior required by the GLSL
discard
statement, and should be used when available by GLSL compilers
and applications that need the GLSL discard
behavior.
New Enum Constants
-
VK_KHR_SHADER_TERMINATE_INVOCATION_EXTENSION_NAME
-
VK_KHR_SHADER_TERMINATE_INVOCATION_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_TERMINATE_INVOCATION_FEATURES_KHR
-
VK_KHR_shared_presentable_image
- Name String
-
VK_KHR_shared_presentable_image
- Extension Type
-
Device extension
- Registered Extension Number
-
112
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_get_surface_capabilities2
-
- Contact
-
-
Alon Or-bach alonorbach
-
Other Extension Metadata
- Last Modified Date
-
2017-03-20
- IP Status
-
No known IP claims.
- Contributors
-
-
Alon Or-bach, Samsung Electronics
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Pablo Ceballos, Google
-
Chris Forbes, Google
-
Jeff Juliano, NVIDIA
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Graham Connor, Imagination Technologies
-
Michael Worcester, Imagination Technologies
-
Cass Everitt, Oculus
-
Johannes Van Waveren, Oculus
-
Description
This extension extends VK_KHR_swapchain
to enable creation of a shared
presentable image.
This allows the application to use the image while the presention engine is
accessing it, in order to reduce the latency between rendering and
presentation.
New Enum Constants
-
VK_KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME
-
VK_KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
-
-
Extending VkPresentModeKHR:
-
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
-
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR
-
Issues
1) Should we allow a Vulkan WSI swapchain to toggle between normal usage and shared presentation usage?
RESOLVED: No. WSI swapchains are typically recreated with new properties instead of having their properties changed. This can also save resources, assuming that fewer images are needed for shared presentation, and assuming that most VR applications do not need to switch between normal and shared usage.
2) Should we have a query for determining how the presentation engine refresh is triggered?
RESOLVED: Yes. This is done via which presentation modes a surface supports.
3) Should the object representing a shared presentable image be an extension of a VkSwapchainKHR or a separate object?
RESOLVED: Extension of a swapchain due to overlap in creation properties and to allow common functionality between shared and normal presentable images and swapchains.
4) What should we call the extension and the new structures it creates?
RESOLVED: Shared presentable image / shared present.
5) Should the minImageCount
and presentMode
values of the
VkSwapchainCreateInfoKHR be ignored, or required to be compatible
values?
RESOLVED: minImageCount
must be set to 1, and presentMode
should be set to either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
.
6) What should the layout of the shared presentable image be?
RESOLVED: After acquiring the shared presentable image, the application
must transition it to the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
layout
prior to it being used.
After this initial transition, any image usage that was requested during
swapchain creation can be performed on the image without layout transitions
being performed.
7) Do we need a new API for the trigger to refresh new content?
RESOLVED: vkQueuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to vkQueuePresentKHR.
8) How should an application detect a VK_ERROR_OUT_OF_DATE_KHR
error
on a swapchain using the VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
present mode?
RESOLVED: Introduce vkGetSwapchainStatusKHR to allow applications to query the status of a swapchain using a shared presentation mode.
9) What should subsequent calls to vkQueuePresentKHR for
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
swapchains be defined to
do?
RESOLVED: State that implementations may use it as a hint for updated content.
10) Can the ownership of a shared presentable image be transferred to a different queue?
RESOLVED: No.
It is not possible to transfer ownership of a shared presentable image
obtained from a swapchain created using VK_SHARING_MODE_EXCLUSIVE
after it has been presented.
11) How should vkQueueSubmit behave if a command buffer uses an image
from a VK_ERROR_OUT_OF_DATE_KHR
swapchain?
RESOLVED: vkQueueSubmit is expected to return the
VK_ERROR_DEVICE_LOST
error.
12) Can Vulkan provide any guarantee on the order of rendering, to enable beam chasing?
RESOLVED: This could be achieved via use of render passes to ensure strip rendering.
VK_KHR_surface
- Name String
-
VK_KHR_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
1
- Revision
-
25
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2016-08-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
Description
The VK_KHR_surface
extension is an instance extension.
It introduces VkSurfaceKHR objects, which abstract native platform
surface or window objects for use with Vulkan.
It also provides a way to determine whether a queue family in a physical
device supports presenting to particular surface.
Separate extensions for each platform provide the mechanisms for creating
VkSurfaceKHR objects, but once created they may be used in this and
other platform-independent extensions, in particular the
VK_KHR_swapchain
extension.
New Enum Constants
-
VK_KHR_SURFACE_EXTENSION_NAME
-
VK_KHR_SURFACE_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_SURFACE_KHR
-
-
Extending VkResult:
-
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
-
VK_ERROR_SURFACE_LOST_KHR
-
Examples
Note
The example code for the |
Issues
1) Should this extension include a method to query whether a physical device supports presenting to a specific window or native surface on a given platform?
RESOLVED: Yes. Without this, applications would need to create a device instance to determine whether a particular window can be presented to. Knowing that a device supports presentation to a platform in general is not sufficient, as a single machine might support multiple seats, or instances of the platform that each use different underlying physical devices. Additionally, on some platforms, such as the X Window System, different drivers and devices might be used for different windows depending on which section of the desktop they exist on.
2) Should the vkGetPhysicalDeviceSurfaceCapabilitiesKHR,
vkGetPhysicalDeviceSurfaceFormatsKHR, and
vkGetPhysicalDeviceSurfacePresentModesKHR functions be in this
extension and operate on physical devices, rather than being in
VK_KHR_swapchain
(i.e. device extension) and being dependent on
VkDevice?
RESOLVED: Yes.
While it might be useful to depend on VkDevice
(and therefore on
enabled extensions and features) for the queries, Vulkan was released only
with the VkPhysicalDevice versions.
Many cases can be resolved by a Valid Usage.
And\or by a separate pNext
chain version of the query struct specific
to a given extension or parameters, via extensible versions of the queries:
vkGetPhysicalDeviceSurfaceCapabilities2KHR
,
vkGetPhysicalDeviceSurfaceFormats2KHR
, and
vkGetPhysicalDeviceSurfacePresentModes2EXT
.
3) Should Vulkan include support Xlib or XCB as the API for accessing the X Window System platform?
RESOLVED: Both. XCB is a more modern and efficient API, but Xlib usage is deeply ingrained in many applications and likely will remain in use for the foreseeable future. Not all drivers necessarily need to support both, but including both as options in the core specification will probably encourage support, which should in turn ease adoption of the Vulkan API in older codebases. Additionally, the performance improvements possible with XCB likely will not have a measurable impact on the performance of Vulkan presentation and other minimal window system interactions defined here.
4) Should the GBM platform be included in the list of platform enums?
RESOLVED: Deferred, and will be addressed with a platform-specific extension to be written in the future.
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Created initial Description section.
-
Removed query for whether a platform requires the use of a queue for presentation, since it was decided that presentation will always be modeled as being part of the queue.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code.
-
-
Revision 5, 2015-06-01 (James Jones)
-
Added issues 1 and 2 and made related spec updates.
-
-
Revision 6, 2015-06-01 (James Jones)
-
Merged the platform type mappings table previously removed from VK_KHR_swapchain with the platform description table in this spec.
-
Added issues 3 and 4 documenting choices made when building the initial list of native platforms supported.
-
-
Revision 7, 2015-06-11 (Ian Elliott)
-
Updated table 1 per input from the KHR TSG.
-
Updated issue 4 (GBM) per discussion with Daniel Stone. He will create a platform-specific extension sometime in the future.
-
-
Revision 8, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.
-
-
Revision 9, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 10, 2015-06-18 (James Jones)
-
Marked issues 2 and 3 resolved.
-
-
Revision 11, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 12, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced the term "queue node index" with "queue family index" in the spec as that is the agreed term to be used in the latest version of the core header and spec.
-
Replaced bool32_t with VkBool32.
-
-
Revision 13, 2015-08-06 (Daniel Rakos)
-
Updated spec against latest core API header version.
-
-
Revision 14, 2015-08-20 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.
-
Did miscellaneous cleanup, etc.
-
-
Revision 15, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums here from VK_WSI_swapchain so they could be re-used by VK_WSI_display.
-
-
Revision 16, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 17, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 18, 2015-09-26 (Jesse Hall)
-
Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is created via layered extensions. Added VkDestroySurfaceKHR.
-
-
Revision 19, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.
-
-
Revision 20, 2015-09-30 (Jeff Vigil)
-
Add error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 21, 2015-10-15 (Daniel Rakos)
-
Updated the resolution of issue #2 and include the surface capability queries in this extension.
-
Renamed SurfaceProperties to SurfaceCapabilities as it better reflects that the values returned are the capabilities of the surface on a particular device.
-
Other minor cleanup and consistency changes.
-
-
Revision 22, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_surface to VK_KHR_surface.
-
-
Revision 23, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkDestroySurfaceKHR.
-
-
Revision 24, 2015-11-10 (Jesse Hall)
-
Removed VkSurfaceTransformKHR. Use VkSurfaceTransformFlagBitsKHR instead.
-
Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to maxImageArrayLayers.
-
-
Revision 25, 2016-01-14 (James Jones)
-
Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to not have so many characters per line, and to split out a new example to show how to obtain function pointers.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
VK_KHR_surface_protected_capabilities
- Name String
-
VK_KHR_surface_protected_capabilities
- Extension Type
-
Instance extension
- Registered Extension Number
-
240
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
Requires
VK_KHR_get_surface_capabilities2
-
- Contact
-
-
Sandeep Shinde sashinde
-
Other Extension Metadata
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Sandeep Shinde, NVIDIA
-
James Jones, NVIDIA
-
Daniel Koch, NVIDIA
-
Description
This extension extends VkSurfaceCapabilities2KHR, providing
applications a way to query whether swapchains can be created with the
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
flag set.
Vulkan 1.1 added (optional) support for protect memory and protected
resources including buffers (VK_BUFFER_CREATE_PROTECTED_BIT
), images
(VK_IMAGE_CREATE_PROTECTED_BIT
), and swapchains
(VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
).
However, on implementations which support multiple windowing systems, not
all window systems may be able to provide a protected display path.
This extension provides a way to query if a protected swapchain created for a surface (and thus a specific windowing system) can be displayed on screen. It extends the existing VkSurfaceCapabilities2KHR structure with a new VkSurfaceProtectedCapabilitiesKHR structure from which the application can obtain information about support for protected swapchain creation through vkGetPhysicalDeviceSurfaceCapabilities2KHR.
New Enum Constants
-
VK_KHR_SURFACE_PROTECTED_CAPABILITIES_EXTENSION_NAME
-
VK_KHR_SURFACE_PROTECTED_CAPABILITIES_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR
-
VK_KHR_swapchain
- Name String
-
VK_KHR_swapchain
- Extension Type
-
Device extension
- Registered Extension Number
-
2
- Revision
-
70
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
James Jones cubanismo
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Patrick Doane, Blizzard
-
Ian Elliott, LunarG
-
Jesse Hall, Google
-
Mathias Heyer, NVIDIA
-
James Jones, NVIDIA
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Jason Ekstrand, Intel
-
Matthaeus G. Chajdas, AMD
-
Ray Smith, ARM
-
Description
The VK_KHR_swapchain
extension is the device-level companion to the
VK_KHR_surface
extension.
It introduces VkSwapchainKHR objects, which provide the ability to
present rendering results to a surface.
New Structures
If Version 1.1 is supported:
-
Extending VkBindImageMemoryInfo:
-
Extending VkImageCreateInfo:
-
Extending VkPresentInfoKHR:
-
Extending VkSwapchainCreateInfoKHR:
New Enums
If Version 1.1 is supported:
New Bitmasks
If Version 1.1 is supported:
New Enum Constants
-
VK_KHR_SWAPCHAIN_EXTENSION_NAME
-
VK_KHR_SWAPCHAIN_SPEC_VERSION
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
-
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_SWAPCHAIN_KHR
-
-
Extending VkResult:
-
VK_ERROR_OUT_OF_DATE_KHR
-
VK_SUBOPTIMAL_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
-
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
-
If Version 1.1 is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
-
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
-
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
-
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
-
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
-
Issues
1) Does this extension allow the application to specify the memory backing of the presentable images?
RESOLVED: No. Unlike standard images, the implementation will allocate the memory backing of the presentable image.
2) What operations are allowed on presentable images?
RESOLVED: This is determined by the image usage flags specified when creating the presentable image’s swapchain.
3) Does this extension support MSAA presentable images?
RESOLVED: No. Presentable images are always single-sampled. Multi-sampled rendering must use regular images. To present the rendering results the application must manually resolve the multi- sampled image to a single-sampled presentable image prior to presentation.
4) Does this extension support stereo/multi-view presentable images?
RESOLVED: Yes.
The number of views associated with a presentable image is determined by the
imageArrayLayers
specified when creating a swapchain.
All presentable images in a given swapchain use the same array size.
5) Are the layers of stereo presentable images half-sized?
RESOLVED: No. The image extents always match those requested by the application.
6) Do the “present” and “acquire next image” commands operate on a queue? If not, do they need to include explicit semaphore objects to interlock them with queue operations?
RESOLVED: The present command operates on a queue. The image ownership operation it represents happens in order with other operations on the queue, so no explicit semaphore object is required to synchronize its actions.
Applications may want to acquire the next image in separate threads from those in which they manage their queue, or in multiple threads. To make such usage easier, the acquire next image command takes a semaphore to signal as a method of explicit synchronization. The application must later queue a wait for this semaphore before queuing execution of any commands using the image.
7) Does vkAcquireNextImageKHR block if no images are available?
RESOLVED: The command takes a timeout parameter.
Special values for the timeout are 0, which makes the call a non-blocking
operation, and UINT64_MAX
, which blocks indefinitely.
Values in between will block for up to the specified time.
The call will return when an image becomes available or an error occurs.
It may, but is not required to, return before the specified timeout expires
if the swapchain becomes out of date.
8) Can multiple presents be queued using one vkQueuePresentKHR call?
RESOLVED: Yes. VkPresentInfoKHR contains a list of swapchains and corresponding image indices that will be presented. When supported, all presentations queued with a single vkQueuePresentKHR call will be applied atomically as one operation. The same swapchain must not appear in the list more than once. Later extensions may provide applications stronger guarantees of atomicity for such present operations, and/or allow them to query whether atomic presentation of a particular group of swapchains is possible.
9) How do the presentation and acquire next image functions notify the application the targeted surface has changed?
RESOLVED: Two new result codes are introduced for this purpose:
-
VK_SUBOPTIMAL_KHR
- Presentation will still succeed, subject to the window resize behavior, but the swapchain is no longer configured optimally for the surface it targets. Applications should query updated surface information and recreate their swapchain at the next convenient opportunity. -
VK_ERROR_OUT_OF_DATE_KHR
- Failure. The swapchain is no longer compatible with the surface it targets. The application must query updated surface information and recreate the swapchain before presentation will succeed.
These can be returned by both vkAcquireNextImageKHR and vkQueuePresentKHR.
10) Does the vkAcquireNextImageKHR command return a semaphore to the application via an output parameter, or accept a semaphore to signal from the application as an object handle parameter?
RESOLVED: Accept a semaphore to signal as an object handle. This avoids the need to specify whether the application must destroy the semaphore or whether it is owned by the swapchain, and if the latter, what its lifetime is and whether it can be re-used for other operations once it is received from vkAcquireNextImageKHR.
11) What types of swapchain queuing behavior should be exposed? Options include swap interval specification, mailbox/most recent vs. FIFO queue management, targeting specific vertical blank intervals or absolute times for a given present operation, and probably others. For some of these, whether they are specified at swapchain creation time or as per-present parameters needs to be decided as well.
RESOLVED: The base swapchain extension will expose 3 possible behaviors (of which, FIFO will always be supported):
-
Immediate present: Does not wait for vertical blanking period to update the current image, likely resulting in visible tearing. No internal queue is used. Present requests are applied immediately.
-
Mailbox queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for re-use by the application.
-
FIFO queue: Waits for the next vertical blanking period to update the current image. No tearing should be observed. An internal queue containing
numSwapchainImages
- 1 entries is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty
Not all surfaces will support all of these modes, so the modes supported will be returned using a surface info query. All surfaces must support the FIFO queue mode. Applications must choose one of these modes up front when creating a swapchain. Switching modes can be accomplished by recreating the swapchain.
12) Can VK_PRESENT_MODE_MAILBOX_KHR
provide non-blocking guarantees
for vkAcquireNextImageKHR? If so, what is the proper criteria?
RESOLVED: Yes. The difficulty is not immediately obvious here. Naively, if at least 3 images are requested, mailbox mode should always have an image available for the application if the application does not own any images when the call to vkAcquireNextImageKHR was made. However, some presentation engines may have more than one “current” image, and would still need to block in some cases. The right requirement appears to be that if the application allocates the surface’s minimum number of images + 1 then it is guaranteed non-blocking behavior when it does not currently own any images.
13) Is there a way to create and initialize a new swapchain for a surface
that has generated a VK_SUBOPTIMAL_KHR
return code while still using
the old swapchain?
RESOLVED: Not as part of this specification. This could be useful to allow the application to create an “optimal” replacement swapchain and rebuild all its command buffers using it in a background thread at a low priority while continuing to use the “suboptimal” swapchain in the main thread. It could probably use the same “atomic replace” semantics proposed for recreating direct-to-device swapchains without incurring a mode switch. However, after discussion, it was determined some platforms probably could not support concurrent swapchains for the same surface though, so this will be left out of the base KHR extensions. A future extension could add this for platforms where it is supported.
14) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageCount
to indicate there are no
practical limits on the number of images in a swapchain?
RESOLVED: Yes. There where often be cases where there is no practical limit to the number of images in a swapchain other than the amount of available resources (I.e., memory) in the system. Trying to derive a hard limit from things like memory size is prone to failure. It is better in such cases to leave it to applications to figure such soft limits out via trial/failure iterations.
15) Should there be a special value for
VkSurfaceCapabilitiesKHR::currentExtent
to indicate the size of
the platform surface is undefined?
RESOLVED: Yes. On some platforms (Wayland, for example), the surface size is defined by the images presented to it rather than the other way around.
16) Should there be a special value for
VkSurfaceCapabilitiesKHR::maxImageExtent
to indicate there is no
practical limit on the surface size?
RESOLVED: No. It seems unlikely such a system would exist. 0 could be used to indicate the platform places no limits on the extents beyond those imposed by Vulkan for normal images, but this query could just as easily return those same limits, so a special “unlimited” value does not seem useful for this field.
17) How should surface rotation and mirroring be exposed to applications? How do they specify rotation and mirroring transforms applied prior to presentation?
RESOLVED: Applications can query both the supported and current transforms
of a surface.
Both are specified relative to the device’s “natural” display rotation and
direction.
The supported transforms indicates which orientations the presentation
engine accepts images in.
For example, a presentation engine that does not support transforming
surfaces as part of presentation, and which is presenting to a surface that
is displayed with a 90-degree rotation, would return only one supported
transform bit: VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
.
Applications must transform their rendering by the transform they specify
when creating the swapchain in preTransform
field.
18) Can surfaces ever not support VK_MIRROR_NONE
? Can they support
vertical and horizontal mirroring simultaneously? Relatedly, should
VK_MIRROR_NONE
[_BIT] be zero, or bit one, and should applications be
allowed to specify multiple pre and current mirror transform bits, or
exactly one?
RESOLVED: Since some platforms may not support presenting with a transform
other than the native window’s current transform, and prerotation/mirroring
are specified relative to the device’s natural rotation and direction,
rather than relative to the surface’s current rotation and direction, it is
necessary to express lack of support for no mirroring.
To allow this, the MIRROR_NONE
enum must occupy a bit in the flags.
Since MIRROR_NONE
must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
VK_MIRROR_NONE_BIT
| VK_MIRROR_HORIZONTAL_BIT
, or a transform
that includes both “no mirroring” and “horizontal mirroring”
simultaneously.
Therefore, it is desirable to allow specifying all supported mirroring
transforms using only one bit.
The question then becomes, should there be a
VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT
to represent a simultaneous
horizontal and vertical mirror transform? However, such a transform is
equivalent to a 180 degree rotation, so presentation engines and
applications that wish to support or use such a transform can express it
through rotation instead.
Therefore, 3 exclusive bits are sufficient to express all needed mirroring
transforms.
19) Should support for sRGB be required?
RESOLVED: In the advent of UHD and HDR display devices, proper color space information is vital to the display pipeline represented by the swapchain. The app can discover the supported format/color-space pairs and select a pair most suited to its rendering needs. Currently only the sRGB color space is supported, future extensions may provide support for more color spaces. See issues 23 and 24.
20) Is there a mechanism to modify or replace an existing swapchain with one targeting the same surface?
RESOLVED: Yes. This is described above in the text.
21) Should there be a way to set prerotation and mirroring using native APIs when presenting using a Vulkan swapchain?
RESOLVED: Yes.
The transforms that can be expressed in this extension are a subset of those
possible on native platforms.
If a platform exposes a method to specify the transform of presented images
for a given surface using native methods and exposes more transforms or
other properties for surfaces than Vulkan supports, it might be impossible,
difficult, or inconvenient to set some of those properties using Vulkan KHR
extensions and some using the native interfaces.
To avoid overwriting properties set using native commands when presenting
using a Vulkan swapchain, the application can set the pretransform to
“inherit”, in which case the current native properties will be used, or if
none are available, a platform-specific default will be used.
Platforms that do not specify a reasonable default or do not provide native
mechanisms to specify such transforms should not include the inherit bits in
the supportedTransforms
bitmask they return in
VkSurfaceCapabilitiesKHR.
22) Should the content of presentable images be clipped by objects obscuring their target surface?
RESOLVED: Applications can choose which behavior they prefer. Allowing the content to be clipped could enable more optimal presentation methods on some platforms, but some applications might rely on the content of presentable images to perform techniques such as partial updates or motion blurs.
23) What is the purpose of specifying a VkColorSpaceKHR along with VkFormat when creating a swapchain?
RESOLVED: While Vulkan itself is color space agnostic (e.g. even the
meaning of R, G, B and A can be freely defined by the rendering
application), the swapchain eventually will have to present the images on a
display device with specific color reproduction characteristics.
If any color space transformations are necessary before an image can be
displayed, the color space of the presented image must be known to the
swapchain.
A swapchain will only support a restricted set of color format and -space
pairs.
This set can be discovered via vkGetPhysicalDeviceSurfaceFormatsKHR.
As it can be expected that most display devices support the sRGB color
space, at least one format/color-space pair has to be exposed, where the
color space is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
.
24) How are sRGB formats and the sRGB color space related?
RESOLVED: While Vulkan exposes a number of SRGB texture formats, using
such formats does not guarantee working in a specific color space.
It merely means that the hardware can directly support applying the
non-linear transfer functions defined by the sRGB standard color space when
reading from or writing to images of that these formats.
Still, it is unlikely that a swapchain will expose a *_SRGB
format
along with any color space other than
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
.
On the other hand, non-*_SRGB
formats will be very likely exposed in
pair with a SRGB color space.
This means, the hardware will not apply any transfer function when reading
from or writing to such images, yet they will still be presented on a device
with sRGB display characteristics.
In this case the application is responsible for applying the transfer
function, for instance by using shader math.
25) How are the lifetime of surfaces and swapchains targeting them related?
RESOLVED: A surface must outlive any swapchains targeting it. A VkSurfaceKHR owns the binding of the native window to the Vulkan driver.
26) How can the client control the way the alpha channel of swapchain images is treated by the presentation engine during compositing?
RESOLVED: We should add new enum values to allow the client to negotiate
with the presentation engine on how to treat image alpha values during the
compositing process.
Since not all platforms can practically control this through the Vulkan
driver, a value of VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR
is provided like
for surface transforms.
27) Is vkCreateSwapchainKHR the right function to return
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
, or should the various
platform-specific VkSurfaceKHR factory functions catch this error
earlier?
RESOLVED: For most platforms, the VkSurfaceKHR structure is a simple container holding the data that identifies a native window or other object representing a surface on a particular platform. For the surface factory functions to return this error, they would likely need to register a reference on the native objects with the native display server somehow, and ensure no other such references exist. Surfaces were not intended to be that heavyweight.
Swapchains are intended to be the objects that directly manipulate native windows and communicate with the native presentation mechanisms. Swapchains will already need to communicate with the native display server to negotiate allocation and/or presentation of presentable images for a native surface. Therefore, it makes more sense for swapchain creation to be the point at which native object exclusivity is enforced. Platforms may choose to enforce further restrictions on the number of VkSurfaceKHR objects that may be created for the same native window if such a requirement makes sense on a particular platform, but a global requirement is only sensible at the swapchain level.
Examples
Note
The example code for the |
Version History
-
Revision 1, 2015-05-20 (James Jones)
-
Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.
-
-
Revision 2, 2015-05-22 (Ian Elliott)
-
Made many agreed-upon changes from 2015-05-21 KHR TSG meeting. This includes using only a queue for presentation, and having an explicit function to acquire the next image.
-
Fixed typos and other minor mistakes.
-
-
Revision 3, 2015-05-26 (Ian Elliott)
-
Improved the Description section.
-
Added or resolved issues that were found in improving the Description. For example, pSurfaceDescription is used consistently, instead of sometimes using pSurface.
-
-
Revision 4, 2015-05-27 (James Jones)
-
Fixed some grammatical errors and typos
-
Filled in the description of imageUseFlags when creating a swapchain.
-
Added a description of swapInterval.
-
Replaced the paragraph describing the order of operations on a queue for image ownership and presentation.
-
-
Revision 5, 2015-05-27 (James Jones)
-
Imported relevant issues from the (abandoned) vk_wsi_persistent_swapchain_images extension.
-
Added issues 6 and 7, regarding behavior of the acquire next image and present commands with respect to queues.
-
Updated spec language and examples to align with proposed resolutions to issues 6 and 7.
-
-
Revision 6, 2015-05-27 (James Jones)
-
Added issue 8, regarding atomic presentation of multiple swapchains
-
Updated spec language and examples to align with proposed resolution to issue 8.
-
-
Revision 7, 2015-05-27 (James Jones)
-
Fixed compilation errors in example code, and made related spec fixes.
-
-
Revision 8, 2015-05-27 (James Jones)
-
Added issue 9, and the related VK_SUBOPTIMAL_KHR result code.
-
Renamed VK_OUT_OF_DATE_KHR to VK_ERROR_OUT_OF_DATE_KHR.
-
-
Revision 9, 2015-05-27 (James Jones)
-
Added inline proposed resolutions (marked with [JRJ]) to some XXX questions/issues. These should be moved to the issues section in a subsequent update if the proposals are adopted.
-
-
Revision 10, 2015-05-28 (James Jones)
-
Converted vkAcquireNextImageKHR back to a non-queue operation that uses a VkSemaphore object for explicit synchronization.
-
Added issue 10 to determine whether vkAcquireNextImageKHR generates or returns semaphores, or whether it operates on a semaphore provided by the application.
-
-
Revision 11, 2015-05-28 (James Jones)
-
Marked issues 6, 7, and 8 resolved.
-
Renamed VkSurfaceCapabilityPropertiesKHR to VkSurfacePropertiesKHR to better convey the mutable nature of the info it contains.
-
-
Revision 12, 2015-05-28 (James Jones)
-
Added issue 11 with a proposed resolution, and the related issue 12.
-
Updated various sections of the spec to match the proposed resolution to issue 11.
-
-
Revision 13, 2015-06-01 (James Jones)
-
Moved some structures to VK_EXT_KHR_swap_chain to resolve the spec’s issues 1 and 2.
-
-
Revision 14, 2015-06-01 (James Jones)
-
Added code for example 4 demonstrating how an application might make use of the two different present and acquire next image KHR result codes.
-
Added issue 13.
-
-
Revision 15, 2015-06-01 (James Jones)
-
Added issues 14 - 16 and related spec language.
-
Fixed some spelling errors.
-
Added language describing the meaningful return values for vkAcquireNextImageKHR and vkQueuePresentKHR.
-
-
Revision 16, 2015-06-02 (James Jones)
-
Added issues 17 and 18, as well as related spec language.
-
Removed some erroneous text added by mistake in the last update.
-
-
Revision 17, 2015-06-15 (Ian Elliott)
-
Changed special value from "-1" to "0" so that the data types can be unsigned.
-
-
Revision 18, 2015-06-15 (Ian Elliott)
-
Clarified the values of VkSurfacePropertiesKHR::minImageCount and the timeout parameter of the vkAcquireNextImageKHR function.
-
-
Revision 19, 2015-06-17 (James Jones)
-
Misc. cleanup. Removed resolved inline issues and fixed typos.
-
Fixed clarification of VkSurfacePropertiesKHR::minImageCount made in version 18.
-
Added a brief "Image Ownership" definition to the list of terms used in the spec.
-
-
Revision 20, 2015-06-17 (James Jones)
-
Updated enum-extending values using new convention.
-
-
Revision 21, 2015-06-17 (James Jones)
-
Added language describing how to use VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
Cleaned up an XXX comment regarding the description of which queues vkQueuePresentKHR can be used on.
-
-
Revision 22, 2015-06-17 (James Jones)
-
Rebased on Vulkan API version 126.
-
-
Revision 23, 2015-06-18 (James Jones)
-
Updated language for issue 12 to read as a proposed resolution.
-
Marked issues 11, 12, 13, 16, and 17 resolved.
-
Temporarily added links to the relevant bugs under the remaining unresolved issues.
-
Added issues 19 and 20 as well as proposed resolutions.
-
-
Revision 24, 2015-06-19 (Ian Elliott)
-
Changed special value for VkSurfacePropertiesKHR::currentExtent back to "-1" from "0". This value will never need to be unsigned, and "0" is actually a legal value.
-
-
Revision 25, 2015-06-23 (Ian Elliott)
-
Examples now show use of function pointers for extension functions.
-
Eliminated extraneous whitespace.
-
-
Revision 26, 2015-06-25 (Ian Elliott)
-
Resolved Issues 9 & 10 per KHR TSG meeting.
-
-
Revision 27, 2015-06-25 (James Jones)
-
Added oldSwapchain member to VkSwapchainCreateInfoKHR.
-
-
Revision 28, 2015-06-25 (James Jones)
-
Added the "inherit" bits to the rotation and mirroring flags and the associated issue 21.
-
-
Revision 29, 2015-06-25 (James Jones)
-
Added the "clipped" flag to VkSwapchainCreateInfoKHR, and the associated issue 22.
-
Specified that presenting an image does not modify it.
-
-
Revision 30, 2015-06-25 (James Jones)
-
Added language to the spec that clarifies the behavior of vkCreateSwapchainKHR() when the oldSwapchain field of VkSwapchainCreateInfoKHR is not NULL.
-
-
Revision 31, 2015-06-26 (Ian Elliott)
-
Example of new VkSwapchainCreateInfoKHR members, "oldSwapchain" and "clipped".
-
Example of using VkSurfacePropertiesKHR::{min|max}ImageCount to set VkSwapchainCreateInfoKHR::minImageCount.
-
Rename vkGetSurfaceInfoKHR()'s 4th parameter to "pDataSize", for consistency with other functions.
-
Add macro with C-string name of extension (just to header file).
-
-
Revision 32, 2015-06-26 (James Jones)
-
Minor adjustments to the language describing the behavior of "oldSwapchain"
-
Fixed the version date on my previous two updates.
-
-
Revision 33, 2015-06-26 (Jesse Hall)
-
Add usage flags to VkSwapchainCreateInfoKHR
-
-
Revision 34, 2015-06-26 (Ian Elliott)
-
Rename vkQueuePresentKHR()'s 2nd parameter to "pPresentInfo", for consistency with other functions.
-
-
Revision 35, 2015-06-26 (Jason Ekstrand)
-
Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums into a single VkSurfaceTransformFlagBitsKHR enum.
-
-
Revision 36, 2015-06-26 (Jason Ekstrand)
-
Added a VkSurfaceTransformKHR enum that is not a bitmask. Each value in VkSurfaceTransformKHR corresponds directly to one of the bits in VkSurfaceTransformFlagBitsKHR so transforming from one to the other is easy. Having a separate enum means that currentTransform and preTransform are now unambiguous by definition.
-
-
Revision 37, 2015-06-29 (Ian Elliott)
-
Corrected one of the signatures of vkAcquireNextImageKHR, which had the last two parameters switched from what it is elsewhere in the specification and header files.
-
-
Revision 38, 2015-06-30 (Ian Elliott)
-
Corrected a typo in description of the vkGetSwapchainInfoKHR() function.
-
Corrected a typo in header file comment for VkPresentInfoKHR::sType.
-
-
Revision 39, 2015-07-07 (Daniel Rakos)
-
Added error section describing when each error is expected to be reported.
-
Replaced bool32_t with VkBool32.
-
-
Revision 40, 2015-07-10 (Ian Elliott)
-
Updated to work with version 138 of the "vulkan.h" header. This includes declaring the VkSwapchainKHR type using the new VK_DEFINE_NONDISP_HANDLE macro, and no longer extending VkObjectType (which was eliminated).
-
-
Revision 41 2015-07-09 (Mathias Heyer)
-
Added color space language.
-
-
Revision 42, 2015-07-10 (Daniel Rakos)
-
Updated query mechanism to reflect the convention changes done in the core spec.
-
Removed "queue" from the name of VK_STRUCTURE_TYPE_QUEUE_PRESENT_INFO_KHR to be consistent with the established naming convention.
-
Removed reference to the no longer existing VkObjectType enum.
-
-
Revision 43, 2015-07-17 (Daniel Rakos)
-
Added support for concurrent sharing of swapchain images across queue families.
-
Updated sample code based on recent changes
-
-
Revision 44, 2015-07-27 (Ian Elliott)
-
Noted that support for VK_PRESENT_MODE_FIFO_KHR is required. That is ICDs may optionally support IMMEDIATE and MAILBOX, but must support FIFO.
-
-
Revision 45, 2015-08-07 (Ian Elliott)
-
Corrected a typo in spec file (type and variable name had wrong case for the imageColorSpace member of the VkSwapchainCreateInfoKHR struct).
-
Corrected a typo in header file (last parameter in PFN_vkGetSurfacePropertiesKHR was missing "KHR" at the end of type: VkSurfacePropertiesKHR).
-
-
Revision 46, 2015-08-20 (Ian Elliott)
-
Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
-
Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.
-
Made improvements to several descriptions.
-
Changed the status of several issues from PROPOSED to RESOLVED, leaving no unresolved issues.
-
Resolved several TODOs, did miscellaneous cleanup, etc.
-
-
Revision 47, 2015-08-20 (Ian Elliott—porting a 2015-07-29 change from James Jones)
-
Moved the surface transform enums to VK_WSI_swapchain so they could be re-used by VK_WSI_display.
-
-
Revision 48, 2015-09-01 (James Jones)
-
Various minor cleanups.
-
-
Revision 49, 2015-09-01 (James Jones)
-
Restore single-field revision number.
-
-
Revision 50, 2015-09-01 (James Jones)
-
Update Example #4 to include code that illustrates how to use the oldSwapchain field.
-
-
Revision 51, 2015-09-01 (James Jones)
-
Fix example code compilation errors.
-
-
Revision 52, 2015-09-08 (Matthaeus G. Chajdas)
-
Corrected a typo.
-
-
Revision 53, 2015-09-10 (Alon Or-bach)
-
Removed underscore from SWAP_CHAIN left in VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR.
-
-
Revision 54, 2015-09-11 (Jesse Hall)
-
Described the execution and memory coherence requirements for image transitions to and from VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR.
-
-
Revision 55, 2015-09-11 (Ray Smith)
-
Added errors for destroying and binding memory to presentable images
-
-
Revision 56, 2015-09-18 (James Jones)
-
Added fence argument to vkAcquireNextImageKHR
-
Added example of how to meter a host thread based on presentation rate.
-
-
Revision 57, 2015-09-26 (Jesse Hall)
-
Replace VkSurfaceDescriptionKHR with VkSurfaceKHR.
-
Added issue 25 with agreed resolution.
-
-
Revision 58, 2015-09-28 (Jesse Hall)
-
Renamed from VK_EXT_KHR_device_swapchain to VK_EXT_KHR_swapchain.
-
-
Revision 59, 2015-09-29 (Ian Elliott)
-
Changed vkDestroySwapchainKHR() to return void.
-
-
Revision 60, 2015-10-01 (Jeff Vigil)
-
Added error result VK_ERROR_SURFACE_LOST_KHR.
-
-
Revision 61, 2015-10-05 (Jason Ekstrand)
-
Added the VkCompositeAlpha enum and corresponding structure fields.
-
-
Revision 62, 2015-10-12 (Daniel Rakos)
-
Added VK_PRESENT_MODE_FIFO_RELAXED_KHR.
-
-
Revision 63, 2015-10-15 (Daniel Rakos)
-
Moved surface capability queries to VK_EXT_KHR_surface.
-
-
Revision 64, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_swapchain to VK_KHR_swapchain.
-
-
Revision 65, 2015-10-28 (Ian Elliott)
-
Added optional pResult member to VkPresentInfoKHR, so that per-swapchain results can be obtained from vkQueuePresentKHR().
-
-
Revision 66, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to create and destroy functions.
-
Updated resource transition language.
-
Updated sample code.
-
-
Revision 67, 2015-11-10 (Jesse Hall)
-
Add reserved flags bitmask to VkSwapchainCreateInfoKHR.
-
Modify naming and member ordering to match API style conventions, and so the VkSwapchainCreateInfoKHR image property members mirror corresponding VkImageCreateInfo members but with an 'image' prefix.
-
Make VkPresentInfoKHR::pResults non-const; it is an output array parameter.
-
Make pPresentInfo parameter to vkQueuePresentKHR const.
-
-
Revision 68, 2016-04-05 (Ian Elliott)
-
Moved the "validity" include for vkAcquireNextImage to be in its proper place, after the prototype and list of parameters.
-
Clarified language about presentable images, including how they are acquired, when applications can and cannot use them, etc. As part of this, removed language about "ownership" of presentable images, and replaced it with more-consistent language about presentable images being "acquired" by the application.
-
-
2016-08-23 (Ian Elliott)
-
Update the example code, to use the final API command names, to not have so many characters per line, and to split out a new example to show how to obtain function pointers. This code is more similar to the LunarG "cube" demo program.
-
-
2016-08-25 (Ian Elliott)
-
A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.
-
-
Revision 69, 2017-09-07 (Tobias Hector)
-
Added interactions with Vulkan 1.1
-
-
Revision 70, 2017-10-06 (Ian Elliott)
-
Corrected interactions with Vulkan 1.1
-
VK_KHR_swapchain_mutable_format
- Name String
-
VK_KHR_swapchain_mutable_format
- Extension Type
-
Device extension
- Registered Extension Number
-
201
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_KHR_maintenance2
-
Requires
VK_KHR_image_format_list
-
- Contact
-
-
Daniel Rakos drakos-arm
-
Other Extension Metadata
- Last Modified Date
-
2018-03-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jason Ekstrand, Intel
-
Jan-Harald Fredriksen, ARM
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Description
This extension allows processing of swapchain images as different formats to that used by the window system, which is particularly useful for switching between sRGB and linear RGB formats.
It adds a new swapchain creation flag that enables creating image views from presentable images with a different format than the one used to create the swapchain.
New Enum Constants
-
VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_EXTENSION_NAME
-
VK_KHR_SWAPCHAIN_MUTABLE_FORMAT_SPEC_VERSION
-
Extending VkSwapchainCreateFlagBitsKHR:
-
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
-
Issues
1) Are there any new capabilities needed?
RESOLVED: No. It is expected that all implementations exposing this extension support swapchain image format mutability.
2) Do we need a separate VK_SWAPCHAIN_CREATE_EXTENDED_USAGE_BIT_KHR
?
RESOLVED: No.
This extension requires VK_KHR_maintenance2
and presentable images of
swapchains created with VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
are
created internally in a way equivalent to specifying both
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
and
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR
.
3) Do we need a separate structure to allow specifying an image format list for swapchains?
RESOLVED: No.
We simply use the same VkImageFormatListCreateInfoKHR structure
introduced by VK_KHR_image_format_list
.
The structure is required to be included in the pNext
chain of
VkSwapchainCreateInfoKHR for swapchains created with
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
.
VK_KHR_synchronization2
- Name String
-
VK_KHR_synchronization2
- Extension Type
-
Device extension
- Registered Extension Number
-
315
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_create_renderpass2
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-12-03 Interactions and External Dependencies:
-
Interacts with
VK_KHR_create_renderpass2
-
- Contributors
-
-
Tobias Hector
-
Description
This extension modifies the original core synchronization APIs to simplify the interface and improve usability of these APIs. It also adds new pipeline stage and access flag types that extend into the 64-bit range, as we have run out within the 32-bit range. The new flags are identical to the old values within the 32-bit range, with new stages and bits beyond that.
Pipeline stages and access flags are now specified together in memory
barrier structures, making the connection between the two more obvious.
Additionally, scoping the pipeline stages into the barrier structs allows
the use of the MEMORY_READ
and MEMORY_WRITE
flags without
sacrificing precision.
The per-stage access flags should be used to disambiguate specific accesses
in a given stage or set of stages - for instance, between uniform reads and
sampling operations.
Layout transitions have been simplified as well; rather than requiring a
different set of layouts for depth/stencil/color attachments, there are
generic VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR
and
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
layouts which are contextually
applied based on the image format.
For example, for a depth format image,
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
is equivalent to
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR
.
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
also functionally replaces
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
.
Events are now more efficient, because they include memory dependency information when you set them on the device. Previously, this information was only known when waiting on an event, so the dependencies could not be satisfied until the wait occurred. That sometimes meant stalling the pipeline when the wait occurred. The new API provides enough information for implementations to satisfy these dependencies in parallel with other tasks.
Queue submission has been changed to wrap command buffers and semaphores in extensible structures, which incorporate changes from Vulkan 1.1, VK_KHR_device_group, and VK_KHR_timeline_semaphore. This also adds a pipeline stage to the semaphore signal operation, mirroring the existing pipeline stage specification for wait operations.
Other miscellaneous changes include:
-
Events can now be specified as interacting only with the device, allowing more efficient access to the underlying object.
-
Image memory barriers that do not perform an image layout transition can be specified by setting
oldLayout
equal tonewLayout
.-
E.g. the old and new layout can both be set to
VK_IMAGE_LAYOUT_UNDEFINED
, without discarding data in the image.
-
-
Queue family ownership transfer parameters are simplified in some cases.
-
Where two synchronization commands need to be matched up (queue transfer operations, events), the dependency information specified in each place must now match completely for consistency.
-
Extensions with commands or functions with a VkPipelineStageFlags or VkPipelineStageFlagBits parameter have had those APIs replaced with equivalents using VkPipelineStageFlags2KHR.
-
The new event and barrier interfaces are now more extensible for future changes.
-
Relevant pipeline stage masks can now be specified as empty with the new
VK_PIPELINE_STAGE_NONE_KHR
andVK_PIPELINE_STAGE_2_NONE_KHR
values. -
VkMemoryBarrier2KHR can be chained to VkSubpassDependency2, overriding the original 32-bit stage and access masks.
New Commands
If VK_AMD_buffer_marker is supported:
If VK_NV_device_diagnostic_checkpoints is supported:
New Enum Constants
-
VK_KHR_SYNCHRONIZATION_2_EXTENSION_NAME
-
VK_KHR_SYNCHRONIZATION_2_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_NONE_KHR
-
-
Extending VkEventCreateFlagBits:
-
VK_EVENT_CREATE_DEVICE_ONLY_BIT_KHR
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR
-
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_NONE_KHR
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER_2_KHR
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_DEPENDENCY_INFO_KHR
-
VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2_KHR
-
VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SYNCHRONIZATION_2_FEATURES_KHR
-
VK_STRUCTURE_TYPE_SEMAPHORE_SUBMIT_INFO_KHR
-
VK_STRUCTURE_TYPE_SUBMIT_INFO_2_KHR
-
If VK_EXT_blend_operation_advanced is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
-
If VK_EXT_conditional_rendering is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_CONDITIONAL_RENDERING_READ_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT
-
If VK_EXT_fragment_density_map is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
If VK_EXT_transform_feedback is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
-
VK_ACCESS_2_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT
-
VK_ACCESS_2_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT
-
If VK_KHR_acceleration_structure is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_KHR
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
-
If VK_KHR_fragment_shading_rate is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_FRAGMENT_SHADING_RATE_ATTACHMENT_READ_BIT_KHR
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
-
If VK_KHR_ray_tracing_pipeline is supported:
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR
-
If VK_NV_device_diagnostic_checkpoints is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_2_NV
-
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_2_NV
-
If VK_NV_device_generated_commands is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_COMMAND_PREPROCESS_READ_BIT_NV
-
VK_ACCESS_2_COMMAND_PREPROCESS_WRITE_BIT_NV
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_COMMAND_PREPROCESS_BIT_NV
-
If VK_NV_mesh_shader is supported:
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_NV
-
VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_NV
-
If VK_NV_ray_tracing is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_READ_BIT_NV
-
VK_ACCESS_2_ACCELERATION_STRUCTURE_WRITE_BIT_NV
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_BUILD_BIT_NV
-
VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_NV
-
If VK_NV_shading_rate_image is supported:
-
Extending VkAccessFlagBits2KHR:
-
VK_ACCESS_2_SHADING_RATE_IMAGE_READ_BIT_NV
-
-
Extending VkPipelineStageFlagBits2KHR:
-
VK_PIPELINE_STAGE_2_SHADING_RATE_IMAGE_BIT_NV
-
VK_KHR_wayland_surface
- Name String
-
VK_KHR_wayland_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
7
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_wayland_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Wayland
wl_surface
, as well as a query to determine support for rendering to a
Wayland compositor.
New Enum Constants
-
VK_KHR_WAYLAND_SURFACE_EXTENSION_NAME
-
VK_KHR_WAYLAND_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Wayland need a way to query for compatibility between a particular
physical device and a specific Wayland display? This would be a more general
query than vkGetPhysicalDeviceSurfaceSupportKHR: if the
Wayland-specific query returned VK_TRUE
for a (VkPhysicalDevice,
struct wl_display*
) pair, then the physical device could be assumed to
support presentation to any VkSurfaceKHR for surfaces on the display.
RESOLVED: Yes. vkGetPhysicalDeviceWaylandPresentationSupportKHR was added to address this issue.
2) Should we require surfaces created with vkCreateWaylandSurfaceKHR
to support the VK_PRESENT_MODE_MAILBOX_KHR
present mode?
RESOLVED: Yes.
Wayland is an inherently mailbox window system and mailbox support is
required for some Wayland compositor interactions to work as expected.
While handling these interactions may be possible with
VK_PRESENT_MODE_FIFO_KHR
, it is much more difficult to do without
deadlock and requiring all Wayland applications to be able to support
implementations which only support VK_PRESENT_MODE_FIFO_KHR
would be
an onerous restriction on application developers.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added vkGetPhysicalDeviceWaylandPresentationSupportKHR() to resolve issue #1.
-
Adjusted wording of issue #1 to match the agreed-upon solution.
-
Renamed "window" parameters to "surface" to match Wayland conventions.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_wayland_surface to VK_KHR_wayland_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWaylandSurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-02-08 (Jason Ekstrand)
-
Added the requirement that implementations support
VK_PRESENT_MODE_MAILBOX_KHR
. -
Added wording about interactions between vkQueuePresentKHR and the Wayland requests sent to the compositor.
-
VK_KHR_win32_keyed_mutex
- Name String
-
VK_KHR_win32_keyed_mutex
- Extension Type
-
Device extension
- Registered Extension Number
-
76
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory_win32
-
- Contact
-
-
Carsten Rohde crohde
-
Other Extension Metadata
- Last Modified Date
-
2016-10-21
- IP Status
-
No known IP claims.
- Contributors
-
-
James Jones, NVIDIA
-
Jeff Juliano, NVIDIA
-
Carsten Rohde, NVIDIA
-
Description
Applications that wish to import Direct3D 11 memory objects into the Vulkan API may wish to use the native keyed mutex mechanism to synchronize access to the memory between Vulkan and Direct3D. This extension provides a way for an application to access the keyed mutex associated with an imported Vulkan memory object when submitting command buffers to a queue.
New Enum Constants
-
VK_KHR_WIN32_KEYED_MUTEX_EXTENSION_NAME
-
VK_KHR_WIN32_KEYED_MUTEX_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_KEYED_MUTEX_ACQUIRE_RELEASE_INFO_KHR
-
VK_KHR_win32_surface
- Name String
-
VK_KHR_win32_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
10
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-04-24
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_win32_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Win32 HWND
, as
well as a query to determine support for rendering to the windows desktop.
New Enum Constants
-
VK_KHR_WIN32_SURFACE_EXTENSION_NAME
-
VK_KHR_WIN32_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does Win32 need a way to query for compatibility between a particular physical device and a specific screen? Compatibility between a physical device and a window generally only depends on what screen the window is on. However, there is not an obvious way to identify a screen without already having a window on the screen.
RESOLVED: No. While it may be useful, there is not a clear way to do this on Win32. However, a method was added to query support for presenting to the windows desktop as a whole.
2) If a native window object (HWND
) is used by one graphics API, and
then is later used by a different graphics API (one of which is Vulkan), can
these uses interfere with each other?
RESOLVED: Yes.
Uses of a window object by multiple graphics APIs results in undefined behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. Potential failures include:
-
Creating then destroying a flip presentation model DXGI swapchain on a window object can prevent vkCreateSwapchainKHR from succeeding on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can prevent creation of a bitblt model DXGI swapchain on the same window object.
-
Creating then destroying a VkSwapchainKHR on a window object can effectively
SetPixelFormat
to a different format than the format chosen by an OpenGL application. -
Creating then destroying a VkSwapchainKHR on a window object on one VkPhysicalDevice can prevent vkCreateSwapchainKHR from succeeding on the same window object, but on a different VkPhysicalDevice that is associated with a different Vulkan ICD.
In all cases the problem can be worked around by creating a new window object.
Technical details include:
-
Creating a DXGI swapchain over a window object can alter the object for the remainder of its lifetime. The alteration persists even after the DXGI swapchain has been destroyed. This alteration can make it impossible for a conformant Vulkan implementation to create a VkSwapchainKHR over the same window object. Mention of this alteration can be found in the remarks section of the MSDN documentation for
DXGI_SWAP_EFFECT
. -
Calling GDI’s
SetPixelFormat
(needed by OpenGL’s WGL layer) on a window object alters the object for the remainder of its lifetime. The MSDN documentation forSetPixelFormat
explains that a window object’s pixel format can be set only one time. -
Creating a VkSwapchainKHR over a window object can alter the object for the remaining life of its lifetime. Either of the above alterations may occur as a side-effect of VkSwapchainKHR.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for win32 desktops.
-
-
Revision 3, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface.
-
-
Revision 4, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateWin32SurfaceKHR.
-
-
Revision 5, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
-
Revision 6, 2017-04-24 (Jeff Juliano)
-
Add issue 2 addressing reuse of a native window object in a different Graphics API, or by a different Vulkan ICD.
-
VK_KHR_workgroup_memory_explicit_layout
- Name String
-
VK_KHR_workgroup_memory_explicit_layout
- Extension Type
-
Device extension
- Registered Extension Number
-
337
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Caio Marcelo de Oliveira Filho cmarcelo
-
Other Extension Metadata
- Last Modified Date
-
2020-06-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_workgroup_memory_explicit_layout
-
- Contributors
-
-
Caio Marcelo de Oliveira Filho, Intel
-
Jeff Bolz, NVIDIA
-
Graeme Leese, Broadcom
-
Jason Ekstrand, Intel
-
Daniel Koch, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_KHR_workgroup_memory_explicit_layout
SPIR-V extension, which allows shaders to explicitly define the layout of
Workgroup
storage class memory and create aliases between variables
from that storage class in a compute shader.
The aliasing feature allows different "views" on the same data, so the shader can bulk copy data from another storage class using one type (e.g. an array of large vectors), and then use the data with a more specific type. It also enables reducing the amount of workgroup memory consumed by allowing the shader to alias data whose lifetimes don’t overlap.
The explicit layout support and some form of aliasing is also required for layering OpenCL on top of Vulkan.
New Enum Constants
-
VK_KHR_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_EXTENSION_NAME
-
VK_KHR_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_WORKGROUP_MEMORY_EXPLICIT_LAYOUT_FEATURES_KHR
-
VK_KHR_xcb_surface
- Name String
-
VK_KHR_xcb_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
6
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_xcb_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an X11 Window
, using
the XCB client-side library, as well as a query to determine support for
rendering via XCB.
New Enum Constants
-
VK_KHR_XCB_SURFACE_EXTENSION_NAME
-
VK_KHR_XCB_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does XCB need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR: If it returned
VK_TRUE
, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for an (xcb_connection_t*, xcb_visualid_t) pair.
-
Removed "root" parameter from CreateXcbSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Removed "root" parameter from CreateXcbSurfaceKHR() in one more place.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xcb_surface to VK_KHR_xcb_surface.
-
-
Revision 5, 2015-10-23 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXcbSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_KHR_xlib_surface
- Name String
-
VK_KHR_xlib_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
5
- Revision
-
6
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jesse Hall critsec
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2015-11-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Patrick Doane, Blizzard
-
Jason Ekstrand, Intel
-
Ian Elliott, LunarG
-
Courtney Goeltzenleuchter, LunarG
-
Jesse Hall, Google
-
James Jones, NVIDIA
-
Antoine Labour, Google
-
Jon Leech, Khronos
-
David Mao, AMD
-
Norbert Nopper, Freescale
-
Alon Or-bach, Samsung
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Ray Smith, ARM
-
Jeff Vigil, Qualcomm
-
Chia-I Wu, LunarG
-
Description
The VK_KHR_xlib_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to an X11 Window
, using
the Xlib client-side library, as well as a query to determine support for
rendering via Xlib.
New Enum Constants
-
VK_KHR_XLIB_SURFACE_EXTENSION_NAME
-
VK_KHR_XLIB_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR
-
Issues
1) Does X11 need a way to query for compatibility between a particular
physical device and a specific screen? This would be a more general query
than vkGetPhysicalDeviceSurfaceSupportKHR; if it returned
VK_TRUE
, then the physical device could be assumed to support
presentation to any window on that screen.
RESOLVED: Yes, this is needed for toolkits that want to create a VkDevice before creating a window. To ensure the query is reliable, it must be made against a particular X visual rather than the screen in general.
Version History
-
Revision 1, 2015-09-23 (Jesse Hall)
-
Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
-
-
Revision 2, 2015-10-02 (James Jones)
-
Added presentation support query for (Display*, VisualID) pair.
-
Removed "root" parameter from CreateXlibSurfaceKHR(), as it is redundant when a window on the same screen is specified as well.
-
Added appropriate X errors.
-
Adjusted wording of issue #1 and added agreed upon resolution.
-
-
Revision 3, 2015-10-14 (Ian Elliott)
-
Renamed this extension from VK_EXT_KHR_x11_surface to VK_EXT_KHR_xlib_surface.
-
-
Revision 4, 2015-10-26 (Ian Elliott)
-
Renamed from VK_EXT_KHR_xlib_surface to VK_KHR_xlib_surface.
-
-
Revision 5, 2015-11-03 (Daniel Rakos)
-
Added allocation callbacks to vkCreateXlibSurfaceKHR.
-
-
Revision 6, 2015-11-28 (Daniel Rakos)
-
Updated the surface create function to take a pCreateInfo structure.
-
VK_KHR_zero_initialize_workgroup_memory
- Name String
-
VK_KHR_zero_initialize_workgroup_memory
- Extension Type
-
Device extension
- Registered Extension Number
-
326
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Alan Baker alan-baker
-
- Last Modified Date
-
2020-11-18
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
None
- Contributors
-
-
Alan Baker, Google
-
Jeff Bolz, Nvidia
-
Jason Ekstrand, Intel
-
This extension allows the use of a null constant initializer on shader Workgroup memory variables, allowing implementations to expose any special hardware or instructions they may have. Zero initialization is commonly used by applications running untrusted content (e.g. web browsers) as way of defeating memory-scraping attacks.
New Enum Constants
-
VK_KHR_ZERO_INITIALIZE_WORKGROUP_MEMORY_EXTENSION_NAME
-
VK_KHR_ZERO_INITIALIZE_WORKGROUP_MEMORY_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ZERO_INITIALIZE_WORKGROUP_MEMORY_FEATURES_KHR
-
VK_EXT_4444_formats
- Name String
-
VK_EXT_4444_formats
- Extension Type
-
Device extension
- Registered Extension Number
-
341
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Joshua Ashton Joshua-Ashton
-
Other Extension Metadata
- Last Modified Date
-
2020-07-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Jason Ekstrand, Intel
-
Description
This extension defines the VK_FORMAT_A4R4G4B4_UNORM_PACK16_EXT
and
VK_FORMAT_A4B4G4R4_UNORM_PACK16_EXT
formats which are defined in other
current graphics APIs.
This extension may be useful for building translation layers for those APIs or for porting applications that use these formats without having to resort to swizzles.
When VK_EXT_custom_border_color is used, these formats are not subject to the same restrictions for border color without format as with VK_FORMAT_B4G4R4A4_UNORM_PACK16.
New Enum Constants
-
VK_EXT_4444_FORMATS_EXTENSION_NAME
-
VK_EXT_4444_FORMATS_SPEC_VERSION
-
Extending VkFormat:
-
VK_FORMAT_A4B4G4R4_UNORM_PACK16_EXT
-
VK_FORMAT_A4R4G4B4_UNORM_PACK16_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_4444_FORMATS_FEATURES_EXT
-
VK_EXT_acquire_xlib_display
- Name String
-
VK_EXT_acquire_xlib_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
90
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_EXT_direct_mode_display
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Dave Airlie, Red Hat
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
Daniel Vetter, Intel
-
Description
This extension allows an application to take exclusive control on a display currently associated with an X11 screen. When control is acquired, the display will be deassociated from the X11 screen until control is released or the specified display connection is closed. Essentially, the X11 screen will behave as if the monitor has been unplugged until control is released.
New Enum Constants
-
VK_EXT_ACQUIRE_XLIB_DISPLAY_EXTENSION_NAME
-
VK_EXT_ACQUIRE_XLIB_DISPLAY_SPEC_VERSION
Issues
1) Should vkAcquireXlibDisplayEXT take an RandR display ID, or a Vulkan display handle as input?
RESOLVED: A Vulkan display handle. Otherwise there would be no way to specify handles to displays that had been prevented from being included in the X11 display list by some native platform or vendor-specific mechanism.
2) How does an application figure out which RandR display corresponds to a Vulkan display?
RESOLVED: A new function, vkGetRandROutputDisplayEXT, is introduced for this purpose.
3) Should vkGetRandROutputDisplayEXT be part of this extension, or a general Vulkan / RandR or Vulkan / Xlib extension?
RESOLVED: To avoid yet another extension, include it in this extension.
VK_EXT_astc_decode_mode
- Name String
-
VK_EXT_astc_decode_mode
- Extension Type
-
Device extension
- Registered Extension Number
-
68
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Description
The existing specification requires that low dynamic range (LDR) ASTC textures are decompressed to FP16 values per component. In many cases, decompressing LDR textures to a lower precision intermediate result gives acceptable image quality. Source material for LDR textures is typically authored as 8-bit UNORM values, so decoding to FP16 values adds little value. On the other hand, reducing precision of the decoded result reduces the size of the decompressed data, potentially improving texture cache performance and saving power.
The goal of this extension is to enable this efficiency gain on existing ASTC texture data. This is achieved by giving the application the ability to select the intermediate decoding precision.
Three decoding options are provided:
-
Decode to
VK_FORMAT_R16G16B16A16_SFLOAT
precision: This is the default, and matches the required behavior in the core API. -
Decode to
VK_FORMAT_R8G8B8A8_UNORM
precision: This is provided as an option in LDR mode. -
Decode to
VK_FORMAT_E5B9G9R9_UFLOAT_PACK32
precision: This is provided as an option in both LDR and HDR mode. In this mode, negative values cannot be represented and are clamped to zero. The alpha component is ignored, and the results are as if alpha was 1.0. This decode mode is optional and support can be queried via the physical device properties.
New Enum Constants
-
VK_EXT_ASTC_DECODE_MODE_EXTENSION_NAME
-
VK_EXT_ASTC_DECODE_MODE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT
-
Issues
1) Are implementations allowed to decode at a higher precision than what is requested?
RESOLUTION: No. If we allow this, then this extension could be exposed on all implementations that support ASTC. But developers would have no way of knowing what precision was actually used, and thus whether the image quality is sufficient at reduced precision.
2) Should the decode mode be image view state and/or sampler state?
RESOLUTION: Image view state only. Some implementations treat the different decode modes as different texture formats.
Example
Create an image view that decodes to VK_FORMAT_R8G8B8A8_UNORM
precision:
VkImageViewASTCDecodeModeEXT decodeMode =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT, // sType
NULL, // pNext
VK_FORMAT_R8G8B8A8_UNORM // decode mode
};
VkImageViewCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, // sType
&decodeMode, // pNext
// flags, image, viewType set to application-desired values
VK_FORMAT_ASTC_8x8_UNORM_BLOCK, // format
// components, subresourceRange set to application-desired values
};
VkImageView imageView;
VkResult result = vkCreateImageView(
device,
&createInfo,
NULL,
&imageView);
VK_EXT_blend_operation_advanced
- Name String
-
VK_EXT_blend_operation_advanced
- Extension Type
-
Device extension
- Registered Extension Number
-
149
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Description
This extension adds a number of “advanced” blending operations that can be used to perform new color blending operations, many of which are more complex than the standard blend modes provided by unextended Vulkan. This extension requires different styles of usage, depending on the level of hardware support and the enabled features:
-
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperations
isVK_FALSE
, the new blending operations are supported, but a memory dependency must separate each advanced blend operation on a given sample.VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
is used to synchronize reads using advanced blend operations. -
If VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::
advancedBlendCoherentOperations
isVK_TRUE
, advanced blend operations obey primitive order just like basic blend operations.
In unextended Vulkan, the set of blending operations is limited, and can be
expressed very simply.
The VK_BLEND_OP_MIN
and VK_BLEND_OP_MAX
blend operations simply
compute component-wise minimums or maximums of source and destination color
components.
The VK_BLEND_OP_ADD
, VK_BLEND_OP_SUBTRACT
, and
VK_BLEND_OP_REVERSE_SUBTRACT
modes multiply the source and destination
colors by source and destination factors and either add the two products
together or subtract one from the other.
This limited set of operations supports many common blending operations but
precludes the use of more sophisticated transparency and blending operations
commonly available in many dedicated imaging APIs.
This extension provides a number of new “advanced” blending operations.
Unlike traditional blending operations using VK_BLEND_OP_ADD
, these
blending equations do not use source and destination factors specified by
VkBlendFactor.
Instead, each blend operation specifies a complete equation based on the
source and destination colors.
These new blend operations are used for both RGB and alpha components; they
must not be used to perform separate RGB and alpha blending (via different
values of color and alpha VkBlendOp).
These blending operations are performed using premultiplied colors, where
RGB colors can be considered premultiplied or non-premultiplied by alpha,
according to the srcPremultiplied
and dstPremultiplied
members
of VkPipelineColorBlendAdvancedStateCreateInfoEXT.
If a color is considered non-premultiplied, the (R,G,B) color components are
multiplied by the alpha component prior to blending.
For non-premultiplied color components in the range [0,1], the
corresponding premultiplied color component would have values in the range
[0 × A, 1 × A].
Many of these advanced blending equations are formulated where the result of
blending source and destination colors with partial coverage have three
separate contributions: from the portions covered by both the source and the
destination, from the portion covered only by the source, and from the
portion covered only by the destination.
The blend parameter
VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap
can be used to specify a correlation between source and destination pixel
coverage.
If set to VK_BLEND_OVERLAP_CONJOINT_EXT
, the source and destination
are considered to have maximal overlap, as would be the case if drawing two
objects on top of each other.
If set to VK_BLEND_OVERLAP_DISJOINT_EXT
, the source and destination
are considered to have minimal overlap, as would be the case when rendering
a complex polygon tessellated into individual non-intersecting triangles.
If set to VK_BLEND_OVERLAP_UNCORRELATED_EXT
, the source and
destination coverage are assumed to have no spatial correlation within the
pixel.
In addition to the coherency issues on implementations not supporting
advancedBlendCoherentOperations
, this extension has several
limitations worth noting.
First, the new blend operations have a limit on the number of color
attachments they can be used with, as indicated by
VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendMaxColorAttachments
.
Additionally, blending precision may be limited to 16-bit floating-point,
which may result in a loss of precision and dynamic range for framebuffer
formats with 32-bit floating-point components, and in a loss of precision
for formats with 12- and 16-bit signed or unsigned normalized integer
components.
New Enum Constants
-
VK_EXT_BLEND_OPERATION_ADVANCED_EXTENSION_NAME
-
VK_EXT_BLEND_OPERATION_ADVANCED_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT
-
-
Extending VkBlendOp:
-
VK_BLEND_OP_BLUE_EXT
-
VK_BLEND_OP_COLORBURN_EXT
-
VK_BLEND_OP_COLORDODGE_EXT
-
VK_BLEND_OP_CONTRAST_EXT
-
VK_BLEND_OP_DARKEN_EXT
-
VK_BLEND_OP_DIFFERENCE_EXT
-
VK_BLEND_OP_DST_ATOP_EXT
-
VK_BLEND_OP_DST_EXT
-
VK_BLEND_OP_DST_IN_EXT
-
VK_BLEND_OP_DST_OUT_EXT
-
VK_BLEND_OP_DST_OVER_EXT
-
VK_BLEND_OP_EXCLUSION_EXT
-
VK_BLEND_OP_GREEN_EXT
-
VK_BLEND_OP_HARDLIGHT_EXT
-
VK_BLEND_OP_HARDMIX_EXT
-
VK_BLEND_OP_HSL_COLOR_EXT
-
VK_BLEND_OP_HSL_HUE_EXT
-
VK_BLEND_OP_HSL_LUMINOSITY_EXT
-
VK_BLEND_OP_HSL_SATURATION_EXT
-
VK_BLEND_OP_INVERT_EXT
-
VK_BLEND_OP_INVERT_OVG_EXT
-
VK_BLEND_OP_INVERT_RGB_EXT
-
VK_BLEND_OP_LIGHTEN_EXT
-
VK_BLEND_OP_LINEARBURN_EXT
-
VK_BLEND_OP_LINEARDODGE_EXT
-
VK_BLEND_OP_LINEARLIGHT_EXT
-
VK_BLEND_OP_MINUS_CLAMPED_EXT
-
VK_BLEND_OP_MINUS_EXT
-
VK_BLEND_OP_MULTIPLY_EXT
-
VK_BLEND_OP_OVERLAY_EXT
-
VK_BLEND_OP_PINLIGHT_EXT
-
VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT
-
VK_BLEND_OP_PLUS_CLAMPED_EXT
-
VK_BLEND_OP_PLUS_DARKER_EXT
-
VK_BLEND_OP_PLUS_EXT
-
VK_BLEND_OP_RED_EXT
-
VK_BLEND_OP_SCREEN_EXT
-
VK_BLEND_OP_SOFTLIGHT_EXT
-
VK_BLEND_OP_SRC_ATOP_EXT
-
VK_BLEND_OP_SRC_EXT
-
VK_BLEND_OP_SRC_IN_EXT
-
VK_BLEND_OP_SRC_OUT_EXT
-
VK_BLEND_OP_SRC_OVER_EXT
-
VK_BLEND_OP_VIVIDLIGHT_EXT
-
VK_BLEND_OP_XOR_EXT
-
VK_BLEND_OP_ZERO_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT
-
Version History
-
Revision 1, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
-
Revision 2, 2017-06-12 (Jeff Bolz)
-
Internal revisions
-
VK_EXT_calibrated_timestamps
- Name String
-
VK_EXT_calibrated_timestamps
- Extension Type
-
Device extension
- Registered Extension Number
-
185
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-10-04
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Alan Harrison, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
Jason Ekstrand, Intel
-
Keith Packard, Valve
-
Description
This extension provides an interface to query calibrated timestamps obtained quasi simultaneously from two time domains.
New Enum Constants
-
VK_EXT_CALIBRATED_TIMESTAMPS_EXTENSION_NAME
-
VK_EXT_CALIBRATED_TIMESTAMPS_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT
-
Issues
1) Is the device timestamp value returned in the same time domain as the timestamp values written by vkCmdWriteTimestamp?
RESOLVED: Yes.
2) What time domain is the host timestamp returned in?
RESOLVED: A query is provided to determine the calibrateable time domains. The expected host time domain used on Windows is that of QueryPerformanceCounter, and on Linux that of CLOCK_MONOTONIC.
3) Should we support other time domain combinations than just one host and the device time domain?
RESOLVED: Supporting that would need the application to query the set of supported time domains, while supporting only one host and the device time domain would only need a query for the host time domain type. The proposed API chooses the general approach for the sake of extensibility.
4) Shouldn’t we use CLOCK_MONOTONIC_RAW instead of CLOCK_MONOTONIC?
RESOLVED: CLOCK_MONOTONIC is usable in a wider set of situations, however, it is subject to NTP adjustments so some use cases may prefer CLOCK_MONOTONIC_RAW. Thus this extension allows both to be exposed.
5) How can the application extrapolate future device timestamp values from the calibrated timestamp value?
RESOLVED: VkPhysicalDeviceLimits::timestampPeriod
makes it
possible to calculate future device timestamps as follows:
futureTimestamp = calibratedTimestamp + deltaNanoseconds / timestampPeriod
6) Can the host and device timestamp values drift apart over longer periods of time?
RESOLVED: Yes, especially as some time domains by definition allow for that to happen (e.g. CLOCK_MONOTONIC is subject to NTP adjustments). Thus it’s recommended that applications re-calibrate from time to time.
7) Should we add a query for reporting the maximum deviation of the timestamp values returned by calibrated timestamp queries?
RESOLVED: A global query seems inappropriate and difficult to enforce. However, it’s possible to return the maximum deviation any single calibrated timestamp query can have by sampling one of the time domains twice as follows:
timestampX = timestampX_before = SampleTimeDomain(X)
for each time domain Y != X
timestampY = SampleTimeDomain(Y)
timestampX_after = SampleTimeDomain(X)
maxDeviation = timestampX_after - timestampX_before
8) Can the maximum deviation reported ever be zero?
RESOLVED: Unless the tick of each clock corresponding to the set of time domains coincides and all clocks can literally be sampled simutaneously, there isn’t really a possibility for the maximum deviation to be zero, so by convention the maximum deviation is always at least the maximum of the length of the ticks of the set of time domains calibrated and thus can never be zero.
VK_EXT_conditional_rendering
- Name String
-
VK_EXT_conditional_rendering
- Extension Type
-
Device extension
- Registered Extension Number
-
82
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
Other Extension Metadata
- Last Modified Date
-
2018-05-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Daniel Rakos, AMD
-
Jesse Hall, Google
-
Jeff Bolz, NVIDIA
-
Piers Daniell, NVIDIA
-
Stuart Smith, Imagination Technologies
-
Description
This extension allows the execution of one or more rendering commands to be conditional on a value in buffer memory. This may help an application reduce the latency by conditionally discarding rendering commands without application intervention. The conditional rendering commands are limited to draws, compute dispatches and clearing attachments within a conditional rendering block.
New Enum Constants
-
VK_EXT_CONDITIONAL_RENDERING_EXTENSION_NAME
-
VK_EXT_CONDITIONAL_RENDERING_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_CONDITIONAL_RENDERING_READ_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_CONDITIONAL_RENDERING_INFO_EXT
-
VK_STRUCTURE_TYPE_CONDITIONAL_RENDERING_BEGIN_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONDITIONAL_RENDERING_FEATURES_EXT
-
Issues
1) Should conditional rendering affect copy and blit commands?
RESOLVED: Conditional rendering should not affect copies and blits.
2) Should secondary command buffers be allowed to execute while conditional rendering is active in the primary command buffer?
RESOLVED: The rendering commands in secondary command buffer will be
affected by an active conditional rendering in primary command buffer if the
conditionalRenderingEnable
is set to VK_TRUE
.
Conditional rendering must not be active in the primary command buffer if
conditionalRenderingEnable
is VK_FALSE
.
Version History
-
Revision 1, 2018-04-19 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-05-21 (Vikram Kushwaha)
-
Add new pipeline stage, access flags and limit conditional rendering to a subpass or entire renderpass.
-
VK_EXT_conservative_rasterization
- Name String
-
VK_EXT_conservative_rasterization
- Extension Type
-
Device extension
- Registered Extension Number
-
102
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-06-09
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_fully_covered
if theVkPhysicalDeviceConservativeRasterizationPropertiesEXT
::fullyCoveredFragmentShaderInputVariable
feature is used. -
This extension requires
SPV_KHR_post_depth_coverage
if theVkPhysicalDeviceConservativeRasterizationPropertiesEXT
::conservativeRasterizationPostDepthCoverage
feature is used. -
This extension provides API support for
GL_NV_conservative_raster_underestimation
if theVkPhysicalDeviceConservativeRasterizationPropertiesEXT
::fullyCoveredFragmentShaderInputVariable
feature is used.
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
Description
This extension adds a new rasterization mode called conservative rasterization. There are two modes of conservative rasterization; overestimation and underestimation.
When overestimation is enabled, if any part of the primitive, including its edges, covers any part of the rectangular pixel area, including its sides, then a fragment is generated with all coverage samples turned on. This extension allows for some variation in implementations by accounting for differences in overestimation, where the generating primitive size is increased at each of its edges by some sub-pixel amount to further increase conservative pixel coverage. Implementations can allow the application to specify an extra overestimation beyond the base overestimation the implementation already does. It also allows implementations to either cull degenerate primitives or rasterize them.
When underestimation is enabled, fragments are only generated if the rectangular pixel area is fully covered by the generating primitive. If supported by the implementation, when a pixel rectangle is fully covered the fragment shader input variable builtin called FullyCoveredEXT is set to true. The shader variable works in either overestimation or underestimation mode.
Implementations can process degenerate triangles and lines by either discarding them or generating conservative fragments for them. Degenerate triangles are those that end up with zero area after the rasterizer quantizes them to the fixed-point pixel grid. Degenerate lines are those with zero length after quantization.
New Enum Constants
-
VK_EXT_CONSERVATIVE_RASTERIZATION_EXTENSION_NAME
-
VK_EXT_CONSERVATIVE_RASTERIZATION_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CONSERVATIVE_RASTERIZATION_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_CONSERVATIVE_STATE_CREATE_INFO_EXT
-
Version History
-
Revision 1.1, 2020-09-06 (Piers Daniell)
-
Add missing SPIR-V and GLSL dependencies.
-
-
Revision 1, 2017-08-28 (Piers Daniell)
-
Internal revisions
-
VK_EXT_custom_border_color
- Name String
-
VK_EXT_custom_border_color
- Extension Type
-
Device extension
- Registered Extension Number
-
288
- Revision
-
12
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Liam Middlebrook liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2020-04-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Joshua Ashton, Valve
-
Hans-Kristian Arntzen, Valve
-
Philip Rebohle, Valve
-
Liam Middlebrook, NVIDIA
-
Jeff Bolz, NVIDIA
-
Tobias Hector, AMD
-
Jason Ekstrand, Intel
-
Spencer Fricke, Samsung Electronics
-
Graeme Leese, Broadcom
-
Jesse Hall, Google
-
Jan-Harald Fredriksen, ARM
-
Tom Olson, ARM
-
Stuart Smith, Imagination Technologies
-
Donald Scorgie, Imagination Technologies
-
Alex Walters, Imagination Technologies
-
Peter Quayle, Imagination Technologies
-
Description
This extension provides cross-vendor functionality to specify a custom
border color for use when the sampler address mode
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
is used.
To create a sampler which uses a custom border color set
VkSamplerCreateInfo::borderColor
to one of:
-
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT
-
VK_BORDER_COLOR_INT_CUSTOM_EXT
When VK_BORDER_COLOR_FLOAT_CUSTOM_EXT
or
VK_BORDER_COLOR_INT_CUSTOM_EXT
is used, applications must provide a
VkSamplerCustomBorderColorCreateInfoEXT in the pNext chain for
VkSamplerCreateInfo.
New Enum Constants
-
VK_EXT_CUSTOM_BORDER_COLOR_EXTENSION_NAME
-
VK_EXT_CUSTOM_BORDER_COLOR_SPEC_VERSION
-
Extending VkBorderColor:
-
VK_BORDER_COLOR_FLOAT_CUSTOM_EXT
-
VK_BORDER_COLOR_INT_CUSTOM_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_CUSTOM_BORDER_COLOR_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT
-
Issues
1) Should VkClearColorValue be used for the border color value, or should we have our own struct/union? Do we need to specify the type of the input values for the components? This is more of a concern if VkClearColorValue is used here because it provides a union of float,int,uint types.
RESOLVED: Will re-use existing VkClearColorValue structure in order to easily take advantage of float,int,uint borderColor types.
2) For hardware which supports a limited number of border colors what happens if that number is exceeded? Should this be handled by the driver unbeknownst to the application? In Revision 1 we had solved this issue using a new Object type, however that may have lead to additional system resource consumption which would otherwise not be required.
RESOLVED: Added
VkPhysicalDeviceCustomBorderColorPropertiesEXT
::maxCustomBorderColorSamplers
for tracking implementation-specific limit, and Valid Usage
statement handling overflow.
3) Should this be supported for immutable samplers at all, or by a feature bit? Some implementations may not be able to support custom border colors on immutable samplers — is it worthwhile enabling this to work on them for implementations that can support it, or forbidding it entirely.
RESOLVED: Samplers created with a custom border color are forbidden from being immutable. This resolves concerns for implementations where the custom border color is an index to a LUT instead of being directly embedded into sampler state.
4) Should UINT and SINT (unsigned integer and signed integer) border color types be separated or should they be combined into one generic INT (integer) type?
RESOLVED: Separating these doesn’t make much sense as the existing fixed border color types don’t have this distinction, and there is no reason in hardware to do so. This separation would also create unnecessary work and considerations for the application.
Version History
-
Revision 1, 2019-10-10 (Joshua Ashton)
-
Internal revisions.
-
-
Revision 2, 2019-10-11 (Liam Middlebrook)
-
Remove VkCustomBorderColor object and associated functions
-
Add issues concerning HW limitations for custom border color count
-
-
Revision 3, 2019-10-12 (Joshua Ashton)
-
Re-expose the limits for the maximum number of unique border colors
-
Add extra details about border color tracking
-
Fix typos
-
-
Revision 4, 2019-10-12 (Joshua Ashton)
-
Changed maxUniqueCustomBorderColors to a uint32_t from a VkDeviceSize
-
-
Revision 5, 2019-10-14 (Liam Middlebrook)
-
Added features bit
-
-
Revision 6, 2019-10-15 (Joshua Ashton)
-
Type-ize VK_BORDER_COLOR_CUSTOM
-
Fix const-ness on pNext of VkSamplerCustomBorderColorCreateInfoEXT
-
-
Revision 7, 2019-11-26 (Liam Middlebrook)
-
Renamed maxUniqueCustomBorderColors to maxCustomBorderColors
-
-
Revision 8, 2019-11-29 (Joshua Ashton)
-
Renamed borderColor member of VkSamplerCustomBorderColorCreateInfoEXT to customBorderColor
-
-
Revision 9, 2020-02-19 (Joshua Ashton)
-
Renamed maxCustomBorderColors to maxCustomBorderColorSamplers
-
-
Revision 10, 2020-02-21 (Joshua Ashton)
-
Added format to VkSamplerCustomBorderColorCreateInfoEXT and feature bit
-
-
Revision 11, 2020-04-07 (Joshua Ashton)
-
Dropped UINT/SINT border color differences, consolidated types
-
-
Revision 12, 2020-04-16 (Joshua Ashton)
-
Renamed VK_BORDER_COLOR_CUSTOM_FLOAT_EXT to VK_BORDER_COLOR_FLOAT_CUSTOM_EXT for consistency
-
VK_EXT_debug_utils
- Name String
-
VK_EXT_debug_utils
- Extension Type
-
Instance extension
- Registered Extension Number
-
129
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Mark Young marky-lunarg
-
Other Extension Metadata
- Last Modified Date
-
2020-04-03
- Revision
-
2
- IP Status
-
No known IP claims.
- Dependencies
-
-
This extension is written against version 1.0 of the Vulkan API.
-
Requires VkObjectType
-
- Contributors
-
-
Mark Young, LunarG
-
Baldur Karlsson
-
Ian Elliott, Google
-
Courtney Goeltzenleuchter, Google
-
Karl Schultz, LunarG
-
Mark Lobodzinski, LunarG
-
Mike Schuchardt, LunarG
-
Jaakko Konttinen, AMD
-
Dan Ginsburg, Valve Software
-
Rolando Olivares, Epic Games
-
Dan Baker, Oxide Games
-
Kyle Spagnoli, NVIDIA
-
Jon Ashburn, LunarG
-
Piers Daniell, NVIDIA
-
Description
Due to the nature of the Vulkan interface, there is very little error
information available to the developer and application.
By using the VK_EXT_debug_utils
extension, developers can obtain more
information.
When combined with validation layers, even more detailed feedback on the
application’s use of Vulkan will be provided.
This extension provides the following capabilities:
-
The ability to create a debug messenger which will pass along debug messages to an application supplied callback.
-
The ability to identify specific Vulkan objects using a name or tag to improve tracking.
-
The ability to identify specific sections within a
VkQueue
orVkCommandBuffer
using labels to aid organization and offline analysis in external tools.
The main difference between this extension and VK_EXT_debug_report
and
VK_EXT_debug_marker
is that those extensions use
VkDebugReportObjectTypeEXT to identify objects.
This extension uses the core VkObjectType in place of
VkDebugReportObjectTypeEXT.
The primary reason for this move is that no future object type handle
enumeration values will be added to VkDebugReportObjectTypeEXT since
the creation of VkObjectType.
In addition, this extension combines the functionality of both
VK_EXT_debug_report
and VK_EXT_debug_marker
by allowing object
name and debug markers (now called labels) to be returned to the
application’s callback function.
This should assist in clarifying the details of a debug message including:
what objects are involved and potentially which location within a
VkQueue or VkCommandBuffer the message occurred.
New Enum Constants
-
VK_EXT_DEBUG_UTILS_EXTENSION_NAME
-
VK_EXT_DEBUG_UTILS_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT
-
Examples
Example 1
VK_EXT_debug_utils
allows an application to register multiple callbacks
with any Vulkan component wishing to report debug information.
Some callbacks may log the information to a file, others may cause a debug
break point or other application defined behavior.
An application can register callbacks even when no validation layers are
enabled, but they will only be called for loader and, if implemented, driver
events.
To capture events that occur while creating or destroying an instance an
application can link a VkDebugUtilsMessengerCreateInfoEXT structure
to the pNext
element of the VkInstanceCreateInfo structure given
to vkCreateInstance.
This callback is only valid for the duration of the vkCreateInstance
and the vkDestroyInstance call.
Use vkCreateDebugUtilsMessengerEXT to create persistent callback
objects.
Example uses: Create three callback objects.
One will log errors and warnings to the debug console using Windows
OutputDebugString
.
The second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
extern VkInstance instance;
VkResult res;
VkDebugUtilsMessengerEXT cb1, cb2, cb3;
// Must call extension functions through a function pointer:
PFN_vkCreateDebugUtilsMessengerEXT pfnCreateDebugUtilsMessengerEXT = (PFN_vkCreateDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkCreateDebugUtilsMessengerEXT");
PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkDestroyDebugUtilsMessengerEXT");
VkDebugUtilsMessengeCreateInfoEXT callback1 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT | // messageSeverity
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
myOutputDebugString, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb1);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
callback1.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
callback1.pfnCallback = myDebugBreak;
callback1.pUserData = NULL;
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb2);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
VkDebugUtilsMessengerCreateInfoEXT callback3 = {
VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT, // sType
NULL, // pNext
0, // flags
VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT, // messageSeverity
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | // messageType
VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
mystdOutLogger, // pfnUserCallback
NULL // pUserData
};
res = pfnCreateDebugUtilsMessengerEXT(instance, &callback3, NULL, &cb3);
if (res != VK_SUCCESS) {
// Do error handling for VK_ERROR_OUT_OF_MEMORY
}
...
// Remove callbacks when cleaning up
pfnDestroyDebugUtilsMessengerEXT(instance, cb1, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb2, NULL);
pfnDestroyDebugUtilsMessengerEXT(instance, cb3, NULL);
Example 2
Associate a name with an image, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages.
extern VkInstance instance;
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetInstanceProcAddr(instance, "vkSetDebugUtilsObjectNameEXT");
// Set a name on the image
const VkDebugUtilsObjectNameInfoEXT imageNameInfo =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, // sType
NULL, // pNext
VK_OBJECT_TYPE_IMAGE, // objectType
(uint64_t)image, // object
"Brick Diffuse Texture", // pObjectName
};
pfnSetDebugUtilsObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
Example 3
Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualization of the commands submitted.
extern VkInstance instance;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueBeginDebugUtilsLabelEXT");
PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueEndDebugUtilsLabelEXT");
PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdBeginDebugUtilsLabelEXT");
PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdEndDebugUtilsLabelEXT");
PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdInsertDebugUtilsLabelEXT");
// Describe the area being rendered
const VkDebugUtilsLabelEXT houseLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Brick House", // pLabelName
{ 1.0f, 0.0f, 0.0f, 1.0f }, // color
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
{
// A mutable structure for each part being rendered
VkDebugUtilsLabelEXT housePartLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
NULL, // pLabelName
{ 0.0f, 0.0f, 0.0f, 0.0f }, // color
};
// Set the name and insert the marker
housePartLabel.pLabelName = "Walls";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartLabel.pLabelName = "Windows";
pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
housePartLabel.pLabelName = "Front Door";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartLabel.pLabelName = "Roof";
pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
// Do other work
vkEndCommandBuffer(commandBuffer);
// Describe the queue being used
const VkDebugUtilsLabelEXT queueLabel =
{
VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
NULL, // pNext
"Main Render Work", // pLabelName
{ 0.0f, 1.0f, 0.0f, 1.0f }, // color
};
// Identify the queue label region
pfnQueueBeginDebugUtilsLabelEXT(queue, &queueLabel);
// Submit the work for the main render thread
const VkCommandBuffer cmd_bufs[] = {commandBuffer};
VkSubmitInfo submit_info = {.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
.pNext = NULL,
.waitSemaphoreCount = 0,
.pWaitSemaphores = NULL,
.pWaitDstStageMask = NULL,
.commandBufferCount = 1,
.pCommandBuffers = cmd_bufs,
.signalSemaphoreCount = 0,
.pSignalSemaphores = NULL};
vkQueueSubmit(queue, 1, &submit_info, fence);
// End the queue label region
pfnQueueEndDebugUtilsLabelEXT(queue);
Issues
1) Should we just name this extension VK_EXT_debug_report2
RESOLVED: No. There is enough additional changes to the structures to break backwards compatibility. So, a new name was decided that would not indicate any interaction with the previous extension.
2) Will validation layers immediately support all the new features.
RESOLVED: Not immediately.
As one can imagine, there is a lot of work involved with converting the
validation layer logging over to the new functionality.
Basic logging, as seen in the origin VK_EXT_debug_report
extension
will be made available immediately.
However, adding the labels and object names will take time.
Since the priority for Khronos at this time is to continue focusing on Valid
Usage statements, it may take a while before the new functionality is fully
exposed.
3) If the validation layers won’t expose the new functionality immediately, then what’s the point of this extension?
RESOLVED: We needed a replacement for VK_EXT_debug_report
because
the VkDebugReportObjectTypeEXT enumeration will no longer be updated
and any new objects will need to be debugged using the new functionality
provided by this extension.
4) Should this extension be split into two separate parts (1 extension that is an instance extension providing the callback functionality, and another device extension providing the general debug marker and annotation functionality)?
RESOLVED: No, the functionality for this extension is too closely related. If we did split up the extension, where would the structures and enums live, and how would you define that the device behavior in the instance extension is really only valid if the device extension is enabled, and the functionality is passed in. It’s cleaner to just define this all as an instance extension, plus it allows the application to enable all debug functionality provided with one enable string during vkCreateInstance.
Version History
-
Revision 1, 2017-09-14 (Mark Young and all listed Contributors)
-
Initial draft, based on
VK_EXT_debug_report
andVK_EXT_debug_marker
in addition to previous feedback supplied from various companies including Valve, Epic, and Oxide games.
-
-
Revision 2, 2020-04-03 (Mark Young and Piers Daniell)
-
Updated to allow either
NULL
or an empty string to be passed in forpObjectName
inVkDebugUtilsObjectNameInfoEXT
, because the loader and various drivers supportNULL
already.
-
VK_EXT_depth_clip_enable
- Name String
-
VK_EXT_depth_clip_enable
- Extension Type
-
Device extension
- Registered Extension Number
-
103
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-12-20
- Contributors
-
-
Daniel Rakos, AMD
-
Henri Verbeet, CodeWeavers
-
Jeff Bolz, NVIDIA
-
Philip Rebohle, DXVK
-
Tobias Hector, AMD
-
Description
This extension allows the depth clipping operation, that is normally
implicitly controlled by
VkPipelineRasterizationStateCreateInfo::depthClampEnable
, to
instead be controlled explicitly by
VkPipelineRasterizationDepthClipStateCreateInfoEXT::depthClipEnable
.
This is useful for translating DX content which assumes depth clamping is always enabled, but depth clip can be controlled by the DepthClipEnable rasterization state (D3D12_RASTERIZER_DESC).
New Enum Constants
-
VK_EXT_DEPTH_CLIP_ENABLE_EXTENSION_NAME
-
VK_EXT_DEPTH_CLIP_ENABLE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEPTH_CLIP_ENABLE_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT
-
VK_EXT_depth_range_unrestricted
- Name String
-
VK_EXT_depth_range_unrestricted
- Extension Type
-
Device extension
- Registered Extension Number
-
14
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2017-06-22
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension removes the VkViewport minDepth
and
maxDepth
restrictions that the values must be between 0.0
and 1.0
,
inclusive.
It also removes the same restriction on
VkPipelineDepthStencilStateCreateInfo minDepthBounds
and
maxDepthBounds
.
Finally it removes the restriction on the depth
value in
VkClearDepthStencilValue.
New Enum Constants
-
VK_EXT_DEPTH_RANGE_UNRESTRICTED_EXTENSION_NAME
-
VK_EXT_DEPTH_RANGE_UNRESTRICTED_SPEC_VERSION
Issues
1) How do VkViewport minDepth
and maxDepth
values outside
of the 0.0
to 1.0
range interact with
Primitive Clipping?
RESOLVED: The behavior described in Primitive
Clipping still applies.
If depth clamping is disabled the depth values are still clipped to 0
≤ zc ≤ wc before the viewport transform.
If depth clamping is enabled the above equation is ignored and the depth
values are instead clamped to the VkViewport minDepth
and
maxDepth
values, which in the case of this extension can be outside of
the 0.0
to 1.0
range.
2) What happens if a resulting depth fragment is outside of the 0.0
to
1.0
range and the depth buffer is fixed-point rather than floating-point?
RESOLVED: The supported range of a fixed-point depth buffer is 0.0
to
1.0
and depth fragments are clamped to this range.
VK_EXT_device_memory_report
- Name String
-
VK_EXT_device_memory_report
- Extension Type
-
Device extension
- Registered Extension Number
-
285
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Yiwei Zhang zhangyiwei
-
Other Extension Metadata
- Last Modified Date
-
2021-01-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Yiwei Zhang, Google
-
Jesse Hall, Google
-
Description
This device extension allows registration of device memory event callbacks upon device creation, so that applications or middleware can obtain detailed information about memory usage and how memory is associated with Vulkan objects. This extension exposes the actual underlying device memory usage, including allocations that are not normally visible to the application, such as memory consumed by vkCreateGraphicsPipelines. It is intended primarily for use by debug tooling rather than for production applications.
New Enum Constants
-
VK_EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME
-
VK_EXT_DEVICE_MEMORY_REPORT_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_DEVICE_MEMORY_REPORT_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_DEVICE_MEMORY_REPORT_CALLBACK_DATA_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DEVICE_MEMORY_REPORT_FEATURES_EXT
-
Issues
1) Should this be better expressed as an extension to VK_EXT_debug_utils and its general purpose messenger construct?
RESOLVED: No.
The intended lifecycle is quite different.
We want to make this extension tied to the device’s lifecycle.
Each ICD just handles its own implementation of this extension, and this
extension will only be directly exposed from the ICD.
So we can avoid the extra implementation complexity used to accommodate the
flexibility of VK_EXT_debug_utils
extension.
2) Can we extend and use the existing internal allocation callbacks instead of adding the new callback structure in this extension?
RESOLVED: No.
Our memory reporting layer that combines this information with other memory
info it collects directly (e.g. bindings of resources to
VkDeviceMemory) would have to intercept all entry points that take a
VkAllocationCallbacks parameter and inject its own
pfnInternalAllocation
and pfnInternalFree
.
That’s maybe doable for the extensions we know about, but not for ones we
don’t.
The proposal would work fine in the face of most unknown extensions.
But even for ones we know about, since apps can provide a different set of
callbacks and userdata and those can be retained by the driver and used
later (esp.
for pool object, but not just those), we’d have to dynamically allocate the
interception trampoline every time.
That’s getting to be an unreasonably large amount of complexity and
(possibly) overhead.
We’re interested in both alloc/free and import/unimport.
The latter is fairly important for tracking (and avoiding double-counting)
of swapchain images (still true with "native swapchains" based on external
memory) and media/camera interop.
Though we might be able to handle this with additional
VkInternalAllocationType values, for import/export we do want to be
able to tie this to the external resource, which is one thing that the
memoryObjectId
is for.
The internal alloc/free callbacks are not extensible except via new VkInternalAllocationType values. The VkDeviceMemoryReportCallbackDataEXT in this extension is extensible. That was deliberate: there’s a real possibility we’ll want to get extra information in the future. As one example, currently this reports only physical allocations, but we believe there are interesting cases for tracking how populated that VA region is.
The callbacks are clearly specified as only callable within the context of a call from the app into Vulkan. We believe there are some cases where drivers can allocate device memory asynchronously. This was one of the sticky issues that derailed the internal device memory allocation reporting design (which is essentially what this extension is trying to do) leading up to 1.0.
VkAllocationCallbacks is described in a section called "Host memory" and the intro to it is very explicitly about host memory. The other callbacks are all inherently about host memory. But this extension is very focused on device memory.
3) Should the callback be reporting which heap is used?
RESOLVED: Yes.
It’s important for non-UMA systems to have all the device memory allocations
attributed to the corresponding device memory heaps.
For internally-allocated device memory, heapIndex
will always
correspond to an advertised heap, rather than having a magic value
indicating a non-advertised heap.
Drivers can advertise heaps that don’t have any corresponding memory types
if they need to.
4) Should we use an array of callback for the layers to intercept instead of
chaining multiple of the VkDeviceDeviceMemoryReportCreateInfoEXT
structures in the pNext
of VkDeviceCreateInfo?
RESOLVED No.
The pointer to the VkDeviceDeviceMemoryReportCreateInfoEXT structure
itself is const and you can’t just cast it away.
Thus we can’t update the callback array inside the structure.
In addition, we can’t drop this pNext
chain either, so making a copy
of this whole structure doesn’t work either.
5) Should we track bulk allocations shared among multiple objects?
RESOLVED No.
Take the shader heap as an example.
Some implementations will let multiple VkPipeline objects share the
same shader heap.
We are not asking the implementation to report VK_OBJECT_TYPE_PIPELINE
along with a VK_NULL_HANDLE for this bulk allocation.
Instead, this bulk allocation is considered as a layer below what this
extension is interested in.
Later, when the actual VkPipeline objects are created by suballocating
from the bulk allocation, we ask the implementation to report the valid
handles of the VkPipeline objects along with the actual suballocated
sizes and different memoryObjectId
.
6) Can we require the callbacks to be always called in the same thread with the Vulkan commands?
RESOLVED No. Some implementations might choose to multiplex work from multiple application threads into a single backend thread and perform JIT allocations as a part of that flow. Since this behavior is theoretically legit, we can’t require the callbacks to be always called in the same thread with the Vulkan commands, and the note is to remind the applications to handle this case properly.
7) Should we add an additional "allocation failed" event type with things like size and heap index reported?
RESOLVED Yes.
This fits in well with the callback infrastructure added in this extension,
and implementation touches the same code and has the same overheads as the
rest of the extension.
It could help debugging things like getting an
VK_ERROR_OUT_OF_HOST_MEMORY
error when ending a command buffer.
Right now the allocation failure could have happened anywhere during
recording, and a callback would be really useful to understand where and
why.
Version History
-
Revision 1, 2020-08-26 (Yiwei Zhang)
-
Initial version
-
-
Revision 2, 2021-01-06 (Yiwei Zhang)
-
Minor description update
-
VK_EXT_direct_mode_display
- Name String
-
VK_EXT_direct_mode_display
- Extension Type
-
Instance extension
- Registered Extension Number
-
89
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Liam Middlebrook, NVIDIA
-
Description
This is extension, along with related platform extensions, allows applications to take exclusive control of displays associated with a native windowing system. This is especially useful for virtual reality applications that wish to hide HMDs (head mounted displays) from the native platform’s display management system, desktop, and/or other applications.
New Enum Constants
-
VK_EXT_DIRECT_MODE_DISPLAY_EXTENSION_NAME
-
VK_EXT_DIRECT_MODE_DISPLAY_SPEC_VERSION
Issues
1) Should this extension and its related platform-specific extensions
leverage VK_KHR_display
, or provide separate equivalent interfaces.
RESOLVED: Use VK_KHR_display
concepts and objects.
VK_KHR_display
can be used to enumerate all displays on the system,
including those attached to/in use by a window system or native platform,
but VK_KHR_display_swapchain
will fail to create a swapchain on in-use
displays.
This extension and its platform-specific children will allow applications to
grab in-use displays away from window systems and/or native platforms,
allowing them to be used with VK_KHR_display_swapchain
.
2) Are separate calls needed to acquire displays and enable direct mode?
RESOLVED: No, these operations happen in one combined command. Acquiring a display puts it into direct mode.
VK_EXT_directfb_surface
- Name String
-
VK_EXT_directfb_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
347
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Nicolas Caramelli caramelli
-
Other Extension Metadata
- Last Modified Date
-
2020-06-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Nicolas Caramelli
-
Description
The VK_EXT_directfb_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a DirectFB
IDirectFBSurface
, as well as a query to determine support for rendering
via DirectFB.
New Enum Constants
-
VK_EXT_DIRECTFB_SURFACE_EXTENSION_NAME
-
VK_EXT_DIRECTFB_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DIRECTFB_SURFACE_CREATE_INFO_EXT
-
VK_EXT_discard_rectangles
- Name String
-
VK_EXT_discard_rectangles
- Extension Type
-
Device extension
- Registered Extension Number
-
100
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2016-12-22
- Interactions and External Dependencies
-
-
Interacts with
VK_KHR_device_group
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension provides additional orthogonally aligned “discard rectangles” specified in framebuffer-space coordinates that restrict rasterization of all points, lines and triangles.
From zero to an implementation-dependent limit (specified by
maxDiscardRectangles
) number of discard rectangles can be operational
at once.
When one or more discard rectangles are active, rasterized fragments can
either survive if the fragment is within any of the operational discard
rectangles (VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT
mode) or be
rejected if the fragment is within any of the operational discard rectangles
(VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT
mode).
These discard rectangles operate orthogonally to the existing scissor test functionality. The discard rectangles can be different for each physical device in a device group by specifying the device mask and setting discard rectangle dynamic state.
New Enum Constants
-
VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME
-
VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT
-
VK_EXT_display_control
- Name String
-
VK_EXT_display_control
- Extension Type
-
Device extension
- Registered Extension Number
-
92
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_EXT_display_surface_counter
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
Description
This extension defines a set of utility functions for use with the
VK_KHR_display
and VK_KHR_display_swapchain
extensions.
New Enum Constants
-
VK_EXT_DISPLAY_CONTROL_EXTENSION_NAME
-
VK_EXT_DISPLAY_CONTROL_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_EVENT_INFO_EXT
-
VK_STRUCTURE_TYPE_DISPLAY_EVENT_INFO_EXT
-
VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT
-
VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT
-
Issues
1) Should this extension add an explicit “WaitForVsync” API or a fence signaled at vsync that the application can wait on?
RESOLVED: A fence. A separate API could later be provided that allows exporting the fence to a native object that could be inserted into standard run loops on POSIX and Windows systems.
2) Should callbacks be added for a vsync event, or in general to monitor events in Vulkan?
RESOLVED: No, fences should be used. Some events are generated by interrupts which are managed in the kernel. In order to use a callback provided by the application, drivers would need to have the userspace driver spawn threads that would wait on the kernel event, and hence the callbacks could be difficult for the application to synchronize with its other work given they would arrive on a foreign thread.
3) Should vblank or scanline events be exposed?
RESOLVED: Vblank events. Scanline events could be added by a separate extension, but the latency of processing an interrupt and waking up a userspace event is high enough that the accuracy of a scanline event would be rather low. Further, per-scanline interrupts are not supported by all hardware.
VK_EXT_display_surface_counter
- Name String
-
VK_EXT_display_surface_counter
- Extension Type
-
Instance extension
- Registered Extension Number
-
91
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_display
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2016-12-13
- IP Status
-
No known IP claims.
- Contributors
-
-
Pierre Boudier, NVIDIA
-
James Jones, NVIDIA
-
Damien Leone, NVIDIA
-
Pierre-Loup Griffais, Valve
-
Daniel Vetter, Intel
-
Description
This extension defines a vertical blanking period counter associated with display surfaces. It provides a mechanism to query support for such a counter from a VkSurfaceKHR object.
New Enum Constants
-
VK_EXT_DISPLAY_SURFACE_COUNTER_EXTENSION_NAME
-
VK_EXT_DISPLAY_SURFACE_COUNTER_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT
-
VK_EXT_extended_dynamic_state
- Name String
-
VK_EXT_extended_dynamic_state
- Extension Type
-
Device extension
- Registered Extension Number
-
268
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-12-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Dan Ginsburg, Valve Corporation
-
Graeme Leese, Broadcom
-
Hans-Kristian Arntzen, Valve Corporation
-
Jan-Harald Fredriksen, Arm Limited
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Hall, Google
-
Philip Rebohle, Valve Corporation
-
Stuart Smith, Imagination Technologies
-
Tobias Hector, AMD
-
Description
This extension adds some more dynamic state to support applications that need to reduce the number of pipeline state objects they compile and bind.
New Enum Constants
-
VK_EXT_EXTENDED_DYNAMIC_STATE_EXTENSION_NAME
-
VK_EXT_EXTENDED_DYNAMIC_STATE_SPEC_VERSION
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_CULL_MODE_EXT
-
VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT
-
VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT
-
VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT
-
VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT
-
VK_DYNAMIC_STATE_FRONT_FACE_EXT
-
VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT
-
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT
-
VK_DYNAMIC_STATE_STENCIL_OP_EXT
-
VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT
-
VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT
-
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTENDED_DYNAMIC_STATE_FEATURES_EXT
-
VK_EXT_external_memory_dma_buf
- Name String
-
VK_EXT_external_memory_dma_buf
- Extension Type
-
Device extension
- Registered Extension Number
-
126
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory_fd
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2017-10-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Description
A dma_buf
is a type of file descriptor, defined by the Linux kernel,
that allows sharing memory across kernel device drivers and across
processes.
This extension enables applications to import a dma_buf
as
VkDeviceMemory, to export VkDeviceMemory as a dma_buf
, and
to create VkBuffer objects that can be bound to that memory.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME
-
VK_EXT_EXTERNAL_MEMORY_DMA_BUF_SPEC_VERSION
-
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
-
Issues
1) How does the application, when creating a VkImage that it intends
to bind to dma_buf
VkDeviceMemory containing an externally
produced image, specify the memory layout (such as row pitch and DRM format
modifier) of the VkImage? In other words, how does the application
achieve behavior comparable to that provided by
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
?
RESOLVED: Features comparable to those in
EGL_EXT_image_dma_buf_import
and
EGL_EXT_image_dma_buf_import_modifiers
will be provided by an extension layered atop this one.
2) Without the ability to specify the memory layout of external dma_buf
images, how is this extension useful?
RESOLVED: This extension provides exactly one new feature: the ability to
import/export between dma_buf
and VkDeviceMemory.
This feature, together with features provided by
VK_KHR_external_memory_fd
, is sufficient to bind a VkBuffer to
dma_buf
.
VK_EXT_external_memory_host
- Name String
-
VK_EXT_external_memory_host
- Extension Type
-
Device extension
- Registered Extension Number
-
179
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2017-11-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
David Mao, AMD
-
Daniel Rakos, AMD
-
Tobias Hector, Imagination Technologies
-
Jason Ekstrand, Intel
-
James Jones, NVIDIA
-
Description
This extension enables an application to import host allocations and host mapped foreign device memory to Vulkan memory objects.
New Enum Constants
-
VK_EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME
-
VK_EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION
-
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT
-
VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT
-
Issues
1) What memory type has to be used to import host pointers?
RESOLVED: Depends on the implementation. Applications have to use the new vkGetMemoryHostPointerPropertiesEXT command to query the supported memory types for a particular host pointer. The reported memory types may include memory types that come from a memory heap that is otherwise not usable for regular memory object allocation and thus such a heap’s size may be zero.
2) Can the application still access the contents of the host allocation after importing?
RESOLVED: Yes. However, usual synchronization requirements apply.
3) Can the application free the host allocation?
RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that’s already freed thus results in undefined behavior.
4) Is vkMapMemory expected to return the same host address which was specified when importing it to the memory object?
RESOLVED: No. Implementations are allowed to return the same address but it’s not required. Some implementations might return a different virtual mapping of the allocation, although the same physical pages will be used.
5) Is there any limitation on the alignment of the host pointer and/or size?
RESOLVED: Yes.
Both the address and the size have to be an integer multiple of
minImportedHostPointerAlignment
.
In addition, some platforms and foreign devices may have additional
restrictions.
6) Can the same host allocation be imported multiple times into a given physical device?
RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device access multiple times, so attempting to do it may result in undefined behavior.
7) Does this extension support exporting the new handle type?
RESOLVED: No.
8) Should we include the possibility to import host mapped foreign device memory using this API?
RESOLVED: Yes, through a separate handle type. Implementations are still allowed to support only one of the handle types introduced by this extension by not returning import support for a particular handle type as returned in VkExternalMemoryPropertiesKHR.
VK_EXT_filter_cubic
- Name String
-
VK_EXT_filter_cubic
- Extension Type
-
Device extension
- Registered Extension Number
-
171
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Bill Licea-Kane wwlk
-
Other Extension Metadata
- Last Modified Date
-
2019-12-13
- Contributors
-
-
Bill Licea-Kane, Qualcomm Technologies, Inc.
-
Andrew Garrard, Samsung
-
Daniel Koch, NVIDIA
-
Donald Scorgie, Imagination Technologies
-
Graeme Leese, Broadcom
-
Jan-Herald Fredericksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Tobias Hector, AMD
-
Tom Olson, ARM
-
Stuart Smith, Imagination Technologies
-
Description
VK_EXT_filter_cubic
extends VK_IMG_filter_cubic
.
It documents cubic filtering of other image view types.
It adds new structures that can be added to the pNext
chain of
VkPhysicalDeviceImageFormatInfo2 and VkImageFormatProperties2
that can be used to determine which image types and which image view types
support cubic filtering.
New Enum Constants
-
VK_EXT_FILTER_CUBIC_EXTENSION_NAME
-
VK_EXT_FILTER_CUBIC_SPEC_VERSION
-
Extending VkFilter:
-
VK_FILTER_CUBIC_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_FILTER_CUBIC_IMAGE_VIEW_IMAGE_FORMAT_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_VIEW_IMAGE_FORMAT_INFO_EXT
-
Version History
-
Revision 3, 2019-12-13 (wwlk)
-
Delete requirement to cubic filter the formats USCALED_PACKED32, SSCALED_PACKED32, UINT_PACK32, and SINT_PACK32 (cut/paste error)
-
-
Revision 2, 2019-06-05 (wwlk)
-
Clarify 1D optional
-
-
Revision 1, 2019-01-24 (wwlk)
-
Initial version
-
VK_EXT_fragment_density_map
- Name String
-
VK_EXT_fragment_density_map
- Extension Type
-
Device extension
- Registered Extension Number
-
219
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthew Netsch mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2018-09-25
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_invocation_density
-
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Robert VanReenen, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Tate Hornbeck, Qualcomm Technologies, Inc.
-
Sam Holmes, Qualcomm Technologies, Inc.
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Pat Brown, NVIDIA
-
Daniel Rakos, AMD
-
Piers Daniell, NVIDIA
-
Description
This extension allows an application to specify areas of the render target where the fragment shader may be invoked fewer times. These fragments are broadcasted out to multiple pixels to cover the render target.
The primary use of this extension is to reduce workloads in areas where lower quality may not be perceived such as the distorted edges of a lens or the periphery of a user’s gaze.
New Enum Constants
-
VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME
-
VK_EXT_FRAGMENT_DENSITY_MAP_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT
-
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT
-
VK_EXT_fragment_density_map2
- Name String
-
VK_EXT_fragment_density_map2
- Extension Type
-
Device extension
- Registered Extension Number
-
333
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_EXT_fragment_density_map
-
- Contact
-
-
Matthew Netsch mnetsch
-
Other Extension Metadata
- Last Modified Date
-
2020-06-16
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
- Contributors
-
-
Matthew Netsch, Qualcomm Technologies, Inc.
-
Jonathan Tinkham, Qualcomm Technologies, Inc.
-
Jonathan Wicks, Qualcomm Technologies, Inc.
-
Jan-Harald Fredriksen, ARM
-
Description
This extension adds additional features and properties to
VK_EXT_fragment_density_map
in order to reduce fragment density map
host latency as well as improved queries for subsampled sampler
implementation-dependent behavior.
New Enum Constants
-
VK_EXT_FRAGMENT_DENSITY_MAP_EXTENSION_NAME
-
VK_EXT_FRAGMENT_DENSITY_MAP_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_FRAGMENT_DENSITY_MAP_READ_BIT_EXT
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
Extending VkImageLayout:
-
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
-
-
Extending VkImageUsageFlagBits:
-
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
-
-
Extending VkImageViewCreateFlagBits:
-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT
-
-
Extending VkSamplerCreateFlagBits:
-
VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT
-
VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT
-
VK_EXT_fragment_shader_interlock
- Name String
-
VK_EXT_fragment_shader_interlock
- Extension Type
-
Device extension
- Registered Extension Number
-
252
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-02
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_fragment_shader_interlock
-
This extension provides API support for
GL_ARB_fragment_shader_interlock
-
- Contributors
-
-
Daniel Koch, NVIDIA
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Ruihao Zhang, Qualcomm
-
Slawomir Grajewski, Intel
-
Spencer Fricke, Samsung
-
Description
This extension adds support for the FragmentShaderPixelInterlockEXT
,
FragmentShaderSampleInterlockEXT
, and
FragmentShaderShadingRateInterlockEXT
capabilities from the
SPV_EXT_fragment_shader_interlock
extension to Vulkan.
Enabling these capabilities provides a critical section for fragment shaders to avoid overlapping pixels being processed at the same time, and certain guarantees about the ordering of fragment shader invocations of fragments of overlapping pixels.
This extension can be useful for algorithms that need to access per-pixel data structures via shader loads and stores. Algorithms using this extension can access per-pixel data structures in critical sections without other invocations accessing the same per-pixel data. Additionally, the ordering guarantees are useful for cases where the API ordering of fragments is meaningful. For example, applications may be able to execute programmable blending operations in the fragment shader, where the destination buffer is read via image loads and the final value is written via image stores.
New Enum Constants
-
VK_EXT_FRAGMENT_SHADER_INTERLOCK_EXTENSION_NAME
-
VK_EXT_FRAGMENT_SHADER_INTERLOCK_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADER_INTERLOCK_FEATURES_EXT
-
VK_EXT_full_screen_exclusive
- Name String
-
VK_EXT_full_screen_exclusive
- Extension Type
-
Device extension
- Registered Extension Number
-
256
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
Requires
VK_KHR_get_surface_capabilities2
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
James Jones cubanismo
-
Other Extension Metadata
- Last Modified Date
-
2019-03-12
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
Interacts with Vulkan 1.1
-
Interacts with
VK_KHR_device_group
-
Interacts with
VK_KHR_win32_surface
-
- Contributors
-
-
Hans-Kristian Arntzen, ARM
-
Slawomir Grajewski, Intel
-
Tobias Hector, AMD
-
James Jones, NVIDIA
-
Daniel Rakos, AMD
-
Jeff Juliano, NVIDIA
-
Joshua Schnarr, NVIDIA
-
Aaron Hagan, AMD
-
Description
This extension allows applications to set the policy for swapchain creation and presentation mechanisms relating to full-screen access. Implementations may be able to acquire exclusive access to a particular display for an application window that covers the whole screen. This can increase performance on some systems by bypassing composition, however it can also result in disruptive or expensive transitions in the underlying windowing system when a change occurs.
Applications can choose between explicitly disallowing or allowing this behavior, letting the implementation decide, or managing this mode of operation directly using the new vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.
New Structures
-
Extending VkPhysicalDeviceSurfaceInfo2KHR, VkSwapchainCreateInfoKHR:
-
Extending VkSurfaceCapabilities2KHR:
If VK_KHR_win32_surface is supported:
New Enum Constants
-
VK_EXT_FULL_SCREEN_EXCLUSIVE_EXTENSION_NAME
-
VK_EXT_FULL_SCREEN_EXCLUSIVE_SPEC_VERSION
-
Extending VkResult:
-
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT
-
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT
-
If VK_KHR_win32_surface is supported:
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT
-
Issues
1) What should the extension & flag be called?
RESOLVED: VK_EXT_full_screen_exclusive.
Other options considered (prior to the app-controlled mode) were:
-
VK_EXT_smooth_fullscreen_transition
-
VK_EXT_fullscreen_behavior
-
VK_EXT_fullscreen_preference
-
VK_EXT_fullscreen_hint
-
VK_EXT_fast_fullscreen_transition
-
VK_EXT_avoid_fullscreen_exclusive
2) Do we need more than a boolean toggle?
RESOLVED: Yes.
Using an enum with default/allowed/disallowed/app-controlled enables applications to accept driver default behavior, specifically override it in either direction without implying the driver is ever required to use full-screen exclusive mechanisms, or manage this mode explicitly.
3) Should this be a KHR or EXT extension?
RESOLVED: EXT, in order to allow it to be shipped faster.
4) Can the fullscreen hint affect the surface capabilities, and if so, should the hint also be specified as input when querying the surface capabilities?
RESOLVED: Yes on both accounts.
While the hint does not guarantee a particular fullscreen mode will be used when the swapchain is created, it can sometimes imply particular modes will NOT be used. If the driver determines that it will opt-out of using a particular mode based on the policy, and knows it can only support certain capabilities if that mode is used, it would be confusing at best to the application to report those capabilities in such cases. Not allowing implementations to report this state to applications could result in situations where applications are unable to determine why swapchain creation fails when they specify certain hint values, which could result in never- terminating surface creation loops.
5) Should full-screen be one word or two?
RESOLVED: Two words.
"Fullscreen" is not in my dictionary, and web searches did not turn up definitive proof that it is a colloquially accepted compound word. Documentation for the corresponding Windows API mechanisms dithers. The text consistently uses a hyphen, but none-the-less, there is a SetFullscreenState method in the DXGI swapchain object. Given this inconclusive external guidance, it is best to adhere to the Vulkan style guidelines and avoid inventing new compound words.
Version History
-
Revision 4, 2019-03-12 (Tobias Hector)
-
Added application-controlled mode, and related functions
-
Tidied up appendix
-
-
Revision 3, 2019-01-03 (James Jones)
-
Renamed to VK_EXT_full_screen_exclusive
-
Made related adjustments to the tri-state enumerant names.
-
-
Revision 2, 2018-11-27 (James Jones)
-
Renamed to VK_KHR_fullscreen_behavior
-
Switched from boolean flag to tri-state enum
-
-
Revision 1, 2018-11-06 (James Jones)
-
Internal revision
-
VK_EXT_global_priority
- Name String
-
VK_EXT_global_priority
- Extension Type
-
Device extension
- Registered Extension Number
-
175
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Andres Rodriguez lostgoat
-
Other Extension Metadata
- Last Modified Date
-
2017-10-06
- IP Status
-
No known IP claims.
- Contributors
-
-
Andres Rodriguez, Valve
-
Pierre-Loup Griffais, Valve
-
Dan Ginsburg, Valve
-
Mitch Singer, AMD
-
Description
In Vulkan, users can specify device-scope queue priorities.
In some cases it may be useful to extend this concept to a system-wide
scope.
This extension provides a mechanism for caller’s to set their system-wide
priority.
The default queue priority is VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT
.
The driver implementation will attempt to skew hardware resource allocation in favour of the higher-priority task. Therefore, higher-priority work may retain similar latency and throughput characteristics even if the system is congested with lower priority work.
The global priority level of a queue shall take precedence over the
per-process queue priority
(VkDeviceQueueCreateInfo
::pQueuePriorities
).
Abuse of this feature may result in starving the rest of the system from
hardware resources.
Therefore, the driver implementation may deny requests to acquire a priority
above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT
) if
the caller does not have sufficient privileges.
In this scenario VK_ERROR_NOT_PERMITTED_EXT
is returned.
The driver implementation may fail the queue allocation request if resources
required to complete the operation have been exhausted (either by the same
process or a different process).
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
New Enum Constants
-
VK_EXT_GLOBAL_PRIORITY_EXTENSION_NAME
-
VK_EXT_GLOBAL_PRIORITY_SPEC_VERSION
-
Extending VkResult:
-
VK_ERROR_NOT_PERMITTED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_QUEUE_GLOBAL_PRIORITY_CREATE_INFO_EXT
-
Version History
-
Revision 2, 2017-11-03 (Andres Rodriguez)
-
Fixed VkQueueGlobalPriorityEXT missing _EXT suffix
-
-
Revision 1, 2017-10-06 (Andres Rodriguez)
-
First version.
-
VK_EXT_hdr_metadata
- Name String
-
VK_EXT_hdr_metadata
- Extension Type
-
Device extension
- Registered Extension Number
-
106
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2018-12-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
Description
This extension defines two new structures and a function to assign SMPTE
(the Society of Motion Picture and Television Engineers) 2086 metadata and
CTA (Consumer Technology Association) 861.3 metadata to a swapchain.
The metadata includes the color primaries, white point, and luminance range
of the reference monitor, which all together define the color volume that
contains all the possible colors the reference monitor can produce.
The reference monitor is the display where creative work is done and
creative intent is established.
To preserve such creative intent as much as possible and achieve consistent
color reproduction on different viewing displays, it is useful for the
display pipeline to know the color volume of the original reference monitor
where content was created or tuned.
This avoids performing unnecessary mapping of colors that are not
displayable on the original reference monitor.
The metadata also includes the maxContentLightLevel
and
maxFrameAverageLightLevel
as defined by CTA 861.3.
While the general purpose of the metadata is to assist in the transformation between different color volumes of different displays and help achieve better color reproduction, it is not in the scope of this extension to define how exactly the metadata should be used in such a process. It is up to the implementation to determine how to make use of the metadata.
New Enum Constants
-
VK_EXT_HDR_METADATA_EXTENSION_NAME
-
VK_EXT_HDR_METADATA_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HDR_METADATA_EXT
-
Issues
1) Do we need a query function?
PROPOSED: No, Vulkan does not provide queries for state that the application can track on its own.
2) Should we specify default if not specified by the application?
PROPOSED: No, that leaves the default up to the display.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2018-12-19 (Courtney Goeltzenleuchter)
-
Correct implicit validity for VkHdrMetadataEXT structure
-
VK_EXT_headless_surface
- Name String
-
VK_EXT_headless_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
257
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Lisa Wu chengtianww
-
Other Extension Metadata
- Last Modified Date
-
2019-03-21
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, Arm
-
Description
The VK_EXT_headless_surface
extension is an instance extension.
It provides a mechanism to create VkSurfaceKHR objects independently
of any window system or display device.
The presentation operation for a swapchain created from a headless surface
is by default a no-op, resulting in no externally-visible result.
Because there is no real presentation target, future extensions can layer on top of the headless surface to introduce arbitrary or customisable sets of restrictions or features. These could include features like saving to a file or restrictions to emulate a particular presentation target.
This functionality is expected to be useful for application and driver development because it allows any platform to expose an arbitrary or customisable set of restrictions and features of a presentation engine. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development.
New Enum Constants
-
VK_EXT_HEADLESS_SURFACE_EXTENSION_NAME
-
VK_EXT_HEADLESS_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT
-
VK_EXT_image_drm_format_modifier
- Name String
-
VK_EXT_image_drm_format_modifier
- Extension Type
-
Device extension
- Registered Extension Number
-
159
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_bind_memory2
-
Requires
VK_KHR_image_format_list
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2018-08-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Antoine Labour, Google
-
Bas Nieuwenhuizen, Google
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jőrg Wagner, ARM
-
Kristian Høgsberg Kristensen, Google
-
Ray Smith, ARM
-
Description
This extension provides the ability to use DRM format modifiers with images, enabling Vulkan to better integrate with the Linux ecosystem of graphics, video, and display APIs.
Its functionality closely overlaps with
EGL_EXT_image_dma_buf_import_modifiers
2
and
EGL_MESA_image_dma_buf_export
3.
Unlike the EGL extensions, this extension does not require the use of a
specific handle type (such as a dma_buf) for external memory and provides
more explicit control of image creation.
Introduction to DRM Format Modifiers
A DRM format modifier is a 64-bit, vendor-prefixed, semi-opaque unsigned
integer.
Most modifiers represent a concrete, vendor-specific tiling format for
images.
Some exceptions are DRM_FORMAT_MOD_LINEAR
(which is not
vendor-specific); DRM_FORMAT_MOD_NONE
(which is an alias of
DRM_FORMAT_MOD_LINEAR
due to historical accident); and
DRM_FORMAT_MOD_INVALID
(which does not represent a tiling format).
The modifier’s vendor prefix consists of the 8 most significant bits.
The canonical list of modifiers and vendor prefixes is found in
drm_fourcc.h
in the Linux kernel source.
The other dominant source of modifiers are vendor kernel trees.
One goal of modifiers in the Linux ecosystem is to enumerate for each vendor a reasonably sized set of tiling formats that are appropriate for images shared across processes, APIs, and/or devices, where each participating component may possibly be from different vendors. A non-goal is to enumerate all tiling formats supported by all vendors. Some tiling formats used internally by vendors are inappropriate for sharing; no modifiers should be assigned to such tiling formats.
Modifier values typically do not describe memory layouts. More precisely, a modifier's lower 56 bits usually have no structure. Instead, modifiers name memory layouts; they name a small set of vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1.
Each modifier is usually supported by a single vendor and its name matches
the pattern {VENDOR}_FORMAT_MOD_*
or DRM_FORMAT_MOD_{VENDOR}_*
.
Examples are I915_FORMAT_MOD_X_TILED
and
DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED
.
An exception is DRM_FORMAT_MOD_LINEAR
, which is supported by most
vendors.
Many APIs in Linux use modifiers to negotiate and specify the memory
layout of shared images.
For example, a Wayland compositor and Wayland client may, by relaying
modifiers over the Wayland protocol zwp_linux_dmabuf_v1
, negotiate a
vendor-specific tiling format for a shared wl_buffer
.
The client may allocate the underlying memory for the wl_buffer
with
GBM, providing the chosen modifier to gbm_bo_create_with_modifiers
.
The client may then import the wl_buffer
into Vulkan for producing
image content, providing the resource’s dma_buf to
VkImportMemoryFdInfoKHR and its modifier to
VkImageDrmFormatModifierExplicitCreateInfoEXT.
The compositor may then import the wl_buffer
into OpenGL for sampling,
providing the resource’s dma_buf and modifier to eglCreateImage
.
The compositor may also bypass OpenGL and submit the wl_buffer
directly
to the kernel’s display API, providing the dma_buf and modifier through
drm_mode_fb_cmd2
.
Format Translation
Modifier-capable APIs often pair modifiers with DRM formats, which are
defined in
drm_fourcc.h
.
However, VK_EXT_image_drm_format_modifier
uses VkFormat instead of
DRM formats.
The application must convert between VkFormat and DRM format when it
sends or receives a DRM format to or from an external API.
The mapping from VkFormat to DRM format is lossy. Therefore, when receiving a DRM format from an external API, often the application must use information from the external API to accurately map the DRM format to a VkFormat. For example, DRM formats do not distinguish between RGB and sRGB (as of 2018-03-28); external information is required to identify the image’s colorspace.
The mapping between VkFormat and DRM format is also incomplete. For some DRM formats there exist no corresponding Vulkan format, and for some Vulkan formats there exist no corresponding DRM format.
Usage Patterns
Three primary usage patterns are intended for this extension:
-
Negotiation. The application negotiates with modifier-aware, external components to determine sets of image creation parameters supported among all components.
In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that assumption but does not require it. The result of the negotiation usually resembles a set of tuples such as (drmFormat, drmFormatModifier), where each participating component supports all tuples in the set.
Many details of this negotiation—such as the protocol used during negotiation, the set of image creation parameters expressable in the protocol, and how the protocol chooses which process and which API will create the image—are outside the scope of this specification.
In this extension, vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT serves a primary role during the negotiation, and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role.
-
Import. The application imports an image with a modifier.
In this pattern, the application receives from an external source the image’s memory and its creation parameters, which are often the result of the negotiation described above. Some image creation parameters are implicitly defined by the external source; for example,
VK_IMAGE_TYPE_2D
is often assumed. Some image creation parameters are usually explicit, such as the image’sformat
,drmFormatModifier
, andextent
; and each plane’soffset
androwPitch
.Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying vkGetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT and vkGetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates the image by chaining VkImageDrmFormatModifierExplicitCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo.
-
Export. The application creates an image and allocates its memory. Then the application exports to modifier-aware consumers the image’s memory handles; its creation parameters; its modifier; and the
offset
,size
, androwPitch
of each memory plane.In this pattern, the Vulkan device is the authority for the image; it is the allocator of the image’s memory and the decider of the image’s creation parameters. When choosing the image’s creation parameters, the application usually chooses a tuple (format, drmFormatModifier) from the result of the negotiation described above. The negotiation’s result often contains multiple tuples that share the same format but differ in their modifier. In this case, the application should defer the choice of the image’s modifier to the Vulkan implementation by providing all such modifiers to VkImageDrmFormatModifierListCreateInfoEXT::
pDrmFormatModifiers
; and the implementation should choose frompDrmFormatModifiers
the optimal modifier in consideration with the other image parameters.The application creates the image by chaining VkImageDrmFormatModifierListCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo. The protocol and APIs by which the application will share the image with external consumers will likely determine the value of VkExternalMemoryImageCreateInfo::
handleTypes
. The implementation chooses for the image an optimal modifier from VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers
. The application then queries the implementation-chosen modifier with vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory layout of each plane with vkGetImageSubresourceLayout.The application then allocates the image’s memory with VkMemoryAllocateInfo, adding chained extending structures for external memory; binds it to the image; and exports the memory, for example, with vkGetMemoryFdKHR.
Finally, the application sends the image’s creation parameters, its modifier, its per-plane memory layout, and the exported memory handle to the external consumers. The details of how the application transmits this information to external consumers is outside the scope of this specification.
Prior Art
Extension
EGL_EXT_image_dma_buf_import
1
introduced the ability to create an EGLImage
by importing for each
plane a dma_buf, offset, and row pitch.
Later, extension
EGL_EXT_image_dma_buf_import_modifiers
2
introduced the ability to query which combination of formats and modifiers
the implementation supports and to specify modifiers during creation of
the EGLImage
.
Extension
EGL_MESA_image_dma_buf_export
3
is the inverse of EGL_EXT_image_dma_buf_import_modifiers
.
The Linux kernel modesetting API (KMS), when configuring the display’s
framebuffer with struct
drm_mode_fb_cmd2
4, allows one to
specify the frambuffer’s modifier as well as a per-plane memory handle,
offset, and row pitch.
GBM, a graphics buffer manager for Linux, allows creation of a gbm_bo
(that is, a graphics buffer object) by importing data similar to that in
EGL_EXT_image_dma_buf_import_modifiers
1;
and symmetrically allows exporting the same data from the gbm_bo
.
See the references to modifier and plane in
gbm.h
5.
New Structures
-
Extending VkFormatProperties2:
-
Extending VkImageCreateInfo:
-
Extending VkPhysicalDeviceImageFormatInfo2:
New Enum Constants
-
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME
-
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION
-
Extending VkImageAspectFlagBits:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT
-
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT
-
-
Extending VkImageTiling:
-
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
-
-
Extending VkResult:
-
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
-
Issues
1) Should this extension define a single DRM format modifier per
VkImage
? Or define one per plane?
+
RESOLVED: There exists a single DRM format modifier per VkImage
.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers
2,
struct drm_mode_fb_cmd2
4, and
struct
gbm_import_fd_modifier_data
5,
allows defining one modifier per plane.
However, developers of the GBM and kernel APIs concede it was a mistake.
Beginning in Linux 4.10, the kernel requires that the application provide
the same DRM format modifier for each plane.
(See Linux commit
bae781b259269590109e8a4a8227331362b88212).
And GBM provides an entry point, gbm_bo_get_modifier
, for querying the
modifier of the image but does not provide one to query the modifier of
individual planes.
2) When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, which is typically used when importing an image, should the application explicitly provide the size of each plane?
+
RESOLVED: No.
The application must not provide the size.
To enforce this, the API requires that
VkImageDrmFormatModifierExplicitCreateInfoEXT::pPlaneLayouts->size
must be 0.
DISCUSSION: Prior art, such as
EGL_EXT_image_dma_buf_import_modifiers
2,
struct drm_mode_fb_cmd2
4, and
struct
gbm_import_fd_modifier_data
5,
omits from the API the size of each plane.
Instead, the APIs infer each plane’s size from the import parameters, which
include the image’s pixel format and a dma_buf, offset, and row pitch for
each plane.
However, Vulkan differs from EGL and GBM with regards to image creation in the following ways:
-
Undedicated allocation by default. When importing or exporting a set of dma_bufs as an
EGLImage
orgbm_bo
, common practice mandates that each dma_buf’s memory be dedicated (in the sense ofVK_KHR_dedicated_allocation
) to the image (though not necessarily dedicated to a single plane). In particular, neither the GBM documentation nor the EGL extension specifications explicitly state this requirement, but in light of common practice this is likely due to under-specification rather than intentional omission. In contrast,VK_EXT_image_drm_format_modifier
permits, but does not require, the implementation to require dedicated allocations for images created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
. -
Separation of image creation and memory allocation. When importing a set of dma_bufs as an
EGLImage
orgbm_bo
, EGL and GBM create the image resource and bind it to memory (the dma_bufs) simultaneously. This allows EGL and GBM to query each dma_buf’s size during image creation. In Vulkan, image creation and memory allocation are independent unless a dedicated allocation is used (as inVK_KHR_dedicated_allocation
). Therefore, without requiring dedicated allocation, Vulkan cannot query the size of each dma_buf (or other external handle) when calculating the image’s memory layout. Even if dedication allocation were required, Vulkan cannot calculate the image’s memory layout until after the image is bound to its dma_ufs.
The above differences complicate the potential inference of plane size in Vulkan. Consider the following problematic cases:
-
Padding. Some plane of the image may require implementation-dependent padding.
-
Metadata. For some modifiers, the image may have a metadata plane which requires a non-trivial calculation to determine its size.
-
Mipmapped, array, and 3D images. The implementation may support
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
for images whosemipLevels
,arrayLayers
, ordepth
is greater than 1. For such images with certain modifiers, the calculation of each plane’s size may be non-trivial.
However, an application-provided plane size solves none of the above problems.
For simplicity, consider an external image with a single memory plane.
The implementation is obviously capable calculating the image’s size when
its tiling is VK_IMAGE_TILING_OPTIMAL
.
Likewise, any reasonable implementation is capable of calculating the
image’s size when its tiling uses a supported modifier.
Suppose that the external image’s size is smaller than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, the implementation would observe the mismatched size
and recognize its inability to comprehend the external image’s layout
(unless the implementation used the application-provided size to select a
refinement of the tiling layout indicated by the modifier, which is
strongly discouraged).
The implementation would observe the conflict, and reject image creation
with VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
less than the size required by the implementation.
The application would observe the conflict and refuse to bind the
VkImage
to the external memory.
In both cases, the result is explicit failure.
Suppose that the external image’s size is larger than the
implementation-calculated size.
If the application provided the external image’s size to
vkCreateImage, for reasons similar to above the implementation would
observe the mismatched size and recognize its inability to comprehend the
image data residing in the extra size.
The implementation, however, must assume that image data resides in the
entire size provided by the application.
The implementation would observe the conflict and reject image creation with
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
.
On the other hand, if the application did not provide the external image’s
size to vkCreateImage, then the application would observe after
calling vkGetImageMemoryRequirements that the external image’s size is
larger than the implementation-usable size.
The application would observe the conflict and refuse to bind the
VkImage
to the external memory.
In both cases, the result is explicit failure.
Therefore, an application-provided size provides no benefit, and this
extension should not require it.
This decision renders VkSubresourceLayout::size
an unused field
during image creation, and thus introduces a risk that implementations may
require applications to submit sideband creation parameters in the unused
field.
To prevent implementations from relying on sideband data, this extension
requires the application to set size
to 0.
VK_EXT_image_robustness
- Name String
-
VK_EXT_image_robustness
- Extension Type
-
Device extension
- Registered Extension Number
-
336
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Graeme Leese gnl21
-
Other Extension Metadata
- Last Modified Date
-
2020-04-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Graeme Leese, Broadcom
-
Jan-Harald Fredriksen, ARM
-
Jeff Bolz, NVIDIA
-
Spencer Fricke, Samsung
-
Courtney Goeltzenleuchter, Google
-
Slawomir Cygan, Intel
-
Description
This extension adds stricter requirements for how out of bounds reads from images are handled. Rather than returning undefined values, most out of bounds reads return R, G, and B values of zero and alpha values of either zero or one. Components not present in the image format may be set to zero or to values based on the format as described in Conversion to RGBA.
New Enum Constants
-
VK_EXT_IMAGE_ROBUSTNESS_EXTENSION_NAME
-
VK_EXT_IMAGE_ROBUSTNESS_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_ROBUSTNESS_FEATURES_EXT
-
Issues
-
How does this extension differ from VK_EXT_robustness2?
The guarantees provided by this extension are a subset of those provided by the robustImageAccess2 feature of VK_EXT_robustness2. Where this extension allows return values of (0, 0, 0, 0) or (0, 0, 0, 1), robustImageAccess2 requires that a particular value dependent on the image format be returned. This extension provides no guarantees about the values returned for an access to an invalid Lod.
VK_EXT_index_type_uint8
- Name String
-
VK_EXT_index_type_uint8
- Extension Type
-
Device extension
- Registered Extension Number
-
266
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-02
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension allows uint8_t
indices to be used with
vkCmdBindIndexBuffer.
New Enum Constants
-
VK_EXT_INDEX_TYPE_UINT8_EXTENSION_NAME
-
VK_EXT_INDEX_TYPE_UINT8_SPEC_VERSION
-
Extending VkIndexType:
-
VK_INDEX_TYPE_UINT8_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INDEX_TYPE_UINT8_FEATURES_EXT
-
VK_EXT_inline_uniform_block
- Name String
-
VK_EXT_inline_uniform_block
- Extension Type
-
Device extension
- Registered Extension Number
-
139
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_maintenance1
-
- Contact
-
-
Daniel Rakos aqnuep
-
Other Extension Metadata
- Last Modified Date
-
2018-08-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Daniel Rakos, AMD
-
Jeff Bolz, NVIDIA
-
Slawomir Grajewski, Intel
-
Neil Henning, Codeplay
-
Description
This extension introduces the ability to back uniform blocks directly with descriptor sets by storing inline uniform data within descriptor pool storage. Compared to push constants this new construct allows uniform data to be reused across multiple disjoint sets of draw or dispatch commands and may enable uniform data to be accessed with less indirections compared to uniforms backed by buffer memory.
New Structures
-
Extending VkDescriptorPoolCreateInfo:
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkWriteDescriptorSet:
New Enum Constants
-
VK_EXT_INLINE_UNIFORM_BLOCK_EXTENSION_NAME
-
VK_EXT_INLINE_UNIFORM_BLOCK_SPEC_VERSION
-
Extending VkDescriptorType:
-
VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_INLINE_UNIFORM_BLOCK_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INLINE_UNIFORM_BLOCK_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_INLINE_UNIFORM_BLOCK_EXT
-
Issues
1) Do we need a new storage class for inline uniform blocks vs uniform blocks?
RESOLVED: No.
The Uniform
storage class is used to allow the same syntax used for
both uniform buffers and inline uniform blocks.
2) Is the descriptor array index and array size expressed in terms of bytes or dwords for inline uniform block descriptors?
RESOLVED: In bytes, but both must be a multiple of 4, similar to how push
constant ranges are specified.
The descriptorCount
of VkDescriptorSetLayoutBinding
thus
provides the total number of bytes a particular binding with an inline
uniform block descriptor type can hold, while the srcArrayElement
,
dstArrayElement
, and descriptorCount
members of
VkWriteDescriptorSet
, VkCopyDescriptorSet
, and
VkDescriptorUpdateTemplateEntry
(where applicable) specify the byte
offset and number of bytes to write/copy to the binding’s backing store.
Additionally, the stride
member of
VkDescriptorUpdateTemplateEntry
is ignored for inline uniform blocks
and a default value of one is used, meaning that the data to update inline
uniform block bindings with must be contiguous in memory.
3) What layout rules apply for uniform blocks corresponding to inline constants?
RESOLVED: They use the same layout rules as uniform buffers.
4) Do we need to add non-uniform indexing features/properties as introduced
by VK_EXT_descriptor_indexing
for inline uniform blocks?
RESOLVED: No, because inline uniform blocks are not allowed to be “arrayed”. A single binding with an inline uniform block descriptor type corresponds to a single uniform block instance and the array indices inside that binding refer to individual offsets within the uniform block (see issue #2). However, this extension does introduce new features/properties about the level of support for update-after-bind inline uniform blocks.
5) Is the descriptorBindingVariableDescriptorCount
feature introduced
by VK_EXT_descriptor_indexing
supported for inline uniform blocks?
RESOLVED: Yes, as long as other inline uniform block specific limits are respected.
6) Do the robustness guarantees of robustBufferAccess
apply to inline
uniform block accesses?
RESOLVED: No, similarly to push constants, as they are not backed by buffer memory like uniform buffers.
VK_EXT_line_rasterization
- Name String
-
VK_EXT_line_rasterization
- Extension Type
-
Device extension
- Registered Extension Number
-
260
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-05-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Allen Jensen, NVIDIA
-
Jason Ekstrand, Intel
-
Description
This extension adds some line rasterization features that are commonly used in CAD applications and supported in other APIs like OpenGL. Bresenham-style line rasterization is supported, smooth rectangular lines (coverage to alpha) are supported, and stippled lines are supported for all three line rasterization modes.
New Enum Constants
-
VK_EXT_LINE_RASTERIZATION_EXTENSION_NAME
-
VK_EXT_LINE_RASTERIZATION_SPEC_VERSION
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_LINE_STIPPLE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LINE_RASTERIZATION_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_EXT
-
Issues
(1) Do we need to support Bresenham-style and smooth lines with more than one rasterization sample? i.e. the equivalent of glDisable(GL_MULTISAMPLE) in OpenGL when the framebuffer has more than one sample?
RESOLVED: Yes. For simplicity, Bresenham line rasterization carries forward a few restrictions from OpenGL, such as not supporting per-sample shading, alpha to coverage, or alpha to one.
VK_EXT_memory_budget
- Name String
-
VK_EXT_memory_budget
- Extension Type
-
Device extension
- Registered Extension Number
-
238
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
While running a Vulkan application, other processes on the machine might also be attempting to use the same device memory, which can pose problems. This extension adds support for querying the amount of memory used and the total memory budget for a memory heap. The values returned by this query are implementation-dependent and can depend on a variety of factors including operating system and system load.
The VkPhysicalDeviceMemoryBudgetPropertiesEXT::heapBudget
values
can be used as a guideline for how much total memory from each heap the
current process can use at any given time, before allocations may start
failing or causing performance degradation.
The values may change based on other activity in the system that is outside
the scope and control of the Vulkan implementation.
The VkPhysicalDeviceMemoryBudgetPropertiesEXT::heapUsage
will
display the current process estimated heap usage.
With this information, the idea is for an application at some interval (once
per frame, per few seconds, etc) to query heapBudget
and
heapUsage
.
From here the application can notice if it is over budget and decide how it
wants to handle the memory situation (free it, move to host memory, changing
mipmap levels, etc).
This extension is designed to be used in concert with
VK_EXT_memory_priority to help with this part of memory management.
New Enum Constants
-
VK_EXT_MEMORY_BUDGET_EXTENSION_NAME
-
VK_EXT_MEMORY_BUDGET_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_BUDGET_PROPERTIES_EXT
-
VK_EXT_memory_priority
- Name String
-
VK_EXT_memory_priority
- Extension Type
-
Device extension
- Registered Extension Number
-
239
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-08
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jeff Juliano, NVIDIA
-
Description
This extension adds a priority
value specified at memory allocation
time.
On some systems with both device-local and non-device-local memory heaps,
the implementation may transparently move memory from one heap to another
when a heap becomes full (for example, when the total memory used across all
processes exceeds the size of the heap).
In such a case, this priority value may be used to determine which
allocations are more likely to remain in device-local memory.
New Enum Constants
-
VK_EXT_MEMORY_PRIORITY_EXTENSION_NAME
-
VK_EXT_MEMORY_PRIORITY_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MEMORY_PRIORITY_ALLOCATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_PRIORITY_FEATURES_EXT
-
VK_EXT_metal_surface
- Name String
-
VK_EXT_metal_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
218
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Dzmitry Malyshau kvark
-
Other Extension Metadata
- Last Modified Date
-
2018-10-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Dzmitry Malyshau, Mozilla Corp.
-
Description
The VK_EXT_metal_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) from CAMetalLayer
, which is the
native rendering surface of Apple’s Metal framework.
New Enum Constants
-
VK_EXT_METAL_SURFACE_EXTENSION_NAME
-
VK_EXT_METAL_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT
-
VK_EXT_pci_bus_info
- Name String
-
VK_EXT_pci_bus_info
- Extension Type
-
Device extension
- Registered Extension Number
-
213
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2018-12-10
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
Description
This extension adds a new query to obtain PCI bus information about a physical device.
Not all physical devices have PCI bus information, either due to the device not being connected to the system through a PCI interface or due to platform specific restrictions and policies. Thus this extension is only expected to be supported by physical devices which can provide the information.
As a consequence, applications should always check for the presence of the extension string for each individual physical device for which they intend to issue the new query for and should not have any assumptions about the availability of the extension on any given platform.
New Enum Constants
-
VK_EXT_PCI_BUS_INFO_EXTENSION_NAME
-
VK_EXT_PCI_BUS_INFO_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PCI_BUS_INFO_PROPERTIES_EXT
-
Version History
-
Revision 2, 2018-12-10 (Daniel Rakos)
-
Changed all members of the new structure to have the uint32_t type
-
-
Revision 1, 2018-10-11 (Daniel Rakos)
-
Initial revision
-
VK_EXT_pipeline_creation_cache_control
- Name String
-
VK_EXT_pipeline_creation_cache_control
- Extension Type
-
Device extension
- Registered Extension Number
-
298
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Gregory Grebe grgrebe_amd
-
Other Extension Metadata
- Last Modified Date
-
2020-03-23
- IP Status
-
No known IP claims.
- Contributors
-
-
Gregory Grebe, AMD
-
Tobias Hector, AMD
-
Matthaeus Chajdas, AMD
-
Mitch Singer, AMD
-
Spencer Fricke, Samsung Electronics
-
Stuart Smith, Imagination Technologies
-
Jeff Bolz, NVIDIA Corporation
-
Daniel Koch, NVIDIA Corporation
-
Dan Ginsburg, Valve Corporation
-
Jeff Leger, QUALCOMM
-
Michal Pietrasiuk, Intel
-
Jan-Harald Fredriksen, Arm Limited
-
Description
This extension adds flags to Vk*PipelineCreateInfo
and
VkPipelineCacheCreateInfo structures with the aim of improving the
predictability of pipeline creation cost.
The goal is to provide information about potentially expensive hazards
within the client driver during pipeline creation to the application before
carrying them out rather than after.
Background
Pipeline creation is a costly operation, and the explicit nature of the Vulkan design means that cost is not hidden from the developer. Applications are also expected to schedule, prioritize, and load balance all calls for pipeline creation. It is strongly advised that applications create pipelines sufficiently ahead of their usage. Failure to do so will result in an unresponsive application, intermittent stuttering, or other poor user experiences. Proper usage of pipeline caches and/or derivative pipelines help mitigate this but is not assured to eliminate disruption in all cases. In the event that an ahead-of-time creation is not possible, considerations should be taken to ensure that the current execution context is suitable for the workload of pipeline creation including possible shader compilation.
Applications making API calls to create a pipeline must be prepared for any of the following to occur:
-
OS/kernel calls to be made by the ICD
-
Internal memory allocation not tracked by the
pAllocator
passed tovkCreate*Pipelines
-
Internal thread synchronization or yielding of the current thread’s core
-
Extremely long (multi-millisecond+), blocking, compilation times
-
Arbitrary call stacks depths and stack memory usage
The job or task based game engines that are being developed to take advantage of explicit graphics APIs like Vulkan may behave exceptionally poorly if any of the above scenarios occur. However, most game engines are already built to "stream" in assets dynamically as the user plays the game. By adding control by way of VkPipelineCreateFlags, we can require an ICD to report back a failure in critical execution paths rather than forcing an unexpected wait.
Applications can prevent unexpected compilation by setting
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT
on
Vk*PipelineCreateInfo
::flags
.
When set, an ICD must not attempt pipeline or shader compilation to create
the pipeline object.
The ICD will return the result VK_PIPELINE_COMPILE_REQUIRED_EXT
.
An ICD may still return a valid VkPipeline
object by either re-using
existing pre-compiled objects such as those from a pipeline cache, or
derivative pipelines.
By default vkCreate*Pipelines
calls must attempt to create all
pipelines before returning.
Setting VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
on
Vk*PipelineCreateInfo
::flags
can be used as an escape hatch for
batched pipeline creates.
Hidden locks also add to the unpredictability of the cost of pipeline
creation.
The most common case of locks inside the vkCreate*Pipelines
is
internal synchronization of the VkPipelineCache object.
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT
can be set
when calling vkCreatePipelineCache to state the cache is
externally synchronized.
The hope is that armed with this information application and engine developers can leverage existing asset streaming systems to recover from "just-in-time" pipeline creation stalls.
New Enum Constants
-
VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME
-
VK_EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION
-
Extending VkPipelineCacheCreateFlagBits:
-
VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT
-
-
Extending VkPipelineCreateFlagBits:
-
VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
-
VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT
-
-
Extending VkResult:
-
VK_PIPELINE_COMPILE_REQUIRED_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT
-
Version History
-
Revision 1, 2019-11-01 (Gregory Grebe)
-
Initial revision
-
-
Revision 2, 2020-02-24 (Gregory Grebe)
-
Initial public revision
-
-
Revision 3, 2020-03-23 (Tobias Hector)
-
Changed
VK_PIPELINE_COMPILE_REQUIRED_EXT
to a success code, adding an alias for the originalVK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT
. Also updated the xml to include these codes as return values.
-
VK_EXT_pipeline_creation_feedback
- Name String
-
VK_EXT_pipeline_creation_feedback
- Extension Type
-
Device extension
- Registered Extension Number
-
193
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-03-12
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Hai Nguyen, Google
-
Andrew Ellem, Google
-
Bob Fraser, Google
-
Sujeevan Rajayogam, Google
-
Jan-Harald Fredriksen, ARM
-
Jeff Leger, Qualcomm Technologies, Inc.
-
Jeff Bolz, NVIDIA
-
Daniel Koch, NVIDIA
-
Neil Henning, AMD
-
Description
This extension adds a mechanism to provide feedback to an application about pipeline creation, with the specific goal of allowing a feedback loop between build systems and in-the-field application executions to ensure effective pipeline caches are shipped to customers.
New Enum Constants
-
VK_EXT_PIPELINE_CREATION_FEEDBACK_EXTENSION_NAME
-
VK_EXT_PIPELINE_CREATION_FEEDBACK_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO_EXT
-
VK_EXT_post_depth_coverage
- Name String
-
VK_EXT_post_depth_coverage
- Extension Type
-
Device extension
- Registered Extension Number
-
156
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Koch dgkoch
-
Other Extension Metadata
- Last Modified Date
-
2017-07-17
- Interactions and External Dependencies
-
-
This extension requires
SPV_KHR_post_depth_coverage
-
This extension provides API support for
GL_ARB_post_depth_coverage
andGL_EXT_post_depth_coverage
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds support for the following SPIR-V extension in Vulkan:
-
SPV_KHR_post_depth_coverage
which allows the fragment shader to control whether values in the
SampleMask
built-in input variable reflect the coverage after early
depth and stencil tests are applied.
This extension adds a new PostDepthCoverage
execution mode under the
SampleMaskPostDepthCoverage
capability.
When this mode is specified along with EarlyFragmentTests
, the value of
an input variable decorated with the
SampleMask
built-in
reflects the coverage after the early fragment
tests are applied.
Otherwise, it reflects the coverage before the depth and stencil tests.
When using GLSL source-based shading languages, the post_depth_coverage
layout qualifier from GL_ARB_post_depth_coverage or
GL_EXT_post_depth_coverage maps to the PostDepthCoverage
execution
mode.
New Enum Constants
-
VK_EXT_POST_DEPTH_COVERAGE_EXTENSION_NAME
-
VK_EXT_POST_DEPTH_COVERAGE_SPEC_VERSION
VK_EXT_private_data
- Name String
-
VK_EXT_private_data
- Extension Type
-
Device extension
- Registered Extension Number
-
296
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthew Rusch mattruschnv
-
Other Extension Metadata
- Last Modified Date
-
2020-03-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthew Rusch, NVIDIA
-
Nuno Subtil, NVIDIA
-
Piers Daniell, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
The 'VK_EXT_private_data' extension is a device extension which enables attaching arbitrary payloads to Vulkan objects. It introduces the idea of private data slots as a means of storing a 64-bit unsigned integer of application defined data. Private data slots can be created or destroyed any time an associated device is available. Private data slots can be reserved at device creation time, and limiting use to the amount reserved will allow the extension to exhibit better performance characteristics.
New Enum Constants
-
VK_EXT_PRIVATE_DATA_EXTENSION_NAME
-
VK_EXT_PRIVATE_DATA_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_PRIVATE_DATA_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRIVATE_DATA_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PRIVATE_DATA_SLOT_CREATE_INFO_EXT
-
VK_EXT_queue_family_foreign
- Name String
-
VK_EXT_queue_family_foreign
- Extension Type
-
Device extension
- Registered Extension Number
-
127
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_external_memory
-
- Contact
-
-
Chad Versace chadversary
-
Other Extension Metadata
- Last Modified Date
-
2017-11-01
- IP Status
-
No known IP claims.
- Contributors
-
-
Chad Versace, Google
-
James Jones, NVIDIA
-
Jason Ekstrand, Intel
-
Jesse Hall, Google
-
Daniel Rakos, AMD
-
Ray Smith, ARM
-
Description
This extension defines a special queue family,
VK_QUEUE_FAMILY_FOREIGN_EXT
, which can be used to transfer ownership
of resources backed by external memory to foreign, external queues.
This is similar to VK_QUEUE_FAMILY_EXTERNAL_KHR
, defined in
VK_KHR_external_memory
.
The key differences between the two are:
-
The queues represented by
VK_QUEUE_FAMILY_EXTERNAL_KHR
must share the same physical device and the same driver version as the current VkInstance.VK_QUEUE_FAMILY_FOREIGN_EXT
has no such restrictions. It can represent devices and drivers from other vendors, and can even represent non-Vulkan-capable devices. -
All resources backed by external memory support
VK_QUEUE_FAMILY_EXTERNAL_KHR
. Support forVK_QUEUE_FAMILY_FOREIGN_EXT
is more restrictive. -
Applications should expect transitions to/from
VK_QUEUE_FAMILY_FOREIGN_EXT
to be more expensive than transitions to/fromVK_QUEUE_FAMILY_EXTERNAL_KHR
.
New Enum Constants
-
VK_EXT_QUEUE_FAMILY_FOREIGN_EXTENSION_NAME
-
VK_EXT_QUEUE_FAMILY_FOREIGN_SPEC_VERSION
-
VK_QUEUE_FAMILY_FOREIGN_EXT
VK_EXT_robustness2
- Name String
-
VK_EXT_robustness2
- Extension Type
-
Device extension
- Registered Extension Number
-
287
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Liam Middlebrook liam-middlebrook
-
Other Extension Metadata
- Last Modified Date
-
2020-01-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Liam Middlebrook, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension adds stricter requirements for how out of bounds reads and writes are handled. Most accesses must be tightly bounds-checked, out of bounds writes must be discarded, out of bound reads must return zero. Rather than allowing multiple possible (0,0,0,x) vectors, the out of bounds values are treated as zero, and then missing components are inserted based on the format as described in Conversion to RGBA and vertex input attribute extraction.
These additional requirements may be expensive on some implementations, and should only be enabled when truly necessary.
This extension also adds support for "null descriptors", where VK_NULL_HANDLE can be used instead of a valid handle. Accesses to null descriptors have well-defined behavior, and don’t rely on robustness.
New Enum Constants
-
VK_EXT_ROBUSTNESS_2_EXTENSION_NAME
-
VK_EXT_ROBUSTNESS_2_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ROBUSTNESS_2_PROPERTIES_EXT
-
Issues
-
Why do VkPhysicalDeviceRobustness2PropertiesEXT::
robustUniformBufferAccessSizeAlignment
and VkPhysicalDeviceRobustness2PropertiesEXT::robustStorageBufferAccessSizeAlignment
exist?
RESOLVED: Some implementations can’t efficiently tightly bounds-check all buffer accesses. Rather, the size of the bound range is padded to some power of two multiple, up to 256 bytes for uniform buffers and up to 4 bytes for storage buffers, and that padded size is bounds-checked. This is sufficient to implement D3D-like behavior, because D3D only allows binding whole uniform buffers or ranges that are a multiple of 256 bytes, and D3D raw and structured buffers only support 32-bit accesses.
VK_EXT_sample_locations
- Name String
-
VK_EXT_sample_locations
- Extension Type
-
Device extension
- Registered Extension Number
-
144
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2017-08-02
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
Slawomir Grajewski, Intel
-
Jeff Bolz, NVIDIA
-
Bill Licea-Kane, Qualcomm
-
Description
This extension allows an application to modify the locations of samples within a pixel used in rasterization. Additionally, it allows applications to specify different sample locations for each pixel in a group of adjacent pixels, which can increase antialiasing quality (particularly if a custom resolve shader is used that takes advantage of these different locations).
It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle may be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated, thus the depth aspect of a depth/stencil attachment must be cleared before rendering to it using different sample locations.
Some implementations may need to evaluate depth image values while performing image layout transitions. To accommodate this, instances of the VkSampleLocationsInfoEXT structure can be specified for each situation where an explicit or automatic layout transition has to take place. VkSampleLocationsInfoEXT can be chained from VkImageMemoryBarrier structures to provide sample locations for layout transitions performed by vkCmdWaitEvents and vkCmdPipelineBarrier calls, and VkRenderPassSampleLocationsBeginInfoEXT can be chained from VkRenderPassBeginInfo to provide sample locations for layout transitions performed implicitly by a render pass instance.
New Enum Constants
-
VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME
-
VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION
-
Extending VkDynamicState:
-
VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT
-
-
Extending VkImageCreateFlagBits:
-
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
-
VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
-
VK_EXT_shader_atomic_float
- Name String
-
VK_EXT_shader_atomic_float
- Extension Type
-
Device extension
- Registered Extension Number
-
261
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha-nv
-
Other Extension Metadata
- Last Modified Date
-
2020-07-15
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_shader_atomic_float_add
-
This extension provides API support for
GL_EXT_shader_atomic_float
-
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jeff Bolz, NVIDIA
-
Description
This extension allows a shader to contain floating-point atomic operations
on buffer, workgroup, and image memory.
It also advertises the SPIR-V AtomicFloat32AddEXT
and
AtomicFloat64AddEXT
capabilities that allows atomic addition on
floating-points numbers.
The supported operations include OpAtomicFAddEXT
,
OpAtomicExchange
, OpAtomicLoad
and OpAtomicStore
.
New Enum Constants
-
VK_EXT_SHADER_ATOMIC_FLOAT_EXTENSION_NAME
-
VK_EXT_SHADER_ATOMIC_FLOAT_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT
-
VK_EXT_shader_demote_to_helper_invocation
- Name String
-
VK_EXT_shader_demote_to_helper_invocation
- Extension Type
-
Device extension
- Registered Extension Number
-
277
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-01
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_demote_to_helper_invocation
-
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds Vulkan support for the
SPV_EXT_demote_to_helper_invocation
SPIR-V extension.
That SPIR-V extension provides a new instruction
OpDemoteToHelperInvocationEXT
allowing shaders to "demote" a fragment
shader invocation to behave like a helper invocation for its duration.
The demoted invocation will have no further side effects and will not output
to the framebuffer, but remains active and can participate in computing
derivatives and in group operations.
This is a better match for the "discard" instruction in HLSL.
New Enum Constants
-
VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_EXTENSION_NAME
-
VK_EXT_SHADER_DEMOTE_TO_HELPER_INVOCATION_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DEMOTE_TO_HELPER_INVOCATION_FEATURES_EXT
-
VK_EXT_shader_image_atomic_int64
- Name String
-
VK_EXT_shader_image_atomic_int64
- Extension Type
-
Device extension
- Registered Extension Number
-
235
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2020-07-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus Chajdas, AMD
-
Graham Wihlidal, Epic Games
-
Tobias Hector, AMD
-
Jeff Bolz, Nvidia
-
Jason Ekstrand, Intel
-
- Interactions and External Dependencies
-
-
This extension requires the
SPV_EXT_shader_image_int64
SPIR-V extension. -
This extension requires the
GLSL_EXT_shader_image_int64
extension for GLSL source languages.
-
Description
This extension extends existing 64-bit integer atomic support to enable these operations on images as well.
When working with large 2- or 3-dimensional data sets (e.g. rasterization or screen-space effects), image accesses are generally more efficient than equivalent buffer accesses. This extension allows applications relying on 64-bit integer atomics in this manner to quickly improve performance with only relatively minor code changes.
64-bit integer atomic support is guaranteed for optimally tiled images with
the VK_FORMAT_R64_UINT
and VK_FORMAT_R64_SINT
formats.
New Enum Constants
-
VK_EXT_SHADER_IMAGE_ATOMIC_INT64_EXTENSION_NAME
-
VK_EXT_SHADER_IMAGE_ATOMIC_INT64_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_IMAGE_ATOMIC_INT64_FEATURES_EXT
-
VK_EXT_shader_stencil_export
- Name String
-
VK_EXT_shader_stencil_export
- Extension Type
-
Device extension
- Registered Extension Number
-
141
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-07-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_EXT_shader_stencil_export
-
This extension provides API support for
GL_ARB_shader_stencil_export
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Description
This extension adds support for the SPIR-V extension
SPV_EXT_shader_stencil_export
, providing a mechanism whereby a shader may
generate the stencil reference value per invocation.
When stencil testing is enabled, this allows the test to be performed
against the value generated in the shader.
New Enum Constants
-
VK_EXT_SHADER_STENCIL_EXPORT_EXTENSION_NAME
-
VK_EXT_SHADER_STENCIL_EXPORT_SPEC_VERSION
VK_EXT_subgroup_size_control
- Name String
-
VK_EXT_subgroup_size_control
- Extension Type
-
Device extension
- Registered Extension Number
-
226
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.1
-
- Contact
-
-
Neil Henning sheredom
-
Other Extension Metadata
- Last Modified Date
-
2019-03-05
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Jason Ekstrand, Intel
-
Sławek Grajewski, Intel
-
Jesse Hall, Google
-
Neil Henning, AMD
-
Daniel Koch, NVIDIA
-
Jeff Leger, Qualcomm
-
Graeme Leese, Broadcom
-
Allan MacKinnon, Google
-
Mariusz Merecki, Intel
-
Graham Wihlidal, Electronic Arts
-
Description
This extension enables an implementation to control the subgroup size by allowing a varying subgroup size and also specifying a required subgroup size.
It extends the subgroup support in Vulkan 1.1 to allow an implementation to expose a varying subgroup size. Previously Vulkan exposed a single subgroup size per physical device, with the expectation that implementations will behave as if all subgroups have the same size. Some implementations may dispatch shaders with a varying subgroup size for different subgroups. As a result they could implicitly split a large subgroup into smaller subgroups or represent a small subgroup as a larger subgroup, some of whose invocations were inactive on launch.
To aid developers in understanding the performance characteristics of their
programs, this extension exposes a minimum and maximum subgroup size that a
physical device supports and a pipeline create flag to enable that pipeline
to vary its subgroup size.
If enabled, any SubgroupSize
decorated variables in the SPIR-V shader
modules provided to pipeline creation may vary between the
minimum and
maximum subgroup sizes.
An implementation is also optionally allowed to support specifying a
required subgroup size for a given pipeline stage.
Implementations advertise which stages support a required subgroup size, and any pipeline of a supported
stage can be passed a
VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure to
set the subgroup size for that shader stage of the pipeline.
For compute shaders, this requires the developer to query the
maxComputeWorkgroupSubgroups
and ensure that:
Developers can also specify a new pipeline shader stage create flag that requires the implementation to have fully populated subgroups within local workgroups. This requires the workgroup size in the X dimension to be a multiple of the subgroup size.
New Enum Constants
-
VK_EXT_SUBGROUP_SIZE_CONTROL_EXTENSION_NAME
-
VK_EXT_SUBGROUP_SIZE_CONTROL_SPEC_VERSION
-
Extending VkPipelineShaderStageCreateFlagBits:
-
VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
-
VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT
-
Version History
-
Revision 1, 2019-03-05 (Neil Henning)
-
Initial draft
-
-
Revision 2, 2019-07-26 (Jason Ekstrand)
-
Add the missing VkPhysicalDeviceSubgroupSizeControlFeaturesEXT for querying subgroup size control features.
-
VK_EXT_swapchain_colorspace
- Name String
-
VK_EXT_swapchain_colorspace
- Extension Type
-
Instance extension
- Registered Extension Number
-
105
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Courtney Goeltzenleuchter courtney-g
-
Other Extension Metadata
- Last Modified Date
-
2019-04-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Courtney Goeltzenleuchter, Google
-
New Enum Constants
-
VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME
-
VK_EXT_SWAPCHAIN_COLOR_SPACE_SPEC_VERSION
-
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT
-
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT
-
VK_COLOR_SPACE_BT2020_LINEAR_EXT
-
VK_COLOR_SPACE_BT709_LINEAR_EXT
-
VK_COLOR_SPACE_BT709_NONLINEAR_EXT
-
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT
-
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT
-
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT
-
VK_COLOR_SPACE_DOLBYVISION_EXT
-
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT
-
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT
-
VK_COLOR_SPACE_HDR10_HLG_EXT
-
VK_COLOR_SPACE_HDR10_ST2084_EXT
-
VK_COLOR_SPACE_PASS_THROUGH_EXT
-
Issues
1) Does the spec need to specify which kinds of image formats support the color spaces?
RESOLVED: Pixel format is independent of color space (though some color spaces really want / need floating point color components to be useful). Therefore, do not plan on documenting what formats support which colorspaces. An application can call vkGetPhysicalDeviceSurfaceFormatsKHR to query what a particular implementation supports.
2) How does application determine if HW supports appropriate transfer function for a colorspace?
RESOLVED: Extension indicates that implementation must not do the OETF encoding if it is not sRGB. That responsibility falls to the application shaders. Any other native OETF / EOTF functions supported by an implementation can be described by separate extension.
Version History
-
Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
-
Initial version
-
-
Revision 2, 2017-01-19 (Courtney Goeltzenleuchter)
-
Add pass through and multiple options for BT2020.
-
Clean up some issues with equations not displaying properly.
-
-
Revision 3, 2017-06-23 (Courtney Goeltzenleuchter)
-
Add extended sRGB non-linear enum.
-
-
Revision 4, 2019-04-26 (Graeme Leese)
-
Clarify colorspace transfer function usage.
-
Refer to normative definitions in the Data Format Specification.
-
Clarify DCI-P3 and Display P3 usage.
-
VK_EXT_texel_buffer_alignment
- Name String
-
VK_EXT_texel_buffer_alignment
- Extension Type
-
Device extension
- Registered Extension Number
-
282
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jeff Bolz jeffbolznv
-
Other Extension Metadata
- Last Modified Date
-
2019-06-06
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
- Contributors
-
-
Jeff Bolz, NVIDIA
-
Description
This extension adds more expressive alignment requirements for uniform and
storage texel buffers.
Some implementations have single texel alignment requirements that can’t be
expressed via
VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment
.
New Enum Constants
-
VK_EXT_TEXEL_BUFFER_ALIGNMENT_EXTENSION_NAME
-
VK_EXT_TEXEL_BUFFER_ALIGNMENT_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXEL_BUFFER_ALIGNMENT_PROPERTIES_EXT
-
VK_EXT_texture_compression_astc_hdr
- Name String
-
VK_EXT_texture_compression_astc_hdr
- Extension Type
-
Device extension
- Registered Extension Number
-
67
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Jan-Harald Fredriksen janharaldfredriksen-arm
-
Other Extension Metadata
- Last Modified Date
-
2019-05-28
- IP Status
-
No known issues.
- Contributors
-
-
Jan-Harald Fredriksen, Arm
-
Description
This extension adds support for textures compressed using the Adaptive Scalable Texture Compression (ASTC) High Dynamic Range (HDR) profile.
When this extension is enabled, the HDR profile is supported for all ASTC formats listed in ASTC Compressed Image Formats.
New Enum Constants
-
VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_EXTENSION_NAME
-
VK_EXT_TEXTURE_COMPRESSION_ASTC_HDR_SPEC_VERSION
-
Extending VkFormat:
-
VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK_EXT
-
VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TEXTURE_COMPRESSION_ASTC_HDR_FEATURES_EXT
-
Issues
1) Should we add a feature or limit for this functionality?
Yes. It is consistent with the ASTC LDR support to add a feature like textureCompressionASTC_HDR.
The feature is strictly speaking redundant as long as this is just an extension; it would be sufficient to just enable the extension. But adding the feature is more forward-looking if wanted to make this an optional core feature in the future.
2) Should we introduce new format enums for HDR?
Yes.
Vulkan 1.0 describes the ASTC format enums as UNORM, e.g.
VK_FORMAT_ASTC_4x4_UNORM_BLOCK
, so it’s confusing to make these
contain HDR data.
Note that the OpenGL (ES) extensions did not make this distinction because a
single ASTC HDR texture may contain both unorm and float blocks.
Implementations may not be able to distinguish between LDR and HDR ASTC
textures internally and just treat them as the same format, i.e. if this
extension is supported then sampling from a
VK_FORMAT_ASTC_4x4_UNORM_BLOCK
image format may return HDR results.
Applications can get predictable results by using the appropriate image
format.
VK_EXT_tooling_info
- Name String
-
VK_EXT_tooling_info
- Extension Type
-
Device extension
- Registered Extension Number
-
246
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2018-11-05
- Contributors
-
-
Rolando Caloca
-
Matthaeus Chajdas
-
Baldur Karlsson
-
Daniel Rakos
-
Description
When an error occurs during application development, a common question is "What tools are actually running right now?" This extension adds the ability to query that information directly from the Vulkan implementation.
Outdated versions of one tool might not play nicely with another, or perhaps a tool is not actually running when it should have been. Trying to figure that out can cause headaches as it is necessary to consult each known tool to figure out what is going on — in some cases the tool might not even be known.
Typically, the expectation is that developers will simply print out this information for visual inspection when an issue occurs, however a small amount of semantic information about what the tool is doing is provided to help identify it programmatically. For example, if the advertised limits or features of an implementation are unexpected, is there a tool active which modifies these limits? Or if an application is providing debug markers, but the implementation is not actually doing anything with that information, this can quickly point that out.
New Enum Constants
-
VK_EXT_TOOLING_INFO_EXTENSION_NAME
-
VK_EXT_TOOLING_INFO_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TOOL_PROPERTIES_EXT
-
If VK_EXT_debug_marker is supported:
-
Extending VkToolPurposeFlagBitsEXT:
-
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT
-
If VK_EXT_debug_report is supported:
-
Extending VkToolPurposeFlagBitsEXT:
-
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT
-
If VK_EXT_debug_utils is supported:
-
Extending VkToolPurposeFlagBitsEXT:
-
VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT
-
VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT
-
Examples
uint32_t num_tools;
VkPhysicalDeviceToolPropertiesEXT *pToolProperties;
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, NULL);
pToolProperties = (VkPhysicalDeviceToolPropertiesEXT*)malloc(sizeof(VkPhysicalDeviceToolPropertiesEXT) * num_tools);
vkGetPhysicalDeviceToolPropertiesEXT(physicalDevice, &num_tools, pToolProperties);
for (int i = 0; i < num_tools; ++i) {
printf("%s:\n", pToolProperties[i].name);
printf("Version:\n");
printf("%s:\n", pToolProperties[i].version);
printf("Description:\n");
printf("\t%s\n", pToolProperties[i].description);
printf("Purposes:\n");
printf("\t%s\n", VkToolPurposeFlagBitsEXT_to_string(pToolProperties[i].purposes));
if (strnlen_s(pToolProperties[i].layer,VK_MAX_EXTENSION_NAME_SIZE) > 0) {
printf("Corresponding Layer:\n");
printf("\t%s\n", pToolProperties[i].layer);
}
}
Issues
1) Why is this information separate from the layer mechanism?
Some tooling may be built into a driver, or be part of the Vulkan loader etc. - and so tying this information directly to layers would’ve been awkward at best.
VK_EXT_transform_feedback
- Name String
-
VK_EXT_transform_feedback
- Extension Type
-
Device extension
- Registered Extension Number
-
29
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Uses
- Contact
-
-
Piers Daniell pdaniell-nv
-
Other Extension Metadata
- Last Modified Date
-
2018-10-09
- Contributors
-
-
Baldur Karlsson, Valve
-
Boris Zanin, Mobica
-
Daniel Rakos, AMD
-
Donald Scorgie, Imagination
-
Henri Verbeet, CodeWeavers
-
Jan-Harald Fredriksen, Arm
-
Jason Ekstrand, Intel
-
Jeff Bolz, NVIDIA
-
Jesse Barker, Unity
-
Jesse Hall, Google
-
Pierre-Loup Griffais, Valve
-
Philip Rebohle, DXVK
-
Ruihao Zhang, Qualcomm
-
Samuel Pitoiset, Valve
-
Slawomir Grajewski, Intel
-
Stu Smith, Imagination Technologies
-
Description
This extension adds transform feedback to the Vulkan API by exposing the
SPIR-V TransformFeedback
and GeometryStreams
capabilities to
capture vertex, tessellation or geometry shader outputs to one or more
buffers.
It adds API functionality to bind transform feedback buffers to capture the
primitives emitted by the graphics pipeline from SPIR-V outputs decorated
for transform feedback.
The transform feedback capture can be paused and resumed by way of storing
and retrieving a byte counter.
The captured data can be drawn again where the vertex count is derived from
the byte counter without CPU intervention.
If the implementation is capable, a vertex stream other than zero can be
rasterized.
All these features are designed to match the full capabilities of OpenGL core transform feedback functionality and beyond. Many of the features are optional to allow base OpenGL ES GPUs to also implement this extension.
The primary purpose of the functionality exposed by this extension is to support translation layers from other 3D APIs. This functionality is not considered forward looking, and is not expected to be promoted to a KHR extension or to core Vulkan. Unless this is needed for translation, it is recommended that developers use alternative techniques of using the GPU to process and capture vertex data.
New Enum Constants
-
VK_EXT_TRANSFORM_FEEDBACK_EXTENSION_NAME
-
VK_EXT_TRANSFORM_FEEDBACK_SPEC_VERSION
-
Extending VkAccessFlagBits:
-
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
-
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT
-
VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
-
-
Extending VkBufferUsageFlagBits:
-
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT
-
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT
-
-
Extending VkPipelineStageFlagBits:
-
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT
-
Issues
1) Should we include pause/resume functionality?
RESOLVED: Yes, this is needed to ease layering other APIs which have this
functionality.
To pause use vkCmdEndTransformFeedbackEXT
and provide valid buffer
handles in the pCounterBuffers
array and offsets in the
pCounterBufferOffsets
array for the implementation to save the resume
points.
Then to resume use vkCmdBeginTransformFeedbackEXT
with the previous
pCounterBuffers
and pCounterBufferOffsets
values.
Between the pause and resume there needs to be a memory barrier for the
counter buffers with a source access of
VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT
at pipeline stage
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
to a destination access
of VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
at pipeline stage
VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT
.
2) How does this interact with multiview?
RESOLVED: Transform feedback cannot be made active in a render pass with multiview enabled.
3) How should queries be done?
RESOLVED: There is a new query type
VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT
.
A query pool created with this type will capture 2 integers -
numPrimitivesWritten and numPrimitivesNeeded - for the specified vertex
stream output from the last vertex processing stage.
The vertex stream output queried is zero by default, but can be specified
with the new vkCmdBeginQueryIndexedEXT
and
vkCmdEndQueryIndexedEXT
commands.
VK_EXT_validation_cache
- Name String
-
VK_EXT_validation_cache
- Extension Type
-
Device extension
- Registered Extension Number
-
161
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Cort Stratton cdwfs
-
Other Extension Metadata
- Last Modified Date
-
2017-08-29
- IP Status
-
No known IP claims.
- Contributors
-
-
Cort Stratton, Google
-
Chris Forbes, Google
-
Description
This extension provides a mechanism for caching the results of potentially expensive internal validation operations across multiple runs of a Vulkan application. At the core is the VkValidationCacheEXT object type, which is managed similarly to the existing VkPipelineCache.
The new struct VkShaderModuleValidationCacheCreateInfoEXT can be
included in the pNext
chain at vkCreateShaderModule time.
It contains a VkValidationCacheEXT to use when validating the
VkShaderModule.
New Enum Constants
-
VK_EXT_VALIDATION_CACHE_EXTENSION_NAME
-
VK_EXT_VALIDATION_CACHE_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_VALIDATION_CACHE_EXT
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT
-
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT
-
VK_EXT_validation_features
- Name String
-
VK_EXT_validation_features
- Extension Type
-
Instance extension
- Registered Extension Number
-
248
- Revision
-
4
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Karl Schultz karl-lunarg
-
Other Extension Metadata
- Last Modified Date
-
2018-11-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Karl Schultz, LunarG
-
Dave Houlton, LunarG
-
Mark Lobodzinski, LunarG
-
Camden Stocker, LunarG
-
Tony Barbour, LunarG
-
John Zulauf, LunarG
-
Description
This extension provides the VkValidationFeaturesEXT struct that can be
included in the pNext
chain of the VkInstanceCreateInfo
structure passed as the pCreateInfo
parameter of
vkCreateInstance.
The structure contains an array of VkValidationFeatureEnableEXT enum
values that enable specific validation features that are disabled by
default.
The structure also contains an array of VkValidationFeatureDisableEXT
enum values that disable specific validation layer features that are enabled
by default.
Note
The |
New Structures
-
Extending VkInstanceCreateInfo:
New Enum Constants
-
VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME
-
VK_EXT_VALIDATION_FEATURES_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT
-
Version History
-
Revision 1, 2018-11-14 (Karl Schultz)
-
Initial revision
-
-
Revision 2, 2019-08-06 (Mark Lobodzinski)
-
Add Best Practices enable
-
-
Revision 3, 2020-03-04 (Tony Barbour)
-
Add Debug Printf enable
-
-
Revision 4, 2020-07-29 (John Zulauf)
-
Add Synchronization Validation enable
-
VK_EXT_vertex_attribute_divisor
- Name String
-
VK_EXT_vertex_attribute_divisor
- Extension Type
-
Device extension
- Registered Extension Number
-
191
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Vikram Kushwaha vkushwaha
-
Other Extension Metadata
- Last Modified Date
-
2018-08-03
- IP Status
-
No known IP claims.
- Contributors
-
-
Vikram Kushwaha, NVIDIA
-
Jason Ekstrand, Intel
-
Description
This extension allows instance-rate vertex attributes to be repeated for certain number of instances instead of advancing for every instance when instanced rendering is enabled.
New Structures
-
Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
-
Extending VkPhysicalDeviceProperties2:
-
Extending VkPipelineVertexInputStateCreateInfo:
New Enum Constants
-
VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_EXTENSION_NAME
-
VK_EXT_VERTEX_ATTRIBUTE_DIVISOR_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT
-
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT
-
Issues
1) What is the effect of a non-zero value for firstInstance
?
RESOLVED: The Vulkan API should follow the OpenGL convention and offset
attribute fetching by firstInstance
while computing vertex attribute
offsets.
2) Should zero be an allowed divisor?
RESOLVED: Yes. A zero divisor means the vertex attribute is repeated for all instances.
Examples
To create a vertex binding such that the first binding uses instanced rendering and the same attribute is used for every 4 draw instances, an application could use the following set of structures:
const VkVertexInputBindingDivisorDescriptionEXT divisorDesc =
{
0,
4
};
const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT, // sType
NULL, // pNext
1, // vertexBindingDivisorCount
&divisorDesc // pVertexBindingDivisors
}
const VkVertexInputBindingDescription binding =
{
0, // binding
sizeof(Vertex), // stride
VK_VERTEX_INPUT_RATE_INSTANCE // inputRate
};
const VkPipelineVertexInputStateCreateInfo viInfo =
{
VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO, // sType
&divisorInfo, // pNext
...
};
//...
Version History
-
Revision 1, 2017-12-04 (Vikram Kushwaha)
-
First Version
-
-
Revision 2, 2018-07-16 (Jason Ekstrand)
-
Adjust the interaction between
divisor
andfirstInstance
to match the OpenGL convention. -
Disallow divisors of zero.
-
-
Revision 3, 2018-08-03 (Vikram Kushwaha)
-
Allow a zero divisor.
-
Add a physical device features structure to query/enable this feature.
-
VK_EXT_ycbcr_image_arrays
- Name String
-
VK_EXT_ycbcr_image_arrays
- Extension Type
-
Device extension
- Registered Extension Number
-
253
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
- Contact
-
-
Piers Daniell pdaniell-nv
-
Description
This extension allows images of a format that requires Y′CBCR conversion to be created with multiple array layers, which is otherwise restricted.
New Enum Constants
-
VK_EXT_YCBCR_IMAGE_ARRAYS_EXTENSION_NAME
-
VK_EXT_YCBCR_IMAGE_ARRAYS_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_YCBCR_IMAGE_ARRAYS_FEATURES_EXT
-
VK_AMD_buffer_marker
- Name String
-
VK_AMD_buffer_marker
- Extension Type
-
Device extension
- Registered Extension Number
-
180
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2018-01-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
Description
This extension adds a new operation to execute pipelined writes of small
marker values into a VkBuffer
object.
The primary purpose of these markers is to facilitate the development of debugging tools for tracking which pipelined command contributed to device loss.
VK_AMD_device_coherent_memory
- Name String
-
VK_AMD_device_coherent_memory
- Extension Type
-
Device extension
- Registered Extension Number
-
230
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2019-02-04
- Contributors
-
-
Ping Fu, AMD
-
Timothy Lottes, AMD
-
Tobias Hector, AMD
-
Description
This extension adds the device coherent and device uncached memory types. Any device accesses to device coherent memory are automatically made visible to any other device access. Device uncached memory indicates to applications that caches are disabled for a particular memory type, which guarantees device coherence.
Device coherent and uncached memory are expected to have lower performance for general access than non-device coherent memory, but can be useful in certain scenarios; particularly so for debugging.
New Enum Constants
-
VK_AMD_DEVICE_COHERENT_MEMORY_EXTENSION_NAME
-
VK_AMD_DEVICE_COHERENT_MEMORY_SPEC_VERSION
-
Extending VkMemoryPropertyFlagBits:
-
VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
-
VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COHERENT_MEMORY_FEATURES_AMD
-
VK_AMD_display_native_hdr
- Name String
-
VK_AMD_display_native_hdr
- Extension Type
-
Device extension
- Registered Extension Number
-
214
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_get_surface_capabilities2
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2018-12-18
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Aaron Hagan, AMD
-
Aric Cyr, AMD
-
Timothy Lottes, AMD
-
Derrick Owens, AMD
-
Daniel Rakos, AMD
-
Description
This extension introduces the following display native HDR features to Vulkan:
-
A new VkColorSpaceKHR enum for setting the native display colorspace. For example, this color space would be set by the swapchain to use the native color space in Freesync2 displays.
-
Local dimming control
New Enum Constants
-
VK_AMD_DISPLAY_NATIVE_HDR_EXTENSION_NAME
-
VK_AMD_DISPLAY_NATIVE_HDR_SPEC_VERSION
-
Extending VkColorSpaceKHR:
-
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD
-
VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD
-
VK_AMD_gcn_shader
- Name String
-
VK_AMD_gcn_shader
- Extension Type
-
Device extension
- Registered Extension Number
-
26
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-05-30
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_gcn_shader
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Graham Sellers, AMD
-
VK_AMD_memory_overallocation_behavior
- Name String
-
VK_AMD_memory_overallocation_behavior
- Extension Type
-
Device extension
- Registered Extension Number
-
190
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Martin Dinkov mdinkov
-
Other Extension Metadata
- Last Modified Date
-
2018-09-19
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus Chajdas, AMD
-
Daniel Rakos, AMD
-
Jon Campbell, AMD
-
Description
This extension allows controlling whether explicit overallocation beyond the device memory heap sizes (reported by VkPhysicalDeviceMemoryProperties) is allowed or not. Overallocation may lead to performance loss and is not supported for all platforms.
New Enum Constants
-
VK_AMD_MEMORY_OVERALLOCATION_BEHAVIOR_EXTENSION_NAME
-
VK_AMD_MEMORY_OVERALLOCATION_BEHAVIOR_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_DEVICE_MEMORY_OVERALLOCATION_CREATE_INFO_AMD
-
VK_AMD_mixed_attachment_samples
- Name String
-
VK_AMD_mixed_attachment_samples
- Extension Type
-
Device extension
- Registered Extension Number
-
137
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2017-07-24
- Contributors
-
-
Mais Alnasser, AMD
-
Matthaeus G. Chajdas, AMD
-
Maciej Jesionowski, AMD
-
Daniel Rakos, AMD
-
Description
This extension enables applications to use multisampled rendering with a depth/stencil sample count that is larger than the color sample count. Having a depth/stencil sample count larger than the color sample count allows maintaining geometry and coverage information at a higher sample rate than color information. All samples are depth/stencil tested, but only the first color sample count number of samples get a corresponding color output.
New Enum Constants
-
VK_AMD_MIXED_ATTACHMENT_SAMPLES_EXTENSION_NAME
-
VK_AMD_MIXED_ATTACHMENT_SAMPLES_SPEC_VERSION
VK_AMD_pipeline_compiler_control
- Name String
-
VK_AMD_pipeline_compiler_control
- Extension Type
-
Device extension
- Registered Extension Number
-
184
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Daniel Rakos, AMD
-
Maciej Jesionowski, AMD
-
Tobias Hector, AMD
-
Description
This extension introduces VkPipelineCompilerControlCreateInfoAMD structure that can be chained to a pipeline’s create info to specify additional flags that affect pipeline compilation.
New Enum Constants
-
VK_AMD_PIPELINE_COMPILER_CONTROL_EXTENSION_NAME
-
VK_AMD_PIPELINE_COMPILER_CONTROL_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_COMPILER_CONTROL_CREATE_INFO_AMD
-
VK_AMD_rasterization_order
- Name String
-
VK_AMD_rasterization_order
- Extension Type
-
Device extension
- Registered Extension Number
-
19
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Daniel Rakos drakos-amd
-
Other Extension Metadata
- Last Modified Date
-
2016-04-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Jaakko Konttinen, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Dominik Witczak, AMD
-
Description
This extension introduces the possibility for the application to control the order of primitive rasterization. In unextended Vulkan, the following stages are guaranteed to execute in API order:
-
depth bounds test
-
stencil test, stencil op, and stencil write
-
depth test and depth write
-
occlusion queries
-
blending, logic op, and color write
This extension enables applications to opt into a relaxed, implementation defined primitive rasterization order that may allow better parallel processing of primitives and thus enabling higher primitive throughput. It is applicable in cases where the primitive rasterization order is known to not affect the output of the rendering or any differences caused by a different rasterization order are not a concern from the point of view of the application’s purpose.
A few examples of cases when using the relaxed primitive rasterization order would not have an effect on the final rendering:
-
If the primitives rendered are known to not overlap in framebuffer space.
-
If depth testing is used with a comparison operator of
VK_COMPARE_OP_LESS
,VK_COMPARE_OP_LESS_OR_EQUAL
,VK_COMPARE_OP_GREATER
, orVK_COMPARE_OP_GREATER_OR_EQUAL
, and the primitives rendered are known to not overlap in clip space. -
If depth testing is not used and blending is enabled for all attachments with a commutative blend operator.
New Enum Constants
-
VK_AMD_RASTERIZATION_ORDER_EXTENSION_NAME
-
VK_AMD_RASTERIZATION_ORDER_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD
-
Issues
1) How is this extension useful to application developers?
RESOLVED: Allows them to increase primitive throughput for cases when strict API order rasterization is not important due to the nature of the content, the configuration used, or the requirements towards the output of the rendering.
2) How does this extension interact with content optimizations aiming to reduce overdraw by appropriately ordering the input primitives?
RESOLVED: While the relaxed rasterization order might somewhat limit the effectiveness of such content optimizations, most of the benefits of it are expected to be retained even when the relaxed rasterization order is used, so applications should still apply these optimizations even if they intend to use the extension.
3) Are there any guarantees about the primitive rasterization order when using the new relaxed mode?
RESOLVED: No. In this case the rasterization order is completely implementation dependent, but in practice it is expected to partially still follow the order of incoming primitives.
4) Does the new relaxed rasterization order have any adverse effect on repeatability and other invariance rules of the API?
RESOLVED: Yes, in the sense that it extends the list of exceptions when the repeatability requirement does not apply.
VK_AMD_shader_ballot
- Name String
-
VK_AMD_shader_ballot
- Extension Type
-
Device extension
- Registered Extension Number
-
38
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2016-09-19
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_ballot
-
- Contributors
-
-
Qun Lin, AMD
-
Graham Sellers, AMD
-
Daniel Rakos, AMD
-
Rex Xu, AMD
-
Dominik Witczak, AMD
-
Matthäus G. Chajdas, AMD
-
VK_AMD_shader_core_properties
- Name String
-
VK_AMD_shader_core_properties
- Extension Type
-
Device extension
- Registered Extension Number
-
186
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Martin Dinkov mdinkov
-
Other Extension Metadata
- Last Modified Date
-
2019-06-25
- IP Status
-
No known IP claims.
- Contributors
-
-
Martin Dinkov, AMD
-
Matthaeus G. Chajdas, AMD
-
Description
This extension exposes shader core properties for a target physical device
through the VK_KHR_get_physical_device_properties2
extension.
Please refer to the example below for proper usage.
New Enum Constants
-
VK_AMD_SHADER_CORE_PROPERTIES_EXTENSION_NAME
-
VK_AMD_SHADER_CORE_PROPERTIES_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD
-
Examples
This example retrieves the shader core properties for a physical device.
extern VkInstance instance;
PFN_vkGetPhysicalDeviceProperties2 pfnVkGetPhysicalDeviceProperties2 =
reinterpret_cast<PFN_vkGetPhysicalDeviceProperties2>
(vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceProperties2") );
VkPhysicalDeviceProperties2 general_props;
VkPhysicalDeviceShaderCorePropertiesAMD shader_core_properties;
shader_core_properties.pNext = nullptr;
shader_core_properties.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD;
general_props.pNext = &shader_core_properties;
general_props.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2;
// After this call, shader_core_properties has been populated
pfnVkGetPhysicalDeviceProperties2(device, &general_props);
printf("Number of shader engines: %d\n",
m_shader_core_properties.shader_engine_count =
shader_core_properties.shaderEngineCount;
printf("Number of shader arrays: %d\n",
m_shader_core_properties.shader_arrays_per_engine_count =
shader_core_properties.shaderArraysPerEngineCount;
printf("Number of CUs per shader array: %d\n",
m_shader_core_properties.compute_units_per_shader_array =
shader_core_properties.computeUnitsPerShaderArray;
printf("Number of SIMDs per compute unit: %d\n",
m_shader_core_properties.simd_per_compute_unit =
shader_core_properties.simdPerComputeUnit;
printf("Number of wavefront slots in each SIMD: %d\n",
m_shader_core_properties.wavefronts_per_simd =
shader_core_properties.wavefrontsPerSimd;
printf("Number of threads per wavefront: %d\n",
m_shader_core_properties.wavefront_size =
shader_core_properties.wavefrontSize;
printf("Number of physical SGPRs per SIMD: %d\n",
m_shader_core_properties.sgprs_per_simd =
shader_core_properties.sgprsPerSimd;
printf("Minimum number of SGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_sgpr_allocation =
shader_core_properties.minSgprAllocation;
printf("Number of available SGPRs: %d\n",
m_shader_core_properties.max_sgpr_allocation =
shader_core_properties.maxSgprAllocation;
printf("SGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.sgpr_allocation_granularity =
shader_core_properties.sgprAllocationGranularity;
printf("Number of physical VGPRs per SIMD: %d\n",
m_shader_core_properties.vgprs_per_simd =
shader_core_properties.vgprsPerSimd;
printf("Minimum number of VGPRs that can be allocated by a wave: %d\n",
m_shader_core_properties.min_vgpr_allocation =
shader_core_properties.minVgprAllocation;
printf("Number of available VGPRs: %d\n",
m_shader_core_properties.max_vgpr_allocation =
shader_core_properties.maxVgprAllocation;
printf("VGPRs are allocated in groups of this size: %d\n",
m_shader_core_properties.vgpr_allocation_granularity =
shader_core_properties.vgprAllocationGranularity;
Version History
-
Revision 2, 2019-06-25 (Matthaeus G. Chajdas)
-
Clarified the meaning of a few fields.
-
-
Revision 1, 2018-02-15 (Martin Dinkov)
-
Initial draft.
-
VK_AMD_shader_core_properties2
- Name String
-
VK_AMD_shader_core_properties2
- Extension Type
-
Device extension
- Registered Extension Number
-
228
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_AMD_shader_core_properties
-
- Contact
-
-
Matthaeus G. Chajdas anteru
-
Other Extension Metadata
- Last Modified Date
-
2019-07-26
- IP Status
-
No known IP claims.
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Tobias Hector, AMD
-
Description
This extension exposes additional shader core properties for a target
physical device through the VK_KHR_get_physical_device_properties2
extension.
New Enum Constants
-
VK_AMD_SHADER_CORE_PROPERTIES_2_EXTENSION_NAME
-
VK_AMD_SHADER_CORE_PROPERTIES_2_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_2_AMD
-
VK_AMD_shader_explicit_vertex_parameter
- Name String
-
VK_AMD_shader_explicit_vertex_parameter
- Extension Type
-
Device extension
- Registered Extension Number
-
22
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_explicit_vertex_parameter
-
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_EXTENSION_NAME
-
VK_AMD_SHADER_EXPLICIT_VERTEX_PARAMETER_SPEC_VERSION
VK_AMD_shader_fragment_mask
- Name String
-
VK_AMD_shader_fragment_mask
- Extension Type
-
Device extension
- Registered Extension Number
-
138
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Aaron Hagan AaronHaganAMD
-
Other Extension Metadata
- Last Modified Date
-
2017-08-16
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_fragment_mask
-
- Contributors
-
-
Aaron Hagan, AMD
-
Daniel Rakos, AMD
-
Timothy Lottes, AMD
-
Description
This extension provides efficient read access to the fragment mask in compressed multisampled color surfaces. The fragment mask is a lookup table that associates color samples with color fragment values.
From a shader, the fragment mask can be fetched with a call to
fragmentMaskFetchAMD
, which returns a single uint
where each
subsequent four bits specify the color fragment index corresponding to the
color sample, starting from the least significant bit.
For example, when eight color samples are used, the color fragment index for
color sample 0 will be in bits 0-3 of the fragment mask, for color sample 7
the index will be in bits 28-31.
The color fragment for a particular color sample may then be fetched with
the corresponding fragment mask value using the fragmentFetchAMD
shader
function.
New Enum Constants
-
VK_AMD_SHADER_FRAGMENT_MASK_EXTENSION_NAME
-
VK_AMD_SHADER_FRAGMENT_MASK_SPEC_VERSION
Examples
This example shows a shader that queries the fragment mask from a multisampled compressed surface and uses it to query fragment values.
#version 450 core
#extension GL_AMD_shader_fragment_mask: enable
layout(binding = 0) uniform sampler2DMS s2DMS;
layout(binding = 1) uniform isampler2DMSArray is2DMSArray;
layout(binding = 2, input_attachment_index = 0) uniform usubpassInputMS usubpassMS;
layout(location = 0) out vec4 fragColor;
void main()
{
vec4 fragOne = vec4(0.0);
uint fragMask = fragmentMaskFetchAMD(s2DMS, ivec2(2, 3));
uint fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(s2DMS, ivec2(2, 3), 1);
fragMask = fragmentMaskFetchAMD(is2DMSArray, ivec3(2, 3, 1));
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(is2DMSArray, ivec3(2, 3, 1), fragIndex);
fragMask = fragmentMaskFetchAMD(usubpassMS);
fragIndex = (fragMask & 0xF0) >> 4;
fragOne += fragmentFetchAMD(usubpassMS, fragIndex);
fragColor = fragOne;
}
VK_AMD_shader_image_load_store_lod
- Name String
-
VK_AMD_shader_image_load_store_lod
- Extension Type
-
Device extension
- Registered Extension Number
-
47
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Dominik Witczak dominikwitczakamd
-
Other Extension Metadata
- Last Modified Date
-
2017-08-21
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_image_load_store_lod
-
This extension provides API support for
GL_AMD_shader_image_load_store_lod
-
- IP Status
-
No known IP claims.
- Contributors
-
-
Dominik Witczak, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_IMAGE_LOAD_STORE_LOD_EXTENSION_NAME
-
VK_AMD_SHADER_IMAGE_LOAD_STORE_LOD_SPEC_VERSION
VK_AMD_shader_info
- Name String
-
VK_AMD_shader_info
- Extension Type
-
Device extension
- Registered Extension Number
-
43
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Jaakko Konttinen jaakkoamd
-
Other Extension Metadata
- Last Modified Date
-
2017-10-09
- IP Status
-
No known IP claims.
- Contributors
-
-
Jaakko Konttinen, AMD
-
Description
This extension adds a way to query certain information about a compiled shader which is part of a pipeline. This information may include shader disassembly, shader binary and various statistics about a shader’s resource usage.
While this extension provides a mechanism for extracting this information, the details regarding the contents or format of this information are not specified by this extension and may be provided by the vendor externally.
Furthermore, all information types are optionally supported, and users should not assume every implementation supports querying every type of information.
Examples
This example extracts the register usage of a fragment shader within a particular graphics pipeline:
extern VkDevice device;
extern VkPipeline gfxPipeline;
PFN_vkGetShaderInfoAMD pfnGetShaderInfoAMD = (PFN_vkGetShaderInfoAMD)vkGetDeviceProcAddr(
device, "vkGetShaderInfoAMD");
VkShaderStatisticsInfoAMD statistics = {};
size_t dataSize = sizeof(statistics);
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_STATISTICS_AMD,
&dataSize,
&statistics) == VK_SUCCESS)
{
printf("VGPR usage: %d\n", statistics.resourceUsage.numUsedVgprs);
printf("SGPR usage: %d\n", statistics.resourceUsage.numUsedSgprs);
}
The following example continues the previous example by subsequently attempting to query and print shader disassembly about the fragment shader:
// Query disassembly size (if available)
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
nullptr) == VK_SUCCESS)
{
printf("Fragment shader disassembly:\n");
void* disassembly = malloc(dataSize);
// Query disassembly and print
if (pfnGetShaderInfoAMD(device,
gfxPipeline,
VK_SHADER_STAGE_FRAGMENT_BIT,
VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
&dataSize,
disassembly) == VK_SUCCESS)
{
printf((char*)disassembly);
}
free(disassembly);
}
VK_AMD_shader_trinary_minmax
- Name String
-
VK_AMD_shader_trinary_minmax
- Extension Type
-
Device extension
- Registered Extension Number
-
21
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Qun Lin linqun
-
Other Extension Metadata
- Last Modified Date
-
2016-05-10
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_shader_trinary_minmax
-
- Contributors
-
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Rex Xu, AMD
-
New Enum Constants
-
VK_AMD_SHADER_TRINARY_MINMAX_EXTENSION_NAME
-
VK_AMD_SHADER_TRINARY_MINMAX_SPEC_VERSION
VK_AMD_texture_gather_bias_lod
- Name String
-
VK_AMD_texture_gather_bias_lod
- Extension Type
-
Device extension
- Registered Extension Number
-
42
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Rex Xu amdrexu
-
Other Extension Metadata
- Last Modified Date
-
2017-03-21
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_AMD_texture_gather_bias_lod
-
- Contributors
-
-
Dominik Witczak, AMD
-
Daniel Rakos, AMD
-
Graham Sellers, AMD
-
Matthaeus G. Chajdas, AMD
-
Qun Lin, AMD
-
Rex Xu, AMD
-
Timothy Lottes, AMD
-
Description
This extension adds two related features.
Firstly, support for the following SPIR-V extension in Vulkan is added:
-
SPV_AMD_texture_gather_bias_lod
Secondly, the extension allows the application to query which formats can be used together with the new function prototypes introduced by the SPIR-V extension.
New Enum Constants
-
VK_AMD_TEXTURE_GATHER_BIAS_LOD_EXTENSION_NAME
-
VK_AMD_TEXTURE_GATHER_BIAS_LOD_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD
-
Examples
struct VkTextureLODGatherFormatPropertiesAMD
{
VkStructureType sType;
const void* pNext;
VkBool32 supportsTextureGatherLODBiasAMD;
};
// ----------------------------------------------------------------------------------------
// How to detect if an image format can be used with the new function prototypes.
VkPhysicalDeviceImageFormatInfo2 formatInfo;
VkImageFormatProperties2 formatProps;
VkTextureLODGatherFormatPropertiesAMD textureLODGatherSupport;
textureLODGatherSupport.sType = VK_STRUCTURE_TYPE_TEXTURE_LOD_GATHER_FORMAT_PROPERTIES_AMD;
textureLODGatherSupport.pNext = nullptr;
formatInfo.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2;
formatInfo.pNext = nullptr;
formatInfo.format = ...;
formatInfo.type = ...;
formatInfo.tiling = ...;
formatInfo.usage = ...;
formatInfo.flags = ...;
formatProps.sType = VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2;
formatProps.pNext = &textureLODGatherSupport;
vkGetPhysicalDeviceImageFormatProperties2(physical_device, &formatInfo, &formatProps);
if (textureLODGatherSupport.supportsTextureGatherLODBiasAMD == VK_TRUE)
{
// physical device supports SPV_AMD_texture_gather_bias_lod for the specified
// format configuration.
}
else
{
// physical device does not support SPV_AMD_texture_gather_bias_lod for the
// specified format configuration.
}
VK_ANDROID_external_memory_android_hardware_buffer
- Name String
-
VK_ANDROID_external_memory_android_hardware_buffer
- Extension Type
-
Device extension
- Registered Extension Number
-
130
- Revision
-
3
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_sampler_ycbcr_conversion
-
Requires
VK_KHR_external_memory
-
Requires
VK_EXT_queue_family_foreign
-
Requires
VK_KHR_dedicated_allocation
-
- Contact
-
-
Jesse Hall critsec
-
Other Extension Metadata
- Last Modified Date
-
2019-08-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Ray Smith, ARM
-
Chad Versace, Google
-
Jesse Hall, Google
-
Tobias Hector, Imagination
-
James Jones, NVIDIA
-
Tony Zlatinski, NVIDIA
-
Matthew Netsch, Qualcomm
-
Andrew Garrard, Samsung
-
Description
This extension enables an application to import Android
AHardwareBuffer
objects created outside of the Vulkan device into
Vulkan memory objects, where they can be bound to images and buffers.
It also allows exporting an AHardwareBuffer
from a Vulkan memory
object for symmetry with other operating systems.
But since not all AHardwareBuffer
usages and formats have Vulkan
equivalents, exporting from Vulkan provides strictly less functionality than
creating the AHardwareBuffer
externally and importing it.
Some AHardwareBuffer
images have implementation-defined external
formats that may not correspond to Vulkan formats.
Sampler Y′CBCR conversion can be used to sample from these images and
convert them to a known color space.
New Enum Constants
-
VK_ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME
-
VK_ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION
-
Extending VkExternalMemoryHandleTypeFlagBits:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID
-
VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID
-
VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID
-
VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
-
VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
-
Issues
1) Other external memory objects are represented as weakly-typed handles
(e.g. Win32 HANDLE
or POSIX file descriptor), and require a handle type
parameter along with handles.
AHardwareBuffer
is strongly typed, so naming the handle type is
redundant.
Does symmetry justify adding handle type parameters/fields anyway?
RESOLVED: No.
The handle type is already provided in places that treat external memory
objects generically.
In the places we would add it, the application code that would have to
provide the handle type value is already dealing with
AHardwareBuffer
-specific commands/structures; the extra symmetry
would not be enough to make that code generic.
2) The internal layout and therefore size of a AHardwareBuffer
image may depend on native usage flags that do not have corresponding Vulkan
counterparts.
Do we provide this info to vkCreateImage somehow, or allow the
allocation size reported by vkGetImageMemoryRequirements to be
approximate?
RESOLVED: Allow the allocation size to be unspecified when allocating the
memory.
It has to work this way for exported image memory anyway, since
AHardwareBuffer
allocation happens in vkAllocateMemory, and
internally is performed by a separate HAL, not the Vulkan implementation
itself.
There is a similar issue with vkGetImageSubresourceLayout: the layout
is determined by the allocator HAL, so it is not known until the image is
bound to memory.
3) Should the result of sampling an external-format image with the suggested
Y′CBCR conversion parameters yield the same results as using a
samplerExternalOES
in OpenGL ES?
RESOLVED: This would be desirable, so that apps converting from OpenGL ES to Vulkan could get the same output given the same input. But since sampling and conversion from Y′CBCR images is so loosely defined in OpenGL ES, multiple implementations do it in a way that doesn’t conform to Vulkan’s requirements. Modifying the OpenGL ES implementation would be difficult, and would change the output of existing unmodified applications. Changing the output only for applications that are being modified gives developers the chance to notice and mitigate any problems. Implementations are encouraged to minimize differences as much as possible without causing compatibility problems for existing OpenGL ES applications or violating Vulkan requirements.
4) Should an AHardwareBuffer
with AHARDWAREBUFFER_USAGE_CPU_
*
usage be mappable in Vulkan? Should it be possible to export an
AHardwareBuffers
with such usage?
RESOLVED: Optional, and mapping in Vulkan is not the same as
AHardwareBuffer_lock
.
The semantics of these are different: mapping in memory is persistent, just
gives a raw view of the memory contents, and does not involve ownership.
AHardwareBuffer_lock
gives the host exclusive access to the buffer, is
temporary, and allows for reformatting copy-in/copy-out.
Implementations are not required to support host-visible memory types for
imported Android hardware buffers or resources backed by them.
If a host-visible memory type is supported and used, the memory can be
mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw
view of the data and does not imply ownership (this means implementations
must not internally call AHardwareBuffer_lock
to implement
vkMapMemory, or assume the application has done so).
Implementations are not required to support linear-tiled images backed by
Android hardware buffers, even if the AHardwareBuffer
has CPU
usage.
There is no reliable way to allocate memory in Vulkan that can be exported
to a AHardwareBuffer
with CPU usage.
5) Android may add new AHardwareBuffer
formats and usage flags over
time.
Can reference to them be added to this extension, or do they need a new
extension?
RESOLVED: This extension can document the interaction between the new AHB
formats/usages and existing Vulkan features.
No new Vulkan features or implementation requirements can be added.
The extension version number will be incremented when this additional
documentation is added, but the version number does not indicate that an
implementaiton supports Vulkan memory or resources that map to the new
AHardwareBuffer
features: support for that must be queried with
vkGetPhysicalDeviceImageFormatProperties2 or is implied by
successfully allocating a AHardwareBuffer
outside of Vulkan that
uses the new feature and has a GPU usage flag.
In essence, these are new features added to a new Android API level, rather than new Vulkan features. The extension will only document how existing Vulkan features map to that new Android feature.
Version History
-
Revision 3, 2019-08-27 (Jon Leech)
-
Update revision history to correspond to XML version number
-
-
Revision 2, 2018-04-09 (Petr Kraus)
-
Markup fixes and remove incorrect Draft status
-
-
Revision 1, 2018-03-04 (Jesse Hall)
-
Initial version
-
VK_FUCHSIA_imagepipe_surface
- Name String
-
VK_FUCHSIA_imagepipe_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
215
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Craig Stout cdotstout
-
Other Extension Metadata
- Last Modified Date
-
2018-07-27
- IP Status
-
No known IP claims.
- Contributors
-
-
Craig Stout, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Description
The VK_FUCHSIA_imagepipe_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Fuchsia
imagePipeHandle
.
New Enum Constants
-
VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME
-
VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA
-
VK_GGP_frame_token
- Name String
-
VK_GGP_frame_token
- Extension Type
-
Device extension
- Registered Extension Number
-
192
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
Requires
VK_GGP_stream_descriptor_surface
-
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Richard O’Grady, Google
-
Description
This extension allows an application that uses the VK_KHR_swapchain
extension in combination with a Google Games Platform surface provided by
the VK_GGP_stream_descriptor_surface
extension to associate a Google
Games Platform frame token with a present operation.
New Structures
-
Extending VkPresentInfoKHR:
New Enum Constants
-
VK_GGP_FRAME_TOKEN_EXTENSION_NAME
-
VK_GGP_FRAME_TOKEN_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP
-
VK_GGP_stream_descriptor_surface
- Name String
-
VK_GGP_stream_descriptor_surface
- Extension Type
-
Instance extension
- Registered Extension Number
-
50
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_surface
-
- Contact
-
-
Jean-Francois Roy jfroy
-
Other Extension Metadata
- Last Modified Date
-
2019-01-28
- IP Status
-
No known IP claims.
- Contributors
-
-
Jean-Francois Roy, Google
-
Brad Grantham, Google
-
Connor Smith, Google
-
Cort Stratton, Google
-
Hai Nguyen, Google
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Jim Ray, Google
-
Katherine Wu, Google
-
Kaye Mason, Google
-
Kuangye Guo, Google
-
Mark Segal, Google
-
Nicholas Vining, Google
-
Paul Lalonde, Google
-
Richard O’Grady, Google
-
Description
The VK_GGP_stream_descriptor_surface
extension is an instance extension.
It provides a mechanism to create a VkSurfaceKHR object (defined by
the VK_KHR_surface
extension) that refers to a Google Games Platform
GgpStreamDescriptor
.
New Enum Constants
-
VK_GGP_STREAM_DESCRIPTOR_SURFACE_EXTENSION_NAME
-
VK_GGP_STREAM_DESCRIPTOR_SURFACE_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_STREAM_DESCRIPTOR_SURFACE_CREATE_INFO_GGP
-
VK_GOOGLE_decorate_string
- Name String
-
VK_GOOGLE_decorate_string
- Extension Type
-
Device extension
- Registered Extension Number
-
225
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_decorate_string
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
Description
The VK_GOOGLE_decorate_string
extension allows use of the
SPV_GOOGLE_decorate_string
extension in SPIR-V shader modules.
VK_GOOGLE_display_timing
- Name String
-
VK_GOOGLE_display_timing
- Extension Type
-
Device extension
- Registered Extension Number
-
93
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
Requires
VK_KHR_swapchain
-
- Contact
-
-
Ian Elliott ianelliottus
-
Other Extension Metadata
- Last Modified Date
-
2017-02-14
- IP Status
-
No known IP claims.
- Contributors
-
-
Ian Elliott, Google
-
Jesse Hall, Google
-
Description
This device extension allows an application that uses the
VK_KHR_swapchain
extension to obtain information about the
presentation engine’s display, to obtain timing information about each
present, and to schedule a present to happen no earlier than a desired time.
An application can use this to minimize various visual anomalies (e.g.
stuttering).
Traditional game and real-time animation applications need to correctly position their geometry for when the presentable image will be presented to the user. To accomplish this, applications need various timing information about the presentation engine’s display. They need to know when presentable images were actually presented, and when they could have been presented. Applications also need to tell the presentation engine to display an image no sooner than a given time. This allows the application to avoid stuttering, so the animation looks smooth to the user.
This extension treats variable-refresh-rate (VRR) displays as if they are fixed-refresh-rate (FRR) displays.
New Enum Constants
-
VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME
-
VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE
-
Examples
Note
The example code for the this extension (like the |
VK_GOOGLE_hlsl_functionality1
- Name String
-
VK_GOOGLE_hlsl_functionality1
- Extension Type
-
Device extension
- Registered Extension Number
-
224
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Hai Nguyen chaoticbob
-
Other Extension Metadata
- Last Modified Date
-
2018-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_hlsl_functionality1
-
- Contributors
-
-
Hai Nguyen, Google
-
Neil Henning, AMD
-
Description
The VK_GOOGLE_hlsl_functionality1
extension allows use of the
SPV_GOOGLE_hlsl_functionality1
extension in SPIR-V shader modules.
New Enum Constants
-
VK_GOOGLE_HLSL_FUNCTIONALITY1_EXTENSION_NAME
-
VK_GOOGLE_HLSL_FUNCTIONALITY1_SPEC_VERSION
VK_GOOGLE_user_type
- Name String
-
VK_GOOGLE_user_type
- Extension Type
-
Device extension
- Registered Extension Number
-
290
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Kaye Mason chaleur
-
Other Extension Metadata
- Last Modified Date
-
2019-07-09
- IP Status
-
No known IP claims.
- Interactions and External Dependencies
-
-
This extension requires
SPV_GOOGLE_user_type
-
- Contributors
-
-
Kaye Mason, Google
-
Hai Nguyen, Google
-
Description
The VK_GOOGLE_user_type
extension allows use of the SPV_GOOGLE_user_type
extension in SPIR-V shader modules.
VK_IMG_filter_cubic
- Name String
-
VK_IMG_filter_cubic
- Extension Type
-
Device extension
- Registered Extension Number
-
16
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Tobias Hector tobski
-
Other Extension Metadata
- Last Modified Date
-
2016-02-23
- Contributors
-
-
Tobias Hector, Imagination Technologies
-
Description
VK_IMG_filter_cubic
adds an additional, high quality cubic filtering mode
to Vulkan, using a Catmull-Rom bicubic filter.
Performing this kind of filtering can be done in a shader by using 16
samples and a number of instructions, but this can be inefficient.
The cubic filter mode exposes an optimized high quality texture sampling
using fixed texture sampling functionality.
New Enum Constants
-
VK_IMG_FILTER_CUBIC_EXTENSION_NAME
-
VK_IMG_FILTER_CUBIC_SPEC_VERSION
-
Extending VkFilter:
-
VK_FILTER_CUBIC_IMG
-
-
Extending VkFormatFeatureFlagBits:
-
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG
-
Example
Creating a sampler with the new filter for both magnification and minification
VkSamplerCreateInfo createInfo =
{
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
// Other members set to application-desired values
};
createInfo.magFilter = VK_FILTER_CUBIC_IMG;
createInfo.minFilter = VK_FILTER_CUBIC_IMG;
VkSampler sampler;
VkResult result = vkCreateSampler(
device,
&createInfo,
&sampler);
VK_IMG_format_pvrtc
- Name String
-
VK_IMG_format_pvrtc
- Extension Type
-
Device extension
- Registered Extension Number
-
55
- Revision
-
1
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Contact
-
-
Stuart Smith
-
Other Extension Metadata
- Last Modified Date
-
2019-09-02
- IP Status
-
Imagination Technologies Proprietary
- Contributors
-
-
Stuart Smith, Imagination Technologies
-
Description
VK_IMG_format_pvrtc
provides additional texture compression functionality
specific to Imagination Technologies PowerVR Texture compression format
(called PVRTC).
New Enum Constants
-
VK_IMG_FORMAT_PVRTC_EXTENSION_NAME
-
VK_IMG_FORMAT_PVRTC_SPEC_VERSION
-
Extending VkFormat:
-
VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG
-
VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG
-
VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG
-
VK_INTEL_performance_query
- Name String
-
VK_INTEL_performance_query
- Extension Type
-
Device extension
- Registered Extension Number
-
211
- Revision
-
2
- Extension and Version Dependencies
-
-
Requires Vulkan 1.0
-
- Special Use
- Contact
-
-
Lionel Landwerlin llandwerlin
-
Other Extension Metadata
- Last Modified Date
-
2018-05-16
- IP Status
-
No known IP claims.
- Contributors
-
-
Lionel Landwerlin, Intel
-
Piotr Maciejewski, Intel
-
Description
This extension allows an application to capture performance data to be interpreted by a external application or library.
Such a library is available at : https://github.com/intel/metrics-discovery
Performance analysis tools such as Graphics Performance Analyzers make use of this extension and the metrics-discovery library to present the data in a human readable way.
New Enum Constants
-
VK_INTEL_PERFORMANCE_QUERY_EXTENSION_NAME
-
VK_INTEL_PERFORMANCE_QUERY_SPEC_VERSION
-
Extending VkObjectType:
-
VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL
-
-
Extending VkQueryType:
-
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL
-
-
Extending VkStructureType:
-
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL
-
VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL
-
VK_STRUCTURE_TYPE_QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL
-
Example Code
// A previously created device
VkDevice device;
// A queue derived from the device
VkQueue queue;
VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = {
VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL,
NULL,
NULL
};
vkInitializePerformanceApiINTEL(
device,
&performanceApiInfoIntel);
VkQueryPoolPerformanceQueryCreateInfoINTEL queryPoolIntel = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL,
NULL,
VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL,
};
VkQueryPoolCreateInfo queryPoolCreateInfo = {
VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
&queryPoolIntel,
0,
VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL,
1,
0
};
VkQueryPool queryPool;
VkResult result = vkCreateQueryPool(
device,
&queryPoolCreateInfo,
NULL,
&queryPool);
assert(VK_SUCCESS == result);
// A command buffer we want to record counters on
VkCommandBuffer commandBuffer;
VkCommandBufferBeginInfo commandBufferBeginInfo = {
VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
NULL,
VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
NULL
};
result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo);
assert(VK_SUCCESS == result);
vkCmdResetQueryPool(
commandBuffer,
queryPool,
0,
1);
vkCmdBeginQuery(
commandBuffer,
queryPool,
0,
0);
// Perform the commands you want to get performance information on
//