Top Description Fields Constructors Methods
org.lwjgl.vulkan

public Class EXTHostImageCopy

extends Object
Class Inheritance
Imports
org.lwjgl.system.*
This extension allows applications to copy data between host memory and images on the host processor, without staging the data through a GPU-accessible buffer. This removes the need to allocate and manage the buffer and its associated memory. On some architectures it may also eliminate an extra copy operation. This extension additionally allows applications to copy data between images on the host.

To support initializing a new image in preparation for a host copy, it is now possible to transition a new image to IMAGE_LAYOUT_GENERAL or other host-copyable layouts via TransitionImageLayoutEXT. Additionally, it is possible to perform copies that preserve the swizzling layout of the image by using the HOST_IMAGE_COPY_MEMCPY_EXT flag. In that case, the memory size needed for copies to or from a buffer can be retrieved by chaining VkSubresourceHostMemcpySizeEXT to pLayout in GetImageSubresourceLayout2EXT.

VK_EXT_host_image_copy
Name String
VK_EXT_host_image_copy
Extension Type
Device extension
Registered Extension Number
271
Revision
1
Extension and Version Dependencies
VK_KHR_get_physical_device_properties2 and VK_KHR_copy_commands2 and VK_KHR_format_feature_flags2
Contact
Extension Proposal
VK_EXT_host_image_copy
Other Extension Metadata
Last Modified Date
2023-04-26
Contributors
  • Shahbaz Youssefi, Google
  • Faith Ekstrand, Collabora
  • Hans-Kristian Arntzen, Valve
  • Piers Daniell, NVIDIA
  • Jan-Harald Fredriksen, Arm
  • James Fitzpatrick, Imagination
  • Daniel Story, Nintendo

Field Summary

Modifier and TypeField and Description
public static final String
VK_EXT_HOST_IMAGE_COPY_EXTENSION_NAME

The extension name.

public static final int
VK_EXT_HOST_IMAGE_COPY_SPEC_VERSION

The extension specification version.

public static final long
VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT

Extends VkFormatFeatureFlagBits2.

public static final int
VK_HOST_IMAGE_COPY_MEMCPY_EXT

VkHostImageCopyFlagBitsEXT - Bitmask specifying additional copy parameters Description

  • HOST_IMAGE_COPY_MEMCPY_EXT specifies that no memory layout swizzling is to be applied during data copy. For copies between memory and images, this flag indicates that image data in host memory is swizzled in exactly the same way as the image data on the device. Using this flag indicates that the implementations may use a simple memory copy to transfer the data between the host memory and the device memory. The format of the swizzled data in host memory is platform dependent and is not defined in this specification.
public static final int
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

Extends VkImageUsageFlagBits.

public static final int
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT

Extends VkStructureType.

Constructor Summary

AccessConstructor and Description
protected
EXTHostImageCopy()

Method Summary

Modifier and TypeMethod and Description
public static int
nvkCopyImageToImageEXT(VkDevice device, long pCopyImageToImageInfo)

Unsafe version of: CopyImageToImageEXT

public static int
nvkCopyImageToMemoryEXT(VkDevice device, long pCopyImageToMemoryInfo)

Unsafe version of: CopyImageToMemoryEXT

public static int
nvkCopyMemoryToImageEXT(VkDevice device, long pCopyMemoryToImageInfo)

Unsafe version of: CopyMemoryToImageEXT

public static void
nvkGetImageSubresourceLayout2EXT(VkDevice device, long image, long pSubresource, long pLayout)

Unsafe version of: GetImageSubresourceLayout2EXT

public static int
nvkTransitionImageLayoutEXT(VkDevice device, int
the number of image layout transitions to perform.
transitionCount, long pTransitions)

Unsafe version of: TransitionImageLayoutEXT

public static int
vkCopyImageToImageEXT(VkDevice
the device which owns pCopyImageToMemoryInfo→srcImage.
device, VkCopyImageToImageInfoEXT
a pointer to a VkCopyImageToImageInfoEXT structure describing the copy parameters.
pCopyImageToImageInfo)

Copy image data using the host.

public static int
vkCopyImageToMemoryEXT(VkDevice
the device which owns pCopyImageToMemoryInfo→srcImage.
device, VkCopyImageToMemoryInfoEXT
a pointer to a VkCopyImageToMemoryInfoEXT structure describing the copy parameters.
pCopyImageToMemoryInfo)

Copy image data into host memory.

public static int
vkCopyMemoryToImageEXT(VkDevice
the device which owns pCopyMemoryToImageInfo→dstImage.
device, VkCopyMemoryToImageInfoEXT
a pointer to a VkCopyMemoryToImageInfoEXT structure describing the copy parameters.
pCopyMemoryToImageInfo)

Copy data from host memory into an image.

public static void
vkGetImageSubresourceLayout2EXT(VkDevice
the logical device that owns the image.
device, long
the image whose layout is being queried.
image, VkImageSubresource2KHR
a pointer to a VkImageSubresource2KHR structure selecting a specific image for the image subresource.
pSubresource, VkSubresourceLayout2KHR
a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.
pLayout)

See GetImageSubresourceLayout2KHR.

public static int
vkTransitionImageLayoutEXT(VkDevice
the device which owns pTransitions[i].image.
device, VkHostImageLayoutTransitionInfoEXT.Buffer
a pointer to an array of VkHostImageLayoutTransitionInfoEXT structures specifying the image and subresource ranges within them to transition.
pTransitions)

Perform an image layout transition on the host.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

VK_EXT_HOST_IMAGE_COPY_EXTENSION_NAMEback to summary
public static final String VK_EXT_HOST_IMAGE_COPY_EXTENSION_NAME

The extension name.

VK_EXT_HOST_IMAGE_COPY_SPEC_VERSIONback to summary
public static final int VK_EXT_HOST_IMAGE_COPY_SPEC_VERSION

The extension specification version.

VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXTback to summary
public static final long VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT

Extends VkFormatFeatureFlagBits2.

VK_HOST_IMAGE_COPY_MEMCPY_EXTback to summary
public static final int VK_HOST_IMAGE_COPY_MEMCPY_EXT

VkHostImageCopyFlagBitsEXT - Bitmask specifying additional copy parameters

Description
  • HOST_IMAGE_COPY_MEMCPY_EXT specifies that no memory layout swizzling is to be applied during data copy. For copies between memory and images, this flag indicates that image data in host memory is swizzled in exactly the same way as the image data on the device. Using this flag indicates that the implementations may use a simple memory copy to transfer the data between the host memory and the device memory. The format of the swizzled data in host memory is platform dependent and is not defined in this specification.
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXTback to summary
public static final int VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

Extends VkImageUsageFlagBits.

VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXTback to summary
public static final int VK_STRUCTURE_TYPE_HOST_IMAGE_COPY_DEVICE_PERFORMANCE_QUERY_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXTback to summary
public static final int VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXTback to summary
public static final int VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXTback to summary
public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_FEATURES_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXTback to summary
public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_HOST_IMAGE_COPY_PROPERTIES_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXTback to summary
public static final int VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT

Extends VkStructureType.

Enum values:

Constructor Detail

EXTHostImageCopyback to summary
protected EXTHostImageCopy()

Method Detail

nvkCopyImageToImageEXTback to summary
public static int nvkCopyImageToImageEXT(VkDevice device, long pCopyImageToImageInfo)

Unsafe version of: CopyImageToImageEXT

nvkCopyImageToMemoryEXTback to summary
public static int nvkCopyImageToMemoryEXT(VkDevice device, long pCopyImageToMemoryInfo)

Unsafe version of: CopyImageToMemoryEXT

nvkCopyMemoryToImageEXTback to summary
public static int nvkCopyMemoryToImageEXT(VkDevice device, long pCopyMemoryToImageInfo)

Unsafe version of: CopyMemoryToImageEXT

nvkGetImageSubresourceLayout2EXTback to summary
public static void nvkGetImageSubresourceLayout2EXT(VkDevice device, long image, long pSubresource, long pLayout)

Unsafe version of: GetImageSubresourceLayout2EXT

nvkTransitionImageLayoutEXTback to summary
public static int nvkTransitionImageLayoutEXT(VkDevice device, int transitionCount, long pTransitions)

Unsafe version of: TransitionImageLayoutEXT

Parameters
transitionCount:int

the number of image layout transitions to perform.

vkCopyImageToImageEXTback to summary
public static int vkCopyImageToImageEXT(VkDevice device, VkCopyImageToImageInfoEXT pCopyImageToImageInfo)

Copy image data using the host.

C Specification

To copy data from an image object to another image object using the host, call:


VkResult vkCopyImageToImageEXT(
    VkDevice                                    device,
    const VkCopyImageToImageInfoEXT*            pCopyImageToImageInfo);
Description

This command is functionally similar to CmdCopyImage2, except it is executed on the host.

Valid Usage
Valid Usage (Implicit)
  • device must be a valid VkDevice handle
  • pCopyImageToImageInfo must be a valid pointer to a valid VkCopyImageToImageInfoEXT structure
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkCopyImageToImageInfoEXT

Parameters
device:VkDevice

the device which owns pCopyImageToMemoryInfo→srcImage.

pCopyImageToImageInfo:VkCopyImageToImageInfoEXT

a pointer to a VkCopyImageToImageInfoEXT structure describing the copy parameters.

Annotations
@NativeType:VkResult
vkCopyImageToMemoryEXTback to summary
public static int vkCopyImageToMemoryEXT(VkDevice device, VkCopyImageToMemoryInfoEXT pCopyImageToMemoryInfo)

Copy image data into host memory.

C Specification

To copy data from an image object to host memory, call:


VkResult vkCopyImageToMemoryEXT(
    VkDevice                                    device,
    const VkCopyImageToMemoryInfoEXT*           pCopyImageToMemoryInfo);
Description

This command is functionally similar to CmdCopyImageToBuffer2, except it is executed on the host and writes to host memory instead of a buffer.

Valid Usage
Valid Usage (Implicit)
  • device must be a valid VkDevice handle
  • pCopyImageToMemoryInfo must be a valid pointer to a valid VkCopyImageToMemoryInfoEXT structure
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkCopyImageToMemoryInfoEXT

Parameters
device:VkDevice

the device which owns pCopyImageToMemoryInfo→srcImage.

pCopyImageToMemoryInfo:VkCopyImageToMemoryInfoEXT

a pointer to a VkCopyImageToMemoryInfoEXT structure describing the copy parameters.

Annotations
@NativeType:VkResult
vkCopyMemoryToImageEXTback to summary
public static int vkCopyMemoryToImageEXT(VkDevice device, VkCopyMemoryToImageInfoEXT pCopyMemoryToImageInfo)

Copy data from host memory into an image.

C Specification

To copy data from host memory to an image object, call:


VkResult vkCopyMemoryToImageEXT(
    VkDevice                                    device,
    const VkCopyMemoryToImageInfoEXT*           pCopyMemoryToImageInfo);
Description

This command is functionally similar to CmdCopyBufferToImage2, except it is executed on the host and reads from host memory instead of a buffer.

Valid Usage
Valid Usage (Implicit)
  • device must be a valid VkDevice handle
  • pCopyMemoryToImageInfo must be a valid pointer to a valid VkCopyMemoryToImageInfoEXT structure
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkCopyMemoryToImageInfoEXT

Parameters
device:VkDevice

the device which owns pCopyMemoryToImageInfo→dstImage.

pCopyMemoryToImageInfo:VkCopyMemoryToImageInfoEXT

a pointer to a VkCopyMemoryToImageInfoEXT structure describing the copy parameters.

Annotations
@NativeType:VkResult
vkGetImageSubresourceLayout2EXTback to summary
public static void vkGetImageSubresourceLayout2EXT(VkDevice device, long image, VkImageSubresource2KHR pSubresource, VkSubresourceLayout2KHR pLayout)

See GetImageSubresourceLayout2KHR.

Parameters
device:VkDevice

the logical device that owns the image.

image:long

the image whose layout is being queried.

pSubresource:VkImageSubresource2KHR

a pointer to a VkImageSubresource2KHR structure selecting a specific image for the image subresource.

pLayout:VkSubresourceLayout2KHR

a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.

vkTransitionImageLayoutEXTback to summary
public static int vkTransitionImageLayoutEXT(VkDevice device, VkHostImageLayoutTransitionInfoEXT.Buffer pTransitions)

Perform an image layout transition on the host.

C Specification

To perform an image layout transition on the host, call:


VkResult vkTransitionImageLayoutEXT(
    VkDevice                                    device,
    uint32_t                                    transitionCount,
    const VkHostImageLayoutTransitionInfoEXT*   pTransitions);
Valid Usage (Implicit)
  • device must be a valid VkDevice handle
  • pTransitions must be a valid pointer to an array of transitionCount valid VkHostImageLayoutTransitionInfoEXT structures
  • transitionCount must be greater than 0
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkHostImageLayoutTransitionInfoEXT

Parameters
device:VkDevice

the device which owns pTransitions[i].image.

pTransitions:VkHostImageLayoutTransitionInfoEXT.Buffer

a pointer to an array of VkHostImageLayoutTransitionInfoEXT structures specifying the image and subresource ranges within them to transition.

Annotations
@NativeType:VkResult