Minor updates to the API overview documentation pages

documentation/api_overview.rst

@@ -47,8 +47,8 @@ Layers list:
 
 +-----------------------------------------+--------------------------------------------------------------------------------+
 | | **Sdc**                               |The lowest level layer, implements the core subdivision details                 |
-| | Subdivision Core                      |to facilitate the generation of consistent results.                             |
-| | `Sdc Overview <sdc_overview.html>`__  |                                                                                |
+| | Subdivision Core                      |to facilitate the generation of consistent results. Most cases will only        |
+| | `Sdc Overview <sdc_overview.html>`__  |require the use of simple public types and constants from Sdc.                  |
 +-----------------------------------------+--------------------------------------------------------------------------------+
 | | **Vtr**                               | A suite of classes to provide an intermediate                                  |
 | | Vectorized Topological Representation | representation of topology that supports efficient refinement.                 |

documentation/sdc_overview.rst

@@ -39,7 +39,8 @@ Subdivision Core (Sdc)
 Sdc is the lowest level layer in OpenSubdiv.  Its intent is to separate
 the core subdivision details from any particular representation of a mesh
 (it was previously bound to Hbr) to facilitate the generation of consistent
-results to other mesh representations, both internal and external to OpenSubdiv.
+results with other mesh representations, both internal and external to
+OpenSubdiv.
 
 The functionality can be divided roughly into three sections:
 
@@ -47,6 +48,12 @@ The functionality can be divided roughly into three sections:
     * computations required to support semi-sharp creasing
     * computations for mask weights of subdivided vertices for all schemes
 
+For most common usage, familiarity with only the first of these is necessary --
+primarily the use of public types and constants for the choice of subdivision
+scheme and its associated options.  The latter two provide the basis for a
+more comprehensive implementation of subdivision, which requires considerably
+more understanding and effort.
+
 Overall the approach taken was to extract the functionality at as low a
 level as possible.  In some cases they are not far from being simple global
 functions.  The intent was to start at a low level and build any higher

documentation/vtr_overview.rst

@@ -37,11 +37,14 @@ Vectorized Topology Representation (Vtr)
 ========================================
 
 *Vtr* consists of a suite of classes that collectively provide an intermediate
-representation of topology that supports efficient refinement. *Vtr* is
-intended for internal use only and is currently accessed through the *Far*
-layer by the `Far::TopologyRefiner <far_overview.html>`__, which assembles
+representation of topology that supports efficient refinement.
+
+*Vtr* is intended for internal use only and is currently accessed through the
+*Far* layer by the `Far::TopologyRefiner <far_overview.html>`__, which assembles
 these *Vtr* classes to meet the topological and refinement needs of the *Far*
-layer.
+layer.  What follows is therefore more intended to provide insite into the
+underlying architecture than to describe particular usage.  For documentation
+more relevant to direct usage, proceed to the *Far* section previously noted.
 
 *Vtr* is vectorized in that its topological data is stored more as a collection of
 vectors of primitive elements rather than as the faces, vertices and edges that