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

Functions
ktxVulkanDeviceInfo *	ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_Create (VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks *pAllocator)
	Create a ktxVulkanDeviceInfo object. More...

ktxVulkanDeviceInfo *	ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_CreateEx (VkInstance instance, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks pAllocator, const ktxVulkanFunctions pFuncs)
	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...

KTX_error_code	ktxVulkanDeviceInfo::ktxVulkanDeviceInfo_ConstructEx (ktxVulkanDeviceInfo This, VkInstance instance, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks pAllocator, const ktxVulkanFunctions *pFunctions)
	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 ktxTexture1 object. More...

KTX_error_code	ktxTexture1::ktxTexture1_VkUploadEx (ktxTexture1 This, ktxVulkanDeviceInfo vdi, ktxVulkanTexture *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)
	Create a Vulkan image object from a ktxTexture1 object. More...

KTX_error_code	ktxTexture1::ktxTexture1_VkUpload (ktxTexture1 texture, ktxVulkanDeviceInfo vdi, ktxVulkanTexture *vkTexture)
	Create a Vulkan image object from a ktxTexture1 object. More...

KTX_error_code	ktxTexture2::ktxTexture2_VkUploadEx (ktxTexture2 This, ktxVulkanDeviceInfo vdi, ktxVulkanTexture *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)
	Create a Vulkan image object from a ktxTexture2 object. More...

KTX_error_code	ktxTexture2::ktxTexture2_VkUpload (ktxTexture2 This, ktxVulkanDeviceInfo vdi, ktxVulkanTexture *vkTexture)
	Create a Vulkan image object from a ktxTexture2 object. More...

VkFormat	ktxTexture1::ktxTexture1_GetVkFormat (ktxTexture1 *This)
	Return the VkFormat enum of a ktxTexture1 object. More...

VkFormat	ktxTexture2::ktxTexture2_GetVkFormat (ktxTexture2 *This)
	Return the VkFormat enum of a ktxTexture2 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

◆ ktxTexture1_GetVkFormat()

VkFormat ktxTexture1_GetVkFormat ( ktxTexture1 * This )

Return the VkFormat enum of a ktxTexture1 object.

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

◆ ktxTexture1_VkUpload()

KTX_error_code ktxTexture1_VkUpload	(	ktxTexture1 *	texture,
		ktxVulkanDeviceInfo *	vdi,
		ktxVulkanTexture *	vkTexture
	)

Create a Vulkan image object from a ktxTexture1 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.

◆ ktxTexture1_VkUploadEx()

KTX_error_code ktxTexture1_VkUploadEx	(	ktxTexture1 *	This,
		ktxVulkanDeviceInfo *	vdi,
		ktxVulkanTexture *	vkTexture,
		VkImageTiling	tiling,
		VkImageUsageFlags	usageFlags,
		VkImageLayout	finalLayout
	)

Create a Vulkan image object from a ktxTexture1 object.

This simplly calls ktxTexture_VkUploadEx.

Creates a VkImage with VkFormat etc. matching the KTX data and uploads the images. 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]	This	pointer to the ktxTexture from which to upload.
[in]	vdi	pointer to a ktxVulkanDeviceInfo structure providing information about the Vulkan device onto which to load the texture.
[in,out]	vkTexture	pointer to a ktxVulkanTexture structure into which the function writes information about the created VkImage.
[in]	tiling	type of tiling to use in the destination image on the Vulkan device.
[in]	usageFlags	a set of VkImageUsageFlags bits indicating the intended usage of the destination image.
[in]	finalLayout	a 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_VALUE	`This`, `vdi` or `vkTexture` is `NULL`.
KTX_INVALID_OPERATION	The ktxTexture contains neither images nor an active stream from which to read them.
KTX_INVALID_OPERATION	The combination of the ktxTexture's format, `tiling` and `usageFlags` is not supported by the physical device.
KTX_INVALID_OPERATION	Requested mipmap generation is not supported by the physical device for the combination of the ktxTexture's format and `tiling`.
KTX_INVALID_OPERATION	Number of mip levels or array layers exceeds the maximums supported for the ktxTexture's format and `tiling`.
KTX_OUT_OF_MEMORY	Sufficient memory could not be allocated on either the CPU or the Vulkan device.

◆ ktxTexture2_GetVkFormat()

VkFormat ktxTexture2_GetVkFormat ( ktxTexture2 * This )

Return the VkFormat enum of a ktxTexture2 object.

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

◆ ktxTexture2_VkUpload()

KTX_error_code ktxTexture2_VkUpload	(	ktxTexture2 *	This,
		ktxVulkanDeviceInfo *	vdi,
		ktxVulkanTexture *	vkTexture
	)

Create a Vulkan image object from a ktxTexture2 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: ktxTexture2_VkUploadEx() for details and use that for complete control.

◆ ktxTexture2_VkUploadEx()

KTX_error_code ktxTexture2_VkUploadEx	(	ktxTexture2 *	This,
		ktxVulkanDeviceInfo *	vdi,
		ktxVulkanTexture *	vkTexture,
		VkImageTiling	tiling,
		VkImageUsageFlags	usageFlags,
		VkImageLayout	finalLayout
	)

Create a Vulkan image object from a ktxTexture2 object.

This simplly calls ktxTexture_VkUploadEx.

Creates a VkImage with VkFormat etc. matching the KTX data and uploads the images. 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]	This	pointer to the ktxTexture from which to upload.
[in]	vdi	pointer to a ktxVulkanDeviceInfo structure providing information about the Vulkan device onto which to load the texture.
[in,out]	vkTexture	pointer to a ktxVulkanTexture structure into which the function writes information about the created VkImage.
[in]	tiling	type of tiling to use in the destination image on the Vulkan device.
[in]	usageFlags	a set of VkImageUsageFlags bits indicating the intended usage of the destination image.
[in]	finalLayout	a 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_VALUE	`This`, `vdi` or `vkTexture` is `NULL`.
KTX_INVALID_OPERATION	The ktxTexture contains neither images nor an active stream from which to read them.
KTX_INVALID_OPERATION	The combination of the ktxTexture's format, `tiling` and `usageFlags` is not supported by the physical device.
KTX_INVALID_OPERATION	Requested mipmap generation is not supported by the physical device for the combination of the ktxTexture's format and `tiling`.
KTX_INVALID_OPERATION	Number of mip levels or array layers exceeds the maximums supported for the ktxTexture's format and `tiling`.
KTX_OUT_OF_MEMORY	Sufficient memory could not be allocated on either the CPU or the Vulkan device.

◆ ktxTexture_GetVkFormat()

VkFormat ktxTexture_GetVkFormat ( ktxTexture * This )

Return the VkFormat enum of a ktxTexture object.

In ordert to ensure that the Vulkan uploader is not linked into an application unless explicitly called, this is not a virtual function. It determines the texture type then dispatches to the correct function.

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 ktxTexture1 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. 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]	This	pointer to the ktxTexture from which to upload.
[in]	vdi	pointer to a ktxVulkanDeviceInfo structure providing information about the Vulkan device onto which to load the texture.
[in,out]	vkTexture	pointer to a ktxVulkanTexture structure into which the function writes information about the created VkImage.
[in]	tiling	type of tiling to use in the destination image on the Vulkan device.
[in]	usageFlags	a set of VkImageUsageFlags bits indicating the intended usage of the destination image.
[in]	finalLayout	a 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_VALUE	`This`, `vdi` or `vkTexture` is `NULL`.
KTX_INVALID_OPERATION	The ktxTexture contains neither images nor an active stream from which to read them.
KTX_INVALID_OPERATION	The combination of the ktxTexture's format, `tiling` and `usageFlags` is not supported by the physical device.
KTX_INVALID_OPERATION	Requested mipmap generation is not supported by the physical device for the combination of the ktxTexture's format and `tiling`.
KTX_INVALID_OPERATION	Number of mip levels or array layers exceeds the maximums supported for the ktxTexture's format and `tiling`.
KTX_OUT_OF_MEMORY	Sufficient 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

This	pointer to the ktxVulkanDeviceInfo object to initialize.
physicalDevice	handle of the Vulkan physical device.
device	handle of the Vulkan logical device.
queue	handle of the Vulkan queue.
cmdPool	handle of the Vulkan command pool.
pAllocator	pointer 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_ConstructEx()

KTX_error_code ktxVulkanDeviceInfo_ConstructEx	(	ktxVulkanDeviceInfo *	This,
		VkInstance	instance,
		VkPhysicalDevice	physicalDevice,
		VkDevice	device,
		VkQueue	queue,
		VkCommandPool	cmdPool,
		const VkAllocationCallbacks *	pAllocator,
		const ktxVulkanFunctions *	pFunctions
	)

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

This	pointer to the ktxVulkanDeviceInfo object to initialize.
instance	handle of the Vulkan instance. If `VK_NULL_HANDLE`, which is not recommended, the function will attempt to initialize the instance-level functions via the platform's standard dynamic library symbol loading mechanisms.
physicalDevice	handle of the Vulkan physical device.
device	handle of the Vulkan logical device.
queue	handle of the Vulkan queue.
cmdPool	handle of the Vulkan command pool.
pAllocator	pointer to the allocator to use for the image memory. If NULL, the default allocator will be used.
pFunctions	pointer to the struct of functions to use for vulkan operations. Can be NULL in which case the function will retrieve the proc addresses itself.

Returns: KTX_SUCCESS on success, KTX_OUT_OF_MEMORY if a command buffer could not be allocated.

See also: ktxVulkanDeviceInfo_destruct()

◆ 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_CreateEx()

ktxVulkanDeviceInfo * ktxVulkanDeviceInfo_CreateEx	(	VkInstance	instance,
		VkPhysicalDevice	physicalDevice,
		VkDevice	device,
		VkQueue	queue,
		VkCommandPool	cmdPool,
		const VkAllocationCallbacks *	pAllocator,
		const ktxVulkanFunctions *	pFuncs
	)

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

This	pointer to the ktxVulkanDeviceInfo to destroy.

◆ ktxVulkanDeviceInfo_Destruct()

void ktxVulkanDeviceInfo_Destruct ( ktxVulkanDeviceInfo * This )

Destruct a ktxVulkanDeviceInfo object.

Frees the command buffer.

Parameters

This	pointer 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

vkTexture	pointer to the ktxVulkanTexture to be destructed.
device	handle to the Vulkan logical device to which the texture was loaded.
pAllocator	pointer to the allocator used during loading.

Functions

Detailed Description

Function Documentation

◆ ktxTexture1_GetVkFormat()

◆ ktxTexture1_VkUpload()

◆ ktxTexture1_VkUploadEx()

◆ ktxTexture2_GetVkFormat()

◆ ktxTexture2_VkUpload()

◆ ktxTexture2_VkUploadEx()

◆ ktxTexture_GetVkFormat()

◆ ktxTexture_VkUpload()

◆ ktxTexture_VkUploadEx()

◆ ktxVulkanDeviceInfo_Construct()

◆ ktxVulkanDeviceInfo_ConstructEx()

◆ ktxVulkanDeviceInfo_Create()

◆ ktxVulkanDeviceInfo_CreateEx()

◆ ktxVulkanDeviceInfo_Destroy()

◆ ktxVulkanDeviceInfo_Destruct()

◆ ktxVulkanTexture_Destruct()