fabi/Syplheed-Reborn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initialise workspace — Milestone 1 asset explorer

Browse Source 
Three-crate Cargo workspace structured per PROJECT.md spec:
- crates/sylpheed-formats  — Xbox 360 format parsers (no Bevy)
- crates/sylpheed-viewer   — Bevy 0.15 asset viewer + egui UI
- crates/sylpheed-cli      — CLI tools (extract/list/sniff/texture)

Milestone 1 features:
- XISO disc image reading via xdvdfs 0.8
- XPR2 texture container parsing + Morton de-tiling
- D3DFORMAT → wgpu TextureFormat mapping (DXT1/3/5, DXN, ARGB)
- Custom Bevy AssetLoader for .xpr files
- Orbit camera (LMB orbit, RMB pan, scroll zoom)
- egui file browser + RE notes panel
- CLI: extract / list / sniff / texture info / texture export
- GitHub Actions CI (Linux, macOS, Windows, WASM)
- Trunk WASM build config

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-03-25 21:04:07 +01:00
commit f8127e73b0
23 changed files with 8107 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

422
crates/sylpheed-formats/src/texture.rs Normal file
View File

@@ -0,0 +1,422 @@
//! Xbox 360 texture format parsing and de-tiling.
//!
//! ## The Problem: GPU Tiling
//! The Xbox 360 Xenos GPU stores textures in a "tiled" memory layout for
//! cache efficiency. The tiles are 32×32 texel macro-tiles, and within
//! each macro-tile the DXT compression blocks are arranged in Morton
//! (Z-order curve) order. Before we can upload a texture to a modern GPU,
//! we must "de-tile" it back to a standard linear (row-major) layout.
//!
//! ## Reference implementations
//! - Xenia emulator: `src/xenia/gpu/texture_util.cc`
//! - RareView (C#): Xbox 360 texture de-tiling
//! - swizzleinator crate: general console texture unswizzling
use binrw::{BinRead, binread};
use thiserror::Error;
// ── Error type ───────────────────────────────────────────────────────────────
#[derive(Debug, Error)]
pub enum TextureError {
#[error("Invalid texture header magic: expected {expected:?}, got {got:?}")]
BadMagic { expected: [u8; 4], got: [u8; 4] },
#[error("Unsupported texture format: 0x{0:02X}")]
UnsupportedFormat(u8),
#[error("Buffer too small: need {needed} bytes, have {have}")]
BufferTooSmall { needed: usize, have: usize },
#[error("IO error: {0}")]
Io(#[from] std::io::Error),
#[error("Parse error: {0}")]
Parse(#[from] binrw::Error),
}
// ── Texture formats ───────────────────────────────────────────────────────────
/// D3DFORMAT values used by the Xbox 360 SDK for texture data.
/// These appear in XPR2 headers and in-memory texture descriptors.
///
/// Format codes sourced from:
/// - Xbox 360 SDK documentation (leaked)
/// - Xenia emulator source (gpu/xenos.h)
/// - ZenHAX community research
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum X360TextureFormat {
/// DXT1 / BC1 — 4 bpp, 1-bit alpha
Dxt1 = 0x52,
/// DXT3 / BC2 — 8 bpp, 4-bit explicit alpha
Dxt3 = 0x53,
/// DXT5 / BC3 — 8 bpp, 8-bit interpolated alpha
Dxt5 = 0x54,
/// DXN / BC5 / ATI2 — normal maps, two-channel
Dxn = 0x71,
/// Uncompressed A8R8G8B8 — 32 bpp
A8R8G8B8 = 0x06,
/// Uncompressed X8R8G8B8 — 32 bpp, no alpha
X8R8G8B8 = 0x07,
}
impl X360TextureFormat {
pub fn from_u8(v: u8) -> Option<Self> {
match v {
0x52 => Some(Self::Dxt1),
0x53 => Some(Self::Dxt3),
0x54 => Some(Self::Dxt5),
0x71 => Some(Self::Dxn),
0x06 => Some(Self::A8R8G8B8),
0x07 => Some(Self::X8R8G8B8),
_ => None,
}
}
/// Bytes per compressed block (4×4 texel group).
/// For uncompressed formats, bytes per pixel instead.
pub fn bytes_per_block(&self) -> usize {
match self {
Self::Dxt1 => 8,
Self::Dxt3 | Self::Dxt5 | Self::Dxn => 16,
Self::A8R8G8B8 | Self::X8R8G8B8 => 4,
}
}
/// Is this a BCn block-compressed format?
pub fn is_block_compressed(&self) -> bool {
matches!(self, Self::Dxt1 | Self::Dxt3 | Self::Dxt5 | Self::Dxn)
}
/// Texels per block side (4 for BCn, 1 for uncompressed).
pub fn block_size(&self) -> usize {
if self.is_block_compressed() { 4 } else { 1 }
}
}
// ── XPR2 container format ─────────────────────────────────────────────────────
/// XPR2 is Microsoft's Xbox Packed Resource v2 format.
/// It stores D3D resources (textures, vertex buffers, index buffers)
/// in a single blob that can be DMA'd directly into GPU memory.
///
/// The header is big-endian (Xbox 360 is big-endian PowerPC).
/// NOTE: Project Sylpheed may use a custom container. If files don't
/// start with b"XPR2", check for game-specific magic bytes instead.
#[binread]
#[br(magic = b"XPR2", big)]
#[derive(Debug, Clone)]
pub struct Xpr2Header {
/// Total file size in bytes
pub total_size: u32,
/// Size of the header section (texture data starts after this)
pub header_size: u32,
/// Number of resource entries in this file
pub num_resources: u32,
}
/// A single resource entry within an XPR2 file.
/// Each entry describes one D3D resource (texture, buffer, etc.)
#[binread]
#[br(big)]
#[derive(Debug, Clone)]
pub struct Xpr2ResourceEntry {
/// Encoded type and reference count.
/// Bits [0..15] = ref_count
/// Bits [16..18] = resource type (4 = texture)
/// Bits [19..31] = flags
pub resource_type_and_flags: u32,
/// Offset of this resource's data within the XPR2 file
pub data_offset: u32,
/// Reserved / unknown
pub _unknown: u32,
}
impl Xpr2ResourceEntry {
pub fn resource_type(&self) -> u8 {
((self.resource_type_and_flags >> 16) & 0x7) as u8
}
pub fn is_texture(&self) -> bool {
self.resource_type() == 4
}
}
/// Xbox 360 D3D texture descriptor embedded in an XPR2 resource.
/// This is what the GPU register `NV097_SET_TEXTURE_FORMAT` receives.
///
/// Reference: xboxdevwiki.net/XPR
#[binread]
#[br(big)]
#[derive(Debug, Clone)]
pub struct X360TextureDesc {
/// Packed GPU texture format register
/// Bits [0..3] = DMA channel
/// Bits [4..7] = dimensionality (2 = 2D)
/// Bits [8..15] = D3DFORMAT (see X360TextureFormat)
/// Bits [16..19] = mip levels
/// Bits [20..23] = width as power-of-two: actual = 1 << value
/// Bits [24..27] = height as power-of-two: actual = 1 << value
/// Bits [28..31] = depth (for 3D textures)
pub gpu_format: u32,
/// For non-power-of-two textures, encodes actual dimensions
pub npot_size: u32,
}
impl X360TextureDesc {
pub fn format_code(&self) -> u8 {
((self.gpu_format >> 8) & 0xFF) as u8
}
pub fn format(&self) -> Option<X360TextureFormat> {
X360TextureFormat::from_u8(self.format_code())
}
pub fn mip_levels(&self) -> u32 {
(self.gpu_format >> 16) & 0xF
}
/// Width from the packed power-of-two field.
pub fn width_pow2(&self) -> u32 {
1 << ((self.gpu_format >> 20) & 0xF)
}
/// Height from the packed power-of-two field.
pub fn height_pow2(&self) -> u32 {
1 << ((self.gpu_format >> 24) & 0xF)
}
}
// ── Decoded texture ───────────────────────────────────────────────────────────
/// A decoded Xbox 360 texture, ready to upload to a modern GPU.
///
/// After `from_xpr2()` or `from_raw_tiled()`, the `data` field contains
/// the texture in standard linear layout that Bevy / wgpu can consume.
#[derive(Debug, Clone)]
pub struct X360Texture {
pub width: u32,
pub height: u32,
pub format: X360TextureFormat,
pub mip_levels: u32,
/// De-tiled texture data in linear (row-major) order.
/// For BCn formats: standard DDS-style packed block data.
/// For ARGB: standard RGBA8 pixel data.
pub data: Vec<u8>,
}
impl X360Texture {
/// Parse a texture from a raw XPR2 file's bytes.
///
/// This handles the full pipeline:
/// 1. Parse XPR2 header + resource descriptors
/// 2. Locate the texture resource
/// 3. De-tile the GPU memory layout → linear layout
pub fn from_xpr2(bytes: &[u8]) -> Result<Self, TextureError> {
use std::io::Cursor;
let mut cur = Cursor::new(bytes);
// Parse main header (validates "XPR2" magic)
let header = Xpr2Header::read(&mut cur)?;
// Parse resource entries
let mut entries = Vec::new();
for _ in 0..header.num_resources {
entries.push(Xpr2ResourceEntry::read(&mut cur)?);
}
// Find the first texture resource
let tex_entry = entries.iter()
.find(|e| e.is_texture())
.ok_or_else(|| TextureError::UnsupportedFormat(0))?;
// The texture descriptor immediately follows the resource entries
let desc = X360TextureDesc::read(&mut cur)?;
let format = desc.format()
.ok_or(TextureError::UnsupportedFormat(desc.format_code()))?;
let width = desc.width_pow2();
let height = desc.height_pow2();
// Texture data is at header_size offset
let data_start = header.header_size as usize;
if bytes.len() <= data_start {
return Err(TextureError::BufferTooSmall {
needed: data_start + 1,
have: bytes.len(),
});
}
let tiled_data = &bytes[data_start..];
// De-tile!
let linear_data = detile(tiled_data, width, height, format)?;
Ok(X360Texture {
width,
height,
format,
mip_levels: desc.mip_levels().max(1),
data: linear_data,
})
}
/// Parse a texture from already-known parameters + raw tiled data.
///
/// Use this when you've reverse-engineered a game-specific container
/// and extracted the raw tiled texture bytes yourself.
pub fn from_raw_tiled(
tiled_data: &[u8],
width: u32,
height: u32,
format: X360TextureFormat,
) -> Result<Self, TextureError> {
let linear_data = detile(tiled_data, width, height, format)?;
Ok(X360Texture {
width,
height,
format,
mip_levels: 1,
data: linear_data,
})
}
}
// ── Core de-tiling algorithm ──────────────────────────────────────────────────
/// De-tile an Xbox 360 GPU texture from tiled to linear layout.
///
/// Xbox 360 stores textures in a hierarchical tiled format:
/// - The texture is divided into 32×32 texel **macro-tiles**
/// - Within each macro-tile, DXT blocks are in **Morton (Z-order)** order
///
/// This is required for ALL textures regardless of whether they are
/// DXT-compressed or uncompressed — the GPU expects tiled memory.
///
/// Algorithm based on:
/// - Xenia: `texture_util.cc` `TileTexture()`
/// - GTA IV Xbox 360 Texture Editor by Pimpin Tyler and Anthony
pub fn detile(
src: &[u8],
width: u32,
height: u32,
format: X360TextureFormat,
) -> Result<Vec<u8>, TextureError> {
let block_size = format.block_size() as u32;
let bpb = format.bytes_per_block(); // bytes per block
// Dimensions in blocks
let blocks_wide = ((width + block_size - 1) / block_size).max(1);
let blocks_tall = ((height + block_size - 1) / block_size).max(1);
let expected = blocks_wide as usize * blocks_tall as usize * bpb;
if src.len() < expected {
return Err(TextureError::BufferTooSmall {
needed: expected,
have: src.len(),
});
}
let mut dst = vec![0u8; expected];
// Macro-tile dimensions (in blocks)
// Xbox 360 always uses 32×32 texel macro-tiles
let macro_tile_blocks = 32 / block_size; // = 8 for BCn (4×4 texels/block)
let macro_tiles_wide = (blocks_wide + macro_tile_blocks - 1) / macro_tile_blocks;
let macro_tiles_tall = (blocks_tall + macro_tile_blocks - 1) / macro_tile_blocks;
let blocks_per_macro_tile = (macro_tile_blocks * macro_tile_blocks) as usize;
for macro_y in 0..macro_tiles_tall {
for macro_x in 0..macro_tiles_wide {
let macro_base = ((macro_y * macro_tiles_wide + macro_x) as usize)
* blocks_per_macro_tile
* bpb;
for local in 0..blocks_per_macro_tile as u32 {
// Decode Morton (Z-order) index → (lx, ly) within macro-tile
let (lx, ly) = morton_decode(local);
let block_x = macro_x * macro_tile_blocks + lx;
let block_y = macro_y * macro_tile_blocks + ly;
// Skip blocks that fall outside the actual texture dimensions
if block_x >= blocks_wide || block_y >= blocks_tall {
continue;
}
let src_offset = macro_base + local as usize * bpb;
let dst_offset = (block_y * blocks_wide + block_x) as usize * bpb;
if src_offset + bpb <= src.len() && dst_offset + bpb <= dst.len() {
dst[dst_offset..dst_offset + bpb]
.copy_from_slice(&src[src_offset..src_offset + bpb]);
}
}
}
}
Ok(dst)
}
/// Decode a Morton (Z-order curve) index into (x, y) coordinates.
///
/// Morton encoding interleaves the bits of x and y coordinates:
/// index = ...y3 x3 y2 x2 y1 x1 y0 x0
///
/// This is the inverse operation — extract interleaved bits back to x, y.
#[inline]
pub fn morton_decode(index: u32) -> (u32, u32) {
let x = compact_bits(index);
let y = compact_bits(index >> 1);
(x, y)
}
/// Compact every other bit — the "de-interleave" operation.
/// Used by `morton_decode` to separate X and Y from a Morton index.
#[inline]
fn compact_bits(mut x: u32) -> u32 {
x &= 0x5555_5555; // x = -f-e -d-c -b-a -9-8 -7-6 -5-4 -3-2 -1-0
x = (x ^ (x >> 1)) & 0x3333_3333; // x = --fe --dc --ba --98 --76 --54 --32 --10
x = (x ^ (x >> 2)) & 0x0f0f_0f0f; // x = ----fedc ----ba98 ----7654 ----3210
x = (x ^ (x >> 4)) & 0x00ff_00ff; // x = --------fedcba98 --------76543210
x = (x ^ (x >> 8)) & 0x0000_ffff; // x = ----------------fedcba9876543210
x
}
// ── Tests ────────────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn morton_decode_corners() {
// Index 0 → (0, 0)
assert_eq!(morton_decode(0), (0, 0));
// Index 1 → (1, 0) — bit 0 is x
assert_eq!(morton_decode(1), (1, 0));
// Index 2 → (0, 1) — bit 1 is y
assert_eq!(morton_decode(2), (0, 1));
// Index 3 → (1, 1)
assert_eq!(morton_decode(3), (1, 1));
}
#[test]
fn detile_noop_for_1x1_block() {
// A 4×4 DXT1 texture = exactly 1 block = 8 bytes
// De-tiling a single block should be identity
let src = vec![0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x02, 0x03, 0x04];
let result = detile(&src, 4, 4, X360TextureFormat::Dxt1).unwrap();
assert_eq!(result, src);
}
#[test]
fn x360_format_bytes_per_block() {
assert_eq!(X360TextureFormat::Dxt1.bytes_per_block(), 8);
assert_eq!(X360TextureFormat::Dxt5.bytes_per_block(), 16);
assert_eq!(X360TextureFormat::A8R8G8B8.bytes_per_block(), 4);
}
}