Public Member Functions
CRenderHairAccessor Class Reference

Detailed Description

This class provides access to the render hair information exposed by the hair primitive. This information includes: the vertex positions of each generated render hair, the root/tip radius values, the UVW, weight map and vertex color values for each render hair root location.

CRenderHairAccessor provides a mechanism to access the data in chunks which allows you to optimize the memory allocation required for accessing such a large data set.

Use HairPrimitive::GetRenderHairAccessor to create an instance of CRenderHairAccessor.

See also:
HairPrimitive
Since:
5.0
Example:
This example demonstrates how to use the render hair accessor to extract the render hair data from a hair primitive.
        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        // create a cone with hair along with a uv property
        X3DObject myCone;
        root.AddGeometry( L"Cone", L"MeshSurface",L"myCone",myCone);

        Material myMat;
        myCone.AddMaterial(L"Phong", false, L"myMat", myMat);

        Shader sh = myMat.GetShaders().GetItem(0);
        Parameter p = sh.GetParameters().GetItem(L"diffuse");

        // connect an image parameter and add a UV property on the diffuse param
        CRef newSource;
        CRef prevSource;
        p.ConnectFromPreset( L"Image", siTextureShaderFamily, prevSource, newSource );

        // creates a projection i.e. UV property
        CValueArray args(7);
        CValue outArg;
        args[0] = myCone.GetFullName();
        args[1] = CString(L"siTxtSpherical");
        args[2] = CString(L"siTxtDefaultSpherical");
        args[3] = CValue();
        args[4] = CString(L"Texture_Projection");
        args[5] = CValue();
        args[6] = CValue((LONG)XSI::siRelDefault);

        app.ExecuteCommand( L"CreateProjection", args, outArg );

        // assign the projection to the cone
        args.Resize(3);
        args[0] = myCone.GetFullName();
        args[1] = CString(L"Sources.Materials.DefaultLib.myMat.Phong.Image.tspace_id");
        args[2] = CString(L"Texture_Projection");

        app.ExecuteCommand( L"SetInstanceDataValue", args, outArg );

        // add hair to the cone
        args.Resize(1);
        args[0] = myCone;
        app.ExecuteCommand( L"ApplyHairOp", args, outArg ) ;

        // transfer the uv property to the hair primitive
        X3DObject myHair = myCone.FindChild( L"Hair", L"", CStringArray() );

        args.Resize(2);
        args[0] = myHair.GetFullName();
        args[1] = CString(L"myCone.polymsh.cls.Texture_Coordinates_AUTO.Texture_Projection");

        app.ExecuteCommand( L"PropertyTransfer", args, outArg ) ;

        // setup a render hair accessor for 100 hairs with a chunk size of 10
        HairPrimitive myHairPrim( myHair.GetActivePrimitive() );

        CRenderHairAccessor rha = myHairPrim.GetRenderHairAccessor( 100, 10 );

        LONG nReqChunkSize = rha.GetRequestedChunkSize();
        app.LogMessage( L"nReqChunkSize: " + CValue(nReqChunkSize).GetAsText() );

        LONG nReqHairCount = rha.GetRequestedHairCount();
        app.LogMessage( L"nReqHairCount: " + CValue(nReqHairCount).GetAsText() );

        LONG nUVs = rha.GetUVCount();
        app.LogMessage( L"nUVs: " + CValue(nUVs).GetAsText() );

        // get the values in chunks
        LONG nChunk = 0;
        LONG i=0;
        while( rha.Next() )
        {
            app.LogMessage( L"Chunk: " + CValue(nChunk++).GetAsText() );

            // get the number of vertices for each render hair
            // note: this array is used for iterating over the render hair position
            // and radius values
            CLongArray verticesCountArray;
            rha.GetVerticesCount(verticesCountArray);

            // get the render hair positions
            CFloatArray posVals;
            rha.GetVertexPositions(posVals);

            LONG k = 0;
            app.LogMessage( L"Render hair position values: " );
            for (i=0; i<verticesCountArray.GetCount(); i++ )
            {
                LONG nCount = verticesCountArray[i];
                for (LONG j=0; j<nCount; j++ )
                {
                    CString strVals;
                    strVals=
                        CValue(posVals[k++]).GetAsText() + CString(L" ") +
                        CValue(posVals[k++]).GetAsText() + CString(L" ") +
                        CValue(posVals[k++]).GetAsText() ;

                    app.LogMessage( CValue(i).GetAsText() + L": " + strVals );
                }
            }

            // get the render hair radius
            app.LogMessage( L"Render hair radius values: " );
            CFloatArray radVals;
            rha.GetVertexRadiusValues(radVals);

            k = 0;
            for (i=0; i<verticesCountArray.GetCount(); i++ )
            {
                LONG nCount = verticesCountArray[i];
                for (LONG j=0; j<nCount; j++ )
                {
                    app.LogMessage( CValue(i).GetAsText() + L": " +
                        CValue(radVals[k++]).GetAsText() );
                }
            }

            // get the uv values
            app.LogMessage( L"Render hair uv values: " );
            for (i=0; i<nUVs; i++)
            {
                app.LogMessage( L"    UV: " +  rha.GetUVName(i) );

                CFloatArray uvVals;
                rha.GetUVValues( i, uvVals );

                for (LONG j=0,k=0; j<uvVals.GetCount(); j+=3, k++)
                {
                    CString strVals;
                    strVals =
                        CValue(uvVals[j+0]).GetAsText() + L" " +
                        CValue(uvVals[j+1]).GetAsText() + L" " +
                        CValue(uvVals[j+2]).GetAsText() ;

                    app.LogMessage( CValue(k).GetAsText() + L": " + strVals );
                }
            }
        }

#include <xsi_renderhairaccessor.h>

Inheritance diagram for CRenderHairAccessor:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 CRenderHairAccessor ()
 ~CRenderHairAccessor ()
 CRenderHairAccessor (const CRef &in_ref)
 CRenderHairAccessor (const CRenderHairAccessor &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
CRenderHairAccessoroperator= (const CRenderHairAccessor &in_obj)
CRenderHairAccessoroperator= (const CRef &in_ref)
bool Next ()
CStatus Reset ()
LONG GetRequestedChunkSize () const
LONG GetRequestedHairCount () const
LONG GetChunkHairCount () const
CStatus GetVerticesCount (CLongArray &out_values) const
CStatus GetVertexPositions (CFloatArray &out_values) const
CStatus GetVertexRadiusValues (CFloatArray &out_values) const
CStatus GetHairSurfaceNormalValues (CFloatArray &out_values) const
LONG GetUVCount () const
LONG GetVertexColorCount () const
LONG GetWeightMapCount () const
CString GetUVName (LONG in_nIdx) const
CString GetVertexColorName (LONG in_nIdx) const
CString GetWeightMapName (LONG in_nIdx) const
CStatus GetUVValues (LONG in_nIdx, CFloatArray &out_values) const
CStatus GetVertexColorValues (LONG in_nIdx, CFloatArray &out_values) const
CStatus GetWeightMapValues (LONG in_nIdx, CFloatArray &out_values) const

Constructor & Destructor Documentation

Default constructor.

Default destructor.

CRenderHairAccessor ( const CRef in_ref)

Constructor.

Parameters:
in_refconstant reference object.

Copy constructor.

Parameters:
in_objconstant 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_ClassIDclass type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Implements CBase.

CRenderHairAccessor& operator= ( const CRenderHairAccessor 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_objconstant class object.
Returns:
The new CRenderHairAccessor object.
CRenderHairAccessor& 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_refconstant class object.
Returns:
The new CRenderHairAccessor object.
bool Next ( )

Sets the accessor to the next available chunk of render hair data for reading. The position of the next chunk is computed based on the chunk size used for initializing the accessor. When the accessor is first initialized, there is no data available and CRenderHairAccessor::Next has to be called to receive the first chunk of data.

Returns:
True if there is data to read or false otherwise.
See also:
CRenderHairAccessor::Reset, HairPrimitive::GetRenderHairAccessor, CRenderHairAccessor::GetRequestedChunkSize
CStatus Reset ( )

Sets the accessor to the first chunk of render hair data for reading.

Returns:
CStatus::OK Success.
See also:
CRenderHairAccessor::Next
LONG GetRequestedChunkSize ( ) const

Returns the requested size of each render hair chunk. This number is always larger than or equal to the value returned from CRenderHairAccessor::GetChunkHairCount().

Returns:
long Chunk size. Returns -1 if the function fails.
See also:
CRenderHairAccessor::Next, HairPrimitive::GetRenderHairAccessor, CRenderHairAccessor::GetChunkHairCount
LONG GetRequestedHairCount ( ) const

Returns the maximum number of render hairs to access. This value is specified when the accessor is first created and does not correspond to the maximum number of render hairs available on the primitive.

Returns:
LONG Requested number of render hairs. Returns -1 if the function fails.
See also:
HairPrimitive::GetRenderHairAccessor
LONG GetChunkHairCount ( ) const

Returns the number of render hairs available for the current chunk. If hairs have been trimmed due to cut or density maps, this number can be less than the requested chunk size, even zero.

Returns:
LONG Number of render hairs for the current chunk. Returns -1 if the function fails.
See also:
CRenderHairAccessor::Next
CStatus GetVerticesCount ( CLongArray out_values) const

Returns an array containing the number of vertices for each generated render hair. This array can be used to iterate over the array of vertices and radius values.

Return values:
out_valuesArray of vertex count.
Returns:
CStatus::OK Success
See also:
GetRenderHairAccessor::GetVertexPositions, GetRenderHairAccessor::GetVertexRadiusValues
CStatus GetVertexPositions ( CFloatArray out_values) const

Returns an array of vertex positions (XYZ) for each render hair in local space. The vertex points are packed sequentially, the first being the root location, the next one in the sequence being the next connected point, all the way to the tip of the hair. Use the array returned by GetRenderHairAccessor::GetVerticesCount to find the number of vertices for each render hair in order to iterate over the vertex positions.

Return values:
out_valuesXYZ values.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetVerticesCount
CStatus GetVertexRadiusValues ( CFloatArray out_values) const

Returns an array of radius values at each render hair vertex. The radius values are packed sequentially, the first being the radius of the root location, the next one in the sequence being the next connected point radius, all the way to the tip of the hair. Use the array returned by GetRenderHairAccessor::GetVerticesCount to find the number of vertices for each render hair in order to iterate over the vertex radius values.

Return values:
out_valuesRadius values for each vertex of a render hair.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetVerticesCount
CStatus GetHairSurfaceNormalValues ( CFloatArray out_values) const

Returns the surface normal (XYZ) of the hair's emitter surface, from which each render hair is emitted.

Return values:
out_valuesSurface normal values for each render hair.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetVerticesCount
LONG GetUVCount ( ) const

Returns the number of UV properties on the primitive.

Returns:
LONG Number of UV properties. Returns -1 if the function fails.
See also:
GetRenderHairAccessor::GetUVName, GetRenderHairAccessor::GetUVValues
LONG GetVertexColorCount ( ) const

Returns the number of vertex color properties on the primitive.

Returns:
LONG Number of vertex color properties. Returns -1 if the function fails.
See also:
GetRenderHairAccessor::GetVertexColorName, GetRenderHairAccessor::GetVertexColorValues
LONG GetWeightMapCount ( ) const

Returns the number of weight map properties on the primitive.

Returns:
LONG Number of weight map properties. Returns -1 if the function fails.
See also:
GetRenderHairAccessor::GetWeightMapName, GetRenderHairAccessor::GetWeightMapValues
CString GetUVName ( LONG  in_nIdx) const

Returns the name of the UV property at a given index. The index refers to the position of the property on the primitive.

Parameters:
in_nIdxProperty index.
Returns:
CString Name of the property.
See also:
GetRenderHairAccessor::GetUVCount, GetRenderHairAccessor::GetUVValues
CString GetVertexColorName ( LONG  in_nIdx) const

Returns the name of the vertex color property at a given index. The index refers to the position of the property on the primitive.

Parameters:
in_nIdxProperty index.
Returns:
CString Name of the property.
See also:
GetRenderHairAccessor::GetVertexColorCount, GetRenderHairAccessor::GetVertexColorValues
CString GetWeightMapName ( LONG  in_nIdx) const

Returns the name of the weight map property at a given index. The index refers to the position of the property on the primitive.

Parameters:
in_nIdxProperty index.
Returns:
CString Name of the property.
See also:
GetRenderHairAccessor::GetWeightMapCount, GetRenderHairAccessor::GetWeightMapValues
CStatus GetUVValues ( LONG  in_nIdx,
CFloatArray out_values 
) const

Returns an array of UVW values for the UV property at the specified index. The values match the render hair root locations on the primitive. The index refers to the position of the property on the primitive.

In general, the size of the returned array is GetRenderHairAccessor::GetChunkHairCount() * 3. However, in the case where render hairs are generated in an area where they get cut due to a cut map or where the density decreases, the number of values returned is smaller.

Parameters:
in_nIdxProperty index.
Return values:
out_valuesUVW values.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetUVCount, GetRenderHairAccessor::GetUVName
CStatus GetVertexColorValues ( LONG  in_nIdx,
CFloatArray out_values 
) const

Returns an array of vertex color values (RGBA) for the vertex color property at the specified index. The values match the render hair root locations on the primitive. The index refers to the position of the property on the primitive.

In general, the size of the returned array is GetRenderHairAccessor::GetChunkHairCount() * 4. However, in the case where render hairs are generated in an area where they get cut due to a cut map or where the density decreases, the number of values returned is smaller.

Parameters:
in_nIdxProperty index.
Return values:
out_valuesRGBA color values ranging from 0.0 to 1.0.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetVertexColorCount, GetRenderHairAccessor::GetVertexColorName
CStatus GetWeightMapValues ( LONG  in_nIdx,
CFloatArray out_values 
) const

Returns an array of weight map values (W) for the weight map property at the specified index. The values match the render hair root locations on the primitive. The index refers to the position of the property on the primitive.

In general, the size of the returned array is GetRenderHairAccessor::GetChunkHairCount(). However, in the case where render hairs are generated in an area where they get cut due to a cut map or where the density decreases, the number of values returned is smaller.

Parameters:
in_nIdxProperty index.
Return values:
out_valuesWeight map values.
Returns:
CStatus::OK success
See also:
GetRenderHairAccessor::GetWeightMapCount, GetRenderHairAccessor::GetWeightMapName

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