Skip to content

Commit a73739c

Browse files
committed
Add comprehensive documentation for creating and optimizing KTX2 files
- Expanded guide with methods to create KTX2 files using tools, libraries, and image editing software. - Included instructions for converting popular formats (PNG, JPEG, DDS, HDR, etc.) to KTX2. - Detailed optimization techniques like compression, mipmaps, and metadata. - Listed tools, libraries, viewers, and game engine integrations for working with KTX2 files.
1 parent e297a2f commit a73739c

File tree

1 file changed

+224
-0
lines changed

1 file changed

+224
-0
lines changed

en/15_GLTF_KTX2_Migration.adoc

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -423,6 +423,230 @@ Example using obj2gltf:
423423
obj2gltf -i model.obj -o model.gltf
424424
----
425425

426+
== Working with KTX2 Files
427+
428+
=== Creating KTX2 Files
429+
430+
There are several ways to create KTX2 files:
431+
432+
==== Using the KTX-Software Tools
433+
434+
The KTX-Software package provides command-line tools for creating KTX2 files:
435+
436+
* **toktx**: The primary tool for creating KTX2 files from existing images
437+
438+
Basic usage:
439+
440+
[,bash]
441+
----
442+
# Create a basic KTX2 file
443+
toktx texture.ktx2 texture.png
444+
445+
# Create a KTX2 file with mipmaps
446+
toktx --mipmap texture.ktx2 texture.png
447+
448+
# Create a KTX2 file with Basis Universal compression
449+
toktx --bcmp texture.ktx2 texture.png
450+
451+
# Create a KTX2 file with specific GPU compression format (BC7)
452+
toktx --bcmp --format BC7_RGBA texture.ktx2 texture.png
453+
454+
# Create a cubemap KTX2 file
455+
toktx --cubemap cubemap.ktx2 posx.png negx.png posy.png negy.png posz.png negz.png
456+
----
457+
458+
==== Using the KTX Library API
459+
460+
You can also create KTX2 files programmatically using the KTX library API:
461+
462+
[,c{pp}]
463+
----
464+
#include <ktx.h>
465+
466+
// Create a new KTX2 texture
467+
ktxTexture2* texture;
468+
ktxTextureCreateInfo createInfo = {
469+
.vkFormat = VK_FORMAT_R8G8B8A8_SRGB,
470+
.baseWidth = 512,
471+
.baseHeight = 512,
472+
.baseDepth = 1,
473+
.numDimensions = 2,
474+
.numLevels = 1,
475+
.numLayers = 1,
476+
.numFaces = 1,
477+
.isArray = KTX_FALSE,
478+
.generateMipmaps = KTX_FALSE
479+
};
480+
481+
KTX_error_code result = ktxTexture2_Create(&createInfo, KTX_TEXTURE_CREATE_ALLOC_STORAGE, &texture);
482+
483+
// Set image data
484+
uint32_t* imageData = new uint32_t[512 * 512];
485+
// ... fill image data ...
486+
ktxTexture_SetImageFromMemory(ktxTexture(texture), 0, 0, 0, imageData, 512 * 512 * 4);
487+
488+
// Write to file
489+
ktxTexture_WriteToNamedFile(ktxTexture(texture), "output.ktx2");
490+
491+
// Clean up
492+
ktxTexture_Destroy(ktxTexture(texture));
493+
delete[] imageData;
494+
----
495+
496+
==== Using Image Editing Software
497+
498+
Some image editing and 3D modeling software can export directly to KTX2:
499+
500+
* **Substance Designer**: Can export textures directly to KTX2 format
501+
* **Blender**: With plugins, can export textures to KTX2
502+
* **GIMP**: With the KTX plugin, can save images as KTX2
503+
504+
=== Converting from Other Formats to KTX2
505+
506+
KTX2 files can be created from various popular image formats:
507+
508+
==== From PNG/JPEG/TIFF
509+
510+
The simplest conversion is from standard image formats using toktx:
511+
512+
[,bash]
513+
----
514+
# Convert PNG to KTX2
515+
toktx texture.ktx2 texture.png
516+
517+
# Convert JPEG to KTX2
518+
toktx texture.ktx2 texture.jpg
519+
520+
# Convert TIFF to KTX2
521+
toktx texture.ktx2 texture.tiff
522+
----
523+
524+
==== From DDS (DirectX Texture Format)
525+
526+
DDS is another GPU-optimized texture format commonly used with DirectX:
527+
528+
[,bash]
529+
----
530+
# Using texconv to convert DDS to PNG first
531+
texconv -ft png texture.dds
532+
533+
# Then convert PNG to KTX2
534+
toktx texture.ktx2 texture.png
535+
----
536+
537+
Alternatively, you can use the Khronos Texture Tools:
538+
539+
[,bash]
540+
----
541+
ktx2ktx2 --convert texture.dds texture.ktx2
542+
----
543+
544+
==== From HDR/EXR (High Dynamic Range Formats)
545+
546+
For HDR textures:
547+
548+
[,bash]
549+
----
550+
# Convert HDR to KTX2
551+
toktx --hdr texture.ktx2 texture.hdr
552+
553+
# Convert EXR to KTX2 (may require intermediate conversion)
554+
toktx --hdr texture.ktx2 texture.exr
555+
----
556+
557+
==== From PSD (Photoshop)
558+
559+
For Photoshop files:
560+
561+
[,bash]
562+
----
563+
# Export PSD as PNG first
564+
# Then convert to KTX2
565+
toktx texture.ktx2 texture.png
566+
----
567+
568+
=== Optimizing KTX2 Files
569+
570+
To get the most out of KTX2 files, consider these optimization techniques:
571+
572+
==== Compression Options
573+
574+
KTX2 supports various compression methods:
575+
576+
[,bash]
577+
----
578+
# Basis Universal compression (highly portable)
579+
toktx --bcmp texture.ktx2 texture.png
580+
581+
# ASTC compression (good for mobile)
582+
toktx --format ASTC_4x4_RGBA texture.ktx2 texture.png
583+
584+
# BC7 compression (good for desktop)
585+
toktx --format BC7_RGBA texture.ktx2 texture.png
586+
587+
# ETC2 compression (good for Android)
588+
toktx --format ETC2_RGBA texture.ktx2 texture.png
589+
----
590+
591+
==== Mipmap Generation
592+
593+
Mipmaps improve rendering performance and quality:
594+
595+
[,bash]
596+
----
597+
# Generate mipmaps
598+
toktx --mipmap texture.ktx2 texture.png
599+
600+
# Generate mipmaps with specific filter
601+
toktx --mipmap --filter lanczos texture.ktx2 texture.png
602+
----
603+
604+
==== Metadata
605+
606+
KTX2 files can include metadata:
607+
608+
[,bash]
609+
----
610+
# Add key-value metadata
611+
toktx --mipmap --key "author" --value "Your Name" texture.ktx2 texture.png
612+
----
613+
614+
=== Tools for Working with KTX2 Files
615+
616+
Several tools are available for working with KTX2 files:
617+
618+
==== Command-line Tools
619+
620+
* **KTX-Software Suite**:
621+
* `toktx`: Create KTX2 files
622+
* `ktx2ktx2`: Convert between KTX versions
623+
* `ktxinfo`: Display information about KTX files
624+
* `ktxsc`: Apply supercompression to KTX2 files
625+
* `ktxunpack`: Unpack a KTX file to individual images
626+
627+
==== Libraries and SDKs
628+
629+
* **KTX-Software Library**: C/C++ library for reading, writing, and processing KTX files
630+
* **libktx**: The core library used by KTX-Software
631+
* **Basis Universal**: Compression technology used in KTX2
632+
* **Vulkan SDK**: Includes KTX tools and libraries
633+
* **glTF-Transform**: JavaScript library that can process KTX2 textures in glTF files
634+
635+
==== Viewers and Debuggers
636+
637+
* **KTX Load Test**: Part of KTX-Software, for viewing KTX files
638+
* **RenderDoc**: Graphics debugger that can inspect KTX2 textures
639+
* **Khronos Texture Tools**: Includes viewers for KTX files
640+
* **glTF Viewer**: Many glTF viewers support KTX2 textures
641+
642+
==== Integration with Game Engines
643+
644+
* **Unity**: Supports KTX2 through plugins
645+
* **Unreal Engine**: Supports KTX2 through plugins
646+
* **Godot**: Has KTX2 support in development
647+
* **Three.js**: Supports KTX2 textures
648+
* **Babylon.js**: Supports KTX2 textures
649+
426650
=== Converting Images to KTX2
427651

428652
To convert existing image files to KTX2, you can use:

0 commit comments

Comments
 (0)