KHR_texture_basisu enables KTX2 GPU textures with Basis Universal supercompression for any material texture.

GPU texture formats, unlike traditional image formats, remain compressed in GPU memory. As a result, they (1) upload to the GPU much more quickly, and (2) require much less GPU memory. In certain cases they may also have smaller filesizes than PNG or JPEG textures, but this is not guaranteed. GPU textures often require more careful tuning during compression to maintain image quality, but this extra effort is worthwhile for applications that need to maintain a smooth framerate while uploading images, or where GPU memory is limited.

Defining no ExtensionProperty types, this Extension is simply attached to the Document, and affects the entire Document by allowing use of the image/ktx2 MIME type and passing KTX2 image data to the Texture.setImage method. Without the Extension, the same MIME types and image data would yield an invalid glTF document, under the stricter core glTF specification.

Properties:

  • N/A

Example

import { TextureBasisu } from '@gltf-transform/extensions';

// Create an Extension attached to the Document.
const basisuExtension = document.createExtension(TextureBasisu)
    .setRequired(true);
document.createTexture('MyCompressedTexture')
    .setMimeType('image/ktx2')
    .setImage(fs.readFileSync('my-texture.ktx2'));

Compression is not done automatically when adding the extension as shown above — you must compress the image data first, then pass the .ktx2 payload to Texture.setImage. The glTF-Transform CLI has functions to help with this, or any similar KTX2-capable utility will work.

When the KHR_texture_basisu extension is added to a file by glTF-Transform, the extension should always be required. This tool does not support writing assets that "fall back" to optional PNG or JPEG image data.

_NOTICE: Compressing some textures — particularly 3-component (RGB) normal maps, and occlusion/roughness/metalness maps, may give poor results with the ETC1S compression option. These issues can often be avoided with the larger UASTC compression option, or by upscaling the texture before compressing it.

For best results when authoring new textures, use texture dilation and minimize prominent UV seams._

Hierarchy

  • Extension
    • TextureBasisu

Properties

extensionName: "KHR_texture_basisu" = ...
prereadTypes: PropertyType[] = ...
prewriteTypes: PropertyType[]

Before writing, extension should be called for these Property types. Most extensions don't need to implement this.

readDependencies: string[]

Dependency IDs needed by this extension, to be installed before I/O.

Methods

  • dispose(): void
  • Disables and removes the extension from the Document.

  • Installs dependencies required by the extension.

  • isRequired(): boolean
  • Indicates to the client whether it is OK to load the asset when this extension is not recognized. Optional extensions are generally preferred, if there is not a good reason to require a client to completely fail when an extension isn't known.

  • prewrite(_writerContext: WriterContext, _propertyType: PropertyType): TextureBasisu
  • Used by the PlatformIO utilities when writing a glTF asset. This method may optionally be implemented by an extension, and should then support any property type declared by the Extension's Extension.prewriteTypes list. The Extension will be given a WriterContext instance, and is expected to update either the context or its JSONDocument with resources known to the Extension. Most extensions don't need to implement this.

  • Indicates to the client whether it is OK to load the asset when this extension is not recognized. Optional extensions are generally preferred, if there is not a good reason to require a client to completely fail when an extension isn't known.

Function symbol, f(📦) → 📦, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy TypeDoc documentation Copyright 2020 under MIT license