VkImageTiling - Specifies the tiling arrangement of data in an image

See Also

VkImageCreateInfo, VkPhysicalDeviceImageFormatInfo2, VkPhysicalDeviceSparseImageFormatInfo2, vkGetPhysicalDeviceExternalImageFormatPropertiesNV, vkGetPhysicalDeviceImageFormatProperties, vkGetPhysicalDeviceSparseImageFormatProperties

VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more optimal memory access).

VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row).

VkImageType - Specifies the type of an image object

See Also

VkImageCreateInfo, VkPhysicalDeviceImageFormatInfo2, VkPhysicalDeviceSparseImageFormatInfo2, vkGetPhysicalDeviceExternalImageFormatPropertiesNV, vkGetPhysicalDeviceImageFormatProperties, vkGetPhysicalDeviceSparseImageFormatProperties

VK_IMAGE_TYPE_1D specifies a one-dimensional image.

VK_IMAGE_TYPE_2D specifies a two-dimensional image.

VK_IMAGE_TYPE_3D specifies a three-dimensional image.

VkPhysicalDeviceType - Supported physical device types

Description

• VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any other available types.

• VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically one embedded in or tightly coupled with the host.
• VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a separate processor connected to the host via an interlink.
• VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a virtual node in a virtualization environment.
• VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on the same processors as the host.

The physical device type is advertised for informational purposes only, and does not directly affect the operation of the system. However, the device type may correlate with other advertised properties or capabilities of the system, such as how many memory heaps there are.

See Also

VkPhysicalDeviceProperties

VkSystemAllocationScope - Allocation scope

Description

• VK_SYSTEM_ALLOCATION_SCOPE_COMMAND specifies that the allocation is scoped to the duration of the Vulkan command.

• VK_SYSTEM_ALLOCATION_SCOPE_OBJECT specifies that the allocation is scoped to the lifetime of the Vulkan object that is being created or used.
• VK_SYSTEM_ALLOCATION_SCOPE_CACHE specifies that the allocation is scoped to the lifetime of a VkPipelineCache or VkValidationCacheEXT object.
• VK_SYSTEM_ALLOCATION_SCOPE_DEVICE specifies that the allocation is scoped to the lifetime of the Vulkan device.
• VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE specifies that the allocation is scoped to the lifetime of the Vulkan instance.

Most Vulkan commands operate on a single object, or there is a sole object that is being created or manipulated. When an allocation uses an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the object being created or manipulated.

When an implementation requires host memory, it will make callbacks to the application using the most specific allocator and allocation scope available:

• If an allocation is scoped to the duration of a command, the allocator will use the VK_SYSTEM_ALLOCATION_SCOPE_COMMAND allocation scope. The most specific allocator available is used: if the object being created or manipulated has an allocator, that object’s allocator will be used, else if the parent VkDevice has an allocator it will be used, else if the parent VkInstance has an allocator it will be used. Else,
• If an allocation is associated with an object of type VkValidationCacheEXT or VkPipelineCache, the allocator will use the VK_SYSTEM_ALLOCATION_SCOPE_CACHE allocation scope. The most specific allocator available is used (cache, else device, else instance). Else,
• If an allocation is scoped to the lifetime of an object, that object is being created or manipulated by the command, and that object’s type is not VkDevice or VkInstance, the allocator will use an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_OBJECT. The most specific allocator available is used (object, else device, else instance). Else,
• If an allocation is scoped to the lifetime of a device, the allocator will use an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_DEVICE. The most specific allocator available is used (device, else instance). Else,
• If the allocation is scoped to the lifetime of an instance and the instance has an allocator, its allocator will be used with an allocation scope of VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE.
• Otherwise an implementation will allocate memory through an alternative mechanism that is unspecified.

See Also

VkAllocationCallbacks

VkInternalAllocationType - Allocation type

See Also

PFN_vkInternalAllocationNotification, PFN_vkInternalFreeNotification

VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the allocation is intended for execution by the host.

VkInstanceCreateFlags - Reserved for future use

Description

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

See Also

VkInstanceCreateInfo

VkQueueFlagBits - Bitmask specifying capabilities of queues in a queue family

Description

• VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family support graphics operations.

• VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family support compute operations.
• VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family support transfer operations.
• VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue family support sparse memory management operations (see Sparse Resources). If any of the sparse resource features are enabled, then at least one queue family must support this bit.

If an implementation exposes any queue family that supports graphics operations, at least one queue family of at least one physical device exposed by the implementation must support both graphics and compute operations.

Note

All commands that are allowed on a queue that supports transfer operations are also allowed on a queue that supports either graphics or compute operations. Thus, if the capabilities of a queue family include VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, then reporting the VK_QUEUE_TRANSFER_BIT capability separately for that queue family is optional.

For further details see Queues.

See Also

VkQueueFlags

VkMemoryPropertyFlagBits - Bitmask specifying properties for a memory type

See Also

VkMemoryPropertyFlags

VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit specifies that memory allocated with this type is the most efficient for device access. This property will be set if and only if the memory type belongs to a heap with the VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set.

VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit specifies that memory allocated with this type can be mapped for host access using vkMapMemory.

VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit specifies that the host cache management commands vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges are not needed to flush host writes to the device or make device writes visible to the host, respectively.

VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit specifies that memory allocated with this type is cached on the host. Host memory accesses to uncached memory are slower than to cached memory, however uncached memory is always host coherent.

VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit specifies that the memory type only allows device access to the memory. Memory types must not have both VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. Additionally, the object’s backing memory may be provided by the implementation lazily as specified in Lazily Allocated Memory.

VkMemoryHeapFlagBits - Bitmask specifying attribute flags for a heap

See Also

VkMemoryHeapFlags

VK_MEMORY_HEAP_DEVICE_LOCAL_BIT specifies that the heap corresponds to device local memory. Device local memory may have different performance characteristics than host local memory, and may support different memory property flags.

VkImageUsageFlagBits - Bitmask specifying intended usage of an image

See Also

VkImageUsageFlags

VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can be used as the source of a transfer command.

VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can be used as the destination of a transfer command.

VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a shader.

VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_IMAGE.

VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a color or resolve attachment in a VkFramebuffer.

VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a depth/stencil attachment in a VkFramebuffer.

VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that the memory bound to this image will have been allocated with the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT (see {html_spec_relative}#memory for more detail). This bit can be set for any image that can be used to create a VkImageView suitable for use as a color, resolve, depth/stencil, or input attachment.

VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for occupying VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer.

VkImageCreateFlagBits - Bitmask specifying additional parameters of an image

Description

• VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will be backed using sparse memory binding.

• VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can be partially backed using sparse memory binding. Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag.
• VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another image (or another portion of the same image). Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag
• VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can be used to create a VkImageView with a different format from the image. For multi-planar formats, VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a VkImageView can be created of a plane of the image.
• VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_CUBE or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.
• VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY.
• VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the image can be used with a non-zero value of the splitInstanceBindRegionCount member of a VkBindImageMemoryDeviceGroupInfo structure passed into vkBindImageMemory2. This flag also has the effect of making the image use the standard sparse image block dimensions.
• VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the image having a compressed format can be used to create a VkImageView with an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image.
• VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can be created with usage flags that are not supported for the format the image is created with but are supported for at least one format a VkImageView created from the image can have.
• VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a multi-planar format must have each plane separately bound to memory, rather than having a single memory binding for the whole image; the presence of this bit distinguishes a disjoint image from an image without this bit set.
• VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with the same creation parameters and aliased to the same memory can interpret the contents of the memory consistently with each other, subject to the rules described in the Memory Aliasing section. This flag further specifies that each plane of a disjoint image can share an in-memory non-linear representation with single-plane images, and that a single-plane image can share an in-memory non-linear representation with a plane of a multi-planar disjoint image, according to the rules in {html_spec_relative}#features-formats-compatible-planes. If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, it is as if VK_IMAGE_CREATE_ALIAS_BIT is set.
• VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT specifies that an image with a depth or depth/stencil format can be used with custom sample locations when used as a depth/stencil attachment.

See Sparse Resource Features and Sparse Physical Device Features for more details.

See Also

VkImageCreateFlags

VkFormatFeatureFlagBits - Bitmask specifying features supported by a buffer

Description

The following bits may be set in linearTilingFeatures and optimalTilingFeatures, specifying that the features are supported by images or image views created with the queried vkGetPhysicalDeviceFormatProperties::format:

• VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT specifies that an image view can be sampled from.
• VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT specifies that an image view can be used as a storage images.
• VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT specifies that an image view can be used as storage image that supports atomic operations.
• VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT specifies that an image view can be used as a framebuffer color attachment and as an input attachment.
• VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT specifies that an image view can be used as a framebuffer color attachment that supports blending and as an input attachment.
• VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that an image view can be used as a framebuffer depth/stencil attachment and as an input attachment.
• VK_FORMAT_FEATURE_BLIT_SRC_BIT specifies that an image can be used as srcImage for the vkCmdBlitImage command.
• VK_FORMAT_FEATURE_BLIT_DST_BIT specifies that an image can be used as dstImage for the vkCmdBlitImage command.

• VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT specifies that if VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT is also set, an image view can be used with a sampler that has either of magFilter or minFilter set to VK_FILTER_LINEAR, or mipmapMode set to VK_SAMPLER_MIPMAP_MODE_LINEAR. If VK_FORMAT_FEATURE_BLIT_SRC_BIT is also set, an image can be used as the srcImage to vkCmdBlitImage with a filter of VK_FILTER_LINEAR. This bit must only be exposed for formats that also support the VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT or VK_FORMAT_FEATURE_BLIT_SRC_BIT.

  If the format being queried is a depth/stencil format, this bit only specifies that the depth aspect (not the stencil aspect) of an image of this format supports linear filtering, and that linear filtering of the depth aspect is supported whether depth compare is enabled in the sampler or not. If this bit is not present, linear filtering with depth compare disabled is unsupported and linear filtering with depth compare enabled is supported, but may compute the filtered value in an implementation-dependent manner which differs from the normal rules of linear filtering. The resulting value must be in the range [0,1] and should be proportional to, or a weighted average of, the number of comparison passes or failures.

• VK_FORMAT_FEATURE_TRANSFER_SRC_BIT specifies that an image can be used as a source image for copy commands.
• VK_FORMAT_FEATURE_TRANSFER_DST_BIT specifies that an image can be used as a destination image for copy commands and clear commands.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT specifies VkImage can be used as a sampled image with a min or max VkSamplerReductionModeEXT. This bit must only be exposed for formats that also support the VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG specifies that VkImage can be used with a sampler that has either of magFilter or minFilter set to VK_FILTER_CUBIC_IMG, or be the source image for a blit with filter set to VK_FILTER_CUBIC_IMG. This bit must only be exposed for formats that also support the VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. If the format being queried is a depth/stencil format, this only specifies that the depth aspect is cubic filterable.
• VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT specifies that an application can define a sampler Y’CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfo xChromaOffset and/or yChromaOffset of VK_CHROMA_LOCATION_MIDPOINT. Otherwise both xChromaOffset and yChromaOffset must be VK_CHROMA_LOCATION_COSITED_EVEN. If a format does not incorporate chroma downsampling (it is not a “422” or “420” format) but the implementation supports sampler Y’CBCR conversion for this format, the implementation must set VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT.
• VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT specifies that an application can define a sampler Y’CBCR conversion using this format as a source, and that an image of this format can be used with a VkSamplerYcbcrConversionCreateInfo xChromaOffset and/or yChromaOffset of VK_CHROMA_LOCATION_COSITED_EVEN. Otherwise both xChromaOffset and yChromaOffset must be VK_CHROMA_LOCATION_MIDPOINT. If neither VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT nor VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT is set, the application must not define a sampler Y’CBCR conversion using this format as a source.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT specifies that the format can do linear sampler filtering (min/magFilter) whilst sampler Y’CBCR conversion is enabled.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT specifies that the format can have different chroma, min, and mag filters.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT specifies that reconstruction is explicit, as described in {html_spec_relative}#textures-chroma-reconstruction. If this bit is not present, reconstruction is implicit by default.
• VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT specifies that reconstruction can be forcibly made explicit by setting VkSamplerYcbcrConversionCreateInfo::forceExplicitReconstruction to VK_TRUE.
• VK_FORMAT_FEATURE_DISJOINT_BIT specifies that a multi-planar image can have the VK_IMAGE_CREATE_DISJOINT_BIT set during image creation. An implementation must not set VK_FORMAT_FEATURE_DISJOINT_BIT for single-plane formats.

The following bits may be set in bufferFeatures, specifying that the features are supported by buffers or buffer views created with the queried vkGetPhysicalDeviceProperties::format:

• VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT specifies that the format can be used to create a buffer view that can be bound to a VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER descriptor.
• VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT specifies that the format can be used to create a buffer view that can be bound to a VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor.
• VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT specifies that atomic operations are supported on VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER with this format.
• VK_FORMAT_FEATURE_VERTEX_BUFFER_BIT specifies that the format can be used as a vertex attribute format (VkVertexInputAttributeDescription::format).

See Also

VkFormatFeatureFlags

VkSampleCountFlagBits - Bitmask specifying sample counts supported for an image used for storage operations

See Also

VkAttachmentDescription, VkImageCreateInfo, VkPhysicalDeviceSparseImageFormatInfo2, VkPipelineMultisampleStateCreateInfo, VkSampleCountFlags, VkSampleLocationsInfoEXT, vkGetPhysicalDeviceMultisamplePropertiesEXT, vkGetPhysicalDeviceSparseImageFormatProperties

VK_SAMPLE_COUNT_1_BIT specifies an image with one sample per pixel.

VK_SAMPLE_COUNT_2_BIT specifies an image with 2 samples per pixel.

VK_SAMPLE_COUNT_4_BIT specifies an image with 4 samples per pixel.

VK_SAMPLE_COUNT_8_BIT specifies an image with 8 samples per pixel.

VK_SAMPLE_COUNT_16_BIT specifies an image with 16 samples per pixel.

VK_SAMPLE_COUNT_32_BIT specifies an image with 32 samples per pixel.

VK_SAMPLE_COUNT_64_BIT specifies an image with 64 samples per pixel.

PFN_vkInternalAllocationNotification - Application-defined memory allocation notification function

Parameters

• pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

• size is the requested size of an allocation.
• allocationType is a VkInternalAllocationType value specifying the requested type of an allocation.
• allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

Description

This is a purely informational callback.

See Also

VkAllocationCallbacks

PFN_vkInternalFreeNotification - Application-defined memory free notification function

Parameters

• pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

• size is the requested size of an allocation.
• allocationType is a VkInternalAllocationType value specifying the requested type of an allocation.
• allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

See Also

VkAllocationCallbacks

PFN_vkReallocationFunction - Application-defined memory reallocation function

Parameters

• pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

• pOriginal must be either NULL or a pointer previously returned by pfnReallocation or pfnAllocation of the same allocator.
• size is the size in bytes of the requested allocation.
• alignment is the requested alignment of the allocation in bytes and must be a power of two.
• allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

Description

pfnReallocation must return an allocation with enough space for size bytes, and the contents of the original allocation from bytes zero to min(original size, new size) - 1 must be preserved in the returned allocation. If size is larger than the old size, the contents of the additional space are undefined. If satisfying these requirements involves creating a new allocation, then the old allocation should be freed.

If pOriginal is NULL, then pfnReallocation must behave equivalently to a call to PFN_vkAllocationFunction with the same parameter values (without pOriginal).

If size is zero, then pfnReallocation must behave equivalently to a call to PFN_vkFreeFunction with the same pUserData parameter value, and pMemory equal to pOriginal.

If pOriginal is non-NULL, the implementation must ensure that alignment is equal to the alignment used to originally allocate pOriginal.

If this function fails and pOriginal is non-NULL the application must not free the old allocation.

pfnReallocation must follow the same rules for return values as @PFN_vkAllocationFunction@.

See Also

VkAllocationCallbacks

PFN_vkAllocationFunction - Application-defined memory allocation function

Parameters

• pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

• size is the size in bytes of the requested allocation.
• alignment is the requested alignment of the allocation in bytes and must be a power of two.
• allocationScope is a VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described here.

Description

If pfnAllocation is unable to allocate the requested memory, it must return NULL. If the allocation was successful, it must return a valid pointer to memory allocation containing at least size bytes, and with the pointer value being a multiple of alignment.

Note

Correct Vulkan operation cannot be assumed if the application does not follow these rules.

For example, pfnAllocation (or pfnReallocation) could cause termination of running Vulkan instance(s) on a failed allocation for debugging purposes, either directly or indirectly. In these circumstances, it cannot be assumed that any part of any affected VkInstance objects are going to operate correctly (even vkDestroyInstance), and the application must ensure it cleans up properly via other means (e.g. process termination).

If pfnAllocation returns NULL, and if the implementation is unable to continue correct processing of the current command without the requested allocation, it must treat this as a run-time error, and generate VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command in which the condition was detected, as described in Return Codes.

If the implementation is able to continue correct processing of the current command without the requested allocation, then it may do so, and must not generate VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed allocation.

See Also

VkAllocationCallbacks

PFN_vkFreeFunction - Application-defined memory free function

Parameters

• pUserData is the value specified for VkAllocationCallbacks::pUserData in the allocator specified by the application.

• pMemory is the allocation to be freed.

Description

pMemory may be NULL, which the callback must handle safely. If pMemory is non-NULL, it must be a pointer previously allocated by pfnAllocation or pfnReallocation. The application should free this memory.

See Also

VkAllocationCallbacks

PFN_vkVoidFunction - Dummy function pointer type returned by queries

See Also

vkGetDeviceProcAddr, vkGetInstanceProcAddr

VkInstance - Opaque handle to a instance object

See Also

vkCreateAndroidSurfaceKHR, vkCreateDebugReportCallbackEXT, vkCreateDebugUtilsMessengerEXT, vkCreateDisplayPlaneSurfaceKHR, vkCreateIOSSurfaceMVK, vkCreateInstance, vkCreateMacOSSurfaceMVK, vkCreateMirSurfaceKHR, vkCreateViSurfaceNN, vkCreateWaylandSurfaceKHR, vkCreateWin32SurfaceKHR, vkCreateXcbSurfaceKHR, vkCreateXlibSurfaceKHR, vkDebugReportMessageEXT, vkDestroyDebugReportCallbackEXT, vkDestroyDebugUtilsMessengerEXT, vkDestroyInstance, vkDestroySurfaceKHR, vkEnumeratePhysicalDeviceGroups, vkEnumeratePhysicalDeviceGroupsKHR, vkEnumeratePhysicalDevices, vkGetInstanceProcAddr, vkSubmitDebugUtilsMessageEXT

VkPhysicalDevice - Opaque handle to a physical device object

See Also

VkDeviceGroupDeviceCreateInfo, VkPhysicalDeviceGroupProperties, vkAcquireXlibDisplayEXT, vkCreateDevice, vkCreateDisplayModeKHR, vkEnumerateDeviceExtensionProperties, vkEnumerateDeviceLayerProperties, vkEnumeratePhysicalDevices, vkGetDisplayModePropertiesKHR, vkGetDisplayPlaneCapabilitiesKHR, vkGetDisplayPlaneSupportedDisplaysKHR, vkGetPhysicalDeviceDisplayPlanePropertiesKHR, vkGetPhysicalDeviceDisplayPropertiesKHR, vkGetPhysicalDeviceExternalBufferProperties, vkGetPhysicalDeviceExternalBufferPropertiesKHR, vkGetPhysicalDeviceExternalFenceProperties, vkGetPhysicalDeviceExternalFencePropertiesKHR, vkGetPhysicalDeviceExternalImageFormatPropertiesNV, vkGetPhysicalDeviceExternalSemaphoreProperties, vkGetPhysicalDeviceExternalSemaphorePropertiesKHR, vkGetPhysicalDeviceFeatures, vkGetPhysicalDeviceFeatures2, vkGetPhysicalDeviceFeatures2KHR, vkGetPhysicalDeviceFormatProperties, vkGetPhysicalDeviceFormatProperties2, vkGetPhysicalDeviceFormatProperties2KHR, vkGetPhysicalDeviceGeneratedCommandsPropertiesNVX, vkGetPhysicalDeviceImageFormatProperties, vkGetPhysicalDeviceImageFormatProperties2, vkGetPhysicalDeviceImageFormatProperties2KHR, vkGetPhysicalDeviceMemoryProperties, vkGetPhysicalDeviceMemoryProperties2, vkGetPhysicalDeviceMemoryProperties2KHR, vkGetPhysicalDeviceMirPresentationSupportKHR, vkGetPhysicalDeviceMultisamplePropertiesEXT, vkGetPhysicalDevicePresentRectanglesKHR, vkGetPhysicalDeviceProperties, vkGetPhysicalDeviceProperties2, vkGetPhysicalDeviceProperties2KHR, vkGetPhysicalDeviceQueueFamilyProperties, vkGetPhysicalDeviceQueueFamilyProperties2, vkGetPhysicalDeviceQueueFamilyProperties2KHR, vkGetPhysicalDeviceSparseImageFormatProperties, vkGetPhysicalDeviceSparseImageFormatProperties2, vkGetPhysicalDeviceSparseImageFormatProperties2KHR, vkGetPhysicalDeviceSurfaceCapabilities2EXT, vkGetPhysicalDeviceSurfaceCapabilities2KHR, vkGetPhysicalDeviceSurfaceCapabilitiesKHR, vkGetPhysicalDeviceSurfaceFormats2KHR, vkGetPhysicalDeviceSurfaceFormatsKHR, vkGetPhysicalDeviceSurfacePresentModesKHR, vkGetPhysicalDeviceSurfaceSupportKHR, vkGetPhysicalDeviceWaylandPresentationSupportKHR, vkGetPhysicalDeviceWin32PresentationSupportKHR, vkGetPhysicalDeviceXcbPresentationSupportKHR, vkGetPhysicalDeviceXlibPresentationSupportKHR, vkGetRandROutputDisplayEXT, vkReleaseDisplayEXT

VkDevice - Opaque handle to a device object

See Also

vkAcquireNextImage2KHR, vkAcquireNextImageKHR, vkAllocateCommandBuffers, vkAllocateDescriptorSets, vkAllocateMemory, vkBindBufferMemory, vkBindBufferMemory2, vkBindBufferMemory2KHR, vkBindImageMemory, vkBindImageMemory2, vkBindImageMemory2KHR, vkCreateBuffer, vkCreateBufferView, vkCreateCommandPool, vkCreateComputePipelines, vkCreateDescriptorPool, vkCreateDescriptorSetLayout, vkCreateDescriptorUpdateTemplate, vkCreateDescriptorUpdateTemplateKHR, vkCreateDevice, vkCreateEvent, vkCreateFence, vkCreateFramebuffer, vkCreateGraphicsPipelines, vkCreateImage, vkCreateImageView, vkCreateIndirectCommandsLayoutNVX, vkCreateObjectTableNVX, vkCreatePipelineCache, vkCreatePipelineLayout, vkCreateQueryPool, vkCreateRenderPass, vkCreateSampler, vkCreateSamplerYcbcrConversion, vkCreateSamplerYcbcrConversionKHR, vkCreateSemaphore, vkCreateShaderModule, vkCreateSharedSwapchainsKHR, vkCreateSwapchainKHR, vkCreateValidationCacheEXT, vkDebugMarkerSetObjectNameEXT, vkDebugMarkerSetObjectTagEXT, vkDestroyBuffer, vkDestroyBufferView, vkDestroyCommandPool, vkDestroyDescriptorPool, vkDestroyDescriptorSetLayout, vkDestroyDescriptorUpdateTemplate, vkDestroyDescriptorUpdateTemplateKHR, vkDestroyDevice, vkDestroyEvent, vkDestroyFence, vkDestroyFramebuffer, vkDestroyImage, vkDestroyImageView, vkDestroyIndirectCommandsLayoutNVX, vkDestroyObjectTableNVX, vkDestroyPipeline, vkDestroyPipelineCache, vkDestroyPipelineLayout, vkDestroyQueryPool, vkDestroyRenderPass, vkDestroySampler, vkDestroySamplerYcbcrConversion, vkDestroySamplerYcbcrConversionKHR, vkDestroySemaphore, vkDestroyShaderModule, vkDestroySwapchainKHR, vkDestroyValidationCacheEXT, vkDeviceWaitIdle, vkDisplayPowerControlEXT, vkFlushMappedMemoryRanges, vkFreeCommandBuffers, vkFreeDescriptorSets, vkFreeMemory, vkGetAndroidHardwareBufferPropertiesANDROID, vkGetBufferMemoryRequirements, vkGetBufferMemoryRequirements2, vkGetBufferMemoryRequirements2KHR, vkGetDescriptorSetLayoutSupport, vkGetDescriptorSetLayoutSupportKHR, vkGetDeviceGroupPeerMemoryFeatures, vkGetDeviceGroupPeerMemoryFeaturesKHR, vkGetDeviceGroupPresentCapabilitiesKHR, vkGetDeviceGroupSurfacePresentModesKHR, vkGetDeviceMemoryCommitment, vkGetDeviceProcAddr, vkGetDeviceQueue, vkGetDeviceQueue2, vkGetEventStatus, vkGetFenceFdKHR, vkGetFenceStatus, vkGetFenceWin32HandleKHR, vkGetImageMemoryRequirements, vkGetImageMemoryRequirements2, vkGetImageMemoryRequirements2KHR, vkGetImageSparseMemoryRequirements, vkGetImageSparseMemoryRequirements2, vkGetImageSparseMemoryRequirements2KHR, vkGetImageSubresourceLayout, vkGetMemoryAndroidHardwareBufferANDROID, vkGetMemoryFdKHR, vkGetMemoryFdPropertiesKHR, vkGetMemoryHostPointerPropertiesEXT, vkGetMemoryWin32HandleKHR, vkGetMemoryWin32HandleNV, vkGetMemoryWin32HandlePropertiesKHR, vkGetPastPresentationTimingGOOGLE, vkGetPipelineCacheData, vkGetQueryPoolResults, vkGetRefreshCycleDurationGOOGLE, vkGetRenderAreaGranularity, vkGetSemaphoreFdKHR, vkGetSemaphoreWin32HandleKHR, vkGetShaderInfoAMD, vkGetSwapchainCounterEXT, vkGetSwapchainImagesKHR, vkGetSwapchainStatusKHR, vkGetValidationCacheDataEXT, vkImportFenceFdKHR, vkImportFenceWin32HandleKHR, vkImportSemaphoreFdKHR, vkImportSemaphoreWin32HandleKHR, vkInvalidateMappedMemoryRanges, vkMapMemory, vkMergePipelineCaches, vkMergeValidationCachesEXT, vkRegisterDeviceEventEXT, vkRegisterDisplayEventEXT, vkRegisterObjectsNVX, vkResetCommandPool, vkResetDescriptorPool, vkResetEvent, vkResetFences, vkSetDebugUtilsObjectNameEXT, vkSetDebugUtilsObjectTagEXT, vkSetEvent, vkSetHdrMetadataEXT, vkTrimCommandPool, vkTrimCommandPoolKHR, vkUnmapMemory, vkUnregisterObjectsNVX, vkUpdateDescriptorSetWithTemplate, vkUpdateDescriptorSetWithTemplateKHR, vkUpdateDescriptorSets, vkWaitForFences

vkCreateInstance - Create a new Vulkan instance

Parameters

• pCreateInfo points to an instance of VkInstanceCreateInfo controlling creation of the instance.

• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pInstance points a VkInstance handle in which the resulting instance is returned.

Description

vkCreateInstance verifies that the requested layers exist. If not, vkCreateInstance will return VK_ERROR_LAYER_NOT_PRESENT. Next vkCreateInstance verifies that the requested extensions are supported (e.g. in the implementation or in any enabled instance layer) and if any requested extension is not supported, vkCreateInstance must return VK_ERROR_EXTENSION_NOT_PRESENT. After verifying and enabling the instance layers and extensions the VkInstance object is created and returned to the application. If a requested extension is only supported by a layer, both the layer and the extension need to be specified at vkCreateInstance time for the creation to succeed.

Valid Usage

• All required extensions for each extension in the VkInstanceCreateInfo::ppEnabledExtensionNames list must also be present in that list.

Valid Usage (Implicit)

• pCreateInfo must be a valid pointer to a valid VkInstanceCreateInfo structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pInstance must be a valid pointer to a VkInstance handle

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_INITIALIZATION_FAILED

• VK_ERROR_LAYER_NOT_PRESENT

• VK_ERROR_EXTENSION_NOT_PRESENT

• VK_ERROR_INCOMPATIBLE_DRIVER

See Also

VkAllocationCallbacks, VkInstance, VkInstanceCreateInfo

vkDestroyInstance - Destroy an instance of Vulkan

Parameters

• instance is the handle of the instance to destroy.

• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

• All child objects created using instance must have been destroyed prior to destroying instance

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

Valid Usage (Implicit)

• If instance is not NULL, instance must be a valid VkInstance handle

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

Host Synchronization

• Host access to instance must be externally synchronized

See Also

VkAllocationCallbacks, VkInstance

vkEnumeratePhysicalDevices - Enumerates the physical devices accessible to a Vulkan instance

Parameters

• instance is a handle to a Vulkan instance previously created with vkCreateInstance.

• pPhysicalDeviceCount is a pointer to an integer related to the number of physical devices available or queried, as described below.
• pPhysicalDevices is either NULL or a pointer to an array of VkPhysicalDevice handles.

Description

If pPhysicalDevices is NULL, then the number of physical devices available is returned in pPhysicalDeviceCount. Otherwise, pPhysicalDeviceCount must point to a variable set by the user to the number of elements in the pPhysicalDevices array, and on return the variable is overwritten with the number of handles actually written to pPhysicalDevices. If pPhysicalDeviceCount is less than the number of physical devices available, at most pPhysicalDeviceCount structures will be written. If pPhysicalDeviceCount is smaller than the number of physical devices available, VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available physical devices were returned.

Valid Usage (Implicit)

• instance must be a valid VkInstance handle

• pPhysicalDeviceCount must be a valid pointer to a uint32_t value
• If the value referenced by pPhysicalDeviceCount is not 0, and pPhysicalDevices is not NULL, pPhysicalDevices must be a valid pointer to an array of pPhysicalDeviceCount VkPhysicalDevice handles

Return Codes

[Success] - VK_SUCCESS

• VK_INCOMPLETE

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_INITIALIZATION_FAILED

See Also

VkInstance, VkPhysicalDevice

vkGetDeviceProcAddr - Return a function pointer for a command

Parameters

The table below defines the various use cases for vkGetDeviceProcAddr and expected return value for each case.

Description

The returned function pointer is of type PFN_vkVoidFunction, and must be cast to the type of the command being queried. The function pointer must only be called with a dispatchable object (the first parameter) that is device or a child of device.

vkGetDeviceProcAddr behavior

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pName must be a null-terminated UTF-8 string

See Also

PFN_vkVoidFunction, VkDevice

vkGetInstanceProcAddr - Return a function pointer for a command

Parameters

• instance is the instance that the function pointer will be compatible with, or NULL for commands not dependent on any instance.

• pName is the name of the command to obtain.

Description

vkGetInstanceProcAddr itself is obtained in a platform- and loader- specific manner. Typically, the loader library will export this command as a function symbol, so applications can link against the loader library, or load it dynamically and look up the symbol using platform-specific APIs.

The table below defines the various use cases for vkGetInstanceProcAddr and expected return value (“fp” is “function pointer”) for each case.

The returned function pointer is of type PFN_vkVoidFunction, and must be cast to the type of the command being queried.