oxideav_obj/
lib.rs

1//! Pure-Rust Wavefront OBJ + MTL 3D mesh codec.
2//!
3//! Implements [`oxideav_mesh3d::Mesh3DDecoder`] and
4//! [`oxideav_mesh3d::Mesh3DEncoder`] for the polygonal subset of the
5//! OBJ format published by Wavefront Technologies in the early 1990s
6//! (Appendix B of the *Advanced Visualizer* manual). Companion MTL
7//! material files are parsed/serialised by the same crate so a
8//! decoded [`Scene3D`](oxideav_mesh3d::Scene3D) carries its full
9//! material set.
10//!
11//! # Modules
12//!
13//! * [`obj`] — line-oriented parser and serialiser for the geometry
14//!   format itself (`v` / `vt` / `vn` / `f` / `l` / `o` / `g` / `s` /
15//!   `usemtl` / `mtllib`).
16//! * [`mtl`] — line-oriented parser and serialiser for the material
17//!   library (`newmtl` / `Ka` / `Kd` / `Ks` / `Ns` / `Ni` / `d` /
18//!   `Tr` / `illum` / `map_*` and the Wavefront-PBR extension
19//!   `Pr` / `Pm` / `Pc` / `Ps` / `map_Pr` / `map_Pm`).
20//! * [`decoder`] — [`ObjDecoder`] type wired to the
21//!   [`Mesh3DDecoder`](oxideav_mesh3d::Mesh3DDecoder) trait.
22//! * [`encoder`] — [`ObjEncoder`] type wired to the
23//!   [`Mesh3DEncoder`](oxideav_mesh3d::Mesh3DEncoder) trait.
24//!
25//! # Standalone build
26//!
27//! Drop the `registry` feature for a free-standing build:
28//!
29//! ```toml
30//! oxideav-obj = { version = "0.0", default-features = false }
31//! ```
32//!
33//! This compiles out the [`register`] helper and the `oxideav-core`
34//! dependency; the [`ObjDecoder`] and [`ObjEncoder`] types remain
35//! usable directly through the standalone
36//! [`Mesh3DDecoder`](oxideav_mesh3d::Mesh3DDecoder) /
37//! [`Mesh3DEncoder`](oxideav_mesh3d::Mesh3DEncoder) traits.
38
39#![forbid(unsafe_code)]
40#![warn(missing_debug_implementations)]
41
42pub mod decoder;
43pub mod encoder;
44pub mod mtl;
45pub mod obj;
46
47pub use decoder::ObjDecoder;
48pub use encoder::ObjEncoder;
49
50/// Register OBJ + MTL decoders and encoders with a
51/// [`Mesh3DRegistry`](oxideav_mesh3d::Mesh3DRegistry).
52///
53/// Two format ids land:
54///
55/// * `"obj"` — extension `.obj`. Decoder produces a fully-populated
56///   `Scene3D`; encoder emits a single OBJ document and accepts a
57///   companion MTL via [`ObjEncoder::with_mtl_basename`].
58/// * `"mtl"` — extension `.mtl`. Decoder produces a `Scene3D` with
59///   only the materials populated (no meshes / nodes); encoder emits
60///   the MTL document for the scene's materials.
61///
62/// The OBJ encoder does **not** automatically write the companion MTL
63/// — that's the caller's job (since they own the file-system context).
64/// See [`mtl::serialize_mtl`] / [`obj::serialize_obj`] if you need to
65/// drive both halves manually.
66#[cfg(feature = "registry")]
67pub fn register(registry: &mut oxideav_mesh3d::Mesh3DRegistry) {
68    registry.register_decoder("obj", &["obj"], Box::new(|| Box::new(ObjDecoder::new())));
69    registry.register_encoder("obj", &["obj"], Box::new(|| Box::new(ObjEncoder::new())));
70    registry.register_decoder(
71        "mtl",
72        &["mtl"],
73        Box::new(|| Box::new(decoder::MtlDecoder::new())),
74    );
75    registry.register_encoder(
76        "mtl",
77        &["mtl"],
78        Box::new(|| Box::new(encoder::MtlEncoder::new())),
79    );
80}
oxideav_obj/lib.rs

oxideav_obj/
lib.rs
