org.lwjgl.vulkan

Class NVExternalMemoryWin32

java.lang.Object

org.lwjgl.vulkan.NVExternalMemoryWin32

public class NVExternalMemoryWin32
extends java.lang.Object

Applications may wish to export memory to other Vulkan instances or other APIs, or import memory from other Vulkan instances or other APIs to enable Vulkan workloads to be split up across application module, process, or API boundaries. This extension enables win32 applications to export win32 handles from Vulkan memory objects such that the underlying resources can be referenced outside the Vulkan instance that created them, and import win32 handles created in the Direct3D API to Vulkan memory objects.

Examples

     //
     // Create an exportable memory object and export an external
     // handle from it.
     //
 
     // Pick an external format and handle type.
     static const VkFormat format = VK_FORMAT_R8G8B8A8_UNORM;
     static const VkExternalMemoryHandleTypeFlagsNV handleType =
         VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV;
 
     extern VkPhysicalDevice physicalDevice;
     extern VkDevice device;
 
     VkPhysicalDeviceMemoryProperties memoryProperties;
     VkExternalImageFormatPropertiesNV properties;
     VkExternalMemoryImageCreateInfoNV externalMemoryImageCreateInfo;
     VkDedicatedAllocationImageCreateInfoNV dedicatedImageCreateInfo;
     VkImageCreateInfo imageCreateInfo;
     VkImage image;
     VkMemoryRequirements imageMemoryRequirements;
     uint32_t numMemoryTypes;
     uint32_t memoryType;
     VkExportMemoryAllocateInfoNV exportMemoryAllocateInfo;
     VkDedicatedAllocationMemoryAllocateInfoNV dedicatedAllocationInfo;
     VkMemoryAllocateInfo memoryAllocateInfo;
     VkDeviceMemory memory;
     VkResult result;
     HANDLE memoryHnd;
 
     // Figure out how many memory types the device supports
     vkGetPhysicalDeviceMemoryProperties(physicalDevice,
                                         &memoryProperties);
     numMemoryTypes = memoryProperties.memoryTypeCount;
 
     // Check the external handle type capabilities for the chosen format
     // Exportable 2D image support with at least 1 mip level, 1 array
     // layer, and VK_SAMPLE_COUNT_1_BIT using optimal tiling and supporting
     // texturing and color rendering is required.
     result = vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
         physicalDevice,
         format,
         VK_IMAGE_TYPE_2D,
         VK_IMAGE_TILING_OPTIMAL,
         VK_IMAGE_USAGE_SAMPLED_BIT |
         VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
         0,
         handleType,
         &properties);
 
     if ((result != VK_SUCCESS) ||
         !(properties.externalMemoryFeatures &
           VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NV)) {
         abort();
     }
 
     // Set up the external memory image creation info
     memset(&externalMemoryImageCreateInfo,
            0, sizeof(externalMemoryImageCreateInfo));
     externalMemoryImageCreateInfo.sType =
         VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV;
     externalMemoryImageCreateInfo.handleTypes = handleType;
     if (properties.externalMemoryFeatures &
         VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
         memset(&dedicatedImageCreateInfo, 0, sizeof(dedicatedImageCreateInfo));
         dedicatedImageCreateInfo.sType =
             VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV;
         dedicatedImageCreateInfo.dedicatedAllocation = VK_TRUE;
         externalMemoryImageCreateInfo.pNext = &dedicatedImageCreateInfo;
     }
     // Set up the  core image creation info
     memset(&imageCreateInfo, 0, sizeof(imageCreateInfo));
     imageCreateInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
     imageCreateInfo.pNext = &externalMemoryImageCreateInfo;
     imageCreateInfo.format = format;
     imageCreateInfo.extent.width = 64;
     imageCreateInfo.extent.height = 64;
     imageCreateInfo.extent.depth = 1;
     imageCreateInfo.mipLevels = 1;
     imageCreateInfo.arrayLayers = 1;
     imageCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;
     imageCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
     imageCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT |
         VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
     imageCreateInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
     imageCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
 
     vkCreateImage(device, &imageCreateInfo, NULL, &image);
 
     vkGetImageMemoryRequirements(device,
                                  image,
                                  &imageMemoryRequirements);
 
     // For simplicity, just pick the first compatible memory type.
     for (memoryType = 0; memoryType < numMemoryTypes; memoryType++) {
         if ((1 << memoryType) & imageMemoryRequirements.memoryTypeBits) {
             break;
         }
     }
 
     // At least one memory type must be supported given the prior external
     // handle capability check.
     assert(memoryType < numMemoryTypes);
 
     // Allocate the external memory object.
     memset(&exportMemoryAllocateInfo, 0, sizeof(exportMemoryAllocateInfo));
     exportMemoryAllocateInfo.sType =
         VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO_NV;
     exportMemoryAllocateInfo.handleTypes = handleType;
     if (properties.externalMemoryFeatures &
         VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV) {
         memset(&dedicatedAllocationInfo, 0, sizeof(dedicatedAllocationInfo));
         dedicatedAllocationInfo.sType =
             VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_MEMORY_ALLOCATE_INFO_NV;
         dedicatedAllocationInfo.image = image;
         exportMemoryAllocateInfo.pNext = &dedicatedAllocationInfo;
     }
     memset(&memoryAllocateInfo, 0, sizeof(memoryAllocateInfo));
     memoryAllocateInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
     memoryAllocateInfo.pNext = &exportMemoryAllocateInfo;
     memoryAllocateInfo.allocationSize = imageMemoryRequirements.size;
     memoryAllocateInfo.memoryTypeIndex = memoryType;
 
     vkAllocateMemory(device, &memoryAllocateInfo, NULL, &memory);
 
     if (!(properties.externalMemoryFeatures &
           VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV)) {
         vkBindImageMemory(device, image, memory, 0);
     }
 
     // Get the external memory opaque FD handle
     vkGetMemoryWin32HandleNV(device, memory, &memoryHnd);

Name String

VK_NV_external_memory_win32

Extension Type

Device extension

Registered Extension Number

58

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_NV_external_memory

Deprecation state

• Deprecated by VK_KHR_external_memory_win32 extension

Contact

• James Jones cubanismo

Last Modified Date

2016-08-19

IP Status

No known IP claims.

Contributors

• James Jones, NVIDIA
• Carsten Rohde, NVIDIA

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VK_NV_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME The extension name.
static int	VK_NV_EXTERNAL_MEMORY_WIN32_SPEC_VERSION The extension specification version.
static int	VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV Extends VkStructureType.
static int	VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static int	nvkGetMemoryWin32HandleNV(org.lwjgl.vulkan.VkDevice device, long memory, int handleType, long pHandle) Unsafe version of: GetMemoryWin32HandleNV
static int	vkGetMemoryWin32HandleNV(org.lwjgl.vulkan.VkDevice device, long memory, int handleType, org.lwjgl.PointerBuffer pHandle) retrieve Win32 handle to a device memory object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VK_NV_EXTERNAL_MEMORY_WIN32_SPEC_VERSION

public static final int VK_NV_EXTERNAL_MEMORY_WIN32_SPEC_VERSION

The extension specification version.

See Also:

Constant Field Values

VK_NV_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME

public static final java.lang.String VK_NV_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME

The extension name.

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV

public static final int VK_STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV
• STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

public static final int VK_STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_IMPORT_MEMORY_WIN32_HANDLE_INFO_NV
• STRUCTURE_TYPE_EXPORT_MEMORY_WIN32_HANDLE_INFO_NV

See Also:

Constant Field Values

Method Detail

nvkGetMemoryWin32HandleNV

public static int nvkGetMemoryWin32HandleNV(org.lwjgl.vulkan.VkDevice device,
                                            long memory,
                                            int handleType,
                                            long pHandle)

Unsafe version of: GetMemoryWin32HandleNV

vkGetMemoryWin32HandleNV

public static int vkGetMemoryWin32HandleNV(org.lwjgl.vulkan.VkDevice device,
                                           long memory,
                                           int handleType,
                                           org.lwjgl.PointerBuffer pHandle)

retrieve Win32 handle to a device memory object.

C Specification

To retrieve the handle corresponding to a device memory object created with VkExportMemoryAllocateInfoNV::handleTypes set to include EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV or EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV, call:

 VkResult vkGetMemoryWin32HandleNV(
     VkDevice                                    device,
     VkDeviceMemory                              memory,
     VkExternalMemoryHandleTypeFlagsNV           handleType,
     HANDLE*                                     pHandle);

Valid Usage

• handleType must be a flag specified in VkExportMemoryAllocateInfoNV::handleTypes when allocating memory

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• memory must be a valid VkDeviceMemory handle
• handleType must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values
• handleType must not be 0
• pHandle must be a valid pointer to a HANDLE value
• memory must have been created, allocated, or retrieved from device

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_TOO_MANY_OBJECTS
• ERROR_OUT_OF_HOST_MEMORY

Parameters:

device - the logical device that owns the memory.

memory - the VkDeviceMemory object.

handleType - a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a single bit specifying the type of handle requested.