Add ktx
This commit is contained in:
@@ -0,0 +1,580 @@
|
||||
.TH "ktx_vkloader" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_vkloader \- Vulkan Texture Image Loader
|
||||
.PP
|
||||
\- Create texture images on a Vulkan device\&.
|
||||
|
||||
.SH SYNOPSIS
|
||||
.br
|
||||
.PP
|
||||
.SS "Functions"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "\fBktxVulkanDeviceInfo\fP * \fBktxVulkanDeviceInfo_Create\fP (VkPhysicalDevice \fBphysicalDevice\fP, VkDevice \fBdevice\fP, VkQueue \fBqueue\fP, VkCommandPool \fBcmdPool\fP, const VkAllocationCallbacks *\fBpAllocator\fP)"
|
||||
.br
|
||||
.RI "Create a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBktxVulkanDeviceInfo\fP * \fBktxVulkanDeviceInfo_CreateEx\fP (VkInstance \fBinstance\fP, VkPhysicalDevice \fBphysicalDevice\fP, VkDevice \fBdevice\fP, VkQueue \fBqueue\fP, VkCommandPool \fBcmdPool\fP, const VkAllocationCallbacks *\fBpAllocator\fP, const \fBktxVulkanFunctions\fP *pFuncs)"
|
||||
.br
|
||||
.RI "Create a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxVulkanDeviceInfo_Construct\fP (\fBktxVulkanDeviceInfo\fP *This, VkPhysicalDevice \fBphysicalDevice\fP, VkDevice \fBdevice\fP, VkQueue \fBqueue\fP, VkCommandPool \fBcmdPool\fP, const VkAllocationCallbacks *\fBpAllocator\fP)"
|
||||
.br
|
||||
.RI "Construct a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxVulkanDeviceInfo_ConstructEx\fP (\fBktxVulkanDeviceInfo\fP *This, VkInstance \fBinstance\fP, VkPhysicalDevice \fBphysicalDevice\fP, VkDevice \fBdevice\fP, VkQueue \fBqueue\fP, VkCommandPool \fBcmdPool\fP, const VkAllocationCallbacks *\fBpAllocator\fP, const \fBktxVulkanFunctions\fP *pFunctions)"
|
||||
.br
|
||||
.RI "Construct a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "void \fBktxVulkanDeviceInfo_Destruct\fP (\fBktxVulkanDeviceInfo\fP *This)"
|
||||
.br
|
||||
.RI "Destruct a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "void \fBktxVulkanDeviceInfo_Destroy\fP (\fBktxVulkanDeviceInfo\fP *This)"
|
||||
.br
|
||||
.RI "Destroy a \fBktxVulkanDeviceInfo\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture_VkUploadEx_WithSuballocator\fP (\fBktxTexture\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP *subAllocatorCallbacks)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture_VkUploadEx\fP (\fBktxTexture\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture_VkUpload\fP (\fBktxTexture\fP *texture, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture1_VkUploadEx_WithSuballocator\fP (\fBktxTexture1\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP *subAllocatorCallbacks)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture1\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture1_VkUploadEx\fP (\fBktxTexture1\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture1\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture1_VkUpload\fP (\fBktxTexture1\fP *texture, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture1\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture2_VkUploadEx_WithSuballocator\fP (\fBktxTexture2\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP *subAllocatorCallbacks)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture2\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture2_VkUploadEx\fP (\fBktxTexture2\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture2\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBKTX_error_code\fP \fBktxTexture2_VkUpload\fP (\fBktxTexture2\fP *This, \fBktxVulkanDeviceInfo\fP *vdi, \fBktxVulkanTexture\fP *vkTexture)"
|
||||
.br
|
||||
.RI "Create a Vulkan image object from a \fBktxTexture2\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "VkFormat \fBktxTexture1_GetVkFormat\fP (\fBktxTexture1\fP *This)"
|
||||
.br
|
||||
.RI "Return the VkFormat enum of a \fBktxTexture1\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "VkFormat \fBktxTexture2_GetVkFormat\fP (\fBktxTexture2\fP *This)"
|
||||
.br
|
||||
.RI "Return the VkFormat enum of a \fBktxTexture2\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "VkFormat \fBktxTexture_GetVkFormat\fP (\fBktxTexture\fP *This)"
|
||||
.br
|
||||
.RI "Return the VkFormat enum of a \fBktxTexture\fP object\&. "
|
||||
.ti -1c
|
||||
.RI "\fBktx_error_code_e\fP \fBktxVulkanTexture_Destruct_WithSuballocator\fP (\fBktxVulkanTexture\fP *vkTexture, VkDevice device, const VkAllocationCallbacks *pAllocator, \fBktxVulkanTexture_subAllocatorCallbacks\fP *subAllocatorCallbacks)"
|
||||
.br
|
||||
.RI "Destructor for the object returned when loading a texture image\&. "
|
||||
.ti -1c
|
||||
.RI "void \fBktxVulkanTexture_Destruct\fP (\fBktxVulkanTexture\fP *vkTexture, VkDevice device, const VkAllocationCallbacks *pAllocator)"
|
||||
.br
|
||||
.RI "Destructor for the object returned when loading a texture image\&. "
|
||||
.in -1c
|
||||
.SH "Detailed Description"
|
||||
.PP
|
||||
Create texture images on a Vulkan device\&.
|
||||
|
||||
|
||||
.SH "Function Documentation"
|
||||
.PP
|
||||
.SS "VkFormat ktxTexture1_GetVkFormat (\fBktxTexture1\fP * This)"
|
||||
|
||||
.PP
|
||||
Return the VkFormat enum of a \fBktxTexture1\fP object\&.
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
The VkFormat of the texture object\&. May return VK_FORMAT_UNDEFINED if there is no mapping from the GL internalformat and format\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBKTX_error_code\fP ktxTexture1_VkUpload (\fBktxTexture1\fP * texture, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture1\fP object\&. Calls \fBktxTexture_VkUploadEx()\fP with the most commonly used options: \fRVK_IMAGE_TILING_OPTIMAL\fP, \fRVK_IMAGE_USAGE_SAMPLED_BIT\fP and \fRVK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL\fP\&. Use that for complete control\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture1_VkUploadEx (\fBktxTexture1\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture1\fP object\&. This simply calls \fBktxTexture_VkUploadEx()\fP\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture1_VkUploadEx_WithSuballocator (\fBktxTexture1\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP * subAllocatorCallbacks)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture1\fP object\&. This simply calls \fBktxTexture_VkUploadEx_WithSuballocator()\fP
|
||||
|
||||
.PP
|
||||
Creates a VkImage with \fRVkFormat\fP etc\&. matching the KTX data and uploads the images\&. Mipmaps will be generated if the \fR\fBktxTexture\fP's\fP \fRgenerateMipmaps\fP flag is set\&. Returns the handles of the created objects and information about the texture in the \fR\fBktxVulkanTexture\fP\fP pointed at by \fRvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
The created VkImage will have \fRVK_SHARING_MODE_EXCLUSIVE\fP set thus the resulting image will be usable only with queues of the same family as the \fRqueue\fP in the \fBktxVulkanDeviceInfo\fP pointed to by \fIvdi\fP\&.
|
||||
|
||||
.PP
|
||||
\fRusageFlags\fP and thus acceptable usage of the created image may be augmented as follows:
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT\fP if \fRtiling\fP is \fRVK_IMAGE_TILING_OPTIMAL\fP
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT\fP if \fRgenerateMipmaps\fP is set in the \fR\fBktxTexture\fP\fP\&.
|
||||
.PP
|
||||
|
||||
.PP
|
||||
Most Vulkan implementations support \fRVK_IMAGE_TILING_LINEAR\fP only for a very limited number of formats and features\&. Generally \fRVK_IMAGE_TILING_OPTIMAL\fP is preferred\&. The latter requires a staging buffer so will use more memory during loading\&.
|
||||
|
||||
.PP
|
||||
If a pointer to a set of suballocator callbacks is provided, they will be used instead of manual allocation of VkDeviceMemory\&. A 64 bit uint that references the suballocated page(s) is returned on memory procurement and saved in the \fRallocationId\fP field of the structure pointed to by \fIvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxTexture\fP from which to upload\&.
|
||||
.br
|
||||
\fIvdi\fP pointer to a \fBktxVulkanDeviceInfo\fP structure providing information about the Vulkan device onto which to load the texture\&.
|
||||
.br
|
||||
\fIvkTexture\fP pointer to a \fBktxVulkanTexture\fP structure into which the function writes information about the created VkImage\&.
|
||||
.br
|
||||
\fItiling\fP type of tiling to use in the destination image on the Vulkan device\&.
|
||||
.br
|
||||
\fIusageFlags\fP a set of VkImageUsageFlags bits indicating the intended usage of the destination image\&.
|
||||
.br
|
||||
\fIfinalLayout\fP a VkImageLayout value indicating the desired final layout of the created image\&.
|
||||
.br
|
||||
\fIsubAllocatorCallbacks\fP pointer to a set of suballocator callbacks that wrap around suballocator calls: alloc, bindbuffer, bindimage, map, unmap and free\&. They use a uint64_t stored in the \fRallocationId\fP field of the structure pointed at by \fIvkTexture\fP to reference allocated page(s)\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, other KTX_* enum values on error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBExceptions\fP
|
||||
.RS 4
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP An incomplete set of callbacks are provided in subAllocatorCallbacks\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP, \fRvdi\fP or \fRvkTexture\fP is \fRNULL\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains neither images nor an active stream from which to read them\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The combination of the \fBktxTexture\fP's format, \fRtiling\fP and \fRusageFlags\fP is not supported by the physical device\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Requested mipmap generation is not supported by the physical device for the combination of the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Number of mip levels or array layers exceeds the maximums supported for the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Sufficient memory could not be allocated on either the CPU or the Vulkan device\&.
|
||||
.br
|
||||
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP Attempting to sparsely bind KTX textures for the time being will report this error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Construct()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "VkFormat ktxTexture2_GetVkFormat (\fBktxTexture2\fP * This)"
|
||||
|
||||
.PP
|
||||
Return the VkFormat enum of a \fBktxTexture2\fP object\&.
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
The VkFormat of the texture object\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBKTX_error_code\fP ktxTexture2_VkUpload (\fBktxTexture2\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture2\fP object\&. Calls \fBktxTexture_VkUploadEx()\fP with the most commonly used options: \fRVK_IMAGE_TILING_OPTIMAL\fP, \fRVK_IMAGE_USAGE_SAMPLED_BIT\fP and \fRVK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL\fP\&. Use that for complete control\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture2_VkUploadEx (\fBktxTexture2\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture2\fP object\&. This simply calls \fBktxTexture_VkUploadEx()\fP\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture2_VkUploadEx_WithSuballocator (\fBktxTexture2\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP * subAllocatorCallbacks)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture2\fP object\&. This simplly calls \fBktxTexture_VkUploadEx_WithSuballocator()\fP\&.
|
||||
|
||||
.PP
|
||||
Creates a VkImage with \fRVkFormat\fP etc\&. matching the KTX data and uploads the images\&. Mipmaps will be generated if the \fR\fBktxTexture\fP's\fP \fRgenerateMipmaps\fP flag is set\&. Returns the handles of the created objects and information about the texture in the \fR\fBktxVulkanTexture\fP\fP pointed at by \fRvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
The created VkImage will have \fRVK_SHARING_MODE_EXCLUSIVE\fP set thus the resulting image will be usable only with queues of the same family as the \fRqueue\fP in the \fBktxVulkanDeviceInfo\fP pointed to by \fIvdi\fP\&.
|
||||
|
||||
.PP
|
||||
\fRusageFlags\fP and thus acceptable usage of the created image may be augmented as follows:
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT\fP if \fRtiling\fP is \fRVK_IMAGE_TILING_OPTIMAL\fP
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT\fP if \fRgenerateMipmaps\fP is set in the \fR\fBktxTexture\fP\fP\&.
|
||||
.PP
|
||||
|
||||
.PP
|
||||
Most Vulkan implementations support \fRVK_IMAGE_TILING_LINEAR\fP only for a very limited number of formats and features\&. Generally \fRVK_IMAGE_TILING_OPTIMAL\fP is preferred\&. The latter requires a staging buffer so will use more memory during loading\&.
|
||||
|
||||
.PP
|
||||
If a pointer to a set of suballocator callbacks is provided, they will be used instead of manual allocation of VkDeviceMemory\&. A 64 bit uint that references the suballocated page(s) is returned on memory procurement and saved in the \fRallocationId\fP field of the structure pointed to by \fIvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxTexture\fP from which to upload\&.
|
||||
.br
|
||||
\fIvdi\fP pointer to a \fBktxVulkanDeviceInfo\fP structure providing information about the Vulkan device onto which to load the texture\&.
|
||||
.br
|
||||
\fIvkTexture\fP pointer to a \fBktxVulkanTexture\fP structure into which the function writes information about the created VkImage\&.
|
||||
.br
|
||||
\fItiling\fP type of tiling to use in the destination image on the Vulkan device\&.
|
||||
.br
|
||||
\fIusageFlags\fP a set of VkImageUsageFlags bits indicating the intended usage of the destination image\&.
|
||||
.br
|
||||
\fIfinalLayout\fP a VkImageLayout value indicating the desired final layout of the created image\&.
|
||||
.br
|
||||
\fIsubAllocatorCallbacks\fP pointer to a set of suballocator callbacks that wrap around suballocator calls: alloc, bindbuffer, bindimage, map, unmap and free\&. They use a uint64_t stored in the \fRallocationId\fP field of the structure pointed at by \fIvkTexture\fP to reference allocated page(s)\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, other KTX_* enum values on error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBExceptions\fP
|
||||
.RS 4
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP An incomplete set of callbacks are provided in subAllocatorCallbacks\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP, \fRvdi\fP or \fRvkTexture\fP is \fRNULL\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains neither images nor an active stream from which to read them\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The combination of the \fBktxTexture\fP's format, \fRtiling\fP and \fRusageFlags\fP is not supported by the physical device\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Requested mipmap generation is not supported by the physical device for the combination of the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Number of mip levels or array layers exceeds the maximums supported for the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Sufficient memory could not be allocated on either the CPU or the Vulkan device\&.
|
||||
.br
|
||||
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP Attempting to sparsely bind KTX textures for the time being will report this error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Construct()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "VkFormat ktxTexture_GetVkFormat (\fBktxTexture\fP * This)"
|
||||
|
||||
.PP
|
||||
Return the VkFormat enum of a \fBktxTexture\fP 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\&.
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxTexture1_GetVkFormat()\fP
|
||||
|
||||
.PP
|
||||
\fBktxTexture2_GetVkFormat()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBKTX_error_code\fP ktxTexture_VkUpload (\fBktxTexture\fP * texture, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture\fP object\&. Calls \fBktxTexture_VkUploadEx()\fP with the most commonly used options: \fRVK_IMAGE_TILING_OPTIMAL\fP, \fRVK_IMAGE_USAGE_SAMPLED_BIT\fP and \fRVK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL\fP\&. Use that for complete control\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture_VkUploadEx (\fBktxTexture\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture\fP object\&. Calls \fBktxTexture_VkUploadEx_WithSuballocator()\fP with no supplied suballocator callbacks\&. Use that for complete control\&.
|
||||
.SS "\fBKTX_error_code\fP ktxTexture_VkUploadEx_WithSuballocator (\fBktxTexture\fP * This, \fBktxVulkanDeviceInfo\fP * vdi, \fBktxVulkanTexture\fP * vkTexture, VkImageTiling tiling, VkImageUsageFlags usageFlags, VkImageLayout finalLayout, \fBktxVulkanTexture_subAllocatorCallbacks\fP * subAllocatorCallbacks)"
|
||||
|
||||
.PP
|
||||
Create a Vulkan image object from a \fBktxTexture\fP object\&. Creates a VkImage with \fRVkFormat\fP etc\&. matching the KTX data and uploads the images\&. Mipmaps will be generated if the \fR\fBktxTexture\fP's\fP \fRgenerateMipmaps\fP flag is set\&. Returns the handles of the created objects and information about the texture in the \fR\fBktxVulkanTexture\fP\fP pointed at by \fRvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
The created VkImage will have \fRVK_SHARING_MODE_EXCLUSIVE\fP set thus the resulting image will be usable only with queues of the same family as the \fRqueue\fP in the \fBktxVulkanDeviceInfo\fP pointed to by \fIvdi\fP\&.
|
||||
|
||||
.PP
|
||||
\fRusageFlags\fP and thus acceptable usage of the created image may be augmented as follows:
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT\fP if \fRtiling\fP is \fRVK_IMAGE_TILING_OPTIMAL\fP
|
||||
.IP "\(bu" 2
|
||||
with \fRVK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT\fP if \fRgenerateMipmaps\fP is set in the \fR\fBktxTexture\fP\fP\&.
|
||||
.PP
|
||||
|
||||
.PP
|
||||
Most Vulkan implementations support \fRVK_IMAGE_TILING_LINEAR\fP only for a very limited number of formats and features\&. Generally \fRVK_IMAGE_TILING_OPTIMAL\fP is preferred\&. The latter requires a staging buffer so will use more memory during loading\&.
|
||||
|
||||
.PP
|
||||
If a pointer to a set of suballocator callbacks is provided, they will be used instead of manual allocation of VkDeviceMemory\&. A 64 bit uint that references the suballocated page(s) is returned on memory procurement and saved in the \fRallocationId\fP field of the structure pointed to by \fIvkTexture\fP\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxTexture\fP from which to upload\&.
|
||||
.br
|
||||
\fIvdi\fP pointer to a \fBktxVulkanDeviceInfo\fP structure providing information about the Vulkan device onto which to load the texture\&.
|
||||
.br
|
||||
\fIvkTexture\fP pointer to a \fBktxVulkanTexture\fP structure into which the function writes information about the created VkImage\&.
|
||||
.br
|
||||
\fItiling\fP type of tiling to use in the destination image on the Vulkan device\&.
|
||||
.br
|
||||
\fIusageFlags\fP a set of VkImageUsageFlags bits indicating the intended usage of the destination image\&.
|
||||
.br
|
||||
\fIfinalLayout\fP a VkImageLayout value indicating the desired final layout of the created image\&.
|
||||
.br
|
||||
\fIsubAllocatorCallbacks\fP pointer to a set of suballocator callbacks that wrap around suballocator calls: alloc, bindbuffer, bindimage, map, unmap and free\&. They use a uint64_t stored in the \fRallocationId\fP field of the structure pointed at by \fIvkTexture\fP to reference allocated page(s)\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, other KTX_* enum values on error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBExceptions\fP
|
||||
.RS 4
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP An incomplete set of callbacks are provided in subAllocatorCallbacks\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP, \fRvdi\fP or \fRvkTexture\fP is \fRNULL\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains neither images nor an active stream from which to read them\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP The combination of the \fBktxTexture\fP's format, \fRtiling\fP and \fRusageFlags\fP is not supported by the physical device\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Requested mipmap generation is not supported by the physical device for the combination of the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_INVALID_OPERATION\fP\fP Number of mip levels or array layers exceeds the maximums supported for the \fBktxTexture\fP's format and \fRtiling\fP\&.
|
||||
.br
|
||||
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Sufficient memory could not be allocated on either the CPU or the Vulkan device\&.
|
||||
.br
|
||||
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP Attempting to sparsely bind KTX textures for the time being will report this error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Construct()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBKTX_error_code\fP ktxVulkanDeviceInfo_Construct (\fBktxVulkanDeviceInfo\fP * This, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks * pAllocator)"
|
||||
|
||||
.PP
|
||||
Construct a \fBktxVulkanDeviceInfo\fP 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\&.
|
||||
|
||||
.PP
|
||||
If \fRVK_IMAGE_TILING_OPTIMAL\fP will be passed to ktxTexture_VkUploadEx(), the family of the \fIqueue\fP parameter must support transfers\&. This is true if any of \fRVK_QUEUE_GRAPHICS_BIT\fP, \fRVK_QUEUE_COMPUTE_BIT\fP or \fRVK_QUEUE_TRANSFER_BIT\fP is set in the \fRqueueFlags\fP property of the queue's \fRVkQueueFamilyProperties\fP\&. If protected memory is being used, i\&.e \fRqueueFlags\fP has the \fRVK_QUEUE_PROTECTED_BIT\fP set, then \fRVK_IMAGE_TILING_OPTIMAL\fP must be passed to ktxTexture_VkUploadEx()\&.
|
||||
|
||||
.PP
|
||||
VkImages created in \fBktxTexture_VkUploadEx()\fP will have \fRVK_SHARING_MODE_EXCLUSIVE\fP set\&. Thus the resulting image will be usable only with queues of the same family as \fIqueue\fP\&.
|
||||
|
||||
.PP
|
||||
Pass a valid ktxVulkanDeviceInfo* to any Vulkan KTX image loading function to provide it with the information\&.
|
||||
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, other KTX_* enum values on error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBExceptions\fP
|
||||
.RS 4
|
||||
\fI\fBKTX_NOT_FOUND\fP\fP A dynamically loaded Vulkan function required by the loader was not found\&.
|
||||
.br
|
||||
\fI\fBKTX_OUT_OF_MEMORY\fP\fP A command buffer could not be allocated\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Destruct()\fP
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxVulkanDeviceInfo\fP object to initialize\&.
|
||||
.br
|
||||
\fI\fBphysicalDevice\fP\fP handle of the Vulkan physical device\&.
|
||||
.br
|
||||
\fI\fBdevice\fP\fP handle of the Vulkan logical device\&.
|
||||
.br
|
||||
\fI\fBqueue\fP\fP handle of the Vulkan queue\&.
|
||||
.br
|
||||
\fI\fBcmdPool\fP\fP handle of the Vulkan command pool\&.
|
||||
.br
|
||||
\fI\fBpAllocator\fP\fP pointer to the allocator to use for the image memory\&. If NULL, the default allocator will be used\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBKTX_error_code\fP ktxVulkanDeviceInfo_ConstructEx (\fBktxVulkanDeviceInfo\fP * This, VkInstance instance, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks * pAllocator, const \fBktxVulkanFunctions\fP * pFunctions)"
|
||||
|
||||
.PP
|
||||
Construct a \fBktxVulkanDeviceInfo\fP 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\&.
|
||||
|
||||
.PP
|
||||
If \fRVK_IMAGE_TILING_OPTIMAL\fP will be passed to ktxTexture_VkUploadEx(), the family of the \fIqueue\fP parameter must support transfers\&. This is true if any of \fRVK_QUEUE_GRAPHICS_BIT\fP, \fRVK_QUEUE_COMPUTE_BIT\fP or \fRVK_QUEUE_TRANSFER_BIT\fP is set in the \fRqueueFlags\fP property of the queue's \fRVkQueueFamilyProperties\fP\&. If protected memory is being used, i\&.e \fRqueueFlags\fP has the \fRVK_QUEUE_PROTECTED_BIT\fP set, then \fRVK_IMAGE_TILING_OPTIMAL\fP must be passed to ktxTexture_VkUploadEx()\&.
|
||||
|
||||
.PP
|
||||
VkImages created in \fBktxTexture_VkUploadEx()\fP will have \fRVK_SHARING_MODE_EXCLUSIVE\fP set\&. Thus the resulting image will be usable only with queues of the same family as \fIqueue\fP\&.
|
||||
|
||||
.PP
|
||||
Pass a valid ktxVulkanDeviceInfo* to any Vulkan KTX image loading function to provide it with the information\&.
|
||||
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, other KTX_* enum values on error\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBExceptions\fP
|
||||
.RS 4
|
||||
\fI\fBKTX_NOT_FOUND\fP\fP A dynamically loaded Vulkan function required by the loader was not found\&.
|
||||
.br
|
||||
\fI\fBKTX_OUT_OF_MEMORY\fP\fP A command buffer could not be allocated\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Destruct()\fP
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxVulkanDeviceInfo\fP object to initialize\&.
|
||||
.br
|
||||
\fI\fBphysicalDevice\fP\fP handle of the Vulkan physical device\&.
|
||||
.br
|
||||
\fI\fBdevice\fP\fP handle of the Vulkan logical device\&.
|
||||
.br
|
||||
\fI\fBqueue\fP\fP handle of the Vulkan queue\&.
|
||||
.br
|
||||
\fI\fBcmdPool\fP\fP handle of the Vulkan command pool\&.
|
||||
.br
|
||||
\fI\fBpAllocator\fP\fP pointer to the allocator to use for the image memory\&. If NULL, the default allocator will be used\&.
|
||||
.br
|
||||
\fI\fBinstance\fP\fP handle of the Vulkan instance\&. If \fRVK_NULL_HANDLE\fP, which is not recommended, the function will attempt to initialize the instance-level functions via the platform's standard dynamic library symbol loading mechanisms\&.
|
||||
.br
|
||||
\fIpFunctions\fP 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\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBktxVulkanDeviceInfo\fP * ktxVulkanDeviceInfo_Create (VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks * pAllocator)"
|
||||
|
||||
.PP
|
||||
Create a \fBktxVulkanDeviceInfo\fP object\&. Allocates CPU memory for a \fBktxVulkanDeviceInfo\fP object then calls \fBktxVulkanDeviceInfo_Construct()\fP\&. See it for documentation of the parameters\&.
|
||||
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
a pointer to the constructed \fBktxVulkanDeviceInfo\fP\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Construct()\fP
|
||||
|
||||
.PP
|
||||
\fBktxVulkanDeviceInfo_Destroy()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBktxVulkanDeviceInfo\fP * ktxVulkanDeviceInfo_CreateEx (VkInstance instance, VkPhysicalDevice physicalDevice, VkDevice device, VkQueue queue, VkCommandPool cmdPool, const VkAllocationCallbacks * pAllocator, const \fBktxVulkanFunctions\fP * pFuncs)"
|
||||
|
||||
.PP
|
||||
Create a \fBktxVulkanDeviceInfo\fP object\&. Allocates CPU memory for a \fBktxVulkanDeviceInfo\fP object then calls \fBktxVulkanDeviceInfo_Construct()\fP\&. See it for documentation of the parameters\&.
|
||||
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
a pointer to the constructed \fBktxVulkanDeviceInfo\fP\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanDeviceInfo_Construct()\fP
|
||||
|
||||
.PP
|
||||
\fBktxVulkanDeviceInfo_Destroy()\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "void ktxVulkanDeviceInfo_Destroy (\fBktxVulkanDeviceInfo\fP * This)"
|
||||
|
||||
.PP
|
||||
Destroy a \fBktxVulkanDeviceInfo\fP object\&. Calls \fBktxVulkanDeviceInfo_Destruct()\fP then frees the \fBktxVulkanDeviceInfo\fP\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxVulkanDeviceInfo\fP to destroy\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "void ktxVulkanDeviceInfo_Destruct (\fBktxVulkanDeviceInfo\fP * This)"
|
||||
|
||||
.PP
|
||||
Destruct a \fBktxVulkanDeviceInfo\fP object\&. Frees the command buffer\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIThis\fP pointer to the \fBktxVulkanDeviceInfo\fP to destruct\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "void ktxVulkanTexture_Destruct (\fBktxVulkanTexture\fP * vkTexture, VkDevice device, const VkAllocationCallbacks * pAllocator)"
|
||||
|
||||
.PP
|
||||
Destructor for the object returned when loading a texture image\&. Calls \fBktxVulkanTexture_Destruct_WithSuballocator()\fP without a set of suballocator callbacks\&.
|
||||
|
||||
.PP
|
||||
\fBSee also\fP
|
||||
.RS 4
|
||||
\fBktxVulkanTexture_Destruct_WithSuballocator()\fP for details and use that for complete control\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBktx_error_code_e\fP ktxVulkanTexture_Destruct_WithSuballocator (\fBktxVulkanTexture\fP * vkTexture, VkDevice device, const VkAllocationCallbacks * pAllocator, \fBktxVulkanTexture_subAllocatorCallbacks\fP * subAllocatorCallbacks)"
|
||||
|
||||
.PP
|
||||
Destructor for the object returned when loading a texture image\&. Frees the Vulkan resources created when the texture image was loaded\&. If a complete set of suballocator callbacks are provided, it will use the free call from those instead\&.
|
||||
|
||||
.PP
|
||||
\fBParameters\fP
|
||||
.RS 4
|
||||
\fIvkTexture\fP pointer to the \fBktxVulkanTexture\fP to be destructed\&.
|
||||
.br
|
||||
\fIdevice\fP handle to the Vulkan logical device to which the texture was loaded\&.
|
||||
.br
|
||||
\fIpAllocator\fP pointer to the allocator used during loading\&.
|
||||
.br
|
||||
\fIsubAllocatorCallbacks\fP pointer to a structure of suballocator callbacks\&. Pass NULL if a suballocator was not used\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns\fP
|
||||
.RS 4
|
||||
KTX_SUCCESS on success, KTX_INVALID_VALUE if the supplied subAllocatorCallbacks structure is incomplete\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SH "Author"
|
||||
.PP
|
||||
Generated automatically by Doxygen for libktx Reference from the source code\&.
|
||||
Reference in New Issue
Block a user