vulkan-2.0.0.1: Bindings to the Vulkan graphics API.

Safe HaskellNone
LanguageHaskell2010

Graphics.Vulkan.Core10.Memory

Synopsis

Documentation

newtype VkMemoryMapFlags Source #

VkMemoryMapFlags - Reserved for future use

Description

VkMemoryMapFlags is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

vkMapMemory

Instances
Eq VkMemoryMapFlags Source # 
Instance details
Ord VkMemoryMapFlags Source # 
Instance details
Read VkMemoryMapFlags Source # 
Instance details
Show VkMemoryMapFlags Source # 
Instance details
Storable VkMemoryMapFlags Source # 
Instance details
Bits VkMemoryMapFlags Source # 
Instance details
FiniteBits VkMemoryMapFlags Source # 
Instance details

vkAllocateMemory :: ("device" ::: VkDevice) -> ("pAllocateInfo" ::: Ptr VkMemoryAllocateInfo) -> ("pAllocator" ::: Ptr VkAllocationCallbacks) -> ("pMemory" ::: Ptr VkDeviceMemory) -> IO VkResult Source #

vkAllocateMemory - Allocate device memory

Parameters

  • device is the logical device that owns the memory.
  • pAllocateInfo is a pointer to an instance of the VkMemoryAllocateInfo structure describing parameters of the allocation. A successful returned allocation must use the requested parameters — no substitution is permitted by the implementation.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.
  • pMemory is a pointer to a VkDeviceMemory handle in which information about the allocated memory is returned.

Description

Allocations returned by vkAllocateMemory are guaranteed to meet any alignment requirement of the implementation. For example, if an implementation requires 128 byte alignment for images and 64 byte alignment for buffers, the device memory returned through this mechanism would be 128-byte aligned. This ensures that applications can correctly suballocate objects of different types (with potentially different alignment requirements) in the same memory object.

When memory is allocated, its contents are undefined.

The maximum number of valid memory allocations that can exist simultaneously within a VkDevice may be restricted by implementation- or platform-dependent limits. If a call to vkAllocateMemory would cause the total number of allocations to exceed these limits, such a call will fail and must return VK_ERROR_TOO_MANY_OBJECTS. The @maxMemoryAllocationCount@ feature describes the number of allocations that can exist simultaneously before encountering these internal limits.

Some platforms may have a limit on the maximum size of a single allocation. For example, certain systems may fail to create allocations with a size greater than or equal to 4GB. Such a limit is implementation-dependent, and if such a failure occurs then the error VK_ERROR_OUT_OF_DEVICE_MEMORY must be returned. This limit is advertised in VkPhysicalDeviceMaintenance3Properties::maxMemoryAllocationSize.

Valid Usage

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • pAllocateInfo must be a valid pointer to a valid VkMemoryAllocateInfo structure
  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
  • pMemory must be a valid pointer to a VkDeviceMemory handle

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY
  • VK_ERROR_TOO_MANY_OBJECTS
  • VK_ERROR_INVALID_EXTERNAL_HANDLE

See Also

VkAllocationCallbacks, VkDevice, VkDeviceMemory, VkMemoryAllocateInfo

vkFreeMemory :: ("device" ::: VkDevice) -> ("memory" ::: VkDeviceMemory) -> ("pAllocator" ::: Ptr VkAllocationCallbacks) -> IO () Source #

vkFreeMemory - Free device memory

Parameters

  • device is the logical device that owns the memory.
  • memory is the VkDeviceMemory object to be freed.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Description

Before freeing a memory object, an application must ensure the memory object is no longer in use by the device—​for example by command buffers in the pending state. The memory can remain bound to images or buffers at the time the memory object is freed, but any further use of them (on host or device) for anything other than destroying those objects will result in undefined behavior. If there are still any bound images or buffers, the memory may not be immediately released by the implementation, but must be released by the time all bound images and buffers have been destroyed. Once memory is released, it is returned to the heap from which it was allocated.

How memory objects are bound to Images and Buffers is described in detail in the Resource Memory Association section.

If a memory object is mapped at the time it is freed, it is implicitly unmapped.

Note

As described below, host writes are not implicitly flushed when the memory object is unmapped, but the implementation must guarantee that writes that have not been flushed do not affect any other memory.

Valid Usage

  • All submitted commands that refer to memory (via images or buffers) must have completed execution

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • If memory is not VK_NULL_HANDLE, memory must be a valid VkDeviceMemory handle
  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
  • If memory is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

See Also

VkAllocationCallbacks, VkDevice, VkDeviceMemory

vkMapMemory :: ("device" ::: VkDevice) -> ("memory" ::: VkDeviceMemory) -> ("offset" ::: VkDeviceSize) -> ("size" ::: VkDeviceSize) -> ("flags" ::: VkMemoryMapFlags) -> ("ppData" ::: Ptr (Ptr ())) -> IO VkResult Source #

vkMapMemory - Map a memory object into application address space

Parameters

  • device is the logical device that owns the memory.
  • memory is the VkDeviceMemory object to be mapped.
  • offset is a zero-based byte offset from the beginning of the memory object.
  • size is the size of the memory range to map, or VK_WHOLE_SIZE to map from offset to the end of the allocation.
  • flags is reserved for future use.
  • ppData points to a pointer in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus offset must be aligned to at least VkPhysicalDeviceLimits::minMemoryMapAlignment.

Description

It is an application error to call vkMapMemory on a memory object that is already mapped.

Note

vkMapMemory will fail if the implementation is unable to allocate an appropriately sized contiguous virtual address range, e.g. due to virtual address space fragmentation or platform limits. In such cases, vkMapMemory must return VK_ERROR_MEMORY_MAP_FAILED. The application can improve the likelihood of success by reducing the size of the mapped range and/or removing unneeded mappings using VkUnmapMemory.

vkMapMemory does not check whether the device memory is currently in use before returning the host-accessible pointer. The application must guarantee that any previously submitted command that writes to this range has completed before the host reads from or writes to that range, and that any previously submitted command that reads from that range has completed before the host writes to that region (see here for details on fulfilling such a guarantee). If the device memory was allocated without the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must be made for an extended range: the application must round down the start of the range to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize, and round the end of the range up to the nearest multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize.

While a range of device memory is mapped for host access, the application is responsible for synchronizing both device and host access to that memory range.

Note

It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on Synchronization and Cache Control as they are crucial to maintaining memory access ordering.

Valid Usage

  • memory must not be currently mapped
  • offset must be less than the size of memory
  • If size is not equal to VK_WHOLE_SIZE, size must be greater than 0
  • If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset
  • memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
  • memory must not have been allocated with multiple instances.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • memory must be a valid VkDeviceMemory handle
  • flags must be 0
  • ppData must be a valid pointer to a pointer value
  • memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY
  • VK_ERROR_MEMORY_MAP_FAILED

See Also

VkDevice, VkDeviceMemory, VkDeviceSize, VkMemoryMapFlags

vkUnmapMemory :: ("device" ::: VkDevice) -> ("memory" ::: VkDeviceMemory) -> IO () Source #

vkUnmapMemory - Unmap a previously mapped memory object

Parameters

  • device is the logical device that owns the memory.
  • memory is the memory object to be unmapped.

Valid Usage

  • memory must be currently mapped

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • memory must be a valid VkDeviceMemory handle
  • memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to memory must be externally synchronized

See Also

VkDevice, VkDeviceMemory

vkFlushMappedMemoryRanges :: ("device" ::: VkDevice) -> ("memoryRangeCount" ::: Word32) -> ("pMemoryRanges" ::: Ptr VkMappedMemoryRange) -> IO VkResult Source #

vkFlushMappedMemoryRanges - Flush mapped memory ranges

Parameters

  • device is the logical device that owns the memory ranges.
  • memoryRangeCount is the length of the pMemoryRanges array.
  • pMemoryRanges is a pointer to an array of VkMappedMemoryRange structures describing the memory ranges to flush.

Description

vkFlushMappedMemoryRanges guarantees that host writes to the memory ranges described by pMemoryRanges can be made available to device access, via availability operations from the VK_ACCESS_HOST_WRITE_BIT access type.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is flushed if any byte in that set has been written by the host since it was first mapped, or the last time it was flushed. If pMemoryRanges includes sets of nonCoherentAtomSize bytes where no bytes have been written by the host, those bytes must not be flushed.

Unmapping non-coherent memory does not implicitly flush the mapped memory, and host writes that have not been flushed may not ever be visible to the device. However, implementations must ensure that writes that have not been flushed do not become visible to any other memory.

Note

The above guarantee avoids a potential memory corruption in scenarios where host writes to a mapped memory object have not been flushed before the memory is unmapped (or freed), and the virtual address range is subsequently reused for a different mapping (or memory allocation).

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • pMemoryRanges must be a valid pointer to an array of memoryRangeCount valid VkMappedMemoryRange structures
  • memoryRangeCount must be greater than 0

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDevice, VkMappedMemoryRange

vkInvalidateMappedMemoryRanges :: ("device" ::: VkDevice) -> ("memoryRangeCount" ::: Word32) -> ("pMemoryRanges" ::: Ptr VkMappedMemoryRange) -> IO VkResult Source #

vkInvalidateMappedMemoryRanges - Invalidate ranges of mapped memory objects

Parameters

  • device is the logical device that owns the memory ranges.
  • memoryRangeCount is the length of the pMemoryRanges array.
  • pMemoryRanges is a pointer to an array of VkMappedMemoryRange structures describing the memory ranges to invalidate.

Description

vkInvalidateMappedMemoryRanges guarantees that device writes to the memory ranges described by pMemoryRanges, which have been made visible to the VK_ACCESS_HOST_WRITE_BIT and VK_ACCESS_HOST_READ_BIT access types, are made visible to the host. If a range of non-coherent memory is written by the host and then invalidated without first being flushed, its contents are undefined.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is invalidated if any byte in that set has been written by the device since it was first mapped, or the last time it was invalidated.

Note

Mapping non-coherent memory does not implicitly invalidate the mapped memory, and device writes that have not been invalidated must be made visible before the host reads or overwrites them.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • pMemoryRanges must be a valid pointer to an array of memoryRangeCount valid VkMappedMemoryRange structures
  • memoryRangeCount must be greater than 0

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDevice, VkMappedMemoryRange

vkGetDeviceMemoryCommitment :: ("device" ::: VkDevice) -> ("memory" ::: VkDeviceMemory) -> ("pCommittedMemoryInBytes" ::: Ptr VkDeviceSize) -> IO () Source #

vkGetDeviceMemoryCommitment - Query the current commitment for a VkDeviceMemory

Parameters

  • device is the logical device that owns the memory.
  • memory is the memory object being queried.
  • pCommittedMemoryInBytes is a pointer to a VkDeviceSize value in which the number of bytes currently committed is returned, on success.

Description

The implementation may update the commitment at any time, and the value returned by this query may be out of date.

The implementation guarantees to allocate any committed memory from the heapIndex indicated by the memory type that the memory object was created with.

Valid Usage

  • memory must have been created with a memory type that reports VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT

Valid Usage (Implicit)

  • device must be a valid VkDevice handle
  • memory must be a valid VkDeviceMemory handle
  • pCommittedMemoryInBytes must be a valid pointer to a VkDeviceSize value
  • memory must have been created, allocated, or retrieved from device

See Also

VkDevice, VkDeviceMemory, VkDeviceSize

data VkMemoryAllocateInfo Source #

VkMemoryAllocateInfo - Structure containing parameters of a memory allocation

Description

An instance of the VkMemoryAllocateInfo structure defines a memory import operation if the pNext chain contains an instance of one of the following structures: * VkImportMemoryWin32HandleInfoKHR with non-zero handleType value * VkImportMemoryFdInfoKHR with a non-zero handleType value * VkImportMemoryHostPointerInfoEXT with a non-zero handleType value * VkImportAndroidHardwareBufferInfoANDROID with a non-NULL buffer value

Importing memory must not modify the content of the memory. Implementations must ensure that importing memory does not enable the importing Vulkan instance to access any memory or resources in other Vulkan instances other than that corresponding to the memory object imported. Implementations must also ensure accessing imported memory which has not been initialized does not allow the importing Vulkan instance to obtain data from the exporting Vulkan instance or vice-versa.

Note

How exported and imported memory is isolated is left to the implementation, but applications should be aware that such isolation may prevent implementations from placing multiple exportable memory objects in the same physical or virtual page. Hence, applications should avoid creating many small external memory objects whenever possible.

When performing a memory import operation, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. However, implementations must perform sufficient validation of external handles to ensure that the operation results in a valid memory object which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its allocation parameters. If the external handle provided does not meet these requirements, the implementation must fail the memory import operation with the error code VK_ERROR_INVALID_EXTERNAL_HANDLE.

Valid Usage

  • If the pNext chain contains an instance of VkExportMemoryAllocateInfo, and any of the handle types specified in VkExportMemoryAllocateInfo::handleTypes require a dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 in VkExternalImageFormatProperties::externalMemoryProperties::externalMemoryFeatures or VkExternalBufferProperties::externalMemoryProperties::externalMemoryFeatures, the pNext chain must contain an instance of VkMemoryDedicatedAllocateInfo or VkDedicatedAllocationMemoryAllocateInfoNV with either its image or buffer field set to a value other than VK_NULL_HANDLE.
  • If the pNext chain contains an instance of VkExportMemoryAllocateInfo, it must not contain an instance of VkExportMemoryAllocateInfoNV or VkExportMemoryWin32HandleInfoNV.
  • If the pNext chain contains an instance of VkImportMemoryWin32HandleInfoKHR, it must not contain an instance of VkImportMemoryWin32HandleInfoNV.
  • If the parameters define an import operation, the external handle specified was created by the Vulkan API, and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR, then the values of allocationSize and memoryTypeIndex must match those specified when the memory object being imported was created.
  • If the parameters define an import operation and the external handle specified was created by the Vulkan API, the device mask specified by VkMemoryAllocateFlagsInfo must match that specified when the memory object being imported was allocated.
  • If the parameters define an import operation and the external handle specified was created by the Vulkan API, the list of physical devices that comprise the logical device passed to vkAllocateMemory must match the list of physical devices that comprise the logical device on which the memory was originally allocated.
  • If the parameters define an import operation and the external handle is an NT handle or a global share handle created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by vkGetMemoryWin32HandlePropertiesKHR.
  • If the parameters define an import operation, the external handle was created by the Vulkan API, and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR or VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR, then the values of allocationSize and memoryTypeIndex must match those specified when the memory object being imported was created.
  • If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, allocationSize must match the size reported in the memory requirements of the image or buffer member of the instance of VkDedicatedAllocationMemoryAllocateInfoNV included in the pNext chain.
  • If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, allocationSize must match the size specified when creating the Direct3D 12 heap from which the external handle was extracted.
  • If the parameters define an import operation and the external handle is a POSIX file descriptor created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by vkGetMemoryFdPropertiesKHR.
  • If the parameters define an import operation and the external handle is a host pointer, the value of memoryTypeIndex must be one of those returned by vkGetMemoryHostPointerPropertiesEXT
  • If the parameters define an import operation and the external handle is a host pointer, allocationSize must be an integer multiple of VkPhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment
  • If the parameters define an import operation and the external handle type is VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BIT_ANDROID:

  • If the parameters do not define an import operation, and the pNext chain contains an instance of VkExportMemoryAllocateInfo with VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID included in its handleTypes member, and the pNext contains an instance of VkMemoryDedicatedAllocateInfo with image not equal to VK_NULL_HANDLE, then allocationSize must be 0, otherwise allocationSize must be greater than 0.
  • If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes an instance of VkMemoryDedicatedAllocateInfo with image that is not VK_NULL_HANDLE:

    • The Android hardware buffer’s usage must include at least one of AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE
    • The image’s format must be VK_FORMAT_UNDEFINED or the format returned by vkGetAndroidHardwareBufferPropertiesANDROID in VkAndroidHardwareBufferFormatPropertiesANDROID::format for the Android hardware buffer.
    • The image’s and Android hardware buffer’s width, height, and array layer dimensions must be the same
    • If the Android hardware buffer’s usage includes AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have ⌊log2(max(width, height))⌋ + 1 mip levels, otherwise it must have exactly 1 mip level.
    • Each bit set in the image’s usage must be listed in AHardwareBuffer Usage Equivalence, and if there is a corresponding AHARDWAREBUFFER_USAGE bit listed that bit must be included in the Android hardware buffer’s usage

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO

See Also

VkDeviceSize, VkStructureType, vkAllocateMemory

Constructors

VkMemoryAllocateInfo 

Fields

data VkMappedMemoryRange Source #

VkMappedMemoryRange - Structure specifying a mapped memory range

Valid Usage

  • memory must be currently mapped
  • If size is not equal to VK_WHOLE_SIZE, offset and size must specify a range contained within the currently mapped range of memory
  • If size is equal to VK_WHOLE_SIZE, offset must be within the currently mapped range of memory
  • If size is equal to VK_WHOLE_SIZE, the end of the current mapping of memory must be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize bytes from the beginning of the memory object.
  • offset must be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize
  • If size is not equal to VK_WHOLE_SIZE, size must either be a multiple of VkPhysicalDeviceLimits::nonCoherentAtomSize, or offset plus size must equal the size of memory.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE
  • pNext must be NULL
  • memory must be a valid VkDeviceMemory handle

See Also

VkDeviceMemory, VkDeviceSize, VkStructureType, vkFlushMappedMemoryRanges, vkInvalidateMappedMemoryRanges

Constructors

VkMappedMemoryRange 

Fields

  • vkSType :: VkStructureType

    sType is the type of this structure.

  • vkPNext :: Ptr ()

    pNext is NULL or a pointer to an extension-specific structure.

  • vkMemory :: VkDeviceMemory

    memory is the memory object to which this range belongs.

  • vkOffset :: VkDeviceSize

    offset is the zero-based byte offset from the beginning of the memory object.

  • vkSize :: VkDeviceSize

    size is either the size of range, or VK_WHOLE_SIZE to affect the range from offset to the end of the current mapping of the allocation.