How jkvargas/russimp works
Project Type and Purpose
• russimp is an open-source language-binding library rather than a standalone application.
• It exposes a safe, idiomatic Rust API (russimp crate) on top of low-level FFI bindings (russimp-sys submodule) to the native Assimp C library.
• Core use case: Load and post-process 3D model files of various formats into a unified Rust data structure (Scene, Mesh, Node, etc.).
File Structure
• Top level:
– Cargo.toml / src/… → The main Rust wrapper crate (russimp).
– .gitmodules → Includes the russimp-sys submodule (low-level FFI).
– examples/ → Consumer code demonstrating usage (e.g. load_scene_with_props.rs).
– models/ → Sample 3D assets fed into examples/tests.
– install_assimp.bash → Script to install Assimp system library.
– .github/workflows/russimp.yml → CI pipeline that builds, tests, and produces prebuilt binaries.
• src folder subdivides responsibilities by data type (animation.rs, mesh.rs, material.rs, etc.), reflecting the key abstractions.
README and Build Features
• Cargo features control how Assimp is linked:
• prebuilt → download static libraries from GitHub releases.
• static-link → build Assimp from source via CMake, Ninja/Visual Studio.
• nozlib → toggle zlib linking.
• Runtime API: load from file or buffer, apply post-process flags, traverse Scene structure.
Main Components and Their Relationships
a. Rust Wrapper Layer (russimp crate)
• Public Rust types: Scene, Node, Mesh, Material, Light, Camera, Bone, Animation, etc.
• Conversion logic from raw FFI structs to safe Rust representations (impl_mint.rs handles vector types).
b. FFI / Binding Layer (russimp-sys submodule)
• Raw extern "C" declarations matching Assimp API.
• Build script (build.rs in sys crate) that either downloads prebuilt binaries or compiles Assimp from source.
c. Native Assimp C Library
• Provides model-loading core functionality.
• May link statically or dynamically depending on feature flags.
d. Build Toolchain
• CMake + Ninja / MSVC for source builds.
• GitHub Actions workflow that automates prebuild and publishing of binaries.
e. Consumer Code
• examples/ directory, any downstream crate or application calling Scene::from_file.
f. Sample Assets
• models/ folder containing various 3D formats (FBX, OBJ, GLTF2, COLLADA, etc.) used for testing and examples.
Important Architectural Patterns & Design Principles
• Layered FFI pattern: clear separation between safe Rust API and unsafe C bindings.
• Feature-flag-driven builds: compile-time switches that alter dependency resolution (download vs. build).
• Modular Rust code: one file per major domain concept to keep the codebase navigable.
• CI/CD integration for binary distribution.
Essential Elements
• Clear labels on each component (e.g. “russimp::Scene loader,” “russimp-sys FFI,” “Assimp C library”).
• A small inset showing feature-flag decision points (prebuilt vs. build-from-source).