Crate gctex

gctex

gctex is a Rust crate designed for encoding and decoding texture formats used in the Nintendo GameCube and Wii games. The library provides C bindings, making it useful in both Rust and C/C++ based projects.

Usage

Rust

The following snippet demonstrates how to encode a texture in CMPR format using Rust:

let width: u32 = 32;
let height: u32 = 32;
let src = vec![0; (width*height*4) as usize];
let dst = gctex::encode(gctex::TextureFormat::CMPR, &src, width, height);

C# Bindings

See https://github.com/riidefi/RiiStudio/tree/master/source/gctex/examples/c%23

byte[] dst = new byte[dst_len];
byte[] src = new byte[src_len];
gctex.Encode(0xE /* CMPR */, dst, src, width, height);

C/C++

See https://github.com/riidefi/RiiStudio/tree/master/source/gctex/examples/c%2b%2b

#include "gctex.h"

unsigned char dst[dst_len];
unsigned char src[src_len];
rii_encode_cmpr(dst, sizeof(dst), src, sizeof(src), width, height);

The relevant header is available in include/gctex.h.

Supported Formats

All supported texture formats and their respective encoding and decoding sources are listed below.

Format	Encoding Source	Decoding Source
CMPR	Builtin	Dolphin Emulator (SIMD) / Rust non-SIMD fallback
I4	Builtin	Builtin (SIMD (SSE3))
I8	Builtin	Dolphin Emulator (SIMD) / Rust non-SIMD fallback
IA4	Builtin	Builtin
IA8	Builtin	Dolphin Emulator (SIMD) / Rust non-SIMD fallback
RGB565	Builtin	Dolphin Emulator (SIMD) / Rust non-SIMD fallback
RGB5A3	Builtin	Dolphin Emulator (SIMD) / Rust non-SIMD fallback
RGBA8	Builtin	Builtin (SIMD (SSE3))
C4	-	Dolphin Emulator / No fallback
C8	-	Dolphin Emulator / No fallback
C14	-	Dolphin Emulator / No fallback

Please note, SIMD texture decoding for I4, I8 and IA8 formats uses SSE3 instructions with a fallback to SSE2 if necessary (excepting I4), and these are implemented based on the Dolphin Emulator’s texture decoding logic.

Optional Features

• To avoid needing a C++ compiler or running C++ code, unset the cpp_fallback feature to fallback to non-SIMD Rust implementations of I4/I8/IA8/RGB565/RGB5A3 decoding.
• For debugging the simd feature can be disabled to use pure, standard Rust.

License

This dynamically linked library is published under GPLv2.

Modules

• bindings
• c_api

Enums

• CopyTextureFormat
• TextureFormat
• ZTextureFormat

Constants

• _CTF
• _ZTF

Functions

• compute_image_size
  Computes the size of the image based on its texture format, width, and height.
• compute_image_size_mip
  Computes the total size of the image and its mipmaps based on the texture format, width, height, and number of images.
• decode
  Decodes a Nintendo GameCube or Wii texture and returns the decoded data as a Vec<u8>.
• decode_fast
  Decodes a texture using a fast decoding method optimized for the Nintendo GameCube and Wii texture formats.
• decode_into
  Decodes a Nintendo GameCube or Wii texture into the provided destination buffer.
• encode
  Encodes a Nintendo GameCube or Wii texture into the specified format and returns the encoded data as a Vec<u8>.
• encode_fast
  Encodes a Nintendo GameCube or Wii texture into the specified format and writes the result into the provided destination buffer.
• encode_into
  Encodes a Nintendo GameCube or Wii texture into the specified format and writes the result into the provided destination buffer.
• encode_raw_into
• get_version
  Returns a formatted string representing the version, build profile, and target of the gctex crate.