vulkan-3.8.1: Bindings to the Vulkan graphics API.
Safe HaskellNone
LanguageHaskell2010

Vulkan.Extensions.VK_NV_external_memory_win32

Description

Name

VK_NV_external_memory_win32 - device extension

VK_NV_external_memory_win32

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

Other Extension Metadata

Last Modified Date
2016-08-19
IP Status
No known IP claims.
Contributors
  • James Jones, NVIDIA
  • Carsten Rohde, NVIDIA

Description

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.

New Commands

New Structures

New Enum Constants

Issues

1) If memory objects are shared between processes and APIs, is this considered aliasing according to the rules outlined in the Memory Aliasing section?

RESOLVED: Yes, but strict exceptions to the rules are added to allow some forms of aliasing in these cases. Further, other extensions may build upon these new aliasing rules to define specific support usage within Vulkan for imported native memory objects, or memory objects from other APIs.

2) Are new image layouts or metadata required to specify image layouts and layout transitions compatible with non-Vulkan APIs, or with other instances of the same Vulkan driver?

RESOLVED: No. Separate instances of the same Vulkan driver running on the same GPU should have identical internal layout semantics, so applictions have the tools they need to ensure views of images are consistent between the two instances. Other APIs will fall into two categories: Those that are Vulkan compatible (a term to be defined by subsequent interopability extensions), or Vulkan incompatible. When sharing images with Vulkan incompatible APIs, the Vulkan image must be transitioned to the IMAGE_LAYOUT_GENERAL layout before handing it off to the external API.

Note this does not attempt to address cross-device transitions, nor transitions to engines on the same device which are not visible within the Vulkan API. Both of these are beyond the scope of this extension.

3) Do applications need to call CloseHandle() on the values returned from getMemoryWin32HandleNV when handleType is EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV?

RESOLVED: Yes, unless it is passed back in to another driver instance to import the object. A successful get call transfers ownership of the handle to the application, while an import transfers ownership to the associated driver. Destroying the memory object will not destroy the handle or the handle’s reference to the underlying memory resource.

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);

Version History

  • Revision 1, 2016-08-11 (James Jones)

    • Initial draft

See Also

ExportMemoryWin32HandleInfoNV, ImportMemoryWin32HandleInfoNV, getMemoryWin32HandleNV

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

getMemoryWin32HandleNV Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the logical device that owns the memory.

device must be a valid Device handle

-> DeviceMemory

memory is the DeviceMemory object.

memory must be a valid DeviceMemory handle

memory must have been created, allocated, or retrieved from device

-> ExternalMemoryHandleTypeFlagsNV

handleType is a bitmask of ExternalMemoryHandleTypeFlagBitsNV containing a single bit specifying the type of handle requested.

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

handleType must be a valid combination of ExternalMemoryHandleTypeFlagBitsNV values

handleType must not be 0

-> io HANDLE 

vkGetMemoryWin32HandleNV - retrieve Win32 handle to a device memory object

Return Codes

Success
Failure

See Also

Device, DeviceMemory, ExternalMemoryHandleTypeFlagsNV

data ImportMemoryWin32HandleInfoNV Source #

VkImportMemoryWin32HandleInfoNV - import Win32 memory created on the same physical device

Description

If handleType is 0, this structure is ignored by consumers of the MemoryAllocateInfo structure it is chained from.

Valid Usage (Implicit)

See Also

ExternalMemoryHandleTypeFlagsNV, StructureType

Constructors

ImportMemoryWin32HandleInfoNV 

Fields

Instances

Instances details
Eq ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Show ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Storable ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

FromCStruct ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

ToCStruct ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Zero ImportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

data ExportMemoryWin32HandleInfoNV Source #

VkExportMemoryWin32HandleInfoNV - specify security attributes and access rights for Win32 memory handles

Description

If this structure is not present, or if pAttributes is set to NULL, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for “Synchronization Object Security and Access Rights”1. Further, if the structure is not present, the access rights will be

DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE

1
https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Valid Usage (Implicit)

  • If pAttributes is not NULL, pAttributes must be a valid pointer to a valid SECURITY_ATTRIBUTES value

See Also

StructureType

Constructors

ExportMemoryWin32HandleInfoNV 

Fields

Instances

Instances details
Eq ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Show ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Storable ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

FromCStruct ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

ToCStruct ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

Zero ExportMemoryWin32HandleInfoNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_win32

type NV_EXTERNAL_MEMORY_WIN32_EXTENSION_NAME = "VK_NV_external_memory_win32" Source #

type HANDLE = Ptr () Source #

newtype ExternalMemoryHandleTypeFlagBitsNV Source #

VkExternalMemoryHandleTypeFlagBitsNV - Bitmask specifying external memory handle types

See Also

ExternalMemoryHandleTypeFlagsNV

Bundled Patterns

pattern EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV :: ExternalMemoryHandleTypeFlagBitsNV

EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV specifies a handle to memory returned by getMemoryWin32HandleNV, or one duplicated from such a handle using DuplicateHandle().

pattern EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV :: ExternalMemoryHandleTypeFlagBitsNV

EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_NV specifies a handle to memory returned by getMemoryWin32HandleNV.

pattern EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV :: ExternalMemoryHandleTypeFlagBitsNV

EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_BIT_NV specifies a valid NT handle to memory returned by IDXGIResource1::CreateSharedHandle, or a handle duplicated from such a handle using DuplicateHandle().

pattern EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV :: ExternalMemoryHandleTypeFlagBitsNV

EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_IMAGE_KMT_BIT_NV specifies a handle to memory returned by IDXGIResource::GetSharedHandle().

Instances

Instances details
Eq ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Ord ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Read ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Show ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Storable ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Bits ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Methods

(.&.) :: ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV #

(.|.) :: ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV #

xor :: ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV #

complement :: ExternalMemoryHandleTypeFlagBitsNV -> ExternalMemoryHandleTypeFlagBitsNV #

shift :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

rotate :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

zeroBits :: ExternalMemoryHandleTypeFlagBitsNV #

bit :: Int -> ExternalMemoryHandleTypeFlagBitsNV #

setBit :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

clearBit :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

complementBit :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

testBit :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> Bool #

bitSizeMaybe :: ExternalMemoryHandleTypeFlagBitsNV -> Maybe Int #

bitSize :: ExternalMemoryHandleTypeFlagBitsNV -> Int #

isSigned :: ExternalMemoryHandleTypeFlagBitsNV -> Bool #

shiftL :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

unsafeShiftL :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

shiftR :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

unsafeShiftR :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

rotateL :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

rotateR :: ExternalMemoryHandleTypeFlagBitsNV -> Int -> ExternalMemoryHandleTypeFlagBitsNV #

popCount :: ExternalMemoryHandleTypeFlagBitsNV -> Int #

FiniteBits ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities

Zero ExternalMemoryHandleTypeFlagBitsNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_external_memory_capabilities