Graphics.Vulkan.Core10.Image

Documentation

newtype VkImageLayout

VkImageLayout - Layout of image and image subresources

Description

The type(s) of device access supported by each layout are:

• VK_IMAGE_LAYOUT_UNDEFINED does not support device access. This layout must only be used as the initialLayout member of VkImageCreateInfo or VkAttachmentDescription, or as the oldLayout in an image transition. When transitioning out of this layout, the contents of the memory are not guaranteed to be preserved.
• VK_IMAGE_LAYOUT_PREINITIALIZED does not support device access. This layout must only be used as the initialLayout member of VkImageCreateInfo or VkAttachmentDescription, or as the oldLayout in an image transition. When transitioning out of this layout, the contents of the memory are preserved. This layout is intended to be used as the initial layout for an image whose contents are written by the host, and hence the data can be written to memory immediately, without first executing a layout transition. Currently, VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with VK_IMAGE_TILING_LINEAR images because there is not a standard layout defined for VK_IMAGE_TILING_OPTIMAL images.
• VK_IMAGE_LAYOUT_GENERAL supports all types of device access.
• VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must only be used as a color or resolve attachment in a VkFramebuffer. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.
• VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL must only be used as a depth/stencil attachment in a VkFramebuffer. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
• VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL must only be used as a read-only depth/stencil attachment in a VkFramebuffer and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image subresources of images created with VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image subresources of images created with VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
• VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL: must only be used as a depth/stencil attachment in a VkFramebuffer, where the depth aspect is read-only, and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment) where only the depth aspect is accessed. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image subresources of images created with VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image subresources of images created with VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
• VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL: must only be used as a depth/stencil attachment in a VkFramebuffer, where the stencil aspect is read-only, and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment) where only the stencil aspect is accessed. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image subresources of images created with VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image subresources of images created with VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
• VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL must only be used as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bit enabled.
• VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must only be used as a source image of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.
• VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must only be used as a destination image of a transfer command. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
• VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must only be used for presenting a presentable image for display. A swapchain’s image must be transitioned to this layout before calling vkQueuePresentKHR, and must be transitioned away from this layout after calling vkAcquireNextImageKHR.
• VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared presentable images, and must be used for any usage the image supports.

The layout of each image subresource is not a state of the image subresource itself, but is rather a property of how the data in memory is organized, and thus for each mechanism of accessing an image in the API the application must specify a parameter or structure member that indicates which image layout the image subresource(s) are considered to be in when the image will be accessed. For transfer commands, this is a parameter to the command (see {html_spec_relative}#clears and {html_spec_relative}#copies). For use as a framebuffer attachment, this is a member in the substructures of the VkRenderPassCreateInfo (see Render Pass). For use in a descriptor set, this is a member in the VkDescriptorImageInfo structure (see {html_spec_relative}#descriptorsets-updates). At the time that any command buffer command accessing an image executes on any queue, the layouts of the image subresources that are accessed must all match the layout specified via the API controlling those accesses.

When performing a layout transition on an image subresource, the old layout value must either equal the current layout of the image subresource (at the time the transition executes), or else be VK_IMAGE_LAYOUT_UNDEFINED (implying that the contents of the image subresource need not be preserved). The new layout used in a transition must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.

The image layout of each image subresource of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the image subresource as a depth/stencil attachment, thus applications must provide the same sample locations that were last used to render to the given image subresource whenever a layout transition of the image subresource happens, otherwise the contents of the depth aspect of the image subresource become undefined.

In addition, depth reads from a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range produce undefined results.

Similarly, depth writes to a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range make the contents of the depth aspect of those image subresources undefined.

See Also

VkAttachmentDescription, VkAttachmentReference, VkDescriptorImageInfo, VkImageCreateInfo, VkImageMemoryBarrier, vkCmdBlitImage, vkCmdClearColorImage, vkCmdClearDepthStencilImage, vkCmdCopyBufferToImage, vkCmdCopyImage, vkCmdCopyImageToBuffer, vkCmdResolveImage

Constructors

VkImageLayout Int32

Instances

Eq VkImageLayout

Methods

(==) :: VkImageLayout -> VkImageLayout -> Bool

(/=) :: VkImageLayout -> VkImageLayout -> Bool

Ord VkImageLayout

Methods

compare :: VkImageLayout -> VkImageLayout -> Ordering

(<) :: VkImageLayout -> VkImageLayout -> Bool

(<=) :: VkImageLayout -> VkImageLayout -> Bool

(>) :: VkImageLayout -> VkImageLayout -> Bool

(>=) :: VkImageLayout -> VkImageLayout -> Bool

max :: VkImageLayout -> VkImageLayout -> VkImageLayout

min :: VkImageLayout -> VkImageLayout -> VkImageLayout

Read VkImageLayout

Methods

readsPrec :: Int -> ReadS VkImageLayout

readList :: ReadS [VkImageLayout]

readPrec :: ReadPrec VkImageLayout

readListPrec :: ReadPrec [VkImageLayout]

Show VkImageLayout

Methods

showsPrec :: Int -> VkImageLayout -> ShowS

show :: VkImageLayout -> String

showList :: [VkImageLayout] -> ShowS

Storable VkImageLayout

Methods

sizeOf :: VkImageLayout -> Int

alignment :: VkImageLayout -> Int

peekElemOff :: Ptr VkImageLayout -> Int -> IO VkImageLayout

pokeElemOff :: Ptr VkImageLayout -> Int -> VkImageLayout -> IO ()

peekByteOff :: Ptr b -> Int -> IO VkImageLayout

pokeByteOff :: Ptr b -> Int -> VkImageLayout -> IO ()

peek :: Ptr VkImageLayout -> IO VkImageLayout

poke :: Ptr VkImageLayout -> VkImageLayout -> IO ()

pattern VK_IMAGE_LAYOUT_UNDEFINED :: VkImageLayout

pattern VK_IMAGE_LAYOUT_GENERAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL :: VkImageLayout

pattern VK_IMAGE_LAYOUT_PREINITIALIZED :: VkImageLayout

vkCreateImage :: ("device" ::: VkDevice) -> ("pCreateInfo" ::: Ptr VkImageCreateInfo) -> ("pAllocator" ::: Ptr VkAllocationCallbacks) -> ("pImage" ::: Ptr VkImage) -> IO VkResult

vkCreateImage - Create a new image object

Parameters

• device is the logical device that creates the image.

• pCreateInfo is a pointer to an instance of the VkImageCreateInfo structure containing parameters to be used to create the image.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pImage points to a VkImage handle in which the resulting image object is returned.

Description

Valid Usage

• If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pImage must be a valid pointer to a VkImage handle

Return Codes

Success

- VK_SUCCESS

Failure

- VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkAllocationCallbacks, VkDevice, VkImage, VkImageCreateInfo

vkDestroyImage :: ("device" ::: VkDevice) -> ("image" ::: VkImage) -> ("pAllocator" ::: Ptr VkAllocationCallbacks) -> IO ()

vkDestroyImage - Destroy an image object

Parameters

• device is the logical device that destroys the image.

• image is the image to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Description

Valid Usage

• All submitted commands that refer to image, either directly or via a VkImageView, must have completed execution

• If VkAllocationCallbacks were provided when image was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when image was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

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

Host Synchronization

• Host access to image must be externally synchronized

See Also

VkAllocationCallbacks, VkDevice, VkImage

vkGetImageSubresourceLayout :: ("device" ::: VkDevice) -> ("image" ::: VkImage) -> ("pSubresource" ::: Ptr VkImageSubresource) -> ("pLayout" ::: Ptr VkSubresourceLayout) -> IO ()

vkGetImageSubresourceLayout - Retrieve information about an image subresource

Parameters

• device is the logical device that owns the image.

• image is the image whose layout is being queried.
• pSubresource is a pointer to a VkImageSubresource structure selecting a specific image for the image subresource.
• pLayout points to a VkSubresourceLayout structure in which the layout is returned.

Description

If the VkFormat of image is a multi-planar format, vkGetImageSubresourceLayout describes one plane of the image.

vkGetImageSubresourceLayout is invariant for the lifetime of a single image. However, the subresource layout of images in Android hardware buffer external memory isn’t known until the image has been bound to memory, so calling vkGetImageSubresourceLayout for such an image before it has been bound will result in undefined behavior.

Valid Usage

• image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR

• The aspectMask member of pSubresource must only have a single bit set
• The mipLevel member of pSubresource must be less than the mipLevels specified in VkImageCreateInfo when image was created
• The arrayLayer member of pSubresource must be less than the arrayLayers specified in VkImageCreateInfo when image was created
• If the format of image is a multi-planar format with two planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT
• If the format of image is a multi-planar format with three planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT
• If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• image must be a valid VkImage handle
• pSubresource must be a valid pointer to a valid VkImageSubresource structure
• pLayout must be a valid pointer to a VkSubresourceLayout structure
• image must have been created, allocated, or retrieved from device

See Also

VkDevice, VkImage, VkImageSubresource, VkSubresourceLayout

data VkImageCreateInfo

VkImageCreateInfo - Structure specifying the parameters of a newly created image object

Description

Images created with tiling equal to VK_IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images created with tiling equal to VK_IMAGE_TILING_OPTIMAL. Creation of images with tiling VK_IMAGE_TILING_LINEAR may not be supported unless other parameters meet all of the constraints:

• imageType is VK_IMAGE_TYPE_2D
• format is not a depth/stencil format
• mipLevels is 1
• arrayLayers is 1
• samples is VK_SAMPLE_COUNT_1_BIT
• usage only includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or VK_IMAGE_USAGE_TRANSFER_DST_BIT

Implementations may support additional limits and capabilities beyond those listed above.

To query an implementation’s specific capabilities for a given combination of format, imageType, tiling, usage, VkExternalMemoryImageCreateInfo::handleTypes and flags, call vkGetPhysicalDeviceImageFormatProperties2. The return value specifies whether that combination of image settings is supported. On success, the VkImageFormatProperties output parameter specifies the set of valid samples bits and the limits for extent, mipLevels, arrayLayers, and maxResourceSize. Even if vkGetPhysicalDeviceImageFormatProperties2. returns success and the parameters to vkCreateImage are all within the returned limits, vkCreateImage must fail and return VK_ERROR_OUT_OF_DEVICE_MEMORY if the resulting size of the image would be larger than maxResourceSize.

To determine the set of valid usage bits for a given format, call vkGetPhysicalDeviceFormatProperties.

Note

For images created without VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for the format the image is created with.

For images created with VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for at least one of the formats a VkImageView created from the image can have (see Image Views for more detail).

Valid Usage

• If the pNext chain doesn’t contain an instance of VkExternalFormatANDROID, or if format is not VK_FORMAT_UNDEFINED, the combination of format, imageType, tiling, usage, and flags must be supported, as indicated by a VK_SUCCESS return value from vkGetPhysicalDeviceImageFormatProperties invoked with the same values passed to the corresponding parameters.

• If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
• If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
• If sharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties or vkGetPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device
• format must not be VK_FORMAT_UNDEFINED
• extent::width must be greater than 0.
• extent::height must be greater than 0.
• extent::depth must be greater than 0.
• mipLevels must be greater than 0
• arrayLayers must be greater than 0
• If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_2D
• If flags contains VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_3D
• If imageType is VK_IMAGE_TYPE_1D, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension1D, or VkImageFormatProperties::maxExtent.width (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure) - whichever is higher
• If imageType is VK_IMAGE_TYPE_2D and flags does not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension2D, or VkImageFormatProperties::maxExtent.width/height (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure) - whichever is higher
• If imageType is VK_IMAGE_TYPE_2D and flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be less than or equal to VkPhysicalDeviceLimits::maxImageDimensionCube, or VkImageFormatProperties::maxExtent.width/height (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure) - whichever is higher
• If imageType is VK_IMAGE_TYPE_2D and flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be equal and arrayLayers must be greater than or equal to 6
• If imageType is VK_IMAGE_TYPE_3D, extent.width, extent.height and extent.depth must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension3D, or VkImageFormatProperties::maxExtent.width/height/depth (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure) - whichever is higher
• If imageType is VK_IMAGE_TYPE_1D, both extent.height and extent.depth must be 1
• If imageType is VK_IMAGE_TYPE_2D, extent.depth must be 1
• mipLevels must be less than or equal to ⌊log2(max(extent.width, extent.height, extent.depth))⌋ + 1.
• mipLevels must be less than or equal to VkImageFormatProperties::maxMipLevels (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure)
• arrayLayers must be less than or equal to VkImageFormatProperties::maxArrayLayers (as returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure)
• If imageType is VK_IMAGE_TYPE_3D, arrayLayers must be 1.
• If samples is not VK_SAMPLE_COUNT_1_BIT, imageType must be VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, tiling must be VK_IMAGE_TILING_OPTIMAL, and mipLevels must be equal to 1
• If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, then bits other than VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must not be set
• If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth
• If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight
• If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, usage must also contain at least one of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT.
• samples must be a bit value that is set in VkImageFormatProperties::sampleCounts returned by vkGetPhysicalDeviceImageFormatProperties with format, imageType, tiling, usage, and flags equal to those in this structure
• If the multisampled storage images feature is not enabled, and usage contains VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT
• If the sparse bindings feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT
• If the sparse aliased residency feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
• If imageType is VK_IMAGE_TYPE_1D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for 2D images feature is not enabled, and imageType is VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for 3D images feature is not enabled, and imageType is VK_IMAGE_TYPE_3D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for images with 2 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_2_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for images with 4 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_4_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for images with 8 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_8_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If the sparse residency for images with 16 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_16_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
• If tiling is VK_IMAGE_TILING_LINEAR, format must be a format that has at least one supported feature bit present in the value of VkFormatProperties::linearTilingFeatures returned by vkGetPhysicalDeviceFormatProperties with the same value of format
• If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_SAMPLED_BIT
• If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_STORAGE_BIT
• If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
• If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If tiling is VK_IMAGE_TILING_OPTIMAL, format must be a format that has at least one supported feature bit present in the value of VkFormatProperties::optimalTilingFeatures returned by vkGetPhysicalDeviceFormatProperties with the same value of format
• If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_SAMPLED_BIT
• If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_STORAGE_BIT
• If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
• If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If flags contains VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT
• If any of the bits VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must not also be set
• If the pNext chain contains an instance of VkExternalMemoryImageCreateInfoNV, it must not contain an instance of VkExternalMemoryImageCreateInfo.
• If the pNext chain contains an instance of VkExternalMemoryImageCreateInfo, its handleTypes member must only contain bits that are also in VkExternalImageFormatProperties::externalMemoryProperties::compatibleHandleTypes, as returned by vkGetPhysicalDeviceImageFormatProperties2 with format, imageType, tiling, usage, and flags equal to those in this structure, and with an instance of VkPhysicalDeviceExternalImageFormatInfo in the pNext chain, with a handleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes
• If the pNext chain contains an instance of VkExternalMemoryImageCreateInfoNV, its handleTypes member must only contain bits that are also in VkExternalImageFormatPropertiesNV::externalMemoryProperties::compatibleHandleTypes, as returned by vkGetPhysicalDeviceExternalImageFormatPropertiesNV with format, imageType, tiling, usage, and flags equal to those in this structure, and with externalHandleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfoNV::handleTypes
• If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
• If flags contains VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then mipLevels must be one, arrayLayers must be one, imageType must be VK_IMAGE_TYPE_2D, and tiling must be VK_IMAGE_TILING_OPTIMAL
• If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then format must be a block-compressed image format, an ETC compressed image format, or an ASTC compressed image format.
• If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then flags must also contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT.
• initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.
• If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED

• If the image format is one of those listed in {html_spec_relative}#features-formats-requiring-sampler-ycbcr-conversion:

  • mipLevels must be 1
  • samples must be VK_SAMPLE_COUNT_1_BIT
  • imageType must be VK_IMAGE_TYPE_2D
  • arrayLayers must be 1
• If tiling is VK_IMAGE_TILING_OPTIMAL, format is a multi-planar format, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DISJOINT_BIT, flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT
• If tiling is VK_IMAGE_TILING_LINEAR, format is a multi-planar format, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DISJOINT_BIT, flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT
• If format is not a multi-planar format, and flags does not include VK_IMAGE_CREATE_ALIAS_BIT, flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT
• If flags contains VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT format must be a depth or depth/stencil format

• If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID:

  • imageType must be VK_IMAGE_TYPE_2D
  • mipLevels must either be 1 or equal to ⌊log2(max(extent.width, extent.height, extent.depth))⌋ + 1.
  • If format is not VK_FORMAT_UNDEFINED, then format, imageType, tiling, usage, flags, mipLevels, and samples must be supported with VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle types according to vkGetPhysicalDeviceImageFormatProperties2
  • If format is VK_FORMAT_UNDEFINED, then the pNext chain must include a VkExternalFormatANDROID structure whose externalFormat member is not 0

• If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0:

  • format must be VK_FORMAT_UNDEFINED
  • flags must not include VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
  • usage must not include any usages except VK_IMAGE_USAGE_SAMPLED_BIT
  • tiling must be VK_IMAGE_TILING_OPTIMAL

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkDedicatedAllocationImageCreateInfoNV, VkExternalFormatANDROID, VkExternalMemoryImageCreateInfo, VkExternalMemoryImageCreateInfoNV, VkImageFormatListCreateInfoKHR, or VkImageSwapchainCreateInfoKHR
• Each sType member in the pNext chain must be unique
• flags must be a valid combination of VkImageCreateFlagBits values
• imageType must be a valid VkImageType value
• format must be a valid VkFormat value
• samples must be a valid VkSampleCountFlagBits value
• tiling must be a valid VkImageTiling value
• usage must be a valid combination of VkImageUsageFlagBits values
• usage must not be 0
• sharingMode must be a valid VkSharingMode value
• initialLayout must be a valid VkImageLayout value

See Also

VkExtent3D, VkFormat, VkImageCreateFlags, VkImageLayout, VkImageTiling, VkImageType, VkImageUsageFlags, VkSampleCountFlagBits, VkSharingMode, VkStructureType, vkCreateImage

Constructors

VkImageCreateInfo

Fields

• vkSType :: VkStructureType

  sType is the type of this structure.

• vkPNext :: Ptr ()

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

• vkFlags :: VkImageCreateFlags

  flags is a bitmask of VkImageCreateFlagBits describing additional parameters of the image.

• vkImageType :: VkImageType

  imageType is a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type.

• vkFormat :: VkFormat

  format is a VkFormat describing the format and type of the data elements that will be contained in the image.

• vkExtent :: VkExtent3D

  extent is a VkExtent3D describing the number of data elements in each dimension of the base level.

• vkMipLevels :: Word32

  mipLevels describes the number of levels of detail available for minified sampling of the image.

• vkArrayLayers :: Word32

  arrayLayers is the number of layers in the image.

• vkSamples :: VkSampleCountFlagBits

  samples is the number of sub-data element samples in the image as defined in VkSampleCountFlagBits. See Multisampling.

• vkTiling :: VkImageTiling

  tiling is a VkImageTiling value specifying the tiling arrangement of the data elements in memory.

• vkUsage :: VkImageUsageFlags

  usage is a bitmask of VkImageUsageFlagBits describing the intended usage of the image.

• vkSharingMode :: VkSharingMode

  sharingMode is a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families.

• vkQueueFamilyIndexCount :: Word32

  queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

• vkPQueueFamilyIndices :: Ptr Word32

  pQueueFamilyIndices is a list of queue families that will access this image (ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT).

• vkInitialLayout :: VkImageLayout

  initialLayout is a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.

Instances

Eq VkImageCreateInfo

Methods

(==) :: VkImageCreateInfo -> VkImageCreateInfo -> Bool

(/=) :: VkImageCreateInfo -> VkImageCreateInfo -> Bool

Show VkImageCreateInfo

Methods

showsPrec :: Int -> VkImageCreateInfo -> ShowS

show :: VkImageCreateInfo -> String

showList :: [VkImageCreateInfo] -> ShowS

Storable VkImageCreateInfo

Methods

sizeOf :: VkImageCreateInfo -> Int

alignment :: VkImageCreateInfo -> Int

peekElemOff :: Ptr VkImageCreateInfo -> Int -> IO VkImageCreateInfo

pokeElemOff :: Ptr VkImageCreateInfo -> Int -> VkImageCreateInfo -> IO ()

peekByteOff :: Ptr b -> Int -> IO VkImageCreateInfo

pokeByteOff :: Ptr b -> Int -> VkImageCreateInfo -> IO ()

peek :: Ptr VkImageCreateInfo -> IO VkImageCreateInfo

poke :: Ptr VkImageCreateInfo -> VkImageCreateInfo -> IO ()

data VkSubresourceLayout

VkSubresourceLayout - Structure specifying subresource layout

Description

For images created with linear tiling, rowPitch, arrayPitch and depthPitch describe the layout of the image subresource in linear memory. For uncompressed formats, rowPitch is the number of bytes between texels with the same x coordinate in adjacent rows (y coordinates differ by one). arrayPitch is the number of bytes between texels with the same x and y coordinate in adjacent array layers of the image (array layer values differ by one). depthPitch is the number of bytes between texels with the same x and y coordinate in adjacent slices of a 3D image (z coordinates differ by one). Expressed as an addressing formula, the starting byte of a texel in the image subresource has address:

// (x,y,z,layer) are in texel coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset

For compressed formats, the rowPitch is the number of bytes between compressed texel blocks in adjacent rows. arrayPitch is the number of bytes between compressed texel blocks in adjacent array layers. depthPitch is the number of bytes between compressed texel blocks in adjacent slices of a 3D image.

// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;

arrayPitch is undefined for images that were not created as arrays. depthPitch is defined only for 3D images.

For single-plane color formats, the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_COLOR_BIT. For depth/stencil formats, aspectMask must be either VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and stencil aspects separately, querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that aspect. On implementations that store depth and stencil aspects interleaved, the same offset and size are returned and represent the interleaved memory allocation.

For multi-planar formats, the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or (for 3-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT. Querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that plane.

See Also

VkDeviceSize, vkGetImageSubresourceLayout

Constructors

VkSubresourceLayout

Fields

• vkOffset :: VkDeviceSize

  offset is the byte offset from the start of the image where the image subresource begins.

• vkSize :: VkDeviceSize

  size is the size in bytes of the image subresource. size includes any extra memory that is required based on rowPitch.

• vkRowPitch :: VkDeviceSize

  rowPitch describes the number of bytes between each row of texels in an image.

• vkArrayPitch :: VkDeviceSize

  arrayPitch describes the number of bytes between each array layer of an image.

• vkDepthPitch :: VkDeviceSize

  depthPitch describes the number of bytes between each slice of 3D image.

Instances

Eq VkSubresourceLayout

Methods

(==) :: VkSubresourceLayout -> VkSubresourceLayout -> Bool

(/=) :: VkSubresourceLayout -> VkSubresourceLayout -> Bool

Show VkSubresourceLayout

Methods

showsPrec :: Int -> VkSubresourceLayout -> ShowS

show :: VkSubresourceLayout -> String

showList :: [VkSubresourceLayout] -> ShowS

Storable VkSubresourceLayout

Methods

sizeOf :: VkSubresourceLayout -> Int

alignment :: VkSubresourceLayout -> Int

peekElemOff :: Ptr VkSubresourceLayout -> Int -> IO VkSubresourceLayout

pokeElemOff :: Ptr VkSubresourceLayout -> Int -> VkSubresourceLayout -> IO ()

peekByteOff :: Ptr b -> Int -> IO VkSubresourceLayout

pokeByteOff :: Ptr b -> Int -> VkSubresourceLayout -> IO ()

peek :: Ptr VkSubresourceLayout -> IO VkSubresourceLayout

poke :: Ptr VkSubresourceLayout -> VkSubresourceLayout -> IO ()