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

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation