1.. 2 Copyright 2015 Pixar 3 4 Licensed under the Apache License, Version 2.0 (the "Apache License") 5 with the following modification; you may not use this file except in 6 compliance with the Apache License and the following modification to it: 7 Section 6. Trademarks. is deleted and replaced with: 8 9 6. Trademarks. This License does not grant permission to use the trade 10 names, trademarks, service marks, or product names of the Licensor 11 and its affiliates, except as required to comply with Section 4(c) of 12 the License and to reproduce the content of the NOTICE file. 13 14 You may obtain a copy of the Apache License at 15 16 http://www.apache.org/licenses/LICENSE-2.0 17 18 Unless required by applicable law or agreed to in writing, software 19 distributed under the Apache License with the above modification is 20 distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 21 KIND, either express or implied. See the Apache License for the specific 22 language governing permissions and limitations under the Apache License. 23 24Subdivision Compatibility 25------------------------- 26 27.. contents:: 28 :local: 29 :backlinks: none 30 31 32Subdivision Compatibility 33========================= 34 35This document highlights areas of compatibility with other software that makes 36use of subdivision surfaces, including previous versions of OpenSubdiv. 37 38The "compatibility" here refers to the choice of subdivision rules that define 39the shape of the resulting surfaces. Different subdivision rules will lead to 40different shapes. Choices affecting shape include: 41 42* the types of subdivision schemes supported (e.g. Catmull-Clark, Loop, etc.) 43 44* the basic rules applied for these schemes 45 46* any extended rules to affect sharpness or creasing 47 48* rules applied separately to face-varying data 49 50Ensuring all of these rules are consistent provides the basis for consistent 51shapes, but further approximations to the limit surface create the potential 52for subtle deviations. Even within OpenSubdiv, multiple approximations are 53possible and vary. For now we focus on the compatibility of subdivision rules 54and deal with the limit approximations only when noteworthy. 55 56 57Compatibility with OpenSubdiv 2.x 58================================= 59 60The refactoring of OpenSubdiv 3.0 data representations presented a unique 61opportunity to revisit some corners of the subdivision specification and 62remove or update some legacy features. 63 64**Face-varying Interpolation Options** 65 66Face-varying interpolation options have been consolidated into a single enum 67with one additional choice new to 3.0. No functionality from 2.x has been 68removed -- just re-expressed in a simpler and more comprehensible form. 69 70Face-varying interpolation was previously defined by a "boundary interpolation" 71enum with four modes and an additional boolean "propagate corners" option, 72which was little understood, i.e.: 73 74* void HbrMesh::SetFVarInterpolateBoundarMethod(InterpolateBoundaryMethod) const; 75 76* void HbrMesh::SetFVarPropagateCorners(bool) const; 77 78The latter was only used in conjunction with one 79of the four modes ("edge and corner"), so it was effectively a unique fifth 80choice. Closer inspection of all of these modes also revealed some unexpected 81and undesirable behavior in some common cases -- to an extent that could not 82simply be changed -- and so an additional mode was added to avoid such behavior. 83 84All choices are now provided through a single "linear interpolation" enum, 85described and illustrated in more detail in the overview of 86`Face-Varying Interpolation <subdivision_surfaces.html#face-varying-interpolation-rules>`__. 87The use of "boundary" in the name of the enum was intentionally removed 88as the choice also affects interior interpolation. The new use of "linear" 89is now intended to reflect the fact that interpolation is constrained to be 90linear where specified by the choice applied. 91 92All five of Hbr's original modes of face-varying interpolation are supported 93(with minor modifications where Hbr was found to be incorrect in the presence 94of semi-sharp creasing). An additional mode ("corners only") has also been 95added to avoid some of the undesired side-effects of some existing modes 96(illustrated below). 97 98The new values for the *"Sdc::Options::FVarLinearInterpolation"* enum and its 99equivalents for HbrMesh's InterpolateBoundaryMethod and PropagateCorners flag 100are as follows (ordered such that the set of linear constraints applied is 101always increasing -- from completely smooth to completely linear): 102 103============================ ================================== ========================= 104Sdc FVarLinearInterpolation Hbr FVarInterpolateBoundaryMethod Hbr FVarPropogateCorners 105============================ ================================== ========================= 106FVAR_LINEAR_NONE k_InterpolateBoundaryEdgeOnly N/A (ignored) 107FVAR_LINEAR_CORNERS_ONLY N/A N/A 108FVAR_LINEAR_CORNERS_PLUS1 k_InterpolateBoundaryEdgeAndCorner false 109FVAR_LINEAR_CORNERS_PLUS2 k_InterpolateBoundaryEdgeAndCorner true 110FVAR_LINEAR_BOUNDARIES k_InterpolateBoundaryAlwaysSharp N/A (ignored) 111FVAR_LINEAR_ALL k_InterpolateBoundaryNone N/A (ignored) 112============================ ================================== ========================= 113 114Aside from the two "corners plus" modes that preserve Hbr behavior, all other 115modes are designed so that the interpolation of a disjoint face-varying region 116is not affected by changes to other regions that may share the same vertex. So 117the behavior of a disjoint region should be well understood and predictable 118when looking at it in isolation (e.g. with "corners only" one would expect to 119see linear constraints applied where there are topological corners or infinitely 120sharp creasing applied within the region, and nowhere else). 121 122This is not true of the "plus" modes, and they are named to reflect the fact 123that more is taken into account where disjoint regions meet. 124 125The following example illustrates some undesired effects of the "plus" modes, 126which in part motivated the addition of the new "corners only" mode. The 127example uses the "catmark_fvar_bound0" and "catmark_fvar_bound1" shapes from 128the suite of regression shapes. Both shapes are a simple regular 4x4 grid of 129quads with face-varying UV data partitioned into multiple disjoint regions. 130The "bound0" shape has two disjoint UV regions -- an upper and lower region -- 131while the "bound1" shape further splits the lower region in two. 132 133This first figure illustrates the effect of the original "plus1" mode (which 134is also the same for "plus2"): 135 136.. image:: images/fvar_corners_plus1.png 137 :align: center 138 :width: 60% 139 :target: images/fvar_corners_plus1.png 140 141Note that the effect of splitting the lower UV region in two has the undesired 142side effect of sharpening the boundary of the upper region. This is the result 143of the "plus1" mode making collective decisions about the sharpness of all 144face-varying boundaries at the vertex rather than decisions local to each 145region. In both the "plus1" and "plus2" cases, all face-varying boundaries 146sharing a vertex will be sharpened if there are more than two regions meeting 147at that vertex. 148 149The second figure illustrates the effect of the new "corners only" mode: 150 151.. image:: images/fvar_corners_only.png 152 :align: center 153 :width: 60% 154 :target: images/fvar_corners_only.png 155 156As expected, the splitting of the lower region does not impact the upper 157region. In this case the decision to sharpen a face-varying boundary is made 158based on the local topology of each region. 159 160**Vertex Interpolation Options** 161 162Since the various options are now presented through a new API (Sdc rather than 163Hbr), based on the history of some of these options and input from interested 164parties, the following changes have been implemented: 165 166* The naming of the standard creasing method has been changed from *Normal* 167 to *Uniform*. Values for *"Sdc::Options::CreasingMethod"* are now: 168 169============== ==================================== 170CREASE_UNIFORM standard integer subtraction per level (default) 171CREASE_CHAIKIN Chaikin (non-uniform) averaging around vertices 172============== ==================================== 173 174* Legacy modes of the *"smoothtriangle"* rule have been removed (as they 175 were never actually enabled in the code). Values for 176 *"Sdc::Options::TriangleSubdivision"* are now: 177 178=============== ================= 179TRI_SUB_CATMARK Catmull-Clark weights (default) 180TRI_SUB_SMOOTH "smooth triangle" weights 181=============== ================= 182 183These should have little impact since one is a simple change in terminology 184as part of a new API while the other was removal of an option that was never 185used. 186 187**Change to Chaikin creasing method** 188 189In the process of re-implementing the Chaikin creasing method, observations 190lead to a conscious choice to change the behavior of Chaikin creasing in the 191presence of infinitely sharp edges (most noticeable at boundaries). 192 193Previously, the inclusion of infinite sharpness values in the Chaikin method's 194computation of edge sharpness around a vertex would prevent a 195semi-sharp edge from decaying to zero. Infinitely sharp edges are now 196excluded from the Chaikin (non-uniform) averaging yielding a much more 197predictable and desirable result. For example, where the sharpness assignment 198is actually uniform at such a vertex, the result will now behave the same as 199the Uniform method. 200 201Since this feature has received little use (only recently activated in 202RenderMan), now seemed the best time to make the change before more widespread 203adoption. 204 205**Hierarchical Edits** 206 207While extremely powerful, Hierarchical Edits come with additional maintenance 208and implementation complexity. Support for them in popular interchange formats 209and major DCC applications has either been dropped or was never implemented. 210As a result, the need for Hierarchical Edits is too limited to justify the cost 211and support for them, and they have therefore been removed from the 3.0 release 212of OpenSubdiv. Dropping support for Hierarchical Edits allows for significant 213simplifications of many areas of the subdivision algorithms. 214 215While the 3.0 release does not offer direct support for Hierarchical Edits, 216the architectural changes and direction of 3.0 still facilitate the application 217of the most common value edits for those wishing to use them -- though not 218always in the same optimized context. Of course, support for Hierarchical 219Edits in the future will be considered based on demand and resources. 220 221**Non-Manifold Topology** 222 223OpenSubdiv 2.x and earlier was limited to dealing with meshes whose topology 224was manifold -- a limitation imposed by the use of Hbr. With 3.0 no longer 225using Hbr, the manifold restriction has also been removed. 226 227OpenSubdiv 3.0, therefore, supports a superset of the meshes supported by 2.x 228and earlier versions (with one known exception noted below). 229 230Non-manifold meshes that are acceptable to 3.0 however will likely not work 231with 2.x or earlier. 232 233The one known case that 3.0 will not represent the same as 2.x is ironically 234a case that is non-manifold, and for which Hbr did make special accommodation. 235 236That case occurs at a non-manifold vertex where two or more faces meet 237at a common vertex, but do not share a common edge, *and* when the boundary 238interpolation mode is set for smooth corners (i.e. "edge only"), as 239illustrated below: 240 241.. image:: images/bowtie_vertex.png 242 :align: center 243 :width: 80% 244 :target: images/bowtie_vertex.png 245 246The cage is on the left and is refined to level 2 on the right. On the immediate 247right, boundary interpolation is set to sharp corners and the results appear 248the same for 2.x and 3.0. The center and far right illustrate the affects of 249setting boundary interpolation to smooth corners with 2.x and 3.0 respectively. 250Note that the 2.x result allows the refined mesh (and so the limit surface) to 251split into two while the 3.0 result keeps it connected. 252 253When Hbr encounters such vertices, regardless of the boundary mode it "splits" 254the vertex -- creating a separate instance of it for each face. So when 255building an HbrMesh, after "finalizing" the mesh, it will result in having 256more vertices than were originally defined (termed "split vertices"). 257 258OpenSubdiv 2.x (and earlier) successfully hid the presence of these extra 259vertices from users. 260 261This case behaves in such a way that violates certain properties of the 262surface that 3.0 has attempted to emphasize. One of these relates to the 263nature of the limit surface (and becomes more significant in the context of 264face varying): if the cage is connected then so too is its limit surface, 265or similarly, if the cage consists of *N* connected regions then the limit 266surface similarly consists of *N* connected regions. Another undesirable 267property here is that the vertex *V* at which these faces meet must have 268more than one child vertex *V'*. This makes it difficult to "hide" split 269vertices -- OpenSubdiv 2.x tables had an extra level of indirection that 270made it possible to do this relatively easily, but 3.0 has dispensed with 271such indirection where possible to streamline performance. 272 273 274Compatibility with RenderMan 275============================ 276 277Since RenderMan and OpenSubdiv versions prior to 3.0 share a common library 278(Hbr), most differences between RenderMan and OpenSubdiv 3.0 are covered in the 279preceding section of compatibility with OpenSubdiv 2.x. 280 281In addition to some features between RenderMan and OpenSubdiv that are not 282compatible, there are also other differences that may be present due to 283differences in the implementations of similar features. 284 285For most use cases, OpenSubdiv 3.0 is largely compatible with RenderMan. There 286are however some cases where some differences can be expected. These are 287highlighted below for completeness. 288 289Incompatibilities 290+++++++++++++++++ 291 292OpenSubdiv and RenderMan will be incompatible when certain features are used 293that are not common to both. They are fully described in the 2.x compatibility 294section and are listed briefly here. 295 296**OpenSubdiv 3.0 Features Not Supported by RenderMan** 297 298* Non-manifold meshes 299 300* Choice of the "corners only" face varying interpolation option 301 302 303**RenderMan Features Not Supported by OpenSubdiv 3.0** 304 305* Hierarchical Edits 306 307 308Other Differences 309+++++++++++++++++ 310 311Some differences can occur due to the differing implementations of the 312feature sets. Additionally, OpenSubdiv 3.0's implementation fixes some 313issues discovered in Hbr. 314 315**Smooth Face-Varying Interpolation with Creasing** 316 317There have been two discrepancies noted in the way that face-varying data is 318interpolated smoothly in the presence of creases. Smooth face-varying 319interpolation is expected to match vertex interpolation in the interior and 320only differ along the boundaries or discontinuities where the face-varying 321topology is intentionally made to differ from the vertex topology. 322 323A simple and effective way to identify discrepancies is to use the X and Y 324coordinates of vertex positions as the U and V of texture coordinates. If 325these U and V coordinates are assigned to a face-varying channel, smooth 326interpolation of U and V is expected to exactly match interpolation of X 327and Y, regardless of the presence of any sharpness and creasing. 328 329Two discrepancies can be seen with Hbr when superimposing the XY vertex 330interpolation with the "projected" UV face-varying interpolation. 331 332The first discrepancy occurs with interpolation around dart vertices: 333 334.. image:: images/fvar_hbr_dart.png 335 :align: center 336 :width: 80% 337 :target: images/fvar_hbr_dart.png 338 339This example shows a simple regular XY grid on the left with an interior sharp 340edge creating a dart vertex in the center. With no asymmetry in the vertices, 341the sharpness has no asymmetric affect and the XY vertex interpolation on 342the immediate right shows the regular grid expected from refinement. On the 343far right is the UV interpolation from Hbr, which exhibits distortion around 344the center dart vertex. 345 346The second discrepancy occurs with interpolation involving any fractional 347sharpness values. Hbr effectively ignores any fractional sharpness value 348in its face-varying interpolation. So edges of vertices with sharpness of 349say 2.5, will be treated as though their sharpness is 2.0 when face-varying 350values are interpolated. Similarly, any non-zero sharpness value less than 3511.0 is treated as zero by truncation and so is essentially ignored. 352 353.. image:: images/fvar_hbr_integer.png 354 :align: center 355 :width: 80% 356 :target: images/fvar_hbr_integer.png 357 358This example shows an asymmetric 2x2 grid of quads on the left with the center 359vertex progressively sharpened from 0.5 to 1.0. The three cases of the vertex 360smooth and sharpened are superimposed on the immediate right to display the 361three distinct interpolation results. On the far right the interpolation from 362Hbr displays the same three cases, but only two are visibly distinct -- the 363sharpness of 0.5 being treated the same as if it were 0.0. 364 365Both of these cases are corrected in OpenSubdiv 3.0. Smooth face-varying 366interpolation in the presence of creasing should match the expected behavior 367of the vertex interpolation, except where the face-varying topology is 368explicitly made to differ. 369 370**The Chaikin Creasing Method** 371 372At least two discrepancies are know to exist between the implementations of 373Hbr in RenderMan and OpenSubdiv 3.0: 374 375* Use of Chaikin creasing with boundaries or infinitely sharp edges 376 377* Subtle shape differences due to Hbr's use of "predictive sharpness" 378 379Fortunately, this feature was only recently added to Hbr and RenderMan and is 380little used, so it is expected these differences will have little impact. 381 382The first discrepancy is mentioned briefly in the previous section on 383compatibility between OpenSubdiv 2.x and 3.0. A conscious decision was 384made to change the averaging of sharpness values involving infinitely 385sharp edges in order to make results more predictable and favorable. 386The effects can be seen comparing the regression shape "catmark_chaikin2". 387 388The second is more subtle and results from an oversight within Hbr's 389implementation that is not easily corrected. 390 391When determining what subdivision rule to apply from one level to the 392next, the sharpness values at the next level must be known in order to 393determine whether or not a transition between differing rules is required. 394If the rule at the next level differs from the previous, a combination of 395the two is applied. Such a change results from the sharpness values of 396one or more edges (or the vertex itself) decaying to zero. 397 398Rather than compute the sharpness values at the next level accurately, 399Hbr "predicts" it by simply subtracting 1.0 from it, as is done with the 400uniform creasing method, and it bases decisions on that predicted result. 401This does not work for Chaikin though. A sharpness value less than 1.0 402may not decay to 0 if it is averaged with neighboring sharpness values 403greater than 1.0, so this sharpness prediction can result in the wrong 404rule being chosen for the next level. 405 406A typical case would have the subdivision rules for Chaikin creasing 407transition from Corner to Crease at one level, then from Crease to 408Smooth at the next. Hbr's predictive creasing might mistakenly detect 409the transition as Corner to Smooth at one level, then after properly 410computing the sharpness values for the next level later, from Crease to 411Smooth for the next. One of the regression shapes ("catmark_chakin1") 412was disabled from the regression suite because of this effect. The 413differences in shape that trigger its regression failure were 414investigated and determined to be the result of this issue. 415 416From observations thus far these differences are subtle but can be 417noticeable. 418 419 420**Numerical Precision** 421 422Since its inception, OpenSubdiv has sought to produce results that were 423numerically consistent to RenderMan. A regression suite to ensure a 424certain level of accuracy was provided to detect any substantial deviation. 425 426At some point in the development of OpenSubdiv, the point was made that 427numerical accuracy of Hbr could be improved by changing the order of 428operations and combining the vertex with the lowest coefficient first in 429one of the subdivision rules. This was applied more thoroughly in the 430independent implementation of 3.0 (there seemed no reason not to). In 431most cases the relative magnitudes of the coefficients of subdivision and 432limit masks is clear so no overhead was necessary to detect them. 433 434At a certain point though, this greater accuracy came in conflict with the 435regression suite. It turned out that high-valence vertices could not be 436computed to within the desired tolerances set within the suite. The 437summation of many small coefficients for the adjacent vertices first, before 438the addition of the much larger coefficient for the primary vertex, allowed 439for the accumulation of precision that was being truncated by adding the 440much larger coefficient first in the Hbr implementation. With extremely 441high valence vertices, a difference in magnitude between the most and least 442significant coefficients of several orders of magnitude is likely, and that 443has a significant impact on the single-precision floating point computations. 444 445The improved accuracy of OpenSubdiv 3.0 can reach a magnitude that will 446not go undetected. Whether or not this can lead to visual artifacts is 447unclear. 448
