initial commit, 4.5 stable

thirdparty/libktx/include/ktxvulkan.h

@@ -0,0 +1,299 @@
+/* -*- tab-width: 4; -*- */
+/* vi: set sw=2 ts=4 expandtab: */
+
+#ifndef KTX_H_C54B42AEE39611E68E1E4FF8C51D1C66
+#define KTX_H_C54B42AEE39611E68E1E4FF8C51D1C66
+
+/*
+ * Copyright 2017-2020 The Khronos Group, Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @internal
+ * @file
+ * @~English
+ *
+ * @brief Declares the public functions and structures of the
+ *        KTX Vulkan texture loading API.
+ *
+ * A separate header file is used to avoid extra dependencies for those not
+ * using Vulkan. The nature of the Vulkan API, rampant structures and enums,
+ * means that vulkan.h must be included @e before including this file. The
+ * alternative is duplicating unattractively large parts of it.
+ *
+ * @author Mark Callow, Edgewise Consulting
+ */
+
+#include <ktx.h>
+
+#if 0
+/* Avoid Vulkan include file */
+#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
+
+#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
+        #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
+#else
+        #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
+#endif
+
+VK_DEFINE_HANDLE(VkPhysicalDevice)
+VK_DEFINE_HANDLE(VkDevice)
+VK_DEFINE_HANDLE(VkQueue)
+VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)
+VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)
+VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)
+VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)
+VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @struct ktxVulkanFunctions
+ * @~English
+ * @brief Struct for applications to pass Vulkan function pointers to the
+ *        ktxTexture_VkUpload functions via a ktxVulkanDeviceInfo struct.
+ *
+ * @c vkGetInstanceProcAddr and @c vkGetDeviceProcAddr should be set, others
+ * are optional.
+ */
+typedef struct ktxVulkanFunctions {
+    // These are functions pointers we need to perform our vulkan duties.
+    PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr;
+    PFN_vkGetDeviceProcAddr vkGetDeviceProcAddr;
+
+    // These we optionally specify
+    PFN_vkAllocateCommandBuffers vkAllocateCommandBuffers;
+    PFN_vkAllocateMemory vkAllocateMemory;
+    PFN_vkBeginCommandBuffer vkBeginCommandBuffer;
+    PFN_vkBindBufferMemory vkBindBufferMemory;
+    PFN_vkBindImageMemory vkBindImageMemory;
+    PFN_vkCmdBlitImage vkCmdBlitImage;
+    PFN_vkCmdCopyBufferToImage vkCmdCopyBufferToImage;
+    PFN_vkCmdPipelineBarrier vkCmdPipelineBarrier;
+    PFN_vkCreateImage vkCreateImage;
+    PFN_vkDestroyImage vkDestroyImage;
+    PFN_vkCreateBuffer vkCreateBuffer;
+    PFN_vkDestroyBuffer vkDestroyBuffer;
+    PFN_vkCreateFence vkCreateFence;
+    PFN_vkDestroyFence vkDestroyFence;
+    PFN_vkEndCommandBuffer vkEndCommandBuffer;
+    PFN_vkFreeCommandBuffers vkFreeCommandBuffers;
+    PFN_vkFreeMemory vkFreeMemory;
+    PFN_vkGetBufferMemoryRequirements vkGetBufferMemoryRequirements;
+    PFN_vkGetImageMemoryRequirements vkGetImageMemoryRequirements;
+    PFN_vkGetImageSubresourceLayout vkGetImageSubresourceLayout;
+    PFN_vkGetPhysicalDeviceImageFormatProperties vkGetPhysicalDeviceImageFormatProperties;
+    PFN_vkGetPhysicalDeviceFormatProperties vkGetPhysicalDeviceFormatProperties;
+    PFN_vkGetPhysicalDeviceMemoryProperties vkGetPhysicalDeviceMemoryProperties;
+    PFN_vkMapMemory vkMapMemory;
+    PFN_vkQueueSubmit vkQueueSubmit;
+    PFN_vkQueueWaitIdle vkQueueWaitIdle;
+    PFN_vkUnmapMemory vkUnmapMemory;
+    PFN_vkWaitForFences vkWaitForFences;
+} ktxVulkanFunctions;
+
+/**
+ * @class ktxVulkanTexture
+ * @~English
+ * @brief Struct for returning information about the Vulkan texture image
+ *        created by the ktxTexture_VkUpload* functions.
+ *
+ * Creation of these objects is internal to the upload functions.
+ */
+typedef struct ktxVulkanTexture
+{
+    PFN_vkDestroyImage vkDestroyImage; /*!< Pointer to vkDestroyImage function */
+    PFN_vkFreeMemory vkFreeMemory; /*!< Pointer to vkFreeMemory function */
+
+    VkImage image; /*!< Handle to the Vulkan image created by the loader. */
+    VkFormat imageFormat;     /*!< Format of the image data. */
+    VkImageLayout imageLayout; /*!< Layout of the created image. Has the same
+                                    value as @p layout parameter passed to the
+                                    loader. */
+    VkDeviceMemory deviceMemory; /*!< The memory (sub)allocation for the
+                                  image on the Vulkan device. Will not be
+                                  used with suballocators.*/
+    VkImageViewType viewType; /*!< ViewType corresponding to @p image. Reflects
+                                   the dimensionality, cubeness and arrayness
+                                   of the image. */
+    uint32_t width; /*!< The width of the image. */
+    uint32_t height; /*!< The height of the image. */
+    uint32_t depth; /*!< The depth of the image. */
+    uint32_t levelCount; /*!< The number of MIP levels in the image. */
+    uint32_t layerCount; /*!< The number of array layers in the image. */
+    uint64_t allocationId; /*!< An id referencing suballocation(s). */
+} ktxVulkanTexture;
+
+typedef uint64_t(*ktxVulkanTexture_subAllocatorAllocMemFuncPtr)(VkMemoryAllocateInfo* allocInfo, VkMemoryRequirements* memReq, uint64_t* pageCount);
+typedef VkResult(*ktxVulkanTexture_subAllocatorBindBufferFuncPtr)(VkBuffer buffer, uint64_t allocId);
+typedef VkResult(*ktxVulkanTexture_subAllocatorBindImageFuncPtr)(VkImage image, uint64_t allocId);
+typedef VkResult(*ktxVulkanTexture_subAllocatorMemoryMapFuncPtr)(uint64_t allocId, uint64_t pageNumber, VkDeviceSize *mapLength, void** dataPtr);
+typedef void (*ktxVulkanTexture_subAllocatorMemoryUnmapFuncPtr)(uint64_t allocId, uint64_t pageNumber);
+typedef void (*ktxVulkanTexture_subAllocatorFreeMemFuncPtr)(uint64_t allocId);
+/**
+ * @class ktxVulkanTexture_subAllocatorCallbacks
+ * @~English
+ * @brief Struct that contains all callbacks necessary for suballocation.
+ *
+ * These pointers must all be provided for upload or destroy to occur using suballocator callbacks.
+ */
+typedef struct {
+    ktxVulkanTexture_subAllocatorAllocMemFuncPtr allocMemFuncPtr; /*!< Pointer to the memory procurement function. Can suballocate one or more pages. */
+    ktxVulkanTexture_subAllocatorBindBufferFuncPtr bindBufferFuncPtr; /*!< Pointer to bind-buffer-to-suballocation(s) function. */
+    ktxVulkanTexture_subAllocatorBindImageFuncPtr bindImageFuncPtr; /*!< Pointer to bind-image-to-suballocation(s) function. */
+    ktxVulkanTexture_subAllocatorMemoryMapFuncPtr memoryMapFuncPtr; /*!< Pointer to function for mapping the memory of a specific page. */
+    ktxVulkanTexture_subAllocatorMemoryUnmapFuncPtr memoryUnmapFuncPtr; /*!< Pointer to function for unmapping the memory of a specific page. */
+    ktxVulkanTexture_subAllocatorFreeMemFuncPtr freeMemFuncPtr; /*!< Pointer to the free procurement function. */
+} ktxVulkanTexture_subAllocatorCallbacks;
+
+KTX_API ktx_error_code_e KTX_APIENTRY
+ktxVulkanTexture_Destruct_WithSuballocator(ktxVulkanTexture* This, VkDevice device,
+                                           const VkAllocationCallbacks* pAllocator,
+                                           ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks);
+
+KTX_API void KTX_APIENTRY
+ktxVulkanTexture_Destruct(ktxVulkanTexture* This, VkDevice device,
+                          const VkAllocationCallbacks* pAllocator);
+
+
+/**
+ * @class ktxVulkanDeviceInfo
+ * @~English
+ * @brief Struct for passing information about the Vulkan device on which
+ *        to create images to the texture image loading functions.
+ *
+ * Avoids passing a large number of parameters to each loading function.
+ * Use of ktxVulkanDeviceInfo_create() or ktxVulkanDeviceInfo_construct() to
+ * populate this structure is highly recommended.
+ *
+ * @code
+    ktxVulkanDeviceInfo vdi;
+    ktxVulkanTexture texture;
+ 
+    vdi = ktxVulkanDeviceInfo_create(physicalDevice,
+                                     device,
+                                     queue,
+                                     cmdPool,
+                                     &allocator);
+    ktxLoadVkTextureN("texture_1.ktx", vdi, &texture, NULL, NULL);
+    // ...
+    ktxLoadVkTextureN("texture_n.ktx", vdi, &texture, NULL, NULL);
+    ktxVulkanDeviceInfo_destroy(vdi);
+ * @endcode
+ */
+typedef struct ktxVulkanDeviceInfo {
+    VkInstance instance; /*!< Instance used to communicate with vulkan. */
+    VkPhysicalDevice physicalDevice; /*!< Handle of the physical device. */
+    VkDevice device; /*!< Handle of the logical device. */
+    VkQueue queue; /*!< Handle to the queue to which to submit commands. */
+    VkCommandBuffer cmdBuffer; /*!< Handle of the cmdBuffer to use. */
+    /** Handle of the command pool from which to allocate the command buffer. */
+    VkCommandPool cmdPool;
+    /** Pointer to the allocator to use for the command buffer and created
+     * images.
+     */
+    const VkAllocationCallbacks* pAllocator;
+    /** Memory properties of the Vulkan physical device. */
+    VkPhysicalDeviceMemoryProperties deviceMemoryProperties;
+
+    /** The functions needed to operate functions */
+    ktxVulkanFunctions vkFuncs;
+} ktxVulkanDeviceInfo;
+
+
+KTX_API ktxVulkanDeviceInfo* KTX_APIENTRY
+ktxVulkanDeviceInfo_CreateEx(VkInstance instance, VkPhysicalDevice physicalDevice, VkDevice device,
+                           VkQueue queue, VkCommandPool cmdPool,
+                           const VkAllocationCallbacks* pAllocator,
+                           const ktxVulkanFunctions* pFunctions);
+
+KTX_API ktxVulkanDeviceInfo* KTX_APIENTRY
+ktxVulkanDeviceInfo_Create(VkPhysicalDevice physicalDevice, VkDevice device,
+                           VkQueue queue, VkCommandPool cmdPool,
+                           const VkAllocationCallbacks* pAllocator);
+
+KTX_API KTX_error_code KTX_APIENTRY
+ktxVulkanDeviceInfo_Construct(ktxVulkanDeviceInfo* This,
+                         VkPhysicalDevice physicalDevice, VkDevice device,
+                         VkQueue queue, VkCommandPool cmdPool,
+                         const VkAllocationCallbacks* pAllocator);
+
+KTX_API KTX_error_code KTX_APIENTRY
+ktxVulkanDeviceInfo_ConstructEx(ktxVulkanDeviceInfo* This,
+                              VkInstance instance,
+                              VkPhysicalDevice physicalDevice, VkDevice device,
+                              VkQueue queue, VkCommandPool cmdPool,
+                              const VkAllocationCallbacks* pAllocator,
+                              const ktxVulkanFunctions* pFunctions);
+
+KTX_API void KTX_APIENTRY
+ktxVulkanDeviceInfo_Destruct(ktxVulkanDeviceInfo* This);
+KTX_API void KTX_APIENTRY
+ktxVulkanDeviceInfo_Destroy(ktxVulkanDeviceInfo* This);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture_VkUploadEx_WithSuballocator(ktxTexture* This, ktxVulkanDeviceInfo* vdi,
+                                       ktxVulkanTexture* vkTexture,
+                                       VkImageTiling tiling,
+                                       VkImageUsageFlags usageFlags,
+                                       VkImageLayout finalLayout,
+                                       ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture_VkUploadEx(ktxTexture* This, ktxVulkanDeviceInfo* vdi,
+                      ktxVulkanTexture* vkTexture,
+                      VkImageTiling tiling,
+                      VkImageUsageFlags usageFlags,
+                      VkImageLayout finalLayout);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture_VkUpload(ktxTexture* texture, ktxVulkanDeviceInfo* vdi,
+                    ktxVulkanTexture *vkTexture);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture1_VkUploadEx_WithSuballocator(ktxTexture1* This, ktxVulkanDeviceInfo* vdi,
+                                        ktxVulkanTexture* vkTexture,
+                                        VkImageTiling tiling,
+                                        VkImageUsageFlags usageFlags,
+                                        VkImageLayout finalLayout,
+                                        ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture1_VkUploadEx(ktxTexture1* This, ktxVulkanDeviceInfo* vdi,
+                       ktxVulkanTexture* vkTexture,
+                       VkImageTiling tiling,
+                       VkImageUsageFlags usageFlags,
+                       VkImageLayout finalLayout);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture1_VkUpload(ktxTexture1* texture, ktxVulkanDeviceInfo* vdi,
+                    ktxVulkanTexture *vkTexture);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture2_VkUploadEx_WithSuballocator(ktxTexture2* This, ktxVulkanDeviceInfo* vdi,
+                                        ktxVulkanTexture* vkTexture,
+                                        VkImageTiling tiling,
+                                        VkImageUsageFlags usageFlags,
+                                        VkImageLayout finalLayout,
+                                        ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture2_VkUploadEx(ktxTexture2* This, ktxVulkanDeviceInfo* vdi,
+                       ktxVulkanTexture* vkTexture,
+                       VkImageTiling tiling,
+                       VkImageUsageFlags usageFlags,
+                       VkImageLayout finalLayout);
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture2_VkUpload(ktxTexture2* texture, ktxVulkanDeviceInfo* vdi,
+                     ktxVulkanTexture *vkTexture);
+
+KTX_API VkFormat KTX_APIENTRY
+ktxTexture_GetVkFormat(ktxTexture* This);
+
+KTX_API VkFormat KTX_APIENTRY
+ktxTexture1_GetVkFormat(ktxTexture1* This);
+
+KTX_API VkFormat KTX_APIENTRY
+ktxTexture2_GetVkFormat(ktxTexture2* This);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KTX_H_A55A6F00956F42F3A137C11929827FE1 */