mirror of
https://github.com/BinomialLLC/basis_universal.git
synced 2026-10-16 14:05:31 +00:00
Merge remote-tracking branch 'origin/master'
This commit is contained in:
Richard Geldreich
@@ -380,14 +380,14 @@ Use the `-no_ktx` and `-etc1_only`/`-format_only` options to unpack to less file
|
||||
|
||||
`-info` and `-validate` will just display file information and not output any files.
|
||||
|
||||
The written mipmapped, cubemap, or texture array .KTX/.DDS files will be in a wide variety of compressed GPU texture formats (PVRTC1 4bpp, ETC1-2, BC1-5, BC7, etc.), and to our knowledge there is unfortunately (as of 2024) still no single .KTX or .DDS viewer tool that correctly and reliably supports every GPU texture format that we support. BC1-5 and BC7 files are viewable using AMD's Compressonator, ETC1/2 using Mali's Texture Compression Tool, and PVRTC1 using Imagination Tech's PVRTexTool. [RenderDoc](https://renderdoc.org/) has a useful texture file viewer for many formats. The macOS Finder supports previewing .EXR and .KTX files in various GPU formats. The Windows 11 Explorer can preview .DDS files. The [online OpenHDR Viewer](https://viewer.openhdr.org/) is useful for viewing .EXR/.HDR image files.
|
||||
The written mipmapped, cubemap, or texture array .KTX/.DDS files will be in a wide variety of compressed GPU texture formats (PVRTC1 4bpp, ETC1-2, BC1-5, BC7, etc.), and to our knowledge there is unfortunately (as of 2024) still no single .KTX or .DDS viewer tool that correctly and reliably supports every GPU texture format that we support. BC1-5 and BC7 files are viewable using AMD's Compressonator, ETC1/2 using Mali's Texture Compression Tool, and PVRTC1 using Imagination Tech's PVRTexTool. [RenderDoc](https://renderdoc.org/) has a useful texture file viewer for many formats. The macOS *Finder* app supports previewing .EXR, .ASTC and .KTX files in various GPU formats, including ASTC LDR/ HDR. The Windows 11 Explorer can preview .DDS files. The [online OpenHDR Viewer](https://viewer.openhdr.org/) is useful for viewing .EXR/.HDR image files.
|
||||
|
||||
----
|
||||
|
||||
Pixel Shader Deblocking Sample: CPU + GPU Deblocking Everywhere
|
||||
---------------------------------------------------------------
|
||||
|
||||
The [shader_deblocking sample](https://github.com/BinomialLLC/basis_universal/blob/master/shader_deblocking/README.md) in the repo demonstrates how to use a simple pixel shader to deblock sampled textures of any block size between 4x4-12x12, greatly reducing block artifacts. The sample shader is compatible with mipmapping and bilinear or trilinear filtering. Ultimately, shader deblocking enables the usage of larger ASTC block sizes, reducing bitrate and increasing transcoding speeds. Deblocking is a standard feature of modern image and video codecs, and there's no reason why it can't be used while sampling (or transcoding) GPU textures.
|
||||
The [shader_deblocking sample](https://github.com/BinomialLLC/basis_universal/blob/master/shader_deblocking/README.md) in the repo demonstrates how to use a simple pixel shader to deblock sampled textures of any block size between 4x4-12x12, greatly reducing block artifacts. The sample shader is compatible with mipmapping and bilinear or trilinear filtering. Ultimately, shader deblocking enables the usage of larger ASTC block sizes, reducing bitrate and increasing transcoding speeds. Deblocking is a standard feature of modern image and video codecs, and there's no reason why it can't be used while sampling (or transcoding) GPU textures. Using larger ASTC block sizes can significantly reduce GPU memory bandwidth. If bandwidth is the bottleneck — as it often is — the modest ALU and texture sampling cost of deblocking can be effectively free.
|
||||
|
||||
XUASTC LDR's transcoder supports adaptive deblocking when transcoding to other (non-ASTC) formats like BC7, and GPU shader deblocking can be used for ASTC, resulting in a complete deblocking system for ASTC.
|
||||
|
||||
@@ -511,14 +511,15 @@ checking tool (https://reuse.software/). See the [.reuse](https://github.com/Bin
|
||||
External Tool Links
|
||||
-------------------
|
||||
|
||||
- [ARM's astcenc](https://github.com/ARM-software/astc-encoder) - Crucial official tool from ARM which can unpack ASTC format LDR/HDR .astc and .ktx files to .png or .exr for testing and verification purposes.
|
||||
- [Online .EXR and .HDR Image File Viewer](https://viewer.openhdr.org/) - With strong tone mapping, auto-exposure, HDR histogram.
|
||||
- [Windows HDR + WCG Image Viewer](https://13thsymphony.github.io/hdrimageviewer/) - A true HDR image viewer for Windows which works on HDR monitors. Also see [the github repo](https://github.com/13thsymphony/HDRImageViewer).
|
||||
- [KTX-Software](https://github.com/KhronosGroup/KTX-Software) - A suite of tools for examining, compressing and unpacking KTX2 files (including in our various codec formats) from the Khronos Group.
|
||||
- [AMD Compressonator](https://gpuopen.com/compressonator/) - .DDS viewer, can view .KTX files in some formats.
|
||||
- [PVRTexTool](https://www.imgtec.com/developers/powervr-sdk-tools/pvrtextool/) - Can view .ASTC and .KTX files in some formats. (Note: .DDS viewer seems busted for BC1, doesn't support BC7 at all.)
|
||||
- [Microsoft's DirectXTex](https://github.com/microsoft/DirectXTex) - Samples contain a basic .DDS viewer. (Note: May still have issues loading .DDS files with texture dimensions that aren't divisible by 4 texels.)
|
||||
- [RenderDoc](https://renderdoc.org/) - Reliable viewer for LDR/HDR .DDS files in BC1-7 formats.
|
||||
- [Mali Texture Compression Tool](https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum/52390/announcement-mali-texture-compression-tool-end-of-life) - Now deprecated.
|
||||
- [ARM's astcenc](https://github.com/ARM-software/astc-encoder) - Can unpack ASTC format LDR/HDR .astc and .ktx files to .png etc. for testing.
|
||||
|
||||
For more useful links, papers, and tools/libraries, see the end of the [UASTC HDR 4x4 texture specification](https://github.com/BinomialLLC/basis_universal/wiki/UASTC-HDR-4x4-Texture-Specification-v1.1#papersfurther-reading).
|
||||
|
||||
|
||||
@@ -32,13 +32,15 @@ pip install numpy Pillow glfw PyOpenGL
|
||||
|
||||
You may also want "PyOpenGL_accelerate", and under Linux you may need to also install the system package "libglfw3". We developed this sample under Windows 11.
|
||||
|
||||
See `run.bat` for the command line on how to run the sample. Or run:
|
||||
Run:
|
||||
|
||||
```
|
||||
py -3.12 testbed.py shader.glsl 12 12 flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_0_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_1_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_2_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_3_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_4_face_0_layer_0000.png
|
||||
python testbed.py shader.glsl 12 12 flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_0_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_1_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_2_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_3_face_0_layer_0000.png flower_unpacked_rgb_ASTC_LDR_12X12_RGBA_level_4_face_0_layer_0000.png
|
||||
```
|
||||
|
||||
Depending on your setup you may need to use 'python' or 'python3' etc.
|
||||
Depending on your setup you may need to use `python3`, or `py -3.12` etc.
|
||||
|
||||
Keys: `1` toggles deblocking shader on/off (it defaults to disabled), `2` toggles edges vis (only shows when deblocking is enabled), arrow keys move the object, `W`/`S` keys: forward/backward, `A`/`D`/`Q`/`E`: yaw/pitch, `C`: toggle cube vs. quad. (See the source code remarks for more.)
|
||||
|
||||
The shader can be easily simplified to sample the texture less by using less taps. The current shader uses a total of 9 taps, but 5 are possible.
|
||||
|
||||
@@ -46,6 +48,14 @@ Many variations and optimizations of this basic idea are possible. *Now shader e
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
|
||||
The deblocking shader itself can be put inside a dynamic `if` conditional, so the extra ALU/texture ops only kick in near block edges (which are the minority of samples at ASTC 12x12). The extra sample taps are spatially always near the center sample, so they'll hit the texture cache most of the time. In texture bandwidth bound rendering scenarios (quite common on mobile platforms), the extra ALU ops for deblocking likely come for "free".
|
||||
|
||||
*Another perspective: The alternative to not deblocking is ~2x-8x more GPU memory bandwidth (and increased download size) to use smaller ASTC block sizes which have less noticeable block artifacts.*
|
||||
|
||||
---
|
||||
|
||||
## Screenshots - ASTC 12x12 Block Size
|
||||
|
||||
**Disabled:**
|
||||
|
||||
@@ -1,10 +1,42 @@
|
||||
# Table of Contents
|
||||
- [WebGL Examples](#webgl-examples)
|
||||
- [KTX2 Compression, Transcoding, Display (ktx2_encode_test)](#ktx2-compression-transcoding-display-ktx2_encode_test)
|
||||
- [Texture Video Sample (video-test)](#texture-video-sample-video_test)
|
||||
- [Simple Transcoding (texture_test)](#simple-transcoding-texture_test)
|
||||
- [glTF 3D Model](#gltf-3d-model)
|
||||
- [Tesing and developing locally](#testing-and-developing-locally)
|
||||
|
||||
# WebGL Examples
|
||||
|
||||
Requires WebAssembly and WebGL support. The WebGL demos are hosted live [here](https://subquantumtech.com/bu_6x6/).
|
||||
Requires WebAssembly and WebGL support. The WebGL demos are hosted live [here](https://subquantumtech.com/xu/).
|
||||
|
||||
To build the encoder and transcoder WASM libraries using Emscripten, see the various README.md files in the 'webgl/transcoder' and 'webgl/encoder' folders. The Javascript API wrappers to the C/C++ library are located in [`webgl/transcoder/basis_wrappers.cpp`](https://github.com/BinomialLLC/basis_universal/blob/master/webgl/transcoder/basis_wrappers.cpp).
|
||||
To build the encoder and transcoder WASM libraries using [Emscripten](https://emscripten.org/), see the README.md files in the [webgl/transcoder](https://github.com/BinomialLLC/basis_universal/tree/master/webgl/transcoder) and [webgl/encoder](https://github.com/BinomialLLC/basis_universal/tree/master/webgl/encoder) folders. The JavaScript API wrappers to the C/C++ library are located in [`webgl/transcoder/basis_wrappers.cpp`](https://github.com/BinomialLLC/basis_universal/blob/master/webgl/transcoder/basis_wrappers.cpp). The JavaScript API is a thin wrapper layered above our C++ API (however not our C API).
|
||||
|
||||
## Transcoder (texture_test)
|
||||
---
|
||||
|
||||
## KTX2 Compression, Transcoding, Display (ktx2_encode_test)
|
||||
|
||||
Live demo: [`ktx2_encode_test/index.html'](https://subquantumtech.com/xu/ktx2_encode_test/)
|
||||
|
||||
This demo shows how to use the compressor and transcoder from JavaScript. To use it, select a .PNG file then hit the "Encode!" button. The compressor will dynamically generate a .ktx2 file in memory which will then be immediately transcoded and rendered as a quad with a WebGL pixel shader used to sample the texture using the GPU. Hit the "Download!" button to locally download the generated .ktx2 file. This sample allows the user to toggle on/off all GPU formats the local device supports and see the results in real-time.
|
||||
|
||||
This sample's UI exposes a large fraction of the C++ compression and transcoding API to the user. It runs on desktop and mobile browsers (but note the UI on mobile isn't great).
|
||||
|
||||
To view the compressor's textual debug output, open your browser's developer debug console (under Developer Tools in Chrome) and enable the Debug checkbox before hitting the "Encode!" button. WASM multithreading and WASM64 are optionally supported, and a browser supporting both are recommended.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Texture Video Sample (video_test)
|
||||
|
||||
See [this wiki page](https://github.com/BinomialLLC/basis_universal/wiki/Encoding-ETC1S-and-XUASTC-LDR-Texture-Video).
|
||||
|
||||
<img width="1185" height="610" alt="image" src="https://github.com/user-attachments/assets/1da64bbe-f74f-4650-8a35-729e2fe74f7c" />
|
||||
|
||||
---
|
||||
|
||||
## Simple Transcoding (texture_test)
|
||||
|
||||
Live demo: [webgl/texture_test/index.html](https://subquantumtech.com/xu/texture_test/)
|
||||
|
||||
@@ -17,10 +49,12 @@ Renders a single texture, using the transcoder (compiled to WASM with emscripten
|
||||
* PVRTC 4bpp
|
||||
* BC6H, BC7
|
||||
|
||||
On browsers that don't support any compressed texture format, there's a low-quality fallback code path for opaque LDR textures, and a HDR half float or LDR 32bpp fallback code path for HDR textures.
|
||||
On browsers that don't support any compressed texture formats, there's a low-quality fallback code path for opaque LDR textures, and a HDR half float or LDR 32bpp fallback code path for HDR textures.
|
||||
|
||||
|
||||
|
||||
*Note: This sample doesn't support all ASTC/XUASTC LDR block sizes yet, just 4x4. See the "ktx2_encode_test" or "video_test" samples, which do.*
|
||||
|
||||
## glTF 3D Model
|
||||
|
||||
Live demo: [`gltf/index.html`](https://subquantumtech.com/xu/gltf/)
|
||||
@@ -41,17 +75,7 @@ extension that is [currently in development](https://github.com/KhronosGroup/glT
|
||||
|
||||
|
||||
|
||||
## Compressor (ktx2_encode_test)
|
||||
|
||||
Live demo: [`ktx2_encode_test/index.html'](https://subquantumtech.com/xu/ktx2_encode_test/)
|
||||
|
||||
This demo shows how to use the compressor from JavaScript. To use it, select a .PNG file then hit the "Encode!" button. The compressor will dynamically generate a .ktx2 file in memory which will then be immediately transcoded and displayed. Hit the "Download!" button to locally download the generated .ktx2 file.
|
||||
|
||||
To view the compressor's textual debug output, open your browser's developer debug console (under Developer Tools in Chrome) and enable the Debug checkbox before hitting the "Encode!" button. Multithreading is not currently supported when the compressor is compiled to WebAssembly, so compression will be slower than using the stand-alone command line tool.
|
||||
|
||||
|
||||
|
||||
## Testing locally
|
||||
## Testing and developing locally
|
||||
|
||||
You can locally host the files under the "webgl" folder. One way is to use [Python to setup a local webserver](https://pythonbasics.org/webserver/) in the 'webgl' directory:
|
||||
|
||||
@@ -60,4 +84,4 @@ cd webgl
|
||||
python3 -m http.server 8000
|
||||
```
|
||||
|
||||
Note: For WASM multithreading to be available and enabled, the server [must be properly configured](https://unlimited3d.wordpress.com/2021/12/21/webassembly-and-multi-threading/). See the `webgl/start_webserver.sh` and `webgl/webserver_cross_origin.py` example scripts.
|
||||
**Note: For WASM multithreading to be available and enabled (which is highly recommended for reasonable compression times), the server [must be properly configured](https://unlimited3d.wordpress.com/2021/12/21/webassembly-and-multi-threading/). See the `webgl/start_webserver.sh` and `webgl/webserver_cross_origin.py` example scripts.**
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
`basisu_wrappers.cpp` contains our JavaScript API (implemented via [emscripten](https://emscripten.org/) bindings), which is a thin layer above our encoder and transcoder's C++ API's. As of Basis Universal v2.0 it supports optional WASM multithreading and WASM64.
|
||||
|
||||
Prebuilt versions of `basis_transcoder.js` and `basis_transcoder.wasm` are included in the `build/` folder, and are sufficient for local demos. To build the transcoder yourself, first install emscripten ([tutorial](https://webassembly.org/getting-started/developers-guide/)) and cmake ([download](https://cmake.org/download/)). Then run:
|
||||
|
||||
```shell
|
||||
|
||||
Reference in New Issue
Block a user