babylon101

Discover Basic Elements


Set Shapes 101

These are shapes that usually already have names in everyday use. They are a box (or cuboid), a sphere, a cylinder, a cone, regular polygons, a plane and a specialist horizontal plane called the ground. Slightly less well know but also included in set shapes are a torus, a torus knot and the polyhedra. You will have to wait for the next section to learn how to create shapes that have no everyday names but are formed through data sets and parameters. These are termed parametric shapes.

In the 101 course you will only meet a limited number of set shapes, starting on this page with boxes, spheres, planes and ground. Also you will just use the MeshBuilder method of shape creation rather than the older legacy Mesh method. How to create all the set shapes using either method and the advantages and disadvantages of both can be found by doing Further Reading.

MeshBuilder Method

The general form to create a set shape is

var shape = BABYLON.MeshBuilder.CreateShape(name, options, scene);

The options parameter allows you to do such things as set the size of the shape and set whether you can update it or not. Specific examples below.

Box

var box = BABYLON.MeshBuilder.CreateBox("box", {}, scene); // default box

var myBox = BABYLON.MeshBuilder.CreateBox("myBox", {height: 5, width: 2, depth: 0.5}, scene);
option value default value
size (number) size of each box side 1
height (number) height size, overwrites size property size
width (number) width size, overwrites size property size
depth (number) depth size, overwrites size property size
faceColors (Color4[]) array of 6 Color4, one per box face Color4(1, 1, 1, 1) for each side
faceUV (Vector4[]) array of 6 Vector4, one per box face UVs(0, 0, 1, 1) for each side
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

Playground Example of a Cuboid -


Sphere

var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {}, scene); //default sphere

var mySphere = BABYLON.MeshBuilder.CreateSphere("mySphere", {diameter: 2, diameterX: 3}, scene);
option value default value
segments (number) number of horizontal segments 32
diameter (number) diameter of the sphere 1
diameterX (number) diameter on X axis, overwrites diameter property diameter
diameterY (number) diameter on Y axis, overwrites diameter property diameter
diameterZ (number) diameter on Z axis, overwrites diameter property diameter
arc (number) ratio of the circumference (latitude) between 0 and 1 1
slice (number) ratio of the height (longitude) between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

Playground Example of an Ellipsoid -


Plane

var plane = BABYLON.MeshBuilder.CreatePlane("plane", {}, scene); // default plane

var myPlane = BABYLON.MeshBuilder.CreatePlane("myPlane", {width: 5, height: 2}, scene);
option value default value
size (number) side size of the plane 1
width (number) size of the width size
height (number) size of the height size
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 set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
sourcePlane (Plane) source plane (maths) the mesh will be transformed to null

Playground Example of a Plane -


sourcePlane is a unique option for a plane mesh and provides a method to orientate and position it. For now just consider its orientation which on creation is the vector (0, 0, 1). Now should you want the orientation to be the vector (0, -1, 1) then you create a source plane using

var sourcePlane = new BABYLON.Plane(0, -1, 1, 0);
sourcePlane.normalize();

This creates a mathematical plane which is used as the orientation source. The fourth parameter is a distance moved in the direction of the orientation vector. At this stage leave as 0.

Playground Example with Source Plane -


More Information on Source Plane

Ground

var ground = BABYLON.MeshBuilder.CreateGround("ground", {}, scene); //default ground

var myGround = BABYLON.MeshBuilder.CreateGround("myGround", {width: 6, height: 4, subdivsions: 4}, scene);
option value default value
width (number) size of the width 1
height (number) size of the height 1
updatable (boolean) true if the mesh is updatable false
subdivisions (number) number of square subdivisions 1

Playground Example of Ground -


A variation on CreateGround is CreateGroundFromHeightMap which lets you form undulating ground rather than a flat plane.

Face Colors or UV

This is only available on a limited number of meshes that have distinct faces such as a box but not a sphere. This allows you to give each face for those meshes an individual color or image. Find out about Face Colors and UV.

Updatable

Where a mesh has the updatable parameter set to true 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 How to Update Vertices

Side Orientation

The side orientation option is used to change how each side of a mesh is viewed.

There are four possible values for this option :

  • BABYLON.Mesh.FRONTSIDE,
  • BABYLON.Mesh.BACKSIDE,
  • BABYLON.Mesh.DOUBLESIDE,
  • BABYLON.Mesh.DEFAULT which is the default value and equals FRONTSIDE currently.

By moving your screen pointer left and right to rotate the planes, in the following examples, you can compare between DEFAULT and DOUBLESIDE.
Playground Example of a DEFAULT Plane -


Playground Example of a DOUBLESIDE Plane -

Front and Back UV

When a mesh has a sideOrientation option present and it is set to DOUBLESIDE then it is possible for the front and back to display different images. For more information see How To Display Front and Back Images

Coming Soon

When you create a mesh it is always centered at the origin and in line with the axes. You will want to give it a different position and rotation. Cannot wait then skip the next step and go off to How to Change Position and Rotation

Next Step

Now you have some of the set shapes under your belt find out about Shapes Less Set in Their Ways

Further Reading

Basic - L1

How to Create Set Shapes with MeshBuilder
How to Create Set Shapes Legacy Method
Advantages and Disadvantages