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