1// Copyright 2016-2021 The Khronos Group, Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_KHR_buffer_device_address.txt[]
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    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
19    and
20    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
21    and
22    https://github.com/KhronosGroup/GLSL/blob/master/extensions/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
36https://github.com/KhronosGroup/GLSL/blob/master/extensions/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
69https://github.com/KhronosGroup/GLSL/blob/master/extensions/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
72https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
73and
74https://github.com/KhronosGroup/GLSL/blob/master/extensions/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 capability is optional.
83The original type, enum and command names are still available as aliases of
84the core functionality.
85
86include::{generated}/interfaces/VK_KHR_buffer_device_address.txt[]
87
88=== New SPIR-V Capabilities
89
90  * <<spirvenv-capabilities-table-PhysicalStorageBufferAddresses,code:PhysicalStorageBufferAddresses>>
91
92=== Version History
93
94 * Revision 1, 2019-06-24 (Jan-Harald Fredriksen)
95   - Internal revisions based on VK_EXT_buffer_device_address
96
97ifdef::isrefpage[]
98
99=== Examples
100
101There are various use cases this extensions is designed for.
102It is required for ray tracing, useful for DX12 portability, and it allows
103storing buffer addresses in memory (enabling creating more complex data
104strcutures).
105
106This extension can also be used to hardcode a dedicated debug channel into
107all shaders without impacting other descriptor limits by querying a buffer
108device address at startup and pushing that into shaders as a run-time
109constant (e.g. specialization constant).
110
111There are examples of usage in the
112https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference.txt[`GL_EXT_buffer_reference`]
113spec for how to use this in a high-level shading language such as GLSL.
114The
115https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference2.txt[`GL_EXT_buffer_reference2`]
116and
117https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_buffer_reference_uvec2.txt[`GL_EXT_buffer_reference_uvec2`]
118extensions were added to help cover a few edge cases missed by the original
119`GL_EXT_buffer_reference`.
120
121It is important to also be aware that the capture/replay mechanisms are
122meant for capture/replay tools, and should not be used general application
123usage.
124
125endif::isrefpage[]
126