Writing a host bridge

Load the groomCopy Anchor Link

#include "groomlab/groomlab.hpp"
namespace gl = groomlab::api;

gl::Session session = gl::Session::fromFile("C:/shots/010/hair.groom");

The file brings the graph, guides, scalp, colliders, maps, controls and frame rate. Texture maps with relative paths resolve against the file's folder, then its search paths (session.setSearchPaths).

A Z-up host turns the groom into its axis right away, before feeding any points:

session.setUpAxis("Z");   // the scalp, guides, colliders and world-direction params, a quarter about X

See Units and up axis below.

The library does not open the Alembic caches a file names (an animated scalp, guide caches, simulation bakes). Your bridge feeds the motion itself, as below.

Making a Session also checks that the library's API version matches the header's. In C, check GROOMLAB_C_API_COMPATIBLE(gl_api_version()) once at load time.

Give it the scalpCopy Anchor Link

A groom file already holds the scalp it was made on. When the host has that same mesh (the same points in the same order), feed only its points:

std::vector<float> rest = hostPointsAtRest();   // x y z per point, in the groom's units and axis
session.updateScalpPoints(rest, &rest);         // the rest pose, once

To grow on another mesh, hand the whole mesh to setScalp: points, polygon sizes, point indices and, optionally, UVs per polygon corner.

session.setScalp(points, faceCounts, faceIndices, uvs);   // uvs: u v per corner, or {}

• GroomLab cuts each polygon into a fan of triangles from its first corner. Guides and strands are rooted on those triangles, so a different mesh (or the same mesh triangulated differently) moves them. To keep a groom exactly, feed the file's own triangles: three-corner faces in the order of its "triangles".
• The groom remembers the scalp it was made on (its fingerprint). When the mesh you give has another point order or other triangles, evalErrorsJson() says "the scalp's vertex order or triangles differ from the groom's: strands are rooted again by position". The strands still come, but they are not the file's. Show it to the artist.
• Pass UVs when the groom reads texture maps or the rootUV attribute.
• setScalp replaces the rest pose too: the mesh you give is the rest.

Deform per frameCopy Anchor Link

For each frame, set the time and the scalp's points at that time:

session.setFrame(frame);                       // seconds by every host's rule (below)
session.updateScalpPoints(hostPointsAt(frame));

setFrame turns the frame into seconds the way Maya, the CLI and the Arnold procedural do: frame / fps, an NTSC rate exact (23.976 is 24000 / 1001). Use it, or gl_frame_to_seconds, rather than dividing yourself: an ulp of difference in the time moves Wind's strands.

• The point count must stay the scalp's (scalpPointCount()). Topology and UVs stay as set.
• Keep the rest pose set (step 2). Strands then keep their count, IDs and roots while the scalp moves; only their shape follows.
• Set host-driven values with session.setControl("name", value). Params animated in Maya are linked to controls; the file stores the controls' values when it was saved, not their keys, so set them per frame if your host animates them.
• Keep one session for the whole shot. It caches what does not change, so later frames cost less.

Evaluate and read the strandsCopy Anchor Link

gl::EvalOptions options;
options.density = 0.25f;                       // a viewport preview; 1 for the render
gl::Strands strands = session.evaluate(options);

gl::View<float> points = strands.positions();       // x y z per point, strand after strand
gl::View<std::uint64_t> first = strands.offsets();  // strand s: points first[s] to first[s + 1] - 1
gl::View<float> widths = strands.widths();          // per point, a diameter in scene units
gl::View<std::uint64_t> ids = strands.ids();        // per strand, stable across frames and densities

Attributes carry the look. List them with attributes() (each with its scope); read one with attribute(name), or attribute(name, scope) when a name is there in both scopes:

gl::Attribute color = strands.attribute("color");  // color.values: 3 floats per strand
gl::Attribute banded = strands.attribute("colorR", gl::Scope::Point);  // a banded HairColor's, per point

A name can be listed twice, once per scope: a banded HairColor writes colorR, colorG and colorB per strand and per point. attribute(name) gives the per strand one.

A result is independent of the session. You can hand it to another thread for drawing while the session evaluates the next frame.

If a node fails, the evaluation still returns what the rest made. Show session.evalErrorsJson() to the artist when it is not [].

Render or exportCopy Anchor Link

Turn the strands into the host's curves:

• Points: linear curves, one per strand, from positions() and offsets(). Scale units here (cm by default); the up axis is the groom's (setUpAxis).
• Width: most renderers take a per-point width (a diameter). Some take a radius: halve it.
• IDs: keep ids() as a per-curve attribute. Motion blur and caches match strands across frames by ID.
• Color: color and melanin map onto the host's hair shader.

For a cache, write one sample per frame: Alembic curves or USD BasisCurves (linear, widths per vertex) take these arrays as they are.