.. Copyright (C) Pixar. All rights reserved. This license governs use of the accompanying software. If you use the software, you accept this license. If you do not accept the license, do not use the software. 1. Definitions The terms "reproduce," "reproduction," "derivative works," and "distribution" have the same meaning here as under U.S. copyright law. A "contribution" is the original software, or any additions or changes to the software. A "contributor" is any person or entity that distributes its contribution under this license. "Licensed patents" are a contributor's patent claims that read directly on its contribution. 2. Grant of Rights (A) Copyright Grant- Subject to the terms of this license, including the license conditions and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free copyright license to reproduce its contribution, prepare derivative works of its contribution, and distribute its contribution or any derivative works that you create. (B) Patent Grant- Subject to the terms of this license, including the license conditions and limitations in section 3, each contributor grants you a non-exclusive, worldwide, royalty-free license under its licensed patents to make, have made, use, sell, offer for sale, import, and/or otherwise dispose of its contribution in the software or derivative works of the contribution in the software. 3. Conditions and Limitations (A) No Trademark License- This license does not grant you rights to use any contributor's name, logo, or trademarks. (B) If you bring a patent claim against any contributor over patents that you claim are infringed by the software, your patent license from such contributor to the software ends automatically. (C) If you distribute any portion of the software, you must retain all copyright, patent, trademark, and attribution notices that are present in the software. (D) If you distribute any portion of the software in source code form, you may do so only under this license by including a complete copy of this license with your distribution. If you distribute any portion of the software in compiled or object code form, you may only do so under a license that complies with this license. (E) The software is licensed "as-is." You bear the risk of using it. The contributors give no express warranties, guarantees or conditions. You may have additional consumer rights under your local laws which this license cannot change. To the extent permitted under your local laws, the contributors exclude the implied warranties of merchantability, fitness for a particular purpose and non-infringement. API Overview ------------ .. contents:: :local: :backlinks: none Architecture Overview ===================== Because the OpenSubdiv software is intended to run on a variete of computing resources, the API architecture has to accomodate a fairly complex matrix of interoperations. In order to achieve the requisite flexibility, the code structure is both layered and modular. ---- Opt-In Features *************** One of the fundamental requirement of all our API's design patterns is the opt-in implementation of features. Because most of the algorithms are used within the constraints of interactive applications, we want to provide optimal code paths wherever possible. Therefore, client-code should always have the option to opt-out of the memory and processing costs of any given feature that is not used. ---- Layers ****** From a top-down point of view, OpenSubdiv is comprised of 3 layers : **Hbr**, **Far** and **Osd**. .. image:: images/api_layers.png The color groupings indicate inter-layer functional dependencies: * Osd depends on Far, but not on Hbr * Far depends on Hbr * Hbr has no dependencies It is therefore possible to use functionality from Hbr without introducing any dependency on either Far or Osd. ---- Data and Workflows ****************** Data flows are mostly 1-directional, from top to bottom as a number of algorithms are preparing the coarse mesh data to be refined and passing their results to the next element in the processing chain. .. image:: images/api_data_flow.png :align: center ---- Representation vs. Implementation Layers **************************************** One of the core performance goals of our subdivision algorithms is to leverage interactive performance out of massively parallel code execution wherever possible. In order to support a large diversity of discrete compute devices through multiple dedicated SDKs, it is critical to distill the computations into the smallest and simplest kernels possible. These can in turn be safely ported and optimized for each of the hardware platforms. .. image:: images/api_representations.png This separation of general purpose against hardware-specific code is translated into two types of layers : the **implementation** layer against the **representation** layers. ---- Multiple Representations ************************ The coarse mesh of a subdivision surface is represented by a collection of components that maintain relationships to each other. .. image:: images/api_mesh_data.png :align: center For instance: - vertex to incident edge - edge to origin and destination vertex - face to edges This allows authoring applications to easily access "neighboring" components in order to make topology edits or manipulate properties of the components themselves. The key to achieving efficient many-core processing is to reduce data interdependencies. However, by definition, the bulk of topological mesh data is the very description of these connections (dependencies) between vertices. .. image:: images/api_serialized_data.png :align: center This is why OpenSubdiv provides specific representations for mesh data: - Hbr is a half-edge relational representation - Far is a serialized representation A typical workflow would be to manipulate the topology in authoring applications, maybe using Hbr meshes for common editing operations. Once the topology of the mesh has stabilized, it is processed into a serialized form that can then be evaluated at interactive framerates. The serialized form is embodied by Far, which can then be migrated by the device-specific functions in Osd. .. image:: images/api_workflows.png :align: center ---- Hierarchical Boundary Representation (Hbr) ========================================== Hbr is an interconnected topological data representation. The high level of vertex connectivity information makes this representation well suited for creation and editing purposes. It is however inefficient for interactive refinement operations: Separate objects are allocated for each vertex and edge with pointers to neighboring vertices and edges. Hbr is also the lowest-level subdivision library in Pixar's `Photorealistic RenderMan`. ---- Half-edge Data Structure ************************ The current implementation is based on a half-edge data structure. .. image:: images/half_edge.png :align: center ---- Half-edge cycles and Manifold Topology ************************************** Because half-edges only carry a reference to their opposite half-edge, a given edge can only access a single neighboring edge cycle. .. image:: images/half_edge_cycle.png :align: center This is a fundamental limitation of the half-edge data structure, in that it cannot represent non-manifold geometry, in particular fan-type topologies. A different approach to topology will probably be necessary in order to accomodate non-manifold geometry. ---- Templated Vertex Class ********************** The vertex class has been abstracted into a set of templated function accesses. Providing Hbr with a template vertex class that does not implement these functions allows client-code to use Hbr as a pure topological analysis tool without having to pay any costs for data interpolation. It also allows client-code to remain in complete control of the layout of the vertex data : interleaved or non-interleaved. ---- Feature Adaptive Representation (Far) ===================================== Far is a serialized topoloigcal data representation.Far uses hbr to create and cache fast run time data structures for table driven subdivision of vertices and cubic patches for limit surface evaluation. `Feature-adaptive `__ refinement logic is used to adaptively refine coarse topology near features like extraordinary vertices and creases in order to make the topology amenable to cubic patch evaluation. Far is also a generic, templated algorithmic base API that clients in higher levels instantiate and use by providing an implementation of a vertex class. It supports these subdivision schemes: ---- OpenSubdiv (Osd) ================ Osd contains client-level code that uses Far to create concrete instances of meshes. These meshes use precomputed tables from hbr to perform table-driven subdivision steps with a variety of massively parallel computational backend technologies. Osd supports both `uniform subdivision ` and adaptive refinement with cubic patches. With uniform subdivision the computational backend code performs Catmull/Clark splitting and averaging on each face. With adaptive subdivision the Catmull/Clark steps are used to compute the CVs of cubic patches, then the cubic patches are tessellated on with GLSL or DirectX. OpenSubdiv enforces the same results for the different computation backends with a series of regression tests that compare the methods to each other. The OpenSubdiv layer is comprised of 3 maine modules : Refine, Draw and Eval. .. image:: images/api_osd_modules.png These modules are identified by their name spaces (**OsdRefine**, **OsdDraw**, **OsdEval**) and encapsulate atomic functationality. The vertex data is carried in interoperable buffers that can be exchanged between modules. The typical use pattern is to pose the coarse vertices of a mesh for a given frame. The buffer is submitted to the **Refine** module which applies the subdivision rules and produces refined control vertices. This new buffer can be passed to the **Draw** module which will put them on screen. However, the same buffer of refined control vertices could be passed instead to the **Eval** module (and be projected onto another surface for instance) before being sent for display to the **Draw** module. .. container:: impnotip * **Important** Face-varying smooth data interpolation is currently not supported in Osd. "Smooth UV" modes of various DCC applications are not supported (yet). ---- OsdRefine ********* The Refine module contains the code paths that manage the application of the subdivision rules to the vertex data. ---- OsdDraw ******* The Draw module manages interactions with discrete display devices and provide support for interactive drawing of the subdivision surfaces. ---- OsdEval ******* The Eval module provides computational APIs for the evaluation of vertex data at the limit, ray intersection and point projection.