1. Introduction

In Castle Game Engine we fully support KTX, Khronos Texture Format.

There’s nothing special you need to do to use KTX files in Castle Game Engine. Just load images in KTX format and display them as usual. Yo can refer to KTX image anywhere you would refer to an image (texture), e.g. you point to their URLs from TCastleImageControl.Url, TCastleImageTransform.Url, TDrawableImage, TImageTextureNode. See using images in the manual.

2. Tooling

Our Castle Image Viewer supports KTX and allows to view each subimage of a KTX file.

We also have example utility image_decompose that allows to extract all subimages from a KTX file.

You may find example KTX images inside our demo models. Also KTX-Software has some samples (look in tests subdirectory).

3. Features

KTX is an excellent image format with a number of graphic features useful when it comes to using it for textures and 3D:

Can utilize GPU compression (images are compressed not only on disk, but also in GPU memory). We support these GPU-compressed formats in KTX:
- S3TC (DXT* formats, often available on desktops),
- ATITC (ATI compression, available on some mobile devices),
- PVRTC (PowerVR compression, available on some mobile devices),
- ETC1 (Ericsson compression, often available on mobile devices, but without alpha support).
- More compressed formats can be trivially added, just submit a bugreport with a sample KTX file.
Float-based formats are fully supported. When encountered, KTX files with float-based data will be read to engine float-based formats, and passed as floats to the GPU (so your shaders can enjoy data that has higher-precision and is not bounded to the [0, 1] range):
- TGrayscaleFloatImage,
- TGrayscaleAlphaFloatImage,
- TRGBFloatImage,
- TRGBAlphaFloatImage.
16-bit image formats are also supported, upon reading we will convert them to 32-bit float-based formats (so we waste memory, but we keep the precision).
Textures can have explicit mipmaps (allows texture have better quality when viewer from far away).
Volume (3D) textures.
Configurable orientation of the image data in file. KTX data may be specified in top-to-bottom or bottom-to-top order. For 3D images, the slices can additionally be in front-to-back or back-to-front order. We support all these possibilities.
Cube map can be stored — this means that we effectively have 6 images (for skyboxes, reflections, etc.). TODO: We don’t support cubemap yet, but we plan to add it. Submit a bugreport with a sample KTX file to make it happen sooner!
Both loading and saving of KTX files is implemented in Castle Game Engine.
Reading certain KTX configurations is ultra-optimized, as their format matches precisely the format of image data in memory of the engine, which in turn matches the format expected by GPU.

When saving, we always use the optimized format, if only the padding matches. Almost always this results in ultra-optimized saving too.

To debug when the optimized writing / reading takes place, define the CASTLE_KTX_LOG_SPEED symbol when compiling your program.

We support KTX 1 right now. We plan to support KTX 2 (with KHR_texture_basisu) in the future too.

4. Example usage to speedup loading time: regenerate all your images to .ktx format

Read auto-generated textures documentation to understand the idea of auto-generating textures to a different format/size/compression.

In short, you will need to execute castle-engine auto-generate-textures from the command-line, or use the "Run → Auto-Generate Textures" menu item in CGE editor.

Place this in data/material_properties.xml:

<?xml version="1.0"?>

<!--
Rules for automatic processing
(converting, compressing, downscaling, mipmap creation...) of images.
See https://castle-engine.io/creating_data_auto_generated_textures.php
-->

<properties>
  <!--
  Make not-compressed and not-downscaled version in castle-image format
  of images in textures/ .
  The castle-image format will load faster than anything else in CGE.
  -->
  <auto_generated_textures>
    <preferred_output_format extension=".ktx" />
    <trivial_uncompressed_convert />
    <include path="textures/*" recursive="True" />
  </auto_generated_textures>
</properties>

See usage in 3d_games/walking_adventure.

5. Enumerating KTX subimages using Pascal

You can use CastleInternalCompositeImage unit to load KTX files and explicitly iterate over subimages inside KTX. For example, to iterate over items in a texture array in KTX, for any purpose.

Warning

As the name suggests, CastleInternalCompositeImage is an internal unit and its API may change arbitrarily in the future. Please let us know if you actually need this functionality and why — at the very least, we will consider making it "official" (e.g. unit CastleCompositeImage) and we will put effort to not break its API.

To improve this documentation just edit this page and create a pull request to cge-www repository.