# Billboard Mode

Billboard is a special mode for meshes that ensures the mesh is always facing the camera. This is commonly used to display information to the user, such as sprites or particles.

Example :
```javascript
box.billboardMode = 7;
```

Billboard Mode Values:

value|Type
-----|-------------
0 | BILLBOARDMODE_NONE
1 | BILLBOARDMODE_X
2 | BILLBOARDMODE_Y
4 | BILLBOARDMODE_Z
7 | BILLBOARDMODE_ALL

<Playground id="#ANE052#1" title="Simple Example of Mesh Billboard Mode" description="Simple example of setting a mesh to use Billboard Mode."/>

# Integrating with parent hierarchy

Things get a bit more complex when your billboard object has a parent, because you may or may not want to integrate the parent's rotation into the mix.

If you set nothing but the billboardMode, the mesh will ignore its parent rotation:

<Playground id="#PDO1L6#2" title="Simple Example of Mesh Billboard Mode with a parent" description="Simple Example of Mesh Billboard Mode with a parent."/>

You can decide to force all billboards to take the parent rotation into account without interfering with the billboard orientation by setting `BABYLON.TransformNode.BillboardUseParentOrientation = true;`:

<Playground id="#PDO1L6#3" title="Simple Example of Mesh Billboard Mode with a parent" description="Simple Example of Mesh Billboard Mode with a parent."/>

## What are Decals for

These are usually used to add details to meshes (bullet holes, local details, etc.).
A decal is either a mesh produced from a subset of a previous one with a small offset in order to appear on top of it, or an additional texture applied to a mesh (a "decal map").

### Mesh Decals

Creation Example :

```javascript
const 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.

Starting with v5.28.0, decals can be created for rigged meshes and two new options are available:

| property | value | default value |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| localMode | defines that the computations should be done with the local mesh coordinates instead of the world space coordinates. Use this mode if you want the decal to be parented to the source mesh and move/rotate with it. | false |
| cullBackFaces | defines if the back faces should be removed from the decal mesh | false |

 
Note that `localMode=true` is automatically enforced for rigged meshes (when `sourceMesh.skeleton !== null`); otherwise, it would not work. Also, you should probably always set `localMode` to `true` even for non-rigged meshes, as it allows your decal to follow the source mesh even if the mesh moves or rotates.

The `cullBackFaces` option set to `true` will make sure the faces that are back facing the direction of projection (the inverse direction of the `normal` option) won't be created. It can help you avoid leaking a texture in the back of an object if your decal size is too big in the z dimension (`size.z`).

For example:

![Projection box](/img/features/decals/decal_projbox.webp)

In this picture, the red box represents the projection box and has the `size` dimensions passed in `options`.

As the projection box extends past the back, the projected texture will be visible there when `cullBackFaces=false`:

| front | back |
| -------------------------------------------------- | ---------------------------------------------------- |
| ![Front](/img/features/decals/decal_front.webp!350) | ![Back](/img/features/decals/decal_back_nok.webp!350) |

 
With `cullBackFaces=true`, however, the projected texture will not be visible on the back:

| front | back |
| -------------------------------------------------- | --------------------------------------------------- |
| ![Front](/img/features/decals/decal_front.webp!350) | ![Back](/img/features/decals/decal_back_ok.webp!300) |

 
Of course, you can try to lower the dimensions of the projection box:

![Projection box](/img/features/decals/decal_projbox_small.webp)

It will work even with `cullBackFaces=false` as the box does not extend past the back. But even this reduced box is too big if we want to create a decal on the arm, for example. For the arm, you would need a very tiny box, but then this tiny box may be too tiny if we project on another part of the body... So, you would need to adjust the size depending on where you create the decal, which can be tedious and difficult to achieve in practice. Using `cullBackFaces=true` with a relatively big box will work in all cases without worrying about where the decal is created.

You can use this PG to experiment with decals: <Playground id="#EEUVTY#199" title="Decals with rigged and moving meshes" description="Example of pasting decals for rigged meshes."/>

You can move over the dude / cube / mesh and left click to create a permanent decal. The "Cull back faces of decal" checkbox lets you experiment with the `cullBackFaces` option.

Note that the decal is created with `localMode=true`, that's why it works as expected for the sphere and the box (the decal will follow the rotation/movement of the mesh).

### Texture Decals (or Decal Maps)

Decal Maps are new in Babylon.js since 5.49.0. They are a way to add a decal to a mesh without creating a new mesh. A Decal Map is a texture applied to a mesh so that it appears to be a decal on the mesh.

The advantage of Decal Maps over Mesh Decals is that they are much faster to create and render. They can also be applied to meshes with morph targets or any other custom vertex deformation, which is not the case with Mesh Decals. The main drawback is that you need an additional texture for each mesh you want to apply a decal map to. Other limitations are:
* If your mesh has large extensions, you may need to use large decal textures to get enough detail for the decals.
* You cannot selectively remove some decals and not others in a decal texture: you can either remove them all (by deleting the decal texture or turning off the effect in the mesh), or none.
* The texture coordinates of the mesh must be unique, which means that each triangle in the mesh must correspond to a different texture area.
* Mipmaps are generally necessary to limit aliasing problems. If you often update a large number of decal textures, this can have a substantial impact on performance.

Decal Maps have two aspects: creating the texture/adding decals, and applying the texture to a mesh.

**Note**: Decal Maps are only supported for standard and PBR materials!

#### Creating the Decal Map

There is a new class called `MeshUVSpaceRenderer` which can be used to create and update a decal map. The main method is `renderTexture`, which allows you to add a decal to the texture:

```javascript	
const decalMap = new BABYLON.MeshUVSpaceRenderer(mesh, scene);
const texture = new BABYLON.Texture("bullet.png", scene);
const decalSize = new BABYLON.Vector3(1, 1, 1);
// find the position and the normal of the mesh where you want to add the decal
...
decalMap.renderTexture(texture, position, normal, decalSize) ;
```
Whenever you need to add a new decal to the map, just call `renderTexture`. This is much faster than creating a new mesh decal and you can do it several times per frame without any problem (think "machine gun burst").

#### Rendering a mesh with a decal map

Once you have created the decal map, you can apply it to a mesh using the `decalMap` property of the mesh and enable support for the decal map in the material:
```javascript
mesh.decalMap = decalMap;
mesh.material.decalMap.isEnabled = true;
```

Note that you must enable support for decal maps (`material.decalMap.isEnabled = true`) before rendering with the material! This is because a material plugin must be added to a material before the first rendering, and decal map is implemented by the material plugin mechanism.
However, you can disable/enable the decal map rendering at any time by updating `decalMap.isEnabled`. You can even start in a disabled state and enable it later, but the important thing is to set a value to `material.decalMap.isEnabled` (or even just access `material.decalMap`) before the first rendering. If you don't do this, `material.decalMap` will always return `null`.

Here are sample playgrounds that show how to use decal maps. Click on the meshes to add decals: 
- <Playground id="#9BVW2S#60" title="Decal maps" description="Example of using decal maps." image="/img/playgroundsAndNMEs/pg-9BVW2S-49.webp"/>
- <Playground id="#N10DXG#17" title="Decal Graffiti" description="Add graffiti with decal maps." image="/img/playgroundsAndNMEs/textureDecals_graffiti.webp" />

#### Improving results

Sometimes you may see artifacts when you add a decal to a texture.

This is because the mesh onto which you're projecting the decal has different UV islands, and artifacts appear when the decal crosses several islands.

As of version 6.33.1, you can solve the problem by passing the `uvEdgeBlending: true` option when creating the `MeshUVSpaceRenderer` instance:
```javascript
const decalMap = new BABYLON.MeshUVSpaceRenderer(mesh, scene, { uvEdgeBlending: true });
```

Results:
![Fix seam artifacts](/img/features/decals/decaltexture_fixseams.webp)

The mesh on the right has `uvEdgeBlending = true` but the mesh on the left does not.

Note that this option requires additional GPU processing, so it's a compromise between better visuals and better performance.

#### Using Decal Maps with ES6 and Tree Shaking

Decal maps are an optional feature that is not supported by default by the standard and PBR materials, to avoid an increase in code size if you do not use it.
To enable support when using ES6 and Tree Shaking, see [Babylon.js ES6 support with Tree Shaking](/setup/frameworkPackages/es6Support#tree-shaking).

In ES6 with Tree Shaking, another way to enable decal map support without having to update each material individually is to globally enable decal map plugin injection in all materials:
```javascript
BABYLON.RegisterMaterialPlugin("DecalMap", (material) => {
 material.decalMap = new BABYLON.DecalMapConfiguration(material);
 material.decalMap.isEnabled = true;
 return material.decalMap;
}) ;
```

If you do this, you should import the file `Meshes/abstractMesh.decalMap` and not `Materials/material.decalMap`!

# 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 a visual box that your object or objects fit inside 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 affectionately 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 encompasses both the sphere and the ground.

To do this, we're going to get the minimum and maximum values of the bounding information for both meshes and compare them with special methods that compare two Vector3 values and return the minimum and maximum values. Then we'll set the sphere's bounding information to these new min and max values. 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 two new variables and use those special methods mentioned 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. 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;
```

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. A better way to do this is to leave the sphere's bounding information alone and introduce parenting instead.

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 good reason for that. Up to this point, we were using local coordinates instead of world coordinates. So technically the bounding box is the right size, but it's drawn around the parent mesh, which in this case has its 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."/>

Does that make a bit more sense? But what if you want 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`, and `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 useful 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 of 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);
 }
```

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."/>

# But wait, there's a method for that

We can achieve this same effect by calling [getHierarchyBoundingVectors()](https://doc.babylonjs.com/typedoc/classes/BABYLON.Node#getHierarchyBoundingVectors) on our parent Node.

```javascript
let { min, max } = parent.getHierarchyBoundingVectors(); //Returns the bounding vectors of a Node and all its children 

parent.setBoundingInfo(new BABYLON.BoundingInfo(min, max));
```
 <Playground id="#4F33I3#793" title="Using getHierarchyBoundingVectors()" description="Example of using getHierarchyBoundingVectors() method to draw overall bounding box"/>

If we want to update the bounding box every time the parent receives a new child, we can use `onAfterWorldMatrixUpdateObservable` to listen for changes. However, calling `getHierarchyBoundingVectors()` within this observer will cause an infinite loop. To prevent this, we can check for re-entrancy on the node.

```javascript
parent.onAfterWorldMatrixUpdateObservable.add((v) => {
 setTimeout(() => {
 if (parent.detectReentrancy) {
 return;
 }
 parent.detectReentrancy = true;
 let { min, max } = parent.getHierarchyBoundingVectors(); //triggers observable causing infinite loop
 parent.setBoundingInfo(new BABYLON.BoundingInfo(min, max));
 setTimeout(() => {
 parent.detectReentrancy = false;
 });
 });
 })
```

 <Playground id="#4F33I3#794" title="Updating bounding box on child added" description="Update the bounding box when a node gets a new child"/>
 

To dive even further into bounding boxes, make sure to check out the API as well.

# API

- [boundingBox](/typedoc/classes/babylon.boundingbox)

value	Type
0	BILLBOARDMODE_NONE
1	BILLBOARDMODE_X
2	BILLBOARDMODE_Y
4	BILLBOARDMODE_Z
7	BILLBOARDMODE_ALL

BillBoard Mode