
## GreasedLineRibbon

You can use all the features of `GreasedLine` except `sizeAttenuation` which doesn't make sense to use in non camera facing mode. `GreasedLineRibbon` creates ribbon like geometry for the lines. If you want to create a `GreasedLineRibbon` just add the `ribbonOptions` property to the `GreasedLineMeshBuilderOptions` when using the `CreateGreasedLine` builder function or to `GreasedLineMeshOptions` when creating the `GreasedLineRibbon` manually.

## Create a GreasedLineRibbon

The easiest, preferred 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 id="#P8NDK0#2" title="Basic usage" description="Basic scenarios with GreasedLineRibbon." />

### GreasedLineMeshBuilderOptions.ribbonOptions

If there is a `ribbonOptions` present a non camera facing ribbon like mesh will be created. It's an instance of the `GreasedLineRibbon` class. If you don't want to change the default values it's 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 have to take care of setting 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 id="#SS1UUI#30" title="Point mode POINTS_MODE_POINTS" description="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 id="#SS1UUI#31" title="Point mode POINTS_MODE_PATHS" description="Shows how POINTS_MODE_PATHS works." />

A simple space track created using `POINTS_MODE_PATHS`. The red debug lines shows the paths. Track colors are created using a manually created texture. The red lines shows the paths which defines the edges of the ribbon.

<Playground id="#TN7XWX#35" title="Path mode" description="A simple space track - uses texture." />

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

<Playground id="#TN7XWX#34" title="Path mode" description="A simple space track - uses colors." />

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

<Playground id="#SS1UUI#32" title="Point mode POINTS_MODE_PATHS with more paths" description="Shows how POINTS_MODE_PATHS works with more than 2 paths." />

#### **direction** and **width**

This property is a normalized direction vector of 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 `GreasedLineRibbonMesh.DEFAULT_WIDTH` static property. This will not affect the 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. Recommended when all the lines are on the same plane.

`AUTO_DIRECTIONS_FROM_ALL_SEGMENTS` in this mode the direction (slope) will be calculated for each line segment according to the direction vector between each point of the line segments. Slow method.

`AUTO_DIRECTIONS_ENHANCED` in this mode the direction (slope) will be calculated for each line segment according to the direction vector between each point of the line segments using a more sophisticated algorithm. Slowest method.

`AUTO_DIRECTIONS_FACE_TO` in this mode the direction (slope) will be calculated 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 to the direction of this face-to vector.

`AUTO_DIRECTIONS_NONE` you have to set the direction (slope) manually. Recommended when you want full control.

<Playground id="#H1LRZ3#522" title="Shows different direction modes" description="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` single sided with back face culling. Default value.
In `GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED_NO_BACKFACE_CULLING` single sided without back face culling. 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 amount of faces of the mesh.

<Playground id="#SS1UUI#82" title="Shows different face modes" description="Shows different face modes." />

#### **closePath**

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

<Playground id="#SS1UUI#38" title="Without closing the line ribbon path" description="Without closing the line ribbon path." />
<Playground id="#SS1UUI#37" title="Automatically closing the line ribbon path" description="Automatically closing the line ribbon path." />

#### **smoothShading**

If true, normals will be computed when creating the vertex buffers. This results to smooth shading of the mesh. Doesn't work when `closePath = true`. `colorMode` mustn't be `BABYLON.GreasedLineMeshColorMode.COLOR_MODE_SET` and a lightsource must be present of course.

<Playground id="#SS1UUI#35" title="Without smooth shading" description="Without smooth shading." />
<Playground id="#SS1UUI#36" title="With smooth shading" description="With smooth shading." />

## Example playgrounds

<Playground id="#FJRQ8N#138" title="Simple examples" description="A lot of simple examples in one PG." />
<Playground id="#SS1UUI#51" title="Tie drone" description="Shows how to use different options to build a small Imperial Tie drone." />
<Playground id="#SS1UUI#50" title="Tie drones army" description="Flying tie drones from the previous example" />
<Playground id="#H1LRZ3#407" title="Lazy mode" description="Lazy mode line ribbons." />
<Playground id="#H1LRZ3#415" title="Recycle logo" description="Recycle logo comparison. One created using a GreasedLineMesh and the second using GreasedLineRibbonMesh (non camera facing version vs camwea facing versions)." />











## Ribbon
The ribbon is a very versatile shape. Picture a ribbon in the real world with parallel wires running down its length. You can turn such a ribbon into a wide variety of shapes. Joining one long edge to its opposite you could form a tube and bend that into different shapes. This and more is possible with a Babylon.js ribbon. Instead of parallel wires a Babylon.js ribbon is formed from paths defined by an array of vector3s and how you define the paths determines the final shape. 

On creation the local origin of a ribbon is coincident with the world origin. It is not possible to give a position relative to the constructed shape as this depends on the data sets used.

## MeshBuilder
Usage :

```javascript
const options = {
    pathArray: myPaths, //[vector3 array, vector3 array, vector3 array......]
    updatable: true
}

let ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", options, scene); //scene is optional and defaults to the current scene

options.pathArray: myNewPaths; //The length must equal the length of myPaths and myNewPaths[i].length === myPaths[i] for all i
options.instance = true;

// updates the existing instance of ribbon : no need for the parameter scene
ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myNewPath, instance: ribbon});
```

option|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
frontUVs|_(Vector4)_  **ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option** | Vector4(0,0, 1,1) 
backUVs|_(Vector4)_  **ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option** | Vector4(0,0, 1,1) 
instance|_(LineMesh)_ an instance of a ribbon to be updated|null
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false

### Examples

Update of a ribbon: <Playground id="#F6JW5W#5" title="Updating a Ribbon" description="Simple example of updating a ribbon."/>

double sided ribbon not updatable: <Playground id="#F6JW5W#6" title="Create a Non Updatable Double Sided Ribbon" description="Simple example of creating a non updatable double sided ribbon."/>
double sided ribbon not updatable path lines in red: <Playground id="#F6JW5W#7" title="Create a Non Updatable Double Sided Ribbon With Red Path Lines" description="Simple example of creating a non updatable double sided ribbon with red path lines."/>  
open ribbon: <Playground id="#F6JW5W#8" title="Create An Open Ribbon" description="Simple example of creating an open ribbon."/>
with closePath true: <Playground id="#F6JW5W#9" title="Create a Ribbon with closePath = True" description="Simple example of creating a ribbon with closePath set to true."/> 
with closeArray true: <Playground id="#F6JW5W#10" title="Create a Ribbon with closeArray = True" description="Simple example of creating a ribbon with closeArray set to true."/> 


## Mesh
Usage: 
```javascript
const ribbon = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, closeArray, closePath, offset, scene);
const ribbon = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, closeArray, closePath, offset, scene, updatable, sideOrientation, instance); //optional parameters after scene
```

More about ribbons on the next page


## GreasedLine advanced examples

This page contains some ideas for using GreasedLine.

### Audio analyzer

Shows how you can use `widths` and `offsets` to create a simple audio analyzer. There are two horizontal lines drawn. The big analyzer's widths are changed and the smaller's offsets according to the frequency data of the music. It also shows how can you manually create a `RawTexture` for the `colors` option. The colors are animated simply by modifying the UV offset of the colors texture.

Please unmute the audio after the PG starts.

<Playground id="#3N0IS0#2" title="Line audio analyzer" description="A line audio analyzer with GreasedLine." />

### Circular audio analyzer

A cool circular audio analyzer using one line. Uses `GreasedLineTools.GetCircleLinePoints` to get the points. Setting to dash mode creates the sections. Adding some calm colors and animating the colors texture's uv in the other direction as the circle is rotating results to static colors on the circle. Modify the `widths` of the line according to the audio frequencies and you get the audio analyzer. Finally add some particles to make it cooler.

Please unmute the audio after the PG starts.

<Playground id="#H1LRZ3#387" title="Circular audio analyzer" description="A circle shaped audio analyzer with GreasedLine." />

### Light speed

Shows how to create a light speed effect using `widths`, `visibility` and scaling the lines along the `z` axis. There are several lines draw in `lazy` mode and joined into one mesh when the `updateLazy()` method is called.

Visibility is set to a very low value so the lines appears as dots at the beginning (stars). Widths are also kept low at startup. Simply by increasing the visiblity, widths and scaling the lines the effect becomes alive. Playing a bit with the glow value also helps the effect to be more attractive.

If you want a longer effect you can create more instances of the line mesh and start animating them just at the right time. You could also use only two instances and reuse them. Animate one, prepare the other, animate the second and prepare the first one. Repeat and you will get an infinite light speed effect.

<Playground id="#7MN4LZ#16" title="Light speed effect" description="Light speed effect." />

### Flower power

Slowly revealing beautiful text drawn by flowers.

Uses `GreasedLineTools.GetPointsFromText` function to get the points coordinates of the drawn text. The text is then hidden and only it's line coordinates are used. Using the `GreasedLineTools.GetPositionOnLineByVisibility` goes through the drawn text by incrementing the visibility value and adds animated `Sprite`s of flowers to slowly reveal the whole text.

If your text is not complete and flowers are missing you have to increase the capacity of the `SpriteManager` or lower the density of the flowers by lowering the value at line 47. You can also alter the target size of the flowers in the `addFlower` function.

<Playground id="#0637HC#3" title="Flower power" description="Drawing text with a nice flower effect." />

### Lighting bolts

These lightnings will make even Thor envy. Calculates the position and widths of the bolts using a simple recursive algorithm and draws the lines. Add a bit of glow and you get a cool lightning.

<Playground id="#P5GH2C#13" title="Lighting bolts" description="Create cool looking lighting bolts using GreasedLine." />

### Sparks

GreasedLine can be used to create sparks.

First generate the path the sparks will follow. Create GreasedLines each with a random color from a predefined color palette and with different widths from these paths.

<Playground id="#KIW47V#1" title="Simulating sparks - step 1" description="A cool UFO surrounded by sparks created by GreasedLine - step 1." />

Now set to dash mode and set a `dashRatio` close to 1 so only a small part of the line will be visible in dash mode. Set the number of sparks along the line to an appropriate value.

```javascript
useDash: true,
dashRatio: 0.98,
dashCount: 10
```

<Playground id="#KIW47V#2" title="Simulating sparks - step 2" description="A cool UFO surrounded by sparks created by GreasedLine - step 2." />

Now start to animate the `dashOffset` property of the `line.greasedLineMaterial`. Add a glow effect as well.

```javascript
scene.onBeforeRenderObservable.add(() => {
    const animRatio = scene.getAnimationRatio()
    for (let i = 0; i < sparkCount; i++) {
        sparks[i].line.greasedLineMaterial.dashOffset += sparks[i].speed * animRatio
    }
})
```

<Playground id="#KIW47V#3" title="Simulating sparks - step 3" description="A cool UFO surrounded by sparks created by GreasedLine - step 3." />

All we need to do now is add the UFO and some particles.

<Playground id="#KIW47V" title="Simulating sparks" description="A cool UFO surrounded by sparks created by GreasedLine." />

### Revealing text

Shows how can you make a revealing text using the `visibility` property. If the text pops up already visible just run the PG once again by click the Play button.

<Playground id="#H1LRZ3#234" title="Revealing text" description="The text is slowly drawn on the screen." />

### Supernova

A supernova like star using `GreasedLine`. It draws the main star, applies volumetric light scattering to it and adds two more outer regions to the star using a glow effect. All greased line meshes are then parented to a `TransformNode` which is rotated around the Z axis.

<Playground id="#QZTX7A#7" title="Supernova" description="A supernova like star." />

### Trees

Just some vegetation drawn using GreasedLines.

You will want to tweak the parameters for sure to get a low poly version of the tree/grass/bush otherwise this technique is not recommended for production because it generates a lot of geometry. The visual appearance is neither not quite satisfying but you can achieve quite good results by generating grass/bushes (remove the trunk of the tree). Instancing is highly recommended.

Press PLAY to generate a new one.

<Playground id="#DEHK6P#3" title="Trees" description="Parametric trees using GreasedLine." />

### Recycle logo

Simply by drawing a circle and setting the `widths` of the line in the right places to the right values we can create a recycle logo very easily.

<Playground id="#H1LRZ3#240" title="Recycle logo" description="Recycle logo created using widths." />

### Navigation path line or displaying wind/ocean currents

Shows how can you draw navigation path lines or display currents in the air or in the water. This PG shows only one line but you can ofcourse draw as many as needed.

The line uses an alpha texture which is animated using modifying the `uOffset` of the texture.

<Playground id="#F2M8GA#5" title="Navigation path or Displaying currents" description="Shows how can you draw navigation path lines or display currents." />
