txtrtool

Decodes and encodes TXTR files from Metroid Prime 1, 2: Echoes, and 3: Corruption.

Table of Contents

• Info
• Building
• Credits

Info

All of the Metroid Prime games store image textures as a custom binary format called TXTR (CTexture) which holds a header, palette header, and GX encoded image data for each mipmap. txtrtool can decode these TXTR files to TGA images and back to TXTR files. It supports every GX image format for both decoding and encoding. Mipmap and palette generation are supported as well. Npot (non power of two) images may encode/decode incorrectly (this is not the fault of txtrtool, it just is how GX works). See txtrtool help for usage information.

Building

Linux

1. Install dependencies: git p7zip cmake ninja clang via your package manager.
2. Clone this repo: git clone --recursive https://github.com/xchellx/txtrtool.git && cd txtrtool.
3. Build the project: cmake -S . -B build -DCMAKE_BUILD_TYPE=<RELEASE_TYPE> -G Ninja -DSTBIR_SSE2:BOOL=ON -DSTBIR_AVX:BOOL=ON -DSTBIR_AVX2:BOOL=ON -DBUILD_SQUISH_WITH_SSE2:BOOL=ON where <RELEASE_TYPE> would be either Release or Debug. Specify -DTXTRTOOL_NOASAN:BOOL=ON to not include ASAN (address sanitizer) on a Debug build (if you want to use another external runtime debugger like valgrind).
4. Compile the project: cmake --build build.
5. The resulting binary should be in build directory, named txtrtool.

Windows

1. Go to MSYS2's website and follow directions 1-4 on the website and uncheck Run MSYS2 now at step 4 on the website.
2. Press the Windows Key (or click the Windows icon) and search for msys2 clang64, click the result titled MSYS2 CLANG64.
3. Update the package database: pacman -Syu. Be patient. If prompted, respond with Y. If the prompt is :: To complete this update all MSYS2 processes including this terminal will be closed. Confirm to proceed [Y/n], then respond with Y which will close the window then repeat steps 2 and 3.
4. Install dependencies: pacman -S git p7zip mingw-w64-clang-x86_64-cmake mingw-w64-clang-x86_64-ninja mingw-w64-clang-x86_64-clang.
5. Clone this repo: git clone --recursive https://github.com/xchellx/txtrtool.git && cd txtrtool.
6. Build the project: cmake -S . -B build -DCMAKE_BUILD_TYPE=<RELEASE_TYPE> -G Ninja -DSTBIR_SSE2:BOOL=ON -DSTBIR_AVX:BOOL=ON -DSTBIR_AVX2:BOOL=ON -DBUILD_SQUISH_WITH_SSE2:BOOL=ON where <RELEASE_TYPE> would be either Release or Debug.
7. Compile the project: cmake --build build.
8. The resulting binary should be in build directory, named txtrtool.exe.
9. To run txtrtool.exe, do either A, B, or C where <INSTALL_PATH_OF_MSYS2> is where you installed MSYS2 to:
   • A. If testing for development inside the MSYS2 CLANG64 terminal: Simply run txtrtool.exe with a full or relative path prefix.
   • B. If testing for development outside the MSYS2 CLANG64 terminal: add <INSTALL_PATH_OF_MSYS2>\clang64\bin to your PATH environment variable.
   • C. For redistribution: copy libc++.dll from <INSTALL_PATH_OF_MSYS2>\clang64\bin to the same location as txtrtool.exe.
     • NOTE: Distributing libstdc++-*.dll violates the GPL license! Only distribute libc++.dll (when compiling with MSYS2 CLANG64)!

Additional

If cmake files are changed in a way that makes the cache out of date, [ -d build ] && rm -r build will refresh things (this will require another build). Additionally, I personally wrote and use these for ease of compiling in my .<shell>rc file:

function cmake-clean { [ -d build ] && rm -r build ${@: 1}; }
function cmake-build { [ -n "$1" ] && cmake -S . -B build -DCMAKE_BUILD_TYPE=$1 ${@: 2}; }
function cmake-compile { [ -d build ] && cmake --build build ${@: 1}; }

This makes it simple to build with cmake from the terminal. For example, if I update cmake related files which would make the cache out of date, I'd just do cmake-clean then cmake-build Debug then cmake-compile for example. Easier and quicker to type.

Also, there is a delcfg.sh script to delete all configure_file configured files for this and subprojects (that use the similar pattern). This specifically will only work with this repo (and subrepos that use the same file pattern such as ones I author).

For copying dependencies in Windows step 9.C, there is a script copylibs.sh to help with that.

Credits

• unknown for the lots of help that they've given me developing this (and getting comfortable with C from the start).
• Retro Modding Wiki's documenation on the TXTR format here.
• Custom Mario Kart Wiiki for it's documentation of the image formats of the GX graphics system here.
• Metaforce for its template code of expanding and compacting to and from 8 bits and it's documentation of the TXTR format here.
• noclip.website for examples of how GX texture data is decoded here.
• Luigis-Mansion-Blender-Toolkit for examples of how GX texture data is decoded here
• PrimeWorldEditor for examples of how GX texture data is decoded here.
• Truevision Inc.'s documentation on the Targa (TGA) image format here or here.
• FileFormat's documentation on the Targa (TGA) image format here.
• Paul Bourke's documentation on the Targa (TGA) image format here.
• Wikipedia's documentation on the Targe (TGA) image format here.
• Just Solve The File Format Problem's documentation on the Targa (TGA) image format here
• SweetScape's 010 Editor's Binary Template functionality for helping with TXTR and TGA format research here.
• Surma, for his article of various dithering algorithms here.
• Tanner Helland, for his article of variois dithering algorithms here.
• Wikipedia for it's various pages on dithering algorithms such as here, here, and here.