Reference Source
public class | source

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.

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: "./../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.

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: "./../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: "./../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();
});

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, transcoderPath: String, workerLimit: Number)

Creates a new KTX2TextureTranscoder.

Method Summary

Public Methods
public

Destroys this KTX2TextureTranscoder

public

transcode(buffers: ArrayBuffer[], config: *, texture: Texture2D): Promise

Transcodes texture data from transcoded buffers into a Texture2D.

Public Constructors

public constructor(viewer: Viewer, transcoderPath: String, workerLimit: Number) source

Creates a new KTX2TextureTranscoder.

Params:

NameTypeAttributeDescription
viewer Viewer

The Viewer that our KTX2TextureTranscoder will be used with. This KTX2TextureTranscoder must only be used to transcode textures for this Viewer. This is because the Viewer's capabilities will decide what target GPU formats this KTX2TextureTranscoder will transcode to.

transcoderPath String
  • optional
  • default: "https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/"

Path to the Basis transcoder module that internally does the heavy lifting for our KTX2TextureTranscoder. If we omit this configuration, then our KTX2TextureTranscoder will load it from https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/ by default. Therefore, make sure your application is connected to the internet if you wish to use the default transcoder path.

workerLimit Number
  • optional

The maximum number of Workers to use for transcoding.

Public Methods

public destroy() source

Destroys this KTX2TextureTranscoder

public transcode(buffers: ArrayBuffer[], config: *, texture: Texture2D): Promise source

Transcodes texture data from transcoded buffers into a Texture2D.

Params:

NameTypeAttributeDescription
buffers ArrayBuffer[]

Transcoded texture data. Given as an array of buffers so that we can support multi-image textures, such as cube maps.

config *

Transcoding options.

texture Texture2D

The texture to load.

Return:

Promise

Resolves when the texture has loaded.