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
//! # opensubdiv-rs
//!
//! A faithful Rust port of [Pixar's OpenSubdiv](https://github.com/PixarAnimationStudios/OpenSubdiv)
//! subdivision-surface library.
//!
//! The port mirrors OpenSubdiv's layered architecture:
//!
//! * [`sdc`] — *Subdivision Core*: the lowest layer. Defines the subdivision
//! schemes ([Bilinear](sdc::SchemeType::Bilinear), [Catmark](sdc::SchemeType::Catmark),
//! [Loop](sdc::SchemeType::Loop)), the standard set of subdivision
//! [options](sdc::Options), the semi-sharp creasing rules ([`sdc::Crease`])
//! and the scheme-specific subdivision/limit *masks* (stencil weights).
//! * [`vtr`] — *Vectorized Topology Representation*: intermediate topology
//! representation. A [`vtr::Level`] stores the complete topology of a mesh at
//! a refinement level as flat index arrays, and a [`vtr::Refinement`] maps a
//! parent level to its uniformly refined child level.
//! * [`far`] — *Feature Adaptive Representation*: the public client-facing
//! layer. A [`far::TopologyRefiner`] is built from a
//! [`far::TopologyDescriptor`] via [`far::TopologyRefinerFactory`], refined
//! with [`far::TopologyRefiner::refine_uniform`], and primvar data is
//! interpolated between levels (and onto the limit surface) with a
//! [`far::PrimvarRefiner`].
//! * [`osd`] — the backend-independent part of OpenSubdiv's GPU layer: a
//! [`far::PatchTable`] flattened into the buffers a GPU kernel reads
//! ([`osd::GpuPatchTable`]), and the patch basis those kernels evaluate
//! ([`osd::evaluate_patch_basis`]). It has no GPU dependency; any API can
//! upload the buffers.
//!
//! ## Example
//!
//! Uniformly subdivide a cube (the equivalent of OpenSubdiv's
//! `far_tutorial_1_1`):
//!
//! ```
//! use opensubdiv_rs::far::{
//! PrimvarRefiner, TopologyDescriptor, TopologyRefinerFactory, UniformOptions,
//! };
//! use opensubdiv_rs::sdc;
//!
//! let verts_per_face = [4usize; 6];
//! let face_verts: [u32; 24] = [
//! 0, 1, 3, 2, 2, 3, 5, 4, 4, 5, 7, 6,
//! 6, 7, 1, 0, 1, 7, 5, 3, 6, 0, 2, 4,
//! ];
//! let positions: [[f32; 3]; 8] = [
//! [-0.5, -0.5, 0.5], [ 0.5, -0.5, 0.5],
//! [-0.5, 0.5, 0.5], [ 0.5, 0.5, 0.5],
//! [-0.5, 0.5, -0.5], [ 0.5, 0.5, -0.5],
//! [-0.5, -0.5, -0.5], [ 0.5, -0.5, -0.5],
//! ];
//!
//! let descriptor = TopologyDescriptor::new(8, &verts_per_face, &face_verts);
//! let mut refiner = TopologyRefinerFactory::create(
//! descriptor,
//! sdc::SchemeType::Catmark,
//! sdc::Options::default(),
//! )
//! .unwrap();
//! refiner.refine_uniform(UniformOptions::new(2));
//!
//! // Interpolate the positions up to the last refinement level.
//! let primvar_refiner = PrimvarRefiner::new(&refiner);
//! let mut src = positions.to_vec();
//! for level in 1..=refiner.max_level() {
//! let mut dst = vec![[0.0f32; 3]; refiner.level(level).num_vertices()];
//! primvar_refiner.interpolate(level, &src, &mut dst);
//! src = dst;
//! }
//! assert_eq!(src.len(), 98);
//! ```
//!
//! ## Fidelity notes
//!
//! The subdivision rules (smooth / crease / corner masks, semi-sharp
//! fractional blending, `Uniform` and `Chaikin` crease subdivision, boundary
//! interpolation modes and limit masks) follow the reference implementation in
//! OpenSubdiv's `opensubdiv/sdc/*Scheme.h` and `opensubdiv/sdc/crease.{h,cpp}`.
//! Refined topology is identical in structure to OpenSubdiv's, though the
//! numbering of edges (and hence of edge child-vertices) may differ, as it
//! depends on traversal order internals.
//!
//! Face-varying channels (UVs with seams, all `FVarLinearInterpolation`
//! rules), stencil tables ([`far::StencilTable`], for uniform and adaptive
//! hierarchies, and [`far::LimitStencilTable`], evaluating the limit
//! surface at arbitrary parametric locations from the base cage), patch tables
//! ([`far::PatchTable`], for parametric limit evaluation with derivatives:
//! B-spline patches and Gregory end caps for Catmark, box-spline patches
//! and Gregory triangles for Loop, at extraordinary vertices and on
//! irregular boundaries and infinitely sharp creases) and
//! feature-adaptive refinement
//! ([`far::TopologyRefiner::refine_adaptive`], for both schemes, with
//! sparse levels, mixed-depth patches and optional single-crease patches
//! for semi-sharp creases, restricted to selected faces if wanted with
//! [`far::TopologyRefiner::refine_adaptive_selected`] and
//! [`far::PatchTableFactory::create_with_options_selected`]) are supported,
//! and so are the flat tables a GPU evaluator consumes ([`osd`]). Not yet
//! ported: OpenSubdiv's per-API GPU back-ends themselves. See the project
//! README for the roadmap.
/// The type used for all topological indices (vertices, edges, faces).
///
/// Mirrors `OpenSubdiv::Far::Index` / `Vtr::Index` (a 32-bit integer).
pub type Index = u32;
/// Sentinel for an invalid/absent index (`Vtr::INDEX_INVALID`).
pub const INDEX_INVALID: Index = u32MAX;
/// The type used for small per-component local indices
/// (`Vtr::LocalIndex`).
pub type LocalIndex = u16;