Skip to main content

cadkit_scene/
lib.rs

1//! GPU-free scene data for drawing CAD geometry.
2//!
3//! - [`plan`]: [`Plan2d`], a persistent store of 2D lines, polylines, arcs and circles split
4//!   into fixed-size chunks. Each chunk encodes its curves once into GPU instances
5//!   ([`layout`]) in f32 coordinates relative to the chunk center; every frame checks the
6//!   f32 representation error against a screen-space budget and hands chunks that exceed it
7//!   back to the caller's CPU path.
8//! - [`mesh`]: [`Mesh3d`] triangle meshes in f64 world coordinates and
9//!   [`relative_positions`], the error-checked f64 to f32 conversion for upload.
10//!
11//! The crate knows how to draw, not what the geometry means: callers map their own objects to
12//! [`ObjectId`]s, decide colors and widths, track which objects changed and call
13//! [`Plan2d::upsert`] / [`Plan2d::remove`]. `cadkit-gpu` renders the result with `wgpu`.
14//! Coordinates are in the caller's model units; screen quantities are in logical pixels
15//! unless a name says `physical`.
16//!
17//! ```
18//! use cadkit_geom::{Curve, LineSegment, Point2};
19//! use cadkit_scene::{GroupId, ObjectId, Plan2d, Plan2dOptions, PlanItem, PlanView};
20//! use std::collections::BTreeSet;
21//!
22//! let mut plan = Plan2d::new(Plan2dOptions::new());
23//! let wall = Curve::Line(LineSegment { start: Point2::new(0., 0.), end: Point2::new(5., 0.) });
24//! plan.upsert(ObjectId(1), PlanItem::new(GroupId(0), vec![wall], [40, 40, 40, 255], 1.5));
25//!
26//! let view = PlanView::new(Point2::new(2.5, 0.), 100., [800., 600.], 800.);
27//! plan.prepare(&view, |_| true);
28//! let frame = plan.frame(&view, |_| true, &BTreeSet::new(), true);
29//! assert_eq!(frame.draws.len(), 1);
30//! assert!(frame.cpu.is_empty());
31//! ```
32
33#[cfg(feature = "document")]
34pub mod document;
35pub mod layout;
36pub mod mesh;
37pub mod plan;
38
39pub use mesh::{Mesh3d, MeshBudget, MeshScene, relative_positions};
40pub use plan::{ChunkDraw, Plan2d, Plan2dOptions, PlanFrame, PlanItem, PlanView, curve_bounds};
41
42/// Identifier of one caller object. The caller assigns it; [`Plan2d`] draws objects of a
43/// chunk in ascending id order, so later ids are drawn on top.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
45pub struct ObjectId(pub u64);
46
47/// A group the caller can show or hide per frame without rebuilding, such as a storey or a
48/// sheet. Chunks never mix groups; groups are drawn in ascending id order.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
50pub struct GroupId(pub u32);
51
52/// Why scene data could not be produced.
53#[derive(Debug, Clone, PartialEq, thiserror::Error)]
54#[non_exhaustive]
55pub enum SceneError {
56    /// A caller-supplied budget is not a positive finite number.
57    #[error("invalid {name}: must be positive and finite")]
58    InvalidBudget {
59        /// Name of the parameter.
60        name: &'static str,
61    },
62    /// A coordinate cannot be represented relative to the origin within the error budget.
63    #[error("vertex {vertex} exceeds the f32 precision budget relative to the origin")]
64    Precision {
65        /// Index of the first vertex that failed.
66        vertex: usize,
67    },
68}