Skip to main content

opensubdiv_rs/far/
primvar_refiner.rs

1//! Primvar interpolation between refinement levels and onto the limit
2//! surface (port of `opensubdiv/far/primvarRefiner.h`).
3
4use super::topology_refiner::TopologyRefiner;
5use crate::sdc::{
6    Crease, EdgeNeighborhood, EdgeVertexMask, Scheme, Split, VertexNeighborhood, VertexVertexMask,
7};
8use crate::vtr::{Level, Refinement};
9use crate::{Index, INDEX_INVALID};
10use std::borrow::Cow;
11
12/// Interface for primvar data interpolated by [`PrimvarRefiner`].
13///
14/// This is the Rust equivalent of the duck-typed `Clear()` /
15/// `AddWithWeight()` protocol used throughout OpenSubdiv's Far layer.
16pub trait Primvar: Clone {
17    /// Reset the value to zero.
18    fn clear(&mut self);
19    /// Accumulate `src` scaled by `weight`.
20    fn add_with_weight(&mut self, src: &Self, weight: f32);
21}
22
23impl Primvar for f32 {
24    fn clear(&mut self) {
25        *self = 0.0;
26    }
27    fn add_with_weight(&mut self, src: &Self, weight: f32) {
28        *self += src * weight;
29    }
30}
31
32impl Primvar for f64 {
33    fn clear(&mut self) {
34        *self = 0.0;
35    }
36    fn add_with_weight(&mut self, src: &Self, weight: f32) {
37        *self += src * weight as f64;
38    }
39}
40
41impl<const N: usize> Primvar for [f32; N] {
42    fn clear(&mut self) {
43        *self = [0.0; N];
44    }
45    fn add_with_weight(&mut self, src: &Self, weight: f32) {
46        for (d, s) in self.iter_mut().zip(src) {
47            *d += s * weight;
48        }
49    }
50}
51
52impl<const N: usize> Primvar for [f64; N] {
53    fn clear(&mut self) {
54        *self = [0.0; N];
55    }
56    fn add_with_weight(&mut self, src: &Self, weight: f32) {
57        for (d, s) in self.iter_mut().zip(src) {
58            *d += s * weight as f64;
59        }
60    }
61}
62
63/// Applies refinement operations to generic primvar data
64/// (`Far::PrimvarRefiner`).
65pub struct PrimvarRefiner<'a> {
66    refiner: &'a TopologyRefiner,
67}
68
69impl<'a> PrimvarRefiner<'a> {
70    /// Create a primvar refiner driven by the topology of `refiner`.
71    pub fn new(refiner: &'a TopologyRefiner) -> Self {
72        Self { refiner }
73    }
74
75    /// The refiner this primvar refiner was created with
76    /// (`GetTopologyRefiner`).
77    pub fn topology_refiner(&self) -> &TopologyRefiner {
78        self.refiner
79    }
80
81    /// Apply vertex interpolation weights to a primvar buffer for a single
82    /// level of refinement (`PrimvarRefiner::Interpolate`).
83    ///
84    /// `src` holds one value per vertex of level `level - 1`; `dst` receives
85    /// one value per vertex of level `level`.
86    ///
87    /// # Panics
88    /// Panics if `level` is zero or exceeds the refiner's
89    /// [max level](TopologyRefiner::max_level), or if the buffers are too
90    /// small.
91    pub fn interpolate<T: Primvar>(&self, level: usize, src: &[T], dst: &mut [T]) {
92        assert!(
93            level >= 1 && level <= self.refiner.max_level(),
94            "level {level} out of range 1..={}",
95            self.refiner.max_level()
96        );
97        interpolate_level(
98            self.refiner.scheme(),
99            false,
100            self.refiner.level(level - 1).inner(),
101            self.refiner.level(level).inner(),
102            self.refiner.refinement(level),
103            src,
104            dst,
105        );
106    }
107
108    /// Apply face-varying interpolation weights to a primvar buffer for a
109    /// single level of refinement
110    /// (`PrimvarRefiner::InterpolateFaceVarying`).
111    ///
112    /// `src` holds one value per face-varying *value* of `channel` at level
113    /// `level - 1`; `dst` receives one value per face-varying value at level
114    /// `level` (see
115    /// [`TopologyLevel::num_fvar_values`](super::TopologyLevel::num_fvar_values)).
116    pub fn interpolate_face_varying<T: Primvar>(
117        &self,
118        level: usize,
119        channel: usize,
120        src: &[T],
121        dst: &mut [T],
122    ) {
123        assert!(
124            level >= 1 && level <= self.refiner.max_level(),
125            "level {level} out of range 1..={}",
126            self.refiner.max_level()
127        );
128        let fvar = self.refiner.fvar_channel(channel);
129        // Base-level values are the caller's; the value mesh may split an
130        // index reused at several vertices into several values.
131        let src = if level == 1 {
132            fvar.base_source_values(src)
133        } else {
134            Cow::Borrowed(src)
135        };
136        interpolate_level(
137            fvar.scheme(),
138            fvar.is_linear(),
139            fvar.level(level - 1),
140            fvar.level(level),
141            fvar.refinement(level),
142            &src,
143            dst,
144        );
145    }
146
147    /// Interpolate the whole hierarchy in one call: `base` holds one value
148    /// per base-level (level 0) vertex, and one buffer per refined level is
149    /// returned. A convenience not present in OpenSubdiv, where clients loop
150    /// over `Interpolate(level, src, dst)` themselves.
151    pub fn interpolate_all<T: Primvar + Default>(&self, base: &[T]) -> Vec<Vec<T>> {
152        let mut levels = Vec::with_capacity(self.refiner.max_level());
153        let mut src = base.to_vec();
154        for level in 1..=self.refiner.max_level() {
155            let mut dst = vec![T::default(); self.refiner.level(level).num_vertices()];
156            self.interpolate(level, &src, &mut dst);
157            src.clone_from(&dst);
158            levels.push(dst);
159        }
160        levels
161    }
162
163    /// Interpolate face-varying `channel` through the whole hierarchy in one
164    /// call: `base` holds one value per base-level value of the channel, and
165    /// one buffer per refined level is returned — the face-varying
166    /// counterpart of [`interpolate_all`](Self::interpolate_all). Appended
167    /// to `base`, they form the values
168    /// [`PatchTable::evaluate_face_varying`](super::PatchTable::evaluate_face_varying)
169    /// expects.
170    pub fn interpolate_face_varying_all<T: Primvar + Default>(
171        &self,
172        channel: usize,
173        base: &[T],
174    ) -> Vec<Vec<T>> {
175        let mut levels = Vec::with_capacity(self.refiner.max_level());
176        let mut src = base.to_vec();
177        for level in 1..=self.refiner.max_level() {
178            let mut dst = vec![T::default(); self.refiner.level(level).num_fvar_values(channel)];
179            self.interpolate_face_varying(level, channel, &src, &mut dst);
180            src.clone_from(&dst);
181            levels.push(dst);
182        }
183        levels
184    }
185
186    /// Apply *limit* weights to a primvar buffer (`PrimvarRefiner::Limit`):
187    /// `src` holds one value per vertex of the refiner's last level, and
188    /// `dst` receives the limit-surface position of each of those vertices.
189    ///
190    /// As in OpenSubdiv, evaluating the limit requires the neighborhood of
191    /// every vertex to be "regularized" with respect to face size: for the
192    /// Catmark scheme with non-quad base faces, refine at least once before
193    /// calling this.
194    pub fn limit<T: Primvar>(&self, src: &[T], dst: &mut [T]) {
195        assert!(
196            !self.refiner.is_adaptive(),
197            "Limit requires uniform refinement; evaluate adaptive refiners through a PatchTable or LimitStencilTable"
198        );
199        limit_level(
200            self.refiner.scheme(),
201            false,
202            self.refiner.level(self.refiner.max_level()).inner(),
203            src,
204            dst,
205        );
206    }
207
208    /// Apply face-varying *limit* weights to a primvar buffer
209    /// (`PrimvarRefiner::LimitFaceVarying`): `src` holds one value per
210    /// face-varying value of `channel` at the refiner's last level.
211    pub fn limit_face_varying<T: Primvar>(&self, channel: usize, src: &[T], dst: &mut [T]) {
212        assert!(
213            !self.refiner.is_adaptive(),
214            "Limit requires uniform refinement; evaluate adaptive refiners through a PatchTable or LimitStencilTable"
215        );
216        let fvar = self.refiner.fvar_channel(channel);
217        let max_level = self.refiner.max_level();
218        let src = if max_level == 0 {
219            fvar.base_source_values(src)
220        } else {
221            Cow::Borrowed(src)
222        };
223        limit_level(
224            fvar.scheme(),
225            fvar.is_linear(),
226            fvar.level(max_level),
227            &src,
228            dst,
229        );
230    }
231}
232
233// ----------------------------------------------------------------------
234//  Level-to-level interpolation (PrimvarRefiner::interpChildVertsFrom*)
235//
236//  These are parameterized over the scheme and the level pair so that the
237//  same passes serve both vertex data (the geometry levels) and
238//  face-varying data (a channel's value-mesh levels). `linear` selects the
239//  purely linear masks used for FVarLinearInterpolation::All.
240// ----------------------------------------------------------------------
241
242fn interpolate_level<T: Primvar>(
243    scheme: &Scheme,
244    linear: bool,
245    parent: &Level,
246    child: &Level,
247    refinement: &Refinement,
248    src: &[T],
249    dst: &mut [T],
250) {
251    assert!(src.len() >= parent.num_vertices(), "src buffer too small");
252    assert!(dst.len() >= child.num_vertices(), "dst buffer too small");
253    interpolate_child_verts_from_faces(scheme, refinement, parent, src, dst);
254    interpolate_child_verts_from_edges(scheme, linear, refinement, parent, src, dst);
255    interpolate_child_verts_from_verts(scheme, linear, refinement, parent, src, dst);
256}
257
258fn interpolate_child_verts_from_faces<T: Primvar>(
259    scheme: &Scheme,
260    refinement: &Refinement,
261    parent: &Level,
262    src: &[T],
263    dst: &mut [T],
264) {
265    if refinement.split() == Split::ToTris {
266        return; // Triangular splits generate no face child-vertices.
267    }
268    for f in 0..parent.num_faces() {
269        let cv = refinement.face_child_vertex(f);
270        if cv == INDEX_INVALID {
271            continue; // not refined (sparse refinement)
272        }
273        let fv = parent.face_vertices(f);
274        // The face mask is the centroid for linear and smooth schemes alike.
275        let mask = scheme.compute_face_vertex_mask(fv.len());
276
277        let mut acc = src[fv[0] as usize].clone();
278        acc.clear();
279        for &v in fv {
280            acc.add_with_weight(&src[v as usize], mask.vertex_weight);
281        }
282        dst[cv as usize] = acc;
283    }
284}
285
286fn interpolate_child_verts_from_edges<T: Primvar>(
287    scheme: &Scheme,
288    linear: bool,
289    refinement: &Refinement,
290    parent: &Level,
291    src: &[T],
292    dst: &mut [T],
293) {
294    let mut mask = EdgeVertexMask::default();
295
296    for e in 0..parent.num_edges() {
297        let ecv = refinement.edge_child_vertex(e);
298        if ecv == INDEX_INVALID {
299            continue; // not refined (sparse refinement)
300        }
301        let [v0, v1] = parent.edge_vertices(e);
302        let mut acc = src[v0 as usize].clone();
303        acc.clear();
304
305        let edge_faces = parent.edge_faces(e);
306        // A fringe edge of a sparse refinement can be missing the face
307        // child-vertices its smooth mask references; such vertices only
308        // support the region and are never used by patches, so a crease
309        // (midpoint) fallback suffices.
310        let incomplete = edge_faces
311            .iter()
312            .any(|&f| refinement.face_child_vertex(f as usize) == INDEX_INVALID)
313            && refinement.split() == Split::ToQuads;
314
315        if linear || incomplete {
316            acc.add_with_weight(&src[v0 as usize], 0.5);
317            acc.add_with_weight(&src[v1 as usize], 0.5);
318            dst[ecv as usize] = acc;
319            continue;
320        }
321
322        // The Catmark smooth-triangle rule (`TriangleSubdivision::Smooth`)
323        // weights an edge differently when a triangle is on either side.
324        let face_size = |i: usize| {
325            edge_faces
326                .get(i)
327                .map_or(0, |&f| parent.face_vertices(f as usize).len())
328        };
329        scheme.compute_edge_vertex_mask(
330            &EdgeNeighborhood {
331                sharpness: parent.edge_sharpness(e),
332                num_faces: edge_faces.len(),
333                face_vertex_counts: [face_size(0), face_size(1)],
334            },
335            &mut mask,
336        );
337
338        acc.add_with_weight(&src[v0 as usize], mask.vertex_weights[0]);
339        acc.add_with_weight(&src[v1 as usize], mask.vertex_weights[1]);
340
341        for (&f, &w) in edge_faces.iter().zip(&mask.face_weights) {
342            if w == 0.0 {
343                continue;
344            }
345            if mask.face_weights_for_face_centers {
346                // Catmark: weight the child vertex at the face center,
347                // already computed in the face pass.
348                let fcv = refinement.face_child_vertex(f as usize) as usize;
349                let value = dst[fcv].clone();
350                acc.add_with_weight(&value, w);
351            } else {
352                // Loop: weight the vertex of the face opposite the edge.
353                let opposite = tri_vertex_opposite_edge(parent, f as usize, [v0, v1]);
354                acc.add_with_weight(&src[opposite as usize], w);
355            }
356        }
357        dst[ecv as usize] = acc;
358    }
359}
360
361fn interpolate_child_verts_from_verts<T: Primvar>(
362    scheme: &Scheme,
363    linear: bool,
364    refinement: &Refinement,
365    parent: &Level,
366    src: &[T],
367    dst: &mut [T],
368) {
369    let crease = scheme.crease();
370    let mut mask = VertexVertexMask::default();
371    let mut edge_sharpness = Vec::new();
372    let mut child_edge_sharpness = Vec::new();
373
374    for v in 0..parent.num_vertices() {
375        let cv = refinement.vertex_child_vertex(v);
376        if cv == INDEX_INVALID {
377            continue; // not refined (sparse refinement)
378        }
379
380        // A fringe vertex of a sparse quad refinement can be missing the
381        // face child-vertices its smooth mask references; its child only
382        // supports the region and is never used by patches, so carrying the
383        // parent value suffices. Triangular masks reference parent vertices
384        // only, so they are always complete.
385        let incomplete = refinement.split() == Split::ToQuads
386            && parent
387                .vertex_faces(v)
388                .iter()
389                .any(|&f| refinement.face_child_vertex(f as usize) == INDEX_INVALID);
390
391        if linear || incomplete {
392            dst[cv as usize] = src[v].clone();
393            continue;
394        }
395
396        // Gather the parent-level sharpness of the incident edges, and
397        // derive the child-level sharpness directly through the creasing
398        // rules — the same computation the refinement applied, valid even
399        // when child topology is sparse.
400        parent.gather_vertex_edge_sharpness(v, &mut edge_sharpness);
401        child_edge_sharpness.clear();
402        for &sharpness in edge_sharpness.iter() {
403            child_edge_sharpness.push(if Crease::is_sharp(sharpness) {
404                crease.subdivide_edge_sharpness_at_vertex(sharpness, &edge_sharpness)
405            } else {
406                0.0
407            });
408        }
409
410        let neighborhood = VertexNeighborhood {
411            sharpness: parent.vertex_sharpness(v),
412            child_sharpness: crease.subdivide_vertex_sharpness(parent.vertex_sharpness(v)),
413            edge_sharpness: &edge_sharpness,
414            child_edge_sharpness: &child_edge_sharpness,
415            num_faces: parent.vertex_faces(v).len(),
416        };
417        scheme.compute_vertex_vertex_mask(&neighborhood, &mut mask);
418
419        let mut acc = src[v].clone();
420        acc.clear();
421        acc.add_with_weight(&src[v], mask.vertex_weight);
422        for (&e, &w) in parent.vertex_edges(v).iter().zip(&mask.edge_weights) {
423            if w != 0.0 {
424                let opposite = parent.edge_opposite_vertex(e as usize, v as Index);
425                acc.add_with_weight(&src[opposite as usize], w);
426            }
427        }
428        if !mask.face_weights.is_empty() {
429            debug_assert!(mask.face_weights_for_face_centers);
430            for (&f, &w) in parent.vertex_faces(v).iter().zip(&mask.face_weights) {
431                if w != 0.0 {
432                    let fcv = refinement.face_child_vertex(f as usize) as usize;
433                    let value = dst[fcv].clone();
434                    acc.add_with_weight(&value, w);
435                }
436            }
437        }
438        dst[cv as usize] = acc;
439    }
440}
441
442// ----------------------------------------------------------------------
443//  Limit evaluation
444// ----------------------------------------------------------------------
445
446fn limit_level<T: Primvar>(scheme: &Scheme, linear: bool, level: &Level, src: &[T], dst: &mut [T]) {
447    assert!(src.len() >= level.num_vertices(), "src buffer too small");
448    assert!(dst.len() >= level.num_vertices(), "dst buffer too small");
449
450    if linear {
451        // The limit of linear interpolation is the data itself.
452        dst[..level.num_vertices()].clone_from_slice(&src[..level.num_vertices()]);
453        return;
454    }
455
456    let mut mask = VertexVertexMask::default();
457    let mut edge_sharpness = Vec::new();
458
459    for v in 0..level.num_vertices() {
460        level.gather_vertex_edge_sharpness(v, &mut edge_sharpness);
461        let neighborhood = VertexNeighborhood {
462            sharpness: level.vertex_sharpness(v),
463            child_sharpness: 0.0,
464            edge_sharpness: &edge_sharpness,
465            child_edge_sharpness: &[],
466            num_faces: level.vertex_faces(v).len(),
467        };
468        scheme.compute_vertex_limit_mask(&neighborhood, &mut mask);
469
470        let mut acc = src[v].clone();
471        acc.clear();
472        acc.add_with_weight(&src[v], mask.vertex_weight);
473        for (&e, &w) in level.vertex_edges(v).iter().zip(&mask.edge_weights) {
474            if w != 0.0 {
475                let opposite = level.edge_opposite_vertex(e as usize, v as Index);
476                acc.add_with_weight(&src[opposite as usize], w);
477            }
478        }
479        if !mask.face_weights.is_empty() {
480            debug_assert!(!mask.face_weights_for_face_centers);
481            for (&f, &w) in level.vertex_faces(v).iter().zip(&mask.face_weights) {
482                if w != 0.0 {
483                    let diagonal = face_vertex_opposite(level, f as usize, v as Index);
484                    acc.add_with_weight(&src[diagonal as usize], w);
485                }
486            }
487        }
488        dst[v] = acc;
489    }
490}
491
492/// The vertex of (triangular) face `face` opposite the edge with end
493/// vertices `edge_verts`.
494fn tri_vertex_opposite_edge(level: &Level, face: usize, edge_verts: [Index; 2]) -> Index {
495    let fv = level.face_vertices(face);
496    debug_assert_eq!(fv.len(), 3);
497    *fv.iter()
498        .find(|&&v| v != edge_verts[0] && v != edge_verts[1])
499        .expect("triangle must have a vertex opposite each edge")
500}
501
502/// The vertex of (quad) face `face` diagonally opposite `vertex`.
503fn face_vertex_opposite(level: &Level, face: usize, vertex: Index) -> Index {
504    let fv = level.face_vertices(face);
505    debug_assert_eq!(
506        fv.len(),
507        4,
508        "limit masks with face weights require quad neighborhoods; refine at least once"
509    );
510    let i = fv
511        .iter()
512        .position(|&v| v == vertex)
513        .expect("vertex must belong to its incident face");
514    fv[(i + 2) % fv.len()]
515}