/* -*- 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 … #elif _MSC_VER #define KTX_API … #else #error "Your compiler's equivalent of dllimport is unknown" #endif #endif #elif defined(__ANDROID__) #define KTX_API … #else #define KTX_API #endif #if defined(_WIN32) && !defined(KHRONOS_STATIC) #if !defined(KTX_APIENTRY) #define KTX_APIENTRY … #endif #else #define KTX_APIENTRY #endif /* To avoid including <KHR/khrplatform.h> define our own types. */ ktx_uint8_t; 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> ktx_uint16_t; ktx_int16_t; ktx_uint32_t; ktx_int32_t; ktx_size_t; ktx_uint64_t; ktx_int64_t; #endif /* This will cause compilation to fail if size of uint32 != 4. */ ktx_uint32_t_SIZE_ASSERT; /* * 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 ... */ GLboolean; GLenum; GLint; GLsizei; GLuint; GLubyte; #endif #ifdef __cplusplus extern "C" { #endif /** * @~English * @brief Key string for standard writer metadata. */ #define KTX_ANIMDATA_KEY … /** * @~English * @brief Key string for standard orientation metadata. */ #define KTX_ORIENTATION_KEY … /** * @~English * @brief Key string for standard swizzle metadata. */ #define KTX_SWIZZLE_KEY … /** * @~English * @brief Key string for standard writer metadata. */ #define KTX_WRITER_KEY … /** * @~English * @brief Key string for standard writer supercompression parameter metadata. */ #define KTX_WRITER_SCPARAMS_KEY … /** * @~English * @brief Standard KTX 1 format for 1D orientation value. */ #define KTX_ORIENTATION1_FMT … /** * @~English * @brief Standard KTX 1 format for 2D orientation value. */ #define KTX_ORIENTATION2_FMT … /** * @~English * @brief Standard KTX 1 format for 3D orientation value. */ #define KTX_ORIENTATION3_FMT … /** * @~English * @brief Required unpack alignment */ #define KTX_GL_UNPACK_ALIGNMENT … #define KTX_FACESLICE_WHOLE_LEVEL … #define KTX_TRUE … #define KTX_FALSE … /** * @~English * @brief Error codes returned by library functions. */ ktx_error_code_e; /** * @deprecated * @~English * @brief For backward compatibility */ #define KTX_error_code … #define KTX_IDENTIFIER_REF … #define KTX_ENDIAN_REF … #define KTX_ENDIAN_REF_REV … #define KTX_HEADER_SIZE … /** * @~English * @brief Result codes returned by library functions. */ ktxResult; /** * @class ktxHashList * @~English * @brief Opaque handle to a ktxHashList. */ ktxHashList; ktxStream; #define KTX_APIENTRYP … /** * @class ktxHashListEntry * @~English * @brief Opaque handle to an entry in a @ref ktxHashList. */ ktxHashListEntry; ktxOrientationX; ktxOrientationY; ktxOrientationZ; class_id; /** * @~English * @brief Struct describing the logical orientation of an image. */ struct ktxOrientation { … }; #define KTXTEXTURECLASSDEFN … /** * @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. */ 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::isCubemap * @~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(). */ /**n * @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. */ PFNKTXITERCB; /* Don't use KTX_APIENTRYP to avoid a Doxygen bug. */ PFNKTEXDESTROY; PFNKTEXGETIMAGEOFFSET; PFNKTEXGETDATASIZEUNCOMPRESSED; PFNKTEXGETIMAGESIZE; PFNKTEXITERATELEVELS; PFNKTEXITERATELOADLEVELFACES; PFNKTEXLOADIMAGEDATA; PFNKTEXNEEDSTRANSCODING; PFNKTEXSETIMAGEFROMMEMORY; PFNKTEXSETIMAGEFROMSTDIOSTREAM; PFNKTEXWRITETOSTDIOSTREAM; PFNKTEXWRITETONAMEDFILE; PFNKTEXWRITETOMEMORY; PFNKTEXWRITETOSTREAM; /** * @memberof ktxTexture * @~English * @brief Table of virtual ktxTexture methods. */ struct ktxTexture_vtbl { … }; /**************************************************************** * 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) … /** * @~English * @brief Helper for calling the GetImageOffset virtual method of a * ktxTexture. * @copydoc ktxTexture2.ktxTexture2_GetImageOffset */ #define ktxTexture_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) … /** * @~English * @brief Helper for calling the GetImageSize virtual method of a ktxTexture. * @copydoc ktxTexture2.ktxTexture2_GetImageSize */ #define ktxTexture_GetImageSize(This, level) … /** * @~English * @brief Helper for calling the IterateLevels virtual method of a ktxTexture. * @copydoc ktxTexture2.ktxTexture2_IterateLevels */ #define ktxTexture_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) … /** * @~English * @brief Helper for calling the LoadImageData virtual method of a ktxTexture. * @copydoc ktxTexture2.ktxTexture2_LoadImageData */ #define ktxTexture_LoadImageData(This, pBuffer, bufSize) … /** * @~English * @brief Helper for calling the NeedsTranscoding virtual method of a ktxTexture. * @copydoc ktxTexture2.ktxTexture2_NeedsTranscoding */ #define ktxTexture_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) … /** * @~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) … /** * @~English * @brief Helper for calling the WriteToStdioStream virtual method of a * ktxTexture. * @copydoc ktxTexture2.ktxTexture2_WriteToStdioStream */ #define ktxTexture_WriteToStdioStream(This, dstsstr) … /** * @~English * @brief Helper for calling the WriteToNamedfile virtual method of a * ktxTexture. * @copydoc ktxTexture2.ktxTexture2_WriteToNamedFile */ #define ktxTexture_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) … /** * @~English * @brief Helper for calling the WriteToStream virtual method of a ktxTexture. * @copydoc ktxTexture2.ktxTexture2_WriteToStream */ #define ktxTexture_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. */ ktxTexture1; /*===========================================================* * KTX format version 2 * *===========================================================*/ /** * @~English * @brief Enumerators identifying the supercompression scheme. */ 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. */ ktxTexture2; /** * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture. * * Use with caution. */ #define ktxTexture(t) … /** * @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()" */ ktxTextureCreateInfo; /** * @memberof ktxTexture * @~English * @brief Enum for requesting, or not, allocation of storage for images. * * @sa ktxTexture1_Create() and ktxTexture2_Create(). */ ktxTextureCreateStorageEnum; /** * @memberof ktxTexture * @~English * @brief Flags for requesting services during creation. * * @sa ktxTexture_CreateFrom* */ enum ktxTextureCreateFlagBits { … }; /** * @memberof ktxTexture * @~English * @brief Type for TextureCreateFlags parameters. * * @sa ktxTexture_CreateFrom*() */ 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 ktx_off_t; #endif ktxMem; ktxStream; enum streamType { … }; /** * @~English * @brief type for a pointer to a stream reading function */ ktxStream_read; /** * @~English * @brief type for a pointer to a stream skipping function */ ktxStream_skip; /** * @~English * @brief type for a pointer to a stream writing function */ ktxStream_write; /** * @~English * @brief type for a pointer to a stream position query function */ ktxStream_getpos; /** * @~English * @brief type for a pointer to a stream position query function */ ktxStream_setpos; /** * @~English * @brief type for a pointer to a stream size query function */ ktxStream_getsize; /** * @~English * @brief Destruct a stream */ ktxStream_destruct; /** * @~English * * @brief Interface of ktxStream. * * @author Maksim Kolesin * @author Georg Kolling, Imagination Technology * @author Mark Callow, HI Corporation */ struct ktxStream { … }; /* * See the implementation files for the full documentation of the following * functions. */ /* * 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(ktxTextureCreateInfo* 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 ktx_bool_t KTX_APIENTRY ktxTexture1_NeedsTranscoding(ktxTexture1* This); /* * Write a ktxTexture object to a stdio stream in KTX format. */ KTX_API KTX_error_code KTX_APIENTRY ktxTexture1_WriteKTX2ToStdioStream(ktxTexture1* This, FILE* dstsstr); /* * Write a ktxTexture object to a named file in KTX format. */ KTX_API KTX_error_code KTX_APIENTRY ktxTexture1_WriteKTX2ToNamedFile(ktxTexture1* This, const char* const dstname); /* * Write a ktxTexture object to a block of memory in KTX format. */ KTX_API KTX_error_code KTX_APIENTRY ktxTexture1_WriteKTX2ToMemory(ktxTexture1* This, ktx_uint8_t** bytes, ktx_size_t* size); /* * Write a ktxTexture object to a ktxStream in KTX format. */ 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(ktxTextureCreateInfo* 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 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_uint32_t KTX_APIENTRY ktxTexture2_GetNumComponents(ktxTexture2* This); KTX_API khr_df_transfer_e KTX_APIENTRY ktxTexture2_GetOETF_e(ktxTexture2* This); // For backward compatibility 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 ktx_bool_t KTX_APIENTRY ktxTexture2_NeedsTranscoding(ktxTexture2* This); /** * @~English * @brief Flags specifiying UASTC encoding options. */ ktx_pack_uastc_flag_bits_e; ktx_pack_uastc_flags; /** * @~English * @brief Options specifiying ASTC encoding quality levels. */ ktx_pack_astc_quality_levels_e; /** * @~English * @brief Options specifiying ASTC encoding block dimensions */ ktx_pack_astc_block_dimension_e; /** * @~English * @brief Options specifying ASTC encoder profile mode * This and function is used later to derive the profile. */ 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. */ 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); /** * @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. */ 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. */ ktx_transcode_fmt_e; /** * @~English * @brief Flags guiding transcoding of Basis Universal compressed textures. */ ktx_transcode_flag_bits_e; 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 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 /*========================================================================* * For backward compatibilty with the V3 & early versions of the V4 APIs. * *========================================================================*/ /** * @deprecated Will be dropped before V4 release. */ #define ktx_texture_transcode_fmt_e … /** * @deprecated Will be dropped before V4 release. */ #define ktx_texture_decode_flags … /** * @deprecated Will be dropped before V4 release. */ #define ktxTexture_GetSize … /** @~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 */
Codebase Browser
godot