Merge pull request #668 from barfowl/doc_compat

More documentation updates to the compatibility page

documentation/compatibility.rst

@@ -92,7 +92,8 @@ linear where specified by the choice applied.
 All five of Hbr's original modes of face-varying interpolation are supported
 (with minor modifications where Hbr was found to be incorrect in the presence
 of semi-sharp creasing).  An additional mode ("corners only") has also been
-added to avoid some of the undesired side-effects of some existing modes.
+added to avoid some of the undesired side-effects of some existing modes
+(illustrated below).
 
 The new values for the *"Sdc::Options::FVarLinearInterpolation"* enum and its
 equivalents for HbrMesh's InterpolateBoundaryMethod and PropagateCorners flag
@@ -116,12 +117,45 @@ is not affected by changes to other regions that may share the same vertex. So
 the behavior of a disjoint region should be well understood and predictable
 when looking at it in isolation (e.g. with "corners only" one would expect to
 see linear constraints applied where there are topological corners or infinitely
-sharp creasing applied within the region, and nowhere else).  This is not true
-of the "plus" modes, and they are named to reflect the fact that more is taken
-into account where disjoint regions meet.
+sharp creasing applied within the region, and nowhere else).
 
-Differences between the modes can be seen in the regression shapes with the
-prefix "catmark_fvar" -- which were specifically created for that purpose.
+This is not true of the "plus" modes, and they are named to reflect the fact
+that more is taken into account where disjoint regions meet.
+
+The following example illustrates some undesired effects of the "plus" modes,
+which in part motivated the addition of the new "corners only" mode.  The
+example uses the "catmark_fvar_bound0" and "catmark_fvar_bound1" shapes from
+the suite of regression shapes.  Both shapes are a simple regular 4x4 grid of
+quads with face-varying UV data partitioned into multiple disjoint regions.
+The "bound0" shape has two disjoint UV regions -- an upper and lower region --
+while the "bound1" shape further splits the lower region in two.
+
+This first figure illustrates the effect of the original "plus1" mode (which
+is also the same for "plus2"):
+
+.. image:: images/fvar_corners_plus1.png
+   :align: center
+   :width: 60%
+   :target: images/fvar_corners_plus1.png
+
+Note that the effect of splitting the lower UV region in two has the undesired
+side effect of sharpening the boundary of the upper region.  This is the result
+of the "plus1" mode making collective decisions about the sharpness of all
+face-varying boundaries at the vertex rather than decisions local to each
+region.  In both the "plus1" and "plus2" cases, all face-varying boundaries
+sharing a vertex will be sharpened if there are more than two regions meeting
+at that vertex.
+
+The second figure illustrates the effect of the new "corners only" mode:
+
+.. image:: images/fvar_corners_only.png
+   :align: center
+   :width: 60%
+   :target: images/fvar_corners_only.png
+
+As expected, the splitting of the lower region does not impact the upper
+region.  In this case the decision to sharpen a face-varying boundary is made
+based on the local topology of each region.
 
 **Vertex Interpolation Options**
 
@@ -193,11 +227,11 @@ using Hbr, the manifold restriction has also been removed.
 OpenSubdiv 3.0, therefore, supports a superset of the meshes supported by 2.x
 and earlier versions (with one known exception noted below).
 
-Non-manifold meshes that are acceptible to 3.0 however will likely not work
+Non-manifold meshes that are acceptable to 3.0 however will likely not work
 with 2.x or earlier.
 
 The one known case that 3.0 will not represent the same as 2.x is ironically
-a case that is non-manifold, and for which Hbr did make special accomodation.
+a case that is non-manifold, and for which Hbr did make special accommodation.
 
 That case occurs at a non-manifold vertex where two or more faces meet
 at a common vertex, but do not share a common edge, *and* when the boundary
@@ -209,9 +243,12 @@ illustrated below:
    :width: 80%
    :target: images/bowtie_vertex.png
 
-The cage is in the middle.  On either side is the subdivided mesh at level
-2 with boundary interpolation set to sharp corners and smooth corners on
-the left and right, respectively.
+The cage is on the left and is refined to level 2 on the right.  On the immediate
+right, boundary interpolation is set to sharp corners and the results appear
+the same for 2.x and 3.0.  The center and far right illustrate the affects of
+setting boundary interpolation to smooth corners with 2.x and 3.0 respectively.
+Note that the 2.x result allows the refined mesh (and so the limit surface) to
+split into two while the 3.0 result keeps it connected. 
 
 When Hbr encounters such vertices, regardless of the boundary mode it "splits"
 the vertex -- creating a separate instance of it for each face.  So when
@@ -271,22 +308,144 @@ section, and are listed briefly here.
 Other Differences
 +++++++++++++++++
 
+Additional differences can occur due to the differing implementations of the
+feature sets.  While RenderMan and OpenSubdiv may have shared the Hbr
+implementation at one point, even if OpenSubdiv were to make corrections to
+Hbr, they would not necessarily be picked up in RenderMan until it adopted
+the same version.  Some issues discovered in Hbr are not easily fixed, and
+so while OpenSubdiv 3.0 corrects those issues in its new implementation, it
+does not correct the Hbr implementation.
+
 **Smooth Face-Varying Interpolation with Creasing**
 
 There have been two discrepancies noted in the way that face-varying data is
-interpolated smoothly in the presence of creases:
+interpolated smoothly in the presence of creases.  Smooth face-varying
+interpolation is expected to match vertex interpolation in the interior and
+only differ along the boundaries or discontinuities where the face-varying
+topology is intentionally made to differ from the vertex topology.
 
-* Interpolation around a dart vertex
+A simple and effective way to identify discrepancies is to use the X and Y
+coordinates of vertex positions as the U and V of texture coordinates.  If
+these U and V coordinates are assigned to a face-varying channel, smooth
+interpolation of U and V is expected to exactly match interpolation of X
+and Y, regardless of the presence of any sharpness and creasing.
 
-* Lack of blending for fractional sharpness, i.e. only integer sharpness
+Two discrepancies can be seen with Hbr when superimposing the XY vertex
+interpolation with the "projected" UV face-varying interpolation.
+
+The first discrepancy occurs with interpolation around dart vertices:
+
+.. image:: images/fvar_hbr_dart.png
+   :align: center
+   :width: 80%
+   :target: images/fvar_hbr_dart.png
+
+This example shows a simple regular XY grid on the left with an interior sharp
+edge creating a dart vertex in the center.  With no asymmetry in the vertices,
+the sharpness has no asymmetric affect and the XY vertex interpolation on
+the immediate right shows the regular grid expected from refinement.  On the
+far right is the UV interpolation from Hbr, which exhibits distortion around
+the center dart vertex.
+
+The second discrepancy occurs with interpolation involving any fractional
+sharpness values.  Hbr effectively ignores any fractional sharpness value
+in its face-varying interpolation.  So edges of vertices with sharpness of
+say 2.5, will be treated as though their sharpness is 2.0 when face-varying
+values are interpolated.  Similarly, any non-zero sharpness value less than
+1.0 is treated as zero by truncation and so is essentially ignored.
+
+.. image:: images/fvar_hbr_integer.png
+   :align: center
+   :width: 80%
+   :target: images/fvar_hbr_integer.png
+
+This example shows an asymmetric 2x2 grid of quads on the left with the center
+vertex progressively sharpened from 0.5 to 1.0.  The three cases of the vertex
+smooth and sharpened are superimposed on the immediate right to display the
+three distinct interpolation results.  On the far right the interpolation from
+Hbr displays the same three cases, but only two are visibly distinct -- the
+sharpness of 0.5 being treated the same as if it were 0.0.
+
+Both of these cases are corrected in OpenSubdiv 3.0.  So smooth face-varying
+interpolation in the presence of creasing should match the expected behavior
+of the vertex interpolation, except where the face-varying topology is
+explicitly made to differ.
 
 **The Chaikin Creasing Method**
 
+At least two discrepancies are know to exist between the implementations of
+Hbr in RenderMan and OpenSubdiv 3.0:
+
 * Use of Chaikin creasing with boundaries or infinitely sharp edges
 
 * Subtle shape differences due to Hbr's use of "predictive sharpness"
 
+Fortunately this feature was only recently added to Hbr and RenderMan and is
+little used, so it is expected these differences will have little impact.
+
+The first of these is mentioned briefly in the previous section on
+compatibility between OpenSubdiv 2.x and 3.0.  A conscious decision was
+made to change the averaging of sharpness values involving infinitely
+sharp edges in order to make results more predictable and favorable.
+The effects can be seen comparing the regression shape "catmark_chaikin2".
+
+The second is more subtle and results from an oversight within Hbr's
+implementation that is not easily corrected.
+
+When determining what subdivision rule to apply from one level to the
+next, the sharpness values at the next level must be known in order to
+determine whether or not a transition between differing rules is required.
+If the rule at the next level differs from the previous, a combination of
+the two is applied.  Such a change results from the sharpness values of
+one or more edges (or the vertex itself) decaying to zero.
+
+Rather than compute the sharpness values at the next level accurately,
+Hbr "predicts" it by simply subtracting 1.0 from it, as is done with the
+uniform creasing method, and it bases decisions on that predicted result.
+This does not work for Chaikin though.  A sharpness value less than 1.0
+may not decay to 0 if it is averaged with neighboring sharpness values
+greater than 1.0.  So this sharpness prediction can result in the wrong
+rule being chosen for the next level.
+
+A typical case would have the subdivision rules for Chaikin creasing
+transition from Corner to Crease at one level, then from Crease to
+Smooth at the next.  Hbr's predictive creasing might mistakenly detect
+the transition as Corner to Smooth at one level, then after properly
+computing the sharpness values for the next level later, from Crease to
+Smooth for the next.  One of the regression shapes ("catmark_chakin1")
+was disabled from the regression suite because of this effect.  The
+differences in shape that trigger its regression failure were
+investigated and determined to be the result of this issue.
+
+From observations thus far these differences are subtle but can be
+noticeable.
+
+
 **Numerical Precision**
 
-* Improved with OpenSubdiv's ordering of weight application (most prevalent with
-  high-valence vertices)
+Since its inception, OpenSubdiv has sought to produce results that were
+numerically consistent to RenderMan.  A regression suite to ensure a
+certain level of accuracy was provided to detect any substantial deviation.
+
+At some point in the development of OpenSubdiv, the point was made that
+numerical accuracy of Hbr could be improved by changing the order of
+operations and combining the vertex with the lowest coefficient first in
+one of the subdivision rules.  This was applied more thoroughly in the
+independent implementation of 3.0 (there seemed no reason not to).  In
+most cases the relative magnitudes of the coefficients of subdivision and
+limit masks is clear so no overhead was necessary to detect them.
+
+At a certain point though, this greater accuracy came in conflict with the
+regression suite.  It turned out that high-valence vertices could not be
+computed to within the desired tolerances set within the suite.  The
+summation of many small coefficients for the adjacent vertices first, before
+the addition of the much larger coefficient for the primary vertex, allowed
+for the accumulation of precision that was being truncated by adding the
+much larger coefficient first in the Hbr implementation.  With extremely
+high valence vertices, a difference in magnitude between the most and least
+significant coefficients of several orders of magnitude is likely, and that
+has a significant impact on the single-precision floating point computations.
+
+So the improved accuracy of OpenSubdiv 3.0 can reach a magnitude that will
+not go undetected.  Whether or not this can lead to visual artifacts is
+unclear.