molgfx-core 0.3.4

The semantic scene graph: columnar tables, GPU record layouts, the borrowed coordinate seam.
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

//! Declarative visual programs attached to exact generic row domains.

#[cfg(test)]
#[path = "domain_visuals_tests.rs"]
mod tests;

use crate::{
    CoreError, RowDomain, Scene, VisualAttributeRef, VisualCompatibility, VisualDescriptor,
};

impl Scene {
    /// Atomically validates and attaches one generic visual descriptor.
    ///
    /// # Errors
    ///
    /// The domain must be live, every attribute must target that exact domain,
    /// and all outputs must be supported by the drawable family.
    pub fn set_domain_visual(
        &mut self,
        domain: RowDomain,
        descriptor: VisualDescriptor,
    ) -> Result<Option<VisualDescriptor>, CoreError> {
        self.row_count(domain).ok_or(CoreError::StaleHandle)?;
        for reference in descriptor.style().program().attributes() {
            let VisualAttributeRef::Attribute { handle, kind } = *reference else {
                return Err(invalid(
                    "generic domain visuals cannot reference legacy atom properties",
                ));
            };
            let attribute = self.attribute(handle).ok_or(CoreError::StaleHandle)?;
            if attribute.domain() != domain || attribute.kind() != kind {
                return Err(invalid(
                    "visual attributes must target the exact descriptor row domain",
                ));
            }
        }
        descriptor
            .style()
            .program()
            .validate_compatibility(compatibility(domain))
            .map_err(|error| CoreError::InvalidVisual {
                summary: error.to_string(),
            })?;
        let previous = self.domain_visuals.insert(domain, descriptor);
        self.domain_visual_revision = self.domain_visual_revision.wrapping_add(1);
        Ok(previous)
    }

    /// Exact visual descriptor for one generic row domain.
    #[must_use]
    pub fn domain_visual(&self, domain: RowDomain) -> Option<&VisualDescriptor> {
        self.domain_visuals.get(&domain)
    }

    /// Mutable descriptor access with eager revision invalidation.
    pub fn domain_visual_mut(&mut self, domain: RowDomain) -> Option<&mut VisualDescriptor> {
        if !self.domain_visuals.contains_key(&domain) {
            return None;
        }
        self.domain_visual_revision = self.domain_visual_revision.wrapping_add(1);
        self.domain_visuals.get_mut(&domain)
    }

    /// Removes one visual attachment without touching its immutable inputs.
    pub fn remove_domain_visual(&mut self, domain: RowDomain) -> Option<VisualDescriptor> {
        let removed = self.domain_visuals.remove(&domain);
        if removed.is_some() {
            self.domain_visual_revision = self.domain_visual_revision.wrapping_add(1);
        }
        removed
    }

    /// Stable domain-ordered introspection for a future Studio.
    pub fn domain_visuals(&self) -> impl Iterator<Item = (RowDomain, &VisualDescriptor)> + '_ {
        self.domain_visuals
            .iter()
            .map(|(domain, descriptor)| (*domain, descriptor))
    }

    /// Membership, program, parameter or order revision.
    #[must_use]
    pub const fn domain_visual_revision(&self) -> u64 {
        self.domain_visual_revision
    }
}

const fn compatibility(domain: RowDomain) -> VisualCompatibility {
    match domain {
        RowDomain::Points(_) => VisualCompatibility::POINTS,
        RowDomain::Instances(_) | RowDomain::TemplateParts(_) => VisualCompatibility::INSTANCES,
        RowDomain::Relations(_) => VisualCompatibility::RELATIONS,
        RowDomain::Atoms(_) => VisualCompatibility::DEFORMABLE,
    }
}

fn invalid(reason: &'static str) -> CoreError {
    CoreError::InvalidVisual {
        summary: reason.into(),
    }
}