Skip to main content

opensubdiv_rs/
lib.rs

1//! # opensubdiv-rs
2//!
3//! A faithful Rust port of [Pixar's OpenSubdiv](https://github.com/PixarAnimationStudios/OpenSubdiv)
4//! subdivision-surface library.
5//!
6//! The port mirrors OpenSubdiv's layered architecture:
7//!
8//! * [`sdc`] — *Subdivision Core*: the lowest layer. Defines the subdivision
9//!   schemes ([Bilinear](sdc::SchemeType::Bilinear), [Catmark](sdc::SchemeType::Catmark),
10//!   [Loop](sdc::SchemeType::Loop)), the standard set of subdivision
11//!   [options](sdc::Options), the semi-sharp creasing rules ([`sdc::Crease`])
12//!   and the scheme-specific subdivision/limit *masks* (stencil weights).
13//! * [`vtr`] — *Vectorized Topology Representation*: intermediate topology
14//!   representation. A [`vtr::Level`] stores the complete topology of a mesh at
15//!   a refinement level as flat index arrays, and a [`vtr::Refinement`] maps a
16//!   parent level to its uniformly refined child level.
17//! * [`far`] — *Feature Adaptive Representation*: the public client-facing
18//!   layer. A [`far::TopologyRefiner`] is built from a
19//!   [`far::TopologyDescriptor`] via [`far::TopologyRefinerFactory`], refined
20//!   with [`far::TopologyRefiner::refine_uniform`], and primvar data is
21//!   interpolated between levels (and onto the limit surface) with a
22//!   [`far::PrimvarRefiner`].
23//! * [`osd`] — the backend-independent part of OpenSubdiv's GPU layer: a
24//!   [`far::PatchTable`] flattened into the buffers a GPU kernel reads
25//!   ([`osd::GpuPatchTable`]), and the patch basis those kernels evaluate
26//!   ([`osd::evaluate_patch_basis`]). It has no GPU dependency; any API can
27//!   upload the buffers.
28//!
29//! ## Example
30//!
31//! Uniformly subdivide a cube (the equivalent of OpenSubdiv's
32//! `far_tutorial_1_1`):
33//!
34//! ```
35//! use opensubdiv_rs::far::{
36//!     PrimvarRefiner, TopologyDescriptor, TopologyRefinerFactory, UniformOptions,
37//! };
38//! use opensubdiv_rs::sdc;
39//!
40//! let verts_per_face = [4usize; 6];
41//! let face_verts: [u32; 24] = [
42//!     0, 1, 3, 2, 2, 3, 5, 4, 4, 5, 7, 6,
43//!     6, 7, 1, 0, 1, 7, 5, 3, 6, 0, 2, 4,
44//! ];
45//! let positions: [[f32; 3]; 8] = [
46//!     [-0.5, -0.5,  0.5], [ 0.5, -0.5,  0.5],
47//!     [-0.5,  0.5,  0.5], [ 0.5,  0.5,  0.5],
48//!     [-0.5,  0.5, -0.5], [ 0.5,  0.5, -0.5],
49//!     [-0.5, -0.5, -0.5], [ 0.5, -0.5, -0.5],
50//! ];
51//!
52//! let descriptor = TopologyDescriptor::new(8, &verts_per_face, &face_verts);
53//! let mut refiner = TopologyRefinerFactory::create(
54//!     descriptor,
55//!     sdc::SchemeType::Catmark,
56//!     sdc::Options::default(),
57//! )
58//! .unwrap();
59//! refiner.refine_uniform(UniformOptions::new(2));
60//!
61//! // Interpolate the positions up to the last refinement level.
62//! let primvar_refiner = PrimvarRefiner::new(&refiner);
63//! let mut src = positions.to_vec();
64//! for level in 1..=refiner.max_level() {
65//!     let mut dst = vec![[0.0f32; 3]; refiner.level(level).num_vertices()];
66//!     primvar_refiner.interpolate(level, &src, &mut dst);
67//!     src = dst;
68//! }
69//! assert_eq!(src.len(), 98);
70//! ```
71//!
72//! ## Fidelity notes
73//!
74//! The subdivision rules (smooth / crease / corner masks, semi-sharp
75//! fractional blending, `Uniform` and `Chaikin` crease subdivision, boundary
76//! interpolation modes and limit masks) follow the reference implementation in
77//! OpenSubdiv's `opensubdiv/sdc/*Scheme.h` and `opensubdiv/sdc/crease.{h,cpp}`.
78//! Refined topology is identical in structure to OpenSubdiv's, though the
79//! numbering of edges (and hence of edge child-vertices) may differ, as it
80//! depends on traversal order internals.
81//!
82//! Face-varying channels (UVs with seams, all `FVarLinearInterpolation`
83//! rules), stencil tables ([`far::StencilTable`], for uniform and adaptive
84//! hierarchies, and [`far::LimitStencilTable`], evaluating the limit
85//! surface at arbitrary parametric locations from the base cage), patch tables
86//! ([`far::PatchTable`], for parametric limit evaluation with derivatives:
87//! B-spline patches and Gregory end caps for Catmark, box-spline patches
88//! and Gregory triangles for Loop, at extraordinary vertices and on
89//! irregular boundaries and infinitely sharp creases) and
90//! feature-adaptive refinement
91//! ([`far::TopologyRefiner::refine_adaptive`], for both schemes, with
92//! sparse levels, mixed-depth patches and optional single-crease patches
93//! for semi-sharp creases, restricted to selected faces if wanted with
94//! [`far::TopologyRefiner::refine_adaptive_selected`] and
95//! [`far::PatchTableFactory::create_with_options_selected`]) are supported,
96//! and so are the flat tables a GPU evaluator consumes ([`osd`]). Not yet
97//! ported: OpenSubdiv's per-API GPU back-ends themselves. See the project
98//! README for the roadmap.
99
100#![forbid(unsafe_code)]
101#![warn(missing_docs)]
102#![deny(rustdoc::broken_intra_doc_links)]
103
104pub mod far;
105pub mod osd;
106pub mod sdc;
107pub mod vtr;
108
109/// The type used for all topological indices (vertices, edges, faces).
110///
111/// Mirrors `OpenSubdiv::Far::Index` / `Vtr::Index` (a 32-bit integer).
112pub type Index = u32;
113
114/// Sentinel for an invalid/absent index (`Vtr::INDEX_INVALID`).
115pub const INDEX_INVALID: Index = u32::MAX;
116
117/// The type used for small per-component local indices
118/// (`Vtr::LocalIndex`).
119pub type LocalIndex = u16;