Instantiating an HbrMesh

First we need to instantiate a mesh object.

Hbr supports 3 subdivision schemes:

• Catmull-Clark (catmark)
• Loop
• Bilinear

The scheme is selected by passing an specialized instance of HbrSubdivision<T>, HbrCatmarkSubdivision<T> in this case. The scheme can be shared across multiple mesh objects, so we only need a single instance.

static OpenSubdiv::HbrCatmarkSubdivision<Vertex> _scheme;

OpenSubdiv::HbrMesh<Vertex> * mesh = new OpenSubdiv::HbrMesh<Vertex>( _scheme );

Creating Vertices

Adding vertices to the mesh is accomplished using the HbrMesh::NewVertex() method.

Because Hbr uses a dedicated vertex allocator to help alleviate the performance impact of intensive fragmented memory allocations. This optimization results in the following design pattern:

Vertex vtx;
for(int i=0;i<numVerts; i++ ) {
    Vertex * v = mesh->NewVertex( i, vtx);

    // v->SetPosition();
}

We instantiate a single "default" vertex object named 'vtx' on the stack. We then recover the pointer to the actual vertex created in the mesh from the NewVertex() method. Once we have recovered that pointer, we can set the data for our vertex by using any of the custom accessors.

Creating Faces

Once all the vertices have been registered in the mesh, we can start adding the faces with HbrMesh::NewFace(). Assuming we had an obj style reader, we need to know the number of vertices in the face and the indices of these vertices.

for (int f=0; f<numFaces; ++f) {

    int nverts = obj->GetNumVertices(f);

    const int * faceverts = obj->GetFaceVerts(f);

    mesh->NewFace(nv, fv, 0);
}

However, currently Hbr is not able to handle non-manifold geometry. In order to avoid tripping asserts or causing memory violations, let's rewrite the previous loop with some some prototype code to check the validity of the topology.

for (int f=0; f<numFaces; ++f) {

    int nv = obj->GetNumVertices(f);

    const int * fv = obj->GetFaceVerts(f);

    // triangles only for Loop subdivision !
    if ((scheme==kLoop) and (nv!=3)) {
        printf("Trying to create a Loop subd with non-triangle face\n");
        continue;
    }

    // now check the half-edges connectivity
    for(int j=0;j<nv;j++) {
        OpenSubdiv::HbrVertex<T> * origin      = mesh->GetVertex( fv[j] );
        OpenSubdiv::HbrVertex<T> * destination = mesh->GetVertex( fv[(j+1)%nv] );
        OpenSubdiv::HbrHalfedge<T> * opposite  = destination->GetEdge(origin);

        if(origin==NULL || destination==NULL) {
            printf(" An edge was specified that connected a nonexistent vertex\n");
            continue;
        }

        if(origin == destination) {
            printf(" An edge was specified that connected a vertex to itself\n");
            continue;
        }

        if(opposite && opposite->GetOpposite() ) {
            printf(" A non-manifold edge incident to more than 2 faces was found\n");
            continue;
        }

        if(origin->GetEdge(destination)) {
            printf(" An edge connecting two vertices was specified more than once."
                   " It's likely that an incident face was flipped\n");
            continue;
        }
    }

    mesh->NewFace(nv, fv, 0);
}

Wrapping Things Up

Once we have vertices and faces set in our mesh, we still need to wrap things up by calling HbrMesh::Finish():

mesh->Finish()

Finish iterates over the mesh to apply the boundary interpolation rules and checks for singular vertices. At this point, there is one final topology check remaining to validate the mesh:

mesh->Finish()

if (mesh->GetNumDisconnectedVertices()) {
    printf("The specified subdivmesh contains disconnected surface components.\n");

    // abort or iterate over the mesh to remove the offending vertices
}

Vertex Creases

Given an index, vertices are very easy to access in the mesh.

int idx;     // vertex index
float sharp; // the edge sharpness

OpenSubdiv::HbrVertex<Vertex> * v = mesh->GetVertex( idx );

if(v) {
    v->SetSharpness( std::max(0.0f, sharp) );
} else
   printf("cannot find vertex for corner tag (%d)\n", idx );

Edge Creases

Usually, edge creases are described with a vertex indices pair. Here is some sample code to locate the matching half-edge and set a crease sharpness.

int v0, v1;  // vertex indices
float sharp; // the edge sharpness

OpenSubdiv::HbrVertex<Vertex> * v = mesh->GetVertex( v0 ),
                              * w = mesh->GetVertex( v1 );

OpenSubdiv::HbrHalfedge<Vertex> * e = 0;

if( v && w ) {

    if((e = v->GetEdge(w)) == 0)
        e = w->GetEdge(v);

    if(e) {
        e->SetSharpness( std::max(0.0f, sharp) );
    } else
       printf("cannot find edge for crease tag (%d,%d)\n", v0, v1 );
}

Instantiating the HbrMesh

The HbrMesh needs to retain some knowledge about the face-varying data that it carries in order to refine it correctly.

int fvarwidth = 2; // total width of the fvar data

static int indices[1] = { 0 }, // 1 offset set to 0
           widths[1] = { 2 };  // 2 floats in a (u,v) pair

int const   fvarcount   = fvarwidth > 0 ? 1 : 0,
          * fvarindices = fvarwidth > 0 ? indices : NULL,
          * fvarwidths  = fvarwidth > 0 ? widths : NULL;

mesh = new OpenSubdiv::HbrMesh<T>( &_scheme,
                                   fvarcount,
                                   fvarindices,
                                   fvarwidths,
                                   fvarwidth );

Setting the Face-Varying Data

After the topology has been created, Hbr is ready to accept face-varying data. Here is some sample code:

for (int i=0, idx=0; i<numFaces; ++i ) {

    OpenSubdiv::HbrFace<Vertex> * f = mesh->GetFace(i);

    int nv = f->GetNumVertices(); // note: this is not the fastest way

    OpenSubdiv::HbrHalfedge<Vertex> * e = f->GetFirstEdge();

    for (int j=0; j<nv; ++j, e=e->GetNext()) {

        OpenSubdiv::HbrFVarData<Vertex> & fvt = e->GetOrgVertex()->GetFVarData(f);

        float const * fvdata = GetFaceVaryingData( i, j );

        if (not fvt.IsInitialized()) {

            // if no fvar daa exists yet on the vertex
            fvt.SetAllData(2, fvdata);

        } else if (not fvt.CompareAll(2, fvdata)) {

            // if there already is fvar data and there is a boundary add the new data
            OpenSubdiv::HbrFVarData<T> & nfvt = e->GetOrgVertex()->NewFVarData(f);
            nfvt.SetAllData(2, fvdata);

        }
    }
}

Retrieving the Face-Varying Data

The HbrFVarData structures are expanded during the refinement process, with every sub-face being assigned a set of interpolated face-varying data. This data can be accessed in 2 ways :

From a face, passing a vertex index:

// OpenSubdiv::HbrFace<Vertex> * f

OpenSubdiv::HbrFVarData const &fv = f.GetFVarData(vindex);

const float * data = fv.GetData()

From a vertex, passing a pointer to an incident face:

// OpenSubdiv::HbrFace<Vertex> * f

OpenSubdiv::HbrFVarData const &fv = myVertex.GetFVarData(f);

const float * data = fv.GetData()