OpenSubdiv/documentation/api_overview.rst

..  
     Copyright 2013 Pixar
  
     Licensed under the Apache License, Version 2.0 (the "Apache License")
     with the following modification; you may not use this file except in
     compliance with the Apache License and the following modification to it:
     Section 6. Trademarks. is deleted and replaced with:
  
     6. Trademarks. This License does not grant permission to use the trade
        names, trademarks, service marks, or product names of the Licensor
        and its affiliates, except as required to comply with Section 4(c) of
        the License and to reproduce the content of the NOTICE file.
  
     You may obtain a copy of the Apache License at
  
         http://www.apache.org/licenses/LICENSE-2.0
  
     Unless required by applicable law or agreed to in writing, software
     distributed under the Apache License with the above modification is
     distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied. See the Apache License for the specific
     language governing permissions and limitations under the Apache License.
  

API Overview
------------

.. contents::
   :local:
   :backlinks: none


Architecture Overview
=====================

Because the OpenSubdiv software is intended to run on a variety 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.

----

API Layers
==========

From a top-down point of view, OpenSubdiv is comprised of several layers, some
public, and some private.

Layers list in descending order:

  * **Osd** (OpenSubdiv)
  * **Far** (Feature Adaptive Representation)
  * **Vtr** (Vectorized Topological Representation)
  * **Sdc** (Subdivision Core)

Client mesh data enters the API through the Far layer. Typically, results will
be collected from the Osd layer. However, it is possible to use
functionality from Far without introducing any dependency on Osd.

Although there are several entry-points to provide topology and primitive variable
data to OpenSubdiv, eventually everything must pass through the private Vtr and Sdc
representations for topological analysis.

See `Using the Right Tools`_ for more in-depth coverage.

.. image:: images/api_layers_3_0.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 compute architectures
it is critical to stream the geometric data to the compute kernels in the
most optimal way.

Data structures that are efficient for topology analysis during the pre-computation
stage are not very good candidates for parallel processing. Our layered structure
reflects this requirement: topology analysis and other pre-computation tasks are
delegated to "representation" layers, while the actual execution of computations
has been moved to an "implementation" layer.

.. image:: images/api_representations.png

**Representation** layers are for general purpose algorithms and differentiated by
the requirements placed on data represenation. See `Multiple Representations`_ for
more details.

The **Implementation** layer contains hardware and API-specific implementations.
In order to minimize code redundancy and bugs, we strive to reduce device-specific
computation logic to the most simplistic expression possible (in many cases as
simple as series of multiply-ads).

----

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: 
  - Vtr is a vectorized topology-only representation
  - Far is a feature adaptive serialized representation

A typical workflow would be to manipulate the topology in authoring applications,
maybe using Hbr or a similar relational representation 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 device-specific functions in Osd.

.. image:: images/api_workflows.png
   :align: center

----

Feature Adaptive Subdivision
============================

Because of the high-performance apsects, one of the main goals of the OpenSubdiv 
set of APIs is to compartmentalize subdivision rules from interpolation 
computations, which can then be dispatched to discrete compute devices, including
a variety of GPUs.

The data paths for the feature adaptive algorithm layered over the OpenSubdiv
architecture:

.. image:: images/osd_layers.png

Vtr serves both as a private, efficient, intermediate topological description and
as the custodian of the Catmull-Clark (and Loop) subdivision rules. Far is used to
leverage these rules in order to produce serialized topological tables. 

The remaining computations have been reduced to extremely simple forms of 
interpolation, which can be dispatched to a variety of discrete computation 
platforms.

----

Using the Right Tools
=====================

OpenSubdiv's tiered interface offers a lot flexibility to make your application
both fast and robust. Because navigating through the large collection of classes and
features can be challenging, here is a flow-chart that should help sketch
the broad lines of going about using subdivisions in your application.

General client application requirements:

+----------------------+-------------------------------------------------------+
| Surface Limit        | For some applications, a polygonal approximation of   | 
|                      | the smooth surface is enough. Others require          |  
|                      | C :sup:`2` continuous differentiable bi-cubic patches |  
|                      | (ex: deformable displacement mapping, smooth normals  |  
|                      | and semi-sharp creases...)                            |  
+----------------------+-------------------------------------------------------+
| Deforming Surface    | Applications such as off-line image renderers often   |
|                      | process a single frame at a time. Others, such as     |    
|                      | interactive games need to evaluate deforming          |    
|                      | character surface every frame. Because we can amortize|    
|                      | many computations if the topology of the mesh does not|    
|                      | change, OpenSubdiv provides 'stencil tables' in order |    
|                      | to leverage subdivision refinement into a             |     
|                      | pre-computation step.                                 |                 
+----------------------+-------------------------------------------------------+
| Multi-threading      | OpenSubdiv also provides dedicated interfaces to      |
|                      | leverage parallelism on a wide variety of platforms   |
|                      | and API standards, including both CPUs and GPUs.      |
+----------------------+-------------------------------------------------------+
| GPU Draw             | If the application requires interactive drawing on    |
|                      | screen, OpenSubdiv provides several back-end          |
|                      | implementations, including D3D11 and OpenGL. These    |
|                      | back-ends provide full support for programmable       |
|                      | shading.                                              |
+----------------------+-------------------------------------------------------+

Flow-chart:

.. image:: images/osd_flow.png
   :align: center
   :target: images/osd_flow.png