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