Safe Haskell | None |
---|---|
Language | Haskell2010 |
Synopsis
- createImage :: forall a io. (Extendss ImageCreateInfo a, PokeChain a, MonadIO io) => Device -> ImageCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> io Image
- withImage :: forall a io r. (Extendss ImageCreateInfo a, PokeChain a, MonadIO io) => Device -> ImageCreateInfo a -> Maybe AllocationCallbacks -> (io Image -> (Image -> io ()) -> r) -> r
- destroyImage :: forall io. MonadIO io => Device -> Image -> ("allocator" ::: Maybe AllocationCallbacks) -> io ()
- getImageSubresourceLayout :: forall io. MonadIO io => Device -> Image -> ImageSubresource -> io SubresourceLayout
- data ImageSubresource = ImageSubresource {}
- data ImageCreateInfo (es :: [Type]) = ImageCreateInfo {
- next :: Chain es
- flags :: ImageCreateFlags
- imageType :: ImageType
- format :: Format
- extent :: Extent3D
- mipLevels :: Word32
- arrayLayers :: Word32
- samples :: SampleCountFlagBits
- tiling :: ImageTiling
- usage :: ImageUsageFlags
- sharingMode :: SharingMode
- queueFamilyIndices :: Vector Word32
- initialLayout :: ImageLayout
- data SubresourceLayout = SubresourceLayout {}
Documentation
createImage :: forall a io. (Extendss ImageCreateInfo a, PokeChain a, MonadIO io) => Device -> ImageCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> io Image Source #
vkCreateImage - Create a new image object
Parameters
device
is the logical device that creates the image.
pCreateInfo
is a pointer to aImageCreateInfo
structure containing parameters to be used to create the image.pAllocator
controls host memory allocation as described in the Memory Allocation chapter.pImage
is a pointer to aImage
handle in which the resulting image object is returned.
Valid Usage
- If the
flags
member ofpCreateInfo
includesIMAGE_CREATE_SPARSE_BINDING_BIT
, creating thisImage
must not cause the total required sparse memory for all currently valid sparse resources on the device to exceedPhysicalDeviceLimits
::sparseAddressSpaceSize
Valid Usage (Implicit)
device
must be a validDevice
handle
pCreateInfo
must be a valid pointer to a validImageCreateInfo
structure- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validAllocationCallbacks
structure pImage
must be a valid pointer to aImage
handle
Return Codes
See Also
withImage :: forall a io r. (Extendss ImageCreateInfo a, PokeChain a, MonadIO io) => Device -> ImageCreateInfo a -> Maybe AllocationCallbacks -> (io Image -> (Image -> io ()) -> r) -> r Source #
A convenience wrapper to make a compatible pair of calls to
createImage
and destroyImage
To ensure that destroyImage
is always called: pass
bracket
(or the allocate function from your
favourite resource management library) as the first argument.
To just extract the pair pass (,)
as the first argument.
destroyImage :: forall io. MonadIO io => Device -> Image -> ("allocator" ::: Maybe AllocationCallbacks) -> io () Source #
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.
Valid Usage
- All submitted commands that refer to
image
, either directly or via aImageView
, must have completed execution
- If
AllocationCallbacks
were provided whenimage
was created, a compatible set of callbacks must be provided here - If no
AllocationCallbacks
were provided whenimage
was created,pAllocator
must beNULL
Valid Usage (Implicit)
device
must be a validDevice
handle
- If
image
is notNULL_HANDLE
,image
must be a validImage
handle - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validAllocationCallbacks
structure - If
image
is a valid handle, it must have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
image
must be externally synchronized
See Also
getImageSubresourceLayout :: forall io. MonadIO io => Device -> Image -> ImageSubresource -> io SubresourceLayout Source #
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 aImageSubresource
structure selecting a specific image for the image subresource.pLayout
is a pointer to aSubresourceLayout
structure in which the layout is returned.
Description
If the image is linear, then the returned layout is valid for host access.
If the image’s tiling is
IMAGE_TILING_LINEAR
and its format is
a
multi-planar format,
then getImageSubresourceLayout
describes one format plane of the
image. If the image’s tiling is
IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
,
then getImageSubresourceLayout
describes one memory plane of the
image. If the image’s tiling is
IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
and the image is
non-linear,
then the returned layout has an implementation-dependent meaning; the
vendor of the image’s
DRM format modifier
may provide documentation that explains how to interpret the returned
layout.
getImageSubresourceLayout
is invariant for the lifetime of a single
image. However, the subresource layout of images in Android hardware
buffer external memory is not known until the image has been bound to
memory, so applications must not call getImageSubresourceLayout
for
such an image before it has been bound.
Valid Usage
image
must have been created withtiling
equal toIMAGE_TILING_LINEAR
orIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
- The
aspectMask
member ofpSubresource
must only have a single bit set - The
mipLevel
member ofpSubresource
must be less than themipLevels
specified inImageCreateInfo
whenimage
was created - The
arrayLayer
member ofpSubresource
must be less than thearrayLayers
specified inImageCreateInfo
whenimage
was created - If the
tiling
of theimage
isIMAGE_TILING_LINEAR
and itsformat
is a multi-planar format with two planes, theaspectMask
member ofpSubresource
must beIMAGE_ASPECT_PLANE_0_BIT
orIMAGE_ASPECT_PLANE_1_BIT
- If the
tiling
of theimage
isIMAGE_TILING_LINEAR
and itsformat
is a multi-planar format with three planes, theaspectMask
member ofpSubresource
must beIMAGE_ASPECT_PLANE_0_BIT
,IMAGE_ASPECT_PLANE_1_BIT
orIMAGE_ASPECT_PLANE_2_BIT
- If
image
was created with theEXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
external memory handle type, thenimage
must be bound to memory - If the
tiling
of theimage
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then theaspectMask
member ofpSubresource
must beVK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT
and the indexi
must be less than theDrmFormatModifierPropertiesEXT
::drmFormatModifierPlaneCount
associated with the image’sformat
andImageDrmFormatModifierPropertiesEXT
::drmFormatModifier
Valid Usage (Implicit)
device
must be a validDevice
handle
image
must be a validImage
handlepSubresource
must be a valid pointer to a validImageSubresource
structurepLayout
must be a valid pointer to aSubresourceLayout
structureimage
must have been created, allocated, or retrieved fromdevice
See Also
data ImageSubresource Source #
VkImageSubresource - Structure specifying an image subresource
Valid Usage (Implicit)
See Also
ImageAspectFlags
,
SparseImageMemoryBind
,
getImageSubresourceLayout
ImageSubresource | |
|
Instances
data ImageCreateInfo (es :: [Type]) Source #
VkImageCreateInfo - Structure specifying the parameters of a newly created image object
Description
Images created with tiling
equal to
IMAGE_TILING_LINEAR
have further
restrictions on their limits and capabilities compared to images created
with tiling
equal to
IMAGE_TILING_OPTIMAL
. Creation of
images with tiling IMAGE_TILING_LINEAR
may not be supported unless other parameters meet all of the
constraints:
imageType
isIMAGE_TYPE_2D
format
is not a depth/stencil formatmipLevels
is 1arrayLayers
is 1samples
isSAMPLE_COUNT_1_BIT
usage
only includesIMAGE_USAGE_TRANSFER_SRC_BIT
and/orIMAGE_USAGE_TRANSFER_DST_BIT
Images created with a format
from one of those listed in
https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion
have further restrictions on their limits and capabilities compared to
images created with other formats. Creation of images with a format
requiring
Y′CBCR conversion
may not be supported unless other parameters meet all of the
constraints:
imageType
isIMAGE_TYPE_2D
mipLevels
is 1arrayLayers
is 1samples
isSAMPLE_COUNT_1_BIT
Implementations may support additional limits and capabilities beyond those listed above.
To determine the set of valid usage
bits for a given format, call
getPhysicalDeviceFormatProperties
.
If the size of the resultant image would exceed maxResourceSize
, then
createImage
must fail and return
ERROR_OUT_OF_DEVICE_MEMORY
. This failure
may occur even when all image creation parameters satisfy their valid
usage requirements.
Note
For images created without
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
IMAGE_CREATE_EXTENDED_USAGE_BIT
a usage
bit is valid if it is supported for at least one of the
formats a ImageView
created from the image can
have (see
Image Views
for more detail).
Valid values for some image creation parameters are limited by a
numerical upper bound or by inclusion in a bitset. For example,
ImageCreateInfo
::arrayLayers
is limited by
imageCreateMaxArrayLayers
, defined below; and
ImageCreateInfo
::samples
is limited by imageCreateSampleCounts
,
also defined below.
Several limiting values are defined below, as well as assisting values
from which the limiting values are derived. The limiting values are
referenced by the relevant valid usage statements of ImageCreateInfo
.
Let
uint64_t imageCreateDrmFormatModifiers[]
be the set of Linux DRM format modifiers that the resultant image may have.- If
tiling
is notIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, thenimageCreateDrmFormatModifiers
is empty. - If
ImageCreateInfo
::pNext
containsImageDrmFormatModifierExplicitCreateInfoEXT
, thenimageCreateDrmFormatModifiers
contains exactly one modifier,ImageDrmFormatModifierExplicitCreateInfoEXT
::drmFormatModifier
. - If
ImageCreateInfo
::pNext
containsImageDrmFormatModifierListCreateInfoEXT
, thenimageCreateDrmFormatModifiers
contains the entire arrayImageDrmFormatModifierListCreateInfoEXT
::pDrmFormatModifiers
.
- If
Let
VkBool32 imageCreateMaybeLinear
indicate if the resultant image may be linear.- If
tiling
isIMAGE_TILING_LINEAR
, thenimageCreateMaybeLinear
istrue
. - If
tiling
isIMAGE_TILING_OPTIMAL
, thenimageCreateMaybeLinear
isfalse
. - If
tiling
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, thenimageCreateMaybeLinear_
istrue
if and only ifimageCreateDrmFormatModifiers
containsDRM_FORMAT_MOD_LINEAR
.
- If
Let
VkFormatFeatureFlags imageCreateFormatFeatures
be the set of valid format features available during image creation.- If
tiling
isIMAGE_TILING_LINEAR
, thenimageCreateFormatFeatures
is the value ofImageFormatProperties
::linearTilingFeatures
found by callinggetPhysicalDeviceFormatProperties
with parameterformat
equal toImageCreateInfo
::format
. - If
tiling
isIMAGE_TILING_OPTIMAL
, and if thepNext
chain includes noExternalFormatANDROID
structure with non-zeroexternalFormat
, thenimageCreateFormatFeatures
is value ofImageFormatProperties
::optimalTilingFeatures
found by callinggetPhysicalDeviceFormatProperties
with parameterformat
equal toImageCreateInfo
::format
. - If
tiling
isIMAGE_TILING_OPTIMAL
, and if thepNext
chain includes aExternalFormatANDROID
structure with non-zeroexternalFormat
, thenimageCreateFormatFeatures
is the value ofAndroidHardwareBufferFormatPropertiesANDROID
::formatFeatures
obtained bygetAndroidHardwareBufferPropertiesANDROID
with a matchingexternalFormat
value. - If
tiling
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then the value ofimageCreateFormatFeatures
is found by callinggetPhysicalDeviceFormatProperties2
withImageFormatProperties
::format
equal toImageCreateInfo
::format
and withDrmFormatModifierPropertiesListEXT
chained intoImageFormatProperties2
; by collecting all members of the returned arrayDrmFormatModifierPropertiesListEXT
::pDrmFormatModifierProperties
whosedrmFormatModifier
belongs toimageCreateDrmFormatModifiers
; and by taking the bitwise intersection, over the collected array members, ofdrmFormatModifierTilingFeatures
. (The resultantimageCreateFormatFeatures
may be empty).
- If
Let
VkImageFormatProperties2 imageCreateImageFormatPropertiesList[]
be defined as follows.If
ImageCreateInfo
::pNext
contains noExternalFormatANDROID
structure with non-zeroexternalFormat
, thenimageCreateImageFormatPropertiesList
is the list of structures obtained by callinggetPhysicalDeviceImageFormatProperties2
, possibly multiple times, as follows:- The parameters
PhysicalDeviceImageFormatInfo2
::format
,imageType
,tiling
,usage
, andflags
must be equal to those inImageCreateInfo
. - If
ImageCreateInfo
::pNext
contains aExternalMemoryImageCreateInfo
structure whosehandleTypes
is not0
, thenPhysicalDeviceImageFormatInfo2
::pNext
must contain aPhysicalDeviceExternalImageFormatInfo
structure whosehandleType
is not0
; andgetPhysicalDeviceImageFormatProperties2
must be called for each handle type inExternalMemoryImageCreateInfo
::handleTypes
, successively settingPhysicalDeviceExternalImageFormatInfo
::handleType
on each call. - If
ImageCreateInfo
::pNext
contains noExternalMemoryImageCreateInfo
structure, or contains a structure whosehandleTypes
is0
, thenPhysicalDeviceImageFormatInfo2
::pNext
must either contain noPhysicalDeviceExternalImageFormatInfo
structure, or contain a structure whosehandleType
is0
. - If
tiling
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, thenPhysicalDeviceImageFormatInfo2
::pNext
must contain aPhysicalDeviceImageDrmFormatModifierInfoEXT
structure wheresharingMode
is equal toImageCreateInfo
::sharingMode
; and, ifsharingMode
isSHARING_MODE_CONCURRENT
, thenqueueFamilyIndexCount
andpQueueFamilyIndices
must be equal to those inImageCreateInfo
; and, ifflags
containsIMAGE_CREATE_MUTABLE_FORMAT_BIT
, then theImageFormatListCreateInfo
structure included in thepNext
chain ofPhysicalDeviceImageFormatInfo2
must be equivalent to the one included in thepNext
chain ofImageCreateInfo
; andgetPhysicalDeviceImageFormatProperties2
must be called for each modifier inimageCreateDrmFormatModifiers
, successively settingPhysicalDeviceImageDrmFormatModifierInfoEXT
::drmFormatModifier
on each call. - If
tiling
is notIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, thenPhysicalDeviceImageFormatInfo2
::pNext
must contain noPhysicalDeviceImageDrmFormatModifierInfoEXT
structure. - If any call to
getPhysicalDeviceImageFormatProperties2
returns an error, thenimageCreateImageFormatPropertiesList
is defined to be the empty list.
- The parameters
If
ImageCreateInfo
::pNext
contains aExternalFormatANDROID
structure with non-zeroexternalFormat
, thenimageCreateImageFormatPropertiesList
contains a single element where:ImageFormatProperties
::maxMipLevels
is ⌊log2(max(extent.width
,extent.height
,extent.depth
))⌋ + 1.ImageFormatProperties
::maxArrayLayers
isPhysicalDeviceLimits
::maxImageArrayLayers.- Each component of
ImageFormatProperties
::maxExtent
isPhysicalDeviceLimits
::maxImageDimension2D. ImageFormatProperties
::sampleCounts
contains exactlySAMPLE_COUNT_1_BIT
.
- Let
uint32_t imageCreateMaxMipLevels
be the minimum value ofImageFormatProperties
::maxMipLevels
inimageCreateImageFormatPropertiesList
. The value is undefined ifimageCreateImageFormatPropertiesList
is empty. - Let
uint32_t imageCreateMaxArrayLayers
be the minimum value ofImageFormatProperties
::maxArrayLayers
inimageCreateImageFormatPropertiesList
. The value is undefined ifimageCreateImageFormatPropertiesList
is empty. - Let
VkExtent3D imageCreateMaxExtent
be the component-wise minimum over allImageFormatProperties
::maxExtent
values inimageCreateImageFormatPropertiesList
. The value is undefined ifimageCreateImageFormatPropertiesList
is empty. - Let
VkSampleCountFlags imageCreateSampleCounts
be the intersection of eachImageFormatProperties
::sampleCounts
inimageCreateImageFormatPropertiesList
. The value is undefined ifimageCreateImageFormatPropertiesList
is empty.
Valid Usage
- Each of the following values (as described in
Image Creation Limits)
must not be undefined
imageCreateMaxMipLevels
,imageCreateMaxArrayLayers
,imageCreateMaxExtent
, andimageCreateSampleCounts
- If
sharingMode
isSHARING_MODE_CONCURRENT
,pQueueFamilyIndices
must be a valid pointer to an array ofqueueFamilyIndexCount
uint32_t
values - If
sharingMode
isSHARING_MODE_CONCURRENT
,queueFamilyIndexCount
must be greater than1
- If
sharingMode
isSHARING_MODE_CONCURRENT
, each element ofpQueueFamilyIndices
must be unique and must be less thanpQueueFamilyPropertyCount
returned by eithergetPhysicalDeviceQueueFamilyProperties
orgetPhysicalDeviceQueueFamilyProperties2
for thephysicalDevice
that was used to createdevice
- If the
pNext
chain includes aExternalFormatANDROID
structure, and itsexternalFormat
member is non-zero theformat
must beFORMAT_UNDEFINED
- If the
pNext
chain does not include aExternalFormatANDROID
structure, or does and itsexternalFormat
member is0
, theformat
must not beFORMAT_UNDEFINED
extent.width
must be greater than0
extent.height
must be greater than0
extent.depth
must be greater than0
mipLevels
must be greater than0
arrayLayers
must be greater than0
- If
flags
containsIMAGE_CREATE_CUBE_COMPATIBLE_BIT
,imageType
must beIMAGE_TYPE_2D
- If
flags
containsIMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
,imageType
must beIMAGE_TYPE_2D
- If
flags
containsIMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
,imageType
must beIMAGE_TYPE_3D
extent.width
must be less than or equal toimageCreateMaxExtent.width
(as defined in Image Creation Limits)extent.height
must be less than or equal toimageCreateMaxExtent.height
(as defined in Image Creation Limits)extent.depth
must be less than or equal toimageCreateMaxExtent.depth
(as defined in Image Creation Limits)- If
imageType
isIMAGE_TYPE_2D
andflags
containsIMAGE_CREATE_CUBE_COMPATIBLE_BIT
,extent.width
andextent.height
must be equal andarrayLayers
must be greater than or equal to 6 - If
imageType
isIMAGE_TYPE_1D
, bothextent.height
andextent.depth
must be1
- If
imageType
isIMAGE_TYPE_2D
,extent.depth
must be1
mipLevels
must be less than or equal to the number of levels in the complete mipmap chain based onextent.width
,extent.height
, andextent.depth
mipLevels
must be less than or equal toimageCreateMaxMipLevels
(as defined in Image Creation Limits)arrayLayers
must be less than or equal toimageCreateMaxArrayLayers
(as defined in Image Creation Limits)- If
imageType
isIMAGE_TYPE_3D
,arrayLayers
must be1
- If
samples
is notSAMPLE_COUNT_1_BIT
, thenimageType
must beIMAGE_TYPE_2D
,flags
must not containIMAGE_CREATE_CUBE_COMPATIBLE_BIT
,mipLevels
must be equal to1
, andimageCreateMaybeLinear
(as defined in Image Creation Limits) must befalse
, - If
samples
is notSAMPLE_COUNT_1_BIT
,usage
must not containIMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
- If
usage
includesIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
, then bits other thanIMAGE_USAGE_COLOR_ATTACHMENT_BIT
,IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
, andIMAGE_USAGE_INPUT_ATTACHMENT_BIT
must not be set - If
usage
includesIMAGE_USAGE_COLOR_ATTACHMENT_BIT
,IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
,IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
, orIMAGE_USAGE_INPUT_ATTACHMENT_BIT
,extent.width
must be less than or equal toPhysicalDeviceLimits
::maxFramebufferWidth
- If
usage
includesIMAGE_USAGE_COLOR_ATTACHMENT_BIT
,IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
,IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
, orIMAGE_USAGE_INPUT_ATTACHMENT_BIT
,extent.height
must be less than or equal toPhysicalDeviceLimits
::maxFramebufferHeight
- If
usage
includesIMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
,extent.width
must be less than or equal to \(\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\rceil\) - If
usage
includesIMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
,extent.height
must be less than or equal to \(\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\rceil\) - If
usage
includesIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
,usage
must also contain at least one ofIMAGE_USAGE_COLOR_ATTACHMENT_BIT
,IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
, orIMAGE_USAGE_INPUT_ATTACHMENT_BIT
samples
must be a bit value that is set inimageCreateSampleCounts
(as defined in Image Creation Limits)- If the
multisampled storage images
feature is not enabled, and
usage
containsIMAGE_USAGE_STORAGE_BIT
,samples
must beSAMPLE_COUNT_1_BIT
- If the
sparse bindings
feature is not enabled,
flags
must not containIMAGE_CREATE_SPARSE_BINDING_BIT
- If the
sparse aliased residency
feature is not enabled,
flags
must not containIMAGE_CREATE_SPARSE_ALIASED_BIT
- If
imageType
isIMAGE_TYPE_1D
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for 2D images
feature is not enabled, and
imageType
isIMAGE_TYPE_2D
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for 3D images
feature is not enabled, and
imageType
isIMAGE_TYPE_3D
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for images with 2 samples
feature is not enabled,
imageType
isIMAGE_TYPE_2D
, andsamples
isSAMPLE_COUNT_2_BIT
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for images with 4 samples
feature is not enabled,
imageType
isIMAGE_TYPE_2D
, andsamples
isSAMPLE_COUNT_4_BIT
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for images with 8 samples
feature is not enabled,
imageType
isIMAGE_TYPE_2D
, andsamples
isSAMPLE_COUNT_8_BIT
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If the
sparse residency for images with 16 samples
feature is not enabled,
imageType
isIMAGE_TYPE_2D
, andsamples
isSAMPLE_COUNT_16_BIT
,flags
must not containIMAGE_CREATE_SPARSE_RESIDENCY_BIT
- If
flags
containsIMAGE_CREATE_SPARSE_RESIDENCY_BIT
orIMAGE_CREATE_SPARSE_ALIASED_BIT
, it must also containIMAGE_CREATE_SPARSE_BINDING_BIT
- If any of the bits
IMAGE_CREATE_SPARSE_BINDING_BIT
,IMAGE_CREATE_SPARSE_RESIDENCY_BIT
, orIMAGE_CREATE_SPARSE_ALIASED_BIT
are set,IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
must not also be set - If the protected memory feature is not enabled,
flags
must not containIMAGE_CREATE_PROTECTED_BIT
- If any of the bits
IMAGE_CREATE_SPARSE_BINDING_BIT
,IMAGE_CREATE_SPARSE_RESIDENCY_BIT
, orIMAGE_CREATE_SPARSE_ALIASED_BIT
are set,IMAGE_CREATE_PROTECTED_BIT
must not also be set - If the
pNext
chain includes aExternalMemoryImageCreateInfoNV
structure, it must not contain aExternalMemoryImageCreateInfo
structure - If the
pNext
chain includes aExternalMemoryImageCreateInfo
structure, itshandleTypes
member must only contain bits that are also inExternalImageFormatProperties
::externalMemoryProperties.compatibleHandleTypes
, as returned bygetPhysicalDeviceImageFormatProperties2
withformat
,imageType
,tiling
,usage
, andflags
equal to those in this structure, and with aPhysicalDeviceExternalImageFormatInfo
structure included in thepNext
chain, with ahandleType
equal to any one of the handle types specified inExternalMemoryImageCreateInfo
::handleTypes
- If the
pNext
chain includes aExternalMemoryImageCreateInfoNV
structure, itshandleTypes
member must only contain bits that are also inExternalImageFormatPropertiesNV
::externalMemoryProperties.compatibleHandleTypes
, as returned bygetPhysicalDeviceExternalImageFormatPropertiesNV
withformat
,imageType
,tiling
,usage
, andflags
equal to those in this structure, and withexternalHandleType
equal to any one of the handle types specified inExternalMemoryImageCreateInfoNV
::handleTypes
- If the logical device was created with
DeviceGroupDeviceCreateInfo
::physicalDeviceCount
equal to 1,flags
must not containIMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
- If
flags
containsIMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
, thenmipLevels
must be one,arrayLayers
must be one,imageType
must beIMAGE_TYPE_2D
. andimageCreateMaybeLinear
(as defined in Image Creation Limits) must befalse
- If
flags
containsIMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
, thenformat
must be a block-compressed image format, an ETC compressed image format, or an ASTC compressed image format - If
flags
containsIMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
, thenflags
must also containIMAGE_CREATE_MUTABLE_FORMAT_BIT
initialLayout
must beIMAGE_LAYOUT_UNDEFINED
orIMAGE_LAYOUT_PREINITIALIZED
- If the
pNext
chain includes aExternalMemoryImageCreateInfo
orExternalMemoryImageCreateInfoNV
structure whosehandleTypes
member is not0
,initialLayout
must beIMAGE_LAYOUT_UNDEFINED
- If the image
format
is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion, thenmipLevels
must be 1 - If the image
format
is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion,samples
must beSAMPLE_COUNT_1_BIT
- If the image
format
is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion,imageType
must beIMAGE_TYPE_2D
- If the image
format
is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion, and theycbcrImageArrays
feature is not enabled,arrayLayers
must be 1 - If
format
is a multi-planar format, and ifimageCreateFormatFeatures
(as defined in Image Creation Limits) does not containFORMAT_FEATURE_DISJOINT_BIT
, thenflags
must not containIMAGE_CREATE_DISJOINT_BIT
- If
format
is not a multi-planar format, andflags
does not includeIMAGE_CREATE_ALIAS_BIT
,flags
must not containIMAGE_CREATE_DISJOINT_BIT
- If
tiling
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then thepNext
chain must include exactly one ofImageDrmFormatModifierListCreateInfoEXT
orImageDrmFormatModifierExplicitCreateInfoEXT
structures - If the
pNext
chain includes aImageDrmFormatModifierListCreateInfoEXT
orImageDrmFormatModifierExplicitCreateInfoEXT
structure, thentiling
must beIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
- If
tiling
isIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
andflags
containsIMAGE_CREATE_MUTABLE_FORMAT_BIT
, then thepNext
chain must include aImageFormatListCreateInfo
structure with non-zeroviewFormatCount
- If
flags
containsIMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
format
must be a depth or depth/stencil format - If the
pNext
chain includes aExternalMemoryImageCreateInfo
structure whosehandleTypes
member includesEXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
,imageType
must beIMAGE_TYPE_2D
- If the
pNext
chain includes aExternalMemoryImageCreateInfo
structure whosehandleTypes
member includesEXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
,mipLevels
must either be1
or equal to the number of levels in the complete mipmap chain based onextent.width
,extent.height
, andextent.depth
- If the
pNext
chain includes aExternalFormatANDROID
structure whoseexternalFormat
member is not0
,flags
must not includeIMAGE_CREATE_MUTABLE_FORMAT_BIT
- If the
pNext
chain includes aExternalFormatANDROID
structure whoseexternalFormat
member is not0
,usage
must not include any usages exceptIMAGE_USAGE_SAMPLED_BIT
- If the
pNext
chain includes aExternalFormatANDROID
structure whoseexternalFormat
member is not0
,tiling
must beIMAGE_TILING_OPTIMAL
- If
format
is a depth-stencil format,usage
includesIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
, and thepNext
chain includes aImageStencilUsageCreateInfo
structure, then itsImageStencilUsageCreateInfo
::stencilUsage
member must also includeIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
- If
format
is a depth-stencil format,usage
does not includeIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
, and thepNext
chain includes aImageStencilUsageCreateInfo
structure, then itsImageStencilUsageCreateInfo
::stencilUsage
member must also not includeIMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
- If
format
is a depth-stencil format,usage
includesIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
, and thepNext
chain includes aImageStencilUsageCreateInfo
structure, then itsImageStencilUsageCreateInfo
::stencilUsage
member must also includeIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
- If
format
is a depth-stencil format,usage
does not includeIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
, and thepNext
chain includes aImageStencilUsageCreateInfo
structure, then itsImageStencilUsageCreateInfo
::stencilUsage
member must also not includeIMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
- If
Format
is a depth-stencil format and thepNext
chain includes aImageStencilUsageCreateInfo
structure with itsstencilUsage
member includingIMAGE_USAGE_INPUT_ATTACHMENT_BIT
,extent.width
must be less than or equal toPhysicalDeviceLimits
::maxFramebufferWidth
- If
format
is a depth-stencil format and thepNext
chain includes aImageStencilUsageCreateInfo
structure with itsstencilUsage
member includingIMAGE_USAGE_INPUT_ATTACHMENT_BIT
,extent.height
must be less than or equal toPhysicalDeviceLimits
::maxFramebufferHeight
- If the
multisampled storage images
feature is not enabled,
format
is a depth-stencil format and thepNext
chain includes aImageStencilUsageCreateInfo
structure with itsstencilUsage
includingIMAGE_USAGE_STORAGE_BIT
,samples
must beSAMPLE_COUNT_1_BIT
- If
flags
containsIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
,imageType
must beIMAGE_TYPE_2D
orIMAGE_TYPE_3D
- If
flags
containsIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
, it must not containIMAGE_CREATE_CUBE_COMPATIBLE_BIT
and theformat
must not be a depth/stencil format - If
flags
containsIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
andimageType
isIMAGE_TYPE_2D
,extent.width
andextent.height
must be greater than1
- If
flags
containsIMAGE_CREATE_CORNER_SAMPLED_BIT_NV
andimageType
isIMAGE_TYPE_3D
,extent.width
,extent.height
, andextent.depth
must be greater than1
- If
usage
includesIMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
,imageType
must beIMAGE_TYPE_2D
- If
usage
includesIMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
,samples
must beSAMPLE_COUNT_1_BIT
- If
usage
includesIMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
,tiling
must beIMAGE_TILING_OPTIMAL
- If
flags
containsIMAGE_CREATE_SUBSAMPLED_BIT_EXT
,tiling
must beIMAGE_TILING_OPTIMAL
- If
flags
containsIMAGE_CREATE_SUBSAMPLED_BIT_EXT
,imageType
must beIMAGE_TYPE_2D
- If
flags
containsIMAGE_CREATE_SUBSAMPLED_BIT_EXT
,flags
must not containIMAGE_CREATE_CUBE_COMPATIBLE_BIT
- If
flags
containsIMAGE_CREATE_SUBSAMPLED_BIT_EXT
,mipLevels
must be1
Valid Usage (Implicit)
sType
must beSTRUCTURE_TYPE_IMAGE_CREATE_INFO
- Each
pNext
member of any structure (including this one) in thepNext
chain must be eitherNULL
or a pointer to a valid instance ofDedicatedAllocationImageCreateInfoNV
,ExternalFormatANDROID
,ExternalMemoryImageCreateInfo
,ExternalMemoryImageCreateInfoNV
,ImageDrmFormatModifierExplicitCreateInfoEXT
,ImageDrmFormatModifierListCreateInfoEXT
,ImageFormatListCreateInfo
,ImageStencilUsageCreateInfo
, orImageSwapchainCreateInfoKHR
- The
sType
value of each struct in thepNext
chain must be unique flags
must be a valid combination ofImageCreateFlagBits
valuesimageType
must be a validImageType
valueformat
must be a validFormat
valuesamples
must be a validSampleCountFlagBits
valuetiling
must be a validImageTiling
valueusage
must be a valid combination ofImageUsageFlagBits
valuesusage
must not be0
sharingMode
must be a validSharingMode
valueinitialLayout
must be a validImageLayout
value
</section> = See Also
Extent3D
,
Format
,
ImageCreateFlags
,
ImageLayout
,
ImageTiling
,
ImageType
,
ImageUsageFlags
,
SampleCountFlagBits
,
SharingMode
,
StructureType
, createImage
ImageCreateInfo | |
|
Instances
data SubresourceLayout Source #
VkSubresourceLayout - Structure specifying subresource layout
Description
If the image is
linear,
then 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;
The value of arrayPitch
is undefined for images that were not created
as arrays. depthPitch
is defined only for 3D images.
If the image has a single-plane color format and its tiling is
IMAGE_TILING_LINEAR
, then the
aspectMask
member of ImageSubresource
must be
IMAGE_ASPECT_COLOR_BIT
.
If the image has a depth/stencil format and its tiling is
IMAGE_TILING_LINEAR
, then
aspectMask
must be either
IMAGE_ASPECT_DEPTH_BIT
or
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.
If the image has a
multi-planar format
and its tiling is IMAGE_TILING_LINEAR
, then the aspectMask
member of ImageSubresource
must be
IMAGE_ASPECT_PLANE_0_BIT
,
IMAGE_ASPECT_PLANE_1_BIT
, or
(for 3-plane formats only)
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. If the image is disjoint, then the offset
is relative to the
base address of the plane. If the image is non-disjoint, then the
offset
is relative to the base address of the image.
If the image’s tiling is
IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
,
then the aspectMask
member of ImageSubresource
must be one of
VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT
, where the maximum allowed
plane index i
is defined by the
DrmFormatModifierPropertiesEXT
::drmFormatModifierPlaneCount
associated with the image’s ImageCreateInfo
::format
and
modifier.
The memory range used by the subresource is described by offset
and
size
. If the image is disjoint, then the offset
is relative to the
base address of the memory plane. If the image is non-disjoint, then
the offset
is relative to the base address of the image. If the image
is
non-linear,
then rowPitch
, arrayPitch
, and depthPitch
have an
implementation-dependent meaning.
See Also
DeviceSize
,
ImageDrmFormatModifierExplicitCreateInfoEXT
,
getImageSubresourceLayout
SubresourceLayout | |
|