libktx: Update to 4.3.1

3 files changed, 180 insertions, 90 deletions

diff --git a/thirdparty/libktx/include/KHR/khr_df.h b/thirdparty/libktx/include/KHR/khr_df.h
index bbd0d14bd9..c0d03aa763 100644
--- a/thirdparty/libktx/include/KHR/khr_df.h
+++ b/thirdparty/libktx/include/KHR/khr_df.h
@@ -17,6 +17,11 @@
 #ifndef _KHR_DATA_FORMAT_H_
 #define _KHR_DATA_FORMAT_H_
 
+/** @file khr_df.h
+
+    @brief Data Format enums and macros.
+*/
+
 /* Accessors */
 typedef enum _khr_word_e {
     KHR_DF_WORD_VENDORID = 0U,
@@ -217,41 +222,42 @@ typedef enum _khr_df_versionnumber_e {
     KHR_DF_VERSIONNUMBER_MAX = 0xFFFFU
 } khr_df_versionnumber_e;
 
-/* Model in which the color coordinate space is defined.
+/** @~English
+   @brief Model in which the color coordinate space is defined.
    There is no requirement that a color format use all the
    channel types that are defined in the color model. */
 typedef enum _khr_df_model_e {
-    /* No interpretation of color channels defined */
+    /** No interpretation of color channels defined */
     KHR_DF_MODEL_UNSPECIFIED  = 0U,
-    /* Color primaries (red, green, blue) + alpha, depth and stencil */
+    /** Color primaries (red, green, blue) + alpha, depth and stencil */
     KHR_DF_MODEL_RGBSDA       = 1U,
-    /* Color differences (Y', Cb, Cr) + alpha, depth and stencil */
+    /** Color differences (Y', Cb, Cr) + alpha, depth and stencil */
     KHR_DF_MODEL_YUVSDA       = 2U,
-    /* Color differences (Y', I, Q) + alpha, depth and stencil */
+    /** Color differences (Y', I, Q) + alpha, depth and stencil */
     KHR_DF_MODEL_YIQSDA       = 3U,
-    /* Perceptual color (CIE L*a*b*) + alpha, depth and stencil */
+    /** Perceptual color (CIE L*a*b*) + alpha, depth and stencil */
     KHR_DF_MODEL_LABSDA       = 4U,
-    /* Subtractive colors (cyan, magenta, yellow, black) + alpha */
+    /** Subtractive colors (cyan, magenta, yellow, black) + alpha */
     KHR_DF_MODEL_CMYKA        = 5U,
-    /* Non-color coordinate data (X, Y, Z, W) */
+    /** Non-color coordinate data (X, Y, Z, W) */
     KHR_DF_MODEL_XYZW         = 6U,
-    /* Hue, saturation, value, hue angle on color circle, plus alpha */
+    /** Hue, saturation, value, hue angle on color circle, plus alpha */
     KHR_DF_MODEL_HSVA_ANG     = 7U,
-    /* Hue, saturation, lightness, hue angle on color circle, plus alpha */
+    /** Hue, saturation, lightness, hue angle on color circle, plus alpha */
     KHR_DF_MODEL_HSLA_ANG     = 8U,
-    /* Hue, saturation, value, hue on color hexagon, plus alpha */
+    /** Hue, saturation, value, hue on color hexagon, plus alpha */
     KHR_DF_MODEL_HSVA_HEX     = 9U,
-    /* Hue, saturation, lightness, hue on color hexagon, plus alpha */
+    /** Hue, saturation, lightness, hue on color hexagon, plus alpha */
     KHR_DF_MODEL_HSLA_HEX     = 10U,
-    /* Lightweight approximate color difference (luma, orange, green) */
+    /** Lightweight approximate color difference (luma, orange, green) */
     KHR_DF_MODEL_YCGCOA       = 11U,
-    /* ITU BT.2020 constant luminance YcCbcCrc */
+    /** ITU BT.2020 constant luminance YcCbcCrc */
     KHR_DF_MODEL_YCCBCCRC     = 12U,
-    /* ITU BT.2100 constant intensity ICtCp */
+    /** ITU BT.2100 constant intensity ICtCp */
     KHR_DF_MODEL_ICTCP        = 13U,
-    /* CIE 1931 XYZ color coordinates (X, Y, Z) */
+    /** CIE 1931 XYZ color coordinates (X, Y, Z) */
     KHR_DF_MODEL_CIEXYZ       = 14U,
-    /* CIE 1931 xyY color coordinates (X, Y, Y) */
+    /** CIE 1931 xyY color coordinates (X, Y, Y) */
     KHR_DF_MODEL_CIEXYY       = 15U,
 
     /* Compressed formats start at 128. */
@@ -260,51 +266,54 @@ typedef enum _khr_df_model_e {
        channels are used to distinguish formats, these should be cosited. */
     /* Direct3D (and S3) compressed formats */
     /* Note that premultiplied status is recorded separately */
-    /* DXT1 "channels" are RGB (0), Alpha (1) */
-    /* DXT1/BC1 with one channel is opaque */
-    /* DXT1/BC1 with a cosited alpha sample is transparent */
+    /** DXT1 "channels" are RGB (0), Alpha (1)
+        DXT1/BC1 with one channel is opaque
+        DXT1/BC1 with a cosited alpha sample is transparent */
     KHR_DF_MODEL_DXT1A         = 128U,
     KHR_DF_MODEL_BC1A          = 128U,
-    /* DXT2/DXT3/BC2, with explicit 4-bit alpha */
+    /** DXT2/DXT3/BC2, with explicit 4-bit alpha */
     KHR_DF_MODEL_DXT2          = 129U,
     KHR_DF_MODEL_DXT3          = 129U,
     KHR_DF_MODEL_BC2           = 129U,
-    /* DXT4/DXT5/BC3, with interpolated alpha */
+    /** DXT4/DXT5/BC3, with interpolated alpha */
     KHR_DF_MODEL_DXT4          = 130U,
     KHR_DF_MODEL_DXT5          = 130U,
     KHR_DF_MODEL_BC3           = 130U,
-    /* BC4 - single channel interpolated 8-bit data */
-    /* (The UNORM/SNORM variation is recorded in the channel data) */
+    /** BC4 - single channel interpolated 8-bit data
+        (The UNORM/SNORM variation is recorded in the channel data) */
     KHR_DF_MODEL_BC4           = 131U,
-    /* BC5 - two channel interpolated 8-bit data */
-    /* (The UNORM/SNORM variation is recorded in the channel data) */
+    /** BC5 - two channel interpolated 8-bit data
+        (The UNORM/SNORM variation is recorded in the channel data) */
     KHR_DF_MODEL_BC5           = 132U,
-    /* BC6H - DX11 format for 16-bit float channels */
+    /** BC6H - DX11 format for 16-bit float channels */
     KHR_DF_MODEL_BC6H          = 133U,
-    /* BC7 - DX11 format */
+    /** BC7 - DX11 format */
     KHR_DF_MODEL_BC7           = 134U,
     /* Gap left for future desktop expansion */
 
     /* Mobile compressed formats follow */
-    /* A format of ETC1 indicates that the format shall be decodable
-       by an ETC1-compliant decoder and not rely on ETC2 features */
+    /** A format of ETC1 indicates that the format shall be decodable
+        by an ETC1-compliant decoder and not rely on ETC2 features */
     KHR_DF_MODEL_ETC1          = 160U,
-    /* A format of ETC2 is permitted to use ETC2 encodings on top of
-       the baseline ETC1 specification */
-    /* The ETC2 format has channels "red", "green", "RGB" and "alpha",
-       which should be cosited samples */
-    /* Punch-through alpha can be distinguished from full alpha by
-       the plane size in bytes required for the texel block */
+    /** A format of ETC2 is permitted to use ETC2 encodings on top of
+        the baseline ETC1 specification.
+        The ETC2 format has channels "red", "green", "RGB" and "alpha",
+        which should be cosited samples.
+        Punch-through alpha can be distinguished from full alpha by
+        the plane size in bytes required for the texel block */
     KHR_DF_MODEL_ETC2          = 161U,
-    /* Adaptive Scalable Texture Compression */
-    /* ASTC HDR vs LDR is determined by the float flag in the channel */
-    /* ASTC block size can be distinguished by texel block size */
+    /** Adaptive Scalable Texture Compression */
+    /** ASTC HDR vs LDR is determined by the float flag in the channel */
+    /** ASTC block size can be distinguished by texel block size */
     KHR_DF_MODEL_ASTC          = 162U,
-    /* ETC1S is a simplified subset of ETC1 */
+    /** ETC1S is a simplified subset of ETC1 */
     KHR_DF_MODEL_ETC1S         = 163U,
-    /* PowerVR Texture Compression */
+    /** PowerVR Texture Compression v1 */
     KHR_DF_MODEL_PVRTC         = 164U,
+    /** PowerVR Texture Compression v2 */
     KHR_DF_MODEL_PVRTC2        = 165U,
+    /** UASTC is a transcodable subset of ASTC
+        with additions to support the transcoding. */
     KHR_DF_MODEL_UASTC         = 166U,
     /* Proprietary formats (ATITC, etc.) should follow */
     KHR_DF_MODEL_MAX = 0xFFU
@@ -520,86 +529,88 @@ typedef enum _khr_df_model_channels_e {
     KHR_DF_CHANNEL_COMMON_A       = 15U
 } khr_df_model_channels_e;
 
-/* Definition of the primary colors in color coordinates.
+/** @~English
+   @brief Definition of the primary colors in color coordinates.
    This is implicitly responsible for defining the conversion
    between RGB an YUV color spaces.
    LAB and related absolute color models should use
    KHR_DF_PRIMARIES_CIEXYZ. */
 typedef enum _khr_df_primaries_e {
-    /* No color primaries defined */
+    /** No color primaries defined */
     KHR_DF_PRIMARIES_UNSPECIFIED = 0U,
-    /* Color primaries of ITU-R BT.709 and sRGB */
+    /** Color primaries of ITU-R BT.709 and sRGB */
     KHR_DF_PRIMARIES_BT709       = 1U,
-    /* Synonym for KHR_DF_PRIMARIES_BT709 */
+    /** Synonym for KHR_DF_PRIMARIES_BT709 */
     KHR_DF_PRIMARIES_SRGB        = 1U,
-    /* Color primaries of ITU-R BT.601 (625-line EBU variant) */
+    /** Color primaries of ITU-R BT.601 (625-line EBU variant) */
     KHR_DF_PRIMARIES_BT601_EBU   = 2U,
-    /* Color primaries of ITU-R BT.601 (525-line SMPTE C variant) */
+    /** Color primaries of ITU-R BT.601 (525-line SMPTE C variant) */
     KHR_DF_PRIMARIES_BT601_SMPTE = 3U,
-    /* Color primaries of ITU-R BT.2020 */
+    /** Color primaries of ITU-R BT.2020 */
     KHR_DF_PRIMARIES_BT2020      = 4U,
-    /* CIE theoretical color coordinate space */
+    /** CIE theoretical color coordinate space */
     KHR_DF_PRIMARIES_CIEXYZ      = 5U,
-    /* Academy Color Encoding System primaries */
+    /** Academy Color Encoding System primaries */
     KHR_DF_PRIMARIES_ACES        = 6U,
-    /* Color primaries of ACEScc */
+    /** Color primaries of ACEScc */
     KHR_DF_PRIMARIES_ACESCC      = 7U,
-    /* Legacy NTSC 1953 primaries */
+    /** Legacy NTSC 1953 primaries */
     KHR_DF_PRIMARIES_NTSC1953    = 8U,
-    /* Legacy PAL 525-line primaries */
+    /** Legacy PAL 525-line primaries */
     KHR_DF_PRIMARIES_PAL525      = 9U,
-    /* Color primaries of Display P3 */
+    /** Color primaries of Display P3 */
     KHR_DF_PRIMARIES_DISPLAYP3   = 10U,
-    /* Color primaries of Adobe RGB (1998) */
+    /** Color primaries of Adobe RGB (1998) */
     KHR_DF_PRIMARIES_ADOBERGB    = 11U,
     KHR_DF_PRIMARIES_MAX         = 0xFFU
 } khr_df_primaries_e;
 
-/* Definition of the optical to digital transfer function
+/** @~English
+   @brief Definition of the optical to digital transfer function
    ("gamma correction"). Most transfer functions are not a pure
    power function and also include a linear element.
    LAB and related absolute color representations should use
    KHR_DF_TRANSFER_UNSPECIFIED. */
 typedef enum _khr_df_transfer_e {
-    /* No transfer function defined */
+    /** No transfer function defined */
     KHR_DF_TRANSFER_UNSPECIFIED = 0U,
-    /* Linear transfer function (value proportional to intensity) */
+    /** Linear transfer function (value proportional to intensity) */
     KHR_DF_TRANSFER_LINEAR      = 1U,
-    /* Perceptually-linear transfer function of sRGH (~2.4) */
+    /** Perceptually-linear transfer function of sRGH (~2.4) */
     KHR_DF_TRANSFER_SRGB        = 2U,
-    /* Perceptually-linear transfer function of ITU BT.601, BT.709 and BT.2020 (~1/.45) */
+    /** Perceptually-linear transfer function of ITU BT.601, BT.709 and BT.2020 (~1/.45) */
     KHR_DF_TRANSFER_ITU         = 3U,
-    /* SMTPE170M (digital NTSC) defines an alias for the ITU transfer function (~1/.45) */
+    /** SMTPE170M (digital NTSC) defines an alias for the ITU transfer function (~1/.45) */
     KHR_DF_TRANSFER_SMTPE170M   = 3U,
-    /* Perceptually-linear gamma function of original NTSC (simple 2.2 gamma) */
+    /** Perceptually-linear gamma function of original NTSC (simple 2.2 gamma) */
     KHR_DF_TRANSFER_NTSC        = 4U,
-    /* Sony S-log used by Sony video cameras */
+    /** Sony S-log used by Sony video cameras */
     KHR_DF_TRANSFER_SLOG        = 5U,
-    /* Sony S-log 2 used by Sony video cameras */
+    /** Sony S-log 2 used by Sony video cameras */
     KHR_DF_TRANSFER_SLOG2       = 6U,
-    /* ITU BT.1886 EOTF */
+    /** ITU BT.1886 EOTF */
     KHR_DF_TRANSFER_BT1886      = 7U,
-    /* ITU BT.2100 HLG OETF */
+    /** ITU BT.2100 HLG OETF */
     KHR_DF_TRANSFER_HLG_OETF    = 8U,
-    /* ITU BT.2100 HLG EOTF */
+    /** ITU BT.2100 HLG EOTF */
     KHR_DF_TRANSFER_HLG_EOTF    = 9U,
-    /* ITU BT.2100 PQ EOTF */
+    /** ITU BT.2100 PQ EOTF */
     KHR_DF_TRANSFER_PQ_EOTF     = 10U,
-    /* ITU BT.2100 PQ OETF */
+    /** ITU BT.2100 PQ OETF */
     KHR_DF_TRANSFER_PQ_OETF     = 11U,
-    /* DCI P3 transfer function */
+    /** DCI P3 transfer function */
     KHR_DF_TRANSFER_DCIP3       = 12U,
-    /* Legacy PAL OETF */
+    /** Legacy PAL OETF */
     KHR_DF_TRANSFER_PAL_OETF    = 13U,
-    /* Legacy PAL 625-line EOTF */
+    /** Legacy PAL 625-line EOTF */
     KHR_DF_TRANSFER_PAL625_EOTF = 14U,
-    /* Legacy ST240 transfer function */
+    /** Legacy ST240 transfer function */
     KHR_DF_TRANSFER_ST240       = 15U,
-    /* ACEScc transfer function */
+    /** ACEScc transfer function */
     KHR_DF_TRANSFER_ACESCC      = 16U,
-    /* ACEScct transfer function */
+    /** ACEScct transfer function */
     KHR_DF_TRANSFER_ACESCCT     = 17U,
-    /* Adobe RGB (1998) transfer function */
+    /** Adobe RGB (1998) transfer function */
     KHR_DF_TRANSFER_ADOBERGB    = 18U,
     KHR_DF_TRANSFER_MAX         = 0xFFU
 } khr_df_transfer_e;
diff --git a/thirdparty/libktx/include/ktx.h b/thirdparty/libktx/include/ktx.h
index 0af87f2519..dcf5dae42a 100644
--- a/thirdparty/libktx/include/ktx.h
+++ b/thirdparty/libktx/include/ktx.h
@@ -25,6 +25,7 @@
  * @snippet{doc} version.h API version
  */
 
+#include <limits.h>
 #include <stdio.h>
 #include <stdbool.h>
 #include <sys/types.h>
@@ -156,6 +157,7 @@ extern "C" {
  * @brief Required unpack alignment
  */
 #define KTX_GL_UNPACK_ALIGNMENT 4
+#define KTX_FACESLICE_WHOLE_LEVEL UINT_MAX
 
 #define KTX_TRUE  true
 #define KTX_FALSE false
@@ -176,15 +178,17 @@ typedef enum ktx_error_code_e {
     KTX_FILE_WRITE_ERROR,    /*!< An error occurred while writing to the file. */
     KTX_GL_ERROR,            /*!< GL operations resulted in an error. */
     KTX_INVALID_OPERATION,   /*!< The operation is not allowed in the current state. */
-    KTX_INVALID_VALUE,       /*!< A parameter value was not valid */
-    KTX_NOT_FOUND,           /*!< Requested key was not found */
+    KTX_INVALID_VALUE,       /*!< A parameter value was not valid. */
+    KTX_NOT_FOUND,           /*!< Requested metadata key or required dynamically loaded GPU function was not found. */
     KTX_OUT_OF_MEMORY,       /*!< Not enough memory to complete the operation. */
     KTX_TRANSCODE_FAILED,    /*!< Transcoding of block compressed texture failed. */
     KTX_UNKNOWN_FILE_FORMAT, /*!< The file not a KTX file */
     KTX_UNSUPPORTED_TEXTURE_TYPE, /*!< The KTX file specifies an unsupported texture type. */
     KTX_UNSUPPORTED_FEATURE,  /*!< Feature not included in in-use library or not yet implemented. */
     KTX_LIBRARY_NOT_LINKED,  /*!< Library dependency (OpenGL or Vulkan) not linked into application. */
-    KTX_ERROR_MAX_ENUM = KTX_LIBRARY_NOT_LINKED /*!< For safety checks. */
+    KTX_DECOMPRESS_LENGTH_ERROR, /*!< Decompressed byte count does not match expected byte size */
+    KTX_DECOMPRESS_CHECKSUM_ERROR, /*!< Checksum mismatch when decompressing */
+    KTX_ERROR_MAX_ENUM = KTX_DECOMPRESS_CHECKSUM_ERROR /*!< For safety checks. */
 } ktx_error_code_e;
 /**
  * @deprecated
@@ -672,8 +676,9 @@ typedef enum ktxSupercmpScheme {
     KTX_SS_NONE = 0,            /*!< No supercompression. */
     KTX_SS_BASIS_LZ = 1,        /*!< Basis LZ supercompression. */
     KTX_SS_ZSTD = 2,            /*!< ZStd supercompression. */
+    KTX_SS_ZLIB = 3,            /*!< ZLIB supercompression. */
     KTX_SS_BEGIN_RANGE = KTX_SS_NONE,
-    KTX_SS_END_RANGE = KTX_SS_ZSTD,
+    KTX_SS_END_RANGE = KTX_SS_ZLIB,
     KTX_SS_BEGIN_VENDOR_RANGE = 0x10000,
     KTX_SS_END_VENDOR_RANGE = 0x1ffff,
     KTX_SS_BEGIN_RESERVED = 0x20000,
@@ -703,15 +708,21 @@ typedef struct ktxTexture2 {
     struct ktxTexture2_private* _private;  /*!< Private data. */
 } ktxTexture2;
 
+/**
+ * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.
+ *
+ * Use with caution.
+ */
 #define ktxTexture(t) ((ktxTexture*)t)
 
 /**
  * @memberof ktxTexture
  * @~English
- * @brief Structure for passing texture information to ktxTexture1_Create() and
- *        ktxTexture2_Create().
+ * @brief Structure for passing texture information to ktxTexture1\_Create() and
+ *        ktxTexture2\_Create().
  *
- * @sa ktxTexture1_Create() and ktxTexture2_Create().
+ * @sa @ref ktxTexture1::ktxTexture1\_Create() "ktxTexture1_Create()"
+ * @sa @ref ktxTexture2::ktxTexture2\_Create() "ktxTexture2_Create()"
  */
 typedef struct
 {
@@ -766,9 +777,12 @@ enum ktxTextureCreateFlagBits {
     KTX_TEXTURE_CREATE_RAW_KVDATA_BIT = 0x02,
                                    /*!< Load the raw key-value data instead of
                                         creating a @c ktxHashList from it. */
-    KTX_TEXTURE_CREATE_SKIP_KVDATA_BIT = 0x04
+    KTX_TEXTURE_CREATE_SKIP_KVDATA_BIT = 0x04,
                                    /*!< Skip any key-value data. This overrides
                                         the RAW_KVDATA_BIT. */
+    KTX_TEXTURE_CREATE_CHECK_GLTF_BASISU_BIT = 0x08
+                                   /*!< Load texture compatible with the rules
+                                        of KHR_texture_basisu glTF extension */
 };
 /**
  * @memberof ktxTexture
@@ -1053,6 +1067,9 @@ ktxTexture2_CompressBasis(ktxTexture2* This, ktx_uint32_t quality);
 KTX_API KTX_error_code KTX_APIENTRY
 ktxTexture2_DeflateZstd(ktxTexture2* This, ktx_uint32_t level);
 
+KTX_API KTX_error_code KTX_APIENTRY
+ktxTexture2_DeflateZLIB(ktxTexture2* This, ktx_uint32_t level);
+
 KTX_API void KTX_APIENTRY
 ktxTexture2_GetComponentInfo(ktxTexture2* This, ktx_uint32_t* numComponents,
                              ktx_uint32_t* componentByteLength);
@@ -1682,6 +1699,19 @@ KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForStdioStream(FILE* stdioStream
 KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForNamedFile(const char* const filename);
 KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForMemory(const ktx_uint8_t* bytes, ktx_size_t size);
 
+/*===========================================================*
+ * Utilities for printing info about a KTX2 file.            *
+ *===========================================================*/
+
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForMemory(const ktx_uint8_t* bytes, ktx_size_t size);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForNamedFile(const char* const filename);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForStdioStream(FILE* stdioStream);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForStream(ktxStream* stream);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForMemory(const ktx_uint8_t* bytes, ktx_size_t size, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForNamedFile(const char* const filename, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForStdioStream(FILE* stdioStream, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified);
+KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForStream(ktxStream* stream, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified);
+
 #ifdef __cplusplus
 }
 #endif
@@ -1709,6 +1739,9 @@ KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForMemory(const ktx_uint8_t* byt
 @~English
 @page libktx_history Revision History
 
+No longer updated. Kept to preserve ancient history. For more recent history see the repo log at
+https://github.com/KhronosGroup/KTX-Software. See also the Release Notes in the repo.
+
 @section v8 Version 4.0
 Added:
 @li Support for KTX Version 2.
diff --git a/thirdparty/libktx/include/ktxvulkan.h b/thirdparty/libktx/include/ktxvulkan.h
index e695ee6863..2162b1fc59 100644
--- a/thirdparty/libktx/include/ktxvulkan.h
+++ b/thirdparty/libktx/include/ktxvulkan.h
@@ -23,8 +23,6 @@
  * alternative is duplicating unattractively large parts of it.
  *
  * @author Mark Callow, Edgewise Consulting
- *
- * $Date$
  */
 
 #include <ktx.h>
@@ -116,8 +114,9 @@ typedef struct ktxVulkanTexture
     VkImageLayout imageLayout; /*!< Layout of the created image. Has the same
                                     value as @p layout parameter passed to the
                                     loader. */
-    VkDeviceMemory deviceMemory; /*!< The memory allocated for the image on
-                                  the Vulkan device. */
+    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. */
@@ -126,15 +125,41 @@ typedef struct ktxVulkanTexture
     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
@@ -210,6 +235,13 @@ 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,
@@ -219,6 +251,13 @@ 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,
@@ -228,6 +267,13 @@ 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,