Add ktx
This commit is contained in:
+165
@@ -0,0 +1,165 @@
|
||||
<!-- Copyright 2013-2020 Mark Callow -->
|
||||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
|
||||
<img src="https://www.khronos.org/assets/images/api_logos/khronos.svg" width="300"/>
|
||||
|
||||
## The Official Khronos KTX Software Repository
|
||||
|
||||
|
||||
| GNU/Linux | iOS, macOS | Web / wasm | Windows | Android | Mingw |
|
||||
| :-------: | :--------: | :--------: | :-----: | :-----: | :---: |
|
||||
|  |  |  |  |  |  |
|
||||
|
||||
| Documentation | Check-reuse | Check-mkvk |
|
||||
| :-----------: | :---------: | :--------: |
|
||||
|  |  | 
|
||||
|
||||
This is the official home of the source code for the Khronos KTX library and tools.
|
||||
|
||||
KTX (Khronos Texture) is a lightweight container for textures for OpenGL<sup>®</sup>, Vulkan<sup>®</sup> and other GPU APIs. KTX files contain all the parameters needed for texture loading. A single file can contain anything from a simple base-level 2D texture through to a cubemap array texture with mipmaps. Contained textures can be in a Basis Universal format, in any of the block-compressed formats supported by OpenGL family and Vulkan APIs and extensions or in an uncompressed single-plane format. Basis Universal currently encompasses two formats that can be quickly transcoded to any GPU-supported format: LZ/ETC1S, which combines block-compression and supercompression, and UASTC, a block-compressed format. Formats other than LZ/ETC1S can be supercompressed with Zstd and ZLIB.
|
||||
|
||||
Download [KTX Software Releases](https://github.com/KhronosGroup/KTX-Software/releases)
|
||||
to get binary packages of the tools, library and development headers
|
||||
described below. The [Releases](https://github.com/KhronosGroup/KTX-Software/releases)
|
||||
page also has packages with the Javascript wrappers and .wasm binaries.
|
||||
|
||||
See the Doxygen generated [live documentation](https://github.khronos.org/KTX-Software/)
|
||||
for API and tool usage information.
|
||||
|
||||
The software consists of: (links are to source folders in the KhronosGroup repo)
|
||||
|
||||
- *libktx* - a small library of functions for writing and reading KTX
|
||||
files, and instantiating OpenGL®, OpenGL ES™️ and Vulkan® textures
|
||||
from them. [`lib`](https://github.com/KhronosGroup/KTX-Software/tree/main/lib)
|
||||
- *libktx.{js,wasm}* - Web assembly version of libktx and
|
||||
Javascript wrapper. [`interface/js_binding`](https://github.com/KhronosGroup/KTX-Software/tree/main/interface/js_binding)
|
||||
- *msc\_basis\_transcoder.{js,wasm}* - Web assembly transcoder and
|
||||
Javascript wrapper for Basis Universal formats. For use with KTX parsers written in Javascript. [`interface/js_binding`](https://github.com/KhronosGroup/KTX-Software/tree/main/interface/js_binding)
|
||||
- *libktx.jar, libktx-jni* - Java wrapper and native interface library.
|
||||
[`interface/java_binding`](https://github.com/KhronosGroup/KTX-Software/tree/main/interface/java_binding)
|
||||
- *ktx* - a generic command line tool for managing KTX2 files with subcommands.[`tools/ktx`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktx)
|
||||
- *ktx compare* - Compare two KTX2 files
|
||||
- *ktx create* - Create a KTX2 file from various input files
|
||||
- *ktx deflate* - Deflate a KTX2 file with zstd or ZLIB
|
||||
- *ktx extract* - Export selected images from a KTX2 file
|
||||
- *ktx encode* - Encode a KTX2 file
|
||||
- *ktx transcode* - Transcode a KTX2 file
|
||||
- *ktx info* - Prints information about a KTX2 file
|
||||
- *ktx validate* - Validate a KTX2 file
|
||||
- *ktx help* - Display help information about the ktx tools
|
||||
- *ktx2check* - a tool for validating KTX Version 2 format files. [`tools/ktx2check`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktx2check)
|
||||
- *ktx2ktx2* - a tool for converting a KTX Version 1 file to a KTX
|
||||
Version 2 file. [`tools/ktx2ktx2`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktx2ktx2)
|
||||
- *ktxinfo* - a tool to display information about a KTX file in
|
||||
human readable form. [`tools/ktxinfo`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktxinfo)
|
||||
- *ktxsc* - a tool to supercompress a KTX Version 2 file that
|
||||
contains uncompressed images.[`tools/ktxsc`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktxsc)
|
||||
- *pyktx* - Python wrapper
|
||||
- *toktx* - a tool to create KTX files from PNG, Netpbm or JPEG format images. It supports mipmap generation, encoding to
|
||||
Basis Universal formats and Zstd supercompression.[`tools/toktx`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/toktx)
|
||||
|
||||
See [CONTRIBUTING](CONTRIBUTING.md) for information about contributing.
|
||||
|
||||
See [LICENSE](LICENSE.md) for information about licensing.
|
||||
|
||||
See [BUILDING](BUILDING.md) for information about building the code.
|
||||
|
||||
<!--
|
||||
More information about KTX and links to tools that support it can be
|
||||
found on the
|
||||
[KTX page](http://www.khronos.org/opengles/sdk/tools/KTX/) of
|
||||
the [OpenGL ES SDK](http://www.khronos.org/opengles/sdk) on
|
||||
[khronos.org](http://www.khronos.org).
|
||||
-->
|
||||
|
||||
If you need help with using the KTX library or KTX tools, please use GitHub
|
||||
[Discussions](https://github.com/KhronosGroup/KTX-Software/discussions).
|
||||
To report problems use GitHub [issues](https://github.com/KhronosGroup/KTX/issues).
|
||||
|
||||
**IMPORTANT:** you **must** install the [Git LFS](https://github.com/github/git-lfs)
|
||||
command line extension in order to fully checkout this repository after cloning. You
|
||||
need at least version 1.1. If you did not have Git LFS installed at first checkout
|
||||
then, after installing it, you **must** run
|
||||
|
||||
```bash
|
||||
git lfs checkout
|
||||
```
|
||||
|
||||
### KTX-Software-CTS - Conformance Test Suite
|
||||
|
||||
The tests and test files for the generic command line `ktx` tool can be found in a separate
|
||||
[CTS Repository](https://github.com/KhronosGroup/KTX-Software-CTS/). To save space and bandwidth this repository
|
||||
is included with git submodule and by default it is not required for building the libraries or the tools.
|
||||
For more information about building, running and extending the CTS tests see [BUILDING](BUILDING.md#Conformance-Test-Suite)
|
||||
and [CTS README](https://github.com/KhronosGroup/KTX-Software-CTS/blob/main/README.md).
|
||||
|
||||
### <a id="kwexpansion"></a>$Date$ keyword expansion
|
||||
|
||||
A few files have `$Date$` keywords. If you care about having the proper
|
||||
dates shown or will be generating the documentation or preparing
|
||||
distribution archives, you **must** follow the instructions below.
|
||||
|
||||
$Date$ keywords are expanded via smudge & clean filters. To install
|
||||
the filters, issue the following commands in the root of your clone.
|
||||
|
||||
On Unix (Linux, Mac OS X, etc.) platforms and Windows using Git for
|
||||
Windows' Git Bash or Cygwin's bash terminal:
|
||||
|
||||
```bash
|
||||
./install-gitconfig.sh
|
||||
./scripts/smudge_date.sh
|
||||
|
||||
```
|
||||
|
||||
On Windows PowerShell (requires `git.exe` in a directory
|
||||
on your %PATH%):
|
||||
|
||||
```ps1
|
||||
install-gitconfig.ps1
|
||||
./scripts/smudge_date.ps1
|
||||
```
|
||||
|
||||
The first command adds an [include] of the repo's `.gitconfig` to the
|
||||
local git config file `.git/config`, i.e. the one in your clone of the repo.
|
||||
`.gitconfig` contains the config of the "keyworder" filter. The script in
|
||||
the second command forces a new checkout of the affected files to smudge them
|
||||
with their last modified date. This is unnecessary if you plan to edit
|
||||
these files.
|
||||
|
||||
### Useful Tools
|
||||
|
||||
#### scripts/gk
|
||||
|
||||
For finding strings within the KTX-Software source. Type `scripts/gk -h` for help. `gk` avoids looking in any build directories, `.git`, `external` or `tests/cts`.
|
||||
|
||||
#### scripts/ktx-compare-git
|
||||
|
||||
Wrapper that allows use of `ktx compare` when using `git diff` on KTX2 files.
|
||||
Together with this, `.gitconfig` now includes a *ktx-compare* diff command.
|
||||
Those wishing to use this must run, or have run, install-gitconfig.{ps1,sh}
|
||||
as described above for keyword expansion so that `.gitconfig` is
|
||||
included by your local `.git/config`.
|
||||
|
||||
You need to have the `ktx` command installed in a directory on your $PATH.
|
||||
|
||||
You need to add the line
|
||||
|
||||
```
|
||||
*.ktx2 binary diff=ktx-compare
|
||||
```
|
||||
|
||||
to your repo clone's `.git/info/attributes`. This is not included in the repo's
|
||||
`.gitattributes` because not everyone will have the `ktx` command installed nor have `.gitconfig` included by `.git/config`.
|
||||
|
||||
*NOTE:* This line in a user-global or system-global Git attributes file will not
|
||||
work because those are lower priority than `.gitattributes` so are read first
|
||||
and `.gitattributes` already has an entry for *.ktx2, indicating binary, which
|
||||
overrides anything from the global files.
|
||||
|
||||
To set up your `tests/cts` submodule to use this, copy the *ktx-compare* diff
|
||||
command to `.git/modules/tests/cts/config`. Depending on when you set up the
|
||||
submodule and when you ran `install-gitconfig.sh`, it may already be there.
|
||||
Add the attribute line to `.git/modules/tests/cts/info/attributes`.
|
||||
|
||||
We will be happy to accept a PR to add a .ps1 equivalent script.
|
||||
|
||||
Reference in New Issue
Block a user