OpenSubdiv: SurfaceFactory Class Reference

| OpenSubdiv

Loading...
Searching...
No Matches
SurfaceFactory Class Reference

Base class providing initialization of a Surface for each face of a mesh. More...

`#include <surfaceFactory.h>`

Inheritance diagram for SurfaceFactory:

## Classes
class | Options
| Simple set of options assigned to instances of SurfaceFactory. More...

## Public Member Functions
| ~SurfaceFactory () override
Simple queries of subdivision properties
Simple queries to inspect subdivision properties.
Sdc::SchemeType | GetSchemeType () const
| Return the subdivision scheme.
Sdc::Options | GetSchemeOptions () const
| Return the set of subdivision options.
Simple queries influencing Surface construction
Methods to quickly inspect faces that influence Surface construction. A small set of methods is useful to inspect faces in order to determine if their corresponding Surfaces should be initialized. The Surface initialization methods will fail when a limit surface does exist, so the methods here are intended for purposes when that simple failure on initialization is not suitable, e.g. to address some kind of pre-processing need prior to the initialization of any Surfaces.
bool | FaceHasLimitSurface (Index faceIndex) const
| Return if a specified face has a limit surface.
Parameterization | GetFaceParameterization (Index faceIndex) const
| Return the Parameterization of a face with a limit surface.
Methods to initialize Surfaces
Methods to initialize instances of Surface for a specific face. Given the different interpolation types for data associated with mesh vertices (i.e. vertex, varying and face-varying data), the topology of the limit surface potentially (likely) differs between them. So it is necessary to specify the type of data to be associated with the Surface. Methods exist to initialize a single surface for each of the three data types, and to initialize multiple surfaces for different data types at once (which will avoid repeated effort in a single-threaded context). Failure of these initialization methods is expected (and so to be tested) when a face has no limit surface – either due to it being a hole or through the use of less common boundary interpolation options. Failure is also possible if the subclass fails to provide a valid topological description of the face. (WIP - consider more extreme failure for these cases, e.g. possible assertions.)
template<typename REAL>
bool | InitVertexSurface (Index faceIndex, Surface< REAL > *surface) const
| Initialize a Surface for vertex data.
template<typename REAL>
bool | InitVaryingSurface (Index faceIndex, Surface< REAL > *surface) const
| Initialize a Surface for varying data.
template<typename REAL>
bool | InitFaceVaryingSurface (Index faceIndex, Surface< REAL > *surface) const
| Initialize a Surface for the default face-varying data.
template<typename REAL>
bool | InitFaceVaryingSurface (Index faceIndex, Surface< REAL > *surface, FVarID fvarID) const
| Initialize a Surface for specified face-varying data.
template<typename REAL>
bool | InitSurfaces (Index faceIndex, Surface< REAL > *vtxSurface, Surface< REAL > *fvarSurfaces, FVarID const fvarIDs[]=0, int fvarCount=0, Surface< REAL > *varSurface=0) const
| Initialize multiple Surfaces at once.
Methods to construct Surfaces
Methods to both allocate and initialize a single Surface.
template<typename REAL = float>
Surface< REAL > * | CreateVertexSurface (Index faceIndex) const
| Construct a Surface for vertex data.
template<typename REAL = float>
Surface< REAL > * | CreateVaryingSurface (Index faceIndex) const
| Construct a Surface for varying data.
template<typename REAL = float>
Surface< REAL > * | CreateFaceVaryingSurface (Index faceIndex) const
| Construct a Surface for the default face-varying data.
template<typename REAL = float>
Surface< REAL > * | CreateFaceVaryingSurface (Index faceIndex, FVarID id) const
| Construct a Surface for specified face-varying data.

## Protected methods supporting subclass construction
Protected methods supporting subclass construction.
| SurfaceFactory (Sdc::SchemeType schemeType, Sdc::Options const &schemeOptions, Options const &limitOptions)
| Constructor to be used by subclasses.
void | setInternalCache (SurfaceFactoryCache *cache)
| Subclass to identify an internal cache for use by base class.
| SurfaceFactory (SurfaceFactory const &)=delete
SurfaceFactory & | operator= (SurfaceFactory const &)=delete

## Additional Inherited Members
Public Types inherited from SurfaceFactoryMeshAdapter
typedef int | Index
| Integer type representing a mesh index.
typedef std::intptr_t | FVarID
| Type used to identify and specify face-varying primvars.
Protected Member Functions inherited from SurfaceFactoryMeshAdapter
virtual bool | isFaceHole (Index faceIndex) const =0
| Returns if a face is a hole.
virtual int | getFaceSize (Index faceIndex) const =0
| Returns the size of a face (number of vertices).
virtual int | getFaceVertexIndices (Index faceIndex, Index vertexIndices[]) const =0
| Gather the indices of the face's vertices.
virtual int | getFaceFVarValueIndices (Index faceIndex, FVarID fvarID, Index fvarValueIndices[]) const =0
| Gather the face-varying indices of the face's vertices.
virtual int | populateFaceVertexDescriptor (Index faceIndex, int faceVertex, VertexDescriptor *vertexDescriptor) const =0
| Describe the topology of incident faces around a face-vertex.
virtual int | getFaceVertexIncidentFaceVertexIndices (Index faceIndex, int faceVertex, Index vertexIndices[]) const =0
| Gather vertex indices of incident faces around a face-vertex.
virtual int | getFaceVertexIncidentFaceFVarValueIndices (Index faceIndex, int faceVertex, FVarID fvarID, Index fvarValueIndices[]) const =0
| Gather face-varying indices of incident faces around a face-vertex.
virtual bool | getFaceNeighborhoodVertexIndicesIfRegular (Index faceIndex, Index vertexIndices[]) const
virtual bool | getFaceNeighborhoodFVarValueIndicesIfRegular (Index faceIndex, FVarID fvarID, Index fvarValueIndices[]) const

## Detailed Description

Base class providing initialization of a Surface for each face of a mesh.

SurfaceFactory is an abstract class that provides the majority of the implementation and the interface for a factory that initializes instances of Surface for the faces of a mesh.

A subclass of SurfaceFactory is written to support a specific type of connected mesh. The public interface of SurfaceFactory is both inherited by and extended by the subclasses. Expected extensions to the interface include one or more constructors (i.e. given a specific instance of the subclass' mesh type) as well as other methods that may involve the mesh's data types (primvars) in their native form.

By inheriting the SurfaceFactoryMeshAdapter interface, SurfaceFactory requires its subclasses to implement the small suite of pure virtual methods to complete the factory's implementation for the subclass' mesh type. These methods provide the base factory with topological information about faces of that mesh – from which it creates instances of Surface defining their limit surface.

The SurfaceFactory inherits rather than contains SurfaceFactoryMeshAdapter as instances of SurfaceFactoryMeshAdapter serve no purpose on their own, and the interface between the two is designed with the specific needs of the SurfaceFactory. When customizing a subclass of SurfaceFactory for a particular mesh type, this inheritance also avoids the need to coordinate the subclass of SurfaceFactory with the separate subclass of SurfaceFactoryMeshAdapter.

It must be emphasized that a subclass of SurfaceFactory is written to support a specific type of "connected" mesh – not simply a container of data defining a mesh. The SurfaceFactoryMeshAdapter interface describes the complete topological neighborhood around a specific face, and without any connectivity between mesh components (e.g. given a vertex, what are its incident faces?), satisfying these methods will be impossible, or, at best, extremely inefficient.

Ultimately a subclass of SurfaceFactory is expected to be a lightweight interface to a connected mesh – lightweight in terms of both time and memory usage. It's construction is expected to be trivial, after which it can quickly and efficiently provide a Surface for one or more faces of a mesh for immediate evaluation. So construction of an instance of a subclass should involve no heavy pre-processing – the greater the overhead of a subclass constructor, the more it violates the intention of the base class as a lightweight interface.

Instances of SurfaceFactory are initialized with a set of Options that form part of the state of the factory and remain fixed for its lifetime. Such options are intended to ensure that the instances of Surface that it creates are consistent, as well as to enable/disable or otherwise manage caching for construction efficiency – either internally or between itself and other factories (advanced).

Definition at line 86 of file surfaceFactory.h.

## Constructor & Destructor Documentation

## ◆ ~SurfaceFactory()

~SurfaceFactory | ( |  | ) |
| override

## ◆ SurfaceFactory() [1/2]

SurfaceFactory | ( | Sdc::SchemeType | schemeType,
|  | Sdc::Options const & | schemeOptions,
|  | Options const & | limitOptions )
| protected

Constructor to be used by subclasses.

Construction requires specification of the subdivision scheme and options associated with the mesh (as is the case with other classes in Far). These will typically reflect the settings in the mesh but can also be used to override them – as determined by the subclass. Common uses of overrides are to assign a subdivision scheme to a simple polygonal mesh, or to change the face-varying interpolation for the faster linear interpolation of UVs.

## ◆ SurfaceFactory() [2/2]

SurfaceFactory | ( | SurfaceFactory const & |  | ) |
| protecteddelete

## Member Function Documentation

## ◆ CreateFaceVaryingSurface() [1/2]

template<typename REAL>

Surface< REAL > * CreateFaceVaryingSurface | ( | Index | faceIndex | ) | const
| inline

Construct a Surface for the default face-varying data.

Definition at line 534 of file surfaceFactory.h.

## ◆ CreateFaceVaryingSurface() [2/2]

template<typename REAL>

Surface< REAL > * CreateFaceVaryingSurface | ( | Index | faceIndex,
|  | FVarID | id ) const
| inline

Construct a Surface for specified face-varying data.

Definition at line 526 of file surfaceFactory.h.

## ◆ CreateVaryingSurface()

template<typename REAL>

Surface< REAL > * CreateVaryingSurface | ( | Index | faceIndex | ) | const
| inline

Construct a Surface for varying data.

Definition at line 518 of file surfaceFactory.h.

## ◆ CreateVertexSurface()

template<typename REAL>

Surface< REAL > * CreateVertexSurface | ( | Index | faceIndex | ) | const
| inline

Construct a Surface for vertex data.

Definition at line 510 of file surfaceFactory.h.

## ◆ FaceHasLimitSurface()

bool FaceHasLimitSurface | ( | Index | faceIndex | ) | const

Return if a specified face has a limit surface.

This method determines if a face has an associated limit surface, and so supports initialization of Surface for evaluation. This is usually the case, except when the face is tagged as a hole, or due to the use of uncommon boundary interpolation options (i.e. Sdc::Options::VTX_BOUNDARY_NONE). The test of a hole is trivial, but the boundary test is not when such uncommon options are used.

## ◆ GetFaceParameterization()

Parameterization GetFaceParameterization | ( | Index | faceIndex | ) | const

Return the Parameterization of a face with a limit surface.

This method simply returns the Parameterization of the specified face. It is presumed the face has an existing limit surface and so is a quick and simple accessor.

## ◆ GetSchemeOptions()

Sdc::Options GetSchemeOptions | ( |  | ) | const
| inline

Return the set of subdivision options.

Definition at line 156 of file surfaceFactory.h.

## ◆ GetSchemeType()

Sdc::SchemeType GetSchemeType | ( |  | ) | const
| inline

Return the subdivision scheme.

Definition at line 153 of file surfaceFactory.h.

## ◆ InitFaceVaryingSurface() [1/2]

template<typename REAL>

bool InitFaceVaryingSurface | ( | Index | faceIndex,
|  | Surface< REAL > * | surface ) const
| inline

Initialize a Surface for the default face-varying data.

For this variant, no explicit face-varying ID is specified. The default is determined from the Options with which the SurfaceFactory was created (assignment of that default is required).

Parameters

  faceIndex | Index of face with limit surface of interest
  surface | Surface to initialize for face-varying data

Returns
  True if the face has a limit surface, the default face-varying ID was valid, and its Surface was successfully constructed

Definition at line 483 of file surfaceFactory.h.

## ◆ InitFaceVaryingSurface() [2/2]

template<typename REAL>

bool InitFaceVaryingSurface | ( | Index | faceIndex,
|  | Surface< REAL > * | surface,
|  | FVarID | fvarID ) const
| inline

Initialize a Surface for specified face-varying data.

Parameters

  faceIndex | Index of face with limit surface of interest
  surface | Surface to initialize for face-varying data
  fvarID | Identifier of a specific set of face-varying data

Returns
  True if the face has a limit surface, the given face-varying ID was valid, and its Surface was successfully constructed

Definition at line 477 of file surfaceFactory.h.

## ◆ InitSurfaces()

template<typename REAL>

bool InitSurfaces | ( | Index | faceIndex,
|  | Surface< REAL > * | vtxSurface,
|  | Surface< REAL > * | fvarSurfaces,
|  | FVarID const | fvarIDs[] = 0,
|  | int | fvarCount = 0,
|  | Surface< REAL > * | varSurface = 0 ) const
| inline

Initialize multiple Surfaces at once.

This method initializes multiple Surfaces at once – for any combination of the three different data interpolation types. Its use is recommended when two are more surfaces are known to be non-linear, which will avoid the repeated effort if each Surface is individually initialized.

Arguments are ordered here to satisfy common cases easily with the use of optional arguments for less common cases.

Parameters

  faceIndex | Index of face with limit surfaces of interest
  vtxSurface | Surface to initialize for vertex data
  fvarSurfaces | Surface array to initialize for face-varying data
  fvarIDs | Array of face-varying IDs corresponding to the face-varying Surfaces to be initialized (optional – defaults to an integer sequence [0 .. fvarCount-1] if absent)
  fvarCount | Size of array of face-varying Surfaces (optional)
  varSurface | Surface to initialize for varying data (optional)

Returns
  True if the face has a limit surface, any given face-varying IDs were valid, and all Surfaces were successfully constructed.

Definition at line 490 of file surfaceFactory.h.

## ◆ InitVaryingSurface()

template<typename REAL>

bool InitVaryingSurface | ( | Index | faceIndex,
|  | Surface< REAL > * | surface ) const
| inline

Initialize a Surface for varying data.

Parameters

  faceIndex | Index of face with limit surface of interest
  surface | Surface to initialize for varying data

Returns
  True if the face has a limit surface and it was successfully constructed

Definition at line 471 of file surfaceFactory.h.

## ◆ InitVertexSurface()

template<typename REAL>

bool InitVertexSurface | ( | Index | faceIndex,
|  | Surface< REAL > * | surface ) const
| inline

Initialize a Surface for vertex data.

Parameters

  faceIndex | Index of face with limit surface of interest
  surface | Surface to initialize for vertex data

Returns
  True if the face has a limit surface and it was successfully constructed

Definition at line 465 of file surfaceFactory.h.

## ◆ operator=()

SurfaceFactory & operator= | ( | SurfaceFactory const & |  | ) |
| protecteddelete

## ◆ setInternalCache()

void setInternalCache | ( | SurfaceFactoryCache * | cache | ) |
| protected

Subclass to identify an internal cache for use by base class.

The documentation for this class was generated from the following file:

- opensubdiv/bfr/surfaceFactory.h