all_is_cubes_port/
lib.rs

1//! Data import and export between [`all_is_cubes`] types and other data formats.
2//!
3//! Currently supported formats:
4//!
5//! | Format              | Extension          | Feature     | Import  | Export  | Caveats |
6//! |---------------------|--------------------|-------------|:-------:|:-------:|---------|
7//! | All is Cubes native | `.alliscubesjson`  | `"native"`  | **Yes** | **Yes** | Version compatibility not yet guaranteed. |
8//! | MagicaVoxel `.vox`  | `.vox`             | `"dot-vox"` | **Yes** | **Yes** | Scene import is buggy. Materials are not exported at all. |
9//! | [glTF 2.0]          | `.gltf`            | `"gltf"`    | No      | **Yes** | Textures are not yet implemented. Output is suitable for rendering but not necessarily editing due to combined meshes. |
10//! | [STL]               | `.stl`             | `"stl"`     | No      | **Yes** | Meshes are not necessarily “manifold”/“watertight”. |
11//!
12//! [glTF 2.0]: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
13//! [STL]: <https://en.wikipedia.org/wiki/STL_(file_format)>
14//!
15//! ## Package features
16//!
17//! This package defines the following feature flags:
18//!
19//! * `"import"`: importing/loading.
20//! * `"export"`: exporting/saving.
21//! * `"all-formats"`: Enables all format features.
22//! * Features for each supported format as listed in the above table.
23//! * `"auto-threads"`:
24//!   Enables implicit use of threads for parallel processing,
25//!   including via [`rayon`]’s global thread pool.
26//!
27//! In order to perform any actual operation, the feature for the desired format, and
28//! the appropriate one of `"export"` or `"import"`, must both be enabled.
29//!
30
31// Crate-specific lint settings. (General settings can be found in the workspace manifest.)
32#![forbid(unsafe_code)]
33
34use std::fmt;
35
36#[cfg(doc)]
37use all_is_cubes::space::Space;
38
39// -------------------------------------------------------------------------------------------------
40
41#[cfg(feature = "export")]
42mod export;
43#[cfg(feature = "export")]
44pub use export::*;
45
46#[cfg(feature = "import")]
47mod import;
48#[cfg(feature = "import")]
49pub use import::*;
50
51pub mod file;
52mod util;
53
54// Formats
55#[cfg(all(feature = "export", feature = "gltf"))]
56pub mod gltf;
57#[cfg(feature = "dot-vox")]
58mod mv;
59#[cfg(feature = "native")]
60mod native;
61#[cfg(all(feature = "export", feature = "stl"))]
62mod stl;
63
64#[cfg(test)]
65mod tests;
66
67// -------------------------------------------------------------------------------------------------
68
69/// File formats that All is Cubes data can be exported to or imported from.
70///
71/// Note that if some feature flags are disabled, this library may not be in fact able to
72/// perform an export to all of these formats. The enum variants are present un-conditionally
73/// so that the formats can be described regardless.
74#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
75#[non_exhaustive]
76pub enum Format {
77    /// Native format: JSON-encoded All is Cubes universe serialization.
78    AicJson,
79
80    /// [MagicaVoxel `.vox`][vox] file.
81    ///
82    /// TODO: document version details and export limitations
83    ///
84    /// [vox]: https://github.com/ephtracy/voxel-model/blob/master/MagicaVoxel-file-format-vox.txt
85    DotVox,
86
87    /// [glTF 2.0] format (`.gltf` JSON with auxiliary files).
88    ///
89    /// TODO: document capabilities
90    ///
91    /// TODO: document how auxiliary files are handled
92    ///
93    /// TODO: support `.glb` binary format.
94    ///
95    /// [glTF 2.0]: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
96    Gltf,
97
98    /// [STL] format.
99    ///
100    /// Supports exporting block and space shapes without color.
101    ///
102    /// [STL]: <https://en.wikipedia.org/wiki/STL_(file_format)>
103    Stl,
104}
105
106impl Format {
107    /// Return a noun phrase naming the format, e.g. “glTF”.
108    pub fn descriptive_name(self) -> impl fmt::Display {
109        match self {
110            Format::AicJson => "All is Cubes",
111            Format::DotVox => "MagicaVoxel .vox",
112            Format::Gltf => "glTF",
113            Format::Stl => "STL",
114        }
115    }
116
117    /// Whether exporting to this format is capable of including [`Space`] light data.
118    ///
119    /// This may be used to decide whether to wait for light calculations before exporting.
120    pub fn includes_light(self) -> bool {
121        match self {
122            Format::AicJson => true,
123            Format::DotVox => false,
124            Format::Gltf => false, // TODO: implement light
125            Format::Stl => false,
126        }
127    }
128}
all_is_cubes_port/lib.rs

all_is_cubes_port/
lib.rs
