OpenSubdiv-rs
A faithful Rust port of Pixar's OpenSubdiv subdivision-surface library.
OpenSubdiv-rs implements the same subdivision rules as OpenSubdiv — the RenderMan
/ industry-standard semantics for Catmull-Clark and Loop subdivision with
semi-sharp creasing and boundary interpolation — behind an API that mirrors
OpenSubdiv's layered architecture, translated to idiomatic, safe Rust
(no unsafe, no dependencies).
Architecture
The port follows OpenSubdiv's layer structure one-to-one:
| Module | OpenSubdiv layer | Contents |
|---|---|---|
sdc |
opensubdiv/sdc |
Scheme types (Bilinear, Catmark, Loop), subdivision Options, semi-sharp Crease rules (Uniform and Chaikin), and the scheme-specific subdivision & limit masks |
vtr |
opensubdiv/vtr |
Level — flat-array topology of one refinement level (face-verts, face-edges, edge-verts, edge-faces, vert-faces, vert-edges, sharpness, tags); Refinement — one step of uniform or sparse quad/tri refinement |
far |
opensubdiv/far |
TopologyDescriptor, TopologyRefinerFactory, TopologyRefiner / TopologyLevel, PrimvarRefiner (interpolate, interpolate_face_varying, limit, limit_face_varying), StencilTable / StencilTableFactory, LimitStencilTable / LimitStencilTableFactory, and PatchTable / PatchTableFactory / PatchTableOptions / PatchMap / PatchParam / PtexIndices, with face-varying patches |
osd |
opensubdiv/osd (backend-independent part) |
GpuPatchTable — a patch table as flat GPU buffers in OpenSubdiv's layout (PatchArray, packed PatchParam, index buffer, end-cap local-point stencils), PatchCoord, and evaluate_patch_basis, the CPU reference of the patch kernel; no GPU dependency |
Installation
or, in Cargo.toml:
[]
= "0.7"
The crate has no dependencies and contains no unsafe code
(#![forbid(unsafe_code)]).
Usage
The equivalent of OpenSubdiv's far_tutorial_1_1 — uniformly subdivide a cube:
use ;
use sdc;
let verts_per_face = ;
let face_verts: = ;
let positions: = ;
// Describe the topology and build a refiner.
let descriptor = new;
let mut refiner = create
.expect;
// Refine uniformly.
refiner.refine_uniform;
// Interpolate vertex data level by level.
let primvar_refiner = new;
let mut verts = positions.to_vec;
for level in 1..=refiner.max_level
// Evaluate limit-surface positions of the last level.
let mut limits = verts.clone;
primvar_refiner.limit;
Run the ported tutorial, which writes a refined cube as OBJ:
Primvar data is anything implementing the far::Primvar trait (the Rust
equivalent of OpenSubdiv's Clear() / AddWithWeight() protocol); it is
provided out of the box for f32, f64, [f32; N] and [f64; N].
Features
- Schemes: Bilinear, Catmull-Clark (arbitrary n-gons), Loop (triangle meshes)
- Uniform refinement to any depth, with full topology (all component relations) available at every level
- Feature-adaptive refinement (
refine_adaptive), for Catmark and Loop alike: only irregular features — extraordinary vertices, non-quads, semi-sharp creases and irregular infinitely sharp features — are isolated, together with their one-ring support, until they resolve or reach the isolation level. Levels above the base are sparse: memory grows with the mesh's features, not with4^level, while the patch table evaluates the identical limit surface with far fewer patches. WithAdaptiveOptions::with_single_crease_patch(true)(OpenSubdiv'suseSingleCreasePatch), regular faces along a semi-sharp crease are not isolated at all: each becomes one exact single-crease patch carrying the crease's sharpness - Selected faces (
refine_adaptive_selectedandPatchTableFactory::create_with_options_selected, OpenSubdiv'sselectedFaces): isolate features and build patches around chosen base faces only, so a renderer that needs the limit surface of a few faces of a large cage pays for those faces alone. Their patches are the ones a full refinement and a full table give them, evaluating bit-identically;PatchMapfinds no patch elsewhere - Semi-sharp creasing: edge creases and vertex corners with fractional
sharpness,
UniformandChaikincrease subdivision, and the transitional blending of smooth/crease/corner masks across levels - Boundary interpolation:
None,EdgeOnly,EdgeAndCorner - Triangle subdivision for Catmark: the standard weights, or the
"smooth triangle" rule (
TriangleSubdivision::Smooth, OpenSubdiv'sTRI_SUB_SMOOTH, USD'striangleSubdivisionRule = "smooth") - Face-varying channels (UVs, per-corner colors) with seams, refined in
lockstep with the geometry, supporting all
FVarLinearInterpolationrules (All,None,CornersOnly,CornersPlus1,CornersPlus2,Boundaries) and face-varying limit evaluation - Stencil tables (
StencilTable/StencilTableFactory): the whole refinement — or the limit evaluation — factorized into flat per-vertex stencils on the base control vertices, for fast re-posing of animated meshes viaupdate_values; uniform and feature-adaptive hierarchies alike, withStencilTableOptions::for_patch_controlsfilling a patch table's whole control buffer in one pass - Limit stencils (
LimitStencilTable/LimitStencilTableFactory): the limit surface — position and first derivatives — at arbitrary(ptex face, u, v)locations as sparse stencils on the base cage, obtained by factorizing the patch table's basis weights through the control-vertex stencils. One sparse dot product per sample, no per-level buffers, and the stencils are topology-only, so a deforming cage reuses them across frames - Limit-surface evaluation of vertex positions (
PrimvarRefiner::limit), including crease and corner limit rules - Patch tables (
PatchTable/PatchMap/PatchParam/PtexIndices): parametric evaluation of the limit surface — with first derivatives — at arbitrary(ptex face, u, v)locations, supporting mixed-depth (adaptive) hierarchies: each face is patched at the level where it becomes regular. Regular neighborhoods (including sharpened boundaries, pinned corners and infinitely sharp creases, which are treated as boundaries as with OpenSubdiv'suseInfSharpPatch) become exact bicubic B-spline patches; every other face at its isolation level — extraordinary vertices, irregular boundary and crease corners, sharp corners, darts, and faces around non-manifold edges and vertices (infinitely sharp, as in OpenSubdiv) — is capped with a Gregory patch (as OpenSubdiv'sENDCAP_GREGORY_BASIS), interpolating the corner limit points with C0 boundaries and approximate G1 smoothness; only unsharpened (VtxBoundaryInterpolation::None) boundaries fall back to bilinear quads - Loop patches: for the Loop scheme, regular triangles (interior
valence-6 corners, regular boundary and crease vertices, pinned corners)
become exact quartic box-spline patches on 12 control vertices, and
every other face at its isolation level a Gregory triangle end cap
(as OpenSubdiv's
GREGORY_TRIANGLE) on 18 derived points;PatchParamcarries the triangle's parametric sub-domain (including the inverted central children) andPatchMaplocates triangles by ptex face and(u, v) - Face-varying patches (
PatchTableOptions::generate_fvar_tables, OpenSubdiv'sgenerateFVarTables): per channel, one patch for each vertex patch, over the same(ptex face, u, v)domain, evaluated withPatchTable::evaluate_basis_face_varying. Each is built from the channel's own topology at the patch's level, so seams and the channel'sFVarLinearInterpolationhold: linear patches forAll(or for every channel undergenerate_fvar_legacy_linear_patches, on by default as in OpenSubdiv), B-spline or box-spline patches where the channel is regular, and Gregory end caps elsewhere.AdaptiveOptions::consider_fvar_channelsisolates face-varying features as adaptive refinement isolates vertex ones - GPU evaluation data (
osd): every table a GPU renderer's kernels read, as plain arrays for any API (for examplewgpucompute shaders).StencilTable::offsets/indices/weights(and the limit-stencil derivative weights) feed a stencil kernel;GpuPatchTableflattens aPatchTableinto OpenSubdiv's patch-array, index and packed patch-param buffers — rotation applied to the control points, boundary masks for phantom points, single-crease sharpness, non-quad roots — plus the stencils of the Gregory end caps' local points, whichStencilTableFactory::append_local_point_stencilsfolds into the control-vertex stencils so one pass fills the whole patch control buffer.GpuPatchTable::evaluateruns the patch kernel on the CPU from those buffers alone, and is tested againstPatchTable::evaluate. Face-varying patches and transition-edge tags are not exported yet - Hole tags, propagated through refinement
- Topology validation with typed errors (degenerate faces, out-of-range indices, non-triangular meshes for Loop, …)
Fidelity notes
The numerical rules are ported directly from OpenSubdiv's reference
implementation (sdc/catmarkScheme.h, sdc/loopScheme.h, sdc/crease.cpp):
smooth/crease/corner masks, the Warren-Loop vertex weights, the
(n² V + 4 Σ E + Σ D) / (n (n + 5)) Catmark limit stencil, etc. Refined
topology is structurally identical to OpenSubdiv's (child vertices ordered by
parent faces, then edges, then vertices); the numbering of edges — and hence
of edge child-vertices — can differ from OpenSubdiv's, as it depends on
internal traversal order.
The reference version is OpenSubdiv 3.7.0. The test suite compares
Chaikin creasing and face-varying CornersPlus2 results with values computed
by that release; pixi.toml pins it (opensubdiv >=3.7.0,<4) so the
reference data can be regenerated. The other tests check against the classic
Catmull-Clark and Loop rules and against internal consistency (limit stencils,
linear precision, adaptive vs. uniform).
Face-varying channels are represented as OpenSubdiv represents them
conceptually: a channel's values form a mesh of their own in which UV seams
are boundaries, refined with the same machinery as the geometry after
encoding the channel's linear-interpolation rule as sharpness. One
approximation is documented in far::fvar: CornersPlus2 implements
junction and dart sharpening but not OpenSubdiv's additional concave-corner
analysis.
Face-varying patches reuse that representation: a channel's patch for a
face is the patch its value mesh gets at the vertex patch's level, so it
shares the vertex patch's PatchParam and is classified by the same rules
(B-spline, single-crease, Gregory or linear) as vertex patches are. As in
OpenSubdiv, a face patched where its vertex topology is regular but its
channel's is not gets a face-varying Gregory end cap at that level, unless
AdaptiveOptions::consider_fvar_channels isolates it; the test suite checks
that face-varying patches interpolate the channel's limit at face corners,
and that adaptive refinement considering the channels evaluates the same
face-varying surface as uniform refinement.
Selected-face refinement and patch tables follow OpenSubdiv's
RefineAdaptive and PatchTableFactory::Create with selectedFaces, with
one difference: an empty selection selects no face, where OpenSubdiv's
empty array means every face.
Patch tables extract exact bicubic B-spline patches wherever the limit
surface is polynomial; boundary, crease and corner patches are realized by
folding the phantom-point reflection 2a − b into the basis weights, which
is mathematically equivalent to OpenSubdiv's boundary basis masks. Every
other face at its isolation level is capped with a Gregory patch
built as OpenSubdiv's GregoryConverter builds it
(far/catmarkPatchBuilder.cpp): corners are classified by the span of
faces around them bounded by boundaries, non-manifold edges and infinitely
sharp creases, and
the corner, edge and face points use OpenSubdiv's own coefficients for
smooth interior, smooth boundary/crease, sharp and dart corners. The test
suite verifies that the construction degenerates to the exact B-spline
patch on regular interior, boundary, pinned-corner and crease neighborhoods
(for arbitrary control data), pinning every coefficient. As in OpenSubdiv,
non-manifold edges are made infinitely sharp, and non-manifold vertices
infinitely sharp unless they lie on a crease of exactly two non-manifold
edges bounding every fan around them, so non-manifold neighborhoods refine and patch like sharp features.
Only unsharpened (VtxBoundaryInterpolation::None) boundaries fall back to
bilinear quads of the refined level; semi-sharp features that
are still unresolved at the isolation cap are capped as if smooth, as
OpenSubdiv does.
Single-crease patches (Nießner et al., "Efficient Evaluation of Semi-Smooth
Creases in Catmull-Clark Subdivision Surfaces") are built for interior quads
with valence-4 corners bounded on one side by a straight semi-sharp crease of
uniform sharpness. Around such a face every refinement mask is the tensor
product of the B-spline rule along the crease with a one-dimensional crease
rule across it, so the patch evaluates the exact limit surface — under
Uniform and Chaikin creasing alike — as the linear blend of the profiles
of the two integer sharpnesses bracketing the crease's. OpenSubdiv
additionally caps the stored sharpness at the remaining isolation levels;
this port evaluates the authored sharpness exactly instead. Faces where the
crease ends, turns or changes sharpness are isolated as before.
Loop patches follow the same design on triangles. The quartic box-spline
basis of a regular face is derived by exact subdivision of the regular
lattice (Stam's twelve polynomials); boundaries, infinitely sharp creases
and pinned corners fold their phantom control vertices with the
parallelogram reflection a + b − c across the wall edge (and the point
reflection 2v − n through a pinned corner), which reproduces the crease
subdivision rules exactly, so the boundary curve is the cubic B-spline of
the boundary vertices as with the limit masks. Gregory triangles interpolate
the Loop limit points at their corners; their edge points lie a quarter of
the limit tangent along each edge, their mid-edge points make each edge
curve interpolate the limit surface at the edge's midpoint (the limit of the
edge's child vertex), and their face points come from the G1 condition
between neighboring patches. Adjacent patches share their edge curves, so
they join with exact C0 continuity; on regular neighborhoods the cap
degenerates to the exact box-spline patch, which the test suite verifies for
arbitrary control data. The coefficients are this port's own rather than
OpenSubdiv's loopPatchBuilder.cpp ones: the tangent scales (1/3 of the
cosine-weighted ring sum at interior vertices, 2/3 of the across-boundary
eigenvector at crease vertices — the regular values, applied at every
valence) were chosen by measuring the caps against deeply refined surfaces,
where they stay within about 1% of the edge length for valences 3 to 12.
Feature-adaptive refinement follows OpenSubdiv's approach: faces needing
isolation are selected level by level with their one-ring support included
(the role of Vtr::SparseSelector), producing sparse levels, and the test
suite verifies that adaptive and uniform evaluation agree everywhere on the
same meshes — for Loop as for Catmark. Transition-edge tagging for crack-free hardware tessellation
is not provided — parametric evaluation needs none, as adjacent patches at
different depths evaluate the same limit surface.
Not yet ported (roadmap):
- The
Osdback-ends for other APIs, and hardware tessellation shaders. The backend-independent data they consume is in theosdmodule; wgpu compute kernels running it are in the companion crate below - Face-varying patches in
GpuPatchTable, and transition-edge tags for hardware tessellation
GPU evaluation with wgpu
The companion crate opensubdiv-wgpu (in this
repository's Cargo workspace; this crate itself keeps no dependencies)
runs the stencil and patch kernels on the GPU through wgpu — Vulkan, Metal,
DX12, OpenGL or WebGPU. Its tests check the kernels against the CPU
evaluation on a real adapter (Mesa's lavapipe in CI), and
cargo run -p opensubdiv-wgpu --example tessellate tessellates a cube's
limit surface on the GPU.
Minimum supported Rust version
The MSRV is 1.90, shared by both crates of the workspace and checked in CI. Raising it is treated as a minor-version change.
Changelog
Notable changes are recorded in CHANGELOG.md.
License
Licensed under MIT AND LicenseRef-TOST-1.0:
- The original Rust code of this crate is under the MIT License.
- The crate is a Rust translation of OpenSubdiv, Copyright 2013 Pixar. The parts derived from it are also subject to OpenSubdiv's license, the Tomorrow Open Source Technology License 1.0 (Apache License 2.0 with a modified Section 6, "Trademarks").
The NOTICE file reproduces OpenSubdiv's attribution notice and
states how the translated files were changed. Redistributions must keep
LICENSE, LICENSE-OPENSUBDIV and NOTICE.
This project is not affiliated with or endorsed by Pixar. "OpenSubdiv" names the upstream library this crate translates; no trademark rights are granted.