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:

C++ Example: Applying a User Data Map to the edges of a sphere

// 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) );