Chapter 02Lines and Line Systems

Using the CreateLines method and the CreateLineSystem method of the MeshBuilder class, we can make lines and line systems.

let line = BABYLON.MeshBuilder.CreateLines("name", {points: points}, scene);

let lineSystem = BABYLON.MeshBuilder.CreateLineSystem("name", {lines: lines}, scene);

The first argument of CreateLines() and CreateLineSystem is a String that we can use to retrieve the entire line or line system mesh and data about the line or line system later. The second argument is an object that specifies various properties of the line or line system. The last argument is a reference to the scene in which the line or line system will be inserted into.

<script>
var canvas = document.getElementById("renderCanvas");
var engine = new BABYLON.Engine(canvas, true);

function createScene(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", -Math.PI/2, Math.PI / 2.2, 3, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let points = [new BABYLON.Vector3(-1, 0, 0), 
                  new BABYLON.Vector3(0, 1, 0), 
                  new BABYLON.Vector3(1, 0, 0), 
                  new BABYLON.Vector3(-1, 0, 0)];

    let line = BABYLON.MeshBuilder.CreateLines("line", {points: points}, scene);
    line.color = new BABYLON.Color3(1, 0, 0);
    line.position = new BABYLON.Vector3(-1.5, 0, 0);

    let lines = [[new BABYLON.Vector3(-1, 0, 0), 
                    new BABYLON.Vector3(0, 1, 0)], 
                 [new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(1, 0, 0)], 
                 [new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(0, 0, -1)], 
                 [new BABYLON.Vector3(1, 0, 0), 
                    new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(-1, 0, 0),
                    new BABYLON.Vector3(0, 0, -1), 
                    new BABYLON.Vector3(1, 0, 0)]];

    let lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: lines}, scene);
    lineSystem.color = new BABYLON.Color3(0, 0, 1);
    lineSystem.position = new BABYLON.Vector3(1.5, 0, 0);

    return scene;
};

var scene = createScene(canvas, engine);

engine.runRenderLoop(function(){
    scene.render();
});

window.addEventListener("resize", function(){
    engine.resize();
});
</script>

<canvas id="renderCanvas"></canvas>

Figure 1. A Babylon.js line, in red, and a Babylon.js line system, in blue.

Properties

Points and Lines

The points property is an array of Vector3[] objects which does not have a default vale. The points property is used to specify the path of the line in the scene using the points in the array.

Similarly, the lines property is a two-dimensional array of points where each array in the two-dimensional array is a line.

<script>
var canvas3 = document.getElementById("renderCanvas3");
var engine3 = new BABYLON.Engine(canvas3, true);

function createScene3(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", -Math.PI/2, Math.PI / 2.2, 3, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let mat = new BABYLON.StandardMaterial("mat", scene);
    mat.diffuseColor = new BABYLON.Color3(0, 1, 0);

    let points = [new BABYLON.Vector3(-1, 0, 0), 
                  new BABYLON.Vector3(0, 1, 0), 
                  new BABYLON.Vector3(1, 0, 0), 
                  new BABYLON.Vector3(-1, 0, 0)];

    let line = BABYLON.Mesh.CreateLines("line", points, scene);
    line.color = new BABYLON.Color3(1, 0, 0);
    line.position = new BABYLON.Vector3(-1.5, 0, 0);

    let lines = [[new BABYLON.Vector3(-1, 0, 0), 
                    new BABYLON.Vector3(0, 1, 0)], 
                 [new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(1, 0, 0)], 
                 [new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(0, 0, -1)], 
                 [new BABYLON.Vector3(1, 0, 0), 
                    new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(-1, 0, 0), 
                    new BABYLON.Vector3(0, 0, -1), 
                    new BABYLON.Vector3(1, 0, 0)]];

    let lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: lines}, scene);
    lineSystem.color = new BABYLON.Color3(0, 0, 1);
    lineSystem.position = new BABYLON.Vector3(1.5, 0, 0);

    return scene;
};

var scene3 = createScene3(canvas3, engine3);

engine3.runRenderLoop(function(){
    scene3.render();
});

window.addEventListener("resize", function(){
    engine3.resize();
});
</script>

<canvas id="renderCanvas3"></canvas>

Figure 2. A line, in red, uses the points property to shape it as a triangle. A line system, in blue, uses the lines property to shape it as a triangle.

Updatable

If we want the line or line system to be able to have its internal geometry changed after creation, we can set the Boolean parameter updatable equal to true. The default value is false.

Instance

The instance property, whose default value null, allows us to change the points used in a line mesh, as long as the number of points used in the mesh does not change.

For line systems, the instance property allows us to changes the lines used in our line system, as long as the amount of lines used does not change. In order to use the instance property, the updatable property must be set to true.

<script>
var canvas1 = document.getElementById("renderCanvas1");
var engine1 = new BABYLON.Engine(canvas1, true);

function createScene1(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", -Math.PI/2, Math.PI / 2.2, 3, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let points = [new BABYLON.Vector3(-1, 0, 0),
                  new BABYLON.Vector3(0, 1, 0), 
                  new BABYLON.Vector3(1, 0, 0), 
                  new BABYLON.Vector3(0, -1, 0)];

    let options = {points: points, updatable: true};

    let line = BABYLON.MeshBuilder.CreateLines("line", options, scene);
    line.points = points;
    line.color = new BABYLON.Color3(1, 0, 0);

    return scene;
};

var scene1 = createScene1(canvas1, engine1);

engine1.runRenderLoop(function(){
    scene1.render();
});

window.addEventListener("resize", function(){
    engine1.resize();
});

var ogPoints = true;

function changePoints() {
    let line = scene1.getMeshByName("line");
    let options = {};
    options.instance = line;
    options.points = [];

    if (ogPoints){
        options.points = [new BABYLON.Vector3(-1, 0, 0), new BABYLON.Vector3(0, 1, 0), new BABYLON.Vector3(1, 0, 0), new BABYLON.Vector3(-1, 0, 0)];
        ogPoints = false;
    } else {
        options.points = [new BABYLON.Vector3(-1, 0, 0), new BABYLON.Vector3(0, 1, 0), new BABYLON.Vector3(1, 0, 0), new BABYLON.Vector3(0, -1, 0)];
        ogPoints = true;
    }

    BABYLON.MeshBuilder.CreateLines("line", options);
}
</script>

<canvas id="renderCanvas1"></canvas>

<button onclick = "changePoints()">Change Instance</button>

Figure 3. We can change the points used in our line by using the instances property.

Colors

The colors property is a two-dimensional array of Color4() objects. The array must have the same dimensions as the points or lines property, where each Color4() object corresponds to the color of the respective point of the point or lines array.

<script>
var canvas2 = document.getElementById("renderCanvas2");
var engine2 = new BABYLON.Engine(canvas2, true);

function createScene2(canvas, engine){
    let scene = new BABYLON.Scene(engine);
    scene.clearColor = new BABYLON.Color3(1, 1, 1);
    let camera = new BABYLON.ArcRotateCamera("Camera", -Math.PI/2, Math.PI / 2.2, 3, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);
    let light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(1, 1, 0), scene);

    let points = [new BABYLON.Vector3(-1, 0, 0), 
                  new BABYLON.Vector3(0, 1, 0), 
                  new BABYLON.Vector3(1, 0, 0), 
                  new BABYLON.Vector3(-1, 0, 0)];
    let lineColors = [new BABYLON.Color4(1, 0, 0, 1), 
                      new BABYLON.Color4(0, 1, 0, 1), 
                      new BABYLON.Color4(0, 0, 1, 1), 
                      new BABYLON.Color4(1, 0, 0, 1)];
    
    let line = BABYLON.MeshBuilder.CreateLines("line", {points: points, colors: lineColors}, scene);
    line.position = new BABYLON.Vector3(-1.5, 0, 0);

    let lines = [[new BABYLON.Vector3(-1, 0, 0), 
                    new BABYLON.Vector3(0, 1, 0)], 
                 [new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(1, 0, 0)], 
                 [new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(0, 1, 0), 
                    new BABYLON.Vector3(0, 0, -1)], 
                 [new BABYLON.Vector3(1, 0, 0), 
                    new BABYLON.Vector3(0, 0, 1), 
                    new BABYLON.Vector3(-1, 0, 0), 
                    new BABYLON.Vector3(0, 0, -1), 
                    new BABYLON.Vector3(1, 0, 0)]];
    let colors = [[new BABYLON.Color4(0, 0, 1, 1), 
                    new BABYLON.Color4(0, 1, 0, 1)], 
                  [new BABYLON.Color4(0, 1, 0, 1), 
                    new BABYLON.Color4(1, 0, 0, 1)], 
                  [new BABYLON.Color4(1, 0, 0, 1), 
                    new BABYLON.Color4(0, 0, 1, 1), 
                    new BABYLON.Color4(0, 0, 1, 1)], 
                  [new BABYLON.Color4(0, 1, 0, 1), 
                    new BABYLON.Color4(0, 1, 0, 1), 
                    new BABYLON.Color4(1, 0, 0, 1), 
                    new BABYLON.Color4(1, 0, 0, 1), 
                    new BABYLON.Color4(0, 0, 1, 1)]];

    let lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: lines, colors: colors}, scene);
    lineSystem.position = new BABYLON.Vector3(1.5, 0, 0);

    return scene;
};

var scene2 = createScene2(canvas2, engine2);

engine2.runRenderLoop(function(){
    scene2.render();
});

window.addEventListener("resize", function(){
    engine2.resize();
});
</script>

<canvas id="renderCanvas2"></canvas>

Figure 4. The left triangle is a single line colored using the colors property. The right triangle is a line system colored using the colors property.