libktx - The KTX Library
Vulkan Texture Image Loader

Create texture images on a Vulkan device. More...

Functions

ktxVulkanDeviceInfoktxVulkanDeviceInfo::ktxVulkanDeviceInfo_Create (VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks *pAllocator)
 Create a ktxVulkanDeviceInfo object. More...
 
KTX_error_code ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_Construct (ktxVulkanDeviceInfo *This, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks *pAllocator)
 Construct a ktxVulkanDeviceInfo object. More...
 
void ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_Destruct (ktxVulkanDeviceInfo *This)
 Destruct a ktxVulkanDeviceInfo object. More...
 
void ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_Destroy (ktxVulkanDeviceInfo *This)
 Destroy a ktxVulkanDeviceInfo object. More...
 
KTX_error_code ktxTexture::ktxTexture_VkUploadEx (ktxTexture *This, ktxVulkanDeviceInfo *vdi, ktxVulkanTexture *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)
 Create a Vulkan image object from a ktxTexture object. More...
 
KTX_error_code ktxTexture::ktxTexture_VkUpload (ktxTexture *texture, ktxVulkanDeviceInfo *vdi, ktxVulkanTexture *vkTexture)
 Create a Vulkan image object from a ktxTexture object. More...
 
VkFormat ktxTexture::ktxTexture_GetVkFormat (ktxTexture *This)
 Return the VkFormat enum of a ktxTexture object. More...
 
void ktxVulkanTexture::ktxVulkanTexture_Destruct (ktxVulkanTexture *vkTexture, VkDevice device, const VkAllocationCallbacks *pAllocator)
 Destructor for the object returned when loading a texture image. More...
 

Detailed Description

Create texture images on a Vulkan device.

Function Documentation

◆ ktxTexture_GetVkFormat()

VkFormat ktxTexture_GetVkFormat ( ktxTexture This)

Return the VkFormat enum of a ktxTexture object.

Returns
The VkFormat of the ktxTexture. May return VK_FORMAT_UNDEFINED if there is no mapping from the GL internalformat and format.

◆ ktxTexture_VkUpload()

KTX_error_code ktxTexture_VkUpload ( ktxTexture texture,
ktxVulkanDeviceInfo vdi,
ktxVulkanTexture vkTexture 
)

Create a Vulkan image object from a ktxTexture object.

Calls ktxTexture_VkUploadEx() with the most commonly used options: VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_SAMPLED_BIT and VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.

See also
ktxTexture_VkUploadEx() for details and use that for complete control.

◆ ktxTexture_VkUploadEx()

KTX_error_code ktxTexture_VkUploadEx ( ktxTexture This,
ktxVulkanDeviceInfo vdi,
ktxVulkanTexture vkTexture,
VkImageTiling  tiling,
VkImageUsageFlags  usageFlags,
VkImageLayout  finalLayout 
)

Create a Vulkan image object from a ktxTexture object.

Creates a VkImage with VkFormat etc. matching the KTX data and uploads the images. Also creates a VkImageView object for accessing the image. Mipmaps will be generated if the ktxTexture's generateMipmaps flag is set. Returns the handles of the created objects and information about the texture in the ktxVulkanTexture pointed at by vkTexture.

usageFlags and thus acceptable usage of the created image may be augmented as follows:

  • with VK_IMAGE_USAGE_TRANSFER_DST_BIT if tiling is VK_IMAGE_TILING_OPTIMAL
  • with VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT if generateMipmaps is set in the ktxTexture.

Most Vulkan implementations support VK_IMAGE_TILING_LINEAR only for a very limited number of formats and features. Generally VK_IMAGE_TILING_OPTIMAL is preferred. The latter requires a staging buffer so will use more memory during loading.

Parameters
[in]Thispointer to the ktxTexture from which to upload.
[in]vdipointer to a ktxVulkanDeviceInfo structure providing information about the Vulkan device onto which to load the texture.
[in,out]vkTexturepointer to a ktxVulkanTexture structure into which the function writes information about the created VkImage.
[in]tilingtype of tiling to use in the destination image on the Vulkan device.
[in]usageFlagsa set of VkImageUsageFlags bits indicating the intended usage of the destination image.
[in]finalLayouta VkImageLayout value indicating the desired final layout of the created image.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis, vdi or vkTexture is NULL.
KTX_INVALID_OPERATIONThe ktxTexture contains neither images nor an active stream from which to read them.
KTX_INVALID_OPERATIONThe combination of the ktxTexture's format, tiling and usageFlags is not supported by the physical device.
KTX_INVALID_OPERATIONRequested mipmap generation is not supported by the physical device for the combination of the ktxTexture's format and tiling.
KTX_OUT_OF_MEMORYSufficient memory could not be allocated on either the CPU or the Vulkan device.
Examples:
vkload.cpp.

◆ ktxVulkanDeviceInfo_Construct()

KTX_error_code ktxVulkanDeviceInfo_Construct ( ktxVulkanDeviceInfo This,
VkPhysicalDevice  physicalDevice,
VkDevice  device,
VkQueue  queue,
VkCommandPool  cmdPool,
const VkAllocationCallbacks *  pAllocator 
)

Construct a ktxVulkanDeviceInfo object.

Records the device information, allocates a command buffer that will be used to transfer image data to the Vulkan device and retrieves the physical device memory properties for ease of use when allocating device memory for the images.

Pass a valid ktxVulkanDeviceInfo* to any Vulkan KTX image loading function to provide it with the information.

Parameters
Thispointer to the ktxVulkanDeviceInfo object to initialize.
physicalDevicehandle of the Vulkan physical device.
devicehandle of the Vulkan logical device.
queuehandle of the Vulkan queue.
cmdPoolhandle of the Vulkan command pool.
pAllocatorpointer to the allocator to use for the image memory. If NULL, the default allocator will be used.
Returns
KTX_SUCCESS on success, KTX_OUT_OF_MEMORY if a command buffer could not be allocated.
See also
ktxVulkanDeviceInfo_destruct()
Examples:
vkload.cpp.

◆ ktxVulkanDeviceInfo_Create()

ktxVulkanDeviceInfo * ktxVulkanDeviceInfo_Create ( VkPhysicalDevice  physicalDevice,
VkDevice  device,
VkQueue  queue,
VkCommandPool  cmdPool,
const VkAllocationCallbacks *  pAllocator 
)

Create a ktxVulkanDeviceInfo object.

Allocates CPU memory for a ktxVulkanDeviceInfo object then calls ktxVulkanDeviceInfo_construct(). See it for documentation of the parameters.

Returns
a pointer to the constructed ktxVulkanDeviceInfo.
See also
ktxVulkanDeviceInfo_construct(), ktxVulkanDeviceInfo_destroy()

◆ ktxVulkanDeviceInfo_Destroy()

void ktxVulkanDeviceInfo_Destroy ( ktxVulkanDeviceInfo This)

Destroy a ktxVulkanDeviceInfo object.

Calls ktxVulkanDeviceInfo_destruct() then frees the ktxVulkanDeviceInfo.

Parameters
Thispointer to the ktxVulkanDeviceInfo to destroy.

◆ ktxVulkanDeviceInfo_Destruct()

void ktxVulkanDeviceInfo_Destruct ( ktxVulkanDeviceInfo This)

Destruct a ktxVulkanDeviceInfo object.

Frees the command buffer.

Parameters
Thispointer to the ktxVulkanDeviceInfo to destruct.

◆ ktxVulkanTexture_Destruct()

void ktxVulkanTexture_Destruct ( ktxVulkanTexture vkTexture,
VkDevice  device,
const VkAllocationCallbacks *  pAllocator 
)

Destructor for the object returned when loading a texture image.

Frees the Vulkan resources created when the texture image was loaded.

Parameters
vkTexturepointer to the ktxVulkanTexture to be destructed.
devicehandle to the Vulkan logical device to which the texture was loaded.
pAllocatorpointer to the allocator used during loading.