User Manual

Texture Compression

Texture data is stored in a device's video memory (or VRAM). It is important to ensure that your application does not exhaust VRAM as this can cause undesirable things like browser tab crashes.

The Editor has the ability to apply lossy compression schemes to your textures to dramatically reduce the amount of VRAM used using Basis.

Basis is a 'super-compressed' texture format. It's a platform independent lossy block compression format that can be transcoded to the natively supported hardware compression format at runtime.

Consider this texture asset:

Brick Texture

It's a 512x512 JPG that is 202KB in size. However, JPG is a compressed format and when passed to the graphics engine, it is expanded to an uncompressed RGB8 format that occupies 1.05MB of VRAM (including mipmap levels).

Enabling texture compression achieves the following results:

Basis Compression results

The compression has achieved a 6 times reduction in VRAM usage. Furthermore, in this case, compression has also reduced download size from 202KB to as little as 46KB using the Default quality setting and ETC Mode.

Below is a side by side comparison of the brick texture on Mac with Chrome:

Brick texture compression comparison

Here is another example of the PlayCanvas cube with Basis (ETC mode) and without on Mac with Chrome:

PlayCanvas cube compression comparison

Using Basis Texture Compression

Note: There is a limitation on the dimensions of the texture that can be compressed. The maximum size supported is 4096x4096

Once the texture has been imported into the Editor, select it and scroll down in the inspector to find the Compression section.

  1. Tick BASIS.
  2. Click on Import Basis to add the WASM module for the Basis runtime to the project (this only needs to be done once).
  3. Change mode from 'ETC (smaller size, lower quality)' to 'ASTC (larger size, higher quality)' if you need to reduce compression artifacts on this texture.
  4. Tick Normals if compressing a normal map.
  5. Change the quality setting to balance file size vs quality. Lower quality results in smaller file sizes.
  6. Click on Compress Basis.
Enabling Basis Texture Compression

The Basis WASM module will add 253KB of extra gzipped data to the preload download size but that should be offset by the texture size savings compared to using the legacy texture compression format files (see below).

To remove Basis compression from a texture:

  1. Untick BASIS.
  2. Click on Compress Basis.
Disabling Basis Texture Compression

If you would no longer want to use Basis, remove Basis compression from all textures and delete the Basis folder from the project.

Delete Basis Module

Legacy Texture Compression

We strongly recommend using Basis compression where possible as it requires a single texture file to cover all platforms and it is also a much smaller file compared to the legacy formats. Our tests show Basis to be ~50% smaller with minimal difference in quality.

The Legacy Texture schemes are:

To use the Legacy Texture Compression options, select the texture and scroll down in the inspector to find the Compression section.

  1. Tick LEGACY.
  2. Tick all the formats you wish to use.
  3. Click on Compress Legacy.
Enabling Legacy Texture Compression

To remove a or several formats:

  1. Untick all the formats you wish to remove.
  2. Click on Compress Legacy.
Disabling Legacy Texture Compression

Migrating from Legacy to Basis Texture Compression

If you have a project that is already using the Legacy Texture Compression formats and wish to use Basis, do the following:

  1. Remove all the legacy texture formats.
  2. Enable and use Basis.
Migrate from Legacy to Basis