KTX2TextureTranscoder

Transcodes texture data from KTX2.

Overview

• Uses the Basis Universal GPU Texture Codec to transcode KTX2 textures.
• XKTLoaderPlugin uses a KTX2TextureTranscoder to load textures in XKT files.
• VBOSceneModel uses a KTX2TextureTranscoder to enable us to add KTX2-encoded textures.
• Loads the Basis Codec from CDN by default, but can also be configured to load the Codec from local files.
• We also bundle the Basis Codec with the xeokit-sdk npm package, and in the repository.

What is KTX2?

A KTX2 file stores GPU texture data in the Khronos Texture 2.0 (KTX2) container format. It contains image data for a texture asset compressed with Basis Universal (BasisU) supercompression that can be transcoded to different formats depending on the support provided by the target devices. KTX2 provides a lightweight format for distributing texture assets to GPUs. Due to BasisU compression, KTX2 files can store any image format supported by GPUs.

Loading XKT files containing KTX2 textures

XKTLoaderPlugin uses a KTX2TextureTranscoder to load textures in XKT files. An XKTLoaderPlugin has its own default KTX2TextureTranscoder, configured to load the Basis Codec from the CDN. If we wish, we can override that with our own KTX2TextureTranscoder, configured to load the Codec locally.

In the example below, we'll create a Viewer and add an XKTLoaderPlugin configured with a KTX2TextureTranscoder. Then we'll use the XKTLoaderPlugin to load an XKT file that contains KTX2 textures, which the plugin will transcode using its KTX2TextureTranscoder.

We'll configure our KTX2TextureTranscoder to load the Basis Codec from a local directory. If we were happy with loading the Codec from our CDN (ie. our app will always have an Internet connection) then we could just leave out the KTX2TextureTranscoder altogether, and let the XKTLoaderPlugin use its internal default KTX2TextureTranscoder, which is configured to load the Codec from the CDN. We'll stick with loading our own Codec, in case we want to run our app without an Internet connection.

• [Run this example]

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.camera.eye = [-2.56, 8.38, 8.27];
viewer.camera.look = [13.44, 3.31, -14.83];
viewer.camera.up = [0.10, 0.98, -0.14];

const textureTranscoder = new KTX2TextureTranscoder({
    viewer,
    transcoderPath: "https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/" // <------ Path to Basis Universal transcoder
});

const xktLoader = new XKTLoaderPlugin(viewer, {
    textureTranscoder // <<------------- Transcodes KTX2 textures in XKT files
});

const sceneModel = xktLoader.load({
    id: "myModel",
    src: "./HousePlan.xkt" // <<------ XKT file with KTX2 textures
});

Loading KTX2 files into a VBOSceneModel

A SceneModel that is configured with a KTX2TextureTranscoder will allow us to load textures into it from KTX2-transcoded buffers or files.

In the example below, we'll create a Viewer, containing a VBOSceneModel configured with a KTX2TextureTranscoder.

We'll then programmatically create a simple object within the VBOSceneModel, consisting of a single box mesh with a texture loaded from a KTX2 file, which our VBOSceneModel internally transcodes, using its KTX2TextureTranscoder.

As in the previous example, we'll configure our KTX2TextureTranscoder to load the Basis Codec from a local directory.

• Run a similar example

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-21.80, 4.01, 6.56];
viewer.scene.camera.look = [0, -5.75, 0];
viewer.scene.camera.up = [0.37, 0.91, -0.11];

const textureTranscoder = new KTX2TextureTranscoder({
    viewer,
    transcoderPath: "https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/" // <------ Path to BasisU transcoder module
});

const vboSceneModel = new VBOSceneModel(viewer.scene, {
     id: "myModel",
     textureTranscoder // <<-------------------- Configure model with our transcoder
 });

vboSceneModel.createTexture({
     id: "myColorTexture",
     src: "../assets/textures/compressed/sample_uastc_zstd.ktx2" // <<----- KTX2 texture asset
});

vboSceneModel.createTexture({
     id: "myMetallicRoughnessTexture",
     src: "../assets/textures/alpha/crosshatchAlphaMap.jpg" // <<----- JPEG texture asset
});

vboSceneModel.createTextureSet({
     id: "myTextureSet",
     colorTextureId: "myColorTexture",
     metallicRoughnessTextureId: "myMetallicRoughnessTexture"
 });

vboSceneModel.createMesh({
     id: "myMesh",
     textureSetId: "myTextureSet",
     primitive: "triangles",
     positions: [1, 1, 1, ...],
     normals: [0, 0, 1, 0, ...],
     uv: [1, 0, 0, ...],
     indices: [0, 1, 2, ...],
 });

vboSceneModel.createEntity({
     id: "myEntity",
     meshIds: ["myMesh"]
 });

vboSceneModel.finalize();

Loading KTX2 ArrayBuffers into a VBOSceneModel

A SceneModel that is configured with a KTX2TextureTranscoder will also allow us to load textures into it from KTX2 ArrayBuffers.

In the example below, we'll create a Viewer, containing a VBOSceneModel configured with a KTX2TextureTranscoder.

We'll then programmatically create a simple object within the VBOSceneModel, consisting of a single mesh with a texture loaded from a KTX2 ArrayBuffer, which our VBOSceneModel internally transcodes, using its KTX2TextureTranscoder.

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-21.80, 4.01, 6.56];
viewer.scene.camera.look = [0, -5.75, 0];
viewer.scene.camera.up = [0.37, 0.91, -0.11];

const textureTranscoder = new KTX2TextureTranscoder({
    viewer,
    transcoderPath: "https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/" // <------ Path to BasisU transcoder module
});

const vboSceneModel = new VBOSceneModel(viewer.scene, {
     id: "myModel",
     textureTranscoder // <<-------------------- Configure model with our transcoder
});

utils.loadArraybuffer("../assets/textures/compressed/sample_uastc_zstd.ktx2",(arrayBuffer) => {

    vboSceneModel.createTexture({
        id: "myColorTexture",
        buffers: [arrayBuffer] // <<----- KTX2 texture asset
    });

    vboSceneModel.createTexture({
        id: "myMetallicRoughnessTexture",
        src: "../assets/textures/alpha/crosshatchAlphaMap.jpg" // <<----- JPEG texture asset
    });

    vboSceneModel.createTextureSet({
       id: "myTextureSet",
       colorTextureId: "myColorTexture",
       metallicRoughnessTextureId: "myMetallicRoughnessTexture"
    });

    vboSceneModel.createMesh({
         id: "myMesh",
         textureSetId: "myTextureSet",
         primitive: "triangles",
         positions: [1, 1, 1, ...],
         normals: [0, 0, 1, 0, ...],
         uv: [1, 0, 0, ...],
         indices: [0, 1, 2, ...],
    });

    vboSceneModel.createEntity({
        id: "myEntity",
        meshIds: ["myMesh"]
    });

    vboSceneModel.finalize();
});