natnet 0.1.0

OptiTrack NatNet protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

//! NatNet bitstream versions and supported layout selection.

use crate::{Error, Result};

/// Validation of otherwise bounded, structurally decodable input.
///
/// Both policies tolerate the NatNet outer header's telemetry-only size and
/// preserve explicitly opaque extensions. Strict decoding additionally rejects
/// negative raw counts, a nonzero frame terminator and unexplained residue.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub enum ParsePolicy {
    /// Reject invalid counts, terminators and unexplained trailing bytes.
    #[default]
    Strict,
    /// Preserve extension tolerance for compatible decoding.
    Compatible,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Layout {
    Legacy3,
    Legacy4,
    V4_1,
}

impl Layout {
    pub(crate) fn has_section_sizes(self) -> bool {
        self == Self::V4_1
    }

    pub(crate) fn has_assets(self) -> bool {
        self == Self::V4_1
    }

    pub(crate) fn has_precision(self) -> bool {
        self == Self::V4_1
    }

    pub(crate) fn rigid_body_marker_names(self) -> bool {
        self != Self::Legacy3
    }
}

/// A four-part version quadruple `major.minor.build.revision`.
///
/// SERVERINFO carries the protocol version as four bitstream bytes, such as
/// `04 01 00 00` for 4.1.0.0. The same type represents application versions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Version {
    /// Major version.
    pub major: u8,
    /// Minor version.
    pub minor: u8,
    /// Build number.
    pub build: u8,
    /// Revision.
    pub revision: u8,
}

impl Version {
    /// NatNet protocol version 4.1.0.0.
    pub const V4_1: Self = Self::new(4, 1, 0, 0);

    /// Verifies that the major/minor pair names a supported wire layout.
    ///
    /// Build and revision are retained as provenance; supported layouts use
    /// the vendor sample's major/minor field selection.
    ///
    /// # Errors
    /// Returns [`Error::UnsupportedVersion`] for an unlisted layout.
    pub fn validate(self) -> Result<()> {
        self.layout().map(|_| ())
    }

    pub(crate) fn layout(self) -> Result<Layout> {
        match (self.major, self.minor) {
            (3, 0 | 1) => Ok(Layout::Legacy3),
            (4, 0) => Ok(Layout::Legacy4),
            (4, 1) => Ok(Layout::V4_1),
            _ => Err(Error::UnsupportedVersion {
                major: self.major,
                minor: self.minor,
            }),
        }
    }

    /// Builds a version from its four parts.
    #[must_use]
    pub const fn new(major: u8, minor: u8, build: u8, revision: u8) -> Self {
        Self {
            major,
            minor,
            build,
            revision,
        }
    }

    /// Decodes the four little-endian bitstream bytes as they appear on the
    /// wire (`[major, minor, build, revision]`).
    #[must_use]
    pub const fn from_bytes(b: [u8; 4]) -> Self {
        Self::new(b[0], b[1], b[2], b[3])
    }

    /// The four wire bytes.
    #[must_use]
    pub const fn to_bytes(self) -> [u8; 4] {
        [self.major, self.minor, self.build, self.revision]
    }

    /// Whether this version is at least `major.minor`. This comparison does
    /// not imply that the version is a supported wire layout.
    #[must_use]
    pub const fn at_least(self, major: u8, minor: u8) -> bool {
        self.major > major || (self.major == major && self.minor >= minor)
    }
}

impl core::fmt::Display for Version {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(
            f,
            "{}.{}.{}.{}",
            self.major, self.minor, self.build, self.revision
        )
    }
}