Mesh

CubicVR.Mesh

Mesh( obj_init )

The Mesh class is used to provide high-level interface to compose indexed VBO structures for use with renderObject(). It provides a manageable container for triangles, quads, UV coordinates, segment groups, normals and material information.

Mesh supports the CubicVR.get functionality, meaning you can pass a script reference by ID or URL for an external XML or JSON resource. See the get API documentation more information and examples.

As well you can pass parts to construct via the build( obj ) method which is suitable for most ad-hoc mesh formats. Note that Mesh also takes a duplicate set of the build( obj ) constructor parameters to allow building a base part directly.

var mesh = new CubicVR.Mesh({
  name: "meshName", // name used to reference the Mesh
  primitives: null, // one or an array of [[primitive]] constructors with `type:` property matching primitive.
  parts: null,      // a single or array of `build( obj )` parts to make.
  points: null,     // see the build() function for reference
  faces: null,      // see the build() function for reference
  material: null,   // see the build() function for reference
  uv: null,         // see the build() function for reference
  color: null,      // see the build() function for reference
  flipFaces: false, // flip all faces of any parts/primitives if true
  calcNormals: true,// calculate normals, smoothing angle is set via `max_smooth` in [[Material]].
  prepare: false,   // compile the mesh but do not discard data if true, only applies when building parts
  compile: false,   // compile the mesh and discard data if true, only applies when building parts
  wireframe: false, // enable wireframe rendering for the mesh if true
  buildWireframe: false,   // build wireframe so it's available for rendering if true.
  wireframeMaterial: null, // a [[Material]] or constructor use for wireframe render. Has [[get]] support.
});

CubicVR.Mesh Methods

build( obj )

Can be called to construct portions of a mesh via an object constructor. CubicVR get functionality is also supported.

Parameters:

obj : An object constructor containing a single mesh part to build or an array of part objects.

Mesh.build({
    points:   // An array of points, each point is a 3-component [x,y,z] array.
    faces:    // An array of faces, each face is an array of point indices for the face.
    material: // A CubicVR.Material, constructor or [[get]] compatible URI. It will be applied to any faces.
    uv:       // A CubicVR.UVMapper, constructor or UV array, [[get]] compatible.
    color:    // An array of color values for each face point.
    segment:  // A segment ID for this part for high-performance render toggling of segmented parts at runtime.
    transform:  // A transform to apply to the constructed part relative to local coordinates
});

For points, faces, uv and color an array may be provided:

// the points for the current build operation, if not provided point indices will be relative
// to the existing mesh points.
points = [[x,y,z], [x,y,z], [x,y,z], ...];

// indices relative to points
faces = [[index1,index2,index3], [index1,index2,index3], ...];

// each array of u,v matches to face points, floating point values
uv = [[[u,v],[u,v],[u,v]], [[u,v],[u,v],[u,v]], ...];

// each [r,g,b] matches to a face point index entry, floating point 0.0 to 1.0
color = [[[r,g,b],[r,g,b],[r,g,b]], [[r,g,b],[r,g,b],[r,g,b]], ...];

For transform a simple transform constructor can be provided, or optionally a Transform or array of 16 floats representing a 4x4 matrix:

transform = {
    position: [x, y, z],
    rotation: [x, y, z],
    scale: [x, y, z]
}

// or
transform = (new CubicVR.Transform()).rotate(15,0,90);

// or
transform = [1, 0, 0, 0, 
             0, 1, 0, 0, 
             0, 0, 1, 0, 
             0, 0, 0, 1];

Returns:

this context for Mesh for chaining.

addPoint( point )

Add one or more points to the mesh, format of [x, y, z] relative to the mesh's center.

Parameters:

• point : A single point or array of points, a point is an array with 3 float elements representing X, Y and Z coordinates: [x,y,z]

Returns:

The index of the last point added in mesh.points[].

addFace( point_list, face_number, face_material, face_segment )

Add a Face to the Mesh using the index of points that belong to this mesh.

Parameters:

• point_list : - An indexed list of points for this face, it can be an array of 3 or 4 point indices representing a Triangle or Quad: [0,1,2] or multiple faces represented in an array: [ [0,1,2],[2,3,0],[4,5,6,7] ]
• face_number : (optional) - Face number (or starting face number if array) to insert these faces.
• face_material : (optional) - Material to apply to the newly added faces, defaults to last material set through Mesh.setFaceMaterial()
• face_segment : (optional) - Segment these faces apply to, defaults to last segment set through Mesh.setSegment(x)

Returns:

Index of the last face added. Face can be obtained through mesh.faces[index]

setFaceMaterial( material, facenum )

Without the facenum paremeter the Material material will be applied to subsequent mesh.addFace() calls. Otherwise material will be applied directly to the face at index facenum.

Parameters:

• material : A Material object to be applied.
• facenum (optional) : An existing face number index to apply the material to.

Returns:

the index of the point added.

getMaterial( material_name )

Retrieve the Material object given by material_name

Parameters:

• material_name : String of the name given to the Material you wish to retrieve.

Returns:

A Material object found with the given name of material_name, returns NULL if not found.

booleanAdd( objAdd, transform )

Boolean add an existing mesh objAdd to the current mesh, including Faces, UV's, Materials and Points with optional relative transform of transform.

Parameters:

• objAdd : A Mesh object containing the mesh to be added to the current mesh.
• transform (optional) : A Matrix in an array of 16 floats or a Transform object representing the placement of this mesh data relative to it's center.

Returns:

this context for Mesh for chaining.

calcFaceNormals()

Calculate all the Face normals for the current mesh, note this does not calculate the per-vertex normals needed for VBO just the mesh.faces[x].normal vectors. Use mesh.calcNormals() to prepare normals for VBO.

Returns:

this context for Mesh for chaining.

triangulateQuads()

Split any quads in the mesh into triangles; an additional trangle face will be added for each quad.

Returns:

this context for Mesh for chaining.

calcNormals()

Calculate vertex normals for use in VBO compilation; this is required if you wish to use lighting with your mesh. Note that the normals will be smoothed on a per-material basis, see [[Material]].setMaxSmooth(angle) for full details.

Returns:

this context for Mesh for chaining.

compile( tolerance )

Compile a VBO structure with material and segmentation interleaving and uploads it to the GPU while maintaining references. This prepares the mesh for rendering to the display using CubicVR.renderObject() and is required before any drawing can be performed.

Parameters:

tolerance (optional) : A floating-point tolerance value at which to fuse any points, normals or uvs that fall within this tolerance.

Returns:

this context for Mesh for chaining.

clean()

Once a mesh has been compiled the source face, point, uv and normal data can be safely removed from the mesh to free up memory. Note that the internal structures will be empty after this operation.

Returns:

this context for Mesh for chaining.

removeDoubles( tolerance )

Merges any vertices that are equal or fall within optional tolerance.

Parameters:

tolerance (optional) : A floating-point tolerance value at which to fuse any points that fall within tolerance, default 0.

Returns:

this context for Mesh for chaining.

buildEdges()

Prepares edges for wireframe. If you wish to render wireframe this must be called prior to compile(). If you wish to retain quads in the wireframe instead of creating triangles be sure to call buildEdges() before you call triangulateQuads().

Returns:

this context for Mesh for chaining.

subdivide( level, catmull_clark )

Parameters:

level (optional) : Number of levels of subdivision to apply, default: 1.
catmull_clark (optional) : Whether to apply Catmull-Clark subdivision, if false regular subdivision is applied, default: true.

Returns:

this context for Mesh for chaining.

setSegment( segment, state )

Assign the current segment or toggle a segment state. Segmentation allows you to assign individual faces to segments; they can be set to enabled or disabled at any time to show/hide them during rendering operations. Segments provide a high-performance way for you to mask, animate, handle partial visibility (BSP) or otherwise hide parts of the mesh with minimal performance impact.

Parameters

• segment : The segment you wish to assign or toggle. If state is not provided the current segment will be changed to segment for subsequent faces added to the mesh.
• state (optional) : If state is provided it will set the visibility state of segment to state. By default all segments are set to visible.

Returns:

none

showAllSegments()

Set all segment visibility to true, this will show all segments of the mesh when rendering.

Returns:

none

hideAllSegments()

Set all segment visibility to false, this will hide all segments of the mesh from rendering.

Returns:

none