# CRenderHairAccessor Class Reference

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

`#include <xsi_renderhairaccessor.h>`

Inheritance diagram for CRenderHairAccessor:

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
CRenderHairAccessor & | operator= (const CRenderHairAccessor &in_obj)
CRenderHairAccessor & | operator= (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

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

## Constructor & Destructor Documentation

CRenderHairAccessor | ( |  | ) |

Default constructor.

~CRenderHairAccessor | ( |  | ) |

Default destructor.

CRenderHairAccessor | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  | in_ref | constant reference object.

CRenderHairAccessor | ( | const CRenderHairAccessor & | 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 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_obj | constant 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_ref | constant 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_values | Array 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_values | XYZ 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_values | Radius 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_values | Surface 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_nIdx | Property 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_nIdx | Property 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_nIdx | Property 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_nIdx | Property index.

Return values:

  | out_values | UVW 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_nIdx | Property index.

Return values:

  | out_values | RGBA 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_nIdx | Property index.

Return values:

  | out_values | Weight map values.

Returns:
  CStatus::OK success

See also:
  GetRenderHairAccessor::GetWeightMapCount, GetRenderHairAccessor::GetWeightMapName

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

- xsi_renderhairaccessor.h