
Babylon.js comes with an integrated support for level of detail.

This feature allows you to specify different meshes based on distance to viewer (by default), or screen coverage.
For instance, here is how to define 4 levels of details for a given mesh, with distance comparison :

```javascript
var knot00 = BABYLON.Mesh.CreateTorusKnot("knot0", 0.5, 0.2, 128, 64, 2, 3, scene);
var knot01 = BABYLON.Mesh.CreateTorusKnot("knot1", 0.5, 0.2, 32, 16, 2, 3, scene);
var knot02 = BABYLON.Mesh.CreateTorusKnot("knot2", 0.5, 0.2, 24, 12, 2, 3, scene);
var knot03 = BABYLON.Mesh.CreateTorusKnot("knot3", 0.5, 0.2, 16, 8, 2, 3, scene);

knot00.addLODLevel(15, knot01);
knot00.addLODLevel(30, knot02);
knot00.addLODLevel(45, knot03);
knot00.addLODLevel(55, null);
```

The first parameter used with ```addLODLevel``` defines the distance to the camera. Beyond this distance, the specified level is used.

Each level is independent and can have its own material.
By defining a level of detail to null, you disable rendering of the current mesh, when it is viewed beyond the indicated distance to camera.

When a mesh is used as a level of detail for another mesh, it is linked to it and cannot be rendered directly.

You can remove a LOD level by using ```removeLODLevel```:

```javascript
knot00.removeLODLevel(knot02);
knot00.removeLODLevel(null);
```

You can alternatively add LOD levels by specifying screen coverage cutoff limits. Screen coverage is computed as a ratio between 0 and 1 of the mesh's rendered screen surface area, over the total screen surface area. This method has the notable advantage over distance comparison to be scale-independant, as a big object rendered from a long distance, can still be big on the screen.

To specify that your LOD levels use screen coverage instead of distance, use :

```javascript
knot00.useLODScreenCoverage = true;
```

Now, all LOD levels cutoff values will be interpreted as screen coverages. 

Be careful of 2 things though : 

First, values must be between 0 and 1 : 

```javascript
knot00.addLODLevel(0.1, knot01);
```

Second, a bigger value means a bigger size on the screen, and thus a more detailed LOD. This is the opposite order than with distance, where a big distance meant a smaller size, and therefore a less detailed LOD : 

```javascript
knot00.addLODLevel(0.7, knot01);
knot00.addLODLevel(0.1, knot02);
knot00.addLODLevel(0.01, knot03);
```

Try: <Playground id="#QE7KM" title="LOD Demo" description="Simple example of using the LOD system."/>

## Using LOD and instances
By default, instances will use LOD defined on root mesh. You do not have to specify anything on instances:

```javascript
var count = 3;
var scale = 4;

var knot00 = BABYLON.Mesh.CreateTorusKnot("knot0", 0.5, 0.2, 128, 64, 2, 3, scene);
var knot01 = BABYLON.Mesh.CreateTorusKnot("knot1", 0.5, 0.2, 32, 16, 2, 3, scene);
var knot02 = BABYLON.Mesh.CreateTorusKnot("knot2", 0.5, 0.2, 24, 12, 2, 3, scene);
var knot03 = BABYLON.Mesh.CreateTorusKnot("knot3", 0.5, 0.2, 16, 8, 2, 3, scene);

knot00.setEnabled(false);

knot00.addLODLevel(15, knot01);
knot00.addLODLevel(30, knot02);
knot00.addLODLevel(45, knot03);
knot00.addLODLevel(55, null);

for (var x = -count; x <= count; x++) {
    for (var y = -count; y <= count; y++) {
        for (var z = 5; z < 10; z++) {
            var knot = knot00.createInstance("knotI"),
            knot.position = new BABYLON.Vector3(x * scale, y * scale, z * scale);
        }
    }
}
```

Try: <Playground id="#14ESWC" title="LOD and Instances Demo" description="Simple example of using the LOD system with instances."/>


## What is morphing ?

This part is about the way to morph some kind of meshes.   
For now, it concerns only ribbons, tubes, extruded shapes and lines.   

When talking about morphing, we mean here changing the vertices positions of an existing mesh. Indices remain unchanged. This means the mesh keeps the same number of vertices, the same faces between vertices and it remains the same object in your code.
Only its vertices change their coordinates.   

If you handle a box or another fixed basic shape, it's quite easy to access to vertices positions because your mesh has an expected shape. For example, you can guess a box has 4 vertices per face.   
But when handling parametric shapes like ribbons, tubes, etc, it becomes very difficult to guess how and where vertices were positioned by the mesh constructor algorithm. For a tube, for instance, you only know the axis path you gave to build it (and radius, tessellation, of course).   

So you will learn here how to update the shape of an existing mesh and how to morph it in the render loop.   

## Ribbon
### _ribbon updatable parameter : pathArray_ 
_(reminder : only points positions can change in the path array, not the number of points. Please see the summary at the bottom of this page for more details)_ 

Let's create a ribbon.   
As explained in the Ribbon tutorial part, a good way to create a ribbon is to fill many arrays with _Vector3_ with two _for_ loops : one for each path, another one for the array of paths : the _pathArray_.   

Here we create a simple plane ribbon in the xOz plane   

```javascript
// path function
var pathFunction = function(k) {
  var path = [];
  for (var i = 0; i < 60; i++) {
    var x = i - 30;
    var y = 0;
    var z = k;
    path.push(new BABYLON.Vector3(x, y, z));
  }
  return path;
};
// ribbon creation
var sideO = BABYLON.Mesh.BACKSIDE;
var pathArray = [];
for(var i = -20; i < 20; i++) {
  pathArray.push(pathFunction(i * 2));
}
var mesh = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, false, false, 0, scene, true, sideO);
```
example : <Playground id="#1MSEBT" title="Dynamic Mesh Morph Example 1" description="Simple example of dynamically morphing a mesh."/>   _(please rotate the cam to see it)_

The important key to notice is that we set the **_updatable_** parameter to **_true_** in the _CreateRibbon()_ method : the one just between the _scene_ and the _sideO_ parameters.   

We can now imagine we want to change this existing ribbon _y_ coordinates according to a sinus function. So for each path in the existing _pathArray_ array we just change _Vector3_ coordinates.    
Note we don't create new paths or a new _pathArray_ array. We just access with indexes to every element and just change values.   
```javascript
var updatePath = function(path) {
  for (var i = 0; i < path.length; i++) {
    var x = path[i].x;
    var z = path[i].z;
    var y = 20 * Math.sin(i/ 10);
    path[i].x = x;
    path[i].y = y;
    path[i].z = z;
  }
};

// update pathArray
for(var p = 0; p < pathArray.length; p++) {
  updatePath(pathArray[p]);
}
```
The way to update then our existing mesh is quite simple : let's just re-use the _CreateRibbon()_ method and give it this mesh as last parameter with our modified _pathArray_.   
```javascript
mesh = BABYLON.Mesh.CreateRibbon(null, pathArray, null, null, null, null, null, null, mesh);
```
The other parameters than _pathArray_ and _mesh_ are just ignored when updating, so they can be set to _null_ for better understanding.   
The _CreateRibbon()_ method thus updates the given ribbon and returns it.   
You can also use the other call signature :  
```javascript
mesh = BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: pathArray, instance: mesh});
```

example :  <Playground id="#1MSEBT#1" title="Dynamic Mesh Morph Example 2" description="Simple example of dynamically morphing a mesh."/>

Well, we just updated our ribbon's shape once for now.   

If we now want its shape to evolve dynamically, we just have to set the _pathArray_ computation (fixed to change with an extra _k_ parameter) and the _CreateRibbon()_ call inside the render loop.   

```javascript
var updatePath = function(path, k) {
  for (var i = 0; i < path.length; i++) {
    var x = path[i].x;
    var z = path[i].z;
    var y = 20 * Math.sin(i/ 10) * Math.sin(k + z / 40);
    path[i].x = x;
    path[i].y = y;
    path[i].z = z;
  }
};

// path array population ...
var mesh = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, false, false, 0, scene, true);

// morphing
var k = 0;
scene.registerBeforeRender(function() {
  // path array update
  for(var p = 0; p < pathArray.length; p++) {
    updatePath(pathArray[p], k);
  }
  // ribbon update
  mesh = BABYLON.Mesh.CreateRibbon(null, pathArray, null, null, null, null, null, null, mesh);
  // or also :
  // mesh = BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: pathArray, instance: mesh});
  k += 0.05;
});
```

example :  <Playground id="#1MSEBT#3" title="Dynamic Mesh Morph Example 3" description="Simple example of dynamically morphing a mesh."/>


## Lines and DashedLines
### _lines and dashed lines updatable parameter : points_
### _lines optional updatable parameter : colors_
_(reminder : only points positions can change, not the number of points. Please see the summary at the bottom of this page for more details)_

Once we got the understanding for ribbons, we can apply it to Lines or DashedLines.
It's even easier as Lines just require a path of points as parameter.

```javascript
var points1 = [v1, v2, ..., vN]; // vector3 array
var lines = BABYLON.Mesh.CreateLines("lines", points1, scene, true);
var dashedlines = BABYLON.Mesh.CreateDashedLines("lines", points1, dashSize, gapSize, nb, scene, true);

var points2 = [u1, u2, ..., uN]; // another vector3 array
lines = BABYLON.Mesh.CreateLines(null, points2, null, null, lines);
dashedlines = BABYLON.Mesh.CreateDashedLines(null, points2, null, null, null, null, null, dashedlines);
// or
lines = BABYLON.MeshBuilder.CreateLines(null, {points: points2, instance: lines});
dashedlines = BABYLON.MeshBuilder.CreateDashedLines(null, {points: points2, instance: dashedlines});
```
We can, of course, set the update method within the render loop.

example lines:  <Playground id="#24PQRQ" title="Lines Example" description="Simple example of dynamically morphing a mesh with lines."/>
dashed lines:  <Playground id="#XKYAE#3" title="Dashed Lines Example" description="Simple example of dynamically morphing a mesh with dashed lines."/>

## Tube
### _tube updatable parameters : path, radius, radiusFunction_
_(reminder : only points positions can change in the path, not the number of points. Please see the summary at the bottom of this page for more details)_

Nothing differs for tubes. Let's create a tube and then update it according to new _path_, _radius_ or _radiusFunction_ values :

```javascript
var path1 = [v1, ..., vN]; //vector3 array : tube axis1
var radius1 = 5;
var path2 = [u1, ..., uN]; // another vector3 array : tube axis2
var radius2 = 8;
var tube = BABYLON.Mesh.CreateTube("tube", path1, radius1, 12, null, cap, scene, true);
tube = BABYLON.Mesh.CreateTube(null, path2, radius2, null, null, null, null, null, tube);
// or
tube = BABYLON.MeshBuilder.CreateTube(null, {path: path2, radius: radius2, instance: tube});
```
Of course, it also works with the _radiusFunction_ parameter :
```javascript
var radiusFunction1 = function(i, distance) { ... };
var radiusFunction2 = function(i, distance) { ... };
var tube = BABYLON.Mesh.CreateTube("tube", path1, null, 12, radiusFunction1, cap, scene, true);
tube = BABYLON.Mesh.CreateTube(null, path2, null, null, radiusFunction2, null, null, null, tube);
// or
tube = BABYLON.MeshBuilder.CreateTube(null, {path: path2, radiusFunction: radiusFunction2, instance: tube});
```

Example:  <Playground id="#ACKC2#1" title="Tube Example" description="Simple example of dynamically morphing a tube."/>

As you can read at line 53, the _radiusFunction_ is redefined here at each iteration in the _registerBeforeRender_ loop because it uses the value of the incrementing parameter _k_ : the radius changes according to each path point position and according to k varying in the time.


## Extruded shape
### _extrusion updatable parameters for ExtrudeShape(): shape, path, scale, rotation_
### _extrusion updatable parameters for ExtrudeShapeCustom(): shape, path, scaleFunction, rotateFunction_
_(reminder : only points positions can change in the path, not the number of points. Please see the summary at the bottom of this page for more details)_   

We can see extrusion as some tube generalization : a tube would be a circle _shape_ extruded along a path.   
So we have here the same update capabilities than for a tube (_path_ or shape _scale_ which would be the equivalent to tube _radius_) and some extra parameters : the _rotation_ step can be updated and the _shape_ itself also !   
It is mandatory that the new _shape_ array has the same number of Vector3 than the _shape_ used to build the original instance. A good way to assure this is simply to keep the original _shape_ instance and to modify it instead of creating a new one (or to modify a copy of it).   

```javascript
var shape1 = [s1, s2, ...sN]; // Vector3 array
var shape2 = [t1, t2, ...tN]; // another Vector3 array
var path1 = [p1, p2, ...pN]; // Vector3 array
var path2 = [q1, q2, ...qN]; // another Vector3 array
var scale1 = 1;
var scale2 = 3;
var rotation1 = 0;
var rotation2 = 0.2;
// extrusion
var extruded = BABYLON.Mesh.ExtrudeShape("ext", shape1, path1, scale1, rotation1, cap, scene, true);
// mesh update
extruded = BABYLON.Mesh.ExtrudeShape(null, shape2, path2, scale2, rotation2, null, null, null, null, extruded);
// or
extruded = BABYLON.MeshBuilder.ExtrudeShape(null, {shape: shape2, path: path2, scale: scale2, rotation: rotation2, instance: extruded});
```
Idem for _ExtrudeShapeCustom()_ accepting _scaleFunction_ and _rotationFunction_ parameters :   
```javascript
// path and shape var declared before ...
var myScale1 = function(i, distance) { ... };
var myScale2 = function(i, distance) { ... };
var myRotation1 = function(i, distance) { ... };
var myRotation2 = function(i, distance) { ... };
// extrusion
var ext = BABYLON.Mesh.ExtrudeShapeCustom("ext", shape1, path1, myScale1, myRotation1, false, false, cap, scene, true);
// mesh update
ext = BABYLON.Mesh.ExtrudeShapeCustom(null, shape2, path2, myScale2, myRotation2, null, null, null, null, null, null, ext);
// or 
ext = BABYLON.MeshBuilder.ExtrudeShapeCustom(null,{shape: shape2, path: path2, scaleFunction: myScale2, rotationFunction: myRotation2, instance: ext});
```
Both new functions can be used in the render loop.      

The funny part is, as _ExtrudeShape()_ and _ExtrudedShapeCustom()_ build the same mesh (only parameters change), you can create a simple extruded shape with _ExtrudeShape()_ and then morph it with _ExtrudeShapeCustom()_ if you need more complexity.   
```javascript
var ext = BABYLON.Mesh.ExtrudeShape("ext", shape1, path1, scale1, rotation1, cap, scene, true);
// mesh update
ext = BABYLON.Mesh.ExtrudeShapeCustom(null, shape2, path2, myScale2, myRotation2, null, null, null, null, null, null, ext);
```

Example:  <Playground id="#20IBWW#14" title="Extruded Shape Example" description="Simple example of dynamically morphing an extruded shape."/>


## Other shapes : updateMeshPositions
For now, we just talked about parametric shapes which can be updated with their own _CreateXXX()_ initial method. 
But what about the other mesh types : boxes, spheres, cylinders, etc ? 

There is no mean to update them with their initial _CreateXXX()_ because a box remains a box, a sphere remains a sphere whether you change their size, radius, etc. 
So usually, the right way to change these basic shapes is to play with their ```mesh.scale``` property. 

Nevertheleless, if you create your basic shape with its _updatable_ parameter set to true, you can access another way to morph/change the shape afterwards : the _updateMeshPositions()_ method. 

This method needs two parameters :

* a _positionFunction_ which is js function which will modify the mesh _positions_ array,
* a _computeNormals_ boolean (default = true) to skip/unskip the normals re-computation after the mesh update .

```javascript
var box = BABYLON.Mesh.CreateBox("box", 5.0, scene, true);
var positionFunction = function(positions) {
 // modify positions array values here
};
box.updateMeshPositions(positionFunction, true);
```
Example: <Playground id="#1UZIZC#6" title="Custom Shape Example" description="Simple example of dynamically morphing a custom shape."/>


## More speed : freezeNormals !

The former _CreateXXX()_ update functions try to be as much optimized as possible to run fast in the render loop.   
However, you may need some more speed for any reason (huge mesh with dozens of thousands of vertices for instance).   
So, if your mesh doesn't need to reflect the light (emissive color only for instance), you can skip the normals re-computation which is a CPU consuming process.    
Use then the _freezeNormals()_ method just after your mesh is created :   
```javascript
var tube = BABYLON.Mesh.CreateTube("tube", path, 3, 12, null, BABYLON.Mesh.NO_CAP, scene, true);
tube.freezeNormals();
// path update here ...
tube = BABYLON.Mesh.CreateTube(null, path, 3, null, null, null, null, null, null, tube);
```
If you need to reset the normals computation process on, use then once the _unfreezeNormals()_ method.
```javascript
tube.unfreezeNormals();
```
The normals will then be recomputed and re-applied on the next _CreateXXX()_ update call.   

## Summary   
* To create an updatable mesh, it is mandatory to set its _updatable_ parameter to _true_ when calling _CreateXXX()_ method.   
* To update then an existing parametric shape, we just have to use the same _CreateXXX_ method as we used to construct it. 
* Only the existing mesh and the data relative to new positions (path, pathArray, array of points) must be passed to this method, the other parameters are ignored.    
* If we want to morph the mesh, we then use the _CreateXXX()_ method within the render loop.   
In this case, it is important not to allocate new memory each frame : we access our arrays by indexes and just change values instead of creating new arrays, we access existing objects instead of instantiating new ones, etc. We also take care about the weight of each object (number of sides, number of vertices, etc).    

example : if we need to update a Lines mesh in the render loop, it is to say to update the _points_ array each frame, it is better to change each array element values (_points[i].x = newXValue; points[i].y = newYValue; points[i].z = newZValue;_) in a _for_ loop instead of instantiating a new _points_ array.   

Use case with a _path_ parameter as all parametric shapes have one :    
```javascript
var path = [v1, v2, ..., vN]; // your own array, created once
var mesh = CreateXXX("mesh", path, etc, ..., scene, true); // updatable = true : creates your initial mesh
var computeValue = function(val1, val2) { ... }; // your update logic : returns a value in function of val1 and val2
var getParam = function() { ... }; // returns a param value evolving in the render loop
var updatePath = function(path, k) { // updates the existing path array elements
  for (var i = 0; i < path.length; i++) {
    var x = computeValue(path[i].x, k);
    var y = computeValue(path[i].y, k);
    var z = computeValue(path[i].z, k);
    path[i].x = x;
    path[i].y = y;
    path[i].z = z;
  }
};

scene.registerBeforeRender(function() {
  var k = getParam();
  updatePath(path, k);
  mesh = CreateXXX(null, path, null, ..., null, mesh);
});

```


# Facet Data

## What is FacetData ?
FacetData is a feature that can be enabled on a mesh.  
As it requires some extra memory, it's not enabled by default.  
This feature provides some methods and properties to access each facet of a mesh, like the facet positions, normals or the ability to retrieve all of a mesh facets in a given zone of the world space.

## What is a mesh facet ?
We use here the term "facet" in order to be not confused with the term "face".  
A mesh can have some planar faces. For example, a box has 6 sides, so 6 planar squared faces. Each of its faces are drawn at the WebGL level with 2 triangles.  
We call "facets" these elementary triangles. 

## How to enable the facet data ?
The feature `facetData` can work for any mesh whatever it is created from BJS provided shapes (box, sphere, cylinder, tube, parametric shapes, etc), cloned ones or instances, merged ones or imported ones from an external source (Blender, etc).  
To enable this feature, just call once `updateFacetData()`.  
If the mesh belongs to some parent-child relationship, the feature is then not enabled for its parents or children.  
```javascript
var mesh = BABYLON.MeshBuilder.CreateTorusKnot("t", {radius: 2.0}, scene);
mesh.updateFacetData();
console.log(mesh.facetNb);
```
As soon as the feature is enabled, you can get the mesh total number of facets with the read-only property `.facetNb`.  

The method `updateFacetData()` creates two permanent arrays : the mesh facet positions and facet normals.  
Moreover, it logically divides the mesh according to some partitioning and stores all the facets in this partitioning.  
Unless the mesh is updated or morphed afterwards, you don't need to call this method anymore once it has been done.  
If you don't need this feature any longer, you can disabled it to release the memory with `mesh.disableFacetData()`.  
```javascript
mesh.updateFacetData();
console.log(mesh.isFacetDataEnabled);  // displays "true"
mesh.disableFacetData();
console.log(mesh.isFacetDataEnabled);  // displays "false"
```
The read-only property `.isFacetDataEnabled` returns the current state of the feature.   
Note that disposing the mesh will automatically disable its facet data.  

## The facet data tools
### Facet position
The position of a facet is the position of its barycenter.  
You can get the position of the i-th facet of a mesh with `getFacetPosition(i)`. This returns a new `Vector3` that is the world coordinates of the facet center.  
```javascript
var pos = mesh.getFacetPosition(50); // returns the world position of the mesh 50th facet
```
If you don't want to allocate a new `Vector3` per call, you can use `getFacetPositionToRef(i, ref)` instead.
```javascript
var pos = BABYLON.Vector3.Zero();
mesh.getFacetPositionToRef(50, pos); // stores the facet world position in the variable "pos"
```

Actually, in the internal array containing the facet positions, all the stored coordinates are computed in the mesh local space.  
If you need to get some facet local position, call `getFacetLocalPositions()` to get the array of the facet positions, then access the i-th element.  
```javascript
var localPositions = mesh.getFacetLocalPositions(); // returns the array of facet positions in the local space
var localPos = localPositions[50];                  // Vector3 : the 50th facet local position
```
### Facet normal
The normal of a facet is the normalized vector orthogonal to the facet plane.  
You can get the normal of the i-th facet of a mesh with `getFacetNormal(i)`. This returns a new `Vector3` that is the world coordinates of the facet normal.  
```javascript
var norm = mesh.getFacetNormal(50); // returns the world normal of the mesh 50th facet
```
If you don't want to allocate a new `Vector3` per call, you can use `getFacetNormalToRef(i, ref)` instead.
```javascript
var norm = BABYLON.Vector3.Zero();
mesh.getFacetNormalToRef(50, norm); // stores the facet world normal in the variable "norm"
```

Like for the positions, in the internal array containing the facet normals, all the stored coordinates are computed in the mesh local space.  
If you need to get some facet local normal, call `getFacetLocalNormals()` to get the array of the facet local normals, then access the i-th element.  
```javascript
var localNormals = mesh.getFacetLocalNormals();   // returns the array of facet normals in the local space
var localPos = localNormals[50];                  // Vector3 : the 50th facet local position
```
#### Note
All the methods dealing with the world coordinates use the mesh world matrix. As you may know, this matrix is automatically computed on the render call.  
If you've just moved, scaled or rotated your mesh before calling the facetData methods using the world values and you're not sure about this, you can ever force the world matrix computation.  
```javascript
mesh.rotate.y += 0.2;               // the mesh will be rotated on the next render call, but I need a rotated normal
mesh.computeWorldMatrix(true);      // force the world matrix computation
var norm = mesh.getFacetNormal(50); // returns the world normal of the mesh 50th facet
```
#### Examples :  
Displaying all the facet normals of an icosphere: <Playground id="#1YTZAC" title="Displaying Facet Data" description="Simple example of displaying all the facet normals of an icosphere."/>
Just change the mesh shape, torus knot : <Playground id="#1YTZAC#1" title="Displaying Facet Data - Torus Knot" description="Simple example of displaying all the facet normals of a torus knot."/> 
Smarter : set a box at a distance of 2 from the mesh 10th facet and keep it there, even if the mesh rotates: <Playground id="#1YTZAC#3" title="Displaying Facet Data" description="Simple example of displaying all the facet normals."/> 
Of course, you can add some translation to the mesh and even some rotation to the box: <Playground id="#1YTZAC#4" title="Displaying Facet Data" description="Simple example of displaying all the facet normals."/>   

Note also that the facet index is the same than the facet id `faceId` used by the pickingInfo object or the `faceId` used by the SPS when pickable.  
Here is an example combining pickingInfo, pickable SPS and facetData facet index: <Playground id="#2FPT1A#119" title="Combining pickingInfo and facetData" description="Simple example combining pickingInfo, pickable SPS and facetData facet index."/> 
Just click and the ball is positionned at the clicked facet position, not a the clicked point.    

### Mesh partitioning
The feature `facetData` provides also another tool called the mesh partitioning.  
The mesh is logically divided in 3D blocks aligned with the X, Y and Z axis in its local space.  
Here's an illustration about how this logical partitioning looks like (please wait until the skull is downloaded): <Playground id="#UZGNA#5" title="Mesh Partitioning" description="Simple example of mesh partitioning."/> 
In order to improve the visibility, the planes along the axis Z weren't displayed.  
As you can see, there are by default 10 subdivisions on each axis.  
When you call `updateFacetData()`, the indexes of the all the facets are sorted in the partioning array according to the facet belonging to each block.  

Thus you can get all the facet indexes from some local coordinates _(x, y, z)_ with `getFacetsAtLocalCoordinates(x, y, z)`.  
```javascript
var indexes = mesh.getFacetsAtLocalCoordinates(x, y, z);    // returns an array containing the facet indexes
if (indexes != null) {
    var worldPos = mesh.getFacetPosition(indexes[0]);       // the world position of the first facet in the block
}
```

This method returns an array containing the indexes of the facet belonging to the block containing the point at the coordinates _(x, y, z)_.  
If _(x, y, z)_ aren't in any block or if there's no facet in the block containing _(x, y, z)_, it returns `null`.   
So you can retrieve this way all the facets near some position and do your own treatment.  
This method can be called as many times you need, even in the render loop. It doesn't allocate any object in memory.    

Sometimes you don't need all the facets from a given block but only the closest facet to some world, but not local, coordinates.  
You can then use the method `getClosestFacetAtCoordinates(x, y, z)` what returns the index of the closest facet to the World coordinates _(x, y, z)_.  
```javascript
var index = mesh.getClosestFacetAtCoordinates(x, y, z); // returns the index of the closest facet to (x, y, z)
if (index != null) {
    var worldPos = mesh.getFacetPosition(index);   // the world position of this facet
}
```
The method returns just the index of the closest facet, if any.  
Actually the world coordinates _(x, y, z)_ are internally transformed to local coordinates in the mesh local system.  
If these local coordinates aren't in any block or if there's no facet in this block, it returns `null`.  
This method can be called as many times you need, even in the render loop.  

This method can also compute for you the coordinates of the projection of _(x, y, z)_ on the closest facet plane. You can imagine this projection point as the contact point of _(x, y, z)_ on the facet, or the nearest point from _(x, y, z)_ on the facet.  
Just pass it a`Vector3` as a reference :
```javascript
var projected = BABYLON.Vector3.Zero();
var index = mesh.getClosestFacetAtCoordinates(x, y, z, projected); // sets the point "projected" world coordinates
if (index != null) {
    var worldPos = mesh.getFacetPosition(index);              // the world position of this facet
    // use the vector3 projected here ...
}
```

You can even filter the returned facet index.  
Imagine that you want only the facet "facing" the coordinates _(x, y, z)_, it is to say the facet of which the dot product normal * facetPosition_to_(x, y, z) is positive.  

So just set the fifth parameter `checkFace` to `true` (default `false`) and the sixth parameter `facing?` to `true` (default `true`).  
```javascript
var projected = BABYLON.Vector3.Zero();
var index = mesh.getClosestFacetAtCoordinates(x, y, z, projected, true); // just the "facing" closest facet
if (index != null) {
    var worldPos = mesh.getFacetPosition(index);                    // the world position of this facet
    // use the vector3 projected here ...
}
```

On the contrary, if you just want the closest facet "turning its back" to _(x, y, z)_, set `checkFace` to `true` and `facing?` to `false`.  

```javascript
var projected = BABYLON.Vector3.Zero();
var index = mesh.getClosestFacetAtCoordinates(x, y, z, projected, true, false); // just the "turning back" closest facet
if (index != null) {
    var worldPos = mesh.getFacetPosition(index);                           // the world position of this facet
    // use the vector3 projected here ...
}
```

If you need it, this method exists also in the mesh local space. Everything is then expressed in the local space : _(x, y, z)_ and the returned coordinates of the projected point.  
Just call `getClosestFacetAtLocalCoordinates(x, y, z, projected, checkFace, facing?)` instead.  
```javascript
var localProj = BABYLON.Vector3.Zero();
var index = mesh.getClosestFacetAtLocalCoordinates(x, y, z, localProj); // local projection
if (index != null) {
    var worldPos = mesh.getFacetPosition(index);                    // the world position of this facet
    // use the vector3 localProj here ...
}
```
#### Note
As said before, the returned facet indexes from all these former methods are the same values than the `PickingInfo` or pickable SPS `faceId` values. 
So, you can easily mix all these features together. Ex : to get the facet normal from a picked mesh.  

#### Example
A rotating torus knot with facet data enabled and a Solid Particle System (SPS) moving balls with simple custom physics :  

* move the ball,
* get the torus closest facet to the particle,
* if any, bounce back the particle.    

 <Playground id="#7ATLX" title="Rotating Torus Knot With Facet Data" description="Simple example of rotating torus knot with facet data."/>

### Tweaking the partitioning
By default, the partitioning is set to 10 subdivisions per axis. These subdivisions are applied to the mesh bounding box.  
Actually, it's a bit smarter. It divides the biggest bounding box dimension by 10 and adjust the other ones to their ratio to this biggest.  
Example : if the mesh is sized 200 on X, 100 on Z and 3 on Y, it will subdive X in 10 subdivisions, Z in 5 subdivisions and Y in only 1.  
10 subdivisions is an arbitrary default value. You can change it according to your mesh geometry.  
Just keep in mind these two principles :

* the subdivisions (blocks) must be bigger than the facets to get accurate results,
* the more subdivisions, the fastest the method `getClosestFacetAtCoordinates()`.  

So if you deal with a huge mesh with plenty of very small facets like the BJS skull, you can easily set the subdivision number to 50, but if you deal with your own ribbon built with only one hundred big facets, you should probably reduce this number to 4.  
To set the number of subdivisions, just use the property `.partitioningSubdivisions`. It will be taken in account at the next call to `updateFacetData()` and can be changed at will.  
```javascript
mesh.partitioningSubdivisions = 50;  // set a bigger value than the default one (integer)
mesh.updateFacetData();              // now the internal partitioning has 50 blocks per axis
```
You can also enlarge a bit the space used by the blocks to have a bigger "detection zone" (remember that if _(x, y, z)_ is outside the block zone, the methods return `null`).  
By default, the block area is 1% bigger than the mesh bounding box in order to keep a little space between the peripheric blocks and their contained facets.  
You can set your own value with the property `.partitioningBBoxRatio` (default = 1.01). It will be taken in account at the next call to `updateFacetData()` and can be changed at will.  
```javascript
mesh.partitioningBBoxRatio = 1.05;   // 5% bigger than the bounding box instead of 1% bigger
mesh.updateFacetData();              // now the internal block area if 5% bigger than the bounding box
```

In order to understand, here are two examples :   
ratio = 1.20 (20% bigger) <Playground id="#UZGNA#6" title="Partitioning With a Larger Ratio" description="Simple example of partitioning with a larger ratio."/>   
ratio = 0.80  (20% smaller) <Playground id="#UZGNA#7" title="Partitioning With a Smaller Ratio" description="Simple example of partitioning with a smaller ratio."/>    
Those examples aren't pertinent, because the values are too big or too small : the block area is too far from the mesh or inside the mesh.  
Right values should keep between 1.0 and 1.10.  

### Updating Facet Data

As said in the first part, you need to call once `updateFacetData()` to enable the feature.  
This is enough if the mesh geometry keep unchanged afterwards.  

Nonetheless, if you update or morph your mesh afterwards, you need to call `updateFacetData()` again to force the partitioning recomputation.  
```javascript
var mesh = myBlenderImportedMesh;   // import some mesh from an external source
mesh.updateFacetData();             // enable facetData
// ... process here using the mesh with its current geometry and FacetData
if (condition) {
    customMorphFunction(mesh);      // update the mesh geometry
    mesh.updateFacetData();         // update the facet data
}
```
`updateFacetData()` can be called on demand, even in the render loop. However this method as a CPU cost, actually exactly the same than the static method `ComputeNormals()`.  
So if your mesh has a very huge amount of facets like the BJS skul, this can take some times.  

Some of the provided BJS mesh types are updatable/morphable by their dedicated methods : the parametric shapes and the SPS.  

* the parametric shapes are updatable by calling again the method `CreateXXX()` with the parameter `instance`,
* the SPS is updated each call to `setParticles()`.

For these specific types of updatable meshes, you don't need to call `updateFacetData()` by your own, if the feature is already enabled. 
It will be done automatically, generally in an optimized way, inside the process loop of the mesh geometry update.  
```javascript
var paths = someArrayOfPaths;
var mesh = BABYLON.MeshBuilder.CreateRibbon("m", {pathArray: paths, updatable: true}, scene); // create an updatable ribbon
mesh.updateFacetData();    // enable the feature once
// morphing function : change the ribbon geometry
var morphRibbon = function(k) {
    for (var p = 0; p < paths.length; p++) {
        var path = paths[p];
        for (var i = 0; i < path.length) {
            path[i].y = Math.sin(k) * Math.cos(i);
        }
    }
}
var k = 0.0;
// render loop
scene.registerBeforeRender(function() {
    morphRibbon(k);                     // change the geometry
    BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: paths, instance: mesh}); // actually morph the ribbon
    // No need for updateFacetData() here, CreateRibbon() just did it ... faster !
    k += 0.01;
});
```
Example :   
Custom simple physics on a dynamically morphed ribbon: <Playground id="#XVGK0#3" title="Physics On A Morphed Ribbon" description="Simple example of custom simple physics on a dynamically morphed ribbon."/>


### Facet Depth Sort  

 As you may know, for performance reasons, the facets of a given mesh are always drawn in the same order. This comes to visual issues when the mesh is transparent, concave and is no longer oriented in the right place from the camera :

<Playground id="#FWKUY0" title="Facet Depth Sort 1" description="Simple example of using facet depth sort."/>

This new feature solves the self transparency issue by sorting the mesh facets from some location (the camera position by default) just before drawing them.  
The mesh is **required** to be `updatable`.  
The depth sort is done on each call to `updateFacetData()`. It can be disabled at any time to save CPU cycles if the mesh and the camera don't move any more.  
Usage : 
```javascript
// the mesh must be updatable
var mesh = BABYLON.MeshBuilder.CreateTorusKnot("mesh", {updatable: true}, scene);
mesh.material = mat;                         // transparent material
mesh.mustDepthSortFacets = true;             // enable the depth sort, can be disabled at any time

scene.registerBeforeRender(function() {
mesh.updateFacetData();     // sort the facets each frame
```
Exampl: <Playground id="#FWKUY0#1" title="Facet Depth Sort 2" description="Simple example of using facet depth sort."/>

Depth sorted on the left, standard on the right.  

If don't need the depth sort once enabled, you can simply stop to call `updateFacetData()`.  
If for some reasons, you still need to call `updateFacetData()` but you don't need the depth sort any longer, just disabled it with `mesh.mustDepthSortFacets = false`.   
In both cases, the facet will keep the last given order.  

Note that if your mesh is a SPS (Solid Particle System), it's better to not enable the facet depth sort in the same time than the particle depth sort, simply because the underlying sort is done twice, so more CPU used and no gain.   
In this case, just choose what kind of sorting is better for you : at particle level (faster) or at facet level (more accurate).  

As the facet depth sort reorganizes the mesh indices, it **can't work** with the MultiMaterials.

Levels of Detail (LOD)

Using LOD and instances