ktx.h

/* -*- tab-width: 4; -*- */
/* vi: set sw=2 ts=4 expandtab: */

#ifndef KTX_H_A55A6F00956F42F3A137C11929827FE1
#define KTX_H_A55A6F00956F42F3A137C11929827FE1

/*
 * Copyright 2010-2018 The Khronos Group, Inc.
 * SPDX-License-Identifier: Apache-2.0
 *
 * See the accompanying LICENSE.md for licensing details for all files in
 * the KTX library and KTX loader tests.
 */

/**
 * @file
 * @~English
 *
 * @brief Declares the public functions and structures of the
 *        KTX API.
 *
 * @author Mark Callow, Edgewise Consulting and while at HI Corporation
 * @author Based on original work by Georg Kolling, Imagination Technology
 *
 * @snippet{doc} version.h API version
 */

#include <limits.h>
#include <stdio.h>
#include <stdbool.h>
#include <sys/types.h>

#include <KHR/khr_df.h>

/*
 * Don't use khrplatform.h in order not to break apps existing
 * before these definitions were needed.
 */
#if defined(KHRONOS_STATIC)
  #define KTX_API
#elif defined(_WIN32) || defined(__CYGWIN__)
  #if !defined(KTX_API)
    #if __GNUC__
      #define KTX_API __attribute__ ((dllimport))
    #elif _MSC_VER
      #define KTX_API __declspec(dllimport)
    #else
      #error "Your compiler's equivalent of dllimport is unknown"
    #endif
  #endif
#elif defined(__ANDROID__)
  #define KTX_API __attribute__((visibility("default")))
#else
  #define KTX_API
#endif

#if defined(_WIN32) && !defined(KHRONOS_STATIC)
  #if !defined(KTX_APIENTRY)
    #define KTX_APIENTRY __stdcall
  #endif
#else
  #define KTX_APIENTRY
#endif

/* To avoid including <KHR/khrplatform.h> define our own types. */
typedef unsigned char ktx_uint8_t;
typedef bool ktx_bool_t;
#ifdef _MSC_VER
typedef unsigned __int16 ktx_uint16_t;
typedef   signed __int16 ktx_int16_t;
typedef unsigned __int32 ktx_uint32_t;
typedef   signed __int32 ktx_int32_t;
typedef          size_t  ktx_size_t;
typedef unsigned __int64 ktx_uint64_t;
typedef   signed __int64 ktx_int64_t;
#else
#include <stdint.h>
typedef uint16_t ktx_uint16_t;
typedef  int16_t ktx_int16_t;
typedef uint32_t ktx_uint32_t;
typedef  int32_t ktx_int32_t;
typedef   size_t ktx_size_t;
typedef uint64_t ktx_uint64_t;
typedef  int64_t ktx_int64_t;
#endif

/* This will cause compilation to fail if size of uint32 != 4. */
typedef unsigned char ktx_uint32_t_SIZE_ASSERT[sizeof(ktx_uint32_t) == 4];

/*
 * This #if allows libktx to be compiled with strict c99. It avoids
 * compiler warnings or even errors when a gl.h is already included.
 * "Redefinition of (type) is a c11 feature". Obviously this doesn't help if
 * gl.h comes after. However nobody has complained about the unguarded typedefs
 * since they were introduced so this is unlikely to be a problem in practice.
 * Presumably everybody is using platform default compilers not c99 or else
 * they are using C++.
 */
#if !defined(GL_NO_ERROR)
  /*
   * To avoid having to including gl.h ...
   */
  typedef unsigned char GLboolean;
  typedef unsigned int GLenum;
  typedef int GLint;
  typedef int GLsizei;
  typedef unsigned int GLuint;
  typedef unsigned char GLubyte;
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @~English
 * @brief Key string for standard writer metadata.
 */
#define KTX_ANIMDATA_KEY "KTXanimData"
/**
 * @~English
 * @brief Key string for standard orientation metadata.
 */
#define KTX_ORIENTATION_KEY "KTXorientation"
/**
 * @~English
 * @brief Key string for standard swizzle metadata.
 */
#define KTX_SWIZZLE_KEY "KTXswizzle"
/**
 * @~English
 * @brief Key string for standard writer metadata.
 */
#define KTX_WRITER_KEY "KTXwriter"
/**
 * @~English
 * @brief Key string for standard writer supercompression parameter metadata.
 */
#define KTX_WRITER_SCPARAMS_KEY "KTXwriterScParams"
/**
 * @~English
 * @brief Standard KTX 1 format for 1D orientation value.
 */
#define KTX_ORIENTATION1_FMT "S=%c"
/**
 * @~English
 * @brief Standard KTX 1 format for 2D orientation value.
 */
#define KTX_ORIENTATION2_FMT "S=%c,T=%c"
/**
 * @~English
 * @brief Standard KTX 1 format for 3D orientation value.
 */
#define KTX_ORIENTATION3_FMT "S=%c,T=%c,R=%c"
/**
 * @~English
 * @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

/**
 * @~English
 * @brief Error codes returned by library functions.
 */
typedef enum ktx_error_code_e {
    KTX_SUCCESS = 0,         /*!< Operation was successful. */
    KTX_FILE_DATA_ERROR,     /*!< The data in the file is inconsistent with the spec. */
    KTX_FILE_ISPIPE,         /*!< The file is a pipe or named pipe. */
    KTX_FILE_OPEN_FAILED,    /*!< The target file could not be opened. */
    KTX_FILE_OVERFLOW,       /*!< The operation would exceed the max file size. */
    KTX_FILE_READ_ERROR,     /*!< An error occurred while reading from the file. */
    KTX_FILE_SEEK_ERROR,     /*!< An error occurred while seeking in the file. */
    KTX_FILE_UNEXPECTED_EOF, /*!< File does not have enough data to satisfy request. */
    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 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_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;
/**
 * @~English
 * @deprecated Use #ktx_error_code_e.
 * @brief For backward compatibility
 */
#define KTX_error_code ktx_error_code_e

#define KTX_IDENTIFIER_REF  { 0xAB, 0x4B, 0x54, 0x58, 0x20, 0x31, 0x31, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A }
#define KTX_ENDIAN_REF      (0x04030201)
#define KTX_ENDIAN_REF_REV  (0x01020304)
#define KTX_HEADER_SIZE     (64)

/**
 * @~English
 * @brief Result codes returned by library functions.
 */
 typedef enum ktx_error_code_e ktxResult;

/**
 * @class ktxHashList
 * @~English
 * @brief Opaque handle to a ktxHashList.
 */
typedef struct ktxKVListEntry* ktxHashList;

typedef struct ktxStream ktxStream;

#define KTX_APIENTRYP KTX_APIENTRY *
/**
 * @class ktxHashListEntry
 * @~English
 * @brief Opaque handle to an entry in a @ref ktxHashList.
 */
typedef struct ktxKVListEntry ktxHashListEntry;

typedef enum ktxOrientationX {
    KTX_ORIENT_X_LEFT = 'l', KTX_ORIENT_X_RIGHT = 'r'
} ktxOrientationX;

typedef enum ktxOrientationY {
    KTX_ORIENT_Y_UP = 'u', KTX_ORIENT_Y_DOWN = 'd'
} ktxOrientationY;

typedef enum ktxOrientationZ {
    KTX_ORIENT_Z_IN = 'i', KTX_ORIENT_Z_OUT = 'o'
} ktxOrientationZ;

typedef enum class_id {
    ktxTexture1_c = 1,
    ktxTexture2_c = 2
} class_id;

/**
 * @~English
 * @brief Struct describing the logical orientation of an image.
 */
struct ktxOrientation {
    ktxOrientationX x;  /*!< Orientation in X */
    ktxOrientationY y;  /*!< Orientation in Y */
    ktxOrientationZ z;  /*!< Orientation in Z */
};

#define KTXTEXTURECLASSDEFN                   \
    class_id classId;                         \
    struct ktxTexture_vtbl* vtbl;             \
    struct ktxTexture_vvtbl* vvtbl;           \
    struct ktxTexture_protected* _protected;  \
    ktx_bool_t   isArray;                     \
    ktx_bool_t   isCubemap;                   \
    ktx_bool_t   isCompressed;                \
    ktx_bool_t   generateMipmaps;             \
    ktx_uint32_t baseWidth;                   \
    ktx_uint32_t baseHeight;                  \
    ktx_uint32_t baseDepth;                   \
    ktx_uint32_t numDimensions;               \
    ktx_uint32_t numLevels;                   \
    ktx_uint32_t numLayers;                   \
    ktx_uint32_t numFaces;                    \
    struct ktxOrientation orientation;        \
    ktxHashList  kvDataHead;                  \
    ktx_uint32_t kvDataLen;                   \
    ktx_uint8_t* kvData;                      \
    ktx_size_t dataSize;                      \
    ktx_uint8_t* pData;


/**
 * @class ktxTexture
 * @~English
 * @brief Base class representing a texture.
 *
 * ktxTextures should be created only by one of the provided
 * functions and these fields should be considered read-only.
 */
typedef struct ktxTexture {
    KTXTEXTURECLASSDEFN
} ktxTexture;
/**
 * @typedef ktxTexture::classId
 * @~English
 * @brief Identify the class type.
 *
 * Since there are no public ktxTexture constructors, this can only have
 * values of ktxTexture1_c or ktxTexture2_c.
 */
/**
 * @typedef ktxTexture::vtbl
 * @~English
 * @brief Pointer to the class's vtble.
 */
/**
 * @typedef ktxTexture::vvtbl
 * @~English
 * @brief Pointer to the class's vtble for Vulkan functions.
 *
 * A separate vtble is used so this header does not need to include vulkan.h.
 */
/**
 * @typedef ktxTexture::_protected
 * @~English
 * @brief Opaque pointer to the class's protected variables.
 */
/**
 * @typedef ktxTexture::isArray
 * @~English
 *
 * KTX_TRUE if the texture is an array texture, i.e,
 * a GL_TEXTURE_*_ARRAY target is to be used.
 */
/**
 * @typedef ktxTexture::isCubemap
 * @~English
 *
 * KTX_TRUE if the texture is a cubemap or cubemap array.
 */
/**
 * @typedef ktxTexture::isCompressed
 * @~English
 *
 * KTX_TRUE if the texture's format is a block compressed format.
 */
/**
 * @typedef ktxTexture::generateMipmaps
 * @~English
 *
 * KTX_TRUE if mipmaps should be generated for the texture by
 * ktxTexture_GLUpload() or ktxTexture_VkUpload().
 */
/**
 * @typedef ktxTexture::baseWidth
 * @~English
 * @brief Width of the texture's base level.
 */
/**
 * @typedef ktxTexture::baseHeight
 * @~English
 * @brief Height of the texture's base level.
 */
/**
 * @typedef ktxTexture::baseDepth
 * @~English
 * @brief Depth of the texture's base level.
 */
/**
 * @typedef ktxTexture::numDimensions
 * @~English
 * @brief Number of dimensions in the texture: 1, 2 or 3.
 */
/**
 * @typedef ktxTexture::numLevels
 * @~English
 * @brief Number of mip levels in the texture.
 *
 * Must be 1, if @c generateMipmaps is KTX_TRUE. Can be less than a
 * full pyramid but always starts at the base level.
 */
/**
 * @typedef ktxTexture::numLevels
 * @~English
 * @brief Number of array layers in the texture.
 */
/**
 * @typedef ktxTexture::numFaces
 * @~English
 * @brief Number of faces: 6 for cube maps, 1 otherwise.
 */
/**
 * @typedef ktxTexture::orientation
 * @~English
 * @brief Describes the logical orientation of the images in each dimension.
 *
 * ktxOrientationX for X, ktxOrientationY for Y and ktxOrientationZ for Z.
 */
/**
 * @typedef ktxTexture::kvDataHead
 * @~English
 * @brief Head of the hash list of metadata.
 */
/**
 * @typedef ktxTexture::kvDataLen
 * @~English
 * @brief Length of the metadata, if it has been extracted in its raw form,
 *       otherwise 0.
 */
/**
 * @typedef ktxTexture::kvData
 * @~English
 * @brief Pointer to the metadata, if it has been extracted in its raw form,
 *       otherwise NULL.
 */
/**
 * @typedef ktxTexture::dataSize
 * @~English
 * @brief Byte length of the texture's uncompressed image data.
 */
/**
 * @typedef ktxTexture::pData
 * @~English
 * @brief Pointer to the start of the image data.
 */

/**
 * @memberof ktxTexture
 * @~English
 * @brief Signature of function called by the <tt>ktxTexture_Iterate*</tt>
 *        functions to receive image data.
 *
 * The function parameters are used to pass values which change for each image.
 * Obtain values which are uniform across all images from the @c ktxTexture
 * object.
 *
 * @param [in] miplevel        MIP level from 0 to the max level which is
 *                             dependent on the texture size.
 * @param [in] face            usually 0; for cube maps, one of the 6 cube
 *                             faces in the order +X, -X, +Y, -Y, +Z, -Z,
 *                             0 to 5.
 * @param [in] width           width of the image.
 * @param [in] height          height of the image or, for 1D textures
 *                             textures, 1.
 * @param [in] depth           depth of the image or, for 1D & 2D
 *                             textures, 1.
 * @param [in] faceLodSize     number of bytes of data pointed at by
 *                             @p pixels.
 * @param [in] pixels          pointer to the image data.
 * @param [in,out] userdata    pointer for the application to pass data to and
 *                             from the callback function.
 */

typedef KTX_error_code
    (* PFNKTXITERCB)(int miplevel, int face,
                     int width, int height, int depth,
                     ktx_uint64_t faceLodSize,
                     void* pixels, void* userdata);

/* Don't use KTX_APIENTRYP to avoid a Doxygen bug. */
typedef void (KTX_APIENTRY* PFNKTEXDESTROY)(ktxTexture* This);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXGETIMAGEOFFSET)(ktxTexture* This, ktx_uint32_t level,
                                          ktx_uint32_t layer,
                                          ktx_uint32_t faceSlice,
                                          ktx_size_t* pOffset);
typedef ktx_size_t
    (KTX_APIENTRY* PFNKTEXGETDATASIZEUNCOMPRESSED)(ktxTexture* This);
typedef ktx_size_t
    (KTX_APIENTRY* PFNKTEXGETIMAGESIZE)(ktxTexture* This, ktx_uint32_t level);
typedef ktx_size_t
    (KTX_APIENTRY* PFNKTEXGETLEVELSIZE)(ktxTexture* This, ktx_uint32_t level);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXITERATELEVELS)(ktxTexture* This, PFNKTXITERCB iterCb,
                                         void* userdata);

typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXITERATELOADLEVELFACES)(ktxTexture* This,
                                                 PFNKTXITERCB iterCb,
                                                 void* userdata);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXLOADIMAGEDATA)(ktxTexture* This,
                                         ktx_uint8_t* pBuffer,
                                         ktx_size_t bufSize);
typedef ktx_bool_t
    (KTX_APIENTRY* PFNKTEXNEEDSTRANSCODING)(ktxTexture* This);

typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXSETIMAGEFROMMEMORY)(ktxTexture* This,
                                              ktx_uint32_t level,
                                              ktx_uint32_t layer,
                                              ktx_uint32_t faceSlice,
                                              const ktx_uint8_t* src,
                                              ktx_size_t srcSize);

typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXSETIMAGEFROMSTDIOSTREAM)(ktxTexture* This,
                                                   ktx_uint32_t level,
                                                   ktx_uint32_t layer,
                                                   ktx_uint32_t faceSlice,
                                                   FILE* src, ktx_size_t srcSize);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXWRITETOSTDIOSTREAM)(ktxTexture* This, FILE* dstsstr);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXWRITETONAMEDFILE)(ktxTexture* This,
                                            const char* const dstname);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXWRITETOMEMORY)(ktxTexture* This,
                                         ktx_uint8_t** bytes, ktx_size_t* size);
typedef KTX_error_code
    (KTX_APIENTRY* PFNKTEXWRITETOSTREAM)(ktxTexture* This,
                                         ktxStream* dststr);

/**
 * @memberof ktxTexture
 * @~English
 * @brief Table of virtual ktxTexture methods.
 */
 struct ktxTexture_vtbl {
    PFNKTEXDESTROY Destroy;
    PFNKTEXGETIMAGEOFFSET GetImageOffset;
    PFNKTEXGETDATASIZEUNCOMPRESSED GetDataSizeUncompressed;
    PFNKTEXGETIMAGESIZE GetImageSize;
    PFNKTEXGETLEVELSIZE GetLevelSize;
    PFNKTEXITERATELEVELS IterateLevels;
    PFNKTEXITERATELOADLEVELFACES IterateLoadLevelFaces;
    PFNKTEXNEEDSTRANSCODING NeedsTranscoding;
    PFNKTEXLOADIMAGEDATA LoadImageData;
    PFNKTEXSETIMAGEFROMMEMORY SetImageFromMemory;
    PFNKTEXSETIMAGEFROMSTDIOSTREAM SetImageFromStdioStream;
    PFNKTEXWRITETOSTDIOSTREAM WriteToStdioStream;
    PFNKTEXWRITETONAMEDFILE WriteToNamedFile;
    PFNKTEXWRITETOMEMORY WriteToMemory;
    PFNKTEXWRITETOSTREAM WriteToStream;
};

/****************************************************************
 * Macros to give some backward compatibility to the previous API
 ****************************************************************/

/**
 * @~English
 * @brief Helper for calling the Destroy virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_Destroy
 */
#define ktxTexture_Destroy(This) (This)->vtbl->Destroy(This)

/**
 * @~English
 * @brief Helper for calling the GetImageOffset virtual method of a
 *        ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_GetImageOffset
 */
#define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset) \
            (This)->vtbl->GetImageOffset(This, level, layer, faceSlice, pOffset)

/**
 * @~English
 * @brief Helper for calling the GetDataSizeUncompressed virtual method of a ktxTexture.
 *
 * For a ktxTexture1 this will always return the value of This->dataSize.
 *
 * @copydetails ktxTexture2.ktxTexture2_GetDataSizeUncompressed
 */
#define ktxTexture_GetDataSizeUncompressed(This) \
                                (This)->vtbl->GetDataSizeUncompressed(This)

/**
 * @~English
 * @brief Helper for calling the GetImageSize virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_GetImageSize
 */
#define ktxTexture_GetImageSize(This, level) \
            (This)->vtbl->GetImageSize(This, level)

/**
 * @~English
 * @brief Helper for calling the GetImageSize virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_GetImageSize
 */
#define ktxTexture_GetLevelSize(This, level) \
            (This)->vtbl->GetLevelSize(This, level)

/**
 * @~English
 * @brief Helper for calling the IterateLevels virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_IterateLevels
 */
#define ktxTexture_IterateLevels(This, iterCb, userdata) \
                            (This)->vtbl->IterateLevels(This, iterCb, userdata)

/**
 * @~English
 * @brief Helper for calling the IterateLoadLevelFaces virtual method of a
 * ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_IterateLoadLevelFaces
 */
 #define ktxTexture_IterateLoadLevelFaces(This, iterCb, userdata) \
                    (This)->vtbl->IterateLoadLevelFaces(This, iterCb, userdata)

/**
 * @~English
 * @brief Helper for calling the LoadImageData virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_LoadImageData
 */
#define ktxTexture_LoadImageData(This, pBuffer, bufSize) \
                    (This)->vtbl->LoadImageData(This, pBuffer, bufSize)

/**
 * @~English
 * @brief Helper for calling the NeedsTranscoding virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_NeedsTranscoding
 */
#define ktxTexture_NeedsTranscoding(This) (This)->vtbl->NeedsTranscoding(This)

/**
 * @~English
 * @brief Helper for calling the SetImageFromMemory virtual method of a
 *        ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_SetImageFromMemory
 */
#define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, \
                                      src, srcSize)                  \
    (This)->vtbl->SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)

/**
 * @~English
 * @brief Helper for calling the SetImageFromStdioStream virtual method of a
 *        ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_SetImageFromStdioStream
 */
#define ktxTexture_SetImageFromStdioStream(This, level, layer, faceSlice, \
                                           src, srcSize)                  \
    (This)->vtbl->SetImageFromStdioStream(This, level, layer, faceSlice,  \
                                        src, srcSize)

/**
 * @~English
 * @brief Helper for calling the WriteToStdioStream virtual method of a
 *        ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_WriteToStdioStream
 */
#define ktxTexture_WriteToStdioStream(This, dstsstr) \
                                (This)->vtbl->WriteToStdioStream(This, dstsstr)

/**
 * @~English
 * @brief Helper for calling the WriteToNamedfile virtual method of a
 *        ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_WriteToNamedFile
 */
#define ktxTexture_WriteToNamedFile(This, dstname) \
                                (This)->vtbl->WriteToNamedFile(This, dstname)

/**
 * @~English
 * @brief Helper for calling the WriteToMemory virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_WriteToMemory
 */
#define ktxTexture_WriteToMemory(This, ppDstBytes, pSize) \
                  (This)->vtbl->WriteToMemory(This, ppDstBytes, pSize)

/**
 * @~English
 * @brief Helper for calling the WriteToStream virtual method of a ktxTexture.
 * @copydoc ktxTexture2.ktxTexture2_WriteToStream
 */
#define ktxTexture_WriteToStream(This, dststr) \
                  (This)->vtbl->WriteToStream(This, dststr)


/**
 * @class ktxTexture1
 * @~English
 * @brief Class representing a KTX version 1 format texture.
 *
 * ktxTextures should be created only by one of the ktxTexture_Create*
 * functions and these fields should be considered read-only.
 */
typedef struct ktxTexture1 {
    KTXTEXTURECLASSDEFN
    ktx_uint32_t glFormat; /*!< Format of the texture data, e.g., GL_RGB. */
    ktx_uint32_t glInternalformat; /*!< Internal format of the texture data,
                                        e.g., GL_RGB8. */
    ktx_uint32_t glBaseInternalformat; /*!< Base format of the texture data,
                                            e.g., GL_RGB. */
    ktx_uint32_t glType; /*!< Type of the texture data, e.g, GL_UNSIGNED_BYTE.*/
    struct ktxTexture1_private* _private; /*!< Private data. */
} ktxTexture1;

/*===========================================================*
* KTX format version 2                                      *
*===========================================================*/

/**
 * @~English
 * @brief Enumerators identifying the supercompression scheme.
 */
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_ZLIB,
    KTX_SS_BEGIN_VENDOR_RANGE = 0x10000,
    KTX_SS_END_VENDOR_RANGE = 0x1ffff,
    KTX_SS_BEGIN_RESERVED = 0x20000
} ktxSupercmpScheme;

/**
 * @class ktxTexture2
 * @~English
 * @brief Class representing a KTX version 2 format texture.
 *
 * ktxTextures should be created only by one of the ktxTexture_Create*
 * functions and these fields should be considered read-only.
 */
typedef struct ktxTexture2 {
    KTXTEXTURECLASSDEFN
    ktx_uint32_t  vkFormat;
    ktx_uint32_t* pDfd;
    ktxSupercmpScheme supercompressionScheme;
    ktx_bool_t isVideo;
    ktx_uint32_t duration;
    ktx_uint32_t timescale;
    ktx_uint32_t loopcount;
    struct ktxTexture2_private* _private;  /*!< Private data. */
} ktxTexture2;

/*
 * If Doxygen sees this macro it gets confused and fails to spot
 * references to ktxTexture_*() functions in the running text. It
 * also complains it can't find the reference when @ref is used
 * with a fully qualified method name to make an intra-class
 * reference in the @c ktxTexture class.
 * See https://github.com/doxygen/doxygen/issues/10311.
 *
 * Not documenting the macro is the lesser of two evils.
 */
#if !defined(KTX_DOXYGEN_SKIP)
    /**
     * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.
     *
     * Use with caution.
     */
    #define ktxTexture(t) ((ktxTexture*)t)
#endif

/**
 * @memberof ktxTexture
 * @~English
 * @brief Structure for passing texture information to ktxTexture1\_Create() and
 *        ktxTexture2\_Create().
 *
 * @sa @ref ktxTexture1::ktxTexture1\_Create() "ktxTexture1_Create()"
 * @sa @ref ktxTexture2::ktxTexture2\_Create() "ktxTexture2_Create()"
 */
typedef struct
{
    ktx_uint32_t glInternalformat; /*!< Internal format for the texture, e.g.,
                                        GL_RGB8. Ignored when creating a
                                        ktxTexture2. */
    ktx_uint32_t vkFormat;   /*!< VkFormat for texture. Ignored when creating a
                                  ktxTexture1. */
    ktx_uint32_t* pDfd;      /*!< Pointer to DFD. Used only when creating a
                                  ktxTexture2 and only if vkFormat is
                                  VK_FORMAT_UNDEFINED. */
    ktx_uint32_t baseWidth;  /*!< Width of the base level of the texture. */
    ktx_uint32_t baseHeight; /*!< Height of the base level of the texture. */
    ktx_uint32_t baseDepth;  /*!< Depth of the base level of the texture. */
    ktx_uint32_t numDimensions; /*!< Number of dimensions in the texture, 1, 2
                                     or 3. */
    ktx_uint32_t numLevels; /*!< Number of mip levels in the texture. Should be
                                 1 if @c generateMipmaps is KTX_TRUE; */
    ktx_uint32_t numLayers; /*!< Number of array layers in the texture. */
    ktx_uint32_t numFaces;  /*!< Number of faces: 6 for cube maps, 1 otherwise. */
    ktx_bool_t   isArray;  /*!< Set to KTX_TRUE if the texture is to be an
                                array texture. Means OpenGL will use a
                                GL_TEXTURE_*_ARRAY target. */
    ktx_bool_t   generateMipmaps; /*!< Set to KTX_TRUE if mipmaps should be
                                       generated for the texture when loading
                                       into a 3D API. */
} ktxTextureCreateInfo;

/**
 * @memberof ktxTexture
 * @~English
 * @brief Enum for requesting, or not, allocation of storage for images.
 *
 * @sa ktxTexture1_Create() and ktxTexture2_Create().
 */
typedef enum {
    KTX_TEXTURE_CREATE_NO_STORAGE = 0,  /*!< Don't allocate any image storage. */
    KTX_TEXTURE_CREATE_ALLOC_STORAGE = 1 /*!< Allocate image storage. */
} ktxTextureCreateStorageEnum;

/**
 * @memberof ktxTexture
 * @~English
 * @brief Flags for requesting services during creation.
 *
 * @sa ktxTexture_CreateFrom*
 */
enum ktxTextureCreateFlagBits {
    KTX_TEXTURE_CREATE_NO_FLAGS = 0x00,
    KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT = 0x01,
                                   /*!< Load the images from the KTX source. */
    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,
                                   /*!< 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
 * @~English
 * @brief Type for TextureCreateFlags parameters.
 *
 * @sa ktxTexture_CreateFrom*()
 */
typedef ktx_uint32_t ktxTextureCreateFlags;

/*===========================================================*
* ktxStream
*===========================================================*/

/*
 * This is unsigned to allow ktxmemstreams to use the
 * full amount of memory available. Platforms will
 * limit the size of ktxfilestreams to, e.g, MAX_LONG
 * on 32-bit and ktxfilestreams raises errors if
 * offset values exceed the limits. This choice may
 * need to be revisited if we ever start needing -ve
 * offsets.
 *
 * Should the 2GB file size handling limit on 32-bit
 * platforms become a problem, ktxfilestream will have
 * to be changed to explicitly handle large files by
 * using the 64-bit stream functions.
 */
#if defined(_MSC_VER) && defined(_WIN64)
  typedef unsigned __int64 ktx_off_t;
#else
  typedef   off_t ktx_off_t;
#endif
typedef struct ktxMem ktxMem;
typedef struct ktxStream ktxStream;

enum streamType { eStreamTypeFile = 1, eStreamTypeMemory = 2, eStreamTypeCustom = 3 };

/**
 * @~English
 * @brief type for a pointer to a stream reading function
 */
typedef KTX_error_code (*ktxStream_read)(ktxStream* str, void* dst,
                                         const ktx_size_t count);
/**
 * @~English
 * @brief type for a pointer to a stream skipping function
 */
typedef KTX_error_code (*ktxStream_skip)(ktxStream* str,
                                         const ktx_size_t count);

/**
 * @~English
 * @brief type for a pointer to a stream writing function
 */
typedef KTX_error_code (*ktxStream_write)(ktxStream* str, const void *src,
                                          const ktx_size_t size,
                                          const ktx_size_t count);

/**
 * @~English
 * @brief type for a pointer to a stream position query function
 */
typedef KTX_error_code (*ktxStream_getpos)(ktxStream* str, ktx_off_t* const offset);

/**
 * @~English
 * @brief type for a pointer to a stream position query function
 */
typedef KTX_error_code (*ktxStream_setpos)(ktxStream* str, const ktx_off_t offset);

/**
 * @~English
 * @brief type for a pointer to a stream size query function
 */
typedef KTX_error_code (*ktxStream_getsize)(ktxStream* str, ktx_size_t* const size);

/**
 * @~English
 * @brief Destruct a stream
 */
typedef void (*ktxStream_destruct)(ktxStream* str);

/**
 * @~English
 *
 * @brief Interface of ktxStream.
 *
 * @author Maksim Kolesin
 * @author Georg Kolling, Imagination Technology
 * @author Mark Callow, HI Corporation
 */
struct ktxStream
{
    ktxStream_read read;   /*!< pointer to function for reading bytes. */
    ktxStream_skip skip;   /*!< pointer to function for skipping bytes. */
    ktxStream_write write; /*!< pointer to function for writing bytes. */
    ktxStream_getpos getpos; /*!< pointer to function for getting current position in stream. */
    ktxStream_setpos setpos; /*!< pointer to function for setting current position in stream. */
    ktxStream_getsize getsize; /*!< pointer to function for querying size. */
    ktxStream_destruct destruct; /*!< destruct the stream. */

    enum streamType type;
    union {
        FILE* file;        /**< a stdio FILE pointer for a ktxFileStream. */
        ktxMem* mem;       /**< a pointer to a ktxMem struct for a ktxMemStream. */
        struct
        {
            void* address;           /**< pointer to the data. */
            void* allocatorAddress;  /**< pointer to a memory allocator. */
            ktx_size_t size;         /**< size of the data. */
        } custom_ptr;      /**< pointer to a struct for custom streams. */
    } data;                /**< pointer to the stream data. */
    ktx_off_t readpos;     /**< used by FileStream for stdin. */
    ktx_bool_t closeOnDestruct; /**< Close FILE* or dispose of memory on destruct. */
};

/*
 * See the implementation files for the full documentation of the following
 * functions.
 */

/**
 * @~English
 * @brief typedef of function pointer returned by GLGetProcAddress functions.
 */
typedef void (KTX_APIENTRY* PFNVOIDFUNCTION)(void);
/**
 * @~English
 * @brief typedef of pointer to function for retrieving OpenGL function pointers.
 */
typedef PFNVOIDFUNCTION (KTX_APIENTRY* PFNGLGETPROCADDRESS) (const char *proc);
/*
 * Load pointers for the OpenGL functions needed by ktxTexture_GLUpload.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxLoadOpenGL(PFNGLGETPROCADDRESS pfnGLGetProcAddress);

/*
 * These four create a ktxTexture1 or ktxTexture2 according to the data
 * header, and return a pointer to the base ktxTexture class.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_CreateFromStdioStream(FILE* stdioStream,
                                 ktxTextureCreateFlags createFlags,
                                 ktxTexture** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_CreateFromNamedFile(const char* const filename,
                               ktxTextureCreateFlags createFlags,
                               ktxTexture** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size,
                            ktxTextureCreateFlags createFlags,
                            ktxTexture** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_CreateFromStream(ktxStream* stream,
                            ktxTextureCreateFlags createFlags,
                            ktxTexture** newTex);

/*
 * Returns a pointer to the image data of a ktxTexture object.
 */
KTX_API ktx_uint8_t* KTX_APIENTRY
ktxTexture_GetData(ktxTexture* This);

/*
 * Returns the pitch of a row of an image at the specified level.
 * Similar to the rowPitch in a VkSubResourceLayout.
 */
KTX_API ktx_uint32_t KTX_APIENTRY
ktxTexture_GetRowPitch(ktxTexture* This, ktx_uint32_t level);

 /*
  * Return the element size of the texture's images.
  */
KTX_API ktx_uint32_t KTX_APIENTRY
ktxTexture_GetElementSize(ktxTexture* This);

/*
 * Returns the size of all the image data of a ktxTexture object in bytes.
 */
KTX_API ktx_size_t KTX_APIENTRY
ktxTexture_GetDataSize(ktxTexture* This);

/* Uploads a texture to OpenGL {,ES}. */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_GLUpload(ktxTexture* This, GLuint* pTexture, GLenum* pTarget,
                    GLenum* pGlerror);

/*
 * Iterate over the levels or faces in a ktxTexture object.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_IterateLevelFaces(ktxTexture* This, PFNKTXITERCB iterCb,
                             void* userdata);
/*
 * Create a new ktxTexture1.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_Create(const ktxTextureCreateInfo* const createInfo,
                   ktxTextureCreateStorageEnum storageAllocation,
                   ktxTexture1** newTex);

/*
 * These four create a ktxTexture1 provided the data is in KTX format.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_CreateFromStdioStream(FILE* stdioStream,
                                 ktxTextureCreateFlags createFlags,
                                 ktxTexture1** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_CreateFromNamedFile(const char* const filename,
                               ktxTextureCreateFlags createFlags,
                               ktxTexture1** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size,
                            ktxTextureCreateFlags createFlags,
                            ktxTexture1** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_CreateFromStream(ktxStream* stream,
                             ktxTextureCreateFlags createFlags,
                             ktxTexture1** newTex);
KTX_API void KTX_APIENTRY
ktxTexture1_Destroy(ktxTexture1* This);

KTX_API ktx_bool_t KTX_APIENTRY
ktxTexture1_NeedsTranscoding(ktxTexture1* This);

KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture1_LoadImageData(ktxTexture1* This, ktx_uint8_t* pBuffer, ktx_size_t bufSize);

/*
 * These four write a ktxTexture1 object to a KTX v1 file.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteToStdioStream(ktxTexture1* This, FILE* dstsstr);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteToNamedFile(ktxTexture1* This, const char* const dstname);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteToMemory(ktxTexture1* This,
                             ktx_uint8_t** bytes, ktx_size_t* size);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteToStream(ktxTexture1* This, ktxStream *dststr);

/*
 * These four write a ktxTexture1 object to a KTX v2 file.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteKTX2ToStdioStream(ktxTexture1* This, FILE* dstsstr);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteKTX2ToNamedFile(ktxTexture1* This, const char* const dstname);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteKTX2ToMemory(ktxTexture1* This,
                             ktx_uint8_t** bytes, ktx_size_t* size);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_WriteKTX2ToStream(ktxTexture1* This, ktxStream *dststr);

/*
 * Create a new ktxTexture2.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_Create(const ktxTextureCreateInfo* const createInfo,
                   ktxTextureCreateStorageEnum storageAllocation,
                   ktxTexture2** newTex);

/*
 * Create a new ktxTexture2 as a copy of an existing texture.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CreateCopy(ktxTexture2* orig, ktxTexture2** newTex);

 /*
  * These four create a ktxTexture2 provided the data is in KTX2 format.
  */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CreateFromStdioStream(FILE* stdioStream,
                                 ktxTextureCreateFlags createFlags,
                                 ktxTexture2** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CreateFromNamedFile(const char* const filename,
                               ktxTextureCreateFlags createFlags,
                               ktxTexture2** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size,
                            ktxTextureCreateFlags createFlags,
                            ktxTexture2** newTex);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CreateFromStream(ktxStream* stream,
                             ktxTextureCreateFlags createFlags,
                             ktxTexture2** newTex);

KTX_API void KTX_APIENTRY
ktxTexture2_Destroy(ktxTexture2* This);

KTX_API KTX_error_code KTX_APIENTRY
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);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_GetImageOffset(ktxTexture2* This, ktx_uint32_t level,
                           ktx_uint32_t layer, ktx_uint32_t faceSlice,
                           ktx_size_t* pOffset);

KTX_API ktx_uint32_t KTX_APIENTRY
ktxTexture2_GetNumComponents(ktxTexture2* This);

KTX_API khr_df_transfer_e KTX_APIENTRY
ktxTexture2_GetTransferFunction_e(ktxTexture2* This);
/* For backward compatibility. */
KTX_API khr_df_transfer_e KTX_APIENTRY
ktxTexture2_GetOETF_e(ktxTexture2* This);
KTX_API ktx_uint32_t KTX_APIENTRY
ktxTexture2_GetOETF(ktxTexture2* This);

KTX_API khr_df_model_e KTX_APIENTRY
ktxTexture2_GetColorModel_e(ktxTexture2* This);

KTX_API ktx_bool_t KTX_APIENTRY
ktxTexture2_GetPremultipliedAlpha(ktxTexture2* This);

KTX_API khr_df_primaries_e KTX_APIENTRY
ktxTexture2_GetPrimaries_e(ktxTexture2* This);

KTX_API ktx_bool_t KTX_APIENTRY
ktxTexture2_NeedsTranscoding(ktxTexture2* This);

KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture2_SetTransferFunction(ktxTexture2* This, khr_df_transfer_e tf);
/* For backward compatibility. */
KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture2_SetOETF(ktxTexture2* This, khr_df_transfer_e oetf);

KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture2_SetPrimaries(ktxTexture2* This, khr_df_primaries_e primaries);

KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture2_LoadImageData(ktxTexture2* This, ktx_uint8_t* pBuffer, ktx_size_t bufSize);
/*
 * For rare testing scenarios. Use ktxTexture2_LoadImageData.
 */
KTX_API ktx_error_code_e KTX_APIENTRY
ktxTexture2_LoadDeflatedImageData(ktxTexture2* This,
                                  ktx_uint8_t* pBuffer, ktx_size_t bufSize);

/*
 * These four write a ktxTexture2 object to a KTX v2 file.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_WriteToStdioStream(ktxTexture2* This, FILE* dstsstr);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_WriteToNamedFile(ktxTexture2* This, const char* const dstname);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_WriteToMemory(ktxTexture2* This,
                             ktx_uint8_t** bytes, ktx_size_t* size);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_WriteToStream(ktxTexture2* This, ktxStream *dststr);

/**
 * @~English
 * @brief Flags specifiying UASTC encoding options.
 */
typedef enum ktx_pack_uastc_flag_bits_e {
    KTX_PACK_UASTC_LEVEL_FASTEST  = 0,
        /*!< Fastest compression. 43.45dB. */
    KTX_PACK_UASTC_LEVEL_FASTER   = 1,
        /*!< Faster compression. 46.49dB. */
    KTX_PACK_UASTC_LEVEL_DEFAULT  = 2,
        /*!< Default compression. 47.47dB. */
    KTX_PACK_UASTC_LEVEL_SLOWER   = 3,
        /*!< Slower compression. 48.01dB. */
    KTX_PACK_UASTC_LEVEL_VERYSLOW = 4,
        /*!< Very slow compression. 48.24dB. */
    KTX_PACK_UASTC_MAX_LEVEL = KTX_PACK_UASTC_LEVEL_VERYSLOW,
        /*!< Maximum supported quality level. */
    KTX_PACK_UASTC_LEVEL_MASK     = 0xF,
        /*!< Mask to extract the level from the other bits. */
    KTX_PACK_UASTC_FAVOR_UASTC_ERROR = 8,
        /*!< Optimize for lowest UASTC error. */
    KTX_PACK_UASTC_FAVOR_BC7_ERROR = 16,
        /*!< Optimize for lowest BC7 error. */
    KTX_PACK_UASTC_ETC1_FASTER_HINTS = 64,
        /*!< Optimize for faster transcoding to ETC1. */
    KTX_PACK_UASTC_ETC1_FASTEST_HINTS = 128,
        /*!< Optimize for fastest transcoding to ETC1. */
    KTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL = 256
        /*!< Not documented in BasisU code. */
} ktx_pack_uastc_flag_bits_e;
typedef ktx_uint32_t ktx_pack_uastc_flags;

/**
 * @~English
 * @brief Options specifiying ASTC encoding quality levels.
 */
typedef enum ktx_pack_astc_quality_levels_e {
    KTX_PACK_ASTC_QUALITY_LEVEL_FASTEST  = 0,
        /*!< Fastest compression. */
    KTX_PACK_ASTC_QUALITY_LEVEL_FAST   = 10,
        /*!< Fast compression. */
    KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM   = 60,
        /*!< Medium compression. */
    KTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH   = 98,
        /*!< Slower compression. */
    KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE = 100,
        /*!< Very slow compression. */
    KTX_PACK_ASTC_QUALITY_LEVEL_MAX = KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE,
        /*!< Maximum supported quality level. */
} ktx_pack_astc_quality_levels_e;

/**
 * @~English
 * @brief Options specifiying ASTC encoding block dimensions
 */
typedef enum ktx_pack_astc_block_dimension_e {
    // 2D formats
    KTX_PACK_ASTC_BLOCK_DIMENSION_4x4,                    //: 8.00 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_5x4,                    //: 6.40 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_5x5,                    //: 5.12 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_6x5,                    //: 4.27 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_6x6,                    //: 3.56 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_8x5,                    //: 3.20 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_8x6,                    //: 2.67 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_10x5,                   //: 2.56 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_10x6,                   //: 2.13 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_8x8,                    //: 2.00 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_10x8,                   //: 1.60 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_10x10,                  //: 1.28 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_12x10,                  //: 1.07 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_12x12,                  //: 0.89 bpp
    // 3D formats
    KTX_PACK_ASTC_BLOCK_DIMENSION_3x3x3,                  //: 4.74 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_4x3x3,                  //: 3.56 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_4x4x3,                  //: 2.67 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_4x4x4,                  //: 2.00 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_5x4x4,                  //: 1.60 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_5x5x4,                  //: 1.28 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_5x5x5,                  //: 1.02 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_6x5x5,                  //: 0.85 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x5,                  //: 0.71 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x6,                  //: 0.59 bpp
    KTX_PACK_ASTC_BLOCK_DIMENSION_MAX = KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x6
        /*!< Maximum supported blocks. */
} ktx_pack_astc_block_dimension_e;

/**
 * @~English
 * @brief Options specifying ASTC encoder mode.
 */
typedef enum ktx_pack_astc_encoder_mode_e {
    KTX_PACK_ASTC_ENCODER_MODE_DEFAULT,
        /*!< Selects LDR mode if component size is <= 8-bit, HDR otherwise. */
    KTX_PACK_ASTC_ENCODER_MODE_LDR,
        /*!< Always encode in low dynamic range mode. */
    KTX_PACK_ASTC_ENCODER_MODE_HDR,
        /*!< Always encode in high dynamic range mode. */
    KTX_PACK_ASTC_ENCODER_MODE_MAX = KTX_PACK_ASTC_ENCODER_MODE_HDR
        /*!< Indicates the maximum permissible value. */
} ktx_pack_astc_encoder_mode_e;

extern KTX_API const ktx_uint32_t KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;

/**
 * @memberof ktxTexture
 * @~English
 * @brief Structure for passing extended parameters to
 *        ktxTexture_CompressAstc.
 *
 * Passing a struct initialized to 0 (e.g. " = {0};") will use blockDimension
 * 4x4, mode LDR and qualityLevel FASTEST. Setting qualityLevel to
 * KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM is recommended.
 */
typedef struct ktxAstcParams {
    ktx_uint32_t structSize;
        /*!< Size of this struct. Used so library can tell which version
             of struct is being passed.
         */

    ktx_bool_t verbose;
        /*!< If true, prints Astc encoder operation details to
             @c stdout. Not recommended for GUI apps.
         */

    ktx_uint32_t threadCount;
        /*!< Number of threads used for compression. Default is 1.
         */

    /* astcenc params */
    ktx_uint32_t blockDimension;
        /*!< Combinations of block dimensions that astcenc supports
          i.e. 6x6, 8x8, 6x5 etc
         */

    ktx_uint32_t mode;
        /*!< Can be {ldr/hdr} from astcenc
         */

    ktx_uint32_t qualityLevel;
        /*!< astcenc supports -fastest, -fast, -medium, -thorough, -exhaustive
         */

    ktx_bool_t normalMap;
        /*!< Tunes codec parameters for better quality on normal maps
          In this mode normals are compressed to X,Y components
          Discarding Z component, reader will need to generate Z
          component in shaders.
         */

    ktx_bool_t perceptual;
        /*!< The codec should optimize for perceptual error, instead of direct
           RMS error. This aims to improves perceived image quality, but
           typically lowers the measured PSNR score. Perceptual methods are
           currently only available for normal maps and RGB color data.
         */

    char inputSwizzle[4];
         /*!< A swizzle to provide as input to astcenc. It must match the regular
             expression /^[rgba01]{4}$/.
          */
} ktxAstcParams;

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CompressAstcEx(ktxTexture2* This, ktxAstcParams* params);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CompressAstc(ktxTexture2* This, ktx_uint32_t quality);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_DecodeAstc(ktxTexture2* This);

/**
 * @memberof ktxTexture2
 * @~English
 * @brief Structure for passing extended parameters to
 *        ktxTexture2_CompressBasisEx().
 *
 * If you only want default values, use ktxTexture2_CompressBasis(). Here, at
 * a minimum you must initialize the structure as follows:
 * @code
 *  ktxBasisParams params = {0};
 *  params.structSize = sizeof(params);
 *  params.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;
 * @endcode
 *
 * @e compressionLevel has to be explicitly set because 0 is a valid
 * @e compressionLevel but is not the default used by the BasisU encoder
 * when no value is set. Only the other settings that are to be non-default
 * must be non-zero.
 */
typedef struct ktxBasisParams {
    ktx_uint32_t structSize;
        /*!< Size of this struct. Used so library can tell which version
             of struct is being passed.
         */
    ktx_bool_t uastc;
        /*!<  True to use UASTC base, false to use ETC1S base. */
    ktx_bool_t verbose;
        /*!< If true, prints Basis Universal encoder operation details to
             @c stdout. Not recommended for GUI apps.
         */
    ktx_bool_t noSSE;
        /*!< True to forbid use of the SSE instruction set. Ignored if CPU
             does not support SSE. */
    ktx_uint32_t threadCount;
        /*!< Number of threads used for compression. Default is 1. */

    /* ETC1S params */

    ktx_uint32_t compressionLevel;
        /*!< Encoding speed vs. quality tradeoff. Range is [0,6]. Higher values
             are much slower, but give slightly higher quality. Higher levels
             are intended for video. There is no default. Callers must
             explicitly set this value. Callers can use
             KTX\_ETC1S\_DEFAULT\_COMPRESSION\_LEVEL as a default value.
             Currently this is 2.
        */
    ktx_uint32_t qualityLevel;
        /*!< Compression quality. Range is [1,255].  Lower gives better
             compression/lower quality/faster. Higher gives less compression
             /higher quality/slower.  This automatically determines values for
             @c maxEndpoints, @c maxSelectors,
             @c endpointRDOThreshold and @c selectorRDOThreshold
             for the target quality level. Setting these parameters overrides
             the values determined by @c qualityLevel which defaults to
             128 if neither it nor both of @c maxEndpoints and
             @c maxSelectors have been set.
             @note @e Both of @c maxEndpoints and @c maxSelectors
             must be set for them to have any effect.
             @note qualityLevel will only determine values for
             @c endpointRDOThreshold and @c selectorRDOThreshold
             when its value exceeds 128, otherwise their defaults will be used.
        */
    ktx_uint32_t maxEndpoints;
        /*!< Manually set the max number of color endpoint clusters.
             Range is [1,16128]. Default is 0, unset. If this is set, maxSelectors
             must also be set, otherwise the value will be ignored.
         */
    float endpointRDOThreshold;
        /*!< Set endpoint RDO quality threshold. The default is 1.25. Lower is
             higher quality but less quality per output bit (try [1.0,3.0].
             This will override the value chosen by @c qualityLevel.
         */
    ktx_uint32_t maxSelectors;
        /*!< Manually set the max number of color selector clusters. Range
             is [1,16128]. Default is 0, unset. If this is set, maxEndpoints
             must also be set, otherwise the value will be ignored.
         */
    float selectorRDOThreshold;
        /*!< Set selector RDO quality threshold. The default is 1.5. Lower is
             higher quality but less quality per output bit (try [1.0,3.0]).
             This will override the value chosen by @c qualityLevel.
         */
    char inputSwizzle[4];
        /*!< A swizzle to apply before encoding. It must match the regular
             expression /^[rgba01]{4}$/. If both this and preSwizzle
             are specified ktxTexture_CompressBasisEx will raise
             KTX_INVALID_OPERATION. Usable with both ETC1S and UASTC.
         */
    ktx_bool_t normalMap;
        /*!< Tunes codec parameters for better quality on normal maps (no
             selector RDO, no endpoint RDO) and sets the texture's DFD appropriately.
             Only valid for linear textures.
         */
    ktx_bool_t separateRGToRGB_A;
        /*!< @deprecated This was and is a no-op. 2-component inputs have
            always been automatically separated using an "rrrg" inputSwizzle.
            @sa inputSwizzle and normalMode.
         */
    ktx_bool_t preSwizzle;
        /*!< If the texture has @c KTXswizzle metadata, apply it before
             compressing. Swizzling, like @c rabb may yield drastically
             different error metrics if done after supercompression. Usable
             for both ETC1S and UASTC.
         */
    ktx_bool_t noEndpointRDO;
        /*!< Disable endpoint rate distortion optimizations. Slightly faster,
             less noisy output, but lower quality per output bit. Default is
             KTX_FALSE.
         */
    ktx_bool_t noSelectorRDO;
        /*!< Disable selector rate distortion optimizations. Slightly faster,
             less noisy output, but lower quality per output bit. Default is
             KTX_FALSE.
         */

    /* UASTC params */

    ktx_pack_uastc_flags uastcFlags;
        /*!<  A set of ::ktx_pack_uastc_flag_bits_e controlling UASTC
             encoding. The most important value is the level given in the
             least-significant 4 bits which selects a speed vs quality tradeoff
             as shown in the following table:

                Level/Speed | Quality
                :-----: | :-------:
                KTX_PACK_UASTC_LEVEL_FASTEST | 43.45dB
                KTX_PACK_UASTC_LEVEL_FASTER | 46.49dB
                KTX_PACK_UASTC_LEVEL_DEFAULT | 47.47dB
                KTX_PACK_UASTC_LEVEL_SLOWER  | 48.01dB
                KTX_PACK_UASTC_LEVEL_VERYSLOW | 48.24dB
         */
    ktx_bool_t uastcRDO;
        /*!< Enable Rate Distortion Optimization (RDO) post-processing.
         */
    float uastcRDOQualityScalar;
        /*!< UASTC RDO quality scalar (lambda). Lower values yield higher
             quality/larger LZ compressed files, higher values yield lower
             quality/smaller LZ compressed files. A good range to try is [.2,4].
             Full range is [.001,50.0]. Default is 1.0.
         */
    ktx_uint32_t uastcRDODictSize;
        /*!< UASTC RDO dictionary size in bytes. Default is 4096. Lower
             values=faster, but give less compression. Range is [64,65536].
         */
    float uastcRDOMaxSmoothBlockErrorScale;
        /*!< UASTC RDO max smooth block error scale. Range is [1,300].
             Default is 10.0, 1.0 is disabled. Larger values suppress more
             artifacts (and allocate more bits) on smooth blocks.
         */
    float uastcRDOMaxSmoothBlockStdDev;
        /*!< UASTC RDO max smooth block standard deviation. Range is
             [.01,65536.0]. Default is 18.0. Larger values expand the range of
             blocks considered smooth.
         */
    ktx_bool_t uastcRDODontFavorSimplerModes;
        /*!< Do not favor simpler UASTC modes in RDO mode.
         */
    ktx_bool_t uastcRDONoMultithreading;
        /*!< Disable RDO multithreading (slightly higher compression,
             deterministic).
         */

} ktxBasisParams;

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_CompressBasisEx(ktxTexture2* This, ktxBasisParams* params);

/**
 * @~English
 * @brief Enumerators for specifying the transcode target format.
 *
 * For BasisU/ETC1S format, @e Opaque and @e alpha here refer to 2 separate
 * RGB images, a.k.a slices within the BasisU compressed data. For UASTC
 * format they refer to the RGB and the alpha components of the UASTC data. If
 * the original image had only 2 components, R will be in the opaque portion
 * and G in the alpha portion. The R value will be replicated in the RGB
 * components. In the case of BasisU the G value will be replicated in all 3
 * components of the alpha slice. If the original image had only 1 component
 * it's value is replicated in all 3 components of the opaque portion and
 * there is no alpha.
 *
 * @note You should not transcode sRGB encoded data to @c KTX_TTF_BC4_R,
 * @c KTX_TTF_BC5_RG, @c KTX_TTF_ETC2_EAC_R{,G}11, @c KTX_TTF_RGB565,
 * @c KTX_TTF_BGR565 or @c KTX_TTF_RGBA4444 formats as neither OpenGL nor
 * Vulkan support sRGB variants of these. Doing sRGB decoding in the shader
 * will not produce correct results if any texture filtering is being used.
 */
typedef enum ktx_transcode_fmt_e {
        // Compressed formats

        // ETC1-2
        KTX_TTF_ETC1_RGB = 0,
            /*!< Opaque only. Returns RGB or alpha data, if
                 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is
                 specified. */
        KTX_TTF_ETC2_RGBA = 1,
            /*!< Opaque+alpha. EAC_A8 block followed by an ETC1 block. The
                 alpha channel will be opaque for textures without an alpha
                 channel. */

        // BC1-5, BC7 (desktop, some mobile devices)
        KTX_TTF_BC1_RGB = 2,
            /*!< Opaque only, no punchthrough alpha support yet.  Returns RGB
                 or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS
                 flag is specified. */
        KTX_TTF_BC3_RGBA = 3,
            /*!< Opaque+alpha. BC4 block with alpha followed by a BC1 block. The
                 alpha channel will be opaque for textures without an alpha
                 channel. */
        KTX_TTF_BC4_R = 4,
            /*!< One BC4 block. R = opaque.g or alpha.g, if
                 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is
                 specified. */
        KTX_TTF_BC5_RG = 5,
            /*!< Two BC4 blocks, R=opaque.g and G=alpha.g The texture should
                 have an alpha channel (if not G will be all 255's. For tangent
                 space normal maps. */
        KTX_TTF_BC7_RGBA = 6,
            /*!< RGB or RGBA mode 5 for ETC1S, modes 1, 2, 3, 4, 5, 6, 7 for
                 UASTC. */

        // PVRTC1 4bpp (mobile, PowerVR devices)
        KTX_TTF_PVRTC1_4_RGB = 8,
            /*!< Opaque only. Returns RGB or alpha data, if
                 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is
                 specified. */
        KTX_TTF_PVRTC1_4_RGBA = 9,
            /*!< Opaque+alpha. Most useful for simple opacity maps. If the
                 texture doesn't have an alpha channel KTX_TTF_PVRTC1_4_RGB
                 will be used instead. Lowest quality of any supported
                 texture format. */

        // ASTC (mobile, Intel devices, hopefully all desktop GPU's one day)
        KTX_TTF_ASTC_4x4_RGBA = 10,
            /*!< Opaque+alpha, ASTC 4x4. The alpha channel will be opaque for
                 textures without an alpha channel.  The transcoder uses
                 RGB/RGBA/L/LA modes, void extent, and up to two ([0,47] and
                 [0,255]) endpoint precisions. */

        // ATC and FXT1 formats are not supported by KTX2 as there
        // are no equivalent VkFormats.

        KTX_TTF_PVRTC2_4_RGB = 18,
            /*!< Opaque-only. Almost BC1 quality, much faster to transcode
                 and supports arbitrary texture dimensions (unlike
                 PVRTC1 RGB). */
        KTX_TTF_PVRTC2_4_RGBA = 19,
            /*!< Opaque+alpha. Slower to transcode than cTFPVRTC2_4_RGB.
                 Premultiplied alpha is highly recommended, otherwise the
                 color channel can leak into the alpha channel on transparent
                 blocks. */

        KTX_TTF_ETC2_EAC_R11 = 20,
            /*!< R only (ETC2 EAC R11 unsigned). R = opaque.g or alpha.g, if
                 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is
                 specified. */
        KTX_TTF_ETC2_EAC_RG11 = 21,
            /*!< RG only (ETC2 EAC RG11 unsigned), R=opaque.g, G=alpha.g. The
                 texture should have an alpha channel (if not G will be all
                 255's. For tangent space normal maps. */

        // Uncompressed (raw pixel) formats
        KTX_TTF_RGBA32 = 13,
            /*!< 32bpp RGBA image stored in raster (not block) order in
                 memory, R is first byte, A is last byte. */
        KTX_TTF_RGB565 = 14,
            /*!< 16bpp RGB image stored in raster (not block) order in memory,
                 R at bit position 11. */
        KTX_TTF_BGR565 = 15,
            /*!< 16bpp RGB image stored in raster (not block) order in memory,
                 R at bit position 0. */
        KTX_TTF_RGBA4444 = 16,
            /*!< 16bpp RGBA image stored in raster (not block) order in memory,
                 R at bit position 12, A at bit position 0. */

        // Values for automatic selection of RGB or RGBA depending if alpha
        // present.
        KTX_TTF_ETC = 22,
            /*!< Automatically selects @c KTX_TTF_ETC1_RGB or
                 @c KTX_TTF_ETC2_RGBA according to presence of alpha. */
        KTX_TTF_BC1_OR_3 = 23,
            /*!< Automatically selects @c KTX_TTF_BC1_RGB or
                 @c KTX_TTF_BC3_RGBA according to presence of alpha. */

        KTX_TTF_NOSELECTION = 0x7fffffff,

        // Old enums for compatibility with code compiled against previous
        // versions of libktx.
        KTX_TF_ETC1 = KTX_TTF_ETC1_RGB,
            //!< @deprecated Use #KTX_TTF_ETC1_RGB.
        KTX_TF_ETC2 = KTX_TTF_ETC,
            //!< @deprecated Use #KTX_TTF_ETC.
        KTX_TF_BC1 = KTX_TTF_BC1_RGB,
            //!< @deprecated Use #KTX_TTF_BC1_RGB.
        KTX_TF_BC3 = KTX_TTF_BC3_RGBA,
            //!< @deprecated Use #KTX_TTF_BC3_RGBA.
        KTX_TF_BC4 = KTX_TTF_BC4_R,
            //!< @deprecated Use #KTX_TTF_BC4_R.
        KTX_TF_BC5 = KTX_TTF_BC5_RG,
            //!< @deprecated Use #KTX_TTF_BC5_RG.
        KTX_TTF_BC7_M6_RGB = KTX_TTF_BC7_RGBA,
            //!< @deprecated Use #KTX_TTF_BC7_RGBA.
        KTX_TTF_BC7_M5_RGBA = KTX_TTF_BC7_RGBA,
            //!< @deprecated Use #KTX_TTF_BC7_RGBA.
        KTX_TF_BC7_M6_OPAQUE_ONLY = KTX_TTF_BC7_RGBA,
            //!< @deprecated Use #KTX_TTF_BC7_RGBA
        KTX_TF_PVRTC1_4_OPAQUE_ONLY = KTX_TTF_PVRTC1_4_RGB
            //!< @deprecated Use #KTX_TTF_PVRTC1_4_RGB.
} ktx_transcode_fmt_e;

/**
 * @~English
 * @brief Flags guiding transcoding of Basis Universal compressed textures.
 */
typedef enum ktx_transcode_flag_bits_e {
    KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 = 2,
        /*!< PVRTC1: decode non-pow2 ETC1S texture level to the next larger
             power of 2 (not implemented yet, but we're going to support it).
             Ignored if the slice's dimensions are already a power of 2.
         */
    KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS = 4,
        /*!< When decoding to an opaque texture format, if the Basis data has
             alpha, decode the alpha slice instead of the color slice to the
             output texture format. Has no effect if there is no alpha data.
         */
    KTX_TF_HIGH_QUALITY = 32,
        /*!< Request higher quality transcode of UASTC to BC1, BC3, ETC2_EAC_R11 and
             ETC2_EAC_RG11. The flag is unused by other UASTC transcoders.
         */
} ktx_transcode_flag_bits_e;
typedef ktx_uint32_t ktx_transcode_flags;

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_TranscodeBasis(ktxTexture2* This, ktx_transcode_fmt_e fmt,
                           ktx_transcode_flags transcodeFlags);

/*
 * Returns a string corresponding to a KTX error code.
 */
KTX_API const char* KTX_APIENTRY
ktxErrorString(KTX_error_code error);

/*
 * Returns a string corresponding to a supercompression scheme.
 */
KTX_API const char* KTX_APIENTRY
ktxSupercompressionSchemeString(ktxSupercmpScheme scheme);

/*
 * Returns a string corresponding to a transcode target format.
 */
KTX_API const char* KTX_APIENTRY
ktxTranscodeFormatString(ktx_transcode_fmt_e format);

KTX_API KTX_error_code KTX_APIENTRY ktxHashList_Create(ktxHashList** ppHl);
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_CreateCopy(ktxHashList** ppHl, ktxHashList orig);
KTX_API void KTX_APIENTRY ktxHashList_Construct(ktxHashList* pHl);
KTX_API void KTX_APIENTRY
ktxHashList_ConstructCopy(ktxHashList* pHl, ktxHashList orig);
KTX_API void KTX_APIENTRY ktxHashList_Destroy(ktxHashList* head);
KTX_API void KTX_APIENTRY ktxHashList_Destruct(ktxHashList* head);

/*
 * Adds a key-value pair to a hash list.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_AddKVPair(ktxHashList* pHead, const char* key,
                      unsigned int valueLen, const void* value);

/*
 * Deletes a ktxHashListEntry from a ktxHashList.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_DeleteEntry(ktxHashList* pHead,  ktxHashListEntry* pEntry);

/*
 * Finds the entry for a key in a ktxHashList and deletes it.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_DeleteKVPair(ktxHashList* pHead, const char* key);

/*
 * Looks up a key and returns the ktxHashListEntry.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_FindEntry(ktxHashList* pHead, const char* key,
                      ktxHashListEntry** ppEntry);

/*
 * Looks up a key and returns the value.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_FindValue(ktxHashList* pHead, const char* key,
                      unsigned int* pValueLen, void** pValue);

/*
 * Return the next entry in a ktxHashList.
 */
KTX_API ktxHashListEntry* KTX_APIENTRY
ktxHashList_Next(ktxHashListEntry* entry);

/*
 * Sorts a ktxHashList into order of the key codepoints.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_Sort(ktxHashList* pHead);

/*
 * Serializes a ktxHashList to a block of memory suitable for
 * writing to a KTX file.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_Serialize(ktxHashList* pHead,
                      unsigned int* kvdLen, unsigned char** kvd);

/*
 * Creates a hash table from the serialized data read from a
 * a KTX file.
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashList_Deserialize(ktxHashList* pHead, unsigned int kvdLen, void* kvd);

/*
 * Get the key from a ktxHashListEntry
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashListEntry_GetKey(ktxHashListEntry* This,
                        unsigned int* pKeyLen, char** ppKey);

/*
 * Get the value from a ktxHashListEntry
 */
KTX_API KTX_error_code KTX_APIENTRY
ktxHashListEntry_GetValue(ktxHashListEntry* This,
                          unsigned int* pValueLen, void** ppValue);

/*===========================================================*
 * Utilities for printing info about a KTX file.             *
 *===========================================================*/

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 KTX v1 file.          *
 *===========================================================*/

 KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX1InfoTextForStream(ktxStream* stream);

/*===========================================================*
 * Utilities for printing info about a KTX v2 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

/**
@~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.
@li Support for encoding and transcoding Basis Universal images in KTX Version 2 files.
@li Function to print info about a KTX file.

@section v7 Version 3.0.1
Fixed:
@li GitHub issue #159: compile failure with recent Vulkan SDKs.
@li Incorrect mapping of GL DXT3 and DXT5 formats to Vulkan equivalents.
@li Incorrect BC4 blocksize.
@li Missing mapping of PVRTC formats from GL to Vulkan.
@li Incorrect block width and height calculations for sizes that are not
    a multiple of the block size.
@li Incorrect KTXorientation key in test images.

@section v6 Version 3.0
Added:
@li new ktxTexture object based API for reading KTX files without an OpenGL context.
@li Vulkan loader. @#include <ktxvulkan.h> to use it.

Changed:
@li ktx.h to not depend on KHR/khrplatform.h and GL{,ES*}/gl{corearb,}.h.
    Applications using OpenGL must now include these files themselves.
@li ktxLoadTexture[FMN], removing the hack of loading 1D textures as 2D textures
    when the OpenGL context does not support 1D textures.
    KTX_UNSUPPORTED_TEXTURE_TYPE is now returned.

@section v5 Version 2.0.2
Added:
@li Support for cubemap arrays.

Changed:
@li New build system

Fixed:
@li GitHub issue #40: failure to byte-swap key-value lengths.
@li GitHub issue #33: returning incorrect target when loading cubemaps.
@li GitHub PR #42: loading of texture arrays.
@li GitHub PR #41: compilation error when KTX_OPENGL_ES2=1 defined.
@li GitHub issue #39: stack-buffer-overflow in toktx
@li Don't use GL_EXTENSIONS on recent OpenGL versions.

@section v4 Version 2.0.1
Added:
@li CMake build files. Thanks to Pavel Rotjberg for the initial version.

Changed:
@li ktxWriteKTXF to check the validity of the type & format combinations
    passed to it.

Fixed:
@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=999">999</a>: 16-bit luminance texture cannot be written.
@li compile warnings from compilers stricter than MS Visual C++. Thanks to
    Pavel Rotjberg.

@section v3 Version 2.0
Added:
@li support for decoding ETC2 and EAC formats in the absence of a hardware
    decoder.
@li support for converting textures with legacy LUMINANCE, LUMINANCE_ALPHA,
    etc. formats to the equivalent R, RG, etc. format with an
    appropriate swizzle, when loading in OpenGL Core Profile contexts.
@li ktxErrorString function to return a string corresponding to an error code.
@li tests for ktxLoadTexture[FN] that run under OpenGL ES 3.0 and OpenGL 3.3.
    The latter includes an EGL on WGL wrapper that makes porting apps between
    OpenGL ES and OpenGL easier on Windows.
@li more texture formats to ktxLoadTexture[FN] and toktx tests.

Changed:
@li ktxLoadTexture[FMN] to discover the capabilities of the GL context at
    run time and load textures, or not, according to those capabilities.

Fixed:
@li failure of ktxWriteKTXF to pad image rows to 4 bytes as required by the KTX
    format.
@li ktxWriteKTXF exiting with KTX_FILE_WRITE_ERROR when attempting to write
    more than 1 byte of face-LOD padding.

Although there is only a very minor API change, the addition of ktxErrorString,
the functional changes are large enough to justify bumping the major revision
number.

@section v2 Version 1.0.1
Implemented ktxLoadTextureM.
Fixed the following:
@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=571">571</a>: crash when null passed for pIsMipmapped.
@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=572">572</a>: memory leak when unpacking ETC textures.
@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=573">573</a>: potential crash when unpacking ETC textures with unused padding pixels.
@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=576">576</a>: various small fixes.

Thanks to Krystian Bigaj for the ktxLoadTextureM implementation and these fixes.

@section v1 Version 1.0
Initial release.

*/

#endif /* KTX_H_A55A6F00956F42F3A137C11929827FE1 */