1/* -*- tab-width: 4; -*- */ 
2/* vi: set sw=2 ts=4 expandtab: */ 
3 
4#ifndef KTX_H_A55A6F00956F42F3A137C11929827FE1 
5#define KTX_H_A55A6F00956F42F3A137C11929827FE1 
6 
7/* 
8 * Copyright 2010-2018 The Khronos Group, Inc. 
9 * SPDX-License-Identifier: Apache-2.0 
10 * 
11 * See the accompanying LICENSE.md for licensing details for all files in 
12 * the KTX library and KTX loader tests. 
13 */ 
14 
15/** 
16 * @file 
17 * @~English 
18 * 
19 * @brief Declares the public functions and structures of the 
20 * KTX API. 
21 * 
22 * @author Mark Callow, Edgewise Consulting and while at HI Corporation 
23 * @author Based on original work by Georg Kolling, Imagination Technology 
24 * 
25 * @snippet{doc} version.h API version 
26 */ 
27 
28#include <limits.h> 
29#include <stdio.h> 
30#include <stdbool.h> 
31#include <sys/types.h> 
32 
33#include <KHR/khr_df.h> 
34 
35/* 
36 * Don't use khrplatform.h in order not to break apps existing 
37 * before these definitions were needed. 
38 */ 
39#if defined(KHRONOS_STATIC) 
40 #define KTX_API 
41#elif defined(_WIN32) || defined(__CYGWIN__) 
42 #if !defined(KTX_API) 
43 #if __GNUC__ 
44 #define KTX_API __attribute__ ((dllimport)) 
45 #elif _MSC_VER 
46 #define KTX_API __declspec(dllimport) 
47 #else 
48 #error "Your compiler's equivalent of dllimport is unknown" 
49 #endif 
50 #endif 
51#elif defined(__ANDROID__) 
52 #define KTX_API __attribute__((visibility("default"))) 
53#else 
54 #define KTX_API 
55#endif 
56 
57#if defined(_WIN32) && !defined(KHRONOS_STATIC) 
58 #if !defined(KTX_APIENTRY) 
59 #define KTX_APIENTRY __stdcall 
60 #endif 
61#else 
62 #define KTX_APIENTRY 
63#endif 
64 
65/* To avoid including <KHR/khrplatform.h> define our own types. */ 
66typedef unsigned char ktx_uint8_t; 
67typedef bool ktx_bool_t; 
68#ifdef _MSC_VER 
69typedef unsigned __int16 ktx_uint16_t; 
70typedef signed __int16 ktx_int16_t; 
71typedef unsigned __int32 ktx_uint32_t; 
72typedef signed __int32 ktx_int32_t; 
73typedef size_t ktx_size_t; 
74typedef unsigned __int64 ktx_uint64_t; 
75typedef signed __int64 ktx_int64_t; 
76#else 
77#include <stdint.h> 
78typedef uint16_t ktx_uint16_t; 
79typedef int16_t ktx_int16_t; 
80typedef uint32_t ktx_uint32_t; 
81typedef int32_t ktx_int32_t; 
82typedef size_t ktx_size_t; 
83typedef uint64_t ktx_uint64_t; 
84typedef int64_t ktx_int64_t; 
85#endif 
86 
87/* This will cause compilation to fail if size of uint32 != 4. */ 
88typedef unsigned char ktx_uint32_t_SIZE_ASSERT[sizeof(ktx_uint32_t) == 4]; 
89 
90/* 
91 * This #if allows libktx to be compiled with strict c99. It avoids 
92 * compiler warnings or even errors when a gl.h is already included. 
93 * "Redefinition of (type) is a c11 feature". Obviously this doesn't help if 
94 * gl.h comes after. However nobody has complained about the unguarded typedefs 
95 * since they were introduced so this is unlikely to be a problem in practice. 
96 * Presumably everybody is using platform default compilers not c99 or else 
97 * they are using C++. 
98 */ 
99#if !defined(GL_NO_ERROR) 
100 /* 
101 * To avoid having to including gl.h ... 
102 */ 
103 typedef unsigned char GLboolean; 
104 typedef unsigned int GLenum; 
105 typedef int GLint; 
106 typedef int GLsizei; 
107 typedef unsigned int GLuint; 
108 typedef unsigned char GLubyte; 
109#endif 
110 
111#ifdef __cplusplus 
112extern "C" { 
113#endif 
114 
115/** 
116 * @~English 
117 * @brief Key string for standard writer metadata. 
118 */ 
119#define KTX_ANIMDATA_KEY "KTXanimData" 
120/** 
121 * @~English 
122 * @brief Key string for standard orientation metadata. 
123 */ 
124#define KTX_ORIENTATION_KEY "KTXorientation" 
125/** 
126 * @~English 
127 * @brief Key string for standard swizzle metadata. 
128 */ 
129#define KTX_SWIZZLE_KEY "KTXswizzle" 
130/** 
131 * @~English 
132 * @brief Key string for standard writer metadata. 
133 */ 
134#define KTX_WRITER_KEY "KTXwriter" 
135/** 
136 * @~English 
137 * @brief Key string for standard writer supercompression parameter metadata. 
138 */ 
139#define KTX_WRITER_SCPARAMS_KEY "KTXwriterScParams" 
140/** 
141 * @~English 
142 * @brief Standard KTX 1 format for 1D orientation value. 
143 */ 
144#define KTX_ORIENTATION1_FMT "S=%c" 
145/** 
146 * @~English 
147 * @brief Standard KTX 1 format for 2D orientation value. 
148 */ 
149#define KTX_ORIENTATION2_FMT "S=%c,T=%c" 
150/** 
151 * @~English 
152 * @brief Standard KTX 1 format for 3D orientation value. 
153 */ 
154#define KTX_ORIENTATION3_FMT "S=%c,T=%c,R=%c" 
155/** 
156 * @~English 
157 * @brief Required unpack alignment 
158 */ 
159#define KTX_GL_UNPACK_ALIGNMENT 4 
160#define KTX_FACESLICE_WHOLE_LEVEL UINT_MAX 
161 
162#define KTX_TRUE true 
163#define KTX_FALSE false 
164 
165/** 
166 * @~English 
167 * @brief Error codes returned by library functions. 
168 */ 
169typedef enum ktx_error_code_e { 
170 KTX_SUCCESS = 0, /*!< Operation was successful. */ 
171 KTX_FILE_DATA_ERROR, /*!< The data in the file is inconsistent with the spec. */ 
172 KTX_FILE_ISPIPE, /*!< The file is a pipe or named pipe. */ 
173 KTX_FILE_OPEN_FAILED, /*!< The target file could not be opened. */ 
174 KTX_FILE_OVERFLOW, /*!< The operation would exceed the max file size. */ 
175 KTX_FILE_READ_ERROR, /*!< An error occurred while reading from the file. */ 
176 KTX_FILE_SEEK_ERROR, /*!< An error occurred while seeking in the file. */ 
177 KTX_FILE_UNEXPECTED_EOF, /*!< File does not have enough data to satisfy request. */ 
178 KTX_FILE_WRITE_ERROR, /*!< An error occurred while writing to the file. */ 
179 KTX_GL_ERROR, /*!< GL operations resulted in an error. */ 
180 KTX_INVALID_OPERATION, /*!< The operation is not allowed in the current state. */ 
181 KTX_INVALID_VALUE, /*!< A parameter value was not valid. */ 
182 KTX_NOT_FOUND, /*!< Requested metadata key or required dynamically loaded GPU function was not found. */ 
183 KTX_OUT_OF_MEMORY, /*!< Not enough memory to complete the operation. */ 
184 KTX_TRANSCODE_FAILED, /*!< Transcoding of block compressed texture failed. */ 
185 KTX_UNKNOWN_FILE_FORMAT, /*!< The file not a KTX file */ 
186 KTX_UNSUPPORTED_TEXTURE_TYPE, /*!< The KTX file specifies an unsupported texture type. */ 
187 KTX_UNSUPPORTED_FEATURE, /*!< Feature not included in in-use library or not yet implemented. */ 
188 KTX_LIBRARY_NOT_LINKED, /*!< Library dependency (OpenGL or Vulkan) not linked into application. */ 
189 KTX_DECOMPRESS_LENGTH_ERROR, /*!< Decompressed byte count does not match expected byte size */ 
190 KTX_DECOMPRESS_CHECKSUM_ERROR, /*!< Checksum mismatch when decompressing */ 
191 KTX_ERROR_MAX_ENUM = KTX_DECOMPRESS_CHECKSUM_ERROR /*!< For safety checks. */ 
192} ktx_error_code_e; 
193/** 
194 * @~English 
195 * @deprecated Use #ktx_error_code_e. 
196 * @brief For backward compatibility 
197 */ 
198#define KTX_error_code ktx_error_code_e 
199 
200#define KTX_IDENTIFIER_REF { 0xAB, 0x4B, 0x54, 0x58, 0x20, 0x31, 0x31, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A } 
201#define KTX_ENDIAN_REF (0x04030201) 
202#define KTX_ENDIAN_REF_REV (0x01020304) 
203#define KTX_HEADER_SIZE (64) 
204 
205/** 
206 * @~English 
207 * @brief Result codes returned by library functions. 
208 */ 
209 typedef enum ktx_error_code_e ktxResult; 
210 
211/** 
212 * @class ktxHashList 
213 * @~English 
214 * @brief Opaque handle to a ktxHashList. 
215 */ 
216typedef struct ktxKVListEntry* ktxHashList; 
217 
218typedef struct ktxStream ktxStream; 
219 
220#define KTX_APIENTRYP KTX_APIENTRY * 
221/** 
222 * @class ktxHashListEntry 
223 * @~English 
224 * @brief Opaque handle to an entry in a @ref ktxHashList. 
225 */ 
226typedef struct ktxKVListEntry ktxHashListEntry; 
227 
228typedef enum ktxOrientationX { 
229 KTX_ORIENT_X_LEFT = 'l', KTX_ORIENT_X_RIGHT = 'r' 
230} ktxOrientationX; 
231 
232typedef enum ktxOrientationY { 
233 KTX_ORIENT_Y_UP = 'u', KTX_ORIENT_Y_DOWN = 'd' 
234} ktxOrientationY; 
235 
236typedef enum ktxOrientationZ { 
237 KTX_ORIENT_Z_IN = 'i', KTX_ORIENT_Z_OUT = 'o' 
238} ktxOrientationZ; 
239 
240typedef enum class_id { 
241 ktxTexture1_c = 1, 
242 ktxTexture2_c = 2 
243} class_id; 
244 
245/** 
246 * @~English 
247 * @brief Struct describing the logical orientation of an image. 
248 */ 
249struct ktxOrientation { 
250 ktxOrientationX x; /*!< Orientation in X */ 
251 ktxOrientationY y; /*!< Orientation in Y */ 
252 ktxOrientationZ z; /*!< Orientation in Z */ 
253}; 
254 
255#define KTXTEXTURECLASSDEFN \ 
256 class_id classId; \ 
257 struct ktxTexture_vtbl* vtbl; \ 
258 struct ktxTexture_vvtbl* vvtbl; \ 
259 struct ktxTexture_protected* _protected; \ 
260 ktx_bool_t isArray; \ 
261 ktx_bool_t isCubemap; \ 
262 ktx_bool_t isCompressed; \ 
263 ktx_bool_t generateMipmaps; \ 
264 ktx_uint32_t baseWidth; \ 
265 ktx_uint32_t baseHeight; \ 
266 ktx_uint32_t baseDepth; \ 
267 ktx_uint32_t numDimensions; \ 
268 ktx_uint32_t numLevels; \ 
269 ktx_uint32_t numLayers; \ 
270 ktx_uint32_t numFaces; \ 
271 struct ktxOrientation orientation; \ 
272 ktxHashList kvDataHead; \ 
273 ktx_uint32_t kvDataLen; \ 
274 ktx_uint8_t* kvData; \ 
275 ktx_size_t dataSize; \ 
276 ktx_uint8_t* pData; 
277 
278 
279/** 
280 * @class ktxTexture 
281 * @~English 
282 * @brief Base class representing a texture. 
283 * 
284 * ktxTextures should be created only by one of the provided 
285 * functions and these fields should be considered read-only. 
286 */ 
287typedef struct ktxTexture { 
288 KTXTEXTURECLASSDEFN 
289} ktxTexture; 
290/** 
291 * @typedef ktxTexture::classId 
292 * @~English 
293 * @brief Identify the class type. 
294 * 
295 * Since there are no public ktxTexture constructors, this can only have 
296 * values of ktxTexture1_c or ktxTexture2_c. 
297 */ 
298/** 
299 * @typedef ktxTexture::vtbl 
300 * @~English 
301 * @brief Pointer to the class's vtble. 
302 */ 
303/** 
304 * @typedef ktxTexture::vvtbl 
305 * @~English 
306 * @brief Pointer to the class's vtble for Vulkan functions. 
307 * 
308 * A separate vtble is used so this header does not need to include vulkan.h. 
309 */ 
310/** 
311 * @typedef ktxTexture::_protected 
312 * @~English 
313 * @brief Opaque pointer to the class's protected variables. 
314 */ 
315/** 
316 * @typedef ktxTexture::isArray 
317 * @~English 
318 * 
319 * KTX_TRUE if the texture is an array texture, i.e, 
320 * a GL_TEXTURE_*_ARRAY target is to be used. 
321 */ 
322/** 
323 * @typedef ktxTexture::isCubemap 
324 * @~English 
325 * 
326 * KTX_TRUE if the texture is a cubemap or cubemap array. 
327 */ 
328/** 
329 * @typedef ktxTexture::isCompressed 
330 * @~English 
331 * 
332 * KTX_TRUE if the texture's format is a block compressed format. 
333 */ 
334/** 
335 * @typedef ktxTexture::generateMipmaps 
336 * @~English 
337 * 
338 * KTX_TRUE if mipmaps should be generated for the texture by 
339 * ktxTexture_GLUpload() or ktxTexture_VkUpload(). 
340 */ 
341/** 
342 * @typedef ktxTexture::baseWidth 
343 * @~English 
344 * @brief Width of the texture's base level. 
345 */ 
346/** 
347 * @typedef ktxTexture::baseHeight 
348 * @~English 
349 * @brief Height of the texture's base level. 
350 */ 
351/** 
352 * @typedef ktxTexture::baseDepth 
353 * @~English 
354 * @brief Depth of the texture's base level. 
355 */ 
356/** 
357 * @typedef ktxTexture::numDimensions 
358 * @~English 
359 * @brief Number of dimensions in the texture: 1, 2 or 3. 
360 */ 
361/** 
362 * @typedef ktxTexture::numLevels 
363 * @~English 
364 * @brief Number of mip levels in the texture. 
365 * 
366 * Must be 1, if @c generateMipmaps is KTX_TRUE. Can be less than a 
367 * full pyramid but always starts at the base level. 
368 */ 
369/** 
370 * @typedef ktxTexture::numLevels 
371 * @~English 
372 * @brief Number of array layers in the texture. 
373 */ 
374/** 
375 * @typedef ktxTexture::numFaces 
376 * @~English 
377 * @brief Number of faces: 6 for cube maps, 1 otherwise. 
378 */ 
379/** 
380 * @typedef ktxTexture::orientation 
381 * @~English 
382 * @brief Describes the logical orientation of the images in each dimension. 
383 * 
384 * ktxOrientationX for X, ktxOrientationY for Y and ktxOrientationZ for Z. 
385 */ 
386/** 
387 * @typedef ktxTexture::kvDataHead 
388 * @~English 
389 * @brief Head of the hash list of metadata. 
390 */ 
391/** 
392 * @typedef ktxTexture::kvDataLen 
393 * @~English 
394 * @brief Length of the metadata, if it has been extracted in its raw form, 
395 * otherwise 0. 
396 */ 
397/** 
398 * @typedef ktxTexture::kvData 
399 * @~English 
400 * @brief Pointer to the metadata, if it has been extracted in its raw form, 
401 * otherwise NULL. 
402 */ 
403/** 
404 * @typedef ktxTexture::dataSize 
405 * @~English 
406 * @brief Byte length of the texture's uncompressed image data. 
407 */ 
408/** 
409 * @typedef ktxTexture::pData 
410 * @~English 
411 * @brief Pointer to the start of the image data. 
412 */ 
413 
414/** 
415 * @memberof ktxTexture 
416 * @~English 
417 * @brief Signature of function called by the <tt>ktxTexture_Iterate*</tt> 
418 * functions to receive image data. 
419 * 
420 * The function parameters are used to pass values which change for each image. 
421 * Obtain values which are uniform across all images from the @c ktxTexture 
422 * object. 
423 * 
424 * @param [in] miplevel MIP level from 0 to the max level which is 
425 * dependent on the texture size. 
426 * @param [in] face usually 0; for cube maps, one of the 6 cube 
427 * faces in the order +X, -X, +Y, -Y, +Z, -Z, 
428 * 0 to 5. 
429 * @param [in] width width of the image. 
430 * @param [in] height height of the image or, for 1D textures 
431 * textures, 1. 
432 * @param [in] depth depth of the image or, for 1D & 2D 
433 * textures, 1. 
434 * @param [in] faceLodSize number of bytes of data pointed at by 
435 * @p pixels. 
436 * @param [in] pixels pointer to the image data. 
437 * @param [in,out] userdata pointer for the application to pass data to and 
438 * from the callback function. 
439 */ 
440 
441typedef KTX_error_code 
442 (* PFNKTXITERCB)(int miplevel, int face, 
443 int width, int height, int depth, 
444 ktx_uint64_t faceLodSize, 
445 void* pixels, void* userdata); 
446 
447/* Don't use KTX_APIENTRYP to avoid a Doxygen bug. */ 
448typedef void (KTX_APIENTRY* PFNKTEXDESTROY)(ktxTexture* This); 
449typedef KTX_error_code 
450 (KTX_APIENTRY* PFNKTEXGETIMAGEOFFSET)(ktxTexture* This, ktx_uint32_t level, 
451 ktx_uint32_t layer, 
452 ktx_uint32_t faceSlice, 
453 ktx_size_t* pOffset); 
454typedef ktx_size_t 
455 (KTX_APIENTRY* PFNKTEXGETDATASIZEUNCOMPRESSED)(ktxTexture* This); 
456typedef ktx_size_t 
457 (KTX_APIENTRY* PFNKTEXGETIMAGESIZE)(ktxTexture* This, ktx_uint32_t level); 
458typedef ktx_size_t 
459 (KTX_APIENTRY* PFNKTEXGETLEVELSIZE)(ktxTexture* This, ktx_uint32_t level); 
460typedef KTX_error_code 
461 (KTX_APIENTRY* PFNKTEXITERATELEVELS)(ktxTexture* This, PFNKTXITERCB iterCb, 
462 void* userdata); 
463 
464typedef KTX_error_code 
465 (KTX_APIENTRY* PFNKTEXITERATELOADLEVELFACES)(ktxTexture* This, 
466 PFNKTXITERCB iterCb, 
467 void* userdata); 
468typedef KTX_error_code 
469 (KTX_APIENTRY* PFNKTEXLOADIMAGEDATA)(ktxTexture* This, 
470 ktx_uint8_t* pBuffer, 
471 ktx_size_t bufSize); 
472typedef ktx_bool_t 
473 (KTX_APIENTRY* PFNKTEXNEEDSTRANSCODING)(ktxTexture* This); 
474 
475typedef KTX_error_code 
476 (KTX_APIENTRY* PFNKTEXSETIMAGEFROMMEMORY)(ktxTexture* This, 
477 ktx_uint32_t level, 
478 ktx_uint32_t layer, 
479 ktx_uint32_t faceSlice, 
480 const ktx_uint8_t* src, 
481 ktx_size_t srcSize); 
482 
483typedef KTX_error_code 
484 (KTX_APIENTRY* PFNKTEXSETIMAGEFROMSTDIOSTREAM)(ktxTexture* This, 
485 ktx_uint32_t level, 
486 ktx_uint32_t layer, 
487 ktx_uint32_t faceSlice, 
488 FILE* src, ktx_size_t srcSize); 
489typedef KTX_error_code 
490 (KTX_APIENTRY* PFNKTEXWRITETOSTDIOSTREAM)(ktxTexture* This, FILE* dstsstr); 
491typedef KTX_error_code 
492 (KTX_APIENTRY* PFNKTEXWRITETONAMEDFILE)(ktxTexture* This, 
493 const char* const dstname); 
494typedef KTX_error_code 
495 (KTX_APIENTRY* PFNKTEXWRITETOMEMORY)(ktxTexture* This, 
496 ktx_uint8_t** bytes, ktx_size_t* size); 
497typedef KTX_error_code 
498 (KTX_APIENTRY* PFNKTEXWRITETOSTREAM)(ktxTexture* This, 
499 ktxStream* dststr); 
500 
501/** 
502 * @memberof ktxTexture 
503 * @~English 
504 * @brief Table of virtual ktxTexture methods. 
505 */ 
506 struct ktxTexture_vtbl { 
507 PFNKTEXDESTROY Destroy; 
508 PFNKTEXGETIMAGEOFFSET GetImageOffset; 
509 PFNKTEXGETDATASIZEUNCOMPRESSED GetDataSizeUncompressed; 
510 PFNKTEXGETIMAGESIZE GetImageSize; 
511 PFNKTEXGETLEVELSIZE GetLevelSize; 
512 PFNKTEXITERATELEVELS IterateLevels; 
513 PFNKTEXITERATELOADLEVELFACES IterateLoadLevelFaces; 
514 PFNKTEXNEEDSTRANSCODING NeedsTranscoding; 
515 PFNKTEXLOADIMAGEDATA LoadImageData; 
516 PFNKTEXSETIMAGEFROMMEMORY SetImageFromMemory; 
517 PFNKTEXSETIMAGEFROMSTDIOSTREAM SetImageFromStdioStream; 
518 PFNKTEXWRITETOSTDIOSTREAM WriteToStdioStream; 
519 PFNKTEXWRITETONAMEDFILE WriteToNamedFile; 
520 PFNKTEXWRITETOMEMORY WriteToMemory; 
521 PFNKTEXWRITETOSTREAM WriteToStream; 
522}; 
523 
524/**************************************************************** 
525 * Macros to give some backward compatibility to the previous API 
526 ****************************************************************/ 
527 
528/** 
529 * @~English 
530 * @brief Helper for calling the Destroy virtual method of a ktxTexture. 
531 * @copydoc ktxTexture2.ktxTexture2_Destroy 
532 */ 
533#define ktxTexture_Destroy(This) (This)->vtbl->Destroy(This) 
534 
535/** 
536 * @~English 
537 * @brief Helper for calling the GetImageOffset virtual method of a 
538 * ktxTexture. 
539 * @copydoc ktxTexture2.ktxTexture2_GetImageOffset 
540 */ 
541#define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset) \ 
542 (This)->vtbl->GetImageOffset(This, level, layer, faceSlice, pOffset) 
543 
544/** 
545 * @~English 
546 * @brief Helper for calling the GetDataSizeUncompressed virtual method of a ktxTexture. 
547 * 
548 * For a ktxTexture1 this will always return the value of This->dataSize. 
549 * 
550 * @copydetails ktxTexture2.ktxTexture2_GetDataSizeUncompressed 
551 */ 
552#define ktxTexture_GetDataSizeUncompressed(This) \ 
553 (This)->vtbl->GetDataSizeUncompressed(This) 
554 
555/** 
556 * @~English 
557 * @brief Helper for calling the GetImageSize virtual method of a ktxTexture. 
558 * @copydoc ktxTexture2.ktxTexture2_GetImageSize 
559 */ 
560#define ktxTexture_GetImageSize(This, level) \ 
561 (This)->vtbl->GetImageSize(This, level) 
562 
563/** 
564 * @~English 
565 * @brief Helper for calling the GetImageSize virtual method of a ktxTexture. 
566 * @copydoc ktxTexture2.ktxTexture2_GetImageSize 
567 */ 
568#define ktxTexture_GetLevelSize(This, level) \ 
569 (This)->vtbl->GetLevelSize(This, level) 
570 
571/** 
572 * @~English 
573 * @brief Helper for calling the IterateLevels virtual method of a ktxTexture. 
574 * @copydoc ktxTexture2.ktxTexture2_IterateLevels 
575 */ 
576#define ktxTexture_IterateLevels(This, iterCb, userdata) \ 
577 (This)->vtbl->IterateLevels(This, iterCb, userdata) 
578 
579/** 
580 * @~English 
581 * @brief Helper for calling the IterateLoadLevelFaces virtual method of a 
582 * ktxTexture. 
583 * @copydoc ktxTexture2.ktxTexture2_IterateLoadLevelFaces 
584 */ 
585 #define ktxTexture_IterateLoadLevelFaces(This, iterCb, userdata) \ 
586 (This)->vtbl->IterateLoadLevelFaces(This, iterCb, userdata) 
587 
588/** 
589 * @~English 
590 * @brief Helper for calling the LoadImageData virtual method of a ktxTexture. 
591 * @copydoc ktxTexture2.ktxTexture2_LoadImageData 
592 */ 
593#define ktxTexture_LoadImageData(This, pBuffer, bufSize) \ 
594 (This)->vtbl->LoadImageData(This, pBuffer, bufSize) 
595 
596/** 
597 * @~English 
598 * @brief Helper for calling the NeedsTranscoding virtual method of a ktxTexture. 
599 * @copydoc ktxTexture2.ktxTexture2_NeedsTranscoding 
600 */ 
601#define ktxTexture_NeedsTranscoding(This) (This)->vtbl->NeedsTranscoding(This) 
602 
603/** 
604 * @~English 
605 * @brief Helper for calling the SetImageFromMemory virtual method of a 
606 * ktxTexture. 
607 * @copydoc ktxTexture2.ktxTexture2_SetImageFromMemory 
608 */ 
609#define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, \ 
610 src, srcSize) \ 
611 (This)->vtbl->SetImageFromMemory(This, level, layer, faceSlice, src, srcSize) 
612 
613/** 
614 * @~English 
615 * @brief Helper for calling the SetImageFromStdioStream virtual method of a 
616 * ktxTexture. 
617 * @copydoc ktxTexture2.ktxTexture2_SetImageFromStdioStream 
618 */ 
619#define ktxTexture_SetImageFromStdioStream(This, level, layer, faceSlice, \ 
620 src, srcSize) \ 
621 (This)->vtbl->SetImageFromStdioStream(This, level, layer, faceSlice, \ 
622 src, srcSize) 
623 
624/** 
625 * @~English 
626 * @brief Helper for calling the WriteToStdioStream virtual method of a 
627 * ktxTexture. 
628 * @copydoc ktxTexture2.ktxTexture2_WriteToStdioStream 
629 */ 
630#define ktxTexture_WriteToStdioStream(This, dstsstr) \ 
631 (This)->vtbl->WriteToStdioStream(This, dstsstr) 
632 
633/** 
634 * @~English 
635 * @brief Helper for calling the WriteToNamedfile virtual method of a 
636 * ktxTexture. 
637 * @copydoc ktxTexture2.ktxTexture2_WriteToNamedFile 
638 */ 
639#define ktxTexture_WriteToNamedFile(This, dstname) \ 
640 (This)->vtbl->WriteToNamedFile(This, dstname) 
641 
642/** 
643 * @~English 
644 * @brief Helper for calling the WriteToMemory virtual method of a ktxTexture. 
645 * @copydoc ktxTexture2.ktxTexture2_WriteToMemory 
646 */ 
647#define ktxTexture_WriteToMemory(This, ppDstBytes, pSize) \ 
648 (This)->vtbl->WriteToMemory(This, ppDstBytes, pSize) 
649 
650/** 
651 * @~English 
652 * @brief Helper for calling the WriteToStream virtual method of a ktxTexture. 
653 * @copydoc ktxTexture2.ktxTexture2_WriteToStream 
654 */ 
655#define ktxTexture_WriteToStream(This, dststr) \ 
656 (This)->vtbl->WriteToStream(This, dststr) 
657 
658 
659/** 
660 * @class ktxTexture1 
661 * @~English 
662 * @brief Class representing a KTX version 1 format texture. 
663 * 
664 * ktxTextures should be created only by one of the ktxTexture_Create* 
665 * functions and these fields should be considered read-only. 
666 */ 
667typedef struct ktxTexture1 { 
668 KTXTEXTURECLASSDEFN 
669 ktx_uint32_t glFormat; /*!< Format of the texture data, e.g., GL_RGB. */ 
670 ktx_uint32_t glInternalformat; /*!< Internal format of the texture data, 
671 e.g., GL_RGB8. */ 
672 ktx_uint32_t glBaseInternalformat; /*!< Base format of the texture data, 
673 e.g., GL_RGB. */ 
674 ktx_uint32_t glType; /*!< Type of the texture data, e.g, GL_UNSIGNED_BYTE.*/ 
675 struct ktxTexture1_private* _private; /*!< Private data. */ 
676} ktxTexture1; 
677 
678/*===========================================================* 
679* KTX format version 2 * 
680*===========================================================*/ 
681 
682/** 
683 * @~English 
684 * @brief Enumerators identifying the supercompression scheme. 
685 */ 
686typedef enum ktxSupercmpScheme { 
687 KTX_SS_NONE = 0, /*!< No supercompression. */ 
688 KTX_SS_BASIS_LZ = 1, /*!< Basis LZ supercompression. */ 
689 KTX_SS_ZSTD = 2, /*!< ZStd supercompression. */ 
690 KTX_SS_ZLIB = 3, /*!< ZLIB supercompression. */ 
691 KTX_SS_BEGIN_RANGE = KTX_SS_NONE, 
692 KTX_SS_END_RANGE = KTX_SS_ZLIB, 
693 KTX_SS_BEGIN_VENDOR_RANGE = 0x10000, 
694 KTX_SS_END_VENDOR_RANGE = 0x1ffff, 
695 KTX_SS_BEGIN_RESERVED = 0x20000 
696} ktxSupercmpScheme; 
697 
698/** 
699 * @class ktxTexture2 
700 * @~English 
701 * @brief Class representing a KTX version 2 format texture. 
702 * 
703 * ktxTextures should be created only by one of the ktxTexture_Create* 
704 * functions and these fields should be considered read-only. 
705 */ 
706typedef struct ktxTexture2 { 
707 KTXTEXTURECLASSDEFN 
708 ktx_uint32_t vkFormat; 
709 ktx_uint32_t* pDfd; 
710 ktxSupercmpScheme supercompressionScheme; 
711 ktx_bool_t isVideo; 
712 ktx_uint32_t duration; 
713 ktx_uint32_t timescale; 
714 ktx_uint32_t loopcount; 
715 struct ktxTexture2_private* _private; /*!< Private data. */ 
716} ktxTexture2; 
717 
718/* 
719 * If Doxygen sees this macro it gets confused and fails to spot 
720 * references to ktxTexture_*() functions in the running text. It 
721 * also complains it can't find the reference when @ref is used 
722 * with a fully qualified method name to make an intra-class 
723 * reference in the @c ktxTexture class. 
724 * See https://github.com/doxygen/doxygen/issues/10311. 
725 * 
726 * Not documenting the macro is the lesser of two evils. 
727 */ 
728#if !defined(KTX_DOXYGEN_SKIP) 
729 /** 
730 * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture. 
731 * 
732 * Use with caution. 
733 */ 
734 #define ktxTexture(t) ((ktxTexture*)t) 
735#endif 
736 
737/** 
738 * @memberof ktxTexture 
739 * @~English 
740 * @brief Structure for passing texture information to ktxTexture1\_Create() and 
741 * ktxTexture2\_Create(). 
742 * 
743 * @sa @ref ktxTexture1::ktxTexture1\_Create() "ktxTexture1_Create()" 
744 * @sa @ref ktxTexture2::ktxTexture2\_Create() "ktxTexture2_Create()" 
745 */ 
746typedef struct 
747{ 
748 ktx_uint32_t glInternalformat; /*!< Internal format for the texture, e.g., 
749 GL_RGB8. Ignored when creating a 
750 ktxTexture2. */ 
751 ktx_uint32_t vkFormat; /*!< VkFormat for texture. Ignored when creating a 
752 ktxTexture1. */ 
753 ktx_uint32_t* pDfd; /*!< Pointer to DFD. Used only when creating a 
754 ktxTexture2 and only if vkFormat is 
755 VK_FORMAT_UNDEFINED. */ 
756 ktx_uint32_t baseWidth; /*!< Width of the base level of the texture. */ 
757 ktx_uint32_t baseHeight; /*!< Height of the base level of the texture. */ 
758 ktx_uint32_t baseDepth; /*!< Depth of the base level of the texture. */ 
759 ktx_uint32_t numDimensions; /*!< Number of dimensions in the texture, 1, 2 
760 or 3. */ 
761 ktx_uint32_t numLevels; /*!< Number of mip levels in the texture. Should be 
762 1 if @c generateMipmaps is KTX_TRUE; */ 
763 ktx_uint32_t numLayers; /*!< Number of array layers in the texture. */ 
764 ktx_uint32_t numFaces; /*!< Number of faces: 6 for cube maps, 1 otherwise. */ 
765 ktx_bool_t isArray; /*!< Set to KTX_TRUE if the texture is to be an 
766 array texture. Means OpenGL will use a 
767 GL_TEXTURE_*_ARRAY target. */ 
768 ktx_bool_t generateMipmaps; /*!< Set to KTX_TRUE if mipmaps should be 
769 generated for the texture when loading 
770 into a 3D API. */ 
771} ktxTextureCreateInfo; 
772 
773/** 
774 * @memberof ktxTexture 
775 * @~English 
776 * @brief Enum for requesting, or not, allocation of storage for images. 
777 * 
778 * @sa ktxTexture1_Create() and ktxTexture2_Create(). 
779 */ 
780typedef enum { 
781 KTX_TEXTURE_CREATE_NO_STORAGE = 0, /*!< Don't allocate any image storage. */ 
782 KTX_TEXTURE_CREATE_ALLOC_STORAGE = 1 /*!< Allocate image storage. */ 
783} ktxTextureCreateStorageEnum; 
784 
785/** 
786 * @memberof ktxTexture 
787 * @~English 
788 * @brief Flags for requesting services during creation. 
789 * 
790 * @sa ktxTexture_CreateFrom* 
791 */ 
792enum ktxTextureCreateFlagBits { 
793 KTX_TEXTURE_CREATE_NO_FLAGS = 0x00, 
794 KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT = 0x01, 
795 /*!< Load the images from the KTX source. */ 
796 KTX_TEXTURE_CREATE_RAW_KVDATA_BIT = 0x02, 
797 /*!< Load the raw key-value data instead of 
798 creating a @c ktxHashList from it. */ 
799 KTX_TEXTURE_CREATE_SKIP_KVDATA_BIT = 0x04, 
800 /*!< Skip any key-value data. This overrides 
801 the RAW_KVDATA_BIT. */ 
802 KTX_TEXTURE_CREATE_CHECK_GLTF_BASISU_BIT = 0x08 
803 /*!< Load texture compatible with the rules 
804 of KHR_texture_basisu glTF extension */ 
805}; 
806/** 
807 * @memberof ktxTexture 
808 * @~English 
809 * @brief Type for TextureCreateFlags parameters. 
810 * 
811 * @sa ktxTexture_CreateFrom*() 
812 */ 
813typedef ktx_uint32_t ktxTextureCreateFlags; 
814 
815/*===========================================================* 
816* ktxStream 
817*===========================================================*/ 
818 
819/* 
820 * This is unsigned to allow ktxmemstreams to use the 
821 * full amount of memory available. Platforms will 
822 * limit the size of ktxfilestreams to, e.g, MAX_LONG 
823 * on 32-bit and ktxfilestreams raises errors if 
824 * offset values exceed the limits. This choice may 
825 * need to be revisited if we ever start needing -ve 
826 * offsets. 
827 * 
828 * Should the 2GB file size handling limit on 32-bit 
829 * platforms become a problem, ktxfilestream will have 
830 * to be changed to explicitly handle large files by 
831 * using the 64-bit stream functions. 
832 */ 
833#if defined(_MSC_VER) && defined(_WIN64) 
834 typedef unsigned __int64 ktx_off_t; 
835#else 
836 typedef off_t ktx_off_t; 
837#endif 
838typedef struct ktxMem ktxMem; 
839typedef struct ktxStream ktxStream; 
840 
841enum streamType { eStreamTypeFile = 1, eStreamTypeMemory = 2, eStreamTypeCustom = 3 }; 
842 
843/** 
844 * @~English 
845 * @brief type for a pointer to a stream reading function 
846 */ 
847typedef KTX_error_code (*ktxStream_read)(ktxStream* str, void* dst, 
848 const ktx_size_t count); 
849/** 
850 * @~English 
851 * @brief type for a pointer to a stream skipping function 
852 */ 
853typedef KTX_error_code (*ktxStream_skip)(ktxStream* str, 
854 const ktx_size_t count); 
855 
856/** 
857 * @~English 
858 * @brief type for a pointer to a stream writing function 
859 */ 
860typedef KTX_error_code (*ktxStream_write)(ktxStream* str, const void *src, 
861 const ktx_size_t size, 
862 const ktx_size_t count); 
863 
864/** 
865 * @~English 
866 * @brief type for a pointer to a stream position query function 
867 */ 
868typedef KTX_error_code (*ktxStream_getpos)(ktxStream* str, ktx_off_t* const offset); 
869 
870/** 
871 * @~English 
872 * @brief type for a pointer to a stream position query function 
873 */ 
874typedef KTX_error_code (*ktxStream_setpos)(ktxStream* str, const ktx_off_t offset); 
875 
876/** 
877 * @~English 
878 * @brief type for a pointer to a stream size query function 
879 */ 
880typedef KTX_error_code (*ktxStream_getsize)(ktxStream* str, ktx_size_t* const size); 
881 
882/** 
883 * @~English 
884 * @brief Destruct a stream 
885 */ 
886typedef void (*ktxStream_destruct)(ktxStream* str); 
887 
888/** 
889 * @~English 
890 * 
891 * @brief Interface of ktxStream. 
892 * 
893 * @author Maksim Kolesin 
894 * @author Georg Kolling, Imagination Technology 
895 * @author Mark Callow, HI Corporation 
896 */ 
897struct ktxStream 
898{ 
899 ktxStream_read read; /*!< pointer to function for reading bytes. */ 
900 ktxStream_skip skip; /*!< pointer to function for skipping bytes. */ 
901 ktxStream_write write; /*!< pointer to function for writing bytes. */ 
902 ktxStream_getpos getpos; /*!< pointer to function for getting current position in stream. */ 
903 ktxStream_setpos setpos; /*!< pointer to function for setting current position in stream. */ 
904 ktxStream_getsize getsize; /*!< pointer to function for querying size. */ 
905 ktxStream_destruct destruct; /*!< destruct the stream. */ 
906 
907 enum streamType type; 
908 union { 
909 FILE* file; /**< a stdio FILE pointer for a ktxFileStream. */ 
910 ktxMem* mem; /**< a pointer to a ktxMem struct for a ktxMemStream. */ 
911 struct 
912 { 
913 void* address; /**< pointer to the data. */ 
914 void* allocatorAddress; /**< pointer to a memory allocator. */ 
915 ktx_size_t size; /**< size of the data. */ 
916 } custom_ptr; /**< pointer to a struct for custom streams. */ 
917 } data; /**< pointer to the stream data. */ 
918 ktx_off_t readpos; /**< used by FileStream for stdin. */ 
919 ktx_bool_t closeOnDestruct; /**< Close FILE* or dispose of memory on destruct. */ 
920}; 
921 
922/* 
923 * See the implementation files for the full documentation of the following 
924 * functions. 
925 */ 
926 
927/** 
928 * @~English 
929 * @brief typedef of function pointer returned by GLGetProcAddress functions. 
930 */ 
931typedef void (KTX_APIENTRY* PFNVOIDFUNCTION)(void); 
932/** 
933 * @~English 
934 * @brief typedef of pointer to function for retrieving OpenGL function pointers. 
935 */ 
936typedef PFNVOIDFUNCTION (KTX_APIENTRY* PFNGLGETPROCADDRESS) (const char *proc); 
937/* 
938 * Load pointers for the OpenGL functions needed by ktxTexture_GLUpload. 
939 */ 
940KTX_API KTX_error_code KTX_APIENTRY 
941ktxLoadOpenGL(PFNGLGETPROCADDRESS pfnGLGetProcAddress); 
942 
943/* 
944 * These four create a ktxTexture1 or ktxTexture2 according to the data 
945 * header, and return a pointer to the base ktxTexture class. 
946 */ 
947KTX_API KTX_error_code KTX_APIENTRY 
948ktxTexture_CreateFromStdioStream(FILE* stdioStream, 
949 ktxTextureCreateFlags createFlags, 
950 ktxTexture** newTex); 
951 
952KTX_API KTX_error_code KTX_APIENTRY 
953ktxTexture_CreateFromNamedFile(const char* const filename, 
954 ktxTextureCreateFlags createFlags, 
955 ktxTexture** newTex); 
956 
957KTX_API KTX_error_code KTX_APIENTRY 
958ktxTexture_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, 
959 ktxTextureCreateFlags createFlags, 
960 ktxTexture** newTex); 
961 
962KTX_API KTX_error_code KTX_APIENTRY 
963ktxTexture_CreateFromStream(ktxStream* stream, 
964 ktxTextureCreateFlags createFlags, 
965 ktxTexture** newTex); 
966 
967/* 
968 * Returns a pointer to the image data of a ktxTexture object. 
969 */ 
970KTX_API ktx_uint8_t* KTX_APIENTRY 
971ktxTexture_GetData(ktxTexture* This); 
972 
973/* 
974 * Returns the pitch of a row of an image at the specified level. 
975 * Similar to the rowPitch in a VkSubResourceLayout. 
976 */ 
977KTX_API ktx_uint32_t KTX_APIENTRY 
978ktxTexture_GetRowPitch(ktxTexture* This, ktx_uint32_t level); 
979 
980 /* 
981 * Return the element size of the texture's images. 
982 */ 
983KTX_API ktx_uint32_t KTX_APIENTRY 
984ktxTexture_GetElementSize(ktxTexture* This); 
985 
986/* 
987 * Returns the size of all the image data of a ktxTexture object in bytes. 
988 */ 
989KTX_API ktx_size_t KTX_APIENTRY 
990ktxTexture_GetDataSize(ktxTexture* This); 
991 
992/* Uploads a texture to OpenGL {,ES}. */ 
993KTX_API KTX_error_code KTX_APIENTRY 
994ktxTexture_GLUpload(ktxTexture* This, GLuint* pTexture, GLenum* pTarget, 
995 GLenum* pGlerror); 
996 
997/* 
998 * Iterate over the levels or faces in a ktxTexture object. 
999 */ 
1000KTX_API KTX_error_code KTX_APIENTRY 
1001ktxTexture_IterateLevelFaces(ktxTexture* This, PFNKTXITERCB iterCb, 
1002 void* userdata); 
1003/* 
1004 * Create a new ktxTexture1. 
1005 */ 
1006KTX_API KTX_error_code KTX_APIENTRY 
1007ktxTexture1_Create(const ktxTextureCreateInfo* const createInfo, 
1008 ktxTextureCreateStorageEnum storageAllocation, 
1009 ktxTexture1** newTex); 
1010 
1011/* 
1012 * These four create a ktxTexture1 provided the data is in KTX format. 
1013 */ 
1014KTX_API KTX_error_code KTX_APIENTRY 
1015ktxTexture1_CreateFromStdioStream(FILE* stdioStream, 
1016 ktxTextureCreateFlags createFlags, 
1017 ktxTexture1** newTex); 
1018 
1019KTX_API KTX_error_code KTX_APIENTRY 
1020ktxTexture1_CreateFromNamedFile(const char* const filename, 
1021 ktxTextureCreateFlags createFlags, 
1022 ktxTexture1** newTex); 
1023 
1024KTX_API KTX_error_code KTX_APIENTRY 
1025ktxTexture1_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, 
1026 ktxTextureCreateFlags createFlags, 
1027 ktxTexture1** newTex); 
1028 
1029KTX_API KTX_error_code KTX_APIENTRY 
1030ktxTexture1_CreateFromStream(ktxStream* stream, 
1031 ktxTextureCreateFlags createFlags, 
1032 ktxTexture1** newTex); 
1033KTX_API void KTX_APIENTRY 
1034ktxTexture1_Destroy(ktxTexture1* This); 
1035 
1036KTX_API ktx_bool_t KTX_APIENTRY 
1037ktxTexture1_NeedsTranscoding(ktxTexture1* This); 
1038 
1039/* 
1040 * Write a ktxTexture object to a stdio stream in KTX format. 
1041 */ 
1042KTX_API KTX_error_code KTX_APIENTRY 
1043ktxTexture1_WriteKTX2ToStdioStream(ktxTexture1* This, FILE* dstsstr); 
1044 
1045/* 
1046 * Write a ktxTexture object to a named file in KTX format. 
1047 */ 
1048KTX_API KTX_error_code KTX_APIENTRY 
1049ktxTexture1_WriteKTX2ToNamedFile(ktxTexture1* This, const char* const dstname); 
1050 
1051/* 
1052 * Write a ktxTexture object to a block of memory in KTX format. 
1053 */ 
1054KTX_API KTX_error_code KTX_APIENTRY 
1055ktxTexture1_WriteKTX2ToMemory(ktxTexture1* This, 
1056 ktx_uint8_t** bytes, ktx_size_t* size); 
1057 
1058/* 
1059 * Write a ktxTexture object to a ktxStream in KTX format. 
1060 */ 
1061KTX_API KTX_error_code KTX_APIENTRY 
1062ktxTexture1_WriteKTX2ToStream(ktxTexture1* This, ktxStream *dststr); 
1063 
1064/* 
1065 * Create a new ktxTexture2. 
1066 */ 
1067KTX_API KTX_error_code KTX_APIENTRY 
1068ktxTexture2_Create(const ktxTextureCreateInfo* const createInfo, 
1069 ktxTextureCreateStorageEnum storageAllocation, 
1070 ktxTexture2** newTex); 
1071 
1072/* 
1073 * Create a new ktxTexture2 as a copy of an existing texture. 
1074 */ 
1075KTX_API KTX_error_code KTX_APIENTRY 
1076ktxTexture2_CreateCopy(ktxTexture2* orig, ktxTexture2** newTex); 
1077 
1078 /* 
1079 * These four create a ktxTexture2 provided the data is in KTX2 format. 
1080 */ 
1081KTX_API KTX_error_code KTX_APIENTRY 
1082ktxTexture2_CreateFromStdioStream(FILE* stdioStream, 
1083 ktxTextureCreateFlags createFlags, 
1084 ktxTexture2** newTex); 
1085 
1086KTX_API KTX_error_code KTX_APIENTRY 
1087ktxTexture2_CreateFromNamedFile(const char* const filename, 
1088 ktxTextureCreateFlags createFlags, 
1089 ktxTexture2** newTex); 
1090 
1091KTX_API KTX_error_code KTX_APIENTRY 
1092ktxTexture2_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, 
1093 ktxTextureCreateFlags createFlags, 
1094 ktxTexture2** newTex); 
1095 
1096KTX_API KTX_error_code KTX_APIENTRY 
1097ktxTexture2_CreateFromStream(ktxStream* stream, 
1098 ktxTextureCreateFlags createFlags, 
1099 ktxTexture2** newTex); 
1100 
1101KTX_API void KTX_APIENTRY 
1102ktxTexture2_Destroy(ktxTexture2* This); 
1103 
1104KTX_API KTX_error_code KTX_APIENTRY 
1105ktxTexture2_CompressBasis(ktxTexture2* This, ktx_uint32_t quality); 
1106 
1107KTX_API KTX_error_code KTX_APIENTRY 
1108ktxTexture2_DeflateZstd(ktxTexture2* This, ktx_uint32_t level); 
1109 
1110KTX_API KTX_error_code KTX_APIENTRY 
1111ktxTexture2_DeflateZLIB(ktxTexture2* This, ktx_uint32_t level); 
1112 
1113KTX_API void KTX_APIENTRY 
1114ktxTexture2_GetComponentInfo(ktxTexture2* This, ktx_uint32_t* numComponents, 
1115 ktx_uint32_t* componentByteLength); 
1116 
1117KTX_API ktx_uint32_t KTX_APIENTRY 
1118ktxTexture2_GetNumComponents(ktxTexture2* This); 
1119 
1120KTX_API khr_df_transfer_e KTX_APIENTRY 
1121ktxTexture2_GetOETF_e(ktxTexture2* This); 
1122 
1123// For backward compatibility 
1124KTX_API ktx_uint32_t KTX_APIENTRY 
1125ktxTexture2_GetOETF(ktxTexture2* This); 
1126 
1127KTX_API khr_df_model_e KTX_APIENTRY 
1128ktxTexture2_GetColorModel_e(ktxTexture2* This); 
1129 
1130KTX_API ktx_bool_t KTX_APIENTRY 
1131ktxTexture2_GetPremultipliedAlpha(ktxTexture2* This); 
1132 
1133KTX_API khr_df_primaries_e KTX_APIENTRY 
1134ktxTexture2_GetPrimaries_e(ktxTexture2* This); 
1135 
1136KTX_API ktx_bool_t KTX_APIENTRY 
1137ktxTexture2_NeedsTranscoding(ktxTexture2* This); 
1138 
1139KTX_API ktx_error_code_e KTX_APIENTRY 
1140ktxTexture2_SetOETF(ktxTexture2* This, khr_df_transfer_e oetf); 
1141 
1142KTX_API ktx_error_code_e KTX_APIENTRY 
1143ktxTexture2_SetPrimaries(ktxTexture2* This, khr_df_primaries_e primaries); 
1144 
1145/** 
1146 * @~English 
1147 * @brief Flags specifiying UASTC encoding options. 
1148 */ 
1149typedef enum ktx_pack_uastc_flag_bits_e { 
1150 KTX_PACK_UASTC_LEVEL_FASTEST = 0, 
1151 /*!< Fastest compression. 43.45dB. */ 
1152 KTX_PACK_UASTC_LEVEL_FASTER = 1, 
1153 /*!< Faster compression. 46.49dB. */ 
1154 KTX_PACK_UASTC_LEVEL_DEFAULT = 2, 
1155 /*!< Default compression. 47.47dB. */ 
1156 KTX_PACK_UASTC_LEVEL_SLOWER = 3, 
1157 /*!< Slower compression. 48.01dB. */ 
1158 KTX_PACK_UASTC_LEVEL_VERYSLOW = 4, 
1159 /*!< Very slow compression. 48.24dB. */ 
1160 KTX_PACK_UASTC_MAX_LEVEL = KTX_PACK_UASTC_LEVEL_VERYSLOW, 
1161 /*!< Maximum supported quality level. */ 
1162 KTX_PACK_UASTC_LEVEL_MASK = 0xF, 
1163 /*!< Mask to extract the level from the other bits. */ 
1164 KTX_PACK_UASTC_FAVOR_UASTC_ERROR = 8, 
1165 /*!< Optimize for lowest UASTC error. */ 
1166 KTX_PACK_UASTC_FAVOR_BC7_ERROR = 16, 
1167 /*!< Optimize for lowest BC7 error. */ 
1168 KTX_PACK_UASTC_ETC1_FASTER_HINTS = 64, 
1169 /*!< Optimize for faster transcoding to ETC1. */ 
1170 KTX_PACK_UASTC_ETC1_FASTEST_HINTS = 128, 
1171 /*!< Optimize for fastest transcoding to ETC1. */ 
1172 KTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL = 256 
1173 /*!< Not documented in BasisU code. */ 
1174} ktx_pack_uastc_flag_bits_e; 
1175typedef ktx_uint32_t ktx_pack_uastc_flags; 
1176 
1177/** 
1178 * @~English 
1179 * @brief Options specifiying ASTC encoding quality levels. 
1180 */ 
1181typedef enum ktx_pack_astc_quality_levels_e { 
1182 KTX_PACK_ASTC_QUALITY_LEVEL_FASTEST = 0, 
1183 /*!< Fastest compression. */ 
1184 KTX_PACK_ASTC_QUALITY_LEVEL_FAST = 10, 
1185 /*!< Fast compression. */ 
1186 KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM = 60, 
1187 /*!< Medium compression. */ 
1188 KTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH = 98, 
1189 /*!< Slower compression. */ 
1190 KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE = 100, 
1191 /*!< Very slow compression. */ 
1192 KTX_PACK_ASTC_QUALITY_LEVEL_MAX = KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE, 
1193 /*!< Maximum supported quality level. */ 
1194} ktx_pack_astc_quality_levels_e; 
1195 
1196/** 
1197 * @~English 
1198 * @brief Options specifiying ASTC encoding block dimensions 
1199 */ 
1200typedef enum ktx_pack_astc_block_dimension_e { 
1201 // 2D formats 
1202 KTX_PACK_ASTC_BLOCK_DIMENSION_4x4, //: 8.00 bpp 
1203 KTX_PACK_ASTC_BLOCK_DIMENSION_5x4, //: 6.40 bpp 
1204 KTX_PACK_ASTC_BLOCK_DIMENSION_5x5, //: 5.12 bpp 
1205 KTX_PACK_ASTC_BLOCK_DIMENSION_6x5, //: 4.27 bpp 
1206 KTX_PACK_ASTC_BLOCK_DIMENSION_6x6, //: 3.56 bpp 
1207 KTX_PACK_ASTC_BLOCK_DIMENSION_8x5, //: 3.20 bpp 
1208 KTX_PACK_ASTC_BLOCK_DIMENSION_8x6, //: 2.67 bpp 
1209 KTX_PACK_ASTC_BLOCK_DIMENSION_10x5, //: 2.56 bpp 
1210 KTX_PACK_ASTC_BLOCK_DIMENSION_10x6, //: 2.13 bpp 
1211 KTX_PACK_ASTC_BLOCK_DIMENSION_8x8, //: 2.00 bpp 
1212 KTX_PACK_ASTC_BLOCK_DIMENSION_10x8, //: 1.60 bpp 
1213 KTX_PACK_ASTC_BLOCK_DIMENSION_10x10, //: 1.28 bpp 
1214 KTX_PACK_ASTC_BLOCK_DIMENSION_12x10, //: 1.07 bpp 
1215 KTX_PACK_ASTC_BLOCK_DIMENSION_12x12, //: 0.89 bpp 
1216 // 3D formats 
1217 KTX_PACK_ASTC_BLOCK_DIMENSION_3x3x3, //: 4.74 bpp 
1218 KTX_PACK_ASTC_BLOCK_DIMENSION_4x3x3, //: 3.56 bpp 
1219 KTX_PACK_ASTC_BLOCK_DIMENSION_4x4x3, //: 2.67 bpp 
1220 KTX_PACK_ASTC_BLOCK_DIMENSION_4x4x4, //: 2.00 bpp 
1221 KTX_PACK_ASTC_BLOCK_DIMENSION_5x4x4, //: 1.60 bpp 
1222 KTX_PACK_ASTC_BLOCK_DIMENSION_5x5x4, //: 1.28 bpp 
1223 KTX_PACK_ASTC_BLOCK_DIMENSION_5x5x5, //: 1.02 bpp 
1224 KTX_PACK_ASTC_BLOCK_DIMENSION_6x5x5, //: 0.85 bpp 
1225 KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x5, //: 0.71 bpp 
1226 KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x6, //: 0.59 bpp 
1227 KTX_PACK_ASTC_BLOCK_DIMENSION_MAX = KTX_PACK_ASTC_BLOCK_DIMENSION_6x6x6 
1228 /*!< Maximum supported blocks. */ 
1229} ktx_pack_astc_block_dimension_e; 
1230 
1231/** 
1232 * @~English 
1233 * @brief Options specifying ASTC encoder profile mode 
1234 * This and function is used later to derive the profile. 
1235 */ 
1236typedef enum ktx_pack_astc_encoder_mode_e { 
1237 KTX_PACK_ASTC_ENCODER_MODE_DEFAULT, 
1238 KTX_PACK_ASTC_ENCODER_MODE_LDR, 
1239 KTX_PACK_ASTC_ENCODER_MODE_HDR, 
1240 KTX_PACK_ASTC_ENCODER_MODE_MAX = KTX_PACK_ASTC_ENCODER_MODE_HDR 
1241} ktx_pack_astc_encoder_mode_e; 
1242 
1243extern KTX_API const ktx_uint32_t KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL; 
1244 
1245/** 
1246 * @memberof ktxTexture 
1247 * @~English 
1248 * @brief Structure for passing extended parameters to 
1249 * ktxTexture_CompressAstc. 
1250 * 
1251 * Passing a struct initialized to 0 (e.g. " = {0};") will use blockDimension 
1252 * 4x4, mode LDR and qualityLevel FASTEST. Setting qualityLevel to 
1253 * KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM is recommended. 
1254 */ 
1255typedef struct ktxAstcParams { 
1256 ktx_uint32_t structSize; 
1257 /*!< Size of this struct. Used so library can tell which version 
1258 of struct is being passed. 
1259 */ 
1260 
1261 ktx_bool_t verbose; 
1262 /*!< If true, prints Astc encoder operation details to 
1263 @c stdout. Not recommended for GUI apps. 
1264 */ 
1265 
1266 ktx_uint32_t threadCount; 
1267 /*!< Number of threads used for compression. Default is 1. 
1268 */ 
1269 
1270 /* astcenc params */ 
1271 ktx_uint32_t blockDimension; 
1272 /*!< Combinations of block dimensions that astcenc supports 
1273 i.e. 6x6, 8x8, 6x5 etc 
1274 */ 
1275 
1276 ktx_uint32_t mode; 
1277 /*!< Can be {ldr/hdr} from astcenc 
1278 */ 
1279 
1280 ktx_uint32_t qualityLevel; 
1281 /*!< astcenc supports -fastest, -fast, -medium, -thorough, -exhaustive 
1282 */ 
1283 
1284 ktx_bool_t normalMap; 
1285 /*!< Tunes codec parameters for better quality on normal maps 
1286 In this mode normals are compressed to X,Y components 
1287 Discarding Z component, reader will need to generate Z 
1288 component in shaders. 
1289 */ 
1290 
1291 ktx_bool_t perceptual; 
1292 /*!< The codec should optimize for perceptual error, instead of direct 
1293 RMS error. This aims to improves perceived image quality, but 
1294 typically lowers the measured PSNR score. Perceptual methods are 
1295 currently only available for normal maps and RGB color data. 
1296 */ 
1297 
1298 char inputSwizzle[4]; 
1299 /*!< A swizzle to provide as input to astcenc. It must match the regular 
1300 expression /^[rgba01]{4}$/. 
1301 */ 
1302} ktxAstcParams; 
1303 
1304KTX_API KTX_error_code KTX_APIENTRY 
1305ktxTexture2_CompressAstcEx(ktxTexture2* This, ktxAstcParams* params); 
1306 
1307KTX_API KTX_error_code KTX_APIENTRY 
1308ktxTexture2_CompressAstc(ktxTexture2* This, ktx_uint32_t quality); 
1309 
1310/** 
1311 * @memberof ktxTexture2 
1312 * @~English 
1313 * @brief Structure for passing extended parameters to 
1314 * ktxTexture2_CompressBasisEx(). 
1315 * 
1316 * If you only want default values, use ktxTexture2_CompressBasis(). Here, at a minimum you 
1317 * must initialize the structure as follows: 
1318 * @code 
1319 * ktxBasisParams params = {0}; 
1320 * params.structSize = sizeof(params); 
1321 * params.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL; 
1322 * @endcode 
1323 * 
1324 * @e compressionLevel has to be explicitly set because 0 is a valid @e compressionLevel 
1325 * but is not the default used by the BasisU encoder when no value is set. Only the other 
1326 * settings that are to be non-default must be non-zero. 
1327 */ 
1328typedef struct ktxBasisParams { 
1329 ktx_uint32_t structSize; 
1330 /*!< Size of this struct. Used so library can tell which version 
1331 of struct is being passed. 
1332 */ 
1333 ktx_bool_t uastc; 
1334 /*!< True to use UASTC base, false to use ETC1S base. */ 
1335 ktx_bool_t verbose; 
1336 /*!< If true, prints Basis Universal encoder operation details to 
1337 @c stdout. Not recommended for GUI apps. 
1338 */ 
1339 ktx_bool_t noSSE; 
1340 /*!< True to forbid use of the SSE instruction set. Ignored if CPU 
1341 does not support SSE. */ 
1342 ktx_uint32_t threadCount; 
1343 /*!< Number of threads used for compression. Default is 1. */ 
1344 
1345 /* ETC1S params */ 
1346 
1347 ktx_uint32_t compressionLevel; 
1348 /*!< Encoding speed vs. quality tradeoff. Range is [0,5]. Higher values 
1349 are slower, but give higher quality. There is no default. Callers 
1350 must explicitly set this value. Callers can use 
1351 KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL as a default value. 
1352 Currently this is 2. 
1353 */ 
1354 ktx_uint32_t qualityLevel; 
1355 /*!< Compression quality. Range is [1,255]. Lower gives better 
1356 compression/lower quality/faster. Higher gives less compression 
1357 /higher quality/slower. This automatically determines values for 
1358 @c maxEndpoints, @c maxSelectors, 
1359 @c endpointRDOThreshold and @c selectorRDOThreshold 
1360 for the target quality level. Setting these parameters overrides 
1361 the values determined by @c qualityLevel which defaults to 
1362 128 if neither it nor both of @c maxEndpoints and 
1363 @c maxSelectors have been set. 
1364 @note @e Both of @c maxEndpoints and @c maxSelectors 
1365 must be set for them to have any effect. 
1366 @note qualityLevel will only determine values for 
1367 @c endpointRDOThreshold and @c selectorRDOThreshold 
1368 when its value exceeds 128, otherwise their defaults will be used. 
1369 */ 
1370 ktx_uint32_t maxEndpoints; 
1371 /*!< Manually set the max number of color endpoint clusters. 
1372 Range is [1,16128]. Default is 0, unset. If this is set, maxSelectors 
1373 must also be set, otherwise the value will be ignored. 
1374 */ 
1375 float endpointRDOThreshold; 
1376 /*!< Set endpoint RDO quality threshold. The default is 1.25. Lower is 
1377 higher quality but less quality per output bit (try [1.0,3.0]. 
1378 This will override the value chosen by @c qualityLevel. 
1379 */ 
1380 ktx_uint32_t maxSelectors; 
1381 /*!< Manually set the max number of color selector clusters. Range 
1382 is [1,16128]. Default is 0, unset. If this is set, maxEndpoints 
1383 must also be set, otherwise the value will be ignored. 
1384 */ 
1385 float selectorRDOThreshold; 
1386 /*!< Set selector RDO quality threshold. The default is 1.5. Lower is 
1387 higher quality but less quality per output bit (try [1.0,3.0]). 
1388 This will override the value chosen by @c qualityLevel. 
1389 */ 
1390 char inputSwizzle[4]; 
1391 /*!< A swizzle to apply before encoding. It must match the regular 
1392 expression /^[rgba01]{4}$/. If both this and preSwizzle 
1393 are specified ktxTexture_CompressBasisEx will raise 
1394 KTX_INVALID_OPERATION. Usable with both ETC1S and UASTC. 
1395 */ 
1396 ktx_bool_t normalMap; 
1397 /*!< Tunes codec parameters for better quality on normal maps (no 
1398 selector RDO, no endpoint RDO) and sets the texture's DFD appropriately. 
1399 Only valid for linear textures. 
1400 */ 
1401 ktx_bool_t separateRGToRGB_A; 
1402 /*!< @deprecated This was and is a no-op. 2-component inputs have 
1403 always been automatically separated using an "rrrg" inputSwizzle. 
1404 @sa inputSwizzle and normalMode. 
1405 */ 
1406 ktx_bool_t preSwizzle; 
1407 /*!< If the texture has @c KTXswizzle metadata, apply it before 
1408 compressing. Swizzling, like @c rabb may yield drastically 
1409 different error metrics if done after supercompression. Usable 
1410 for both ETC1S and UASTC. 
1411 */ 
1412 ktx_bool_t noEndpointRDO; 
1413 /*!< Disable endpoint rate distortion optimizations. Slightly faster, 
1414 less noisy output, but lower quality per output bit. Default is 
1415 KTX_FALSE. 
1416 */ 
1417 ktx_bool_t noSelectorRDO; 
1418 /*!< Disable selector rate distortion optimizations. Slightly faster, 
1419 less noisy output, but lower quality per output bit. Default is 
1420 KTX_FALSE. 
1421 */ 
1422 
1423 /* UASTC params */ 
1424 
1425 ktx_pack_uastc_flags uastcFlags; 
1426 /*!< A set of ::ktx_pack_uastc_flag_bits_e controlling UASTC 
1427 encoding. The most important value is the level given in the 
1428 least-significant 4 bits which selects a speed vs quality tradeoff 
1429 as shown in the following table: 
1430 
1431 Level/Speed | Quality 
1432 :-----: | :-------: 
1433 KTX_PACK_UASTC_LEVEL_FASTEST | 43.45dB 
1434 KTX_PACK_UASTC_LEVEL_FASTER | 46.49dB 
1435 KTX_PACK_UASTC_LEVEL_DEFAULT | 47.47dB 
1436 KTX_PACK_UASTC_LEVEL_SLOWER | 48.01dB 
1437 KTX_PACK_UASTC_LEVEL_VERYSLOW | 48.24dB 
1438 */ 
1439 ktx_bool_t uastcRDO; 
1440 /*!< Enable Rate Distortion Optimization (RDO) post-processing. 
1441 */ 
1442 float uastcRDOQualityScalar; 
1443 /*!< UASTC RDO quality scalar (lambda). Lower values yield higher 
1444 quality/larger LZ compressed files, higher values yield lower 
1445 quality/smaller LZ compressed files. A good range to try is [.2,4]. 
1446 Full range is [.001,50.0]. Default is 1.0. 
1447 */ 
1448 ktx_uint32_t uastcRDODictSize; 
1449 /*!< UASTC RDO dictionary size in bytes. Default is 4096. Lower 
1450 values=faster, but give less compression. Range is [64,65536]. 
1451 */ 
1452 float uastcRDOMaxSmoothBlockErrorScale; 
1453 /*!< UASTC RDO max smooth block error scale. Range is [1,300]. 
1454 Default is 10.0, 1.0 is disabled. Larger values suppress more 
1455 artifacts (and allocate more bits) on smooth blocks. 
1456 */ 
1457 float uastcRDOMaxSmoothBlockStdDev; 
1458 /*!< UASTC RDO max smooth block standard deviation. Range is 
1459 [.01,65536.0]. Default is 18.0. Larger values expand the range of 
1460 blocks considered smooth. 
1461 */ 
1462 ktx_bool_t uastcRDODontFavorSimplerModes; 
1463 /*!< Do not favor simpler UASTC modes in RDO mode. 
1464 */ 
1465 ktx_bool_t uastcRDONoMultithreading; 
1466 /*!< Disable RDO multithreading (slightly higher compression, 
1467 deterministic). 
1468 */ 
1469 
1470} ktxBasisParams; 
1471 
1472KTX_API KTX_error_code KTX_APIENTRY 
1473ktxTexture2_CompressBasisEx(ktxTexture2* This, ktxBasisParams* params); 
1474 
1475/** 
1476 * @~English 
1477 * @brief Enumerators for specifying the transcode target format. 
1478 * 
1479 * For BasisU/ETC1S format, @e Opaque and @e alpha here refer to 2 separate 
1480 * RGB images, a.k.a slices within the BasisU compressed data. For UASTC 
1481 * format they refer to the RGB and the alpha components of the UASTC data. If 
1482 * the original image had only 2 components, R will be in the opaque portion 
1483 * and G in the alpha portion. The R value will be replicated in the RGB 
1484 * components. In the case of BasisU the G value will be replicated in all 3 
1485 * components of the alpha slice. If the original image had only 1 component 
1486 * it's value is replicated in all 3 components of the opaque portion and 
1487 * there is no alpha. 
1488 * 
1489 * @note You should not transcode sRGB encoded data to @c KTX_TTF_BC4_R, 
1490 * @c KTX_TTF_BC5_RG, @c KTX_TTF_ETC2_EAC_R{,G}11, @c KTX_TTF_RGB565, 
1491 * @c KTX_TTF_BGR565 or @c KTX_TTF_RGBA4444 formats as neither OpenGL nor 
1492 * Vulkan support sRGB variants of these. Doing sRGB decoding in the shader 
1493 * will not produce correct results if any texture filtering is being used. 
1494 */ 
1495typedef enum ktx_transcode_fmt_e { 
1496 // Compressed formats 
1497 
1498 // ETC1-2 
1499 KTX_TTF_ETC1_RGB = 0, 
1500 /*!< Opaque only. Returns RGB or alpha data, if 
1501 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is 
1502 specified. */ 
1503 KTX_TTF_ETC2_RGBA = 1, 
1504 /*!< Opaque+alpha. EAC_A8 block followed by an ETC1 block. The 
1505 alpha channel will be opaque for textures without an alpha 
1506 channel. */ 
1507 
1508 // BC1-5, BC7 (desktop, some mobile devices) 
1509 KTX_TTF_BC1_RGB = 2, 
1510 /*!< Opaque only, no punchthrough alpha support yet. Returns RGB 
1511 or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS 
1512 flag is specified. */ 
1513 KTX_TTF_BC3_RGBA = 3, 
1514 /*!< Opaque+alpha. BC4 block with alpha followed by a BC1 block. The 
1515 alpha channel will be opaque for textures without an alpha 
1516 channel. */ 
1517 KTX_TTF_BC4_R = 4, 
1518 /*!< One BC4 block. R = opaque.g or alpha.g, if 
1519 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is 
1520 specified. */ 
1521 KTX_TTF_BC5_RG = 5, 
1522 /*!< Two BC4 blocks, R=opaque.g and G=alpha.g The texture should 
1523 have an alpha channel (if not G will be all 255's. For tangent 
1524 space normal maps. */ 
1525 KTX_TTF_BC7_RGBA = 6, 
1526 /*!< RGB or RGBA mode 5 for ETC1S, modes 1, 2, 3, 4, 5, 6, 7 for 
1527 UASTC. */ 
1528 
1529 // PVRTC1 4bpp (mobile, PowerVR devices) 
1530 KTX_TTF_PVRTC1_4_RGB = 8, 
1531 /*!< Opaque only. Returns RGB or alpha data, if 
1532 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is 
1533 specified. */ 
1534 KTX_TTF_PVRTC1_4_RGBA = 9, 
1535 /*!< Opaque+alpha. Most useful for simple opacity maps. If the 
1536 texture doesn't have an alpha channel KTX_TTF_PVRTC1_4_RGB 
1537 will be used instead. Lowest quality of any supported 
1538 texture format. */ 
1539 
1540 // ASTC (mobile, Intel devices, hopefully all desktop GPU's one day) 
1541 KTX_TTF_ASTC_4x4_RGBA = 10, 
1542 /*!< Opaque+alpha, ASTC 4x4. The alpha channel will be opaque for 
1543 textures without an alpha channel. The transcoder uses 
1544 RGB/RGBA/L/LA modes, void extent, and up to two ([0,47] and 
1545 [0,255]) endpoint precisions. */ 
1546 
1547 // ATC and FXT1 formats are not supported by KTX2 as there 
1548 // are no equivalent VkFormats. 
1549 
1550 KTX_TTF_PVRTC2_4_RGB = 18, 
1551 /*!< Opaque-only. Almost BC1 quality, much faster to transcode 
1552 and supports arbitrary texture dimensions (unlike 
1553 PVRTC1 RGB). */ 
1554 KTX_TTF_PVRTC2_4_RGBA = 19, 
1555 /*!< Opaque+alpha. Slower to transcode than cTFPVRTC2_4_RGB. 
1556 Premultiplied alpha is highly recommended, otherwise the 
1557 color channel can leak into the alpha channel on transparent 
1558 blocks. */ 
1559 
1560 KTX_TTF_ETC2_EAC_R11 = 20, 
1561 /*!< R only (ETC2 EAC R11 unsigned). R = opaque.g or alpha.g, if 
1562 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is 
1563 specified. */ 
1564 KTX_TTF_ETC2_EAC_RG11 = 21, 
1565 /*!< RG only (ETC2 EAC RG11 unsigned), R=opaque.g, G=alpha.g. The 
1566 texture should have an alpha channel (if not G will be all 
1567 255's. For tangent space normal maps. */ 
1568 
1569 // Uncompressed (raw pixel) formats 
1570 KTX_TTF_RGBA32 = 13, 
1571 /*!< 32bpp RGBA image stored in raster (not block) order in 
1572 memory, R is first byte, A is last byte. */ 
1573 KTX_TTF_RGB565 = 14, 
1574 /*!< 16bpp RGB image stored in raster (not block) order in memory, 
1575 R at bit position 11. */ 
1576 KTX_TTF_BGR565 = 15, 
1577 /*!< 16bpp RGB image stored in raster (not block) order in memory, 
1578 R at bit position 0. */ 
1579 KTX_TTF_RGBA4444 = 16, 
1580 /*!< 16bpp RGBA image stored in raster (not block) order in memory, 
1581 R at bit position 12, A at bit position 0. */ 
1582 
1583 // Values for automatic selection of RGB or RGBA depending if alpha 
1584 // present. 
1585 KTX_TTF_ETC = 22, 
1586 /*!< Automatically selects @c KTX_TTF_ETC1_RGB or 
1587 @c KTX_TTF_ETC2_RGBA according to presence of alpha. */ 
1588 KTX_TTF_BC1_OR_3 = 23, 
1589 /*!< Automatically selects @c KTX_TTF_BC1_RGB or 
1590 @c KTX_TTF_BC3_RGBA according to presence of alpha. */ 
1591 
1592 KTX_TTF_NOSELECTION = 0x7fffffff, 
1593 
1594 // Old enums for compatibility with code compiled against previous 
1595 // versions of libktx. 
1596 KTX_TF_ETC1 = KTX_TTF_ETC1_RGB, 
1597 //!< @deprecated Use #KTX_TTF_ETC1_RGB. 
1598 KTX_TF_ETC2 = KTX_TTF_ETC, 
1599 //!< @deprecated Use #KTX_TTF_ETC. 
1600 KTX_TF_BC1 = KTX_TTF_BC1_RGB, 
1601 //!< @deprecated Use #KTX_TTF_BC1_RGB. 
1602 KTX_TF_BC3 = KTX_TTF_BC3_RGBA, 
1603 //!< @deprecated Use #KTX_TTF_BC3_RGBA. 
1604 KTX_TF_BC4 = KTX_TTF_BC4_R, 
1605 //!< @deprecated Use #KTX_TTF_BC4_R. 
1606 KTX_TF_BC5 = KTX_TTF_BC5_RG, 
1607 //!< @deprecated Use #KTX_TTF_BC5_RG. 
1608 KTX_TTF_BC7_M6_RGB = KTX_TTF_BC7_RGBA, 
1609 //!< @deprecated Use #KTX_TTF_BC7_RGBA. 
1610 KTX_TTF_BC7_M5_RGBA = KTX_TTF_BC7_RGBA, 
1611 //!< @deprecated Use #KTX_TTF_BC7_RGBA. 
1612 KTX_TF_BC7_M6_OPAQUE_ONLY = KTX_TTF_BC7_RGBA, 
1613 //!< @deprecated Use #KTX_TTF_BC7_RGBA 
1614 KTX_TF_PVRTC1_4_OPAQUE_ONLY = KTX_TTF_PVRTC1_4_RGB 
1615 //!< @deprecated Use #KTX_TTF_PVRTC1_4_RGB. 
1616} ktx_transcode_fmt_e; 
1617 
1618/** 
1619 * @~English 
1620 * @brief Flags guiding transcoding of Basis Universal compressed textures. 
1621 */ 
1622typedef enum ktx_transcode_flag_bits_e { 
1623 KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 = 2, 
1624 /*!< PVRTC1: decode non-pow2 ETC1S texture level to the next larger 
1625 power of 2 (not implemented yet, but we're going to support it). 
1626 Ignored if the slice's dimensions are already a power of 2. 
1627 */ 
1628 KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS = 4, 
1629 /*!< When decoding to an opaque texture format, if the Basis data has 
1630 alpha, decode the alpha slice instead of the color slice to the 
1631 output texture format. Has no effect if there is no alpha data. 
1632 */ 
1633 KTX_TF_HIGH_QUALITY = 32, 
1634 /*!< Request higher quality transcode of UASTC to BC1, BC3, ETC2_EAC_R11 and 
1635 ETC2_EAC_RG11. The flag is unused by other UASTC transcoders. 
1636 */ 
1637} ktx_transcode_flag_bits_e; 
1638typedef ktx_uint32_t ktx_transcode_flags; 
1639 
1640KTX_API KTX_error_code KTX_APIENTRY 
1641ktxTexture2_TranscodeBasis(ktxTexture2* This, ktx_transcode_fmt_e fmt, 
1642 ktx_transcode_flags transcodeFlags); 
1643 
1644/* 
1645 * Returns a string corresponding to a KTX error code. 
1646 */ 
1647KTX_API const char* KTX_APIENTRY 
1648ktxErrorString(KTX_error_code error); 
1649 
1650/* 
1651 * Returns a string corresponding to a supercompression scheme. 
1652 */ 
1653KTX_API const char* KTX_APIENTRY 
1654ktxSupercompressionSchemeString(ktxSupercmpScheme scheme); 
1655 
1656/* 
1657 * Returns a string corresponding to a transcode target format. 
1658 */ 
1659KTX_API const char* KTX_APIENTRY 
1660ktxTranscodeFormatString(ktx_transcode_fmt_e format); 
1661 
1662KTX_API KTX_error_code KTX_APIENTRY ktxHashList_Create(ktxHashList** ppHl); 
1663KTX_API KTX_error_code KTX_APIENTRY 
1664ktxHashList_CreateCopy(ktxHashList** ppHl, ktxHashList orig); 
1665KTX_API void KTX_APIENTRY ktxHashList_Construct(ktxHashList* pHl); 
1666KTX_API void KTX_APIENTRY 
1667ktxHashList_ConstructCopy(ktxHashList* pHl, ktxHashList orig); 
1668KTX_API void KTX_APIENTRY ktxHashList_Destroy(ktxHashList* head); 
1669KTX_API void KTX_APIENTRY ktxHashList_Destruct(ktxHashList* head); 
1670 
1671/* 
1672 * Adds a key-value pair to a hash list. 
1673 */ 
1674KTX_API KTX_error_code KTX_APIENTRY 
1675ktxHashList_AddKVPair(ktxHashList* pHead, const char* key, 
1676 unsigned int valueLen, const void* value); 
1677 
1678/* 
1679 * Deletes a ktxHashListEntry from a ktxHashList. 
1680 */ 
1681KTX_API KTX_error_code KTX_APIENTRY 
1682ktxHashList_DeleteEntry(ktxHashList* pHead, ktxHashListEntry* pEntry); 
1683 
1684/* 
1685 * Finds the entry for a key in a ktxHashList and deletes it. 
1686 */ 
1687KTX_API KTX_error_code KTX_APIENTRY 
1688ktxHashList_DeleteKVPair(ktxHashList* pHead, const char* key); 
1689 
1690/* 
1691 * Looks up a key and returns the ktxHashListEntry. 
1692 */ 
1693KTX_API KTX_error_code KTX_APIENTRY 
1694ktxHashList_FindEntry(ktxHashList* pHead, const char* key, 
1695 ktxHashListEntry** ppEntry); 
1696 
1697/* 
1698 * Looks up a key and returns the value. 
1699 */ 
1700KTX_API KTX_error_code KTX_APIENTRY 
1701ktxHashList_FindValue(ktxHashList* pHead, const char* key, 
1702 unsigned int* pValueLen, void** pValue); 
1703 
1704/* 
1705 * Return the next entry in a ktxHashList. 
1706 */ 
1707KTX_API ktxHashListEntry* KTX_APIENTRY 
1708ktxHashList_Next(ktxHashListEntry* entry); 
1709 
1710/* 
1711 * Sorts a ktxHashList into order of the key codepoints. 
1712 */ 
1713KTX_API KTX_error_code KTX_APIENTRY 
1714ktxHashList_Sort(ktxHashList* pHead); 
1715 
1716/* 
1717 * Serializes a ktxHashList to a block of memory suitable for 
1718 * writing to a KTX file. 
1719 */ 
1720KTX_API KTX_error_code KTX_APIENTRY 
1721ktxHashList_Serialize(ktxHashList* pHead, 
1722 unsigned int* kvdLen, unsigned char** kvd); 
1723 
1724/* 
1725 * Creates a hash table from the serialized data read from a 
1726 * a KTX file. 
1727 */ 
1728KTX_API KTX_error_code KTX_APIENTRY 
1729ktxHashList_Deserialize(ktxHashList* pHead, unsigned int kvdLen, void* kvd); 
1730 
1731/* 
1732 * Get the key from a ktxHashListEntry 
1733 */ 
1734KTX_API KTX_error_code KTX_APIENTRY 
1735ktxHashListEntry_GetKey(ktxHashListEntry* This, 
1736 unsigned int* pKeyLen, char** ppKey); 
1737 
1738/* 
1739 * Get the value from a ktxHashListEntry 
1740 */ 
1741KTX_API KTX_error_code KTX_APIENTRY 
1742ktxHashListEntry_GetValue(ktxHashListEntry* This, 
1743 unsigned int* pValueLen, void** ppValue); 
1744 
1745/*===========================================================* 
1746 * Utilities for printing info about a KTX file. * 
1747 *===========================================================*/ 
1748 
1749KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForStdioStream(FILE* stdioStream); 
1750KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForNamedFile(const char* const filename); 
1751KTX_API KTX_error_code KTX_APIENTRY ktxPrintInfoForMemory(const ktx_uint8_t* bytes, ktx_size_t size); 
1752 
1753/*===========================================================* 
1754 * Utilities for printing info about a KTX2 file. * 
1755 *===========================================================*/ 
1756 
1757KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForMemory(const ktx_uint8_t* bytes, ktx_size_t size); 
1758KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForNamedFile(const char* const filename); 
1759KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForStdioStream(FILE* stdioStream); 
1760KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoTextForStream(ktxStream* stream); 
1761KTX_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); 
1762KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForNamedFile(const char* const filename, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified); 
1763KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForStdioStream(FILE* stdioStream, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified); 
1764KTX_API KTX_error_code KTX_APIENTRY ktxPrintKTX2InfoJSONForStream(ktxStream* stream, ktx_uint32_t base_indent, ktx_uint32_t indent_width, bool minified); 
1765 
1766#ifdef __cplusplus 
1767} 
1768#endif 
1769 
1770/** 
1771@~English 
1772@page libktx_history Revision History 
1773 
1774No longer updated. Kept to preserve ancient history. For more recent history see the repo log at 
1775https://github.com/KhronosGroup/KTX-Software. See also the Release Notes in the repo. 
1776 
1777@section v8 Version 4.0 
1778Added: 
1779@li Support for KTX Version 2. 
1780@li Support for encoding and transcoding Basis Universal images in KTX Version 2 files. 
1781@li Function to print info about a KTX file. 
1782 
1783@section v7 Version 3.0.1 
1784Fixed: 
1785@li GitHub issue #159: compile failure with recent Vulkan SDKs. 
1786@li Incorrect mapping of GL DXT3 and DXT5 formats to Vulkan equivalents. 
1787@li Incorrect BC4 blocksize. 
1788@li Missing mapping of PVRTC formats from GL to Vulkan. 
1789@li Incorrect block width and height calculations for sizes that are not 
1790 a multiple of the block size. 
1791@li Incorrect KTXorientation key in test images. 
1792 
1793@section v6 Version 3.0 
1794Added: 
1795@li new ktxTexture object based API for reading KTX files without an OpenGL context. 
1796@li Vulkan loader. @#include <ktxvulkan.h> to use it. 
1797 
1798Changed: 
1799@li ktx.h to not depend on KHR/khrplatform.h and GL{,ES*}/gl{corearb,}.h. 
1800 Applications using OpenGL must now include these files themselves. 
1801@li ktxLoadTexture[FMN], removing the hack of loading 1D textures as 2D textures 
1802 when the OpenGL context does not support 1D textures. 
1803 KTX_UNSUPPORTED_TEXTURE_TYPE is now returned. 
1804 
1805@section v5 Version 2.0.2 
1806Added: 
1807@li Support for cubemap arrays. 
1808 
1809Changed: 
1810@li New build system 
1811 
1812Fixed: 
1813@li GitHub issue #40: failure to byte-swap key-value lengths. 
1814@li GitHub issue #33: returning incorrect target when loading cubemaps. 
1815@li GitHub PR #42: loading of texture arrays. 
1816@li GitHub PR #41: compilation error when KTX_OPENGL_ES2=1 defined. 
1817@li GitHub issue #39: stack-buffer-overflow in toktx 
1818@li Don't use GL_EXTENSIONS on recent OpenGL versions. 
1819 
1820@section v4 Version 2.0.1 
1821Added: 
1822@li CMake build files. Thanks to Pavel Rotjberg for the initial version. 
1823 
1824Changed: 
1825@li ktxWriteKTXF to check the validity of the type & format combinations 
1826 passed to it. 
1827 
1828Fixed: 
1829@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=999">999</a>: 16-bit luminance texture cannot be written. 
1830@li compile warnings from compilers stricter than MS Visual C++. Thanks to 
1831 Pavel Rotjberg. 
1832 
1833@section v3 Version 2.0 
1834Added: 
1835@li support for decoding ETC2 and EAC formats in the absence of a hardware 
1836 decoder. 
1837@li support for converting textures with legacy LUMINANCE, LUMINANCE_ALPHA, 
1838 etc. formats to the equivalent R, RG, etc. format with an 
1839 appropriate swizzle, when loading in OpenGL Core Profile contexts. 
1840@li ktxErrorString function to return a string corresponding to an error code. 
1841@li tests for ktxLoadTexture[FN] that run under OpenGL ES 3.0 and OpenGL 3.3. 
1842 The latter includes an EGL on WGL wrapper that makes porting apps between 
1843 OpenGL ES and OpenGL easier on Windows. 
1844@li more texture formats to ktxLoadTexture[FN] and toktx tests. 
1845 
1846Changed: 
1847@li ktxLoadTexture[FMN] to discover the capabilities of the GL context at 
1848 run time and load textures, or not, according to those capabilities. 
1849 
1850Fixed: 
1851@li failure of ktxWriteKTXF to pad image rows to 4 bytes as required by the KTX 
1852 format. 
1853@li ktxWriteKTXF exiting with KTX_FILE_WRITE_ERROR when attempting to write 
1854 more than 1 byte of face-LOD padding. 
1855 
1856Although there is only a very minor API change, the addition of ktxErrorString, 
1857the functional changes are large enough to justify bumping the major revision 
1858number. 
1859 
1860@section v2 Version 1.0.1 
1861Implemented ktxLoadTextureM. 
1862Fixed the following: 
1863@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=571">571</a>: crash when null passed for pIsMipmapped. 
1864@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=572">572</a>: memory leak when unpacking ETC textures. 
1865@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. 
1866@li Public Bugzilla <a href="http://www.khronos.org/bugzilla/show_bug.cgi?id=576">576</a>: various small fixes. 
1867 
1868Thanks to Krystian Bigaj for the ktxLoadTextureM implementation and these fixes. 
1869 
1870@section v1 Version 1.0 
1871Initial release. 
1872 
1873*/ 
1874 
1875#endif /* KTX_H_A55A6F00956F42F3A137C11929827FE1 */ 
1876