🔥 KTXForge

Encode KTX textures without learning the format or opening a terminal — drop ordinary images, press Encode, move on. If you enjoy using handbrake but never learned ffmpeg command line arguments and syntax: congratulations you are a human! This tool is for you.

For people who want the result, not a ktx create degree. Sensible defaults, presets and a rules engine to hide invalid option combos; every documented option is still there when you need it. Inspect .ktx / .ktx2 the same way: drop a file, no CLI.

Built with Tauri, runs in Windows, macOS, and Linux.

📸 Highlights

Encode

Batch KTX outputs, Official presets, option explanations, wipe preview

Inspect

Drop a .ktx / .ktx2 to browse mips, layers, cubemap faces, 3D texture orbit preview, supports KTX1 / KTX2 in a dedicated window.

✨ Features

🖼️ Encoder

• Drag-and-drop images onto the main window as standalone KTX Outputs or multiple Inputs for a single KTX (Array Layers, mips, cubemap faces, depth slices)
• Encode presets Handbrake-style: pick a recipe, press Encode; full options stay editable.
• Batch of KTX outputs: one encode job per output, shared options.
• Pack multiple inputs into one KTX as array layers, cubemap faces, mip chain, or depth slices.
• Every ktx create option in the UI:
  • Formats and codecs: uncompressed Vulkan layouts, BasisLZ, UASTC LDR/HDR, ASTC block sizes, Zstd / Zlib supercompression.
  • Color / orientation / channels: transfer functions, primaries, texcoord origin, swizzle, normalize, premultiply, normal-mode, conversion warn/fail flags.
  • Mipmap generate / runtime mips, resample filters, scale / width / height, 1D / cubemap / layers / depth / levels / raw.
  • Animation packing with KTXanimData written after a successful create.
• Source vs encoded wipe preview, mip scrubbing, cubemap cross, 3D depth volume orbit.
• Everyday formats the CLI rejects (JPEG, WebP, BMP, GIF, TIFF, …) are converted in Rust before ktx create.

🔍 Inspector

• Drop .ktx / .ktx2, or open them via the OS (“Open with” / double-click on an installed build), to open a dedicated inspector window.
• Full ktx info report (JSON for KTX2, text + best-effort header for KTX1), including validation messages.
• Known metadata keys (KTXorientation, KTXswizzle, KTXwriter, KTXanimData, platform format keys, …).
• Browse mips, layers / frames, faces, and depth slices; pan / zoom; View menu zoom controls.
• Export the selected subresource as PNG or JPEG.
• Cubemap cross and CSS3D depth-volume views when the file has faces or depth.

💻 Platform

• Embedded, pinned ktx and ktx2ktx2 sidecar: no system install required.
• Installed builds register as a viewer for .ktx / .ktx2 (OS file associations).
• Auto-update.

🛠️ Development

npm ci
npm run setup      # rustfmt/clippy, cargo-machete, fetch pinned ktx sidecar
npm run tauri dev

Prerequisites: Node LTS, Git LFS (git lfs install once per machine), and Rust via rustup (stable).

On Linux you also need the usual Tauri system packages (libwebkit2gtk-4.1-dev, libappindicator3-dev, librsvg2-dev, patchelf). npm ci / npm install runs git lfs install --local (filters + hooks in .git/hooks) so a normal git push uploads LFS objects.

npm run setup installs rustfmt, clippy, and cargo-machete when missing, then stages the ktx and ktx2ktx2 sidecars.

The same tool install + fetch runs via precheck:rust before npm run check; pretauri only runs fetch-ktx (host triple) so release cross-builds stay fast.

Quality gate before commit (Rust fmt/clippy/machete, Vue build/lint/style, tests, fallow):

npm run check

Tests: one Playwright runner, one command. tests/unit covers frontend logic; tests/e2e runs real inputs through the app's Rust commands and the bundled ktx, checked with Khronos' own ktx, plus the real frontend in Chromium bridged to the same Rust. Results and the HTML report land in test-results/:

npx playwright install chromium   # once per machine
npm test

Acceptance checklist: docs/acceptance.md.

Local release-style builds that produce updater signatures need the private key from 1Password (Tech vault), not a key file on disk. See docs/updater-signing.md:

npm run tauri:build:signed

📦 Commits and releases

Commits follow Conventional Commits. On main / beta, semantic-release derives the version (feat → minor, fix / perf → patch, ! or BREAKING CHANGE: → major; other types do not release), updates CHANGELOG.md, tags, and publishes GitHub Release artifacts via Actions.

Preview the next version locally (needs a GITHUB_TOKEN with repo access):

npx semantic-release --dry-run --no-ci

Releases run only in CI (npm run release / the Release workflow). To bump the embedded ktx pin, edit ktx-version.json in a feat: or fix: commit.

Product requirements live in docs/requirements.md. Decision log: docs/decision-context.md.

📄 License

KTXForge is MIT. The embedded KTX-Software ktx sidecar ships under its own terms (primarily Apache-2.0); see src-tauri/licenses/KTX-Software-LICENSE.md.