• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2016-2022 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_KHR_dedicated_allocation.adoc[]
6
7=== Other Extension Metadata
8
9*Last Modified Date*::
10    2017-09-05
11*IP Status*::
12    No known IP claims.
13*Interactions and External Dependencies*::
14  - Promoted to Vulkan 1.1 Core
15*Contributors*::
16  - Jeff Bolz, NVIDIA
17  - Jason Ekstrand, Intel
18
19=== Description
20
21This extension enables resources to be bound to a dedicated allocation,
22rather than suballocated.
23For any particular resource, applications can: query whether a dedicated
24allocation is recommended, in which case using a dedicated allocation may:
25improve the performance of access to that resource.
26Normal device memory allocations must support multiple resources per
27allocation, memory aliasing and sparse binding, which could interfere with
28some optimizations.
29Applications should query the implementation for when a dedicated allocation
30may: be beneficial by adding a sname:VkMemoryDedicatedRequirementsKHR
31structure to the pname:pNext chain of the sname:VkMemoryRequirements2
32structure passed as the pname:pMemoryRequirements parameter of a call to
33fname:vkGetBufferMemoryRequirements2 or fname:vkGetImageMemoryRequirements2.
34Certain external handle types and external images or buffers may: also
35depend on dedicated allocations on implementations that associate image or
36buffer metadata with OS-level memory objects.
37
38This extension adds a two small structures to memory requirements querying
39and memory allocation: a new structure that flags whether an image/buffer
40should have a dedicated allocation, and a structure indicating the image or
41buffer that an allocation will be bound to.
42
43=== Promotion to Vulkan 1.1
44
45All functionality in this extension is included in core Vulkan 1.1, with the
46KHR suffix omitted.
47The original type, enum and command names are still available as aliases of
48the core functionality.
49
50include::{generated}/interfaces/VK_KHR_dedicated_allocation.adoc[]
51
52=== Examples
53
54[source,c++]
55--------------------------------------
56
57    // Create an image with a dedicated allocation based on the
58    // implementation's preference
59
60    VkImageCreateInfo imageCreateInfo =
61    {
62        // Image creation parameters
63    };
64
65    VkImage image;
66    VkResult result = vkCreateImage(
67        device,
68        &imageCreateInfo,
69        NULL,                               // pAllocator
70        &image);
71
72    VkMemoryDedicatedRequirementsKHR dedicatedRequirements =
73    {
74        VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS_KHR,
75        NULL,                               // pNext
76    };
77
78    VkMemoryRequirements2 memoryRequirements =
79    {
80        VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2,
81        &dedicatedRequirements,             // pNext
82    };
83
84    const VkImageMemoryRequirementsInfo2 imageRequirementsInfo =
85    {
86        VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2,
87        NULL,                               // pNext
88        image
89    };
90
91    vkGetImageMemoryRequirements2(
92        device,
93        &imageRequirementsInfo,
94        &memoryRequirements);
95
96    if (dedicatedRequirements.prefersDedicatedAllocation) {
97        // Allocate memory with VkMemoryDedicatedAllocateInfoKHR::image
98        // pointing to the image we are allocating the memory for
99
100        VkMemoryDedicatedAllocateInfoKHR dedicatedInfo =
101        {
102            VK_STRUCTURE_TYPE_MEMORY_DEDICATED_ALLOCATE_INFO_KHR,   // sType
103            NULL,                                                   // pNext
104            image,                                                  // image
105            VK_NULL_HANDLE,                                         // buffer
106        };
107
108        VkMemoryAllocateInfo memoryAllocateInfo =
109        {
110            VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,                 // sType
111            &dedicatedInfo,                                         // pNext
112            memoryRequirements.size,                                // allocationSize
113            FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
114        };
115
116        VkDeviceMemory memory;
117        vkAllocateMemory(
118            device,
119            &memoryAllocateInfo,
120            NULL,                       // pAllocator
121            &memory);
122
123        // Bind the image to the memory
124
125        vkBindImageMemory(
126            device,
127            image,
128            memory,
129            0);
130    } else {
131        // Take the normal memory sub-allocation path
132    }
133
134--------------------------------------
135
136=== Version History
137
138  * Revision 1, 2017-02-27 (James Jones)
139  ** Copy content from VK_NV_dedicated_allocation
140  ** Add some references to external object interactions to the overview.
141
142  * Revision 2, 2017-03-27 (Jason Ekstrand)
143  ** Rework the extension to be query-based
144
145  * Revision 3, 2017-07-31 (Jason Ekstrand)
146  ** Clarify that memory objects allocated with
147     VkMemoryDedicatedAllocateInfoKHR can only have the specified resource
148     bound and no others.
149