ClusterProperty Class
Reference
#include <xsi_clusterproperty.h>
Represents a property of a cluster.
Values contained by the cluster property can be accessed with ClusterProperty::GetElements or ClusterProperty::GetValues.
ClusterProperty::GetElements returns a CClusterPropertyElementArray object. This object can be used to access the entire value array with CClusterPropertyElementArray::GetArray or individual values via CClusterPropertyElementArray::GetItems. GetIems returns an array of double values.
ClusterProperty::GetValues is typically used to access the data on ClusterProperty objects generated by the CGeometryAccessor object. This method is more efficient than the one above as it doesn't need any intermediate objects to access the values. All values are returned in one single array of the size of the geometry elements. The array is indexed with cluster element indices. ClusterProperty::GetValues allows you to perform fast iteration over the array by using a CBitArray object and skipping the cluster elements that are not part of the cluster property. ClusterProperty::GetValues is especially suited for writing exporter applications as it is designed to access large data sets more easily and faster than ClusterProperty::GetElements.
In the case of ShapeKey cluster properties, values returned by ClusterProperty::GetValues are automatically converted to object relative reference mode, which is not the case for ClusterProperty::GetElements. For more information about shape reference modes, see Shape Animation
using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot();
X3DObject myCube;
root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );
// install the texture support object
CValueArray args(4);
args[0] = CValue( CString(L"Image") );
args[1] = CValue(myCube);
args[2] = CValue((short)1);
args[3] = CValue(false);
CStatus st;
CValue outArg;
st = app.ExecuteCommand( L"BlendInPresets", args, outArg );
if ( st.GetCode() != CStatus::OK )
{
app.LogMessage( L"BlendInPresets failed" );
return;
}
args[0] = CValue(myCube);
args[1] = CValue((LONG)siTxtUV);
args[2] = CValue((LONG)siTxtDefaultSpherical);
args[3] = CValue(CString(L"Texture_Support"));
st = app.ExecuteCommand( L"CreateTextureSupport", args, outArg );
if ( st.GetCode() != CStatus::OK )
{
app.LogMessage( L"CreateTextureSupport failed" );
return;
}
// get the uv data on the cube
PolygonMesh pm = myCube.GetActivePrimitive().GetGeometry();
CGeometryAccessor ga = pm.GetGeometryAccessor();
CRefArray uvs = ga.GetUVs();
LONG nUVs = uvs.GetCount();
// iterate over the uv data
for ( LONG i=0; i<nUVs; i++ )
{
ClusterProperty uv(uvs[i]);
app.LogMessage( uv.GetName() );
// get the values
CFloatArray uvValues;
uv.GetValues( uvValues );
// log the values
LONG nValues = uvValues.GetCount();
for ( LONG idxElem=0; idxElem<nValues; idxElem += 3)
{
CString X(uvValues[idxElem]);
CString Y(uvValues[idxElem+1]);
CString W(uvValues[idxElem+2]);
app.LogMessage( CString(idxElem/3) + L": " + X + L" "+ Y + L" "+ W );
}
}
// iterate over the uv data using a CBitArray object
for ( LONG i=0; i<nUVs; i++ )
{
ClusterProperty uv(uvs[i]);
app.LogMessage( uv.GetName() );
// get the values and the element set
CBitArray elemSet;
CFloatArray uvValues;
uv.GetValues( uvValues, elemSet );
// log the values by iterating over the cluster elements adressed by
// the property
LONG idxElem = elemSet.GetIterator();
while ( elemSet.GetNextTrueBit(idxElem) )
{
LONG nIdx = idxElem*3;
CString X(uvValues[nIdx]);
CString Y(uvValues[nIdx+1]);
CString W(uvValues[nIdx+2]);
app.LogMessage( CString(idxElem) + L": " + X + L" "+ Y + L" "+ W );
}
}
// Expected results for both loops:
//'INFO : Texture_Support
//'INFO : 0: 0.125 0.304087 0
//'INFO : 1: 0.125 0.695913 0
//'INFO : 2: -0.125 0.695913 0
//'INFO : 3: -0.125 0.304087 0
//'INFO : 4: 0.125 0.304087 0
//'INFO : 5: 0.875 0.304087 0
//'INFO : 6: 0.625 0.304087 0
//'INFO : 7: 0.375 0.304087 0
//'INFO : 8: 0.125 0.304087 0
//'INFO : 9: 0.375 0.304087 0
//'INFO : 10: 0.375 0.695913 0
//'INFO : 11: 0.125 0.695913 0
//'INFO : 12: 0.875 0.304087 0
//'INFO : 13: 0.875 0.695913 0
//'INFO : 14: 0.625 0.695913 0
//'INFO : 15: 0.625 0.304087 0
//'INFO : 16: 0.125 0.695913 0
//'INFO : 17: 0.375 0.695913 0
//'INFO : 18: 0.625 0.695913 0
//'INFO : 19: 0.875 0.695913 0
//'INFO : 20: 0.375 0.304087 0
//'INFO : 21: 0.625 0.304087 0
//'INFO : 22: 0.625 0.695913 0
//'INFO : 23: 0.375 0.695913 0
using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot();
X3DObject myCube;
root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );
// install the texture support object
CValueArray args(4);
args[0] = CValue( CString(L"Image") );
args[1] = CValue(myCube);
args[2] = CValue((short)1);
args[3] = CValue(false);
CStatus st;
CValue outArg;
st = app.ExecuteCommand( L"BlendInPresets", args, outArg );
if ( st.GetCode() != CStatus::OK )
{
app.LogMessage( L"BlendInPresets failed" );
return;
}
args[0] = CValue(myCube);
args[1] = CValue((LONG)siTxtUV);
args[2] = CValue((LONG)siTxtDefaultSpherical);
args[3] = CValue(CString(L"Texture_Support"));
st = app.ExecuteCommand( L"CreateTextureSupport", args, outArg );
if ( st.GetCode() != CStatus::OK )
{
app.LogMessage( L"CreateTextureSupport failed" );
return;
}
// get the sample point cluster
Geometry geom(myCube.GetActivePrimitive().GetGeometry());
CRefArray samplePoints;
geom.GetClusters().Filter( siSampledPointCluster,
CStringArray(),
L"",
samplePoints );
Cluster cluster(samplePoints.GetItem(0));
ClusterProperty UVWProp(myCube.GetMaterial().GetCurrentUV());
app.LogMessage( L"Cluster property class ID: " +
UVWProp.GetClassIDName() );
app.LogMessage( L"Cluster property type: " + UVWProp.GetType() );
app.LogMessage( L"Cluster property name: " + UVWProp.GetName() );
Public Member Functions |
|
| ClusterProperty () | |
| ~ClusterProperty () | |
| ClusterProperty (const CRef &in_ref) | |
| ClusterProperty (const ClusterProperty &in_obj) | |
| bool | IsA (siClassID in_ClassID) const |
| siClassID | GetClassID () const |
| ClusterProperty & | operator= (const ClusterProperty &in_obj) |
| ClusterProperty & | operator= (const CRef &in_ref) |
| CClusterPropertyElementArray | GetElements () const |
| LONG | GetValueSize () const |
| siClusterPropertyType | GetPropertyType () const |
| CValue::DataType | GetInternalType () const |
| CStatus | GetValues (CFloatArray &out_data) const |
| CStatus | GetValues (CFloatArray &out_data, CBitArray &out_elemIdx) const |
| CStatus | SetValues (const float *in_pValues, LONG in_nValues, LONG in_nOffset=0) |
| CStatus | SetValues (const LONG *in_pElements, const float *in_pValues, LONG in_nElements) |
| ClusterProperty | ( | ) |
Default constructor.
| ~ClusterProperty | ( | ) |
Default destructor.
| ClusterProperty | ( | const CRef & | in_ref | ) |
Constructor.
| in_ref | constant reference object. |
| ClusterProperty | ( | const ClusterProperty & | in_obj | ) |
Copy constructor.
| in_obj | constant class object. |
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from Property.
Reimplemented in EnvelopeWeight, ShapeKey, and UVProperty.
| siClassID GetClassID | ( | ) | const [virtual] |
Returns the type of the API class.
Reimplemented from Property.
Reimplemented in EnvelopeWeight, ShapeKey, and UVProperty.
| ClusterProperty& operator= | ( | const ClusterProperty & | in_obj | ) |
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
| in_obj | constant class object. |
| ClusterProperty& operator= | ( | const CRef & | in_ref | ) |
Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.
| in_ref | constant class object. |
Reimplemented from Property.
Reimplemented in EnvelopeWeight, ShapeKey, and UVProperty.
| CClusterPropertyElementArray GetElements | ( | ) | const |
Returns an array of geometry indices represented by the cluster.
| LONG GetValueSize | ( | ) | const |
Returns the number of values per element in the cluster property data. For instance, a uvw cluster property returns 3(uvw) and in the case of a vertex color cluster property it returns 4(rgba).
| siClusterPropertyType GetPropertyType | ( | ) | const |
| CValue::DataType GetInternalType | ( | ) | const |
Returns the internal type of the cluster property elements which represents the data. In general, all elements are represented internally as float. However. types such as the vertex color type is represented as short (rgba). For instance, you can use the internal data type if you need to compress the memory allocated for storing vertex color values.
| CStatus GetValues | ( | CFloatArray & | out_data | ) | const |
Returns an array of cluster element values. The number of elements in the array matches the number of geometry elements (N), the array size is N * ClusterProperty::GetSizeValue.
| out_data | Array of float values. |
| CStatus GetValues | ( | CFloatArray & | out_data, |
| CBitArray & | out_elemIdx | ||
| ) | const |
Returns an array of cluster element values. The number of elements in the array matches the number of geometry elements (N), the array size is N * ClusterProperty::GetSizeValue. The function also returns a bit array of size N which identifies the indices of the geometry elements set in the array. You can use the bit array items to quickly identify what are the geometry elements affected by the cluster property.
| out_data | Array of float values. |
| out_elemIdx | Array of element index flags. |
| CStatus SetValues | ( | const float * | in_pValues, |
| LONG | in_nValues, | ||
| LONG | in_nOffset =
0 |
||
| ) |
Sets the geometry elements exposed by this cluster property.
This function sets the geometry elements in the order specified by
in_pValues starting from index 0. The values are set
directly on the property and the operation is not undoable.
For large data sets, you can use an offset index to set the values in chunks. The offset is used for indexing into the cluster elements which allows you to optimize the memory allocation required for setting the element values.
| in_pValues | Array of size in_nValues *
ClusterProperty::GetSizeValue containing the element values. |
| in_nValues | This value corresponds to the number of cluster elements to set
and doesn't correspond to the number of items in
in_pValues. The number of values in
in_pValues corresponds to the cluster property data
size (specified by ClusterProperty::GetSizeValue) *
in_nValues. |
| in_nOffset | Specifies the starting index in the cluster elements. |
in_nElements is greater than the number of cluster
elements or smaller than zero. Also returns an error if
in_pValues is invalid.| CStatus SetValues | ( | const LONG * | in_pElements, |
| const float * | in_pValues, | ||
| LONG | in_nElements | ||
| ) |
Sets the geometry element exposed by this cluster property. This function sets the values directly on the property and the operation is not undoable.
| in_pElements | Array of size in_nElements containing the geometry
elements to set. |
| in_pValues | Array of size in_nElements *
ClusterProperty::GetValueSize containing the values. |
| in_nElements | Number of elements in in_pElements. |
in_nElements is greater than the number of cluster
elements or smaller than zero. Also returns an error if
in_pElements or in_pValues are
invalid.