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:
Inheritance graph
[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

Default constructor.

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: