Expand description
§A rusty, dual-wielding Quake and Half-Life texture WAD parser
ogre
is a Rust representation and nom
parser for Quake and Half-Life WAD
files.
It’s written in pure Rust, and enforces the use of safe code crate-wide via #![forbid(unsafe_code)]
.
§Rust Representation
The Rust represention lives in the repr
module,
and is a set of structs representing the contents of a parsed WAD
file.
WAD
files contain certain intermediary structures - such as a header, and metadata directory - that are specific to parse-time, and thus don’t show up in the final representation.
For cases where you want to inspect these elements of a WAD
, the parser
module contains its own parser::repr
submodule, as well as nom
functions for parsing into the structures therein.
§Parsing
The simplest way to parse a WAD
file into rust representation is via the parser::parse_wad
function:
let wad = include_bytes!("../../ogre/test_data/wad2/medieval.wad");
let (_, wad) = ogre::parser::parse_wad(wad).expect("Failed to parse WAD");
assert!(wad.len() > 0);
println!("{:#?}", wad);
This will parse a complete Wad
, and block the calling thread until completion.
Internally, it calls the rest of the functions in the parser
module to assemble its final output.
These can also be used directly in cases where more granular parsing is desired.
For better performance, a parallelized implementation is recommended. See the Async
header below for more.
§Format Support
ogre
supports the Quake WAD2
and Half-Life WAD3
formats.
Currently, the original Doom WAD
format is not supported on account of its different data structure and significantly larger scope.
§Serde Support
For cases where serializing and deserializing the rust representation is required,
ogre
includes serde::Serialize
and serde::Deserialize
derives for all types inside the repr
and parser::repr
modules.
This functionality is gated behind the serde_support
feature flag, which is enabled by default.
§Async
ogre
includes a parallelized implementation that uses async_std::task
to multiplex the routines inside parser
over some source of WAD
bytes.
This approach scales better than single-threading, and is generally more performant - especially for large WAD
files.
An explanation and usage guide can be found inside the parser_async
module.
This functionality is gated behind the async
feature flag, which is enabled by default.
Modules§
nom
functions for parsing the WAD format.- Parallelized WAD parsing implementation using
async_std
. - Rust representation of a WAD file and its contents.