diff --git a/en/15_GLTF_KTX2_Migration.adoc b/en/15_GLTF_KTX2_Migration.adoc index e552deea..5c748a46 100644 --- a/en/15_GLTF_KTX2_Migration.adoc +++ b/en/15_GLTF_KTX2_Migration.adoc @@ -466,26 +466,28 @@ There are several ways to create KTX2 files: The KTX-Software package provides command-line tools for creating KTX2 files: -* **toktx**: The primary tool for creating KTX2 files from existing images +* **ktx create**: The primary tool for creating KTX2 files from existing images + +NOTE: The standalone `toktx` executable has been superseded by the unified `ktx` CLI's `create` subcommand. Besides the command name, two things changed: the input file(s) now come *before* the output file (not after), and `--format` is required and takes a `VkFormat` name (minus the `VK_FORMAT_` prefix) rather than a short compression codec name. Basic usage: [,bash] ---- # Create a basic KTX2 file -toktx texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB texture.png texture.ktx2 # Create a KTX2 file with mipmaps -toktx --mipmap texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB --generate-mipmap texture.png texture.ktx2 -# Create a KTX2 file with Basis Universal compression -toktx --bcmp texture.ktx2 texture.png +# Create a KTX2 file with Basis Universal (ETC1S) compression +ktx create --format R8G8B8A8_SRGB --encode basis-lz texture.png texture.ktx2 -# Create a KTX2 file with specific GPU compression format (BC7) -toktx --bcmp --format BC7_RGBA texture.ktx2 texture.png +# Create a KTX2 file with a specific GPU block-compression format (BC7) +ktx create --format BC7_SRGB_BLOCK texture.png texture.ktx2 # Create a cubemap KTX2 file -toktx --cubemap cubemap.ktx2 posx.png negx.png posy.png negy.png posz.png negz.png +ktx create --format R8G8B8A8_SRGB --cubemap posx.png negx.png posy.png negy.png posz.png negz.png cubemap.ktx2 ---- ==== Using the KTX Library API @@ -540,18 +542,18 @@ KTX2 files can be created from various popular image formats: ==== From PNG/JPEG/TIFF -The simplest conversion is from standard image formats using toktx: +The simplest conversion is from standard image formats using `ktx create`: [,bash] ---- # Convert PNG to KTX2 -toktx texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB texture.png texture.ktx2 # Convert JPEG to KTX2 -toktx texture.ktx2 texture.jpg +ktx create --format R8G8B8A8_SRGB texture.jpg texture.ktx2 # Convert TIFF to KTX2 -toktx texture.ktx2 texture.tiff +ktx create --format R8G8B8A8_SRGB texture.tiff texture.ktx2 ---- ==== From DDS (DirectX Texture Format) @@ -564,27 +566,27 @@ DDS is another GPU-optimized texture format commonly used with DirectX: texconv -ft png texture.dds # Then convert PNG to KTX2 -toktx texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB texture.png texture.ktx2 ---- -Alternatively, you can use the Khronos Texture Tools: +Alternatively, you can convert an existing KTX1 file directly: [,bash] ---- -ktx2ktx2 --convert texture.dds texture.ktx2 +ktx convert texture.ktx texture.ktx2 ---- ==== From HDR/EXR (High Dynamic Range Formats) -For HDR textures: +For HDR textures, use a floating-point format instead of an 8-bit UNORM/SRGB one: [,bash] ---- # Convert HDR to KTX2 -toktx --hdr texture.ktx2 texture.hdr +ktx create --format R16G16B16A16_SFLOAT texture.hdr texture.ktx2 # Convert EXR to KTX2 (may require intermediate conversion) -toktx --hdr texture.ktx2 texture.exr +ktx create --format R16G16B16A16_SFLOAT texture.exr texture.ktx2 ---- ==== From PSD (Photoshop) @@ -595,7 +597,7 @@ For Photoshop files: ---- # Export PSD as PNG first # Then convert to KTX2 -toktx texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB texture.png texture.ktx2 ---- === Optimizing KTX2 Files @@ -609,16 +611,16 @@ KTX2 supports various compression methods: [,bash] ---- # Basis Universal compression (highly portable) -toktx --bcmp texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB --encode basis-lz texture.png texture.ktx2 # ASTC compression (good for mobile) -toktx --format ASTC_4x4_RGBA texture.ktx2 texture.png +ktx create --format ASTC_4x4_SRGB_BLOCK texture.png texture.ktx2 # BC7 compression (good for desktop) -toktx --format BC7_RGBA texture.ktx2 texture.png +ktx create --format BC7_SRGB_BLOCK texture.png texture.ktx2 # ETC2 compression (good for Android) -toktx --format ETC2_RGBA texture.ktx2 texture.png +ktx create --format ETC2_R8G8B8A8_SRGB_BLOCK texture.png texture.ktx2 ---- ==== Mipmap Generation @@ -628,21 +630,15 @@ Mipmaps improve rendering performance and quality: [,bash] ---- # Generate mipmaps -toktx --mipmap texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB --generate-mipmap texture.png texture.ktx2 -# Generate mipmaps with specific filter -toktx --mipmap --filter lanczos texture.ktx2 texture.png +# Generate mipmaps with a specific filter +ktx create --format R8G8B8A8_SRGB --generate-mipmap --mipmap-filter lanczos4 texture.png texture.ktx2 ---- ==== Metadata -KTX2 files can include metadata: - -[,bash] ----- -# Add key-value metadata -toktx --mipmap --key "author" --value "Your Name" texture.ktx2 texture.png ----- +You can inspect the key-value metadata already embedded in a KTX2 file with `ktx info`; adding custom key-value pairs at creation time is handled by a separate step in the `ktx` toolset rather than a flag on `create` — see `ktx help create` for the version of KTX-Software you have installed, since this has changed between releases. === Tools for Working with KTX2 Files @@ -650,12 +646,12 @@ Several tools are available for working with KTX2 files: ==== Command-line Tools -* **KTX-Software Suite**: - * `toktx`: Create KTX2 files - * `ktx2ktx2`: Convert between KTX versions - * `ktxinfo`: Display information about KTX files - * `ktxsc`: Apply supercompression to KTX2 files - * `ktxunpack`: Unpack a KTX file to individual images +* **KTX-Software Suite** (the `ktx` CLI, which superseded the standalone `toktx`/`ktx2ktx2`/`ktxinfo`/`ktxsc`/`ktxunpack` executables): + * `ktx create`: Create KTX2 files + * `ktx convert`: Convert between KTX versions + * `ktx info`: Display information about KTX files + * `ktx deflate`: Apply supercompression to KTX2 files + * `ktx extract`: Unpack a KTX file to individual images ==== Libraries and SDKs @@ -684,14 +680,14 @@ Several tools are available for working with KTX2 files: To convert existing image files to KTX2, you can use: -* **toktx**: A command-line tool included with the KTX-Software package +* **ktx create**: A command-line tool included with the KTX-Software package * **KTX-Software**: A library with tools for creating and manipulating KTX files -Example using toktx to create a KTX2 file with Basis Universal compression: +Example using `ktx create` to create a KTX2 file with Basis Universal compression: [,bash] ---- -toktx --bcmp texture.ktx2 texture.png +ktx create --format R8G8B8A8_SRGB --encode basis-lz texture.png texture.ktx2 ---- == Conclusion