
## Digest a Mesh

There is another way than adding shapes of meshes used as models to populate the SPS : you can directly "digest" a mesh.  
To digest a mesh means that the SPS will decompose this mesh geometry and use all its facets to generate the particles. So, by default, a digested mesh generates as many particles as the mesh number of facets.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.digest(model);
model.dispose();
SPS.buildMesh();
```

Note that in this case, all the generated particles have their property "position" set with some values and no more to (0, 0, 0).  
This method is obviously compatible with `addShape()` and you can even call it several times with the same model, or different models, in the same SPS.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.addShape(boxModel, 50);
SPS.digest(model);
SPS.addShape(sphereModel, 20);
SPS.digest(model, { number: 10 });
model.dispose();
sphereModel.dispose();
boxModel.dispose();
SPS.buildMesh();
```

This method accepts three optional parameters : `facetNb`, `delta` and `number`

- `facetNb` is the number of the mesh facets required to build each particle. By default, the value is set to 1, this means each particle will just be a triangle (a mesh facet). Set to 2 and you'll probably get quads instead.  
  The number of generated particles depends then on the mesh initial number of facets and on the `faceNb` value.  
  This parameter is overriden if the parameter `number` is set.
- `delta` (default 0), used with `facetNb`, allows to generate each particle with a random size between _facetNb_ and _facetNb + delta_ facets.
- `number` is the wanted number of particles. `digest()` divides then the mesh into `number` particles of the same size in term of the number of facets used per particle.  
  If `number` is greater than the total number of mesh facets, then this total number is used for the value of `number`.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.digest(model, { facetNb: 10 }); // 10 facets per particle whatever their final number
SPS.digest(model, { number: 200 }); // 200 particles whatever their final size
SPS.digest(model, { facetNb: 10, delta: 30 }); // between 10 and 40 facets per particle, randomly, whatever their final number
model.dispose();
SPS.buildMesh();
```

Example (click on the torus knot): <Playground id="#HDHQN" title="Solid Particle From Mesh Facets Example" description="Simple example of solid particles from mesh facets (click on the torus knot)"/>


# Update a Particle's Shape

- `SPS.updateParticleVertex()` _usage_ :  
  It happens before particle scaling, rotation and translation and it allows to update the vertex coordinates, color and UV of each particle.  
  This function will be called for each vertex of each particle and it will be passed the current particle, the current vertex and its current index in the particle shape.  
  The vertex is a SolidParticleVertex object, so you can access or set its properties :
  ```javascript
  vertex.position: Vector3 (x, y, z)
  vertex.color: Color4 (r, g, b, a)
  vertex.uv: Vector2 (x, y)
  ```

```javascript
SPS.computeParticleVertex = true; // false by default for performance reason
SPS.updateParticleVertex = function(particle, vertex, v) {
  // particle : the current particle object
  // vertex : the current vertex, a solidParticleVertex object
  // the index of the current vertex in the particle shape
  // example :
  if (particle.shapeID == 1) {
    vertex.position.x *= Math.random() + 1;
    vertex.position.y *= Math.random() + 1;
    vertex.position.z *= Math.random() + 1;
    vertex.color.r = Math.abs(Math.sin(v));
    vertex.color.g = 1 - vertex.color.r
    vertex.uv.x = particle.idx + v;
    vertex.uv.y = vertex.uv.x;
  }

};
```

Note well that this vertex update is not stored (the particle shape isn't modified) but just computed in the next call to `setParticles()`. So there is no value accumulation : the vertex coordinates, colors or UVs are always the initial ones when entering this function.  
Note also that the shape reference for each particle is the original shape of the mesh model you passed in `addShape()`, even if you had passed also a custom `vertexFunction` (see in the part : "Going furhter in immutable SPS").  
The good news is that the very same function can be use for `SPS.updateParticleVertex` and for the custom `vertexFunction` expected by `addShape()`.  
So to better understand how it works, here is another global pseudo-code schema :

```javascript
var particles: SolidParticles[] = [array of SolidParticle objects];
function setParticles() {
    beforeUpdateParticles();                 // your custom function
    for (let p = 0; p < nbParticles; p++) {
      var particle = particles[p];
      updateParticles(particle);             // your custom position function
      for(let v = 0; particle.vertices.length; v++) {
        var vertex = particle.vertices[v];
        updateParticleVertex(particle, vertex, v);   // your ustom vertex function
        computeAllTheVertexStuff();
      }
    }
    updateTheWholeMesh();                   // does the WebGL work
    afterUpdateParticles();                 // your ustom function
}
```

Example: <Playground id="#1X7SUN#11" title="Updating Solid Particle Geometry" description="Simple example of manipulating solid particle geometry."/>
or dancing glow-worms: <Playground id="#1X7SUN#12" title="Dancing Glow Worm Solid Particles" description="Fun Glow Worm example of changing solid particle geometry."/>


# Immutable Solid Particle System

An immutable SPS is one where particle properties will not change. This is one way to optimize your scene when it needs many similar objects that won't change afterwards, such as buildings in the distance or asteroids. Placing multiple copies of a model into one mesh means only one draw call for each frame rendering. Besides SPS there are other methods of forming a single mesh from multiple copies of one mesh; these are merge meshes, instances and thin instances.

You can create an immutable SPS in two different ways.

1. Build your SPS as explained earlier in this section and call _initParticles_ and _setParticles()_ just once, before and outside the render loop, to set your particles where and how you need. This method is quite simple However the SPS mesh is still built as updatable so that particle properties can be initiated and because of this particle data is cached, waiting for a hypothetical further change. This is the only way to do it when using billboard mode and in this case you still need to call _setParticles_ in the render loop also even if the particles don't move.
2. Set the SPS to updatable on construction using a third options parameter _SolidParticleSystem(name, scene, \{ updatable: false \})_

It is the second method that we describe here.

To construct an immutable SPS you use

```javascript
var SPS = new BABYLON.SolidParticleSystem(name, scene, { updatable: false });
```

As the mesh can't be updated you cannot initiate the particles with _initParticles()_ and calling _setParticles()_ has no effect; don't call it, you'll spare some CPU. For now the _particles_ array is not even populated! In fact no particle management function called **after** _SPS.buildMesh()_ will have any effect.

How do you set the initial particle properties when the SPS mesh can't be updated? You pass a custom function to an options object with the property _positionFunction_ when you add a model as a shape like this

```javascript
SPS.addShape(model, number_of_particles, { positionFunction: myCustomFunction });
```

Your custom function will be called as many times as the _number_of_particles_ for the added shape. It needs up to three parameters; a particle object, an index, i, which is a counter to the total number of shapes that have been added by all calls to _addShape_ and, s, which is a counter to the number of models added by calling _addShape_.

For example, a custom function has this form

```javascript
const myBuilder = function (particle, i, s) {
  // set properties of particle
};
```

When using it on two models

```javascript
SPS.addShape(model1, 1000, { positionFunction: myBuilder });
SPS.addShape(model2, 500, { positionFunction: myBuilder });
```

While model1 is added i runs from 0 to 999 and s runs from 0 to 999.
When model2 is added i runs from 1000 to 1499 and s runs from 0 to 499

The _particle_ object has the following properties that you can set

| property           | type       | default                                                     |
| ------------------ | ---------- | ----------------------------------------------------------- |
| position           | Vector3    | (0,0,0)                                                     |
| rotation           | Vector3    | (0,0,0)                                                     |
| rotationQuaternion | Quaternion | null, if _rotationQuaternion_ is set, _rotation_ is ignored |
| scaling            | Vector3    | (1,1,1)                                                     |
| pivot              | Vector3    | (0,0,0)                                                     |
| color              | Color4     | null                                                        |
| uvs                | Vector4    | (0,0,1,1)                                                   |

An example of code to build an immutable mesh

```javascript
const myBuilder = (particle, i, s) => {
  // particle is the current particle
  // i is its global index in the SPS
  // s is its index in its shape, so here from 0 to 149
  particle.rotation.y = s / 150;
  particle.position.x = s - 150;
  particle.uvs = new BABYLON.Vector4(0, 0, 0.33, 0.33); // first image from an atlas
  particle.scaling.y = Math.random() + 1;
};
const box = BABYLON.MeshBuilder.CreateBox("b", {}, scene);
const SPS = new BABYLON.SolidParticleSystem("SPS", scene, { updatable: false });
SPS.addShape(box, 150, { positionFunction: myBuilder }); // myBuilder will be called for each of the 150 boxes
const mesh = SPS.buildMesh();
```

Immutable color cube of triangle particles: <Playground id="#2FPT1A#5" title="Immutable Color Cube of Triangle Particles" description="Simple example of immutable color cube of triangle particles."/>
Immutable town with 80,000 buildings: <Playground id="#2FPT1A#36" title="Immutable Town With 80,000 Buildings" description="Simple example of an immutable town with 80,000 buildings"/>

Note that although the particles cannot move but you can still move, scale or rotate the whole SPS mesh. When there is no need for you SPS mesh to move, scale or rotate you can use the standard Babylon.js mesh _freezeXXX()_ methods for further performance gain

```javascript
SPS.mesh.freezeWorldMatrix(); // prevents from re-computing the World Matrix each frame
SPS.mesh.freezeNormals(); // prevents from re-computing the normals each frame
```

You are not restricted to using the _positionFunction_ to just a SPS created with _updatable = true_ although using _initParticles()_ and _setParticles()_ is probably easier and you have a few more particle properties.

## Solid Particle Vertex Position

In addition to the _positionFunction_ to set a particle's property there is also a _vertexFunction_ option to modify the shape of each particle by changing the positions of the vertices of the model forming the particle. The custom function you assign to the _vertexFunction_ is called once by _SPS.buildMesh()_ for each vertex of a particle.

```javascript
var myVertexFunction = function (particle, vertex, i) {
  // particle : the current particle
  // vertex : the current vertex position within the particle
  // i : index of the vertex in the particle shape
  vertex.x *= Math.random() + 1;
};
SPS.addShape(box, 150, { vertexFunction: myVertexFunction }); // the 150 boxes will have their vertices moved randomly
SPS.buildMesh();
```

Of course you can use the both properties together :

```javascript
SPS.addShape(box, 150, {
  vertexFunction: myVertexFunction,
  positionFunction: myPositionFunction,
});
```

Example with asteroids: <Playground id="#2FPT1A#2" title="Solid Particle Vertex Position Example" description="Simple example of updating solid particle vertex positions"/>

Making your SPS immutable is one way to optimize your scene. Next we will consider ways to optimize when using an updatable SPS.

## Rebuild the mesh

if a mesh, changed at creation time with `positionFunction` or `vertexFunction` has been then modified with `setParticles()`, it can be rebuild by reapplying the internally stored `positionFunction` or `vertexFunction` functions.  
Note that only the function are stored, not their results. This means that if one of your function produces different results each call (using `Math.random()` for instance), you won't get back the same SPS mesh shape but another computed shape.

```javascript
SPS.rebuildMesh();
```

Except in some very specific cases, you might not need to use this function.


Solid Particles From Mesh Facets

Digest a Mesh