
## Introduction

The highly recommended way to setup an environment texture is through an HDR ready file (either DDS or ENV) containing a cube texture with prefiltered MipMaps.

To load a HDR environment, you can use a [createDefaultEnvironment](/api/classes/babylon.scene#createdefaultenvironment):

```javascript
scene.createDefaultEnvironment();
```

This will load the file *environmentSpecular.env* from *assets.babylonjs.com*.

To load a custom env texture, simply set the `scene.environmentTexture`:

```javascript
var hdrTexture = new BABYLON.CubeTexture.CreateFromPrefilteredData("textures/environment.env", scene);
scene.environmentTexture = hdrTexture;
```

We are detailing below the two supported ways of creating such files. As of 4.2 we now support prefiltering directly in the Sandbox !!! .hdr files are easy to find on the web so it looks like the most convenient input for filtering.

## Sandbox

First, open the [sandbox](https://sandbox.babylonjs.com/) and then follow the steps:
- drag &amp; drop a PBR scene file ([example](https://models.babylonjs.com/PBR_Spheres.glb))
- drag &amp; drop your hdr environmentTexture file ([example](https://playground.babylonjs.com/textures/country.hdr))
- wait to see the live result (can take a bit of time)
- open the Inspector, go to the Tools, and click on `Generate .env texture`

![inspector env texture tool](/img/How_To/environment/inspector-generate-env-texture.png)

Tada !!! you now have your processed file.

## Directly use .hdr files

In case you want to directly use a .hdr file and are not able to prefilter it to a .env or a .dds from the sandbox or an external tool, you can do it at the moment your texture is loaded. 

```javascript
var reflectionTexture = new BABYLON.HDRCubeTexture("./textures/environment.hdr", scene, 128, false, true, false, true);
```

This method will involve a small delay in the loading of the texture, due to the prefiltering being achieved on-the-fly. Therefore it is preferable to use .env or .dds files for optimal performance.
Please note that WebGL2 is required for prefiltering on-the-fly.

As sometimes you might even want to fully filter in realtime (for animated reflections for instance) you might want to have a look at [the reflection probes tutorial](/divingDeeper/environment/reflectionProbes).

## External tools

The first tool rely on an open source framework named IBL Baker whereas the second one creating higher resolution results is based on a proprietary software named Lys.

Note that you can rotate your environmentTexture if needed:

```javascript
var hdrRotation = 10; // in degrees
hdrTexture.setReflectionTextureMatrix(
    BABYLON.Matrix.RotationY(
        BABYLON.Tools.ToRadians(hdrRotation)
    )
);
```

### Creating a dds environment file from IBL Baker
You can find IBLBaker on: [https://github.com/derkreature/IBLBaker](https://github.com/derkreature/IBLBaker)

After cloning the repo, you will be able to go to `/bin64` folder and launch `IBLBaker.exe`.

Now use the `Load environment` button to load a HDR image (Try one from [there](https://github.com/sbtron/BabylonJS-glTFLoader/tree/master/src/images) as well)

We recommend to play with the environment scale to define the brightness you want.

You may also want to reduce the output size by setting the specular resolution of 128 to ensure the correctness of the blur dropoff:

![iblbaker](/img/how_to/Environment/IBLbaker_DefaultSettings.png)

Once you are satisfied with the overall result, just click on `save environment` button and you are good to go! The file to pick is the SpecularHDR one.

**Please do not forget to write full name with extension in order to make the save works correctly**.

### Creating a dds environment file from LYS
[Lys](https://www.knaldtech.com/lys/) can be find on the [knaldtech](https://www.knaldtech.com/lys/) website.

Using Lys, the output quality of the generated mipmaps will be a higher standard really close in roughness response to the Unity standard materials. You could generate with Lys: 128, 256 or 512 px wide dds cube texture.

Please, follow the steps below to ensure of the physical correctness of the response.

First, you need to choose the following settings in the main window (Adapt the size according to your choices 128, 256, or 512):

![Main Window](/img/How_To/environment/Lys_DefaultSettings_Main.png)

Once done, in the preferences tab, please set the legacy dds mode (Four CC is not supported by BabylonJS):

![Preferences](/img/How_To/environment/Lys_DefaultSettings_Prefs.png)

In the export window, you can chose the appropriate options (setting DDS to 32 bits should be done last as we have seen it defaulting back to 8 bits otherwise):

![ExportSettings](/img/How_To/environment/Lys_DefaultSettings_Export.png)

Finally, you can export your texture through the main tab:

![Export](/img/How_To/environment/Lys_DefaultSettings_MainExportButton.png)

You are all set and ready to use the exported texture in the ```CubeTexture.CreateFromPrefilteredData``` function.

## Creating a compressed environment texture
As the generated DDS files can be relatively large (32Mb for a 512px wide file), we introduced in Babylon a special way to pack your texture. Here are the steps to follow to create the `.env` files used in BabylonJS:

- go to the [sandbox](https://sandbox.babylonjs.com/)
- drag &amp; drop a PBR scene file ([example](https://models.babylonjs.com/PBR_Spheres.glb))
- drag &amp; drop your dds environmentTexture file ([example](https://playground.babylonjs.com/textures/environment.dds))
- open the Inspector, go to the Tools, and click on `Generate .env texture`

![inspector env texture tool](/img/How_To/environment/inspector-generate-env-texture.png)

- you can now download and use your `.env` environment, using this bit of code:

```
scene.environmentTexture = new BABYLON.CubeTexture("environment.env", scene);
```

## What is a .env (Tech Deep Dive)

The issue we are addressing with .env is the size and quality of our IBL Environment Textures. We decided to implement our custom packing to simplify sharing and downloading those assets. This file needs to work cross platform for an easy deployment hence why we are not relying directly on compressed textures.

We are then packing in one file (similar to DDS or KTX) a json manifest header, the polynomial information and all the faces of the mipmaps chain from the prefiltered cube texture in .png format (which compresses more than decently and decode really fast in all browsers.).

In order to keep an HDR support with png, we chose to rely on RGBD as it offers a better distribution of the value in the low range than RGBM by keeping the [0-1] range untouched knowing it is generally used more frequently. It is also less complex to decode at runtime than LogLUV when needed. It seems the like the best tradeoff for us.

RGBD also offers none to low transparency in the lower range preventing browser relying on premultiplication of alpha to loose data in the most visible area. We also introduced a special offset from the max range ensuring that we are not reaching problematic values of alpha in legacy browsers (when alpha is too close from 0 the color quantization is created unacceptable banding artifacts).

In WebGL2 browsers, we are unpacking the data to HalfFloat or FullFloat texture if supported to speedup the runtime and allow correct some interpolations.

The file is also packing the polynomials harmonics vs sphericals to match what Babylon is expected internally speeding up load time by not having to compute or transform them anymore.

As rendering to LOD or even copy to LOD of Half/Fulll float texture does not work consistently on WebGL1 based browser, we are unpacking in live the data in the fragment shader. As RGBD interpolation is not correct we ensured with different test cases that the generated visual artifacts were worth the transport gain. It looks ok in the sets of textures we have been testing.

As an example of result, we can now rely on 512px cube sized texture with around 3Mb of data vs 32 Mb for the unpacked version without noticing any blocking quality drops. This also speed ups our time to first frame by not requiring the compute of the polynomials anymore.

## Using a pure cube texture
While using a dds cube texture is the best option, you may want to still rely on classic cube texture (mostly for size reason).
So, you can still do this as well:
```javascript
scene.environmentTexture = new BABYLON.CubeTexture("textures/TropicalSunnyDay", scene);
```
In this case you won't be able to get HDR rendering and some visual artifacts may appear (mostly when using glossiness or roughness).



A *blend mode* determines how, when rendering a mesh, new on-screen pixels will be mixed with existing pixels.

This may sound trivial as most of the time new pixels simply replace existing ones, which is not really what we may call _blending_ at all. However, in the case of alpha-blended meshes, new pixels do not simply overwrite existing ones: they are _combined_ according to how transparent the mesh is. This is an example of the most simple blending operation available (and also the default one): `BABYLON.Engine.ALPHA_COMBINE`.

Other blend modes exist, and allow you to achieve advanced visual effects.


## Available Blend Modes

All the available blend modes are listed below:

| Blend Mode | Effect | Additional Info |
|-------------------------------- |---------------- | -------------------- |
| `BABYLON.Engine.ALPHA_COMBINE` | This is the default blend mode for alpha-blended meshes. Blending is modulated by the alpha value of the pixel being drawn. | This is the default blend mode. |
| `BABYLON.Engine.ALPHA_ADD` | This blend mode will effectively _add_ the new pixel and existing pixel values, giving off a ghost-like effect and brightening what's behind the mesh. | |
| `BABYLON.Engine.ALPHA_SUBTRACT` | The new pixel value is subtracted from the existing one, giving off an "inverted color" effect. | Blending is **not** modulated by alpha value. |
| `BABYLON.Engine.ALPHA_MULTIPLY` | The new and existing pixel values are multiplied, thus what's behind the rendered mesh is darkened. This is more or less the opposite of the ALPHA_ADD effect. | Blending is **not** modulated by alpha value. |
| `BABYLON.Engine.ALPHA_MAXIMIZED` | This blend mode is similar to ALPHA_ADD, but gives off a less vibrant and saturated effect. | |
| `BABYLON.Engine.ALPHA_ONEONE` | This blend mode is very similar to ALPHA_ADD, except that it is not modulated by alpha value. Used internally for various visual effects. | Blending is **not** modulated by alpha value. |

Please note that the blending operations are in fact simple mathematical operations done seperately on R, G and B components of the pixel values, each one comprised between 0 and 1. As such, having a green mesh (R=0, G=1, B=0) set with ALPHA_SUBTRACT drawn over a yellow one (R=1, G=1, B=0) will give off a red value (R=1, G=0, B=0).


## How to Use Blend Modes

Using blend modes is done by manipulating the `alphaMode` property of materials, setting it to one of the constants listed above.

**This property will only be used when the rendered mesh is alpha-blended.** This is very important, because since the `alphaMode` property will have absolutely no effect on an opaque mesh, you will need to make sure your mesh is *alpha-blended* to use it.

You can force an opaque mesh to be alpha-blended by making it very slightly transparent, like so:
```javascript
mesh.visibility = 0.9999;
```

Or you can assign an opacity texture to its material (even if the opacity texture have no alpha channel):
```javascript
material.opacityTexture = material.diffuseTexture;
```



## Examples

Here is a screenshot showing the previously mentioned blend modes:

![Available Blend Modes](/img/how_to/blend-modes/blend-modes.jpg)

This playground showcases the available blend modes in action: <Playground id="#1MSIXB#4" title="Blend Modes Example" description="Simple example of blend modes in Babylon.js." image="/img/playgroundsAndNMEs/divingDeeperBlendModes1.jpg"/>


A dynamic texture works by creating a canvas onto which you can draw using all the facilities of the [HTML5 Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API). 

![dynamic texture](/img/how_to/dyntext.png)

## Creating and Applying

This is simply achieved using the `dynamicTexture` function with just three parameters,

```javascript
var myDynamicTexture = new BABYLON.DynamicTexture(name, option, scene);   
```
though the existing default values of `minmaps`, `sampling mode` and `texture format` can be overwritten by their addition.

Whereas the name and scene parameters are obvious, the `option` parameter, which determines the width and height of the dynamic texture, can be one of three values:

1. An already created canvas, in which case `canvas.width` and `canvas.height` are used;
2. An object having the properties `width` and `height`;
3. A number, in which case both width and height are set to this number.

Once created, the dynamic texture is used as the `diffuseTexture` for a material in the usual way:

```javascript
var myMaterial = new BABYLON.StandardMaterial("Mat", scene);    				
myMaterial.diffuseTexture = myDynamicTexture;
mesh.material = myMaterial;
```

## Writing Text

A `drawText` method is available so that text can be written directly onto the dynamic texture.

```javascript
myDynamicTexture.drawText(text, x, y, font, color, canvas color, invertY, update);
```

Here are the parameters:
* text: string, the words to be written;
* x: number, distance from the left-hand edge;
* y: number, distance from the top or bottom edge, depending on invertY;
* font: string, font definition in the form font-style, font-size, font_name;
* invertY: boolean, true by default in which case y is the distance from the top, when false, y is distance from the bottom and the letters reversed;
* update: boolean, true by default, the dynamic texture will immediately be updated.

<Playground id="#5ZCGRM#2" title="Drawing Text" description="Simple example of drawing text with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture1.jpg"/>

## Canvas Methods

You can obtain the canvas context using

```javascript
var ctx = myDynamicTexture.getContext();
```
exposing all the possibilities of the HTML5 canvas element. 

### Drawing Curves
As an example, drawing using a quadratic curve

```javascript
ctx.beginPath();
ctx.moveTo(75, 25);
ctx.quadraticCurveTo(25, 25, 25, 62.5);
ctx.quadraticCurveTo(25, 100, 50, 100);
ctx.quadraticCurveTo(50, 120, 30, 125);
ctx.quadraticCurveTo(60, 120, 65, 100);
ctx.quadraticCurveTo(125, 100, 125, 62.5);
ctx.quadraticCurveTo(125, 25, 75, 25);
ctx.stroke();
```

To apply the drawing, the dynamic texture needs updating

```javascript
myDynamicTexture.update();
```

**Note:** use `update(false)` if you do not want to use `invertY`.

<Playground id="#5ZCGRM#3" title="Drawing A Curve" description="Simple example of drawing a circle with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture2.jpg"/>

### Images

Images can be added to fill part or the whole of the canvas using the `drawImage` method. Remember that you will have to wait for the image to load before assigning it to the canvas and update the dynamic texture afterwards.

For whole image  
```javascript
var img = new Image();
img.src = 'PATH TO IMAGE';
img.onload = function() {

ctx.drawImage(this, 0, 0);
myDynamicTexture.update();
```

For part of the image scaled onto part of the canvas  
```javascript
var img = new Image();
img.src = 'PATH TO IMAGE';
img.onload = function() {

ctx.drawImage(this, image start x, image start y, image width, image height, canvas to x, canvas to y, destination width, destination height);
myDynamicTexture.update();
```

<Playground id="#5ZCGRM#4" title="Adding An Image" description="Simple example of adding an image with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture3.jpg"/>

## Playground Combination

This playground combines all the above techniques.

<Playground id="#5ZCGRM#1" title="All Dynamic Texture Techniques" description="Simple example of all of the dynamic texture techniques." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture4.jpg"/>

## Text and Area Matching 

For a single line of text it is possible to fit the text into a specified area or to fit an area to a specified text.

### Fit Text Into an Area.

You have a plane with width and height, `planeWidth` and `planeHeight`, to form the width and height of the dynamic texture multiply both the plane width and height by the same number to maintain aspect ratio. The number to multiply by defines the sharpness of the text, low numbers produce blurred text. Now you can create the dynamic texture.

```javascript
var DTWidth = planeWidth * 60;
var DTHeight = planeHeight * 60;
var dynamicTexture = new BABYLON.DynamicTexture("DynamicTexture", {width:DTWidth, height:DTHeight}, scene);
```

For the next stage using any size of font write and measure the width of text on the dynamic texture. 

```javascript
var ctx = dynamicTexture.getContext();
var size = 12; //any value will work
ctx.font = size + "px " + font_type;
var textWidth = ctx.measureText(text).width;
```

The ratio of text width to size of font applied can be applied to the dynamic texture width to determine the font size that will fit the plane. 

```javascript
var ratio = textWidth/size;

var font_size = Math.floor(DTWidth / ratio); 
```

If you wish you can apply a multiplier to the ratio, the larger the multiplier the smaller the text and bigger margins.

```javascript
var font_size = Math.floor(DTWidth / (ratio * 1.1)); 
```

Now set the font and draw the text

```javascript
var font = font_size + "px " + font_type;
dynamicTexture.drawText(text, null, null, font, "#000000", "#ffffff", true);
```
Finally set and apply the material for the plane.

```javascript
var mat = new BABYLON.StandardMaterial("mat", scene);
mat.diffuseTexture = dynamicTexture;
plane.material = mat;
```

<Playground id="#TMHF80#1" title="Fit Text To Plane" description="Simple example of fitting text to a plane with a dynamic texture." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture5.jpg"/>

### Fit an Area to Text

Take a plane mesh of fixed height, **planeHeight** and text with a set font size you can then calculate how wide the plane must be for the text to fit in. In order to do this you need to know the width the text will take up on a dynamic texture. This is calculated using a temporary dynamic texture and measuring the text.

```javascript
var temp = new BABYLON.DynamicTexture("DynamicTexture", 64, scene);
var tmpctx = temp.getContext();
tmpctx.font = font;
var DTWidth = tmpctx.measureText(text).width;
```

Choose a height for the dynamic texture, **DTHeight** and to maintain the aspect ratio of the plane to the dynamic texture:

1. calculate the `ratio` planeHeight:DTHeight;
2. use the ratio to calculate the width of the `planeWidth` = DTWidth * ratio;
3. create the dynamic texture to use as material with width and height, DTWidth and DTHeight;
4. draw text on dynamic texture;
4. create the plane with width and height planeWidth and planeHeight.

```javascript
var planeHeight = 3;
var DTHeight = 256; //or set as wished
var ratio = planeHeight/DTHeight;
var planeWidth = DTWidth * ratio;

var dynamicTexture = new BABYLON.DynamicTexture("DynamicTexture", {width:DTWidth, height:DTHeight}, scene, false);
var mat = new BABYLON.StandardMaterial("mat", scene);
mat.diffuseTexture = dynamicTexture;
dynamicTexture.drawText(text, null, null, font, "#000000", "#ffffff", true); //use of null, null centers the text
    
var plane = BABYLON.MeshBuilder.CreatePlane("plane", {width:planeWidth, height:planeHeight}, scene);
plane.material = mat;
```
<Playground id="#TMHF80" title="Fit Plane To Text" description="Simple example of fitting a plane to text with a dynamic texture." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture6.jpg"/>

## Serialization
The dynamic texture can be serialized with the scene using `SceneSerializer.Serialize()` or a mesh using `SceneSerializer.SerializeMesh()`.  

**Note:** Be sure that the scene is ready before serialization.

This playground demonstrates serializing a dynamic texture associated with a material on a mesh:

<Playground id="#FU0ES5" title="Drawing Text and a Curve Texture Serialized Mesh" description="Simple example of drawing text and a curve texture serialized mesh." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture7.jpg"/>


Babylon.js 1.14 introduced new parameters for the StandardMaterial: _FresnelParameters_.

![](/img/how_to/Fresnel/fresnel.jpg)

There are 5 of them:

* ```StandardMaterial.diffuseFresnelParameters```
* ```StandardMaterial.opacityFresnelParameters```
* ```StandardMaterial.reflectionFresnelParameters```
* ```StandardMaterial.emissiveFresnelParameters```
* ```StandardMaterial.refractionFresnelParameters```

## How Fresnel is working

A fresnel term is computed by the StandardMaterial in order to change the way a color is applied by using viewing angle.

For instance, you can simulate great glass or reflection effects by just using a simple fresnel. The fresnel will let you have more reflection on edges and not all on the center.

To do so, just use this code:

```javascript
material.reflectionFresnelParameters = new BABYLON.FresnelParameters();
```

You can then control if the reflection is applied on the edges or on the center. For instance, if you want the reflection on the edges (by default), you can control it using the color properties:

```javascript
material.reflectionFresnelParameters.leftColor = BABYLON.Color3.White();
material.reflectionFresnelParameters.rightColor = BABYLON.Color3.Black();
```

![](/img/how_to/Fresnel/fresnel01.jpg)

Conversely, if you only want reflection in the center:

```javascript
material.reflectionFresnelParameters.leftColor = BABYLON.Color3.Black();
material.reflectionFresnelParameters.rightColor = BABYLON.Color3.White();
```

![](/img/how_to/Fresnel/fresnel02.jpg)

By using ```bias``` and ```power``` properties, you can control how the fresnel is computed along the surface of the object according to this formula:

_finalFresnelTerm = pow(**bias** + fresnelTerm, **power**)_

By default, bias == 0 and power == 1

For instance, the following code:

```javascript
material.reflectionFresnelParameters = new BABYLON.FresnelParameters();
material.reflectionFresnelParameters.leftColor = BABYLON.Color3.Black();
material.reflectionFresnelParameters.rightColor = BABYLON.Color3.White();
material.reflectionFresnelParameters.power = 4;
```

...generates the following rendering:

![](/img/how_to/Fresnel/fresnel03.jpg)

## How to use it

A _FresnelParameter_ is defined by the following properties:
* ```isEnabled``` to activate or deactivate fresnel effect
* leftColor to define color used on edges
* rightColor to define color used on center
* bias to define bias applied to computed fresnel term
* power to compute exponent applied to fresnel term

Here is a simple example:

```javascript
material.reflectionTexture = new BABYLON.CubeTexture("Scenes/Customs/skybox/TropicalSunnyDay", scene);
material.diffuseColor = new BABYLON.Color3(0, 0, 0);
material.emissiveColor = new BABYLON.Color3(0.5, 0.5, 0.5);
material.alpha = 0.2;
material.specularPower = 16;

// Fresnel
material.reflectionFresnelParameters = new BABYLON.FresnelParameters();
material.reflectionFresnelParameters.bias = 0.1;

material.emissiveFresnelParameters = new BABYLON.FresnelParameters();
material.emissiveFresnelParameters.bias = 0.6;
material.emissiveFresnelParameters.power = 4;
material.emissiveFresnelParameters.leftColor = BABYLON.Color3.White();
material.emissiveFresnelParameters.rightColor = BABYLON.Color3.Black();

material.opacityFresnelParameters = new BABYLON.FresnelParameters();
material.opacityFresnelParameters.leftColor = BABYLON.Color3.White();
material.opacityFresnelParameters.rightColor = BABYLON.Color3.Black();
```

<Playground id="#22KZUW#6" title="Fresnel Refraction" description="Simple example of using fresnel refraction in your scene." image="/img/playgroundsAndNMEs/divingDeeperFresnel1.jpg"/>
<Playground id="#AQZJ4C#0" title="Fresnel Parameters" description="Simple example for you to explore fresnel parameters in your scene." image="/img/playgroundsAndNMEs/divingDeeperFresnel2.jpg"/>



Having a front and a back makes most sense when talking about flat meshes such as a plane, a disc or a polygon. All of which have exactly two sides both of which can be seen only when the option _sideOrientation_ is set to **BABYLON.Mesh.DOUBLESIDE**.

However, many meshes have the option _sideOrientation_ and this method applies to them as well. In which case think of the front as outside and the back as inside.

To have different textures front and back the front and back image must be in the same file, like the one below

![front and back images](/img/how_to/different-material-front-back/card.jpg)

This is then split using the _frontUVs_ and _backUVs_ options.


## FrontUVs and BackUVs

Both frontUVs and backUVs have the form Vector4(u0, v0, u1, v1) with 0&lt;=  u0, v0, u1, v1 &lt;= 1 and 
(u0, v0) are the bottom left coordinates and (u1, v1) the top right coordinates of the clipping rectangle 
of the image.

To split the image above you can form two variables

```javascript
var f = new BABYLON.Vector4(0.5,0, 1, 1); // front image = half the whole image along the width 
var b = new BABYLON.Vector4(0,0, 0.5, 1); // back image = second half along the width 
```

and then place in the options

```javascript
var plane = BABYLON.MeshBuilder.CreatePlane("plane", {height:1, width: 0.665, sideOrientation: BABYLON.Mesh.DOUBLESIDE, frontUVs: f, backUVs: b}, scene);
```

taking into account width to height ratio of section of image.

It is then just a case of creating a _StandardMaterial_ and setting the texture to the image.

```javascript
var mat = new BABYLON.StandardMaterial("", scene);
mat.diffuseTexture = new BABYLON.Texture("URL to Image File", scene);
plane.material = mat;
```

## Two Sided Examples

<Playground id="#LXZPJK#3" title="Different Images On A Plane" description="Simple example of applying different images to the front and back of a plane." image="/img/playgroundsAndNMEs/divingDeeperFrontBack1.jpg"/>
<Playground id="#4G18GY#2" title="Different Images On A Polygon" description="Simple example of applying different images to the front and back of a Polygon." image="/img/playgroundsAndNMEs/divingDeeperFrontBack2.jpg"/>

## Inside and Outside Examples

<Playground id="#165IV6#74" title="Different Images On A Tube" description="Simple example of applying different images to the front and back of a tube." image="/img/playgroundsAndNMEs/divingDeeperFrontBack3.jpg"/>
<Playground id="#K6M44R#3" title="Image On The Outside Of A Sphere" description="Simple example of applying an image to the outside of a sphere." image="/img/playgroundsAndNMEs/divingDeeperFrontBack4.jpg"/>
<Playground id="#K6M44R#4" title="Image On The Inside Of A Sphere" description="Simple example of applying an image to the inside of a sphere." image="/img/playgroundsAndNMEs/divingDeeperFrontBack5.jpg"/>

 
## Introduction

The aim of Physically Based Rendering, PBR, is to to simulate **real life lighting**.

PBR is a grouping of techniques; it does not force you to choose one in particular. Among others, we can cite some like:

- [Disney](http://blog.selfshadow.com/publications/s2012-shading-course/burley/s2012_pbs_disney_brdf_slides_v2.pdf)
- [Ashkimin Shirley BRDF](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.18.4558&rep=rep1&type=pdf)

In Babylon.js, PBR is done thanks to PBRMaterial. This material contains all features required by modern physically based rendering. On this page we look at two pre-set simplified versions that allow you to quickly get started with PBR.

You can find a demonstration of the effect of using the [PBRMaterial](https://www.babylonjs.com/demos/pbrglossy/) from the main Babylon.js website.

![pbrsample](/img/pbr.jpg)

The two additional materials are `PBRMetallicRoughnessMaterial` and `PBRSpecularGlossinessMaterial`. They both implement a specific convention based on GLTF specifications:

- [Metallic roughness convention](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#metallic-roughness-material) (This is the recommended convention)
- [Specular glossiness convention](https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_materials_pbrSpecularGlossiness/README.md)

## PBRMetallicRoughnessMaterial

This material is based on five main values:

- baseColor / baseTexture: The base color has two different interpretations depending on the value of metalness. When the material is a metal, the base color is the specific measured reflectance value at normal incidence (F0). For a non-metal the base color represents the reflected diffuse color of the material.
- metallic: Specifies the metallic scalar value of the material. Can also be used to scale the metalness values of the metallic texture.
- roughness: Specifies the roughness scalar value of the material. Can also be used to scale the roughness values of the metallic texture.
- metallicRoughnessTexture: Texture containing both the metallic value in the B channel and the roughness value in the G channel to keep better precision. Ambient occlusion can also be saved in R channel.
- environmentTexture: texture

As you are already really familiar with the Babylon Standard Material now we'll only try to address here the main differences and as the simplest setup; your only changes will be to instantiate a **PBRMetallicRoughnessMaterial** instead of a **StandardMaterial**.

```javascript
var pbr = new BABYLON.PBRMetallicRoughnessMaterial("pbr", scene);
```

Apply this material to the object of your choice, e.g.:

```javascript
sphere.material = pbr;
```

Now you can define the physical based values of your material to get a great look and feel:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 0;
pbr.roughness = 1.0;
```

<Playground id="#2FDQT5" title="Roughness Using PBR" description="Simple example PBR roughness in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro1.jpg"/>

With this specific configuration, you can see that there is no reflection at all (metallic set to 0) and no specular (roughness set to 1).

If we want to introduce more reflection we can just do the opposite:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0;
pbr.roughness = 0;
```

But in this case, we need something to reflect. To define this environment, just add this line:

```javascript
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData(
  "/textures/environment.dds",
  scene
);
```

This call will create all required data used by the materials to produce final output.

<Playground id="#2FDQT5#11" title="Reflective Metallic Surface Using PBR" description="Simple example of a reflective metallic surface using PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro2.jpg"/>

Perhaps a bit too reflective now, so let's add more roughness to give it a more golden look:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0;
pbr.roughness = 0.4;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData(
  "/textures/environment.dds",
  scene
);
```

<Playground id="#2FDQT5#12" title="Reflective Surface With Roughness Using PBR" description="Simple example of a reflective surface with roughness using PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro3.jpg"/>

To get more precise over how metallic and roughness on your object, you can also specify the metallicRoughnessTexture:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0; // set to 1 to only use it from the metallicRoughnessTexture
pbr.roughness = 1.0; // set to 1 to only use it from the metallicRoughnessTexture
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData(
  "/textures/environment.dds",
  scene
);
pbr.metallicRoughnessTexture = new BABYLON.Texture("/textures/mr.jpg", scene);
```

<Playground id="#2FDQT5#13" title="Reflective Surface With A Metallic Roughness Texture" description="Simple example of a reflective surface with a metallic roughness texture in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro4.jpg"/>

## PBRSpecularGlossinessMaterial

This material is based on five main values:

- diffuseColor / diffuseTexture: Specifies the diffuse color of the material.
- specularColor: Specifies the specular color of the material. This indicates how reflective is the material (none to mirror).
- glossiness: Specifies the glossiness of the material. This indicates "how sharp is the reflection".
- specularGlossinessTexture: Specifies both the specular color RGB and the glossiness A of the material per pixels.
- environmentTexture: texture

The setup of this material is comparable to the one used for PBRMetallicRoughnessMaterial:

```javascript
var pbr = new BABYLON.PBRSpecularGlossinessMaterial("pbr", scene);
pbr.diffuseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.specularColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.glossiness = 0.4;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData(
  "/textures/environment.dds",
  scene
);
```

<Playground id="#Z1VL3V#5" title="Surface Glossiness With PBR" description="Simple example of surface glossiness with PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro5.jpg"/>

The specularGlossinessTexture can then (like the metallicRoughnessTexture texture) be used to provide more control over specular and glossiness:

```javascript
pbr.diffuseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.specularColor = new BABYLON.Color3(1.0, 1.0, 1.0);
pbr.glossiness = 1.0;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData(
  "/textures/environment.dds",
  scene
);
pbr.specularGlossinessTexture = new BABYLON.Texture("/textures/sg.png", scene);
```

<Playground id="#Z1VL3V#4" title="Glossiness Texture Added In PBR" description="Simple example of glossiness texture added in PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro6.jpg"/>

## Light setup

Dynamic lights are an important part of your PBR setup. You can decide to have no light and only use the environment texture to light your scene or you can decide to add additional light sources to enhance your rendering.

By default, light intensities are computed using the inverse squared distance from the source. This is a type of falloff that is pretty close from what light does in real life. So, the further you are, the bigger your intensity will need to be to reach a surface.

To even go further, the intensity you define on the lights follows physics notions:

- Point and Spot lights are defined in luminous intensity (candela, m/sr)
- Directional and Hemispheric lights in illuminance (nit, cd/m2)

You'll find more info about how dynamic lighting works in mastering PBR but first we look at using high dynamic range (HDR) for use with PBR


## Introduction
<img src="/img/resources/gpu_compressed_textures/compression_cesar.png" title="Compression" caption="Photo credit : © Adam Rzepka - Centre Pompidou, MNAM-CCI /Dist. RMN-GP"/>

Using GPU compressed textures is becoming more and more important in the computer graphics / gaming land as it allows to use more assets within the same memory budget and provides better performances by reducing cache misses on the GPU side.

Note that we are speaking about **GPU compressed textures**, meaning textures that remain compressed on the GPU board. That's different from a .png or .jpg file, for eg, that holds compressed data too but which must be expanded before being sent to the GPU.

## Working with compressed texture formats
<img src="/img/resources/gpu_compressed_textures/container.jpg" title="Container" caption="Photo courtesy of Depositphotos"/>

There are a number of compression formats used by the industry (ASTC, DXT, PVRTC, etc), and depending on your device it will generally support only a (small) subset of them : see [the table here](/advanced_topics/mutliPlatTextures#khronos-texture-container-format--ktx-files) for more details. So, to support a wide range of devices, you would need to provide your assets in multiple different formats and Babylon.js would choose the right one depending on the capability of the target device.

It can be a bit tedious to generate and maintain so many formats for a given asset, so **container files** have been created. These files can either contain multiple formats of the same asset or be transcodable to multiple formats, and being the subject of this article we are going to deal with the **KTX2 container file format**.

## KTX2 container
<img src="/img/resources/gpu_compressed_textures/ktx2.jpg" title="KTX2"/>

**KTX** stands for **Khronos Texture Container** and the current incarnation is [v2.0](http://github.khronos.org/KTX-Specification/#basisu_gd) (we won't discuss v1 version) and the associated file format extension is **.ktx2**.

This file does not in fact contains different formats of the same asset but a **universal representation** of the data that can be transcoded to any format supported by the target device! We are speaking of **transcoding** instead of **expanding** because the data are not expanded per se, they are transformed to another compressed format, one supported by your target device (the universal representation being itself compressed).

Currently, the universal representation is generated by using a compression algorithm known as [Basis Universal](https://github.com/BinomialLLC/basis_universal#basis_universal), or **BasisU** for short, created by a company named Binomial. This algorithm supports two modes :
* **ETC1S** : original low/medium quality mode, produces lower file size. Work best on images, photos, map data or albedo/specular/etc textures, but don't work as well on any data that are not true color data (like normal maps, metallic/roughness maps, etc)
* **UASTC** : high quality mode, can be used on any type of textures, even for non color data maps

On top of this compression, the data can be further compressed in the UASTC case by using a [Zstandard](https://facebook.github.io/zstd/) compression scheme. Note however that this additional compression pass can lead to smaller .ktx2 file sizes but not smaller GPU compressed textures ! The data compressed with Zstandard will be expanded on the CPU side and then will be transcoded to a GPU texture.

Note that .ktx2 files can also store GPU compressed non-universal data, but as far as Babylon.js is concerned it is only dealing with the ETC1S and UASTC universal compression schemes listed above.

## Babylon.js support for .ktx2 files
<img src="/img/resources/gpu_compressed_textures/breeze.gif" title="KTX2" caption="Gif courtesy of giphy.com"/>

On **Babylon.js** side, using such files is a breeze: just create a Texture instance by pointing to the .ktx2 file you want to use, as you would with any other standard picture format (png, jpg, etc) !

The KTX2 format is also used in the **glTF** world by means of the [KHR_texture_basisu extension](https://github.com/KhronosGroup/glTF/pull/1751) : this extension simply enables you to use .ktx2 files for the images used by your .gltf/.glb files and is supported by Babylon.js.

The KTX2 implemention of Babylon.js is developped as an external package (the [KTX2 decoder](https://github.com/BabylonJS/Babylon.js/tree/master/ktx2Decoder)) designed to be small (the minified .js file is less than 22kb) and efficient. Depending on the universal representation of the data in the .ktx2 file and the compressed formats supported by the target device, the right module is used for the transcoding. Whenever possible, the [Universal Texture Transcoders](https://github.com/KhronosGroup/Universal-Texture-Transcoders) (UTT) are used, as they are both very fast and small. For transcoding formats not supported by the UTTs (yet), the [MSC Basis Transcoder](https://github.com/KhronosGroup/KTX-Software/releases) module is used instead.

*Note* : you may have already encountered/heard of **.basis** files. Those files are using the same compression scheme than the .ktx2 files but this format is not baked by any standard committee, contrary to the KTX2 format. So, you should prefer using the latter as it will become the de-facto standard.

## Tools
<img src="/img/resources/gpu_compressed_textures/tools.png" title="Tools" caption="Photo courtesy of pixels.com"/>

Now that you know why you should use .ktx2 files, you will need to actually generate them ! 

Khronos is providing [command line tools](https://github.com/KhronosGroup/KTX-Software/releases) that you can use to generate / check / dump .ktx2 files :
* **toktx.exe** is the primary tool, used to generate .ktx2 files from .png, .jpg files. There are a handful of options, just type **toktx.exe** to display them
* **ktxinfo.exe** will display useful data in human readable form about a .ktx2 file
* **ktx2check.exe** will check that your .ktx2 file is a valid file
* **ktxsc.exe** will allow you to update some parameters of an existing .ktx2 file (change the compression scheme, add a Zstandard compression, etc)

*Happy compressions !*

<img src="/img/resources/gpu_compressed_textures/compression.gif" title="KTX2" caption="Gif courtesy of giphy.com"/>



Materials allow you to cover your meshes in color and texture. How a material appears depends on the light or lights used in the scene and how it is set to react .

## Reactions to light

There are four possible ways that a material can react to light.

1. Diffuse - the basic color or texture of the material as viewed under a light;
2. Specular - the highlight given to the material by a light;
3. Emissive - the color or texture of the material as if self lit;
4. Ambient - the color or texture of the material lit by the environmental background lighting.

Diffuse and Specular material require a [light source](/divingDeeper/lights/lights_introduction) to be created.  
Ambient color requires the ambient color of the scene to be set, giving the environmental background lighting.

```javascript
scene.ambientColor = new BABYLON.Color3(1, 1, 1);
```

## Color

Create a material using

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
```

Set the material color using one, some or all of _diffuseColor_, _specularColor_, _emissiveColor_ and _ambientColor_. Remember that _ambientColor_
will only apply if the scene ambient color has been set.

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);

myMaterial.diffuseColor = new BABYLON.Color3(1, 0, 1);
myMaterial.specularColor = new BABYLON.Color3(0.5, 0.6, 0.87);
myMaterial.emissiveColor = new BABYLON.Color3(1, 1, 1);
myMaterial.ambientColor = new BABYLON.Color3(0.23, 0.98, 0.53);

mesh.material = myMaterial;
```

## Diffuse Color Example

To give an idea on how the material diffuse color reacts to the diffuse light color the following playground example shows how different color materials react to white, red, green and blue diffuse spot lights.

<Playground id="#20OAV9#325" title="Material Color Reaction to Light Color" description="Simple example of material color reacting to light color." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro1.jpg"/>

This reaction of

-   Yellow Material
-   Purple Material
-   Cyan Material
-   White Material

to white, red, green and blue diffuse spot lights can also be seen in the following image.

![ Spot Light](/img/how_to/Materials/spots1.png)

## Ambient Color Example

In the image below all spheres are lit by the same hemispheric light, with _diffuse_ red and _groundColor_ green. The first sphere has no ambient color, the middle has red ambient color defined on its material and the one on the right has material with green ambient color. The scene ambient color, which must be present, is white.

When a scene ambient color component is set to 0, for example red, then whatever the value for red in the material ambient color it will have no effect.

![Ambient](/img/how_to/Materials/ambient1.png)

<Playground id="#20OAV9#14" title="Use of Ambient Color" description="Simple example of using ambient color in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro2.jpg"/>

## Transparent Color Example

Transparency is achieved by setting a materials _alpha_ property from 0 (invisible) to 1 (opaque).

```javascript
myMaterial.alpha = 0.5;
```

<Playground id="#20OAV9#16" title="Material Transparency" description="Simple example of using transparency in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro3.jpg"/>

## Texture

Textures are formed using a saved image.

Create a material using

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
```

Set the material texture using one, some or all of _diffuseTexture_, _specularTexture_, _emissiveTexture_ and _ambientTexture_.
Notice that _ambientTexture_ is applied without the scene ambient color having been set.

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);

myMaterial.diffuseTexture = new BABYLON.Texture("PATH TO IMAGE", scene);
myMaterial.specularTexture = new BABYLON.Texture("PATH TO IMAGE", scene);
myMaterial.emissiveTexture = new BABYLON.Texture("PATH TO IMAGE", scene);
myMaterial.ambientTexture = new BABYLON.Texture("PATH TO IMAGE", scene);

mesh.material = myMaterial;
```

Note: When no normals are specified, Babylon's standard material will compute the normals.

## Texture Example

In this image all spheres are lit by the same hemispheric light, with _diffuse_ red and _groundColor_ green. The first sphere has a diffuse texture, the middle an emissive texture and the one on the right has material with red diffuse color and an ambient texture.

![Texture](/img/how_to/Materials/texture1.png)

<Playground id="#20OAV9#15" title="Material with Diffuse, Emissive, and Ambient Textures" description="Simple example of using diffuse, emissive, and ambient textures in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro4.jpg"/>

## Transparent Texture Examples

For colors, the transparency is achieved by setting a materials _alpha_ property from 0 (invisible) to 1 (opaque).

```javascript
myMaterial.alpha = 0.5;
```

<Playground id="#20OAV9#17" title="Transparent Texture Example" description="Simple example of transparent textures in your scene." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro5.jpg"/>

In addition, the image used for the texture might already have a transparency setting, such as this picture of a dog from wikimedia commons,
which has a transparent background;

![A dog](/img/how_to/Materials/dog.png)

In this case we set the _hasAlpha_ property of the **texture** to true.

```javascript
myMaterial.diffuseTexture.hasAlpha = true;
```

<Playground id="#YDO1F#18" title="Transparent Background Example" description="Simple example of a transparent background in your scene." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro6.jpg"/>

For the back faces of the cube to be visible through the transparent areas of the front faces we have to deal with back-face culling.

## Texture Packer

Some complex scenes will require a large amount of textures for just one material. In this case it can be convenient to package the textures.The advantage of using the texture packer has to be weighed against limitations such as fixed size scaling.

[More on creating a texture package](/divingDeeper/materials/advanced/texturePackage)

## Back-Face Culling

This is a method for efficiently drawing the 2D rendering of the 3D model. Usually there is no need to draw the back face of a cube, or other object,
as it will be hidden by the front face. In BabylonJS the default setting is, as you might expect, set to true. In most cases, this is helpful in maintaining the highest possible performance.

Looking at the images below, when the material property _backFaceCulling_ is true you can see that the transparent areas around the
dog are still transparent, you can see the background through them. However, you cannot see the images on the back faces as they have been culled (or removed).
When _backFaceCulling_ is false the back faces are not removed during rendering so they can be seen through the transparent areas of the front faces.

| Back Face Culling True                      | Back Face Culling False                      |
| ------------------------------------------- | -------------------------------------------- |
| ![BFC True](/img/how_to/Materials/bfc2.png) | ![BFC False](/img/how_to/Materials/bfc1.png) |

<Playground id="#YDO1F#20" title="Backface Culling Example" description="Simple example of using backface culling." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro7.jpg"/>

## WireFrame

You can see a mesh in wireframe mode by using:

```javascript
materialSphere1.wireframe = true;
```

![wireframe](/img/how_to/Materials/04-3.png)

## Local File Access

An important thing to remember, is that for security reasons, web browsers don't allow local files to be accessed for web pages. This includes any texture files you are using. You can use a local server or an image hosting service that is CORS enabled.




A range of effects can be achieved with textures using a few extra lines of code.

## Bump Map
Bump mapping is a technique to simulate bump and dents on a rendered surface. These are made by creating a **normal map** from an image. 
The means to do this can be found on the web, a search for 'normal map generator' will bring up free and paid for methods of doing this. 


![Image Bump Map](/img/how_to/Materials/bump.png)

Normal Map from Image &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Original Image

A bump map can be used with a color; with its original image or another image as below.

![Bump Example](/img/how_to/Materials/bump_spheres.png)

## Creating a Bump Map Example
Just add a _bumpTexture_ to any existing textures.

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
myMaterial.bumpTexture = new BABYLON.Texture("PATH TO NORMAL MAP", scene);
```

<Playground id="#20OAV9#23" title="Using Bump Maps" description="Simple example of applying bump maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials1.jpg"/>

## Inverting Bumps and Dents
Use _invertNormalMapX_ and/or _invertNormalMapY_ on the material.

```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
myMaterial.bumpTexture = new BABYLON.Texture("PATH TO NORMAL MAP", scene);
myMaterial.invertNormalMapX = true;
myMaterial.invertNormalMapY = true
```

## Opacity
The opacity of a material can be graded using an image with varying tranparency. The following PNG image with 
a transparency gradient can be applied to a material using _opacityTexture_

![Opacity Map](/img/how_to/Materials/degrade_map.png)

with the same gradient applied to the material as in the image below.

![Opacity Material](/img/how_to/Materials/degraded_plane.png)

<Playground id="#20OAV9#24" title="Using Opacity Maps" description="Simple example of applying opacity maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials2.jpg"/>

## Applying Opacity
Add an _opacityTexture_ to any existing texture.
```javascript
var myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
myMaterial.opacityTexture = new BABYLON.Texture("PATH TO OPACITY MAP", scene);
```

## Tiling
When a material is applied to a mesh the image used for a texture is positioned according to coordinates. 
Rather than x, y which are already in use for the 3D axes the letters u and v are used for the coordinates.

![uv axes](/img/how_to/Materials/crate.png)

To tile an image you use the _uScale_ and/or _vScale_ properties, of the texture, to set the number of tiles in each direction.

```javascript
myMaterial.diffuseTexture.uScale = 5.0;
myMaterial.diffuseTexture.vScale = 5.0;
```
## Offsetting
To offset your texture on your mesh, you  use the _uOffset_ and _vOffset_ properties, of the texture, to set the offset in each direction.

```javascript
myMaterial.diffuseTexture.uOffset = 1.5;
myMaterial.diffuseTexture.vOffset = 0.5;
```
<Playground id="#20OAV9#25" title="UV Tiling and Offset" description="Simple example of UV tiling and offset." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials3.jpg"/>

## Details maps

A detail map (also called secondary map) is generally used to add extra details to the regular main texture when viewed up close.

See for eg this marble texture without detail map:
![Without detail map](/img/how_to/Materials/detailmap_without.jpg)

You can see fairly big areas with uniform colors because the texture is zoomed in.

You can use a detail map to improve on this:
![With detail map](/img/how_to/Materials/detailmap_with.jpg)

The detail map used in the picture above only contains an albedo (diffuse) channel which is tiled ten times over the main texture.

You can also add a normal channel in the detail map:
![Bump - Without detail map](/img/how_to/Materials/detailmap_bump_without.jpg)
![Bump - With detail map](/img/how_to/Materials/detailmap_bump_with.jpg)

The first picture is the main + bump textures without detail map, the second picture is the main + bump textures + detail map with albedo and normal channels.

The detail map can contains albedo (diffuse), normal and roughness (for PBR materials only) channels, dispatched this way (following **Unity** convention):
* Red channel: greyscale albedo
* Green channel: green component of the normal map
* Blue channel: roughness
* Alpha channel: red component of the normal map

A picture can help to better visualize the channels:
![Channels of the detail map](/img/how_to/Materials/detailmap_channels.jpg)

Note that a mid-gray value (0.5 on a 0..1 scale) for the channels will disable the effect: setting 0.5 in the Green and Alpha channels will disable the detail bump map, for eg.

You can take advantage of this to make the detail map effects fade when the texture gets minimized on screen: you simply need to create mip maps that fade to the 0.5 value after a given level.

For eg, you can decide that the fading effect begins at mip level 3, and is fully achieved at level 5, meaning that from level 3 to 5 the R/G/B/A values are interpolated from their initial values to the 0.5 value, then at level 5 and onward all values are set to 0.5, disabling the detail map effects completely. If you use the mip map levels this way, don't forget to activate trilinear interpolation!

You can enable detail mapping this way:
```javascript
myMaterial.detailMap.texture = new BABYLON.Texture("textures/detailmap.png", scene);
myMaterial.detailMap.isEnabled = true;
```

You can control the strength of the albedo/normal/roughness detail effects this way:
```javascript
myMaterial.detailMap.diffuseBlendLevel = 0.1; // between 0 and 1
myMaterial.detailMap.bumpLevel = 1; // between 0 and 1
myMaterial.detailMap.roughnessBlendLevel = 0.25; // between 0 and 1
```

You can use this PG to experiment with detail maps: 
<Playground id="#5NS7A2#4" title="Using Detail Maps" description="Simple example of applying detail maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials4.jpg"/>

![Detail map PG](/img/how_to/Materials/detailmap_pg.jpg)



A multi-material is used to apply different materials to different parts of the same object as you can see below

![Multi Material Sphere](/img/how_to/Materials/multi.png)


To be able to define a multi-materials you first have to define some standard materials:

```javascript
var material0 = new BABYLON.StandardMaterial("mat0", scene);
material0.diffuseColor = new BABYLON.Color3(1, 0, 0);
material0.bumpTexture = new BABYLON.Texture("normalMap.jpg", scene);<br/>
    
var material1 = new BABYLON.StandardMaterial("mat1", scene);
material1.diffuseColor = new BABYLON.Color3(0, 0, 1);
  
var material2 = new BABYLON.StandardMaterial("mat2", scene);
material2.emissiveColor = new BABYLON.Color3(0.4, 0, 0.4);</pre>
```

Then you can create a multi-material in order to gather them all:

```javascript
var multimat = new BABYLON.MultiMaterial("multi", scene);
multimat.subMaterials.push(material0);
multimat.subMaterials.push(material1);
multimat.subMaterials.push(material2);
```

You are now able to affect the multi-material to your mesh:

```javascript
var sphere = BABYLON.Mesh.CreateSphere("Sphere0", 16, 3, scene);
sphere.material = multimat;
```

But if you do that, you will see that the sphere will only use the first submaterial (the red bumped one). This is because by default a mesh is is designed to use only one material.

You can specify which part of the mesh uses a specific material by using the _subMeshes_ property. By default, every mesh comes with only one submesh that cover the entire mesh.

To define multiple submeshes, you just have to use this code:

```javascript
sphere.subMeshes = [];
var verticesCount = sphere.getTotalVertices();

new BABYLON.SubMesh(0, 0, verticesCount, 0, 900, sphere);
new BABYLON.SubMesh(1, 0, verticesCount, 900, 900, sphere);
new BABYLON.SubMesh(2, 0, verticesCount, 1800, 2088, sphere);
```

In this case, you will have 3 parts:

* One starting from index 0 to index 900
* One starting from index 900 to index 1800
* One starting from index 1800 to index 3880


A submesh is defined with:

* The index of the material to use (this index is used to find the correct material Inside the _subMaterials_ collection of a multi-material)
* The index of the first vertex and the count of vertices used (To optimize things for collisions for instance)
* Index of the first indice to use and indices count
* The parent mesh

So with the code above, you can use the first material on the top part of the sphere, the second material on the middle part and the last material on the bottom part of the sphere.

<Playground id="#2Q4S2S#268" title="Sphere With Multi-Material" description="Simple example of applying a multi-material to a sphere." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial1.jpg"/>

## With Merged Meshes

When you [merge meshes](/divingDeeper/mesh/mergeMeshes) together setting the final parameter *multiMultiMaterial* to true the subMeshes array is automatically created with all merging meshes' subMeshes. Each subMesh's material is also included in the resulting mesh's new multiMaterial. This feature ignores the parameter (`subdivideWithSubMeshes`).

<Playground id="#INZ0Z0#59" title="Multi-Material With Merged Meshes 1" description="Simple example of applying a multi-material to merged meshes." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial2.jpg"/>

When you [merge meshes](/divingDeeper/mesh/mergeMeshes) together with the second to last parameter (`subdivideWithSubMeshes`) set to true, but the last parameter (`multiMultiMaterial`) left as false, the subMeshes array is automatically created with each merging mesh as a submesh of the new mesh. You must assign the correct subMesh index to the correct material index.

When you form `mergedMesh` by merging meshes in this array order [mesh1, mesh2], and the multiMaterials subMaterials array contains materials in the order [mat1, mat2] then for the subMesh from `mesh2` to have material `mat2` you need to set

```javascript
mergedMesh.subMeshes[1].materialIndex = 1;
```

<Playground id="#INZ0Z0#6" title="Multi-Material With Merged Meshes 2" description="Simple example of applying a multi-material to merged meshes." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial2.jpg"/>

 

Starting with Babylon.js v2.4, we introduced Parallax Mapping.

<Playground id="#10I31V#23" title="Parallax Mapping Example" description="Simple example of using parallax mapping in your scene." image="/img/playgroundsAndNMEs/divingDeeperParallaxMapping1.jpg"/>

![parallax mapping example](/img/how_to/Materials/parallax-mapping.jpg)

## What is Parallax Mapping?

Parallax Mapping is an algorithm which, based from a height map, apply an offset on the material's textures in order to accentuate the effect of relief in the geometry's surface.

While this technique is independent from Normal Mapping (a.k.a Bump) it's often used in conjunction with it. The simple reason is that the height map needed to perform Parallax Mapping is most of the time encoded in the Alpha channel of the Normal Map texture. (A diffuse texture is required for using parallax mapping).

There are many techniques that are based on the Parallax Mapping principle, Babylon.js supports two of them.

## Parallax Mapping

The core algorithm which perform an offset computation for the texture UV coordinates, based on a height map. This algorithm is really quick to perform, you can almost think of it as being free if you already are using Bump.

## Parallax Occlusion Mapping (POM)

While traditional Parallax mapping compute the offset based on one sample of the height map, the Occlusion version will make a loop to sample the height map many times in order to reach a more precise location of what the pixel to compute should reflect.

The outcome is way more realistic than traditional Parallax but there can be a performance hit that needs consideration.

## Parallax Mapping with Babylon.js

You can use Parallax Mapping through the following materials:

 - [StandardMaterial](/typedoc/classes/babylon.standardmaterial)
 - [PBRMaterial](/typedoc/classes/babylon.pbrmaterial)

In Babylon.js we think of a parallax mapping as an extension of Normal Mapping, hence to benefit of the former, you have to enable the later. The reason is that we support only the height map being encoded in the Alpha channel of the normal map, as explained above.

You have three properties to work with Parallax:

 - **useParallax**: enables Parallax Mapping over Bump. This property won't have any effect if you didn't assigned a **bumpTexture**.
 - **useParallaxOcclusion**: enables Parallax Occlusion, when setting this property, you must also set **useParallax** to true.
 - **parallaxScaleBias**: apply a scaling factor that determine which "depth" the height map should represent. A value between 0.05 and 0.1 is reasonable in Parallax, you can reach 0.2 using Parallax Occlusion.





## What Are They?
In classic texturing, we use 2D images, often pictures that have been shaped specifically to match an object. Let’s imagine you are creating a medieval fantasy game, working on a dwarf pub, where there are multiple, big, "old school" wooden tables. With classic 2D texturing, you have 3 choices:

- Create a single texture and use it on all of the tables (but every table is going to look the same)

- Create a collection of various wood textures and apply them randomly to each table

- Create a separate texture for each table, insuring that they each look different 

No choice seems to be a good one.

Enter **procedural textures**. 

Procedural texturing is a way to programmatically create a texture. There are 2 types of procedural textures: code-only, and code that references some classic 2D images, sometimes called 'refMaps' or 'sampler' images.

One main advantage of procedural textures is that they are written using a fragment shader (using GLSL in the case of Babylon.js). That means that the code generating the texture is executed by the GPU and not the CPU (that is to say, NOT executed in JavaScript code). This has a huge performance impact in a positive way.

Procedural textures can be generated:

- Only once to create the texture which is put into cache

- Every 1, 2, 3, or 4, or more frames to be able to create an animated texture (like fire)

See more about 'refresh rate' in the Custom Procedural Textures section... far below.

## Procedural Textures in Babylon.js
**Babylon.js** offers you an easy out-of-the-box way to use this kind of texture. The engine itself provides you with standard default textures that you can use right now. It also gives you the ability to create custom procedural textures and package them in a simple way.

## Using a Procedural Texture
Applying a procedural texture is just the same as using a classic one. Let’s start with a simple mesh (a cylinder in this case) and attach it to your scene:

```javascript
    var cylinder = BABYLON.Mesh.CreateCylinder("mycylinder", 7, 2, 2, 12, 1, scene);
```

Then, you need to create a StandardMaterial:

```javascript
    var material = new BABYLON.StandardMaterial("material", scene);
```

Now, create a WoodProceduralTexture object for which you need to pass a name, the size of the generated texture and the scene.

```javascript
    var texture = new BABYLON.WoodProceduralTexture("texture", 1024, scene);
```

You are almost set! All you need to do now is to associate the texture to the material as a diffuseTexture, for instance, (or emissiveTexture, specularTexture, any other) and then apply the material to the mesh.

```javascript
    material.diffuseTexture = texture;
    cylinder.material = material;
```

You can optionally change the values of special default properties.  Here is an example of setting two properties for the WoodProceduralTexture:

```javascript
    texture.woodColor = new BABYLON.Color3(0.49, 0.25, 0);
    texture.ampScale = new BABYLON.Vector2(1.0, 1.0);
```

## Noise Procedural Texture

The NoiseProceduralTexture is available out of the box with the core Babylon.js engine.

You can create one with the following code:

```
var noiseTexture = new BABYLON.NoiseProceduralTexture("perlin", 256, scene);
```

The NoiseProceduralTexture exposes the following properties:
* brightness: Gets or sets a value between 0 and 1 indicating the overall brightness of the texture (default is 0.2)
* octaves: Defines the number of octaves to process (default is 3)
* persistence: Defines the level of persistence (0.8 by default)
* animationSpeedFactor: Gets or sets animation speed factor (default is 1)

<Playground id="#K9GLE6#1" title="Experiment With Noise Properties" description="Simple example for you to experiment with noise properties." image="/img/playgroundsAndNMEs/divingDeeperProceduralTexture1.jpg"/>

## Using Standard Procedural Textures
Babylon.js also has a number of pre-built procedural textures that are gathered in the Procedural Texture library: https://github.com/BabylonJS/Babylon.js/tree/master/proceduralTexturesLibrary

You can use them in your project:
* Using npm with `npm install --save babylonjs babylonjs-procedural-textures`
* With a direct reference to: https://cdn.babylonjs.com/proceduralTexturesLibrary/babylonjs.proceduralTextures.min.js

All standard procedural textures can be used in the same ways, but they each have specific (special) properties:

- **WoodProceduralTexture**: //doc.babylonjs.com/extensions/woodproceduraltexture
- **MarbleProceduralTexture**: //doc.babylonjs.com/extensions/marbleproceduraltexture
- **BrickProceduralTexture**: //doc.babylonjs.com/extensions/brickproceduraltexture
- **FireProceduralTexture**: //doc.babylonjs.com/extensions/fireproceduraltexture
- **GrassProceduralTexture**: //doc.babylonjs.com/extensions/grassproceduraltexture
- **RoadProceduralTexture**: //doc.babylonjs.com/extensions/roadproceduraltexture
- **CloudProceduralTexture**: //doc.babylonjs.com/extensions/cloudproceduraltexture


Using reflection textures can simulate mirror like material and refraction textures can simulate looking through glass or water.

## Reflection
Reflections are created using the _relectionTexture_ property  of a material. A first use is in creating a sky using a [skybox](/divingDeeper/environment/skybox)

This sets the _relectionTexture_ to a _CubeTexture_ and the _coordinatesMode_ of the _relectionTexture_ to SKYBOX_Mode as in

```javascript
skyboxMaterial.reflectionTexture = new BABYLON.CubeTexture("PATH TO IMAGES FOLDER/COMMON PART OF NAMES", scene);
skyboxMaterial.reflectionTexture.coordinatesMode = BABYLON.Texture.SKYBOX_MODE;
```
## CubeTexture
By default six jpeg images are passed to a _CubeTexture_. The images are named in this form, commonPart\_px.jpg, commonPart\_nx.jpg,
commonPart\_py.jpg, commonPart\_ny.jpg, commonPart\_pz.jpg, commonPart\_nz.jpg corresponding to the positions shown below.

![CubeTexture Positions](/img/how_to/Materials/cubetexture1.png)

When doing this for a skybox the box created is given a large size (1000 in the skybox example above) but _CubeTexture_ can be used with any size box and is one
way of applying different textures to each side of a cube. Notice that as we are dealing with a small box and we are viewing it from the outside _backFaceCulling_ can be set to _true_. This is not
possible when the camera is inside the large skybox since in terms of rendering the sky at the back will be still behind the fron portion and will
not be rendered should _backFaceCulling = true_. However we still need to use _reflectionTexture.coordinatesMode = BABYLON.Texture.SKYBOX\_MODE_.

```javascript
var box = BABYLON.MeshBuilder.CreateBox("Box", {}, scene);
var boxMaterial = new BABYLON.StandardMaterial("mat", scene);
boxMaterial.backFaceCulling = true;
boxMaterial.reflectionTexture = new BABYLON.CubeTexture("https://babylonjsguide.github.io/img/cubeSide", scene);
boxMaterial.reflectionTexture.coordinatesMode = BABYLON.Texture.SKYBOX_MODE;
boxMaterial.diffuseColor = new BABYLON.Color3(0, 0, 0);
boxMaterial.specularColor = new BABYLON.Color3(0, 0, 0);
box.material = boxMaterial;
```

<Playground id="#UU7RQ#2" title="Different Reflections On Each Face" description="Simple example of different reflections on each face of a mesh." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction1.jpg"/>

From Babylon.js v2.4 it is also possible to use High Dynamic Range Cube Textures

### Reflecting on Skybox and a shape
Using different _coordinatesMode_ with different shapes will reflect the skybox in the shape

<Playground id="#UU7RQ#3" title="Box and CUBIC_MODE Reflection" description="Simple example of a box and CUBIC_MODE Reflection." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction2.jpg"/>
<Playground id="#UU7RQ#5" title="Ground and PLANAR_MODE Reflection" description="Simple example of a ground and PLANAR_MODE Reflection." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction3.jpg"/>
<Playground id="#UU7RQ#4" title="Sphere and PLANAR_MODE Reflection" description="Simple example of a sphere and PLANAR_MODE Reflection." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction4.jpg"/>

### Using local cubemap mode

Starting with Babylon.js v3.2, you can now use local cubemap mode when using cubemaps (with CUBIC_MODE).
Please read [this article](https://community.arm.com/graphics/b/blog/posts/reflections-based-on-local-cubemaps-in-unity), to get a precise understanding of what local cubemaps are.

CubeTexture and RenderTargetTexture (when in cube mode, like when used with [probes](/divingDeeper/environment/reflectionProbes) for instance) can be switched to local mode by setting  property named `boundingBoxSize` (by default cubemaps are in infinite mode):

```
material.reflectionTexture = new BABYLON.CubeTexture("/textures/TropicalSunnyDay", scene);
material.reflectionTexture.boundingBoxSize = new BABYLON.Vector3(100, 100, 100);
```

You can also specify a property named `boundingBoxPosition` if you want to define the center of the bounding box used for the cubemap (The place where the camera was set when generating the cubemap).

You can find an demo of local cubemaps here: <Playground id="#RNASML#37" title="Local Cubemap Example" description="Simple example of using local cubemaps in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction5.jpg"/>

## HDRCubeTexture
High Dynamic Range (HDR) images are panoramic images that cover an entire field of vision.

Below is an HDR image of a room

![Room](/img/how_to/Materials/room.png)

Replace the following line
```javascript
skyboxMaterial.reflectionTexture = new BABYLON.CubeTexture("PATH TO IMAGES FOLDER/COMMON PART OF NAMES", scene);
```
with
```javascript
skyboxMaterial.reflectionTexture = new BABYLON.HDRCubeTexture("PATH TO HDR IMAGE", scene);
```

<Playground id="#114YPX#5" title="HDR Skybox" description="Simple example of an HDR Skybox in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction6.jpg"/>

## EquiRectangularCubeTexture
Equirectangular images are browser-canvas supported images like jpeg, png, and many more. A list of image support on browsers can be found [here](https://en.wikipedia.org/wiki/Comparison_of_web_browsers#Image_format_support).

Below is an equirectangular image of a shop

![Shop](/img/resources/textures_thumbs/360photo.jpg)

Replace any of the following lines
```javascript
skyboxMaterial.reflectionTexture = new BABYLON.CubeTexture("PATH TO IMAGES FOLDER/COMMON PART OF NAMES", scene);
skyboxMaterial.reflectionTexture = new BABYLON.HDRCubeTexture("PATH TO HDR IMAGE", scene);
```
with
```javascript
cubemapDesiredSize = 512; // The cubemap desired size (the more it increases the longer the generation will be)
skyboxMaterial.reflectionTexture = new BABYLON.EquiRectangularCubeTexture("PATH TO EQUIRECTANGULAR IMAGE", scene, cubemapDesiredSize);
```

<Playground id="#6YN2X1" title="Equirectangular Skybox" description="Simple example of an equirectangular HDR Skybox in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction7.jpg"/>
<Playground id="#32H1D4" title="Equirectangular Image On A Sphere" description="Simple example of an equirectangular image on a sphere." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction8.jpg"/>
<Playground id="#RY8LDL" title="Both Combined" description="Simple example of an equirectangular skybox and equirectangular image on a sphere." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction9.jpg"/>

## Spherical Reflection Texture
Not only can a cube texture can be applied to a sphere so can a plane single image.

![Squares](/img/how_to/Materials/reflectest.png)

The above image was applied to each of four spheres, one as a diffuse texture and the other three with _reflectionTexture_ but different _coordinatesMode_. The resuls are below.

![Reflection on Spheres](/img/how_to/Materials/modes.png)

|   |   |
|-----|-----|
| Diffuse Texture | SPHERICAL_MODE |
| PLANAR\_MODE | PROJECTION\_MODE |

<Playground id="#20OAV9#26" title="Coordinate Modes Example" description="Simple example of coordinate modes." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction10.jpg"/>

## Mirrors
So far reflections have been of images, using _MirrorTexture_ obects within the scene can be reflected as in a mirror. This is simulated by
by setting the _reflectionTexture_ to a _MirrorTexture_ and applying it to a flat surface.

<Playground id="#1YAIO7#5" title="Mirrors" description="Simple example of using mirrors in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction11.jpg"/>

A real mirror is made of two parts glass and a reflected surface applied to the glass and a mirror simulated within
BJS also contains to parts; a flat surface and a reflector. (For a reflective surface such as metal or still water - think metal plus shine and water plus air boundary).

In BJS the flat surface is a ground mesh or a plane mesh and the reflector is a Mathematical Plane which is infinite and
lies on top of the flat mesh and reflects where the two overlap.

With a real mirror it is easy to tell if you are standing in front of it or behind it. For a BJS mirror an object is
in front of the mirror if the normals of the flat surface point towards the object.

### Constructing the Mirror Reflector
The flat surface should be constructed first from a ground or plane mesh. BJS can then construct the reflector using the position and normal of the flat surface. Since the
reflection is on the opposite side of the mirror to the object being reflected the normal for reflection is in the opposite direction to that
of the flat surface. For example a mesh of a plane created in BJS has a normal vector (0, 0, -1) at the time of creation and so the reflected normal will be (0, 0, 1).

The next thing to note is that renderings of meshes take place by applying transformations, the worldMatrix, to the original mesh values. It is
therefore necessary the get this worldMatrix and apply it to the data from the flat surface in order to obtain the current and actual 3D data in world space.

An example of creating a 'glass' flat surface and obtaining the reflector is

```javascript
var glass = BABYLON.MeshBuilder.CreatePlane("glass", {width: 5, height: 5}, scene);

//Position and Rotate flat surface
glass.position = new BABYLON.Vector3(0, 0, 4);
glass.rotation = new BABYLON.Vector3(Math.PI/4, Math.PI/6, Math.PI/8);

//Ensure working with new values for flat surface by computing and obtaining its worldMatrix
glass.computeWorldMatrix(true);
var glass_worldMatrix = glass.getWorldMatrix();

//Obtain normals for plane and assign one of them as the normal
var glass_vertexData = glass.getVerticesData("normal");
var glassNormal = new BABYLON.Vector3(glass_vertexData[0], glass_vertexData[1], glass_vertexData[2]);
//Use worldMatrix to transform normal into its current world value
glassNormal = new BABYLON.Vector3.TransformNormal(glassNormal, glass_worldMatrix)

//Create reflector using the position and reflected normal of the flat surface
var reflector = new BABYLON.Plane.FromPositionAndNormal(glass.position, glassNormal.scale(-1));
```

### Constructing the Mirror
Once the reflector is obtained a _MirrorTexture_ is made that can be applied to the flat surface.

```javascript
var mirrorMaterial = new BABYLON.StandardMaterial("MirrorMat", scene);
mirrorMaterial.reflectionTexture = new BABYLON.MirrorTexture("mirror", 512, scene, true);
mirrorMaterial.reflectionTexture.mirrorPlane = reflector;
mirrorMaterial.reflectionTexture.renderList = [sphere1, sphere2];
```
A _MirrorTexture_ has four parameters: name, size of the rendering buffer (should be a power of 2, the larger the number the better image quality but performance deteriorates); scene and
and optional parameter, default value false, that will generate a MIP map when set to true. This increases quality durinng scaling.

The _mirrorPlane_ is set to the constructed reflector. It is possible to directly set the _mirrorPlane_ by directly using a BABYLON.Plane(a, b, c, d) where a, b and c give the plane normal vector (a, b, c) and
d is a scalar displacement from the _mirrorPlane_ to the origin. However in all but the very simplest of situations it is more straight forward to use the method above.

The _renderList_ is an array of the meshes to be reflected in the mirror.

Finally the mirrorMaterial can be applied to the glass.

```javascript
glass.material = mirrorMaterial;
```

### Blurring the Reflection
_MirrorTexture_ can support blurred rendering with either:

* adaptiveBlurKernel: setting this value to something other than 0 will blur the texture with a specified kernel (the bigger the blurrier). The value will be adapted to the viewport size.
* blurKernel: same as adaptiveBlurKernel property but the value is not adapted to viewport size.

<Playground id="#LVTTQX#1" title="Reflection Blur" description="Simple example of using reflection blur in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction12.jpg"/>

# Refraction
In this case an object behind glass or under water for example can have its position and size changed by the refraction of light.

<Playground id="#22KZUW#15" title="Refraction" description="Simple example of using refraction in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction13.jpg"/>

Refraction is also achieved by taking a flat surface such as a plane or disc and adding, this this case, a refraction material applied to a flat mesh. The difference is that the object
that is to be refracted is placed behind the flat surface, that is the normals of the mesh all point away from the object and the refracted normals are in the same direction.

The method used above to obtain the _reflectionPlane_ could be used if necessary though in this case the normal of the flat surface is not reversed.

```javascript
var refractor = new BABYLON.Plane.FromPositionAndNormal(glass.position, glassNormal);
```

The following example, however, uses a vertical plane for the mesh at the origin and so it is straight forward to obtain the normal (0, 0, -1) and displacement, 0, for the refractor plane.

```javascript
    //Create flat surface
	var surface = BABYLON.MeshBuilder.CreatePlane("surface", {width: 15, height: 15}, scene);

	//Create the refraction material
	var refractionMaterial = new BABYLON.StandardMaterial("refraction", scene);
	refractionMaterial.diffuseColor = new BABYLON.Color3(1, 1, 1);
	refractionMaterial.refractionTexture = new BABYLON.RefractionTexture("refraction", 1024, scene, true);
	refractionMaterial.refractionTexture.refractionPlane = new BABYLON.Plane(0, 0, -1, 0);
	refractionMaterial.refractionTexture.renderList = [sphere];
	refractionMaterial.refractionTexture.depth = 5;
	refractionMaterial.indexOfRefraction = 0.5;
	surface.material = refractionMaterial;
```

Two new parameters are apparent _depth_ a property of the refractionTexture and _indexOfRefraction_ a property of the refraction material/

The two examples below show the effect of changing these.

*Note* in both examples the surfaces are transparent so that the actual position of the sphere can be identified. It is the refracted
sphere that changes psoition as the parameters are changed.

<Playground id="#1YAIO7#20" title="Refraction Depth" description="Simple example of using refraction depth in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction14.jpg"/>
<Playground id="#1YAIO7#19" title="Index Of Refraction" description="Simple example of changing the index of refraction in your scene." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction15.jpg"/>


This method is only available when creating a mesh using the _MeshBuilder_ method.

The following meshes have identifiable faces: box; cylinder; extruded polygon and polyhedron have identifiable faces and have the _faceUV_ and _faceColors_ parameters in the options using the _MeshBuilder_ method  to create them. This means that each of their faces can have a different texture or color. For colors a particular color is mapped to a particular face. For textures part of the image file is mapped to a particular face. This can be done with any image and it is often useful to use a texture atlas containing a number of images combined into one image file.

When you are concerned about the orientation of the images on the faces then it can be necessary to have different orientations of the separate images in the image file.

Using these methods on the above meshes there is no need for submaterials or submeshes.

As a prerequisite, you may want to learn more about UV mapping on [Wikipedia](https://en.wikipedia.org/wiki/UV_mapping).

## Face Numbers

The playground below shows that face numbering using `MeshBuilder.CreateBox` is that 

* side 0 faces the positive z direction
* side 1 faces the negative z direction
* side 2 faces the positive x direction
* side 3 faces the negative x direction
* side 4 faces the positive y direction
* side 5 faces the negative y direction

<Playground id="#ICLXQ8#1" title="Individual Face Numbers Example" description="Simple example of applying individual face numbers to a cube." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials1.jpg"/>

## Texture Atlas

A texture atlas also known as a __sprite sheet_ or _sprite atlas_ contains a range of images as in the example below.
_ or _sprite atlas_ contains a range of images as in the example below.

![Sprite Altlas](/img/how_to/apply-material-to-faces/spriteAtlas.png)

In this atlas there are 24 different images in 4 rows of 6. Each sprite image is mapped onto a face using uv coordinates. The u coordinate goes horizontally left to right from 0 to 1 and the v coordinate goes vertically bottom to top from 0 to 1.

To map part of the image the bottom left coordinates and top right coordinates are used. Using (0, 0) and (1, 1) will use the whole of the texture atlas. In this case there are six sprites in a row and four in a column divide the image into a grid and mark the axes as below 

![Sprite Atlas with Grid](/img/how_to/Materials/spritesheet1.jpg)

Consider the sprite in the grid space marked with a *. Counting the columns as `0, 1, 2, 3, 4, 5` and the rows as `0, 1, 2, 3` it is in column 2 and row 1 and so bottom left is `(2 * 1/6, 1 * 1/4) = (2/6, 1/4)` and top right is `((2 + 1) * 1/6, (1 + 1) * 1/4) = (3/6, 2/4)`.

In general for this texture atlas a sprite in column `c` and row `r` will have coordinates bottom left `(c * 1/6, r * 1/4)` and top right `((c + 1) * 1/6, (r + 1) * 1/4)`. With faces of the mesh numbered from 0 when you want to map face f to the sprite at grid (c, r) take an array faceUV and put

```javascript
faceUV[f] = (c * 1/6, r * 1/4, (c + 1) * 1/6, (r + 1) * 1/4);
```

Assigning the texture atlas as a texture material to the mesh is done as usual

```javascript
var mat = new BABYLON.StandardMaterial("mat", scene);
var texture = new BABYLON.Texture("URL of Texture Atlas", scene);
mat.diffuseTexture = texture;

mesh.material = mat;
``` 

## Colors

To apply a color to a face f just use an array faceColors and assign a color.

```javascript
faceColors[f] = new BABYLON.Color4(r,g,b,a); 
```

For colors only no material is needed.

These colors are BJS Color4-class values. The Color4 alpha values become active if we set `hasVertexAlpha = true` : 

## Combine Colors and Textures

You can even combine the vertex colors with a colored material.

```javascript
faceUV[f] = (c * 1/6, r * 1/4, (c + 1) * 1/6, (r + 1) * 1/4);
faceColors[f] = new BABYLON.Color4(r,g,b,a); 
```

## Examples of Per Face Material 

The box example demonstrates the full scope of this feature. At least one example is provided for each of the other types of mesh that can use _faceUV_ and _facecolors_

## Box - faceUV

A box has six faces so only the bottom row, row 0, of the texture atlas above is used on the box in these examples.

To map sprites 0 to 5 onto faces 0 to 5 it is sufficient for the face number to match the column number and to set the row number to 0.

```javascript
  var columns =  6;  // 6 columns
  var rows =  4;  // 4 rows

  var faceUV = new Array(6);

  for (var i = 0; i < 6; i++) {
    faceUV[i] = new BABYLON.Vector4(i/columns, 0, (i+1)/columns, 1/rows);
  }
```
Then this array is passed to the _faceUV_ option to be used in the _MeshBuilder.CreateBox()_ method along with any options for the size of the box and the material formed with the given texture atlas.

```javascript

var options = {
   width: 10,
   height: 3,
   depth: 5,
   faceUV: faceUV
};

var box = BABYLON.MeshBuilder.CreateBox('box', options, scene);

var mat = new BABYLON.StandardMaterial("mat", scene);
var texture = new BABYLON.Texture("URL of Texture Atlas", scene);
mat.diffuseTexture = texture;
box.material = mat;
```

<Playground id="#ICZEXW" title="FaceUVs Example" description="Simple example of using FaceUVs to create a box." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials2.jpg"/>

You do not have to map all the faces. When you just want one face with an image then just map that one face.

Take the alien sprite on row 0 and column 3 and just map this sprite to face 1.

```javascript
  var columns =  6;  // 6 columns
  var rows =  4;  // 4 rows

  var faceUV = new Array(6);

  faceUV[1] = new BABYLON.Vector4(3/columns, 0, (3+1)/columns, 1/rows);
```
<Playground id="#ICZEXW#1" title="Specific Sprite to Single Face" description="Simple example a single sprite on a single face of a box." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials3.jpg"/>

As you view the box in the above playground from different angles you will notice that the whole texture atlas is applied to all the other faces, that is the default value `(0, 0, 1, 1)`. When you want to display just the one sprite on the one face and leave the others blank then you need to set all the other faceUV values to `(0, 0, 0, 0)`.

```javascript
  var columns =  6;  // 6 columns
  var rows =  4;  // 4 rows

  var faceUV = new Array(6);

  //set all values to zero
  for (var i = 0; i < 6; i++) {
    faceUV[i] = new BABYLON.Vector4(0, 0, 0, 0);
  }

  //overwrite wanted face with sprite coordinates
  faceUV[1] = new BABYLON.Vector4(3/columns, 0, (3+1)/columns, 1/rows);
```
  
<Playground id="#ICZEXW#2" title="Sprite On Face With Other Blank Faces" description="Simple Example of applying a sprite to the side of a box with the other box faces blank." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials4.jpg"/>

Of course you can do this with one, two, three, four, or five the box faces.


Want add some all over color to the box then just add in a_diffuseColor_ to your material.

<Playground id="#ICZEXW#3" title="Sprite on Box Face With Material Color" description="Simple Example of applying a sprite to the side of a box with applied material color." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials5.jpg"/>

You can also use one texture atlas to apply two different images from the same sheet onto two different meshes.  

<Playground id="#ICZEXW#7" title="Sprites Sheet On Faces of 2 Meshes" description="Simple Example of applying a sprite sheet to the faces of different meshes." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials6.jpg"/>

Looking closer at the face images around the sides you will see some images are at 90 degrees to others. Unfortunately should you want to have all images around the side to have the same orientation this is not possible by only adjusting UV coordinates. What can be done by swapping coordinates is considered next, followed by a method using an adjustment to the texture atlas to orientate images on the sides.

### How To Orientate a Sprite on a Face with faceUV

Because of how UV coordinates are interpreted it is possible to reflect a sprite horizontally, vertically or both (which is the same as an 180 degree rotation). Any other rotation has to be dealt with by rotating the sprite within the texture atlas.

Consider the alien with bottom left and top right coordinates for UV as shown.

![alien sprite](/img/how_to/Materials/alienuv.jpg)

To set this to face one in its current orientation you would use

```javascript
faceUV[1] = new BABYLON.Vector4(Ubottom_left, Vbottom_left, Utop_right, Vtop_right);
```
To reflect in a vertical line swap the horizontal, U, coordinates.

```javascript
faceUV[1] = new BABYLON.Vector4(Utop_right, Vbottom_left, Ubottom_left, Vtop_right);
```

To reflect in a horizontal line swap the vertical, V, coordinates.

```javascript
faceUV[1] = new BABYLON.Vector4(Ubottom_left, Vtop_right, Utop_right, Vbottom_left);
```

To reflect in both horizontal and vertical lanes swap the U coordinates and also swap the V coordinates.

```javascript
faceUV = new BABYLON.Vector4(Utop_right, Vtop_right, Ubottom_left, Vbottom_left);
```

You can use the images on the other faces in the following playground to check the change on orientation of the alien sprite in all the reflections.

<Playground id="#ICZEXW#4" title="Understanding Face Orientation Wtih Sprites" description="Simple Example of applying sprites to face mesh reflection." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials7.jpg"/>

Since a Vector4 has the properties x, y, z, w, (in that order) setting 

```javascript
faceUV[1] = new BABYLON.Vector4(Ubottom_left, Vbottom_left, Utop_right, Vtop_right);
```
means

```javascript
faceUV[1].x = Ubottom_left;
faceUV[1].y = Vbottom_left;
faceUV[1].z = Utop_right;
faceUV[1].w = Vtop_right;
```

which gives another way to swap coordinates. For example to reflect in a vertical line do
 
```javascript
  var temp = faceUV[1].x;
  faceUV[f].x = faceUV[f].z;
  faceUV[f].z = temp;
```

### How To Orientate a Sprite on a Face with the Texture Atlas From Version 4.0

Three new optional parameters were added to `CreateBox` in the V4.0 update, these are

* wrap - boolean (default = false), when true all vertical sides (0, 1, 2, 3) will apply image textures in the correct, upright, direction and the two horizontal sides (4, 5) will apply image textures so that when the box is when rotated around the x axis so that these sides are vertical the applied image textures will be applied in their original orientations;
* topBaseAt - integer, 0, 1, 2, 3,  (default = 1), the bottom (base) of the image for the top of the box is next the the side with the number given; 
* bottomBaseAt- integer, 0, 1, 2, 3,  (default = 0), the bottom (base) of the image for the bottom of the box is next the the side with the number given.

In the following playground the two boxes at the top do not use the wrap parameter and the result is backwards compatible with earlier versions of Babylon.js. The lower boxes are with wrap set to true.

<Playground id="#ICZEXW#4" title="Wrap Sprite Orientation" description="Simple Example of a wrap to orient a sprite on a mesh face." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials8.jpg"/>

The next playground shows the use of non-default values for topBaseAt and bottomBaseAt

<Playground id="#ICLXQ8#4" title="Wrap Top and Bottom Rotate" description="Simple Example of a wrap with top and bottom sprites rotated." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials9.jpg"/>
<Playground id="#ICLXQ8" title="Wrap Cartoon Head" description="Simple Example of a wrap to produce a box with a cartoon head." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials10.jpg"/>

### How To Orientate a Sprite on a Face with the Texture Atlas Before Version 4.0

Here consider just the orientation of the sides as viewed in the playground below. 

Take the following texture atlas 

![letters](/img/how_to/Materials/letters.jpg)

and apply it to a cube to give the playground below

<Playground id="#ICZEXW#8" title="Default Image Rotation" description="Simple Example of the default image rotation on faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials11.jpg"/>

Looking at the playground tells you two things

1. Which face is number 0, which is number 1 and so on by matching letter to number  
2. Going round the sides the orientations vary by 90 degrees.

As you saw in the previous section it is possible to doubly reflect A so it is the right way up. It is not possible to do this with C and D. To have A, B, C, and D all the same way up the texture atlas itself has to be changed.

A is rotated 180 degrees and C and D are rotated 90 degrees counter clockwise. Taking this into account change the texture atlas to

![rotated letters](/img/how_to/Materials/rotated_letters.jpg)

resulting in the following playground

<Playground id="#ICZEXW#9" title="Aligning Images on Faces" description="Simple Example of aligning images by altering the sprite sheet." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials12.jpg"/>

## Box - faceColors

For this no material is needed.

Define a 6 element array _faceColors_ (6 box faces) and just set the color of the faces we want with `Colors4`.  

```javascript
  var faceColors = new Array(6);

  faceColors[4] = new BABYLON.Color4(1,0,0,1);   // red top
  faceColors[1] = new BABYLON.Color4(0,1,0,1);   // green front
```

Then pass this array to the _MeshBuilder.CreateBox()_ method with the new _faceColors_ parameter of options. 
 
```javascript
  var options = {
    width: 10,
    height: 3,
    depth: 5,
    faceColors : faceColors
  };

  var box = BABYLON.MeshBuilder.CreateBox('box', options, scene);
```

<Playground id="#ICZEXW#5" title="Different Colors on 2 Faces" description="Simple Example of applying different colors to 2 faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials13.jpg"/>

These colors are BJS Color4-class values. The Color4 alpha values become active if you set `hasVertexAlpha = true` for the box. 

<Playground id="#ICZEXW#6" title="Different Transparent Colors on 2 Faces" description="Simple Example of applying different transparent colors to 2 faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials14.jpg"/>


## Box - Mix Face Textures and Colors

Finally you can also mix per-face colors with per-face textures, and/or mix either with the material's standard colors.  

<Playground id="#ICZEXW#10" title="Mixed Textures and Colors Per Face" description="Simple Example of applying different textures and colors per face." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials15.jpg"/>

## Cylinder

A cylinder has three surfaces, the top, the bottom and the tube joining them. For the face options face 0 is the bottom, face 1 is the tube and face 2 the top.

The following texture image is split into two parts, an approximation to a top and the label. The bottom will be colored just using faceColors and so the bottom face uv coordinates will be 0, 0, 0, 0.

![can label and top](/img/how_to/apply-material-to-faces/can-texture.jpg)

The label part has width 866 pixels and height 319 pixels.

So you need to tube surface to have the same height to width ratio.

When you create a cylinder with default diameter of 1 then the rectangle wrapping around the tube surface will have a width of &pi;.

Letting h be the height of the cylinder then to not distort the aspect ration of the image wrapped around the cyclinder keep the ratios h/&pi; and 319/866 the same.

So make h = &pi; * 319/866 = 1.16 to 2 decimal places.

Also note that because of how a cylinder's mesh is constructed the horizontal coordinates (U) are swapped in faceUV[1] for the wrapped around image to correct the reflection of the image.

<Playground id="#VA2AC#3" title="Different Texture on Cylinder and Its Top" description="Simple Example of applying different textures to a cylinder's side and top." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials16.jpg"/>

## Extruded Polygon

An extruded polygon has three surfaces top, bottom and extruded sides, face 0 is the top, face 1 the extruded sides and face 2 the bottom.

<Playground id="#RNCYVM#2" title="Extruded Polygon with Different Textures on Sides and Top" description="Simple Example of applying different textures to an extruded polygon's sides and top." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials17.jpg"/>

## Polyhedra

You can use a texture atlas with all the polyhedra however without very careful consideration of the nature of the texture atlas the results can be a little random looking.

<Playground id="#21QRSK#16" title="Polyhedra with Different Characters Per Face" description="Simple Example of applying different characters to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials18.jpg"/>

Having each sprite as a texture rather than a picture makes more sense.

<Playground id="#21QRSK#18" title="Polyhedra with Different Textures Per Face" description="Simple Example of applying different textures to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials19.jpg"/>

Just colors works well.

<Playground id="#21QRSK#17" title="Polyhedra with Different Colors Per Face" description="Simple Example of applying different colors to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials20.jpg"/>


If you want to display a video in your scene, the Babylon engine has a special texture for that. This special texture works similar to other textures, with the exception of a few parameters. These parameters include video urls (an url array), the size of the video texture (here is 256), the scene, and a final optional boolean that indicates if you want to use [mipmap](https://en.wikipedia.org/wiki/Mipmap) or not.

Here is an example from our Flat2009 Demo: <Playground id="#ZMCFYA#2" title="Video Texture Example" description="Simple example of using video as a texture in your scene." image="/img/playgroundsAndNMEs/divingDeeperVideoTexture1.jpg"/>

This plays a video on the demo's ZTV screen (ecran = screen).

```javascript
ecran.material.diffuseTexture = new BABYLON.VideoTexture("video", "textures/babylonjs.mp4", scene, true);
```

The [_VideoTexture_ object](/api/classes/babylon.videotexture) accepts an array of videos (to take into account various codecs). The first video in the array that can be loaded... is the one used as content source. Currently, HTML5 supports .mp4, .webm, and .ogv video formats.

The internal [video DOM object](https://www.w3.org/wiki/HTML/Elements/video) is accessible via the VideoTexture.video property... which allows you to control some characteristics and monitor the status of the video (things such as play, pause, loop, autoplay, etc). See the link above for the full story.

![video](/img/how_to/Advanced%20Texturing/3.png)

Even though we are working with advanced texturing techniques, _VideoTexture_ works in conjunction with a StandardMaterial. Simply put, it needs to have some light. As a handy alternative or video illumination assistant, you may want to set an _emissiveColor_ on the base material of the mesh.

```javascript
ecran.material.emissiveColor = new BABYLON.Color3(1,1,1);
```

Mobile devices do not auto-play videos. A user interaction (such as a tap) is required to start the video. Until the user taps, the video texture will be black. A simple way of starting the video is this:

```javascript
scene.onPointerDown = function () { 
  videoTexture.video.play();
}
```

This will start the video on the first tap in the scene. A demo can be found here: <Playground id="#CHQ4T#1" title="Tap To Play Video Texture" description="Simple example of tapping to start playing a video texture." image="/img/playgroundsAndNMEs/divingDeeperVideoTexture2.jpg"/>

In case you wish to display a texture during the load time, you can provide in the ```poster``` property of the settings the URL of an image displayed during loading or until the user interacts with the video.

An event is also available to detect if you are in browser preventing autoplay by policy:

```javascript
texture.onUserActionRequestedObservable.add(() => {
  scene.onPointerDown = function () { 
    videoTexture.video.play();
  }
});
```

Starting with v2.6, we introduced the support for WebRTC. So now you can create a specific VideoTexture which will be connected to your default WebCam:

```javascript
BABYLON.VideoTexture.CreateFromWebCam(scene, function(videoTexture) {
}, { maxWidth: 256, maxHeight: 256 });
```

The third parameter is optional and can be used to define minWidth, maxWidth, minHeight and maxHeight. These values will be used to constraint the camera resolution.


# Materials

Materials give your meshes color and texture.  One material in Babylon.js can be used to cover as many meshes as you wish. They can be displayed as a wireframe, scaled and offset across a mesh, have degrees of transparency and be blended. You can apply multiple materials on one mesh and use a dynamic texture as a material that you can draw and write on in real time. Do you need to make your material to appear more textured or bumpier and reflect and refract? The first section shows you how.

Node materials allow you create a material based on custom shaders but without having to deal with shader code.

The advanced section considers more technical aspects of materials and ways of customizing them.


Using Materials

How To Use Materials

Coming next

Introduction To Materials

Jump into the exciting world of learning to use Babylon.js materials.

More Materials

Learn about applying bump, opacity, tiling, and detail maps in Babylon.js.

Parallax Mapping

Learn all about using parallax mapping in Babylon.js.

Map Materials to Individual Mesh Faces

Learn how to apply different materials to different faces of a mesh.

Different Textures On The Front And Back Of A Mesh

Learn how to apply different textures to the front and back of a mesh.

Multi-Materials

Learn how to use Babylon.js Multi-Materials.

Dynamic Textures

Learn all about dynamic textures in Babylon.js.

Video As A Texture

Learn about how to use video as a texture in Babylon.js.

Introduction To Blend Modes

Learn blend modes and blending pixels in Babylon.js.

Introduction to Physically Based Rendering

Start learning about Physically Based Rendering in Babylon.js.

Using An HDR Environment For PBR

Learn about using an HDR Environment in your Babylon.js scene.

Mastering PBR Materials

Dive further into learning about PBR materials in Babylon.js.

Reflections and Refractions

Learn all about reflection and refraction in Babylon.js.

Fresnel Paramaters

Learn fresnel parameters in Babylon.js.

Procedural Textures

Learn fresnel parameters in Babylon.js.

KTX2 Compressed Textures

Learn advanced texture compression with KTX2 support in Babylon.js.