created_at2021-05-03 22:37:56.463497
updated_at2024-04-02 21:34:54.040853
descriptionA rusty, dual-wielding Quake and Half-Life texture WAD parser.
Shfty (Shfty)



# Ogre   [![License]][mit] [![Latest Version]][crates.io] [![Documentation]][docs.rs] [License]: https://img.shields.io/badge/license-MIT-blue.svg [mit]: LICENSE [Latest Version]: https://img.shields.io/crates/v/ogre.svg [crates.io]: https://crates.io/crates/ogre [Documentation]: https://docs.rs/ogre/badge.svg [docs.rs]: https://docs.rs/ogre ## 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`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) 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`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) file. [`WAD`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) 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`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0), 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`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) file into AST is via the `parser::parse_wad` function: ```rust 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 functions `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`](#Async) header below for more. ## Format Support `ogre` supports the Quake [`WAD2`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) and Half-Life [`WAD3`](https://yuraj.ucoz.com/half-life-formats.pdf) formats. Currently, the original Doom [`WAD`](https://doomwiki.org/wiki/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`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) bytes. This approach scales better than single-threading, and is generally more performant - especially for large [`WAD`](https://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_7.htm#CWAD0) 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.
Commit count: 22

cargo fmt