Vulkan-Docs/doc/specs/vulkan/appendices/VK_NV_dedicated_allocation.txt

== VK_NV_dedicated_allocation

*Name String*:: VK_NV_dedicated_allocation
*Extension Type*:: Device extension
*Registered Extension Number*:: 27
*Status*:: Draft.
*Last Modified Date*:: 31/05/2016
*Revision*:: 1
*IP Status*:: No known IP claims.
*Dependencies*::
    - This extension is written against version 1.0. of the Vulkan API.
*Contributors*::
    - Jeff Bolz, NVIDIA
*Contacts*::
    - Jeff Bolz (jbolz 'at' nvidia.com)

This extension allows device memory to be allocated for a particular buffer or
image resource, which on some devices can significantly improve the
performance of that resource. Normal device memory allocations must support
memory aliasing and sparse binding, which could interfere with optimizations
like framebuffer compression or efficient page table usage. This is important
for render targets and very large resources, but need not (and probably should
not) be used for smaller resources that can benefit from suballocation.

This extension adds a few small structures to resource creation and memory
allocation: a new structure that flags whether am image/buffer will have a
dedicated allocation, and a structure indicating the image or buffer that an
allocation will be bound to.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV
  ** ename:VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV
  ** ename:VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV

=== New Enums

None.

=== New Structures

  * slink:VkDedicatedAllocationImageCreateInfoNV
  * slink:VkDedicatedAllocationBufferCreateInfoNV
  * slink:VkDedicatedAllocationMemoryAllocateInfoNV

=== New Functions

None.

=== Issues

None.

=== Examples

[source,{basebackend@docbook:c++:cpp}]
--------------------------------------

    // Create an image with
    // VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation
    // set to VK_TRUE

    VkDedicatedAllocationImageCreateInfoNV dedicatedImageInfo =
    {
        VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV,            // sType
        NULL,                                                                   // pNext
        VK_TRUE,                                                                // dedicatedAllocation
    };

    VkImageCreateInfo imageCreateInfo =
    {
        VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO,    // sType
        &dedicatedImageInfo                     // pNext
        // Other members set as usual
    };

    VkImage image;
    VkResult result = vkCreateImage(
        device,
        &imageCreateInfo,
        NULL,                       // pAllocator
        &image);

    VkMemoryRequirements memoryRequirements;
    vkGetImageMemoryRequirements(
        device,
        image,
        &memoryRequirements);

    // Allocate memory with VkDedicatedAllocationMemoryAllocateInfoNV::image
    // pointing to the image we're allocating the memory for

    VkDedicatedAllocationMemoryAllocateInfoNV dedicatedInfo =
    {
        VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV,             // sType
        NULL,                                                                       // pNext
        image,                                                                      // image
        VK_NULL_HANDLE,                                                             // buffer
    };

    VkMemoryAllocateInfo memoryAllocateInfo =
    {
        VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,                 // sType
        &dedicatedInfo,                                         // pNext
        memoryRequirements.size,                                // allocationSize
        FindMemoryTypeIndex(memoryRequirements.memoryTypeBits), // memoryTypeIndex
    };

    VkDeviceMemory memory;
    vkAllocateMemory(
        device,
        &memoryAllocateInfo,
        NULL,                       // pAllocator
        &memory);

    // Bind the image to the memory

    vkBindImageMemory(
        device,
        image,
        memory,
        0);

--------------------------------------

=== Version History

 * Revision 1, 2016-05-31 (Jeff Bolz)
   - Internal revisions