API Reference — dna/layers/DefinitionWriter

class DNAAPI DefinitionWriter : public DescriptorWriter

Write the rig's static data: GUI and raw control names, joint names and joint index lists.

When to use this

Use this interface when constructing or mutating the structural (non-animated) portion of a DNA rig: assigning names to GUI/raw controls, joints, blend shape channels, animated maps, and meshes; wiring those elements into LOD tiers; and setting the joint hierarchy and neutral-pose transforms. Do not subclass DefinitionWriter directly — the @warning in the class docstring requires implementors to inherit from Writer instead, which composes all layer interfaces.

Use it when you build or modify a DNA definition. Implementors should inherit from Writer itself, not from this class.

Method groups

Group Methods
GUI Controls clearGUIControlNames, setGUIControlName
Raw Controls clearRawControlNames, setRawControlName
Joints clearJointNames, setJointName, clearJointIndices, setJointIndices, clearLODJointMappings, setLODJointMapping, setJointHierarchy, setNeutralJointTranslations, setNeutralJointRotations
Blend Shape Channels clearBlendShapeChannelNames, setBlendShapeChannelName, clearBlendShapeChannelIndices, setBlendShapeChannelIndices, clearLODBlendShapeChannelMappings, setLODBlendShapeChannelMapping
Animated Maps clearAnimatedMapNames, setAnimatedMapName, clearAnimatedMapIndices, setAnimatedMapIndices, clearLODAnimatedMapMappings, setLODAnimatedMapMapping
Meshes clearMeshNames, setMeshName, clearMeshIndices, setMeshIndices, clearLODMeshMappings, setLODMeshMapping, clearMeshBlendShapeChannelMappings, setMeshBlendShapeChannelMapping

Example

// writer is a concrete Writer* obtained from a factory (inherits DefinitionWriter)
// --- GUI / Raw controls ---
writer->clearGUIControlNames();
writer->setGUIControlName(0, "CTRL_L_eye_blink");
writer->setGUIControlName(1, "CTRL_R_eye_blink");

writer->clearRawControlNames();
writer->setRawControlName(0, "raw_L_eye_blink");

// --- Joints ---
writer->clearJointNames();
writer->setJointName(0, "spine_01");
writer->setJointName(1, "neck_01");
writer->setJointName(2, "head");

// Joint hierarchy: spine_01 is root (index 0); neck_01 and head are children of spine_01
const std::uint16_t hierarchy[] = {0, 0, 1};
writer->setJointHierarchy(hierarchy, 3);

// Neutral-pose translations
const Vector3 translations[] = {{0.0f, 0.0f, 0.0f}, {0.0f, 10.0f, 0.0f}, {0.0f, 5.0f, 0.0f}};
writer->setNeutralJointTranslations(translations, 3);

// Assign joints to LOD 0 via an index list
const std::uint16_t lod0Joints[] = {0, 1, 2};
writer->clearJointIndices();
writer->setJointIndices(0, lod0Joints, 3);
writer->clearLODJointMappings();
writer->setLODJointMapping(/*lod=*/0, /*index=*/0);

// --- Blend shape channels ---
writer->clearBlendShapeChannelNames();
writer->setBlendShapeChannelName(0, "browInnerUp_L");

// Associate blend shape channel 0 with mesh 0
writer->clearMeshBlendShapeChannelMappings();
writer->setMeshBlendShapeChannelMapping(/*mappingIndex=*/0, /*meshIndex=*/0, /*bsChannelIndex=*/0);

Parameters

Name Type Description
index std::uint16_t required. Position in the zero-indexed array. Storage is resized implicitly to fit.
name const char* required. Null-terminated string. It is copied, which allocates.

Constraints

  • Storage is resized implicitly based on the index passed in.
  • For joint indices, index is the position of an entire list (a row in a 2D matrix), not of an element.

Watch out for

  • Names passed in are copied, which costs an additional allocation.
  • Joint indices can be used to look up names through DefinitionReader::getJointName.
  • Implementors must inherit from Writer, not DefinitionWriter directly. The class docstring carries an explicit @warning to this effect. Subclassing DefinitionWriter alone bypasses the full Writer composition and will produce an incomplete interface.
  • setLODBlendShapeChannelMapping uses an independent LOD index space from BehaviorWriter::setBlendShapeChannelLODs. The docstring for that method explicitly notes these values are not interchangeable — mixing them causes silent mapping corruption.
  • All set*Name methods copy the passed string, incurring an extra allocation. Callers can free the source buffer immediately after the call but should not assume zero-copy semantics.
  • Storage for names and indices is implicitly resized by index. Writing to index 5 without writing indices 0–4 leaves those slots in an unspecified state. Populate slots in order or call the corresponding clear* method first to reset.
  • setJointHierarchy encodes the entire parent array in one call — the array position is the child joint index and the value is the parent joint index. The root joint(s) reference themselves (value equals their own index, typically 0).