Skip to content

KTX2Loader: Add setTranscoderUrls() for custom transcoder URLs #31446

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
wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

KTX2Loader: Add setTranscoderUrls() for custom transcoder URLs #31446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e1ff610
KTX2Loader: Add setTranscoderUrls() for custom transcoder URLs
saqsun Jul 19, 2025
38c017a
BREAKING: change KTX2Loader.setTranscoderPath to object-based signature
saqsun Jul 28, 2025
768b62f
test: fix e2e failures after setTranscoderPath API change
saqsun Jul 29, 2025
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
5 changes: 4 additions & 1 deletion docs/examples/en/loaders/KTX2Loader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,10 @@ <h2>Code Example</h2>

<code>
var ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'examples/jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
ktx2Loader.detectSupport( renderer );
ktx2Loader.load( 'diffuse.ktx2', function ( texture ) {

Expand Down
5 changes: 4 additions & 1 deletion docs/examples/zh/loaders/KTX2Loader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,10 @@ <h2>代码示例</h2>

<code>
var ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'examples/jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
ktx2Loader.detectSupport( renderer );
ktx2Loader.load( 'diffuse.ktx2', function ( texture ) {

Expand Down
5 changes: 4 additions & 1 deletion editor/js/Loader.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -992,7 +992,10 @@ function Loader( editor ) {
dracoLoader.setDecoderPath( '../examples/jsm/libs/draco/gltf/' );

const ktx2Loader = new KTX2Loader( manager );
ktx2Loader.setTranscoderPath( '../examples/jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} );

editor.signals.rendererDetectKTX2Support.dispatch( ktx2Loader );

Expand Down
5 changes: 4 additions & 1 deletion editor/js/libs/ui.three.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,10 @@ class UITexture extends UISpan {
const arrayBuffer = event.target.result;
const blobURL = URL.createObjectURL( new Blob( [ arrayBuffer ] ) );
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( '../../examples/jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} );
editor.signals.rendererDetectKTX2Support.dispatch( ktx2Loader );

ktx2Loader.load( blobURL, function ( texture ) {
Expand Down
5 changes: 4 additions & 1 deletion examples/jsm/libs/basis/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@ Both are dependencies of `KTX2Loader`:

```js
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'examples/jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
ktx2Loader.detectSupport( renderer );
ktx2Loader.load( 'diffuse.ktx2', function ( texture ) {

Expand Down
31 changes: 21 additions & 10 deletions examples/jsm/loaders/KTX2Loader.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,10 @@ let _zstd;
*
* ```js
* const loader = new KTX2Loader();
* loader.setTranscoderPath( 'examples/jsm/libs/basis/' );
* loader.setTranscoderPath( {
* js: 'examples/jsm/libs/basis/basis_transcoder.js',
* wasm: 'examples/jsm/libs/basis/basis_transcoder.wasm'
* } );
* loader.detectSupport( renderer );
* const texture = loader.loadAsync( 'diffuse.ktx2' );
* ```
Expand All @@ -119,7 +122,8 @@ class KTX2Loader extends Loader {

super( manager );

this.transcoderPath = '';
this.transcoderJsPath = null;
this.transcoderWasmPath = null;
this.transcoderBinary = null;
this.transcoderPending = null;

Expand All @@ -141,16 +145,19 @@ class KTX2Loader extends Loader {
}

/**
* Sets the transcoder path.
* Sets the transcoder paths.
*
* The WASM transcoder and JS wrapper are available from the `examples/jsm/libs/basis` directory.
*
* @param {string} path - The transcoder path to set.
* @param {Object} paths - An object with js and wasm fields
* @param {string} paths.js - Full URL to the basis_transcoder.js file
* @param {string} paths.wasm - Full URL to the basis_transcoder.wasm file
* @return {KTX2Loader} A reference to this loader.
*/
setTranscoderPath( path ) {
setTranscoderPath( { js, wasm } ) {

this.transcoderPath = path;
this.transcoderJsPath = js;
this.transcoderWasmPath = wasm;

return this;

Expand Down Expand Up @@ -241,18 +248,22 @@ class KTX2Loader extends Loader {

if ( ! this.transcoderPending ) {

if ( ! this.transcoderJsPath || ! this.transcoderWasmPath ) {

throw new Error( 'THREE.KTX2Loader: Missing transcoder paths. Use .setTranscoderPath() to set the paths.' );

}

// Load transcoder wrapper.
const jsLoader = new FileLoader( this.manager );
jsLoader.setPath( this.transcoderPath );
jsLoader.setWithCredentials( this.withCredentials );
const jsContent = jsLoader.loadAsync( 'basis_transcoder.js' );
const jsContent = jsLoader.loadAsync( this.transcoderJsPath );

// Load transcoder WASM binary.
const binaryLoader = new FileLoader( this.manager );
binaryLoader.setPath( this.transcoderPath );
binaryLoader.setResponseType( 'arraybuffer' );
binaryLoader.setWithCredentials( this.withCredentials );
const binaryContent = binaryLoader.loadAsync( 'basis_transcoder.wasm' );
const binaryContent = binaryLoader.loadAsync( this.transcoderWasmPath );

this.transcoderPending = Promise.all( [ jsContent, binaryContent ] )
.then( ( [ jsContent, binaryContent ] ) => {
Expand Down
5 changes: 4 additions & 1 deletion examples/misc_exporter_gltf.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -484,7 +484,10 @@
// Exporting compressed textures and meshes (KTX2 / Draco / Meshopt)
// ---------------------------------------------------------------------
const ktx2Loader = new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupport( renderer );

const gltfLoader = new GLTFLoader().setPath( 'models/gltf/' );
Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_loader_gltf_compressed.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,10 @@
scene.add( grid );

const ktx2Loader = new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupport( renderer );

const loader = new GLTFLoader().setPath( 'models/gltf/' );
Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_loader_texture_ktx2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,10 @@
renderer.setPixelRatio( window.devicePixelRatio );

const loader = new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.setPath( 'textures/ktx2/' )
.detectSupport( renderer );

Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_morphtargets_face.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,10 @@
container.appendChild( renderer.domElement );

const ktx2Loader = new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupport( renderer );

new GLTFLoader()
Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_morphtargets_webcam.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,10 @@
const eyeRotationLimit = THREE.MathUtils.degToRad( 30 );

const ktx2Loader = new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupport( renderer );

new GLTFLoader()
Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_texture2darray_compressed.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,10 @@
//

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} );
ktx2Loader.detectSupport( renderer );

ktx2Loader.load( 'textures/spiritedaway.ktx2', function ( texturearray ) {
Expand Down
5 changes: 4 additions & 1 deletion examples/webgl_texture2darray_layerupdate.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,10 @@
// Configure the KTX2 loader.

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} );
ktx2Loader.detectSupport( renderer );

// Load several KTX2 textures which will later be used to modify
Expand Down
5 changes: 4 additions & 1 deletion examples/webgpu_loader_gltf_compressed.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,10 @@
controls.update();

const ktx2Loader = await new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupportAsync( renderer );

const loader = new GLTFLoader();
Expand Down
5 changes: 4 additions & 1 deletion examples/webgpu_morphtargets_face.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,10 @@
scene.environment = pmremGenerator.fromScene( environment ).texture;

const ktx2Loader = await new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupportAsync( renderer );

new GLTFLoader()
Expand Down
5 changes: 4 additions & 1 deletion examples/webgpu_sandbox.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,10 @@
textureDisplace.wrapT = THREE.RepeatWrapping;

const ktxLoader = await new KTX2Loader()
.setTranscoderPath( 'jsm/libs/basis/' )
.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} )
.detectSupportAsync( renderer );

const ktxTexture = await ktxLoader.loadAsync( './textures/ktx2/2d_uastc.ktx2' );
Expand Down
5 changes: 4 additions & 1 deletion examples/webgpu_textures_2d-array_compressed.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,10 @@
//

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( 'jsm/libs/basis/' );
ktx2Loader.setTranscoderPath( {
js: 'jsm/libs/basis/basis_transcoder.js',
wasm: 'jsm/libs/basis/basis_transcoder.wasm'
} );
await ktx2Loader.detectSupportAsync( renderer );

ktx2Loader.load( 'textures/spiritedaway.ktx2', function ( texturearray ) {
Expand Down