Additions and minor improvements to far/tutorials:

- added far/tutorial_10 illustrating variable width vertex class
    - revised far/tutorial_9 for command line and documentation conventions
    - updated doc/tutorials.rst with missing and new tutorial descriptions

documentation/CMakeLists.txt

@@ -178,6 +178,9 @@ if (DOCUTILS_FOUND AND PYTHONINTERP_FOUND)
         far/tutorial_5/far_tutorial_5.cpp
         far/tutorial_6/far_tutorial_6.cpp
         far/tutorial_7/far_tutorial_7.cpp
+        far/tutorial_8/far_tutorial_8.cpp
+        far/tutorial_9/far_tutorial_9.cpp
+        far/tutorial_10/far_tutorial_10.cpp
         osd/tutorial_0/osd_tutorial_0.cpp
     )
 

documentation/tutorials.rst

@@ -33,7 +33,7 @@ Tutorials
 
 The tutorial source code can be found in the `github.com repository
 <https://github.com/PixarAnimationStudios/OpenSubdiv/tree/master/tutorials>`__
-or in your local ``<repository root>/turorials``.
+or in your local ``<repository root>/tutorials``.
 
 ----
 
@@ -65,7 +65,8 @@ or in your local ``<repository root>/turorials``.
 
    * - | **Tutorial 0**
        | This tutorial presents in a very succinct way the requisite steps to
-         instantiate a Far mesh from simple topological data. `[code] <far_tutorial_0.html>`__
+         instantiate a mesh as a Far::TopologyRefiner from simple topological
+         data. `[code] <far_tutorial_0.html>`__
        | |far_tut_0|
        |
        | **Tutorial 1**
@@ -88,11 +89,11 @@ or in your local ``<repository root>/turorials``.
          'face-varying' data recorded in the uv texture layout.  `[code] <far_tutorial_3.html>`__
        | |far_tut_3|
        |
-     - | **Tutorial 4**
-       | This tutorial shows how to create and manipulate FarStencilTable. We use the
+       | **Tutorial 4**
+       | This tutorial shows how to create and manipulate a StencilTable. We use the
          factorized stencils to interpolate vertex primvar data buffers. `[code] <far_tutorial_4.html>`__
        |
-       | **Tutorial 5**
+     - | **Tutorial 5**
        | This tutorial shows how to create and manipulate both 'vertex' and 'varying'
          FarStencilTable to interpolate 2 primvar data buffers: vertex positions and
          vertex colors. `[code] <far_tutorial_5.html>`__
@@ -106,6 +107,24 @@ or in your local ``<repository root>/turorials``.
        | This tutorial shows how to create and manipulate tables of cascading
          stencils to apply hierarchical vertex edits. `[code] <far_tutorial_7.html>`__
        |
+       | **Tutorial 8**
+       | Building on tutorial 3, this example shows how to instantiate a simple mesh,
+         refine it uniformly, interpolate both 'vertex' and 'face-varying' primvar
+         data, and finally calculate approximated smooth normals.  The resulting
+         interpolated data is output in 'obj' format.  `[code] <far_tutorial_8.html>`__
+       |
+       | **Tutorial 9**
+       | Building on tutorial 6, this example shows how to manage the limit surface
+         of a potentially large mesh by creating and evaluating separate PatchTables
+         for selected groups of faces of the mesh.  `[code] <far_tutorial_9.html>`__
+       |
+       | **Tutorial 10**
+       | In contrast to other tutorials, this tutorial makes use of a different vertex
+         data definition for use when vertex data is of arbitrary width.  Uniform
+         refinement is applied to data buffers of three types:  two of fixed size and
+         the third a union of the two that is dynamically sized and constructed.
+         `[code] <far_tutorial_10.html>`__
+       |
 
 ----
 

tutorials/far/CMakeLists.txt

@@ -33,6 +33,7 @@ set(TUTORIALS
     tutorial_7
     tutorial_8
     tutorial_9
+    tutorial_10
 )
 
 foreach(tutorial ${TUTORIALS})

tutorials/far/tutorial_10/CMakeLists.txt

@@ -0,0 +1,37 @@
+#
+#   Copyright 2013 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.
+#
+
+set(SOURCE_FILES
+    far_tutorial_10.cpp
+)
+
+_add_executable(far_tutorial_10 "tutorials/far"
+    ${SOURCE_FILES}
+    $<TARGET_OBJECTS:sdc_obj>
+    $<TARGET_OBJECTS:vtr_obj>
+    $<TARGET_OBJECTS:far_obj>
+)
+
+install(TARGETS far_tutorial_10 DESTINATION "${CMAKE_BINDIR_BASE}/tutorials")
+

tutorials/far/tutorial_10/far_tutorial_10.cpp

@@ -0,0 +1,292 @@
+//
+//   Copyright 2018 DreamWorks Animation LLC.
+//
+//   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.
+//
+
+
+//------------------------------------------------------------------------------
+// Tutorial description:
+//
+// This tutorial illustrates two different styles of defining classes for
+// interpolating primvar data with the template methods in Far.  The most
+// common usage involves data of a fixed size, so the focus here is on an
+// alternative supporting variable length data.
+//
+
+#include <opensubdiv/far/topologyDescriptor.h>
+#include <opensubdiv/far/primvarRefiner.h>
+
+#include <cstdio>
+
+using namespace OpenSubdiv;
+
+//
+//  Vertex data containers for interpolation:
+//      - Coord3 is fixed to support 3 floats
+//      - Coord2 is fixed to support 2 floats
+//      - CoordBuffer can support a specified number of floats
+//
+struct Coord3 {
+    Coord3() { }
+    Coord3(float x, float y, float z) { _xyz[0] = x, _xyz[1] = y, _xyz[2] = z; }
+
+    void Clear() { _xyz[0] = _xyz[1] = _xyz[2] = 0.0f; }
+
+    void AddWithWeight(Coord3 const & src, float weight) {
+        _xyz[0] += weight * src._xyz[0];
+        _xyz[1] += weight * src._xyz[1];
+        _xyz[2] += weight * src._xyz[2];
+    }
+
+    float const * Coords() const { return &_xyz[0]; }
+
+private:
+    float _xyz[3];
+};
+
+struct Coord2 {
+    Coord2() { }
+    Coord2(float u, float v) { _uv[0] = u, _uv[1] = v; }
+
+    void Clear() { _uv[0] = _uv[1] = 0.0f; }
+
+    void AddWithWeight(Coord2 const & src, float weight) {
+        _uv[0] += weight * src._uv[0];
+        _uv[1] += weight * src._uv[1];
+    }
+
+    float const * Coords() const { return &_uv[0]; }
+
+private:
+    float _uv[2];
+};
+
+struct CoordBuffer {
+    //
+    //  The head of an external buffer and stride is specified on construction:
+    //
+    CoordBuffer(float * data, int size) : _data(data), _size(size) { }
+    CoordBuffer() : _data(0), _size(0) { }
+
+    void Clear() {
+        for (int i = 0; i < _size; ++i) {
+            _data[i] = 0.0f;
+        }
+    }
+
+    void AddWithWeight(CoordBuffer const & src, float weight) {
+        assert(src._size == _size);
+        for (int i = 0; i < _size; ++i) {
+            _data[i] += weight * src._data[i];
+        }
+    }
+
+    float const * Coords() const { return _data; }
+
+    //
+    //  Defining [] to return a location elsewhere in the buffer is the key
+    //  requirement to supporting interpolatible data of varying size
+    //
+    CoordBuffer operator[](int index) const {
+        return CoordBuffer(_data + index * _size, _size);
+    }
+
+private:
+    float * _data;
+    int     _size;
+};
+
+//
+//  Global cube geometry from catmark_cube.h
+//
+//  Topology:
+static int g_nverts = 8;
+static int g_nfaces = 6;
+
+static int g_vertsperface[6] = { 4, 4, 4, 4, 4, 4 };
+
+static int g_vertIndices[24] = { 0, 1, 3, 2,
+                                 2, 3, 5, 4,
+                                 4, 5, 7, 6,
+                                 6, 7, 1, 0,
+                                 1, 7, 5, 3,
+                                 6, 0, 2, 4  };
+//  Primvar data:
+static float g_verts[8][3] = {{  0.0f,  0.0f,  1.0f },
+                              {  1.0f,  0.0f,  1.0f },
+                              {  0.0f,  1.0f,  1.0f },
+                              {  1.0f,  1.0f,  1.0f },
+                              {  0.0f,  1.0f,  0.0f },
+                              {  1.0f,  1.0f,  0.0f },
+                              {  0.0f,  0.0f,  0.0f },
+                              {  1.0f,  0.0f,  0.0f }};
+
+//
+//  Creates Far::TopologyRefiner from raw geometry above (see tutorial_0 for
+//  more details)
+//
+static Far::TopologyRefiner *
+createFarTopologyRefiner() {
+
+    typedef Far::TopologyDescriptor Descriptor;
+
+    Sdc::SchemeType type = OpenSubdiv::Sdc::SCHEME_CATMARK;
+
+    Sdc::Options options;
+    options.SetVtxBoundaryInterpolation(Sdc::Options::VTX_BOUNDARY_EDGE_ONLY);
+
+    Descriptor desc;
+    desc.numVertices  = g_nverts;
+    desc.numFaces     = g_nfaces;
+    desc.numVertsPerFace = g_vertsperface;
+    desc.vertIndicesPerFace  = g_vertIndices;
+
+    // Instantiate a Far::TopologyRefiner from the descriptor
+    Far::TopologyRefiner * refiner =
+            Far::TopologyRefinerFactory<Descriptor>::Create(desc,
+                    Far::TopologyRefinerFactory<Descriptor>::Options(type, options));
+
+    return refiner;
+}
+
+//
+//  Overview of main():
+//      - create a Far::TopologyRefiner and uniformly refine it
+//      - allocate separate and combined data buffers for vertex positions and UVs
+//      - populate all refined data buffers and compare results
+//      - write the result in Obj format
+//
+//  Disable warnings for exact floating point comparisons:
+#ifdef __INTEL_COMPILER
+#pragma warning disable 1572
+#endif
+
+int main(int, char **) {
+
+    //  Instantiate a FarTopologyRefiner from the global geometry:
+    Far::TopologyRefiner * refiner = createFarTopologyRefiner();
+
+    //  Uniformly refine the topology up to 'maxlevel'
+    int maxlevel = 2;
+
+    refiner->RefineUniform(Far::TopologyRefiner::UniformOptions(maxlevel));
+
+    //  Allocate and populate data buffers for vertex primvar data -- positions and
+    //  UVs. We assign UV coordiantes by simply projecting/assigning XY values.
+    //  The position and UV buffers use their associated data types, while the
+    //  combined buffer uses 5 floats per vertex.
+    //
+    int numBaseVertices  = g_nverts;
+    int numTotalVertices = refiner->GetNumVerticesTotal();
+
+    std::vector<Coord3> posData(numTotalVertices);
+    std::vector<Coord2> uvData(numTotalVertices);
+
+    int                 combinedStride = 3 + 2;
+    std::vector<float>  combinedData(numTotalVertices * combinedStride);
+
+    for (int i = 0; i < numBaseVertices; ++i) {
+        posData[i] = Coord3(g_verts[i][0], g_verts[i][1], g_verts[i][2]);
+        uvData[i]  = Coord2(g_verts[i][0], g_verts[i][1]);
+
+        float * coordCombined = &combinedData[i * combinedStride];
+        coordCombined[0] = g_verts[i][0];
+        coordCombined[1] = g_verts[i][1];
+        coordCombined[2] = g_verts[i][2];
+        coordCombined[3] = g_verts[i][0];
+        coordCombined[4] = g_verts[i][1];
+    }
+
+    //  Interpolate vertex primvar data
+    Far::PrimvarRefiner primvarRefiner(*refiner);
+
+    Coord3 * posSrc = &posData[0];
+    Coord2 * uvSrc  = & uvData[0];
+
+    CoordBuffer combinedSrc(&combinedData[0], combinedStride);
+
+    for (int level = 1; level <= maxlevel; ++level) {
+        int numLevelVerts = refiner->GetLevel(level-1).GetNumVertices();
+
+        Coord3 * posDst = posSrc + numLevelVerts;
+        Coord2 * uvDst  = uvSrc + numLevelVerts;
+
+        CoordBuffer combinedDst = combinedSrc[numLevelVerts];
+
+        primvarRefiner.Interpolate(level, posSrc, posDst);
+        primvarRefiner.Interpolate(level, uvSrc, uvDst);
+        primvarRefiner.Interpolate(level, combinedSrc, combinedDst);
+
+        posSrc = posDst;
+        uvSrc = uvDst;
+        combinedSrc = combinedDst;
+    }
+
+    //  Verify that the combined coords match the separate results:
+    for (int i = numBaseVertices; i < numTotalVertices; ++i) {
+        float const * posCoords = posData[i].Coords();
+        float const * uvCoords  = uvData[i].Coords();
+
+        float const * combCoords = &combinedData[combinedStride * i];
+
+        assert(combCoords[0] == posCoords[0]);
+        assert(combCoords[1] == posCoords[1]);
+        assert(combCoords[2] == posCoords[2]);
+        assert(combCoords[3] == uvCoords[0]);
+        assert(combCoords[4] == uvCoords[1]);
+    }
+
+    //
+    //  Output OBJ of the highest level refined:
+    //
+    Far::TopologyLevel const & refLastLevel = refiner->GetLevel(maxlevel);
+
+    int firstOfLastVerts = numTotalVertices - refLastLevel.GetNumVertices();
+
+    //  Print vertex positions
+    printf("#  Vertices:\n");
+    for (int vert = firstOfLastVerts; vert < numTotalVertices; ++vert) {
+        float const * pos = &combinedData[vert * combinedStride];
+        printf("v %f %f %f\n", pos[0], pos[1], pos[2]);
+    }
+
+    printf("#  UV coordinates:\n");
+    for (int vert = firstOfLastVerts; vert < numTotalVertices; ++vert) {
+        float const * uv = &combinedData[vert * combinedStride] + 3;
+        printf("vt %f %f\n", uv[0], uv[1]);
+    }
+
+    //  Print faces
+    int numFaces = refLastLevel.GetNumFaces();
+
+    printf("#  Faces:\n");
+    for (int face = 0; face < numFaces; ++face) {
+        Far::ConstIndexArray fverts = refLastLevel.GetFaceVertices(face);
+
+        printf("f ");
+        for (int fvert = 0; fvert < fverts.size(); ++fvert) {
+            int objIndex = 1 + fverts[fvert]; // OBJ uses 1-based arrays...
+            printf("%d/%d ", objIndex, objIndex);
+        }
+        printf("\n");
+    }
+}

tutorials/far/tutorial_9/far_tutorial_9.cpp

@@ -22,8 +22,10 @@
 //   language governing permissions and limitations under the Apache License.
 //
 
+
+//------------------------------------------------------------------------------
+//  Tutorial description:
 //
-//  Description:
 //      This tutorial shows how to manage the limit surface of a potentially
 //      large mesh by creating groups of patches for selected faces of the
 //      mesh.  Familiarity with construction and evaluation of a PatchTable
@@ -500,18 +502,20 @@ public:
                 } else {
                     fprintf(stderr, "Warning: .obj file '%s' ignored\n", argv[i]);
                 }
-            } else if (!strcmp(argv[i], "-mult")) {
-                if (++i < argc) geoMultiplier = atoi(argv[i]);
+            } else if (!strcmp(argv[i], "-l")) {
+                if (++i < argc) maxPatchDepth = atoi(argv[i]);
+            } else if (!strcmp(argv[i], "-level")) {
+                if (++i < argc) maxPatchDepth = atoi(argv[i]);
             } else if (!strcmp(argv[i], "-bilinear")) {
                 schemeType = Sdc::SCHEME_BILINEAR;
             } else if (!strcmp(argv[i], "-catmark")) {
                 schemeType = Sdc::SCHEME_CATMARK;
             } else if (!strcmp(argv[i], "-loop")) {
                 schemeType = Sdc::SCHEME_LOOP;
-            } else if (!strcmp(argv[i], "-depth")) {
-                if (++i < argc) maxPatchDepth = atoi(argv[i]);
             } else if (!strcmp(argv[i], "-groups")) {
                 if (++i < argc) numPatchGroups = atoi(argv[i]);
+            } else if (!strcmp(argv[i], "-mult")) {
+                if (++i < argc) geoMultiplier = atoi(argv[i]);
             } else if (!strcmp(argv[i], "-notess")) {
                 noTessFlag = true;
             } else if (!strcmp(argv[i], "-nooutput")) {