CMeshBuilder Class
Reference
#include <xsi_meshbuilder.h>
CMeshBuilder allows you to create polygon meshes from an ordered array of vertex coordinates and polygon connections (polygon to vertices). You can build the vertices and polygons by providing all the data at once or you can build them incrementally by providing the data in chunks.
Building a mesh incrementally is especially convenient when you have to deal with very large data sets, allowing you to minimize the memory required for storing such data sets.
Although you can undo the storing CMeshBuilder operation (ie., the whole creation of the new mesh), the individual operations for setting the vertex and polygon values are not undoable. For performance reasons it is not recommended to use undo for building a mesh as this will duplicate the data in memory.
CMeshBuilder also provides the functionality for setting the material used by each polygon of the mesh with only one function call (CMeshBuilder::SetPolygonsMaterial). The SetPolygonsMaterial function manages creating clusters, which can also be undone. However, while you can undo the cluster creation, you cannot undo the operations for setting the cluster element values.
CMeshBuilder can only be used from existing X3DObject instances. Therefore, the newly created mesh will replace the current one on the X3DObject instance.
using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot();
// Create the grid from an empty mesh object
X3DObject myObj;
CMeshBuilder msBuilder;
root.AddPolygonMesh( L"MyMesh", myObj, msBuilder );
// Add the vertices of the grid
double myVertexPositionArray[27] =
{
-4, 0, -4,
-4, 0, 0,
-4, 0, 4,
0, 0, -4,
0, 0, 0,
0, 0, 4,
4, 0, -4,
4, 0, 0,
4, 0, 4
};
// Add the vertices with positions
msBuilder.AddVertices( 9, myVertexPositionArray );
// Add the polygons of the grid
LONG pPolyVertexCounts[4] = {4,4,4,4};
LONG pVtxIndices[16] =
{
0, 1, 4, 3,
1, 2, 5, 4,
3, 4, 7, 6,
4, 5, 8, 7
};
msBuilder.AddPolygons( 4, pPolyVertexCounts, pVtxIndices );
// Generate the new grid with undo disabled
CMeshBuilder::CErrorDescriptor err = msBuilder.Build(false);
if (err.GetCode()==CStatus::Fail)
{
app.LogMessage( L"Error generating the mesh: " + err.GetDescription() );
}
Classes |
|
| class | CErrorDescriptor |
| This class reports the error status returned
by CMeshBuilder::Build.
If the mesh builder fails, the faulty indices are reported by this
object. More... |
|
Public Member Functions |
|
| CMeshBuilder () | |
| ~CMeshBuilder () | |
| CMeshBuilder (const CRef &in_ref) | |
| CMeshBuilder (const CMeshBuilder &in_obj) | |
| bool | IsA (siClassID in_ClassID) const |
| siClassID | GetClassID () const |
| CMeshBuilder & | operator= (const CMeshBuilder &in_obj) |
| CMeshBuilder & | operator= (const CRef &in_ref) |
| CStatus | AddVertices (LONG in_nVertices, const double *in_pPos=0) |
| CStatus | SetVertexPositions (LONG in_nVertices, const double *in_pPos, LONG in_nOffset=0) |
| CStatus | AddPolygons (LONG in_nPolygons, const LONG *in_pPolyVertexCounts, const LONG *in_pVtxIndices) |
| CStatus | AddTriangles (LONG in_nTriangles, const LONG *in_pVtxIndices) |
| CStatus | SetEdgeCreaseValue (LONG in_nPolyID, LONG in_nPolyEdgeIndex, float in_value) |
| CStatus | SetHardEdge (LONG in_nPolyID, LONG in_nPolyEdgeIndex, bool in_bFlag=true) |
| CStatus | SetVertexCreaseValue (LONG in_nVtxID, float in_value) |
| CStatus | SetPolygonsMaterial (const CRef &in_refMat, LONG in_nSize, const LONG *in_pPolyIndices) |
| CStatus | SetPolygonsMaterial (const CRef &in_refMat, LONG in_nSize, const LONG *in_pPolyIndices, CString &io_clsName) |
| CErrorDescriptor | Build (bool in_bUndoRequired) |
| CMeshBuilder | ( | ) |
Default constructor.
| ~CMeshBuilder | ( | ) |
Default destructor.
| CMeshBuilder | ( | const CRef & | in_ref | ) |
Constructor.
| in_ref | constant reference object. |
| CMeshBuilder | ( | const CMeshBuilder & | in_obj | ) |
Copy constructor.
| in_obj | constant class object. |
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from CBase.
| siClassID GetClassID | ( | ) | const [virtual] |
| CMeshBuilder& operator= | ( | const CMeshBuilder & | in_obj | ) |
Creates an object from another object. The newly created object is set to empty if the input object is not compatible.
| in_obj | constant class object. |
| CMeshBuilder& 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.
| in_ref | constant class object. |
| CStatus AddVertices | ( | LONG | in_nVertices, |
| const double * | in_pPos = 0 |
||
| ) |
Adds the specified number of vertices to the underlying mesh. You can either specify the array of positions for these vertices as input to this function or use the CMeshBuilder::SetVertexPositions function to specify them later.
| in_nVertices | Number of vertices to add. One vertex is a 3 components value (xyz). |
| in_pPos | Optional array of size in_nVertices*3 containing the vertex positions (xyz). If this array is omitted, all vertex positions are set to 0. |
| CStatus SetVertexPositions | ( | LONG | in_nVertices, |
| const double * | in_pPos, | ||
| LONG | in_nOffset =
0 |
||
| ) |
Sets the positions of the mesh vertices by identifying which vertices to set and what the new values will be. This method allows you to incrementally set vertex values to minimize memory usage, but you can also specify the positions all at once when you add the vertices to the mesh.
| in_nVertices | Number of vertices to set. One vertex is a 3 components value (xyz). |
| in_pPos | Array of size in_nVertices*3 containing the vertex positions (xyz) |
| in_nOffset | Specifies the starting vertex index in the mesh. |
using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot();
// Creates the cube from an empty mesh
X3DObject myObj;
CMeshBuilder msBuilder;
root.AddPolygonMesh( L"MyCube", myObj, msBuilder );
// Add empty vertices to the cube without setting the positions
msBuilder.AddVertices( 8, NULL );
// Add polygons to the cube
LONG pPolyVertexCounts[6] = {4,4,4,4,4,4};
LONG pVtxIndices[24] =
{
0, 2, 3, 1,
0, 1, 5, 4,
0, 4, 6, 2,
1, 3, 7, 5,
2, 6, 7, 3,
4, 5, 7, 6
};
msBuilder.AddPolygons( 6, pPolyVertexCounts, pVtxIndices );
// Now set the positions one at a time
double myCubeVertices[24] =
{
-4, -4, -4,
4, -4, -4,
-4, 4, -4,
4, 4, -4,
-4, -4, 4,
4, -4, 4,
-4, 4, 4,
4, 4, 4
};
for (LONG i=0, nOffset=0; i<8; i++, nOffset++ )
{
msBuilder.SetVertexPositions(
1, // nb vertices
myCubeVertices+(nOffset*3), // positions
nOffset // vertex index to set
);
}
// Generate the new cube
CMeshBuilder::CErrorDescriptor err = msBuilder.Build(false);
if (err==CStatus::Fail)
{
app.LogMessage( L"Error generating the mesh: " + err.GetDescription() );
}
| CStatus AddPolygons | ( | LONG | in_nPolygons, |
| const LONG * | in_pPolyVertexCounts, | ||
| const LONG * | in_pVtxIndices | ||
| ) |
Adds polygons to a mesh by describing how many polygons to add and how many vertices (and their indices) each new polygon will have.
| in_nPolygons | Number of polygons to add. |
| in_pPolyVertexCounts | Array of size in_nPolygons containing the vertex count of each polygon to add. |
| in_pVtxIndices | Array containing the vertex indices for each polygon to add. This array describes how each polygon is connected to the mesh. The Array size should be the sum of all items of in_pPolyVertexCounts. |
| CStatus AddTriangles | ( | LONG | in_nTriangles, |
| const LONG * | in_pVtxIndices | ||
| ) |
Adds triangle polygons to a mesh. The function assumes the polygons to add are triangles. Therefore the caller doesn't need to allocate an array for storing the number of vertices per polygon as for CMeshBuilder::AddPolygons.
| in_nTriangles | Number of triangles to add. |
| in_pVtxIndices | Array containing the vertex indices for each polygon to add. This array describes how each triangle is connected to the mesh. The Array size should be in_nTriangles * 3. |
| CStatus SetEdgeCreaseValue | ( | LONG | in_nPolyID, |
| LONG | in_nPolyEdgeIndex, | ||
| float | in_value | ||
| ) |
| CStatus SetHardEdge | ( | LONG | in_nPolyID, |
| LONG | in_nPolyEdgeIndex, | ||
| bool | in_bFlag =
true |
||
| ) |
| CStatus SetVertexCreaseValue | ( | LONG | in_nVtxID, |
| float | in_value | ||
| ) |
Sets the vertex crease value for the specified vertex.
| in_nVtxID | Index of the vertex to set. |
| in_value | The crease value. |
Assigns the specified material to the set of polygons matching the specified indices. This function selects existing clusters or creates new ones based on the input material by using the following heuristics:
| in_refMat | Material to assign to the polygons |
| in_nSize | Size of the in_pPolyIndices array |
| in_pPolyIndices | Array of polygon indices |
using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot( );
// Get a mesh builder from an empty mesh to create the new cube
X3DObject myCube;
CMeshBuilder msBuilder;
root.AddPolygonMesh( L"MyCube", myCube, msBuilder );
// Add vertices
double myCubeVertices[ 24 ] =
{
-4, -4, -4,
4, -4, -4,
-4, 4, -4,
4, 4, -4,
-4, -4, 4,
4, -4, 4,
-4, 4, 4,
4, 4, 4
};
msBuilder.AddVertices( 8, myCubeVertices );
// Appends the polygons
LONG pPolyVertexCounts[ 6 ] = { 4,4,4,4,4,4 };
LONG pVtxIndices[ 24 ] =
{
0, 2, 3, 1,
0, 1, 5, 4,
0, 4, 6, 2,
1, 3, 7, 5,
2, 6, 7, 3,
4, 5, 7, 6
};
msBuilder.AddPolygons( 6, pPolyVertexCounts, pVtxIndices );
// Generate the new cube with undo disabled
CMeshBuilder::CErrorDescriptor err = msBuilder.Build( false );
if (err==CStatus::Fail)
{
app.LogMessage( L"Error generating the mesh: " + err.GetDescription() );
}
// Create 3 different materials
Scene scene = app.GetActiveProject( ).GetActiveScene( );
MaterialLibrary matlib( scene.GetActiveMaterialLibrary( ) );
Material myMat1 = matlib.CreateMaterial( L"Phong", L"myMat1" );
Shader sh = myMat1.GetShaders( ).GetItem( 0 );
Parameter p = sh.GetParameters( ).GetItem( L"diffuse" );
p.PutParameterValue( L"red", 1L );
p.PutParameterValue( L"green", 0L );
p.PutParameterValue( L"blue", 0L );
Material myMat2 = matlib.CreateMaterial( L"Phong", L"myMat2" );
sh = myMat2.GetShaders( ).GetItem( 0 );
p = sh.GetParameters( ).GetItem( L"diffuse" );
p.PutParameterValue( L"red", 0L );
p.PutParameterValue( L"green", 1L );
p.PutParameterValue( L"blue", 0L );
Material myMat3 = matlib.CreateMaterial( L"Phong", L"myMat3" );
sh = myMat3.GetShaders( ).GetItem( 0 );
p = sh.GetParameters( ).GetItem( L"diffuse" );
p.PutParameterValue( L"red", 0L );
p.PutParameterValue( L"green", 0L );
p.PutParameterValue( L"blue", 1L );
// Set polygon 4, 5 with the red material
LONG poly45[] = {4,5};
msBuilder.SetPolygonsMaterial( myMat1, 2, poly45 );
// Set polygon 2, 3 with the green material
LONG poly23[] = {2,3};
msBuilder.SetPolygonsMaterial( myMat2, 2, poly23 );
// Set polygon 0, 1 with the blue material
LONG poly01[] = {0,1};
msBuilder.SetPolygonsMaterial( myMat3, 2, poly01 );
| CStatus SetPolygonsMaterial | ( | const CRef & | in_refMat, |
| LONG | in_nSize, | ||
| const LONG * | in_pPolyIndices, | ||
| CString & | io_clsName | ||
| ) |
Assigns a specific material to a set of polygons via a polygon cluster. This function can only be called once the mesh is built.
The following heuristics are used by the function for selecting the polygon cluster to use for setting the polygon's material. The selected cluster is returned with io_clsName:
| in_refMat | Material to assign to the polygons |
| in_nSize | Size of the in_pPolyIndices array |
| in_pPolyIndices | Array of polygon indices |
| io_clsName | Name of the cluster to use for setting the polygons. The function returns the name of the selected cluster with io_clsName. |
| CErrorDescriptor Build | ( | bool | in_bUndoRequired | ) |
Validates the new mesh created from the vertices and polygon data and swaps the underlying X3DObject's mesh with the new one. The existing mesh, clusters and properties on the X3DObject are destroyed. An error descriptor is returned to inform the caller whether or not the mesh was created correctly.
If the mesh creation fails, the error object is set with the faulty indices, one array per geometry type (polygon, vertex, edge and node). The operation of building a mesh can be undone but that comes with a cost since mesh geometries can get quite large.
| in_bUndoRequired | If true, CMeshBuilder saves the data for both new and original meshes for undo. If the current undo stack level is 0, the operation is not undoable. If you pass false, the current undo stack is set to 0. Therefore all undo events currently on the stack are lost. The undo stack is set back to the previous level after the Build function returns. |