OpenSubdiv Documentation

The Osd layer provides device-dependent code to make Far structures available on various backends (TBB, CUDA, OpenCL, GLSL, etc.). Its primary roles include:

• Refinement: Computing stencil-based uniform or adaptive subdivision on CPU/GPU.
• Limit Stencil Evaluation: Computing limit surfaces using limit stencils on CPU/GPU.
• Limit Evaluation with PatchTable: Computing limit surfaces via patch evaluation on CPU/GPU.
• Hardware Tessellation Drawing: Providing GLSL/HLSL/Metal tessellation functions for OpenGL, DX11, or Metal.
• Buffer Configuration: Providing consistent buffer descriptors for interleaved or batched layouts.
• Cross-Platform Interop: Providing classes to facilitate interop between compute and draw APIs.

Note: Osd Evaluators do not own vertex buffers; clients must provide their own source and destination buffers.

Far is the primary API layer in OpenSubdiv used for processing client-supplied mesh data into subdivided surfaces. It can be used directly or to prepare mesh data for the Osd API. The process is divided into two main stages:

1. Topology Refinement: Splitting mesh topology (vertices, edges, faces) based on subdivision rules. This can be uniform or adaptive (isolating extraordinary features). This process is purely topological and does not depend on primvar values like point positions.
2. Primvar Refinement: Computing values for primvar data (points, colors, normals, texture coordinates, etc.) by applying weights determined by subdivision rules. This allows applying a single static topological refinement to multiple primvar instances or animated samples.

OpenSubdiv is a set of open source libraries designed for high-performance subdivision surface (subdiv) evaluation. It is optimized for massively parallel CPU and GPU architectures, specifically targeting the drawing of deforming surfaces with static topology at interactive framerates.

Important Note for Developers: OpenSubdiv is an API intended for integration into 3rd party digital content creation (DCC) tools. It is not a standalone application or a tool for direct digital asset creation.

OpenSubdiv treats subdivision surfaces as piecewise parametric surfaces defined over meshes of arbitrary topology.

Key concepts:

• Subdivision Operation: A process applied to a polygonal mesh to refine it (make it smoother).
• Limit Surface: The underlying smooth mathematical surface that the repeated subdivision process converges to. OpenSubdiv focuses on making this limit surface accessible and accurate.
• Piecewise Parametric Surfaces: Surfaces composed of multiple simpler modeling primitives called patches.

A patch is the fundamental building block of a piecewise smooth surface.

Key components of a patch:

• Control Points / Control Vertices: A set of points that determine the shape of the patch. The collection of these points is often referred to as the cage, control mesh, control hull, or hull.
• Surface: The actual smooth surface affected by the control points.
• Parameterization: The process of mapping a 2D domain (using coordinates u and v) to a 3D surface (x, y, z).
• Basis Function: A mathematical function associated with each control point that defines how moving that point affects the resulting surface. Different patch types (like B-Spline vs. Bezier) are distinguished by their basis functions.

The Far interface is used for high-performance subdivision and interpolation.

Key tasks:

• Mesh Instantiation: Instantiate a mesh as a Far::TopologyRefiner from simple topological data.
• Vertex Data Interpolation: Interpolate vertex data, including support for arbitrary width data buffers and different primvar types (vertex and varying).
• Primvar Types: Support for vertex, varying, and face-varying primvar data. face-varying data can be output in OBJ format using the UV texture layout.
• Smooth Normals: Calculate approximated smooth normals during the refinement process.

OpenSubdiv supports two primary subdivision surface types:

• Catmull-Clark (often called "Catmark"): Best suited for quad-dominant meshes and is the most widely used.
• Loop subdivision: Preferred for and requires purely triangulated meshes.

In the Base Face Representation (Bfr), every mesh face has an implicit local 2D parameterization $(u, v)$ used to evaluate the surface.

• Quadrilateral faces with quad-based subdivision (e.g., Catmull-Clark) use a single quad parameterization.
• Triangular faces with triangle-based subdivision (e.g., Loop) use a single triangle parameterization.
• Non-quad faces (like triangles) using a quad-based subdivision scheme are parameterized as a set of quadrilateral "sub-faces".

Note on Barycentric Coordinates: While triangles are often represented by barycentric coordinates $(u, v, w)$ where $w = 1 - u - v$, Bfr uses 2D $(u, v)$ pairs for all purposes. If you need barycentric coordinates for external tools, you must manually compute $w$ from the provided $(u, v)$ pair.

The Subdivision Core (Sdc) is the lowest-level layer in OpenSubdiv. It is designed to separate core subdivision logic from specific mesh representations (like Hbr), allowing for consistent results across different internal and external mesh formats.

Sdc provides the fundamental building blocks for:

• Supported subdivision schemes (types, traits, and options).
• Semi-sharp creasing computations.
• Mask weight computations for subdivided vertices across all schemes.

Note: Sdc is not a general framework for defining custom subdivision schemes; it is optimized for efficiently processing the specific set of schemes supported by OpenSubdiv.