Skip to content

Update KTX2 docs to the ktx CLI #465

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gpx1000 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update KTX2 docs to the ktx CLI #465

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 38 additions & 42 deletions en/15_GLTF_KTX2_Migration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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
Expand All @@ -628,34 +630,28 @@ 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

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

Expand Down Expand Up @@ -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
Expand Down
Loading