@@ -423,6 +423,230 @@ Example using obj2gltf:
423423obj2gltf -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
428652To convert existing image files to KTX2, you can use:
0 commit comments