Accessing Binary User Data on Components

UserDataMaps or UserDataMaps are similar to UserDataBlobs or UserDataBlobs, but support storing per-component binary data rather than object-level binary data. For example, if some user data is meant to apply to every point in a vertex cluster then it should be stored in a UserDataBlob, whereas, if the user data is meant to apply only to a single vertex, it should be stored at the correct index in a UserDataMap.

Raw binary user data on components is available to plug-in developers through the object model as the UserDataMap object. The user data map attaches to a cluster of components, with individual user data items on the map corresponding to each item in the cluster. Each of these items can contain its own piece of data in binary (BLOB) format. This is similar to a weight map except that instead of storing only floating point values, any kind of data may be attached to each component.

Once you get the UserDataMap object, you can attach or retrieve the data stored on individual components (points, edges, etc.) by one of these methods:

• For scripting and C#, you can get each UserDataItem individually via UserDataMap.Item (UserDataMap.GetItem2 for Python) and then use the UserDataItem.Value property to get the values on the cluster element (component).

• For both the Object Model and the C++ API, you can get the value of the item using UserDataMap.ItemValue property (Object Model) or UserDataMap.GetItemValue member function (C++ API) on the cluster element (component) directly.

• For the C++ API, you can also use UserDataMap::GetValues to get the entire set of user data values stored on the cluster in an array.

// C++ example (using the C++ API) giving an overview of accessing
// per-component user data on a cluster
using namespace XSI;

Application app;
Model root = app.GetActiveSceneRoot();

// equiv: oRoot.AddGeometry( "Sphere", "NurbsSurface" )
X3DObject sphere;
root.AddGeometry( L"Sphere", L"MeshSurface", "SphereWithUserData",sphere);

// Create a cluster containing all the edges on the geometry, then
// create a user data map
Cluster cls;
Geometry geom( myGrid.GetActivePrimitive().GetGeometry(0) );
CLongArray edges(4);
edges[0] = 31; edges[1] = 45; edges[2] = 46; edges[3] = 47; 
geom.AddCluster( siEdgeCluster, L"UserDataCls", edges, cls );

UserDataMap map;
cls.AddProperty( L"UserDataMap", false, L"UserDataBasicExample", map );

// In C++ it is easy and efficient to save binary data instead of strings
unsigned char aExampleData[] = { 0, 23, 1, 244, 20, 99 };

// Copy the data into the user data map
map.PutItemValue( 3, (unsigned char*)&aExampleData,sizeof(aExampleData) );