# GreasedLineRibbon - a non-camera-facing version of GreasedLine

> GreasedLineRibbon - a non-camera-facing version of GreasedLine

Source: https://doc.babylonjs.com/features/featuresDeepDive/mesh/creation/param/greased_line/greased_line_ribbon

## 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:

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

The simplest usage is:

```javascript
const line = BABYLON.CreateGreasedLine("name", { points, ribbonOptions: { } })
```

- [Playground: Basic usage](https://playground.babylonjs.com/#P8NDK0#2) - Basic scenarios with GreasedLineRibbon.

### 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.

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

The default values are:

```javascript
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:

```javascript
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:

- [Playground: Point mode POINTS_MODE_POINTS](https://playground.babylonjs.com/#SS1UUI#30) - Shows how POINTS_MODE_POINTS works.

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

- [Playground: Point mode POINTS_MODE_PATHS](https://playground.babylonjs.com/#SS1UUI#31) - Shows how POINTS_MODE_PATHS works.

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.

- [Playground: Path mode](https://playground.babylonjs.com/#TN7XWX#35) - A simple space track - uses texture.

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

- [Playground: Path mode](https://playground.babylonjs.com/#TN7XWX#34) - A simple space track - uses colors.

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

- [Playground: Point mode POINTS_MODE_PATHS with more paths](https://playground.babylonjs.com/#SS1UUI#32) - Shows how POINTS_MODE_PATHS works with more than 2 paths.

#### **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.

- [Playground: Shows different direction modes](https://playground.babylonjs.com/#H1LRZ3#522) - Demonstrates all available direction modes.

#### **facesMode**

```javascript
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.

- [Playground: Shows different face modes](https://playground.babylonjs.com/#SS1UUI#82) - Shows different face modes.

#### **closePath**

If true, the line will be closed. Works in both `pathMode`s.

- [Playground: Without closing the line ribbon path](https://playground.babylonjs.com/#SS1UUI#38) - Without closing the line ribbon path.
- [Playground: Automatically closing the line ribbon path](https://playground.babylonjs.com/#SS1UUI#37) - Automatically closing the line ribbon path.

#### **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.

- [Playground: Without smooth shading](https://playground.babylonjs.com/#SS1UUI#35) - Without smooth shading.
- [Playground: With smooth shading](https://playground.babylonjs.com/#SS1UUI#36) - With smooth shading.

## Example playgrounds

- [Playground: Simple examples](https://playground.babylonjs.com/#FJRQ8N#138) - A lot of simple examples in one PG.
- [Playground: Tie drone](https://playground.babylonjs.com/#SS1UUI#51) - Shows how to use different options to build a small Imperial Tie drone.
- [Playground: Tie drones army](https://playground.babylonjs.com/#SS1UUI#50) - Flying tie drones from the previous example
- [Playground: Lazy mode](https://playground.babylonjs.com/#H1LRZ3#407) - Lazy mode line ribbons.
- [Playground: Recycle logo](https://playground.babylonjs.com/#H1LRZ3#415) - Recycle logo comparison. One created using a GreasedLineMesh and the second using GreasedLineRibbonMesh (non-camera-facing version vs camera-facing versions).