Houdini Engine 1.9
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages

About Houdini Attributes

Houdini has an unparalleled ability to store meta-data. Where geometries are concerned, meta-data can be attached at four possible levels (or owners - HAPI_AttributeOwner):

  1. The geometry itself (detail attributes - HAPI_ATTROWNER_DETAIL).
  2. On each face of the geometry (face attributes - HAPI_ATTROWNER_PRIM).
  3. On each point of the geometry (point attributes - HAPI_ATTROWNER_POINT).
  4. On each vertex of the geometry (vertex attributes - HAPI_ATTROWNER_VERTEX).

This sort of data, whether per geometry, per face, per point, or per vertex, is known as attributes. Attributes may be of int, float, or string types, and they may have any tuple size up to 16, where vector attributes would have a tuple size of 3 or 4.

This ability to store arbitrary data at all levels of the geometry is incredibly powerful, and is one of the key features of Houdini. The use of attributes is so deeply ingrained that point positions are themselves stored as a float point attribute with the reserved name "P" (HAPI_ATTRIB_POSITION) and tuple size of 3. Along with positions, there are many other standard attributes like normals as "N" (HAPI_ATTRIB_NORMAL) and colors as "Cd" (HAPI_ATTRIB_COLOR).

Query Attribute Information

To retrieve or set attribute data you must first know its name. In the case where we want to access the point positions, the name is known to be the pre-defined name "P", or "N" for the normals. However, in the more general case, you might want to query a geometry to see what sort of attributes have been attached to it. To do this call HAPI_GetAttributeNames(). The number of attributes of a specific HAPI_AttributeOwner is stored as an appropriate count on the HAPI_PartInfo.

Once we know the name of the attribute that we wish to retrieve the data for, the next step is to get some information on by calling HAPI_GetAttributeInfo() and filling a HAPI_AttributeInfo struct. Always check HAPI_AttributeInfo::exists before trying to use it.

Getting Attribute Values

Assuming you have a filled HAPI_AttributeInfo as decribed in Query Attribute Information, the HAPI_AttributeInfo::storage, HAPI_AttributeInfo::count, and HAPI_AttributeInfo::tupleSize tell you everything you need to know to allocate an appropriately sized buffer to hold the attribute data. For example, to retrieve point positions from a geometry with 100 points, the HAPI_AttributeInfo::storage would be HAPI_STORAGETYPE_FLOAT, the HAPI_AttributeInfo::count would be 100, and the HAPI_AttributeInfo::tupleSize would be 3. Consequently, we would allocate a buffer to hold 100 * 3 floats. Once the appropriate type and size buffer has been allocated, the data can be retrieved with a call to the appropriate getter function:

For a sample use of these functions, please see Objects, Geos, and Parts Sample.

Adding Attributes

Attributes can only be created on input assets. See Marshalling Geometry Into Houdini.

To create an attribute first create and initialize a HAPI_AttributeInfo struct. You can use the HAPI_AttributeInfo_Create() helper function to initialize. Make sure you set all fields in this struct appropriately given your geometry.

Using the HAPI_AttributeInfo, create a new attribute using HAPI_AddAttribute().

Setting Attribute Values

Mirroring the getter equivalents, here are the attribute setters:

For example, the follow code snippet from the Maya plugin adds the position "P" attribute onto the input geometry, then proceeds to push the actual points into Houdini Engine via HAPI_SetAttributeFloatData():

HAPI_AttributeInfo pos_attr_info;
pos_attr_info.exists = true;
pos_attr_info.owner = HAPI_ATTROWNER_POINT;
pos_attr_info.count = meshFn.numVertices();
pos_attr_info.tupleSize = 3;
myInputAssetId, myInputObjectId, myInputGeoId,
"P", &pos_attr_info );
myInputAssetId, myInputObjectId, myInputGeoId,
"P", &pos_attr_info,
meshFn.getRawPoints( NULL ), 0, meshFn.numVertices() );