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