// Copyright 2016-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_buffer_device_address.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2019-06-24
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - Promoted to Vulkan 1.2 Core
  - This extension requires
    {spirv}/KHR/SPV_KHR_physical_storage_buffer.html[`SPV_KHR_physical_storage_buffer`]
  - This extension provides API support for
    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
    and
    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
    and
    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`]
*Contributors*::
  - Jeff Bolz, NVIDIA
  - Neil Henning, AMD
  - Tobias Hector, AMD
  - Jason Ekstrand, Intel
  - Baldur Karlsson, Valve
  - Jan-Harald Fredriksen, Arm

=== Description

This extension allows the application to query a 64-bit buffer device
address value for a buffer, which can be used to access the buffer memory
via the code:PhysicalStorageBuffer storage class in the
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
GLSL extension and
{spirv}/KHR/SPV_KHR_physical_storage_buffer.html[`SPV_KHR_physical_storage_buffer`]
SPIR-V extension.

Another way to describe this extension is that it adds "`pointers to buffer
memory in shaders`".
By calling flink:vkGetBufferDeviceAddress with a sname:VkBuffer, it will
return a basetype:VkDeviceAddress value which represents the address of the
start of the buffer.

flink:vkGetBufferOpaqueCaptureAddress and
flink:vkGetDeviceMemoryOpaqueCaptureAddress allow opaque addresses for
buffers and memory objects to be queried for the current process.
A trace capture and replay tool can then supply these addresses to be used
at replay time to match the addresses used when the trace was captured.
To enable tools to insert these queries, new memory allocation flags must be
specified for memory objects that will be bound to buffers accessed via the
code:PhysicalStorageBuffer storage class.
Note that this mechanism is intended only to support capture/replay tools,
and is not recommended for use in other applications.

There are various use cases this extension is designed for.
It is required for ray tracing, useful for DX12 portability, and by allowing
buffer addresses to be stored in memory it enables more complex data
structures to be created.

This extension can also be used to hardcode a dedicated debug channel into
all shaders by querying a pointer at startup and pushing that into shaders
as a run-time constant (e.g. specialization constant) that avoids impacting
other descriptor limits.

There are examples of usage in the
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
spec for how to use this in a high-level shading language such as GLSL.
The
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
and
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`]
extensions were also added to help cover a few additional edge cases.

=== Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the
KHR suffix omitted.
However, if Vulkan 1.2 is supported and this extension is not, the
code:bufferDeviceAddress capability is optional.
The original type, enum and command names are still available as aliases of
the core functionality.

include::{generated}/interfaces/VK_KHR_buffer_device_address.txt[]

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-PhysicalStorageBufferAddresses,code:PhysicalStorageBufferAddresses>>

=== Version History

 * Revision 1, 2019-06-24 (Jan-Harald Fredriksen)
   - Internal revisions based on VK_EXT_buffer_device_address

ifdef::isrefpage[]

=== Examples

There are various use cases this extensions is designed for.
It is required for ray tracing, useful for DX12 portability, and it allows
storing buffer addresses in memory (enabling creating more complex data
strcutures).

This extension can also be used to hardcode a dedicated debug channel into
all shaders without impacting other descriptor limits by querying a buffer
device address at startup and pushing that into shaders as a run-time
constant (e.g. specialization constant).

There are examples of usage in the
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
spec for how to use this in a high-level shading language such as GLSL.
The
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
and
https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`]
extensions were added to help cover a few edge cases missed by the original
`GL_EXT_buffer_reference`.

It is important to also be aware that the capture/replay mechanisms are
meant for capture/replay tools, and should not be used general application
usage.

endif::isrefpage[]