Merge branch 'release/v0.4.4'

.travis.yml

@@ -3,5 +3,9 @@ cache: cargo
 rust:
   - stable
   - beta
+  - 1.34.0
+script:
+  - cargo build --verbose --all-features
+  - cargo test --verbose --all-features
 notifications:
   email: false

CHANGELOG.md

@@ -2,6 +2,62 @@
 
 ## [Unreleased]
 
+## [0.4.4]
+
+* Documents are improved a little.
+* Manual tree construction (without using parser) is now supported.
+    + You can add nodes and attributes manually to the tree at runtime.
+    + You can describe the tree using `tree_v7400!` macro at compile time.
+* FBX binary writer is added.
+* Tiny improvements:
+    + `low::v7400::AttributeValue` implements `From<_>` for some types.
+    + Strict equality check is added for trees, nodes, and attribute values.
+    + `tree::v7400::Tree::debug_tree()` is added.
+* Now rustc-1.34 or later is required.
+    + To use `std::convert::{TryFrom, TryInto}`.
+
+### Added
+* Manual tree construction support is added (64f70b051c30, 39c4fabad119).
+    + Methods to add new nodes and attributes are added.
+    + Complete modification is not yet supported, for example modifying already
+      added attributes or removing nodes.
+    * `tree_v7400!` macro is added to construct tree easily.
+      See documentation for detail.
+* FBX binary writer is added (e1cb2a232d19, 33d9ac3a589c, d5dc779c0bd4,
+  6cddca849a4f, 8c84359d2578).
+    + `writer::v7400::binary` contains FBX binary writer stuff.
+    + This can be enabled by `writer` feature.
+    + `write_v7400_binary!` macro is also added.
+      See the documentation for detail.
+* `low::v7400::AttributeValue` implements `From<_>` for some types
+  (a54226534a73, 6546d62fd38a).
+    + Primitive types: `bool`, `i16`, `i32`, `i64`, `f32`, `f64`.
+    + Vector types: `Vec<bool>`, `Vec<i32>`, `Vec<i64>`, `Vec<f32>`, `Vec<f64>`,
+      `Vec<u8>`.
+    + Slice types: `&[bool]`, `&[i32]`, `&[i64]`, `&[f32]`, `&[f64]`, `&[u8]`.
+    + Special types: `String`, `&str`.
+* Strict equality check is added for trees, nodes, and attribute values
+  (8784d7609d8e).
+    + Trees: `tree::v7400::Tree::strict_eq()`.
+    + Nodes: `tree::v7400::NodeHandle::strict_eq()`.
+    + Attributes: `low::v7400::AttributeValue::strict_eq()`.
+    + These checks compares `f32` and `f64` bitwise.
+      This means `NAN == NAN` situation is possible.
+* `tree::v7400::Tree::debug_tree()` is added (4524b4dc4a99).
+    * This returns pretty-printable object of the tree.
+    * It dumps human-readable tree structure.
+    * Default `Debug` implementation for `Tree` is hard to read because it dumps
+      arena and interned string table.
+
+### Non-breaking change
+* Now rustc-1.34 or later is required.
+    + To use `std::convert::TryFrom`.
+    + Strictly, this is a breaking change (for users with rustc-1.33 or below),
+      but not breaking for users with latest rustc.
+    + Currently, only `writer` module uses `TryFrom`.
+      Users not using `writer` feature won't be affected for now, but they could
+      encounter compile error in future version of fbxcel.
+
 ## [0.4.3]
 
 * Longer lifetime for iterator returned by
@@ -93,7 +149,7 @@
     + It is moved to `low::v7400::AttributeValue`.
     + Now `DirectAttributeValue` is a type alias to
       `low::v7400::AttributeValue`.
-    + The type alias will exists for a while, but will be removed in future
+    + The type alias will exist for a while, but will be removed in future
       version.
 
 ## [0.3.0]
@@ -155,7 +211,8 @@
 
 Totally rewritten.
 
-[Unreleased]: <https://github.com/lo48576/fbxcel/compare/v0.4.3...develop>
+[Unreleased]: <https://github.com/lo48576/fbxcel/compare/v0.4.4...develop>
+[0.4.4]: <https://github.com/lo48576/fbxcel/releases/tag/v0.4.4>
 [0.4.3]: <https://github.com/lo48576/fbxcel/releases/tag/v0.4.3>
 [0.4.2]: <https://github.com/lo48576/fbxcel/releases/tag/v0.4.2>
 [0.4.1]: <https://github.com/lo48576/fbxcel/releases/tag/v0.4.1>

Cargo.toml

@@ -1,13 +1,14 @@
 [package]
 name = "fbxcel"
-version = "0.4.3"
+version = "0.4.4"
 authors = ["YOSHIOKA Takuma <[email protected]>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 description = "Excellent FBX library"
 repository = "https://github.com/lo48576/fbxcel"
 keywords = ["FBX", "3D", "model"]
+categories = ["parser-implementations"]
 
 [package.metadata.docs.rs]
 all-features = true
@@ -16,10 +17,11 @@ all-features = true
 default = []
 
 tree = ["indextree", "string-interner"]
+writer = []
 
 [dependencies]
 byteorder = "1"
-indextree = { version = "3", optional = true }
+indextree = { version = "4", optional = true }
 libflate = "0.1"
 log = "0.4.4"
 string-interner = { version = "0.7", optional = true, default-features = false }

README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://travis-ci.org/lo48576/fbxcel.svg?branch=develop)](https://travis-ci.org/lo48576/fbxcel)
 [![Latest version](https://img.shields.io/crates/v/fbxcel.svg)](https://crates.io/crates/fbxcel)
 [![Documentation](https://docs.rs/fbxcel/badge.svg)](https://docs.rs/fbxcel)
-![Minimum rustc version: 1.33](https://img.shields.io/badge/rustc-1.33+-lightgray.svg)
+![Minimum rustc version: 1.34](https://img.shields.io/badge/rustc-1.34+-lightgray.svg)
 
 `fbxcel` is an FBX library for Rust programming language.
 
@@ -15,6 +15,9 @@ If you want to interpret and render FBX data, use
 
 * Pull parser for FBX binary (`pull_parser` module)
     + FBX 7.4 and 7.5 is explicitly supported.
+* Writer for FBX binary (`writer` module)
+    + FBX 7.4 and 7.5 is explicitly supported.
+    + This is optional and enabled by `writer` feature.
 * Types and functions for low-level FBX tree access
     + This is optional and enabled by `tree` feature.
     + Provides arena-based tree type and read-only access to nodes.
@@ -34,7 +37,7 @@ Currently there is no plan to support FBX ASCII format.
 
 ## Rust version
 
-Latest stable compiler (currently 1.33) is supported.
+Latest stable compiler (currently 1.34) is supported.
 
 ## License
 

src/lib.rs

@@ -9,10 +9,15 @@
 //! `tree` module provides tree types, which allow users to access FBX data as
 //! tree, not as stream of parser events.
 //! To use `tree` module, enable `tree` feature.
+//!
+//! `writer` module provides writer types.
+//! To use `writer` module, enable `writer` feature.
 #![warn(missing_docs)]
 #![warn(clippy::missing_docs_in_private_items)]
 
 pub mod low;
 pub mod pull_parser;
 #[cfg(feature = "tree")]
 pub mod tree;
+#[cfg(feature = "writer")]
+pub mod writer;

src/low.rs

@@ -1,5 +1,7 @@
 //! Low-level or primitive data types for FBX binary.
 
+#[cfg(feature = "writer")]
+pub(crate) use self::fbx_header::MAGIC;
 pub use self::{
     fbx_header::{FbxHeader, HeaderError},
     version::FbxVersion,

src/low/fbx_header.rs

@@ -10,6 +10,9 @@ use crate::{low::FbxVersion, pull_parser::ParserVersion};
 /// Magic binary length.
 const MAGIC_LEN: usize = 23;
 
+/// Magic binary.
+pub(crate) const MAGIC: &[u8; MAGIC_LEN] = b"Kaydara FBX Binary  \x00\x1a\x00";
+
 /// Header read error.
 #[derive(Debug)]
 pub enum HeaderError {
@@ -48,9 +51,6 @@ pub struct FbxHeader {
 impl FbxHeader {
     /// Reads an FBX header from the given reader.
     pub fn load(mut reader: impl io::Read) -> Result<Self, HeaderError> {
-        /// Magic binary.
-        const MAGIC: &[u8; MAGIC_LEN] = b"Kaydara FBX Binary  \x00\x1a\x00";
-
         // Check magic.
         let mut magic_buf = [0u8; MAGIC_LEN];
         reader.read_exact(&mut magic_buf)?;

src/low/v7400.rs

@@ -1,14 +1,14 @@
 //! Low-level or primitive data types for FBX 7.4 and compatible versions.
 
-pub(crate) use self::{
-    array_attribute::{ArrayAttributeEncoding, ArrayAttributeHeader},
-    node_header::NodeHeader,
-    special_attribute::SpecialAttributeHeader,
-};
 pub use self::{
-    attribute::{AttributeType, AttributeValue},
+    array_attribute::ArrayAttributeEncoding,
+    attribute::{type_::AttributeType, value::AttributeValue},
     fbx_footer::FbxFooter,
 };
+pub(crate) use self::{
+    array_attribute::ArrayAttributeHeader, node_header::NodeHeader,
+    special_attribute::SpecialAttributeHeader,
+};
 
 mod array_attribute;
 mod attribute;

src/low/v7400/array_attribute.rs

@@ -28,6 +28,15 @@ impl ArrayAttributeEncoding {
             _ => None,
         }
     }
+
+    /// Returns the raw value.
+    #[cfg(feature = "writer")]
+    pub(crate) fn to_u32(self) -> u32 {
+        match self {
+            ArrayAttributeEncoding::Direct => 0,
+            ArrayAttributeEncoding::Zlib => 1,
+        }
+    }
 }
 
 impl From<ArrayAttributeEncoding> for Compression {

src/low/v7400/attribute.rs

@@ -1,6 +1,4 @@
 //! Node attribute.
 
-pub use self::{type_::AttributeType, value::AttributeValue};
-
-mod type_;
-mod value;
+pub(crate) mod type_;
+pub(crate) mod value;

src/low/v7400/attribute/type_.rs

@@ -55,6 +55,26 @@ impl AttributeType {
             _ => None,
         }
     }
+
+    /// Returns the type code.
+    #[cfg(feature = "writer")]
+    pub(crate) fn type_code(self) -> u8 {
+        match self {
+            AttributeType::Bool => b'C',
+            AttributeType::I16 => b'Y',
+            AttributeType::I32 => b'I',
+            AttributeType::I64 => b'L',
+            AttributeType::F32 => b'F',
+            AttributeType::F64 => b'D',
+            AttributeType::ArrBool => b'b',
+            AttributeType::ArrI32 => b'i',
+            AttributeType::ArrI64 => b'l',
+            AttributeType::ArrF32 => b'f',
+            AttributeType::ArrF64 => b'd',
+            AttributeType::Binary => b'R',
+            AttributeType::String => b'S',
+        }
+    }
 }
 
 impl FromReader for AttributeType {

src/low/v7400/attribute/value.rs

@@ -13,7 +13,9 @@ use crate::low::v7400::AttributeType;
 /// * `get_*_or_type()` returns `Result<_, AttributeType>`.
 ///     + If a value of the expected type available, returns `Ok(_)`.
 ///     + If not, returns `Ok(ty)` where `ty` is value type (same value as
-///       returned by `type_()`.
+///       returned by [`type_()`][`type_`].
+///
+/// [`type_`]: #method.type_
 #[derive(Debug, Clone, PartialEq)]
 pub enum AttributeValue {
     /// Single `bool`.
@@ -220,4 +222,72 @@ impl AttributeValue {
         get_binary_or_type,
         "Returns the reference to the inner binary data, if available.\n\nReturns `Err(type)` on type mismatch.",
     }
+
+    /// Compares attribute values strictly.
+    ///
+    /// "Strictly" means, `f32` and `f64` values are compared bitwise.
+    pub fn strict_eq(&self, other: &Self) -> bool {
+        use AttributeValue::*;
+
+        match (self, other) {
+            (Bool(l), Bool(r)) => l == r,
+            (I16(l), I16(r)) => l == r,
+            (I32(l), I32(r)) => l == r,
+            (I64(l), I64(r)) => l == r,
+            (F32(l), F32(r)) => l.to_bits() == r.to_bits(),
+            (F64(l), F64(r)) => l.to_bits() == r.to_bits(),
+            (ArrBool(l), ArrBool(r)) => l == r,
+            (ArrI32(l), ArrI32(r)) => l == r,
+            (ArrI64(l), ArrI64(r)) => l == r,
+            (ArrF32(l), ArrF32(r)) => l
+                .iter()
+                .map(|v| v.to_bits())
+                .eq(r.iter().map(|v| v.to_bits())),
+            (ArrF64(l), ArrF64(r)) => l
+                .iter()
+                .map(|v| v.to_bits())
+                .eq(r.iter().map(|v| v.to_bits())),
+            (Binary(l), Binary(r)) => l == r,
+            (String(l), String(r)) => l == r,
+            _ => false,
+        }
+    }
+}
+
+macro_rules! impl_from {
+    (direct: $ty:ty, $variant:ident) => {
+        impl From<$ty> for AttributeValue {
+            fn from(v: $ty) -> Self {
+                AttributeValue::$variant(v.into())
+            }
+        }
+    };
+    (map: $ty:ty, $variant:ident, $arg:ident, $v:expr) => {
+        impl From<$ty> for AttributeValue {
+            fn from($arg: $ty) -> Self {
+                AttributeValue::$variant($v)
+            }
+        }
+    };
 }
+
+impl_from! { direct: bool, Bool }
+impl_from! { direct: i16, I16 }
+impl_from! { direct: i32, I32 }
+impl_from! { direct: i64, I64 }
+impl_from! { direct: f32, F32 }
+impl_from! { direct: f64, F64 }
+impl_from! { direct: Vec<bool>, ArrBool }
+impl_from! { direct: Vec<i32>, ArrI32 }
+impl_from! { direct: Vec<i64>, ArrI64 }
+impl_from! { direct: Vec<f32>, ArrF32 }
+impl_from! { direct: Vec<f64>, ArrF64 }
+impl_from! { direct: Vec<u8>, Binary }
+impl_from! { direct: String, String }
+impl_from! { map: &[bool], ArrBool, v, v.to_owned() }
+impl_from! { map: &[i32], ArrI32, v, v.to_owned() }
+impl_from! { map: &[i64], ArrI64, v, v.to_owned() }
+impl_from! { map: &[f32], ArrF32, v, v.to_owned() }
+impl_from! { map: &[f64], ArrF64, v, v.to_owned() }
+impl_from! { map: &[u8], Binary, v, v.to_owned() }
+impl_from! { map: &str, String, v, v.to_owned() }

src/low/v7400/node_header.rs

@@ -26,6 +26,17 @@ impl NodeHeader {
             && self.bytelen_attributes == 0
             && self.bytelen_name == 0
     }
+
+    /// Returns node end marker.
+    #[cfg(feature = "writer")]
+    pub(crate) fn node_end() -> Self {
+        Self {
+            end_offset: 0,
+            num_attributes: 0,
+            bytelen_attributes: 0,
+            bytelen_name: 0,
+        }
+    }
 }
 
 impl FromParser for NodeHeader {

src/low/version.rs

@@ -5,6 +5,12 @@
 pub struct FbxVersion(u32);
 
 impl FbxVersion {
+    /// Version 7.4.
+    pub const V7_4: Self = FbxVersion(7400);
+
+    /// Version 7.5.
+    pub const V7_5: Self = FbxVersion(7500);
+
     /// Creates a new `FbxVersion`.
     pub(crate) fn new(version: u32) -> Self {
         FbxVersion(version)