
## How to Use Decals

These are usually used to add details on meshes (bullets hole, local details, etc...), a decal is a mesh produced from a subset of a previous one with a small offset in order to appear on top of it.

Creation Example :
```javascript
var decal = BABYLON.MeshBuilder.CreateDecal("decal", mesh,  {position: myPos}, scene);
```
Don't forget the _mesh_ parameter; this is the mesh to which the decal is applied.

Properties, all optional :

property|value|default value
--------|-----|-------------
position|_(Vector3)_ position of the decal (World coordinates) | (0, 0, 0)
normal|_(Vector3)_  the normal of the mesh where the decal is applied onto (World coordinates)|Vector3.Up
size|_(Vector3)_  the x, y, z sizes of the decal|(1, 1, 1)
angle|_(number)_ the angle to rotate the decal|0

<Playground id="#1BAPRM#73" title="Simple Example of Decals" description="Simple example of pasting decals in a Babylon.js scene."/> click on the cat.


## How To Highlight a Mesh

How often did you search to highlight some of your meshes in a scene? Sounds easy at first but quickly becomes an issue dealing with edges, blur and antialiasing.

If you ever needed it, this tutorial is made for you.

![illustration](/img/how_to/highlight-mesh/introduction.png)

## How to use?

Before anything else, you must ensure that your engine was created with stencil on:

```javascript
var engine = new BABYLON.Engine(canvas, true, { stencil: true });
```

The HighlightLayer relies on stencil to determine which part of the image it needs to paint.

### Default Use Case

In the most basic shape, you only need to instantiate one highlight layer in your scene and add the meshes you want to highlight in it.

```javascript
// Add the highlight layer.
var hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
```

The highlight color is driven by the second parameter of the `addMesh` method:

<Playground id="#1KUJ0A#305" title="Mesh Highlighting Example" description="Simple example of highlighting a mesh."/>

### Stop highlighting a Mesh

In case one highlighted mesh do not require highlights anymore, you can simply remove it from the layer:

```javascript
// Add the highlight layer.
var hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
hl.removeMesh(sphere);
```

<Playground id="#1KUJ0A#102" title="Stop Mesh Highlighting" description="Simple example of stoping highlighting a mesh."/>

### Emissive Input

If you wish, you could also use the emissive texture as a source for the highlight color. Simply pass true as the third parameter of the add mesh method.

```javascript
hl1.addMesh(sphere, BABYLON.Color3.Black(), true);
```

<Playground id="#1KUJ0A#57" title="Mesh Highlighting Emissive Input" description="Simple example of using the emissive input with mesh hilighting."/>

You can notice here that one side of the sphere is glowing in yellow whereas the other one is grey. The color is not uniform.

## Going further

### Overlapping Highlights

The first thing you will probably notice is the fact that overlapping highlighted meshes are not showing highlights in common areas.

```javascript
// Add the highlight layer.
var hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
hl.addMesh(ground, BABYLON.Color3.Red());
```

<Playground id="#1KUJ0A#1" title="Broken Overlapping Mesh Highlights" description="Simple example of broken overlapping mesh highlights."/>

This is the default behavior optimized for performance. If you are running your scenes on a fast enough machine, you can create several highlight layers to work around the issue:

```javascript
// Add the highlight layer.
var hl1 = new BABYLON.HighlightLayer("hl1", scene);
hl1.addMesh(sphere, BABYLON.Color3.White());
var hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());
```

<Playground id="#1KUJ0A#2" title="Overlapping Mesh Highlights" description="Simple example of overlapping mesh highlights."/>

### Blur Size

The second question you will probably have is the ability to animate the blur size of the highlight. You can dynamically change it at run time through the blur size property of the layer:

```javascript
// Add the highlight layer.
var hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());

var alpha = 0;
scene.registerBeforeRender(() => {
  alpha += 0.06;

  hl2.blurHorizontalSize = 0.3 + Math.cos(alpha) * 0.6 + 0.6;
  hl2.blurVerticalSize = 0.3 + Math.sin(alpha / 3) * 0.6 + 0.6;
});
```

<Playground id="#1KUJ0A#4" title="Blur Size Mesh Highlight" description="Simple example of blur size in the mesh highlight."/>

### Inner vs Outer Glow

Finally, you can easily enable/disable inner and outer glow on the highlight layer.

```javascript
// Add the highlight layer.
var hl1 = new BABYLON.HighlightLayer("hl1", scene);
hl1.addMesh(sphere, BABYLON.Color3.White());
hl1.outerGlow = false;

var hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());
hl2.innerGlow = false;
```

<Playground id="#1KUJ0A#3" title="Inner vs Outer Glow" description="Simple example of mesh highlighting with inner vs outer glow."/>

You can notice on the previous scene the white glowing only inside of the sphere and the red only outside of the plane.

### Exclude mesh

Depending on your scene, transparent meshes may not render correctly with other highlighted meshes:

<Playground id="#2FFOYQ#6" title="Broken Transparency Mesh Highlight" description="Simple example of broken transparency mesh highlighting."/>

In that case, try to exclude them from the highlight generation process in order to fix this:

```javascript
hl.addExcludedMesh(skybox1);
```

<Playground id="#2FFOYQ#7" title="Fixed Transparency Mesh Highlight" description="Simple example of fixed transparency mesh highlighting."/>

### Multi Camera

By default, the highlight layer will apply on all active cameras but it creates extra processing on the camera where it is not needed.

You can easily specify what camera your highlights are related to in the options:

```javascript
var hl1 = new BABYLON.HighlightLayer("hl1", scene, { camera: camera });
hl1.addMesh(sphere, BABYLON.Color3.Green());
```

<Playground id="#CDHKK#7" title="Multi-Camera" description="Simple example of mesh highlight handling with multiple cameras."/>

### Rendering Groups

If you rely on rendering groups in your application, be mindful that the highlights requires stencil and depth info of your scene to work accurately.

So you could disable the clear between rendering groups with the command: `scene.setRenderingAutoClearDepthStencil(1, false, false)` where the first parameter is the rendering group id, the second to prevent automatically clearing depth between groups and the last to prevent automatically clearing stencil information between groups.

## Options

The available members of the option object are:

- mainTextureRatio?: number - Multiplication factor apply to the canvas size to compute the render target size used to generated the glowing objects (the smaller the faster).
- mainTextureFixedSize?: number - Enforces a fixed size texture to ensure resize independent blur.
- blurTextureSizeRatio?: number - Multiplication factor apply to the main texture size in the first step of the blur to reduce the size of the picture to blur (the smaller the faster).
- blurVerticalSize?: number - How big in texel of the blur texture is the vertical blur.
- blurHorizontalSize?: number - How big in texel of the blur texture is the horizontal blur.
- alphaBlendingMode?: number - Alpha blending mode used to apply the blur. Default is combine.
- camera?: Camera - The camera attached to the layer (only this camera can see the highlights).

You can pass them during the construction of the highlight layer:

```javascript
var hl1 = new BABYLON.HighlightLayer("hl1", scene, { camera: myCamera });
```



# How to Draw Bounding Boxes

It's pretty easy to draw bounding boxes around a mesh in Babylon. You can think of a bounding box as visual box that your object(s) fit inside of perfectly. It encompasses the outer "bounds" of your object.

# Drawing a bounding box around a single object

Let's start by drawing a bounding box around a single object. You can follow along with the default [playground](https://playground.babylonjs.com/).

Let's say that you have a sphere in your scene that you've affecionately named "sphere".

To draw the bounding box around your sphere, all you need to do is set the showBoundingBox property to true.

Like this :
```javascript
sphere.showBoundingBox = true;
```
Pretty simple right? 

Here is a playground where you can see it working. <Playground id="#4F33I3" title="Drawing A Box Around A Single Object" description="Simple example of drawing a bounding box around a single object."/>

# Drawing a bounding box around multiple objects

Ok so let's make it a little more complicated. Let's say that your scene also has a ground plane in it that you've lovingly named "ground" and you'd like to draw a bounding box around the area that encomposes both the sphere and ground. 

To do this, we're going to get the minimum and maximum values of the bounding information of both meshes and compare them with special methods that compares two vector 3 values and gives you the minimum and maximum values. Then we'll set the sphere's bounding information to this new min and max. Let's try it out.

Let's start by declaring four new variables that will hold the minimum and maximum bounding information for the sphere and the ground. Like this:

```javascript
let sphereMin = sphere.getBoundingInfo().boundingBox.minimum;
let sphereMax = sphere.getBoundingInfo().boundingBox.maximum;

let groundMin = ground.getBoundingInfo().boundingBox.minimum;
let groundMax = ground.getBoundingInfo().boundingBox.maximum;
```

Ok and now let's declare 2 new variables and use those special methods metioned above to compare the min and max bounding info of both meshes.

```javascript
let newMin = BABYLON.Vector3.Minimize(sphereMin, groundMin);
let newMax = BABYLON.Vector3.Maximize(sphereMax, groundMax);
```

So now newMin and newMax are the minimum and maximum bounds of both objects! So next we will set the sphere's bounding information to a new set of bounding data based on newMin and newMax

```javascript
sphere.setBoundingInfo(new BABYLON.BoundingInfo(newMin, newMax));
```

And finally, just like before, we then display the sphere's bounding box.

```javascript
sphere.showBoundingBox = true;
```

TA DA!!! Here it is working in a playground: <Playground id="#4F33I3#1" title="Drawing A Box Around Multiple Objects" description="Simple example of drawing a bounding box around multiple objects."/>

# A better approach

Ok so there's a problem with the technique we used above. We actually changed the bounding info of the sphere to the new bounding information that encompasses both the sphere and the ground. There's actually a better way to do this, and that's to leave the sphere's bounding information alone and instead, introduce parenting into the equation!!!!

To start, let's create a new generic mesh like this:

```javascript
let parent = new BABYLON.Mesh("parent", scene);
```

And now let's use this generic mesh as the parent of the sphere and the ground;

```javascript
sphere.setParent(parent);
ground.setParent(parent);
```

Lastly, instead of setting the bounding information and displaying the bounding box of the sphere, let's change that to the parent instead.

```javascript
parent.setBoundingInfo(new BABYLON.BoundingInfo(newMin, newMax));
    
parent.showBoundingBox = true;
```

So here's what our playground looks like now. <Playground id="#4F33I3#2" title="A Better Approach For Bounding Boxes" description="Better example of drawing bounding boxes."/>

Notice something wrong? Our bounding box doesn't line up with the bounds of our objects anymore does it? There's a very good reason for that. It's because up until this point we are using LOCAL coordinates instead of world coordinates! So technically the bounding box that we're seeing is the right size, but it's drawn around the parent mesh...which in this case has it's pivot at the origin. You can clearly see the problem when you comment out this line:

```javascript
sphere.position.y = 1;
```

See that here in this playground: <Playground id="#4F33I3#3" title="A Fixed Better Approach For Bounding Boxes" description="Better example of drawing bounding boxes fixed."/>

Make a bit more sense? But what about if you wanted to get the world bounds of the positioned objects? It's actually pretty easy to do. We'll make a couple of minor modifications to the sphereMin, sphereMax, groundMin, groundMax values like this:

```javascript
let sphereMin = sphere.getBoundingInfo().boundingBox.minimumWorld;
let sphereMax = sphere.getBoundingInfo().boundingBox.maximumWorld;

let groundMin = ground.getBoundingInfo().boundingBox.minimumWorld;
let groundMax = ground.getBoundingInfo().boundingBox.maximumWorld;
```

Nice! That looks more like what you were probably expecting doesn't it?

Here's the updated playground to check out. <Playground id="#4F33I3#4" title="World Transform Bounding Boxes" description="Simple example of drawing bounding boxes in world space."/>

# One last trick

So what happens if you have a whole bunch of objects and you want to get the bounding box of all of them? You wouldn't want to do that manually for each one right? So we'll introduce a loop into the mix!

Like earlier, we'll make sure that we have a parent mesh, and that each object we want to include in the bounding box will be parented to that parent mesh.

The fun technique here is that we can loop through an array of every "child mesh" of the parent. Let's start by declaring a new variable that will be an array of all of the parent's child meshes.

```javascript
let childMeshes = parent.getChildMeshes();
```

Next, let's declare two new variables that will hold the minimum and maximum bounding values.

```javascript
let min = childMeshes[0].getBoundingInfo().boundingBox.minimumWorld;
let max = childMeshes[0].getBoundingInfo().boundingBox.maximumWorld;
```

We're setting the starting values of these min and max variables to the world min and world max bounding information for the first child mesh.

Now we can loop through all of the child meshes and continually update the min and max values with the new bounding information of each comparative mesh. It looks like this:

```javascript
for(let i=0; i<childMeshes.length; i++){
        let meshMin = childMeshes[i].getBoundingInfo().boundingBox.minimumWorld;
        let meshMax = childMeshes[i].getBoundingInfo().boundingBox.maximumWorld;

        min = BABYLON.Vector3.Minimize(min, meshMin);
        max = BABYLON.Vector3.Maximize(max, meshMax);
    }
```

SWEET! We did it! Nice job! Here's the playground result of those changes. <Playground id="#4F33I3#6" title="Loop Through Meshes to Draw Bounding Box" description="Simple example of looping through meshes to draw an overall bounding box."/>

To dive even further into bounding boxes, make sure to check out the API as well

# API

- [boundingBox](/typedoc/classes/babylon.boundingbox)




property	value	default value
property position	value (Vector3) position of the decal (World coordinates)	default value (0, 0, 0)
property normal	value (Vector3) the normal of the mesh where the decal is applied onto (World coordinates)	default value Vector3.Up
property size	value (Vector3) the x, y, z sizes of the decal	default value (1, 1, 1)
property angle	value (number) the angle to rotate the decal	default value 0

Decals

How to Use Decals

Further reading

Creating Set Shapes

Learn how to create standard set shapes in Babylon.js.