1// Copyright 2016-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_KHR_buffer_device_address.adoc[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2019-06-24 11*IP Status*:: 12 No known IP claims. 13*Interactions and External Dependencies*:: 14 - Promoted to Vulkan 1.2 Core 15 - This extension requires 16 {spirv}/KHR/SPV_KHR_physical_storage_buffer.html[`SPV_KHR_physical_storage_buffer`] 17 - This extension provides API support for 18 {GLSLregistry}/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`] 19 and 20 {GLSLregistry}/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`] 21 and 22 {GLSLregistry}/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`] 23*Contributors*:: 24 - Jeff Bolz, NVIDIA 25 - Neil Henning, AMD 26 - Tobias Hector, AMD 27 - Jason Ekstrand, Intel 28 - Baldur Karlsson, Valve 29 - Jan-Harald Fredriksen, Arm 30 31=== Description 32 33This extension allows the application to query a 64-bit buffer device 34address value for a buffer, which can be used to access the buffer memory 35via the code:PhysicalStorageBuffer storage class in the 36{GLSLregistry}/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`] 37GLSL extension and 38{spirv}/KHR/SPV_KHR_physical_storage_buffer.html[`SPV_KHR_physical_storage_buffer`] 39SPIR-V extension. 40 41Another way to describe this extension is that it adds "`pointers to buffer 42memory in shaders`". 43By calling flink:vkGetBufferDeviceAddress with a sname:VkBuffer, it will 44return a basetype:VkDeviceAddress value which represents the address of the 45start of the buffer. 46 47flink:vkGetBufferOpaqueCaptureAddress and 48flink:vkGetDeviceMemoryOpaqueCaptureAddress allow opaque addresses for 49buffers and memory objects to be queried for the current process. 50A trace capture and replay tool can then supply these addresses to be used 51at replay time to match the addresses used when the trace was captured. 52To enable tools to insert these queries, new memory allocation flags must be 53specified for memory objects that will be bound to buffers accessed via the 54code:PhysicalStorageBuffer storage class. 55Note that this mechanism is intended only to support capture/replay tools, 56and is not recommended for use in other applications. 57 58There are various use cases this extension is designed for. 59It is required for ray tracing, useful for DX12 portability, and by allowing 60buffer addresses to be stored in memory it enables more complex data 61structures to be created. 62 63This extension can also be used to hardcode a dedicated debug channel into 64all shaders by querying a pointer at startup and pushing that into shaders 65as a run-time constant (e.g. specialization constant) that avoids impacting 66other descriptor limits. 67 68There are examples of usage in the 69{GLSLregistry}/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`] 70spec for how to use this in a high-level shading language such as GLSL. 71The 72{GLSLregistry}/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`] 73and 74{GLSLregistry}/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`] 75extensions were also added to help cover a few additional edge cases. 76 77=== Promotion to Vulkan 1.2 78 79All functionality in this extension is included in core Vulkan 1.2, with the 80KHR suffix omitted. 81However, if Vulkan 1.2 is supported and this extension is not, the 82code:bufferDeviceAddress feature is optional. 83The original type, enum and command names are still available as aliases of 84the core functionality. 85 86=== Promotion to Vulkan 1.3 87 88Support for the code:bufferDeviceAddress feature is mandatory in Vulkan 1.3, 89regardless of whether this extension is supported. 90 91include::{generated}/interfaces/VK_KHR_buffer_device_address.adoc[] 92 93=== New SPIR-V Capabilities 94 95 * <<spirvenv-capabilities-table-PhysicalStorageBufferAddresses, 96 code:PhysicalStorageBufferAddresses>> 97 98ifdef::isrefpage[] 99 100=== Examples 101 102There are various use cases this extensions is designed for. 103It is required for ray tracing, useful for DX12 portability, and it allows 104storing buffer addresses in memory (enabling creating more complex data 105structures). 106 107This extension can also be used to hardcode a dedicated debug channel into 108all shaders without impacting other descriptor limits by querying a buffer 109device address at startup and pushing that into shaders as a run-time 110constant (e.g. specialization constant). 111 112There are examples of usage in the 113{GLSLregistry}/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`] 114spec for how to use this in a high-level shading language such as GLSL. 115The 116{GLSLregistry}/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`] 117and 118{GLSLregistry}/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`] 119extensions were added to help cover a few edge cases missed by the original 120`GL_EXT_buffer_reference`. 121 122It is important to also be aware that the capture/replay mechanisms are 123meant for capture/replay tools, and should not be used general application 124usage. 125 126endif::isrefpage[] 127 128=== Version History 129 130 * Revision 1, 2019-06-24 (Jan-Harald Fredriksen) 131 ** Internal revisions based on VK_EXT_buffer_device_address 132 133