Skip to main content

opensubdiv_rs/osd/
mod.rs

1//! **Osd** — the data a GPU evaluator needs.
2//!
3//! OpenSubdiv's `opensubdiv/osd` layer adds no subdivision math: it uploads
4//! tables built by `Far` to a device and runs small kernels on them, in a
5//! version per API (CPU, OpenMP, TBB, CUDA, OpenCL, GLSL, HLSL, Metal). This
6//! module ports the backend-independent part — the flat tables and the
7//! patch basis the kernels evaluate — so any GPU API, such as `wgpu`, can
8//! run them; it has no GPU dependency itself.
9//!
10//! Two kernels cover what a renderer needs:
11//!
12//! * **Stencil evaluation** (`EvalStencils`): one invocation per output
13//!   vertex computes `dst[i] = Σ weights[j] · src[indices[j]]` over a
14//!   [`StencilTable`](crate::far::StencilTable)'s flat
15//!   [`offsets`](crate::far::StencilTable::offsets),
16//!   [`indices`](crate::far::StencilTable::indices) and
17//!   [`weights`](crate::far::StencilTable::weights). This refines a
18//!   deforming cage each frame — uniformly, for drawing a refined level, or
19//!   into the control buffer of a patch table.
20//! * **Patch evaluation** (`EvalPatches`): one invocation per
21//!   [`PatchCoord`] evaluates [`evaluate_patch_basis`] on the patch's
22//!   control points, read from a [`GpuPatchTable`]'s buffers — the limit
23//!   surface at arbitrary locations, with derivatives, for example on a
24//!   tessellation grid per patch.
25//!
26//! ```
27//! use opensubdiv_rs::far::{
28//!     AdaptiveOptions, PatchMap, PatchTableFactory, StencilTableFactory, StencilTableOptions,
29//!     TopologyDescriptor, TopologyRefinerFactory,
30//! };
31//! use opensubdiv_rs::osd::GpuPatchTable;
32//! use opensubdiv_rs::sdc;
33//!
34//! // A cube, adaptively refined: B-spline patches and Gregory end caps.
35//! let verts_per_face = [4; 6];
36//! let face_verts = [0, 1, 3, 2, 2, 3, 5, 4, 4, 5, 7, 6, 6, 7, 1, 0, 1, 7, 5, 3, 6, 0, 2, 4];
37//! let positions: [[f32; 3]; 8] = [
38//!     [-0.5, -0.5, 0.5], [0.5, -0.5, 0.5], [-0.5, 0.5, 0.5], [0.5, 0.5, 0.5],
39//!     [-0.5, 0.5, -0.5], [0.5, 0.5, -0.5], [-0.5, -0.5, -0.5], [0.5, -0.5, -0.5],
40//! ];
41//! let descriptor = TopologyDescriptor::new(8, &verts_per_face, &face_verts);
42//! let mut refiner = TopologyRefinerFactory::create(
43//!     descriptor, sdc::SchemeType::Catmark, sdc::Options::default(),
44//! ).unwrap();
45//! refiner.refine_adaptive(AdaptiveOptions::new(3));
46//! let patches = PatchTableFactory::create(&refiner).unwrap();
47//! let gpu = GpuPatchTable::new(&patches).unwrap();
48//!
49//! // Once per topology: one stencil table from the cage to every point the
50//! // patches index, and the buffers to upload.
51//! let stencils = StencilTableFactory::append_local_point_stencils(
52//!     &StencilTableFactory::create(&refiner, StencilTableOptions::for_patch_controls()),
53//!     gpu.local_point_stencils(),
54//! );
55//! let (_arrays, _indices, _params) =
56//!     (gpu.patch_array_words(), gpu.patch_index_buffer(), gpu.patch_param_words());
57//!
58//! // Per frame — here on the CPU, as the GPU kernels would: refine the cage
59//! // into the patches' control points, then evaluate a location.
60//! let mut points = vec![[0.0f32; 3]; stencils.num_stencils()];
61//! stencils.update_values(&positions, &mut points);
62//! let patch = PatchMap::new(&patches).find_patch(0, 0.25, 0.5).unwrap();
63//! let (p, _du, _dv) = gpu.evaluate(&gpu.patch_coord(patch, 0.25, 0.5), &points);
64//! assert!(p[2] > 0.0); // on the cube's front face, inside its +z cage face
65//! ```
66
67mod patch_basis;
68mod patch_table;
69mod types;
70
71pub use patch_basis::{evaluate_patch_basis, PatchWeights};
72pub use patch_table::GpuPatchTable;
73pub use types::{patch_descriptor, PatchArray, PatchCoord, PatchParam};