Bfr::SurfaceFactory

Construction of Bfr::Surfaces requires an instance of Bfr::SurfaceFactory.

An instance of SurfaceFactory is a light-weight interface to an instance of a mesh that requires little to no construction cost or memory. The SurfaceFactory does no work until a Surface is requested for a particular face -- at which point the factory inspects the mesh topology around that face to assemble the Surface.

SurfaceFactory is actually a base class that is inherited to provide a consistent construction interface for Surfaces. Subclasses are derived to support a particular class of connected mesh -- to implement the topology inspection around each face required to construct the Surface. Use of these subclasses is very simple given the public interface of SurfaceFactory, but defining such a subclass is not. That more complex use case of SurfaceFactory will be described in detail later with other more advanced topics.

In many cases, it is not necessary to explicitly define a subclass of SurfaceFactory, as the tutorials for Bfr illustrate. If already using OpenSubdiv for other reasons, a Far::TopologyRefiner will have been constructed to represent the initial base mesh before refinement. Bfr provides a subclass of SurfaceFactory using Far::TopologyRefiner as the base mesh (ignoring any levels of refinement) for immediate use in such cases.

For those cases when no connected mesh representation is available at all (i.e. only raw, unconnected mesh data exists) construction of a Far::TopologyRefiner provides a reasonably efficient connected mesh representation (see the Far tutorials for construction details), whose provided subclass for SurfaceFactory is then readily available.

Given the different interpolation types for mesh data (i.e. "vertex", "varying" and "face-varying"), the common interface for SurfaceFactory provides methods to construct Surfaces explicitly for all data types. So for positions, the methods for "vertex" data must be used to obtain the desired Surface, while for texture coordinates the methods for "face-varying" are usually required, e.g.:

Surface * CreateVertexSurface(     Index faceIndex) const;
Surface * CreateVaryingSurface(    Index faceIndex) const;
Surface * CreateFaceVaryingSurface(Index faceIndex) const;

The Surfaces created by these construction methods may all be distinct as the underlying representations of the Surfaces and the indices of the data that define them will often differ. For example, the position data may require a bicubic patch while the face-varying texture data may be linear or a different type of bicubic patch (given the different interpolation rules for face-varying and the possibility of seams).

While the internal representations of the Surfaces constructed for different data interpolation types may differ, since they are all constructed as Surfaces, the functionality used to evaluate them is identical.

Bfr::Surface

The Surface class encapsulates the piece of limit surface associated with a particular face of the mesh. The term "surface" is used rather than "patch" to emphasize that the Surface may itself be a piecewise parametric surface composed of more than one patch (potentially even a complex set of patches).

Surface is also a class template selected by floating point precision, and so typically declared as Bfr::Surface<float>. Just as a simpler type name is likely to be declared when used, the simple name Surface will be used to refer to it here. And where code fragments may be warranted, "float" will be substituted for the template parameter for clarity.

Once created, there are two steps required to evaluate a Surface:

• preparation of associated data points from the mesh
• the actual calls to evaluation methods using these data points

The latter is straight-forward, but the former warrants a little more explanation.

The shape of a Surface for a base face is influenced by the set of data points associated with both the vertices of the face and a subset of those in its immediate neighborhood. These "control points" are identified when the Surface is initialized and are publicly available for inspection if desired. The control points are sufficient to define the Surface if the face and its neighborhood are regular, but any irregularity (an extra-ordinary vertex, crease, etc.) usually requires additional, intermediate points to be computed from those control points in order to evaluate the Surface efficiently.

Having previously avoided use of the term "patch" in favor of "surface", the term "patch points" is now used to refer to these intermediate points. Patch points always include the control points as a subset and may be followed by points needed for any additional patches required to represent a more complex Surface. While the patch points are assembled in a local array for direct use by the Surface, the control points can either be gathered and accessed locally or indexed from buffers associated with the mesh for other purposes (e.g. computing a bounding box of the Surface):

Once the patch points for a Surface are prepared, they can be passed to the main evaluation methods with the desired parametric coordinates. As previously noted, since the Surface class is a template for floating point precision, evaluation is supported in single or double precision by constructing a Surface for the desired precision. Evaluation methods are overloaded to obtain simply position or including all first or second derivatives. So preparation and evaluation can be achieved with the following:

//  Preparing patch points:
void PreparePatchPoints(
        float const * meshPoints,  PointDescriptor meshPointDescriptor,
        float       * patchPoints, PointDescriptor patchPointDescriptor) const;

//  Evaluating position and 1st derivatives:
void Evaluate(float const uv[2],
        float const * patchPoints, PointDescriptor patchPointDescriptor,
        float * P, float * dPdu, float * dPdv) const;

The PointDescriptor class here is a simple struct defining the size and stride of the associated array of points. Any use of mesh points, control points or patch points generally requires an accompanying descriptor.

Depending on the complexity of the limit surface, this preparation of patch points can be costly -- especially if only evaluating the Surface once or twice. In such cases, it is worth considering evaluating "limit stencils", i.e. sets of coefficients that combine the original control vertices of the mesh without requiring the computation of intermediate values. The cost of evaluating stencils is considerably higher than direct evaluation, but that added overhead is often offset by avoiding the use of patch points.

Surfaces should be considered a class for transient use as retaining them for longer term usage can reduce their benefits. The relatively high cost of initialization of irregular Surfaces can be a deterrent and often motivates their retention despite increased memory costs. Retaining all Surfaces of a mesh for random sampling is a situation that should be undertaken with caution and will be discussed in more detail later with other advanced topics.

Bfr::Parameterization

Bfr::Parameterization is a simple class that fully defines the parameterization for a particular face.

An instance of Parameterization is fully defined on construction given the "size" of a face and the subdivision scheme applied to it (where the face "size" is its number of vertices/edges). Since any parameterization of N-sided faces requires N in some form, the face size is stored as a member and made publicly available.

Each Surface has the Parameterization of its face assigned internally as part of its construction, and that is used internally by the Surface in many of its methods. The need to deal directly with the explicit details of the Parameterization class is not generally necessary. Often it is sufficient to retrieve the Parameterization from a Surface for use in some other context (e.g. passed to Bfr::Tessellation).

The enumerated type Parameterization::Type currently defines three kinds of parameterizations -- one of which is assigned to each instance on construction according to the properties of the face:

Parameterizations that involve subdivision into sub-faces, e.g. QUAD_SUBFACES, may warrant some care as they are not continuous. Depending on how they are defined, the sub-faces may be disjoint (e.g. Bfr) or overlap in parametric space (e.g. Ptex). To help these situations, methods to detect the presence of sub-faces and deal with their local parameterizations are made available.

Discontinuous Parameterizations

When a face does not have a regular parameterization, the division of the parameterization into sub-faces can create complications -- as noted and addressed elsewhere in OpenSubdiv.

Bfr::Parameterization defines a quadrangulated sub-face parameterization differently from the Far and Osd interfaces. For an N-sided face, Far uses a parameterization adopted by Ptex. In this case, all quad sub-faces are parameterized over the unit square and require an additional index of the sub-face to identify them. So Ptex coordinates require three values: the index and (u,v) of the sub-face.

To embed sub-face coordinates in a single (u,v) pair, Bfr tiles the sub-faces in disjoint regions in parameter space. This tiling is similar to the Udim convention for textures, where a UDim on the order of sqrt(N) is used to preserve accuracy for increasing N:

Note also that the edges of each sub-face are of parametric length 0.5, which results in a total parametric length of 1.0 for all base edges. This differs again from Ptex, which parameterizes sub-faces with edge lengths of 1.0, and so can lead to inconsistencies in parametric scale (typically with derivatives) across edges of the mesh if not careful.

As previously mentioned, care may be necessary when dealing with the discontinuities that exist in parameterizations with sub-faces. This is particularly true if evaluating data at sampled locations of the face and needing to evaluate at other locations interpolated from these.

Interpolation between parametric locations, e.g. A, B and C, should be avoided when discontinuous.

In many cases, dealing directly with coordinates of the sub-faces is unavoidable, e.g. interpolating Ptex coordinates for sampling of textures assigned explicitly to the sub-faces. Methods are provided to convert from Bfr's tiled parameterization to and from other representations that use a local parameterization for each sub-face.

Bfr::Tessellation

In Bfr a Tessellation is a simple class defined by a Parameterization and a given set of tessellation rates (and a few additional options). These two elements define a specific tessellation pattern for all faces sharing that Parameterization. An instance of Tessellation can then be inspected to identify all or subsets of its coords or facets.

The process of tessellation in other contexts usually generates triangular facets, but that is not the case with Bfr. While producing triangular facets is the default, options are available to have Tessellation include quads in patterns for parameterizations associated with quad-based subdivision schemes. For simple uniform patterns, these produce patterns that are similar in topology to those resulting from subdivision:

Tessellation of 4- and 5-sided faces of a quad-based scheme using quadrilateral facets (left) and triangular (right)

The name "Tessellation" was chosen rather than "Tessellator" as it is a passive class that simply holds information define its pattern. It doesn't do much other than providing information about the pattern when requested. A few general properties about the pattern are determined and retained on construction, after which an instance is immutable. So it does not maintain any additional state between queries.

In order to provide flexibility when dealing with tessellations of adjacent faces, the coords arising from an instance of Tessellation are ordered and are retrievable in ways to help identify points along edges that may be shared between two or more faces. The coords of a Tessellation are generated in concentric rings, beginning with the outer ring and starting with the first vertex:

Ordering of coords around boundary for quad and tri parameterizations.

Methods of the Tessellation class allow the coords associated with specific vertices or edges to be identified, as well as providing the coords for the entire ring around the boundary separately from those of the interior if desired. While the ordering of coords in the interior is not defined (and so not to be relied upon), the ordering of the boundary coords is specifically fixed to support the correlation of potentially shared coords between faces.

The Tessellation class is completely independent of the Surface class. Tessellation simply takes a Parameterization and tessellation rates and provides the coords and facets that define its pattern. So Tessellation can be used in any other evaluation context where the Parameterizations are appropriate.

Tessellation Rates

For a particular Parameterization, the various tessellation patterns are determined by one or more tessellation rates.

The simplest set of patterns uses a single tessellation rate and is said to be "uniform", i.e. all edges and the interior of the face are split to a similar degree:

Uniform tessellation of a quadrilateral and triangle with rates of 5 and 8.

More complex non-uniform patterns allow the edges of the face to be split independently from the interior of the face. Given rates for each edge, a suitable uniform rate for the interior can be either inferred or specified explicitly. These are typically referred to as the "outer rates" and the "inner rate". (The single rate specified for a simple uniform tessellation is essentially the specification of a single inner rate while the outer rates for all edges are inferred as the same.)

Non-uniform tessellation of a quadrilateral, triangle and 5-sided face with various outer and inner rates.

In the case of Parameterizations for quads, it is common elsewhere to associate two inner rates with the opposing edges. So two separate inner rates are available for quad parameterizations -- to be specified or otherwise inferred:

Quad tessellations with differing inner rates with matching (left) and varying outer rates (right).

Differences from Hardware Tessellation

Since the specifications for hardware tessellation often leave some details of the patterns as implementation dependent, no two hardware implementations are necessarily the same. Typically there may be subtle differences in the non-uniform tessellation patterns along boundaries, and that is to be executed here.

Bfr does provide some obvious additional functionality not present in hardware tessellation and vice versa, e.g. Bfr provides the following (not supported by hardware tessellation):

• patterns for parameterizations other than quads and tris (e.g. N-sided)
• preservation of quad facets of quad-based parameterizations

while hardware tessellation provides the following (not supported by Bfr):

• patterns for so-called "fractional" tessellation (non-integer rates)

The lack of fractional tessellation in Bfr is something that may be addressed in a future release.

Where the functionality of Bfr and hardware tessellation overlap, a few other differences are worth noting:

• indexing of edges and their associated outer tessellation rates
• uniform tessellation patterns for triangles differ significantly

For the indexing of edges and rates, when specifying an outer rate associated with an edge, the array index for rate i is expected to correspond to edge i. Bfr follows the convention established elsewhere in OpenSubdiv of labeling/indexing edges 0, 1, etc. between vertex pairs [0,1], [1,2], etc. So outer rate [0] corresponds to the edge between vertices [0,1]. In contrast, hardware tessellation associates the rate for the edge between vertices [0,1] as outer rate [1] -- its outer rate [0] is between vertices [N-1,0]. So an offset of 1 is warranted when comparing the two.

Outer edge tessellation rates of {1,3,5,7} applied to a quad with Bfr (left) and GPU tessellation (right).

For the uniform tessellation of triangles, its well known that the needs of hardware implementation led designers to factor the patterns for triangles to make use of the same hardware necessary for quads. As a result, many edges are introduced into a simple tessellation of a triangle that are not parallel to one of its three edges.

Bfr uses patterns more consistent with those resulting from the subdivision of triangles. Only edges parallel to the edges of the triangle are introduced, which creates more uniform facets (both edge lengths and area) and reduces their number (by one third). This can reduce artifacts that sometimes arise with use of the hardware patterns at lower tessellation rates:

Uniform tessellation of a triangle with Bfr (left) and GPU tessellation (right).

These triangular patterns have been referred to as "integer spacing" for triangular patches in early work on hardware tessellation. But use of these patterns was generally discarded in favor of techniques that split the triangle into three quads -- allowing the hardware solution for quad tessellation to be reused.

Bfr::SurfaceFactoryCache

The SurfaceFactoryCache is the class used by SurfaceFactory to cache the topological information that it can reuse for other similarly irregular faces of the mesh. Though it is a publicly accessible class, the SurfaceFactoryCache has little to no public interface other than construction (made available to support more advanced cases covered later) and in most cases it can be completely ignored.

Typically an instance of SurfaceFactory has an internal SurfaceFactoryCache member which is used by that factory for its lifetime. Since that cache member is mutable -- potentially updated when an irregular Surface is created -- it does need to be thread-safe if the SurfaceFactory is to be used in a threaded context.

To accommodate this need, SurfaceFactoryCache is defined as a base class with an accompanying class template to allow the trivial declaration of thread-safe subclasses:

template <typename MUTEX_TYPE,
          typename READ_LOCK_GUARD_TYPE,
          typename WRITE_LOCK_GUARD_TYPE >
class SurfaceFactoryCacheThreaded : public SurfaceFactoryCache {
    ...
};

For example, a local type for a thread-safe cache using std::shared_mutex from C++17 could be simply declared as follows:

#include <shared_mutex>

typedef Bfr::SurfaceFactoryCacheThreaded<
            std::shared_mutex,
            std::shared_lock<std::shared_mutex>,
            std::unique_lock<std::shared_mutex> >
        ThreadSafeCache;

Such thread-safe cache types are essential when distributing the work of a single SurfaceFactory across multiple threads. They can be encapsulated in the definitions of subclasses of SurfaceFactory or used to define external cache instances for use with any subclass of SurfaceFactory.

Defining a Thread-Safe SurfaceFactory

The thread-safety of a SurfaceFactory is purely dependent on the thread-safety of the SurfaceFactoryCache that it uses. With caching disabled, any SurfaceFactory is thread-safe but will be far less efficient in dealing with irregular Surfaces.

When a subclass of SurfaceFactory is defined (discussed in more detail later), one of its responsibilities is to identify and manage an instance of SurfaceFactoryCache for its internal use. Defining such a subclass is a simple matter of declaring a thread-safe SurfaceFactoryCache type (as noted above) along with a local member of that type to be used by each instance.

Given the widespread use of the Far::TopologyRefiner in OpenSubdiv, and the lack of a connected mesh representation in many contexts, a subclass of SurfaceFactory is made available to use a TopologyRefiner as a mesh, i.e. the Bfr::RefinerSurfaceFactory subclass.

Since many OpenSubdiv users may make use of the RefinerSurfaceFactory subclass, and they may have different preferences of threading model, the RefinerSurfaceFactory subclass is similarly defined as a class template to enable threading flexibility. In this case, the template is parameterized by the desired type of SurfaceFactoryCache, which embodies the threading specifications as noted above, i.e.:

template <class CACHE_TYPE = SurfaceFactoryCache>
class RefinerSurfaceFactory : public ... {
    ...
};

The default template is the base SurfaceFactoryCache which is not thread-safe, but a simple declaration of a thread-safe cache type is sufficient to declare a similarly thread-safe RefinerSurfaceFactory type:

#include <opensubdiv/bfr/surfaceFactoryCache.h>

//  Declare thread-safe cache type (see std::shared_mutex example above):
typedef Bfr::SurfaceFactoryCacheThreaded< ... > ThreadSafeCache;

//  Declare thread-safe factory type:
typedef Bfr::RefinerSurfaceFactory<ThreadSafeCache> ThreadSafeFactory;

The resulting factory type safely allows the construction of Surfaces (and their subsequent evaluation and tessellation) to be distributed over multiple threads.

Internal versus External SurfaceFactoryCache

Typical usage of the SurfaceFactoryCache by the SurfaceFactory is to have the factory create an internal cache member to be used for the lifetime of the factory associated with a mesh. But the data stored in the cache is not in any way dependent on the factory or mesh used to create it. So a cache can potentially be shared by multiple factories.

While such sharing is possible -- and the Bfr interfaces intentionally permit it -- any exploration should proceed with caution. Greater public knowledge and control of the cache is ultimately necessary to manage its potentially unbounded memory increase, and support in the public interface is currently limited.

A cache stored as a member varialbe and managed exclusively by the factory is said to be "internal" while one managed exclusively by its client is said to be "external". In both cases, the factory deals with retrieving data from or adding data to the cache -- only management of the cache's ownership differs, and that ownership is never transferred.

A subset of the methods of SurfaceFactory::Options provide the means of specifying the use of an internal or external cache, or no caching at all:

// Assign an external cache to override the internal
Options & SetExternalCache(SurfaceFactoryCache * cache);

// Enable or disable caching (default is true):
Options & EnableCaching(bool on);

As noted here, specifying an external cache will override use of a factory's internal cache. Disabling caching takes precedence over both, but is generally not practical and exists mainly to aide debugging.

The common use of the internal cache is to create a SurfaceFactory and distribute processing of the Surfaces of its faces over multiple threads, or to construct Surfaces for the mesh for any other purpose while the mesh remains in scope. There is no need to deal explicitly with the SurfaceFactoryCache in these cases.

Use cases for an external cache are more varied and explicit, including:

• creating a single external cache to process a sequence of meshes on a single thread (cache thread-safety not required)
• creating a separate external cache on each thread to process a set of meshes distributed over multiple threads (cache thread-safety not required)
• creating a single external cache for multiple meshes distributed over multiple threads (cache thread-safety required, and beware of unbounded memory growth here)

Future extensions to the public interface of SurfaceFactoryCache may be made to support common use cases as their common needs are made clearer.

The Bfr::SurfaceFactoryMeshAdapter Interface

The SurfaceFactoryMeshAdapter class defines the interface used to satisfy the topological requirements of the SurfaceFactory. An implementation for a particular mesh class provides the base factory with everything needed to identify the limit surface of a given face from its surrounding topology. The SurfaceFactory actually inherits the SurfaceFactoryMeshAdapter interface but does not implement it -- deferring that to its subclasses -- since separate subclasses of SurfaceFactoryMeshAdapter serve no other purpose.

The limit surface for a face is fully defined by the complete set of incident vertices, faces and edges surrounding the face. But it is difficult to accurately and efficiently assemble and represent all of that required information in a single class or query for all possible cases. So the mesh adapter interface provides a suite of methods to allow the factory to gather only what it needs for the Surface required -- which may differ considerably according to whether the Surface is for vertex or face-varying data, linear or non-linear, etc.

The virtual methods required can be organized into small groups devoted to particular aspects of construction. A description of the methods and purposes for each group follows, with more details and exact signatures available in the accompanying Doxygen for the SurfaceFactoryMeshAdapter class.

Basic Properties of a Face

A small set of simple methods indicate whether the SurfaceFactory needs to create a Surface for a face, and if so, how:

virtual bool isFaceHole(Index faceIndex) const = 0;

virtual int getFaceSize(Index faceIndex) const = 0;

These are trivial and self-explanatory.

Identifying Indices for an Entire Face

If the Surface requested turns out to be linearly interpolated (e.g. for varying or linear face-varying data) indices for the control point data are all assigned to the face and can be trivially identified:

virtual int getFaceVertexIndices(Index faceIndex,
                Index vertexIndices[]) const = 0;

virtual int getFaceFVarValueIndices(Index faceIndex,
                FVarID faceVaryingID,
                Index  faceVaryingIndices[]) const = 0;

Since multiple sets of face-varying data with different topology may be assigned to the mesh, an identifier needs to be specified both in the public interface when requesting a Surface and here when the factory assembles it. How a face-varying identifier is interpreted is completely determined by the subclass through the implementation of the methods that require it.

Specifying the Neighborhood Around a Vertex

When the Surface requested is not linear, the entire neighborhood around the face must be determined. This is achieved by specifying the neighborhoods around each of the vertices of the face, which the factory then assembles.

For the neighborhood of each face-vertex, the factory obtains a complete specification in a simple VertexDescriptor class. An instance of VertexDescriptor is provided and populated with the following method:

virtual int populateFaceVertexDescriptor(
                Index faceIndex, int faceVertex,
                VertexDescriptor * vertexDescriptor) const = 0;

Within this method, the given VertexDescriptor instance is initialized using a small suite of VertexDescriptor methods that specify the following information about the vertex and its neighborhood:

• whether the neighborhood is manifold (ordered counter-clockwise)
• whether the vertex is on a boundary
• the sizes of all or each incident face
• the sharpness of the vertex
• the sharpness of edges of incident faces

These methods are specified between Initialize() and Finalize() methods, so an interior vertex of valence 4 with three incident quads and one incident triangle might be specified as follows:

int vertexValence = 4;
vertexDescriptor.Initialize(vertexValence);
    vertexDescriptor.SetManifold(true);
    vertexDescriptor.SetBoundary(false);

    vertexDescriptor.SetIncidentFaceSize(0, 4);
    vertexDescriptor.SetIncidentFaceSize(1, 4);
    vertexDescriptor.SetIncidentFaceSize(2, 3);
    vertexDescriptor.SetIncidentFaceSize(3, 4);
vertexDescriptor.Finalize();

Specifying the vertex neighborhood as manifold is critical to allowing the factory to inspect the neighborhood efficiently. A manifold vertex has its incident faces and edges ordered in a counter-clockwise orientation and is free of degeneracies. If it is not clear that a vertex is manifold, it should not be set as such or the factory's inspection of associated data will not be correct.

Identifying Indices Around a Vertex

When the Surface requested is not linear, the indices of control point data for the entire neighborhood of the face are ultimately required, and that entire set is similarly determined by identifying the indices for each of the neighborhoods of the face-vertices:

virtual int getFaceVertexIncidentFaceVertexIndices(
                Index faceIndex, int faceVertex,
                Index vertexIndices[]) const = 0;

virtual int getFaceVertexIncidentFaceFVarValueIndices(
                Index faceIndex, int faceVertex,
                FVarID faceVaryingID,
                Index  faceVaryingIndices[]) const = 0;

As was the case with the methods retrieving indices for the entire face, one exists for identifying indices vertex data while another exists to identify indices for a specified set of face-varying data.

Customizing the Subclass Interface

Once the topological requirements of a subclass have been satisfied for its mesh representation, minor customizations of the inherited interface of SurfaceFactory may be useful.

Consider a class called Mesh and its associated subclass of SurfaceFactory called MeshSurfaceFactory.

At minimum, a constructor of MeshSurfaceFactory is necessary to construct an instance for a particular instance of mesh. This is typically achieved as follows:

MeshSurfaceFactory(Mesh const & mesh,
                   Options const & options);

In addition to the Mesh instance, such a constructor passes a set of Options (i.e. SurfaceFactory::Options) to the base SurfaceFactory. Any additional arguments are possible here, e.g. perhaps only a single face-varying UV set is supported, and that might be specified by identifying it on construction.

Given that mesh representations often have their own associated classes that internally contain the actual data, it may be useful to provide a few other conveniences to simplify working with a Mesh. For example, if mesh data is stored in a class called MeshPrimvar, a method to construct a Surface from a given MeshPrimvar may be useful, e.g.:

bool InitPrimvarSurface(int faceIndex,
                        MeshPrimvar const & meshPrimvar,
                        Surface<float> * surface);

which would then determine the nature of the MeshPrimvar data (interpolated as vertex, varying or face-varying) and act accordingly. It may also be worth simplifying the template complexity here if only one precision is ever required.