Public Member Functions
ClusterProperty Class Reference

## Detailed Description

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 ShapeAnimation Shape Animation

See also:
  ClusterProperty::GetValues, CGeometryAccessor, CClusterPropertyElementArray, Cluster, ShapeKey

Example:
  Using ClusterProperty::GetValues

              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

Example:

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

`#include <xsi_clusterproperty.h>`

Inheritance diagram for ClusterProperty:
[legend]

List of all members.

## 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)

## Constructor & Destructor Documentation

ClusterProperty | ( |  | ) |

Default constructor.

~ClusterProperty | ( |  | ) |

Default destructor.

ClusterProperty | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  in_ref | constant reference object.

ClusterProperty | ( | const ClusterProperty & | in_obj | ) |

Copy constructor.

Parameters:

  in_obj | constant class object.

## Member Function Documentation

bool IsA | ( | siClassID | in_ClassID | ) | const `[virtual]`

Returns true if a given class type is compatible with this API class.

Parameters:

  in_ClassID | class type.

Returns:
  true if the class is compatible, false otherwise.

Reimplemented from Property.

Reimplemented in EnvelopeWeight, ShapeKey, and UVProperty.

siClassID GetClassID | ( |  | ) | const `[virtual]`

Returns the type of the API class.

Returns:
  The class type.

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.

Parameters:

  in_obj | constant class object.

Returns:
  The new ClusterProperty 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.

Parameters:

  in_ref | constant class object.

Returns:
  The new ClusterProperty object.

Reimplemented from Property.

Reimplemented in EnvelopeWeight, ShapeKey, and UVProperty.

CClusterPropertyElementArray GetElements | ( |  | ) | const

Returns an array of geometry indices represented by the cluster.

Returns:
  The new CClusterPropertyElementArray object.

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).

Returns:
  The number of values per element.

Since:
  5.0

siClusterPropertyType GetPropertyType | ( |  | ) | const

Returns the type of the cluster property.

Returns:
  Cluster property type.

Since:
  5.0

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.

Returns:
  Data type.

See also:
  ClusterProperty::GetValues

Since:
  5.0

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.

Note:
  Unlike SetValues, GetValues can be used in any context. However, the output data cannot be used with SetValues unless this ClusterProperty instance has been created with CClusterPropertyBuilder

Return values:

  out_data | Array of float values.

Returns:
  CStatus::OK
  CStatus::Fail

See also:
  CGeometryAccessor::GetClusterProperties, Material::GetClusterProperties

Since:
  5.0

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.

Note:
  Unlike SetValues, GetValues can be used in any context. However, the output data cannot be used with SetValues unless this ClusterProperty instance has been created with CClusterPropertyBuilder

Return values:

  out_data | Array of float values.
  out_elemIdx | Array of element index flags.

Returns:
  CStatus::OK
  CStatus::Fail

See also:
  CGeometryAccessor::GetClusterProperties, Material::GetClusterProperties

Since:
  5.0

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.

Note:
  SetValues must be used with ClusterProperty objects returned by CClusterPropertyBuilder methods such as CClusterPropertyBuilder::AddUV and CClusterPropertyBuilder::AddVertexColor. This function is typically used in the context of import/export. Because you cannot build clusters in a custom operator, SetValues cannot be used in this particular context.

Parameters:

  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.

Returns:
  CStatus::OK Success.
  CStatus::InvalidArgument Returns an error if `in_nElements` is greater than the number of cluster elements or smaller than zero. Also returns an error if `in_pValues` is invalid.

See also:
  CClusterPropertyBuilder, CGeometryAccessor::GetClusterProperties, Material::GetClusterProperties

Since:
  5.0

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.

Note:
  SetValues must be used with ClusterProperty objects returned by CClusterPropertyBuilder methods such as CClusterPropertyBuilder::AddUV and CClusterPropertyBuilder::AddVertexColor. This function is typically used in the context of import/export. Because you cannot build clusters in a custom operator, SetValues cannot be used in this particular context.

Parameters:

  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`.

Returns:
  CStatus::OK Success.
  CStatus::InvalidArgument Returns an error if `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.

See also:
  CClusterPropertyBuilder, CGeometryAccessor::GetClusterProperties, Material::GetClusterProperties

Since:
  5.0

The documentation for this class was generated from the following file:

- xsi_clusterproperty.h