# KTX/Basis Texture Unity Package

[![openupm](https://camo.githubusercontent.com/f66b8558ce3ec3b15a524f6b714c99ec1384505e09cc58a70f58bd41f53afa0c/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e617474656e656465722e6b74783f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.atteneder.ktx/) [![GitHub issues](https://camo.githubusercontent.com/3c14b8ab65dd2e6d515592eca0ae2ffbb4760201ac98d5c34ec66bcb7880c7c0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f617474656e656465722f4b7478556e697479)](https://github.com/atteneder/KtxUnity/issues) [![GitHub license](https://camo.githubusercontent.com/32dd0bf1d41768f1b458885120f4cd333541adb55f8e6410798275de3cdc02d0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f617474656e656465722f4b7478556e697479)](https://github.com/atteneder/KtxUnity/blob/main/LICENSE.md) Unity package that allows users to load [KTX 2.0][ktx] or [Basis Universal][basisu] texture files. ## Features - [KTX 2.0][ktx] files (.ktx2) - [Basis Universal][basisu] files (.basis) - ETC1s and UASTC mode for Basis Universal super compression - Arbitrary Texture orientation can be considered Following build targets are supported - WebGL - iOS (arm64 and armv7a) - Android (arm64 and armv7a) - Windows (64 bit) - Universal Windows Platform (x64,x86,ARM,ARM64) - macOS Universal (Apple Silicon and Intel) - Linux (64 bit) - Lumin / Magic Leap ![Screenshot of loaded fish textures](https://raw.githubusercontent.com/atteneder/KtxUnityDemo/main/Images/fishes.png "Lots of fish basis universal textures loaded via BasisUniversalUnity") Thanks to [Khronos][khronos], [Binomial][binomial] and everyone involved in making KTX and Basis Universal available! ## Installing The easiest way to install is to download and open the [Installer Package](https://package-installer.glitch.me/v1/installer/OpenUPM/com.atteneder.ktx?registry=https%3A%2F%2Fpackage.openupm.com&scope=com.atteneder) It runs a script that installs KtxUnity via a [scoped registry][scoped]. After that it is listed in the *Package Manager* and can be updated from there.

Alternative / Legacy installations (for Unity 2018.4 and older)

Install manually via package URL You have to manually add the package's URL into your [project manifest](https://docs.unity3d.com/Manual/upm-manifestPrj.html) Inside your Unity project there's the folder `Packages` containing a file called `manifest.json`. You have to open it and add the following line inside the `dependencies` category: ```json "com.atteneder.ktx": "https://gitlab.com/atteneder/ktxunity.git", ``` It should look something like this: ```json { "dependencies": { "com.atteneder.ktx": "https://gitlab.com/atteneder/ktxunity.git", "com.unity.modules.unitywebrequest": "1.0.0" ... } } ``` Next time you open your project in Unity, it will download the package automatically. You have to have a GIT LFS client (large file support) installed on your system. Otherwise you will get an error that the native library file (dll on Windows) is corrupt. There's more detail about how to add packages via GIT URLs in the [Unity documentation](https://docs.unity3d.com/Manual/upm-git.html).

## Using The API provides the loading classes `KtxTexture` for KTX 2.0 files and `BasisUniversalTexture` for Basis files, which both offer the following async loading methods: - `LoadFromUrl` for loading URLs (including file URLs starting with `file://`) - `LoadFromStreamingAssets` for loading relative paths in the StreamingAssets folder - `LoadFromBytes` for loading from memory See [TextureBase](https://github.com/atteneder/KtxUnity/raw/main/Runtime/Scripts/TextureBase.cs) for complete signature. > Take a look at the demo project [KtxUnityDemo](https://github.com/atteneder/KtxUnityDemo) for extensive usage examples. ### Loading Textures Excerpt from [KtxUnityDemo](https://github.com/atteneder/KtxUnityDemo/raw/main/Assets/Scripts/LoadKtxFileDemo.cs) how to load a file (for example from StreamingAssets): ```C# … async void Start() { // Create KTX texture instance var texture = new KtxTexture(); // Linear color sampling. Needed for non-color value textures (e.g. normal maps) bool linearColor = true; // Load file from Streaming Assets folder (relative path) var result = await texture.LoadFromStreamingAssets("trout.ktx",linearColor); // Alternative: Load from URL // var result = await texture.LoadFromUrl("https://myserver.com/trout.ktx", linearColor); // Alternative: Load from memory // var result = await texture.LoadFromBytes(nativeArray, linearColor); if (result != null) { // Use texture. For example, apply texture to a material targetMaterial.mainTexture = result.texture; // Optional: Support arbitrary texture orientation by flipping the texture if necessary var scale = targetMaterial.mainTextureScale; scale.x = result.orientation.IsXFlipped() ? -1 : 1; scale.y = result.orientation.IsYFlipped() ? -1 : 1; targetMaterial.mainTextureScale = scale; } } … ``` ### Using as Sprite If you want to use the texture in a UI / Sprite context, this is how you create a Sprite with correct orientation (excerpt from [BasisImageLoader](https://github.com/atteneder/KtxUnityDemo/raw/main/Assets/Scripts/LoadBasisFileSpriteDemo.cs)): ```C# … async void Start() { // Create a basis universal texture instance var texture = new BasisUniversalTexture(); // Load file from Streaming Assets folder var result = await texture.LoadFromStreamingAssets("dachstein.basis"); if (result != null) { // Calculate correct size var pos = new Vector2(0,0); var size = new Vector2(result.texture.width, result.texture.height); // Flip Sprite, if required if(result.orientation.IsXFlipped()) { pos.x = size.x; size.x *= -1; } if(result.orientation.IsYFlipped()) { pos.y = size.y; size.y *= -1; } // Create a Sprite and assign it to the Image GetComponent().sprite = Sprite.Create(result.texture, new Rect(pos, size), Vector2.zero); // Preserve aspect ratio: // Flipping the sprite by making the size x or y negative (above) breaks Image's `Preserve Aspect` feature // You can/have to calculate the RectTransform size yourself. Example: // Calculate correct size and assign it to the RectTransform const float scale = 0.5f; // Set this to whatever size you need it - best make it a serialized class field var rt = GetComponent(); rt.sizeDelta = new Vector2(result.texture.width*scale, result.texture.height*scale); } } … ``` > Note: You can still use the `Preserve Aspect` Image option, if you encode your KTX/Basis files with flipped Y axis (see [Creating Textures](https://github.com/atteneder/KtxUnity/raw/main/#creating-textures) ) ### Advanced Developers who want to create advanced loading code should look into classes `KtxTexture`/`BasisUniversalTexture` and `TextureBase` directly. When loading many textures at once, using the low-level API to get finer control over the loading process can yield great performance gains. Have a look at `TextureBase.Load` and for starting and details. ## Creating Textures You can use the command line tools `toktx` (comes with [KTX-Software][ktxsoftware]) to create KTX v2.0 files and `basisu` (part of [Basis Universal](https://github.com/BinomialLLC/basis_universal)) to create .basis files. The default texture orientation of both of those tools (right-down) does not match Unity's orientation (right-up). To counter-act, you can provide a parameter to flip textures in the vertical axis (Y). This is recommended, if you use the textures in Unity only. The parameters are: - `--lower_left_maps_to_s0t0` for `toktx` - `--y_flip` for `basisu` Example usage: ```bash # For KTX files: # Create regular KTX file from an input image toktx --bcmp regular.ktx2 input.png # Create a y-flipped KTX file, fit for Unity out of the box toktx --lower_left_maps_to_s0t0 --bcmp unity_flipped.ktx2 input.png # For Basis files: # Create regular basis file from an input image basisu -output_file regular.basis input.png # Create a y-flipped basis file, fit for Unity out of the box basisu -y_flip -output_file unity_flipped.basis input.png ``` If changing the orientation of your texture files is not an option, you can correct it by applying it flipped at run-time (see [Using](https://github.com/atteneder/KtxUnity/raw/main/#using)). ## Limitations At the moment known shortcomings: - KTX with non-supercompressed formats (like uncompressed, DXT, BC7, PVRTC, ETC, … ) are not tested or supported - Only 2D image texture types (no cube-map, videos, 3D texture, 2D arrays) - Only RGB/RGBA is tested (RG,R untested) ## Support Like this demo? You can show your appreciation and ... [![Buy me a coffee](https://camo.githubusercontent.com/edd140dc65659aca6ef68a871a01c0600e981380743f53e813025fe9756be5a2/68747470733a2f2f617a3734333730322e766f2e6d7365636e642e6e65742f63646e2f6b6f6669312e706e673f763d30)][kofi] ## Trademarks *Unity* is a registered trademark of [Unity Technologies][unity]. *Khronos®* is a registered trademark and *KTX™* is a trademark of [The Khronos Group Inc][khronos]. ## License Copyright (c) 2019 Andreas Atteneder, All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use files in this repository except in compliance with the License. You may obtain a copy of the License at Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. [basisu]: https://github.com/BinomialLLC/basis_universal [binomial]: http://www.binomial.info [khronos]: https://www.khronos.org [kofi]: https://ko-fi.com/C0C3BW7G [ktxsoftware]: https://github.com/KhronosGroup/KTX-Software [ktx]: http://github.khronos.org/KTX-Specification [scoped]: https://docs.unity3d.com/Manual/upm-scoped.html [unity]: https://unity.com