intermediate

Parametric Shapes


Parametric Shapes

Names

The appearance of the standard shapes can generally be determined by their name, though they can be bent, tisted and turned. How these bends, and twist and turns are achieved depends on given parameters.

Updatable

Where a parametric shape has an updatable parameter in its options it means that it is possible to alter the data associated with each vertex of the mesh and so alter the shape of the mesh. For more information see Updating Vertices.

When in addition the shape has an instance parameter in its options then its shape can be updated by using MeshBuilder with instance set to the name of the shape.

In prectice all the parametric shapes, except for the Lathe and Polygon (both Create and Extend), can have their shape updated in this way by using the already created instance of the mesh.

Lines

Creates a continguous series of line segments from a list of points. You must set at least the points property. On update, you must set the points and instance properties.

Example :

//creates lines
var lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray}, scene);

// updates the existing instance of lines : no need for the parameter scene here
lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray, instance: lines});

Properties :

property value default value
points (Vector3[]) array of Vector3, the path of the line REQUIRED
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line mesh to be updated null

A Playground Example of Lines -


Dashed Lines

Creates a continguous series of dashed line segments from a list of points. You must set at least the points property. On update, you must set the points and instance properties.

Example :

// creates an instance of dashedlines
var dashedLines = BABYLON.MeshBuilder.CreateDashedLines("dl", {points: myArray}, scene);

// updates the existing instance of dashedLines : no need for the parameter scene here
dashedLines = BABYLON.MeshBuilder.CreateDashedLines("dl", {points: myArray, instance: dashedLines});

Properties :

property value default value
points (Vector3[]) array of Vector3, the path of the line REQUIRED
dashSize (number) size of the dashes 3
gapSize (number) size of the gaps 1
dashBn (number) intended number of dashes 200
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line mesh to be updated null

A Playground Example of Dashed Lines -


LineSystem

A system of lines that are independent of each other and may exist in their own space. You must set at least the lines property. On update, you must set the lines and instance properties.

Example :

// creates an instance of a line system
var lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: myArray}, scene);

// updates the existing instance of lineSystem : no need for the parameter scene here
lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: myArray, instance: lineSystem});

Properties :

property value default value
lines (Vector3[]) array of lines, each line being an array of successive Vector3 REQUIRED
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line system mesh to be updated null

A Playground Example of a Linesystem -


Ribbon

You must set at least the pathArray property. On update, you must set the pathArray and instance properties.

Example :

// creates an instance
var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myPaths}, scene);

// updates the existing instance of ribbon : no need for the parameter scene
ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myPaths, instance: ribbon});

Properties :

property value default value
pathArray (Vector3[][]) array of array of Vector3, the array of paths REQUIRED
closeArray (boolean) to force the ribbon to join its last and first paths false
closePath (boolean) to force each ribbon path to join its last and first points false
offset (number) used if the pathArray has one path only half the path length
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of a ribbon to be updated null

A Playground Example of a Ribbon -


Tube

You must set at least the path property. On update, you must set the path and instance properties and you can set the radius, radiusFunction or arc properties.

Example :

// creates a tube
var tube = BABYLON.MeshBuilder.CreateTube("tube", {path: myPath}, scene);

// updates the existing instance of tube : no need for the parameter scene
tube = BABYLON.MeshBuilder.CreateTube("tube", {path: myPath, instance: tube});

Properties :

property value default value
path (Vector3[]) array of Vector3, the path of the tube REQUIRED
radius (number) the radius of the tube 1
tessellation (number) the number of radial segments 64
radiusFunction ( function(i, distance) ) a function returning a radius value from (i, distance) parameters null
cap (number) tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
arc (number) ratio of the tube circumference between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of a tube to be updated null

A Playground Example of a Tube -


Extruded Shapes

You must set at least the shape and path properties. On update, you must set the shape, path and instance properties and you can set the scale and rotation properties.

In whatever direction you want to extrude the shape the design of the shape should be based on coordinates in the XOY plane, ie the z component should be 0. Some twisting to this base shape can be applied by leaving the x and y components unchanged but allowing the z component to be non zero but not taking the shape too far from generally lying in th XOY plane. Otherwise results will not be as you might expect.

Example :

// creates an extended shape
var extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPath}, scene);

// updates the existing instance of extruded : no need for the parameter scene
extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPath, scale: newScale, rotation: newRotation instance: extruded});

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to extrude REQUIRED
path (Vector3[]) array of Vector3, the extrusion axis REQUIRED
scale (number) the value to scale the shape 1
rotation (number) the value to rotate the shape each step along the path 0
cap (number) extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of an extruded shape to be updated null

A Playground Example of a Shape in XOY plane in Z direction with Rotation -


A Playground Example of the Same Shape in XOY plane in Y direction with Rotation -

A Playground Example of a Shape in YOZ plane in Z direction with Rotation - Strange! -

Custom Extruded Shapes

You must set at least the shape and path properties. On update, you must set the shape, path and instance properties and you can set the rotationFunction or scaleFunction properties.

Example :

//creates an instance of a Custom Extruded Shape
var extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", {shape: myShape, path: myPath}, scene);

// updates the existing instance of extruded : no need for the parameter scene
extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", {shape: myShape, path: myPath, scaleFunction: myScaleF, rotationFunction: myRotF instance: extruded});

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to extrude REQUIRED
path (Vector3[]) array of Vector3, the extrusion axis REQUIRED
scaleFunction ( function(i, distance) ) a function returning a scale value from (i, distance) parameters {return 1;}
rotationFunction ( function(i, distance) ) a function returning a rotation value from (i, distance) parameters {return 0;}
ribbonClosePath (boolean) the underlying ribbon closePath parameter value false
ribbonCloseArray (boolean) the underlying ribbon closeArray parameter value false
cap (number) extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of an extruded shape to be updated null

A Playground Example of a Custom Extruded Shape -


Lathe

You must set at least the shape property.

Example :

var lathe = BABYLON.MeshBuilder.CreateLathe("lathe", {shape: myShape}, scene);

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to turn REQUIRED
radius (number) the value to radius of the lathe 1
tessellation (number) the number of iteration around the lathe 64
arc (number) ratio of the circumference between 0 and 1 1
cap (number) tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
closed (boolean) to open/close the lathe circumference, should be set to false when used with arc true
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

A Playground Example of a Lathe -


Polygon

You must set at least the shape property.

Example :

var polygon = BABYLON.MeshBuilder.CreatePolygon("polygon", {shape: myShape, sideOrientation: BABYLON.Mesh.DOUBLESIDE, frontUVs: myFrontUVs, backUVs: myBackUVs}, scene);

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to turn REQUIRED
holes (Vector3[]) array of holes, each hole being an array of successive Vector3 []
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)

All vectors for shape and holes are Vector3 and should be in the XoZ plane, ie of the form BABYLON.Vector3(x, 0, z) and in counter clockwise order;

Both frontUVs and backUVs have the form Vector4(u0,v0,u1,v1) with 0>= u0,v0,u1,v1 <= 1 and (u0, v0) are the bottom left coordinates and (u1, v1) the top right coordinates of the clipping rectangle of the image.

A Playground Example of a Polygon

Uses PolygonMeshBuilder

Extruded Polygon

You must set at least the shape and depth properties.

Example :

var polygon = BABYLON.MeshBuilder.ExtrudePolygon("polygon", {shape: myShape, depth: 2, faceUV: myUVs}, scene);

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to turn REQUIRED
depth (number) the depth of the extrusion REQUIRED
faceColors (Color4[]) array of 3 Color4, one per box face Color4(1, 1, 1, 1) for each side
faceUV (Vector4[]) array of 3 Vector4, one per box face UVs(0, 0, 1, 1) for each side
holes (Vector3[]) array of holes, each hole being an array of successive Vector3 []
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

All vectors for shape and holes are Vector3 and should be in the XoZ plane, ie of the form BABYLON.Vector3(x, 0, z) and in counter clockwise order;

To understand how to set faceUV or faceColors, please read this : http://doc.babylonjs.com/tutorials/CreateBox_Per_Face_Textures_And_Colors

face 0 is top polygon, 1 is side of extruded polygon and 2 is bottom polygon

Playground Example of Extruded Polygon -


Uses PolygonMeshBuilder

Further Reading

Intermediate

Additional Shapes
Polyhedra Shapes

Advanced

Ribbons In Detail Maths Makes Ribbons Decals