Skip to content

Add KTX2 docs #21169

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

Merged
merged 1 commit into from
Jan 29, 2021
Merged

Add KTX2 docs #21169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 5 additions & 0 deletions docs/examples/en/loaders/GLTFLoader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,11 @@ <h3>[method:null setDDSLoader]( [param:DDSLoader ddsLoader] )</h3>
[page:DDSLoader ddsLoader] — Instance of THREE.DDSLoader, to be used for loading compressed textures with the MSFT_TEXTURE_DDS extension.
</p>

<h3>[method:null setKTX2Loader]( [param:KTX2Loader ktx2Loader] )</h3>
<p>
[page:KTX2Loader ktx2Loader] — Instance of THREE.KTX2Loader, to be used for loading KTX2 compressed textures.
</p>

<h3>[method:null parse]( [param:ArrayBuffer data], [param:String path], [param:Function onLoad], [param:Function onError] )</h3>
<p>
[page:ArrayBuffer data] — glTF asset to parse, as an ArrayBuffer or <em>JSON</em> string.<br />
Expand Down
133 changes: 133 additions & 0 deletions docs/examples/en/loaders/KTX2Loader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<base href="../../../" />
<script src="page.js"></script>
<link type="text/css" rel="stylesheet" href="page.css" />
</head>
<body>
[page:Loader] &rarr;

<h1>[name]</h1>

<p class="desc">
Loader for KTX 2.0 GPU Texture containers.<br><br>

[link:http://github.khronos.org/KTX-Specification/ KTX 2.0] is a container format for various GPU texture formats. The loader
supports Basis Universal GPU textures, which can be quickly transcoded to
a wide variety of GPU texture compression formats. While KTX 2.0 also allows
other hardware-specific formats, this loader does not yet parse them.
</p>

<p>
This loader parses the KTX 2.0 container and then relies on
[page:BasisTextureLoader] to complete the transcoding process.
The required WASM transcoder and JS wrapper are available from the
[link:https://github.com/mrdoob/three.js/tree/dev/examples/js/libs/basis examples/js/libs/basis]
directory.
</p>

<h2>Code Example</h2>

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

var material = new THREE.MeshStandardMaterial( { map: texture } );

}, function () {

console.log( 'onProgress' );

}, function ( e ) {

console.error( e );

} );
</code>

<h2>Examples</h2>

<p>
[example:webgl_loader_texture_ktx2]
</p>

<h2>Browser compatibility</h2>

<p>
See notes for [page:BasisTextureLoader]. This loader relies on ES6 Promises and Web Assembly, which are not
supported in IE11.
</p>

<br>
<hr>

<h2>Constructor</h2>

<h3>[name]( [param:LoadingManager manager] )</h3>
<p>
[page:LoadingManager manager] — The [page:LoadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
</p>
<p>
Creates a new [name].
</p>

<h2>Properties</h2>
<p>See the base [page:Loader] class for common properties.</p>

<h2>Methods</h2>
<p>See the base [page:Loader] class for common methods.</p>

<h3>[method:null load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
<p>
[page:String url] — A string containing the path/URL of the <em>.basis</em> file.<br />
[page:Function onLoad] — A function to be called after the loading is successfully completed.<br />
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes.<br />
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
</p>
<p>
Load from url and call the <em>onLoad</em> function with the transcoded [page:CompressedTexture].
</p>

<h3>[method:this detectSupport]( [param:WebGLRenderer renderer] )</h3>
<p>
[page:WebGLRenderer renderer] — A renderer instance.
</p>
<p>
Detects hardware support for available compressed texture formats, to determine
the output format for the transcoder. Must be called before loading a texture.
</p>

<h3>[method:this setTranscoderPath]( [param:String path] )</h3>
<p>
[page:String path] — Path to folder containing the WASM transcoder and JS wrapper.
</p>
<p>
The WASM transcoder and JS wrapper are available from the
[link:https://github.com/mrdoob/three.js/tree/dev/examples/js/libs/basis examples/js/libs/basis]
directory.
</p>

<h3>[method:this setWorkerLimit]( [param:Number limit] )</h3>
<p>
[page:Number limit] — Maximum number of workers. Default is '4'.
</p>
<p>
Sets the maximum number of web workers to be allocated by this instance.
</p>

<h3>[method:this dispose]()</h3>
<p>
Disposes the loader object, de-allocating any Web Workers created.
</p>

<h2>Source</h2>

<p>
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/KTX2Loader.js examples/jsm/loaders/KTX2Loader.js]
</p>
</body>
</html>
1 change: 1 addition & 0 deletions docs/list.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,7 @@
"BasisTextureLoader": "examples/en/loaders/BasisTextureLoader",
"DRACOLoader": "examples/en/loaders/DRACOLoader",
"GLTFLoader": "examples/en/loaders/GLTFLoader",
"KTX2Loader": "examples/en/loaders/KTX2Loader",
"MMDLoader": "examples/en/loaders/MMDLoader",
"MTLLoader": "examples/en/loaders/MTLLoader",
"OBJLoader": "examples/en/loaders/OBJLoader",
Expand Down
30 changes: 7 additions & 23 deletions examples/js/libs/basis/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,23 @@ a wide variety of GPU texture compression formats.
## Transcoders

Basis Universal texture data may be used in two different file formats:
`.basis` and `.ktx2`. Texture data is identical in both cases, but different
transcoders are required to read the two file types. Both transcoders are
available in this folder now, but they may be merged in the future.
`.basis` and `.ktx2`, where `ktx2` is a standardized wrapper around basis texture data.

For further documentation about the Basis compressor and transcoder, refer to
the [Basis GitHub repository](https://github.com/BinomialLLC/basis_universal).

### .basis

The folder contains two files required for transcoding `.basis` textures:
The folder contains two files required for transcoding `.basis` or `.ktx2` textures:

* `basis_transcoder.js` — JavaScript wrapper for the WebAssembly transcoder.
* `basis_transcoder.wasm` — WebAssembly transcoder.

Both are dependencies of `THREE.BasisTextureLoader`:
Both are dependencies of `THREE.KTX2Loader` and `THREE.BasisTextureLoader`:

```js
var basisLoader = new THREE.BasisTextureLoader();
basisLoader.setTranscoderPath( 'examples/js/libs/basis/' );
basisLoader.detectSupport( renderer );
basisLoader.load( 'diffuse.basis', function ( texture ) {
var ktx2Loader = new THREE.KTX2Loader();
ktx2Loader.setTranscoderPath( 'examples/js/libs/basis/' );
ktx2Loader.detectSupport( renderer );
ktx2Loader.load( 'diffuse.ktx2', function ( texture ) {

var material = new THREE.MeshStandardMaterial( { map: texture } );

Expand All @@ -45,18 +41,6 @@ basisLoader.load( 'diffuse.basis', function ( texture ) {
} );
```

### .ktx2

The folder contains two files required for transcoding `.ktx2` textures:

* `msc_basis_transcoder.js` — JavaScript wrapper for the WebAssembly transcoder.
* `msc_basis_transcoder.wasm` — WebAssembly transcoder.

Currently, the `msc_basis_transcoder.js` file must be added to the page as a
global script. The WASM transcoder will be downloaded from the same directory
automatically. These will likely be replaced with ES modules, and merged with
the `.basis` transcoder, in the future. See `KTX2Loader` for usage.

## License

[Apache License 2.0](https://github.com/BinomialLLC/basis_universal/blob/master/LICENSE)
4 changes: 3 additions & 1 deletion examples/jsm/loaders/KTX2Loader.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ export class KTX2Loader extends CompressedTextureLoader {

constructor( manager?: LoadingManager );

setTranscoderPath( path: string ): KTX2Loader;
setWorkerLimit( limit: number ): KTX2Loader;
detectSupport( renderer: WebGLRenderer ): KTX2Loader;
initModule(): void;
dispose(): KTX2Loader;

parse(
buffer: ArrayBuffer,
Expand Down