AuroraMiddleware/OpenSubdiv
1
0
Fork 0
mirror of https://github.com/PixarAnimationStudios/OpenSubdiv synced 2024-11-30 15:20:07 +00:00
Code Issues Releases Wiki Activity

Merge pull request #633 from barfowl/doc_updates

Browse Source 
More updates to Release Notes and Porting Guide
This commit is contained in:
George ElKoura 2015-06-14 21:57:52 -07:00
commit 94b84837a4
2 changed files with 140 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
documentation/porting.rst
View File

@ -35,6 +35,24 @@ code to use OpenSubdiv 3.0.
OpenSubdiv forum and we will be happy to help!
Source Code Organization
========================
Given the scale of functional changes that were being made to the public
interface, we took the oppoortunity in 3.0 to update the coding style and
organization -- most notably making use of namespaces for each library.
================= ==================== ===============================================
Subdirectory Namespace Relevance
================= ==================== ===============================================
hbr/ N/A Historical, no longer used
sdc/ Sdc New, low-level, public options, constants, etc.
vtr/ Vtr New, internal use, topology representation
far/ Far Revised, similar functionality with new API
osd/ Osd Revised, similar functionality with new API
================= ==================== ===============================================
Hbr Layer Translation
=====================
@ -209,6 +227,11 @@ FarSubdivisionTables Far::StencilTable
FarPatchTables Far::PatchTable
===================== =====================
Ordering of Refined Vertices
++++++++++++++++++++++++++++
(Need to address this topic at some point -- is this the right place?)
Osd Layer Translation
=====================
@ -388,14 +411,123 @@ splicing isn't needed, however clients must still bind additional buffers
See Osd::GLLegacyGregoryPatchTable for additional details.
Changes to Subdiv Specification
===============================
Subdivision Compatibility
=========================
RenderMan Compatibility Notes
=============================
Changes between 2.x and 3.0
+++++++++++++++++++++++++++
Build Support for 2.x and 3.0
=============================
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.
**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.
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
Build Support for Combining 2.x and 3.0
=======================================
Running OpenSubdiv 2.0 and 3.0 in a single process is supported, however some
special care must be taken to avoid namespace collisions, both in terms of

142
documentation/release_notes.rst
View File

@ -241,103 +241,6 @@ more tutorials as time and resources allow.
----
Changes to the Subdivision Specification
========================================
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.
Vertex Interpolation Rules
**************************
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
The current implementation of the *"Chaikin"* rule shows small
numerical differences with results obtained from Hbr in 2.x releases.
Considering that the feature is rarely used and that the current
implementation is likely the more correct one, we consider the
current implementation as *the standard*. Aside from a conscious
deviation at boundaries (where infinitely sharp creases are now excluded
from the averaging in 3.0 to allow proper decay of a semi-sharp edge
to 0), all other deviations found have been identified as flaws in the
implementation of 2.x (and are not easily corrected).
In all cases, features in active use are not being removed but simply
re-expressed in what is hoped to be a clearer interface.
Face-varying Interpolation Rules
********************************
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 ("edge only")
* FVAR_LINEAR_CORNERS_ONLY - sharpen corners only
* FVAR_LINEAR_CORNERS_PLUS1 - ("edge corner")
* FVAR_LINEAR_CORNERS_PLUS2 - ("edge and corner + propagate corner")
* FVAR_LINEAR_BOUNDARIES - piecewise linear edges and corners ("always sharp")
* FVAR_LINEAR_ALL - bilinear interpolation ("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 are illustrated in more detail elsewhere in the documentation, the tutorials
and the example shapes.
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.
----
RC2 Release Notes
==================
@ -414,48 +317,7 @@ Within 'Master' releases, we expect APIs to be backward compatible so that
existing client code can seamlessly build against newer releases. Changes
may include bug fixes as well as new features.
----
3.x Release Cycle RoadMap
=========================
Within the 3.x release cycle we would like to continue to address many of the
issues related to scaling the application of subdivision surfaces to large amounts
of primitives within typical graphics pipelines, as well as complete other
functionality that has long been missing from evaluation and display.
Support for smooth face-varying (UV) data with patches is one feature that was
targeted for 3.0 but unfortunately was not completed in time. While the fundamental
refinement and interpolation of face-varying data is correct, it has been and remains
linearly approximated in the patches created in Far that are most used for evaluation
and display. We want to update the patch tables to support non-linear patches for
the face-varying data.
As the potential standard for evaluation and display
of subdivision surfaces, OpenSubdiv is still lacking in its support of subdivision
schemes other than Catmark -- specifically Loop. Ultimately the same level of
performance and functionality achieved with Catmark should be available for Loop,
which is more effective in dealing with triangle-based meshes. With the refactoring
of the core refinement code in 3.0, much more of the supporting code for the schemes
can be shared so we have already reduced the effort to bring Loop up to par with
Catmark. We hope to take steps in this direction in an upcoming 3.x release.
Enabling workflows at larger scales will require improvements on several fronts:
* Handle more primitives, but with less overhead:
* Reduce Compute kernel launches, which we will achieve using stencils instead
of subdivision tables
* Reduce Draw calls by addressing the combinatorial explosion of tessellation
shaders
* Provide back-ends for next-gen APIs (D3D12, Mantle, Metal, Vulkan, etc.)
* Handle more semi-sharp creases: feature isolation needs to become much more
efficient to allow for complete creative freedom in using the feature.
* Faster topology analysis
Release 2.x
===========
Previous 2.x Release Notes
==========================
`Previous releases <release_notes_2x.html>`_