diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 75491168..ed2dc55e 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -68,6 +68,7 @@ if (DOCUTILS_FOUND AND PYTHONINTERP_FOUND) api_overview.rst cmake_build.rst code_examples.rst + compatibility.rst downloads.rst dxviewer.rst dxptexviewer.rst diff --git a/documentation/compatibility.rst b/documentation/compatibility.rst new file mode 100644 index 00000000..bbb1f644 --- /dev/null +++ b/documentation/compatibility.rst @@ -0,0 +1,142 @@ +.. + Copyright 2015 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. + +Subdivision Compatibility +------------------------- + +.. contents:: + :local: + :backlinks: none + +This document highlights areas of compatibility with other software that deals +with subdivision surfaces (including older versions of OpenSubdiv). + + +Compatibility with OpenSubdiv 2.x +================================= + +**Vertex Interpolation Options** + +Since the various options are now presented through a new API (Sdc rather than +Hbr), based on the history of some of these options and input from interested +parties, the following changes have been implemented: + +* Legacy modes of the *"smoothtriangle"* rule have been removed (as they + were never actually enabled in the code). Values for *"TriangleSubdivision"* + are now: + + * TRI_SUB_CATMARK - Catmull-Clark weights (default) + * TRI_SUB_SMOOTH - "smooth triangle" weights + +* The naming of the standard creasing method has been changed from *Normal* + to *Uniform*. Values for *"CreasingMethod"* are now: + + * CREASE_UNIFORM - the standard integer subtraction per level + * CREASE_CHAIKIN - use Chaikin averaging around vertices + +A conscious choice was also made to change the behavior of Chaikin creasing +in the presence of infinitely sharp edges (most noticeable at boundaries). +Previously the inclusion of the infinite sharpness values a semi-sharp edge +from decaying to zero. Infinitely sharp edges are now excluded from the +Chaikin averaging yielding a much more predictable and desirable result. +Since this feature has received little use (only recently activated in +RenderMan) now seemed a good time to make the change. + +**Face-varying Interpolation Options** + +Face-varying interpolation was previously defined by a "boundary interpolation" +enum with four modes and an additional boolean "propagate corners" option, +which was little understood. The latter was only used in conjunction with one +of the four modes, so it was effectively a unique fifth choice. Deeper analysis +of all of these modes revealed unexpected and undesirable behavior in some common +cases -- to an extent that could not simply be changed -- and so additions have +been made to avoid such behavior. + +All choices are now provided through a single "linear interpolation" enum -- +intentionally replacing the use of "boundary" in its naming as the choice also +affects interior interpolation. The naming now reflects the fact that +interpolation is constrained to be linear where specified by the choice. + +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 has also been added to allow for +additional control around T-junctions where multiple disjoint face-varying +regions meet at a vertex. + +The new values for the *"FVarLinearInterpolation"* are: + +========================= ============================================================== +FVAR_LINEAR_NONE smooth everywhere (formerly "edge only") +FVAR_LINEAR_CORNERS_ONLY sharpen corners only (new) +FVAR_LINEAR_CORNERS_PLUS1 sharpen corners and some junctions (formerly "edge and corner") +FVAR_LINEAR_CORNERS_PLUS2 sharpen corners and more junctions (formerly "edge and corner + propagate corner") +FVAR_LINEAR_BOUNDARIES piecewise linear edges and corners (formerly "always sharp") +FVAR_LINEAR_ALL bilinear interpolation (formerly "bilinear") (default) +========================= ============================================================== + +Aside from the two "corners plus" modes that preserve Hbr behavior, all other +modes are designed so that the interpolation of a disjoint face-varying region +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. + +These should be illustrated in more detail elsewhere in the documentation +(where exactly?) and with the example shapes and viewers. + +**Hierarchical Edits** + +Currently Hierarchical Edits have been marked as "extended specification" and +support for hierarchical features has been removed from the 3.0 release. This +decision allows for great simplifications of many areas of the subdivision +algorithms. If we can identify legitimate use-cases for hierarchical tags, we +will consider re-implementing them in future releases, as time and resources +allow. + + +Compatibility with RenderMan +============================ + +(More detail to come...) + +Conscious deviations (incompatibilities): + +- non-manifold topology +- choice of new face varying interpolation option ("corners only") +- use of Chaikin creasing with boundaries or infinitely sharp edges +- lack of hierarchical edits support + +Corrections to Hbr's behavior (differences): + +- smooth face varying interpolation in presence of dart vertices +- smooth face varying interpolation with fractional sharpness +- Chaikin creasing in general + +Improved accuracy (differences): + +- ordering of weight application (most prevalent with high-valence vertices) +- limit positions and tangents for arbitrary valence +- potential use of double precision masks diff --git a/documentation/nav_template.txt b/documentation/nav_template.txt index 56467041..467250a1 100644 --- a/documentation/nav_template.txt +++ b/documentation/nav_template.txt @@ -41,7 +41,11 @@
  • Roadmap

    • -
  • Porting Guide: 2.0 to 3.0
    • +
  • Porting and Compatibility
    • +

  • Modeling Tips
    • diff --git a/documentation/porting.rst b/documentation/porting.rst index f353489e..67e7b6c3 100644 --- a/documentation/porting.rst +++ b/documentation/porting.rst @@ -21,8 +21,8 @@ KIND, either express or implied. See the Apache License for the specific language governing permissions and limitations under the Apache License. -Compatibility and Porting Guide -------------------------------- +Porting Guide: 2.x to 3.0 +------------------------- .. contents:: :local: @@ -411,119 +411,22 @@ splicing isn't needed, however clients must still bind additional buffers See Osd::GLLegacyGregoryPatchTable for additional details. -Subdivision Compatibility -========================= - -Changes between 2.x and 3.0 -+++++++++++++++++++++++++++ +Changes to Subdivision +====================== The refactoring of OpenSubdiv 3.0 data representations presents a unique opportunity to revisit some corners of the subdivision specification and -remove or update some legacy features. +remove or update some legacy features. Below are some of the changes made that +affect compatibility with other software and previous versions of OpenSubdiv. +For more details please see the Subdivition Compatibility Guide. -**Vertex Interpolation Options** +* Vertex Interpolation Options changed. + * Legacy modes of the *"smoothtriangle"* triangle have been removed. + * The naming of the standard creasing method has changed from *Normal* to *Uniform*. -Since the various options are now presented through a new API (Sdc rather than -Hbr), based on the history of some of these options and input from interested -parties, the following changes have been implemented: +* Face-varying Interopation options have changed. -* Legacy modes of the *"smoothtriangle"* rule have been removed (as they - were never actually enabled in the code). Values for *"TriangleSubdivision"* - are now: - - * TRI_SUB_CATMARK - Catmull-Clark weights (default) - * TRI_SUB_SMOOTH - "smooth triangle" weights - -* The naming of the standard creasing method has been changed from *Normal* - to *Uniform*. Values for *"CreasingMethod"* are now: - - * CREASE_UNIFORM - the standard integer subtraction per level - * CREASE_CHAIKIN - use Chaikin averaging around vertices - -A conscious choice was also made to change the behavior of Chaikin creasing -in the presence of infinitely sharp edges (most noticeable at boundaries). -Previously the inclusion of the infinite sharpness values a semi-sharp edge -from decaying to zero. Infinitely sharp edges are now excluded from the -Chaikin averaging yielding a much more predictable and desirable result. -Since this feature has received little use (only recently activated in -RenderMan) now seemed a good time to make the change. - -**Face-varying Interpolation Options** - -Face-varying interpolation was previously defined by a "boundary interpolation" -enum with four modes and an additional boolean "propagate corners" option, -which was little understood. The latter was only used in conjunction with one -of the four modes, so it was effectively a unique fifth choice. Deeper analysis -of all of these modes revealed unexpected and undesirable behavior in some common -cases -- to an extent that could not simply be changed -- and so additions have -been made to avoid such behavior. - -All choices are now provided through a single "linear interpolation" enum -- -intentionally replacing the use of "boundary" in its naming as the choice also -affects interior interpolation. The naming now reflects the fact that -interpolation is constrained to be linear where specified by the choice. - -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 has also been added to allow for -additional control around T-junctions where multiple disjoint face-varying -regions meet at a vertex. - -The new values for the *"FVarLinearInterpolation"* are: - -========================= ============================================================== -FVAR_LINEAR_NONE smooth everywhere (formerly "edge only") -FVAR_LINEAR_CORNERS_ONLY sharpen corners only (new) -FVAR_LINEAR_CORNERS_PLUS1 sharpen corners and some junctions (formerly "edge and corner") -FVAR_LINEAR_CORNERS_PLUS2 sharpen corners and more junctions (formerly "edge and corner + propagate corner") -FVAR_LINEAR_BOUNDARIES piecewise linear edges and corners (formerly "always sharp") -FVAR_LINEAR_ALL bilinear interpolation (formerly "bilinear") (default) -========================= ============================================================== - -Aside from the two "corners plus" modes that preserve Hbr behavior, all other -modes are designed so that the interpolation of a disjoint face-varying region -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. - -These should be illustrated in more detail elsewhere in the documentation -(where exactly?) and with the example shapes and viewers. - -**Hierarchical Edits** - -Currently Hierarchical Edits have been marked as "extended specification" and -support for hierarchical features has been removed from the 3.0 release. This -decision allows for great simplifications of many areas of the subdivision -algorithms. If we can identify legitimate use-cases for hierarchical tags, we -will consider re-implementing them in future releases, as time and resources -allow. - -RenderMan Compatibility and Differences -+++++++++++++++++++++++++++++++++++++++ - -(More detail to come...) - -Conscious deviations (incompatibilities): - -- non-manifold topology -- choice of new face varying interpolation option ("corners only") -- use of Chaikin creasing with boundaries or infinitely sharp edges - -Corrections to Hbr's behavior (differences): - -- smooth face varying interpolation in presence of dart vertices -- smooth face varying interpolation with fractional sharpness -- Chaikin creasing in general - -Improved accuracy (differences): - -- ordering of weight application (most prevalent with high-valence vertices) -- limit positions and tangents for arbitrary valence -- potential use of double precision masks +* Hierarchical Edits support has been removed. Build Support for Combining 2.x and 3.0