From 40c5dbdd8293855c2207af10d357f63ed9ccceba Mon Sep 17 00:00:00 2001 From: George ElKoura Date: Mon, 15 Jun 2015 20:16:47 -0700 Subject: [PATCH] Split out Compatiblity Guide into a separate page. The compatibility portions of the "Porting Guide" are now split into a different page. We'd like to keep the "Porting Guide" simple and easy to understand. The Compatiblity portion may live on longer than what is just needed for Porting from 2.x to 3.0. --- documentation/CMakeLists.txt | 1 + documentation/compatibility.rst | 142 ++++++++++++++++++++++++++++++++ documentation/nav_template.txt | 6 +- documentation/porting.rst | 121 +++------------------------ 4 files changed, 160 insertions(+), 110 deletions(-) create mode 100644 documentation/compatibility.rst 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