GreasedLineRibbon - a non-camera-facing version of GreasedLine

GreasedLineRibbon

You can use all the features of GreasedLine except sizeAttenuation, which does not make sense in non-camera-facing mode. GreasedLineRibbon creates ribbon-like geometry for the lines. To create a GreasedLineRibbon, add the ribbonOptions property to GreasedLineMeshBuilderOptions when using the CreateGreasedLine builder function, or to GreasedLineMeshOptions when creating the GreasedLineRibbon manually.

Create a GreasedLineRibbon

The easiest and recommended way to create a GreasedLineRibbon is to use the CreateGreasedLine function:

function CreateGreasedLine(name: string, options: GreasedLineMeshBuilderOptions, materialOptions?: Nullable<GreasedLineMaterialBuilderOptions>, scene?: Nullable<Scene>)

The simplest usage is:

import { CreateGreasedLine } from "@babylonjs/core/Meshes/Builders/greasedLineBuilder";
const line = CreateGreasedLine("name", { points, ribbonOptions: {} });

GreasedLineMeshBuilderOptions.ribbonOptions

If ribbonOptions is present, a non-camera-facing ribbon-like mesh will be created. It is an instance of the GreasedLineRibbon class. If you do not want to change the default values, it is enough to pass an empty object as shown previously.

pointsMode: GreasedLineRibbonPointsMode;
direction: Vector3;
directionsAutoMode?: GreasedLineRibbonAutoDirectionMode;
width: number;
facesMode?: GreasedLineRibbonFacesMode;
closePath?: boolean;
smoothShading?: boolean;

The default values are:

pointsMode = GreasedLineRibbonPointsMode.POINTS_MODE_POINTS;
direction = Vector3.UpReadOnly;
directionsAutoMode: GreasedLineRibbonAutoDirectionMode.AUTO_DIRECTIONS_NONE;
width = GreasedLineMaterialDefaults.DEFAULT_WIDTH; // 0.1
facesMode = GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED;
closePath = false;
smoothShading = false;

If you are creating the GreasedLineRibbonMesh manually, you must set all the values yourself. In addition, you have to set the cameraFacing option to false in GreasedLineMaterialOptions when creating the material manually.

pointsMode

There are two point modes available:

POINTS_MODE_POINTS = 0,
POINTS_MODE_PATHS = 1,

In GreasedLineRibbonPointsMode.POINTS_MODE_POINTS every array of points will become the center (backbone) of the ribbon. The ribbon will be expanded by width / 2 to +direction and -direction as well.

In GreasedLineRibbonPointsMode.POINTS_MODE_PATHS every array of points is one path. These will be used to build one ribbon.

Let's demonstrate both point modes. The gray mesh is the line ribbon itself and the white line is the center (backbone) of it:

The gray mesh is the line ribbon itself and the white lines are the paths which the line ribbon is built between:

A simple space track created using POINTS_MODE_PATHS. The red debug lines show the paths. Track colors are created using a manually created texture. The red lines show the paths that define the edges of the ribbon.

The same space track colored by the colors property of the GreasedLineMaterial:

You can have more than two paths to build line ribbons of custom shapes:

direction and width

This property is a normalized direction vector for the slope of the line in POINTS_MODE_POINTS. The line ribbon will be expanded to +direction and -direction from the center line defined by points by a value of width / 2.

You can change the default width by modifying the value of the static property GreasedLineRibbonMesh.DEFAULT_WIDTH. This will not affect existing line ribbons.

The widths option on GreasedLineMaterialBuilderOptions is not supported in POINTS_MODE_PATHS because in this mode you define the edges of the ribbon and not the center line.

directionsAutoMode

AUTO_DIRECTIONS_FROM_FIRST_SEGMENT sets the direction (slope) of the ribbon from the direction of the first line segment. It is recommended when all the lines are on the same plane.

AUTO_DIRECTIONS_FROM_ALL_SEGMENTS calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments. This is a slow method.

AUTO_DIRECTIONS_ENHANCED calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments using a more sophisticated algorithm. This is the slowest method.

AUTO_DIRECTIONS_FACE_TO calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments and a direction (face-to) vector specified in direction. The resulting line will face the direction of this face-to vector.

AUTO_DIRECTIONS_NONE requires you to set the direction (slope) manually. It is recommended when you want full control.

facesMode

FACES_MODE_SINGLE_SIDED = 0,
FACES_MODE_SINGLE_SIDED_NO_BACKFACE_CULLING = 1,
FACES_MODE_DOUBLE_SIDED = 2

Controls how the faces are created: In GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED, faces are single-sided with back-face culling. This is the default value. In GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED_NO_BACKFACE_CULLING, faces are single-sided without back-face culling. This sets backFaceCulling = false on the material, so it affects all line ribbons added to the line ribbon instance. In GreasedLineRibbonFacesMode.FACES_MODE_DOUBLE_SIDED, extra back faces are created. This doubles the number of faces in the mesh.

closePath

If true, the line will be closed. Works in both pathModes.

smoothShading

If true, normals will be computed when creating the vertex buffers. This results in smooth shading of the mesh. It does not work when closePath = true. colorMode must not be BABYLON.GreasedLineMeshColorMode.COLOR_MODE_SET, and a light source must be present, of course.

Example playgrounds