
## 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](https://doc.babylonjs.com/typedoc/classes/babylon.scene#createdefaultenvironment):

```javascript
scene.createDefaultEnvironment();
```

This will load the file [*environmentSpecular.env*](https://assets.babylonjs.com/environments/environmentSpecular.env) from *assets.babylonjs.com*.

To load a custom env texture, simply set the `scene.environmentTexture`:

```javascript
var hdrTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("textures/environment.env", scene);
scene.environmentTexture = hdrTexture;
```

You can also use an option in `createDefaultEnvironment()`:

```javascript
scene.createDefaultEnvironment({
    environmentTexture: "texture-url.env"
}););
```

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.

## Creating a compressed environment texture using the Sandbox

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 Babylon.js:

- 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);
```

See [What is a .env (Tech Deep Dive)](#what-is-a-env-tech-deep-dive) part at the bottom of this page to know more.

## IBL Texture tool

In case you have a .hdr texture, you're able to use the [IBL Texture Tool](https://www.babylonjs.com/tools/ibl/) to convert it in an easy way to .env.

Just drag &amp; drop your .hdr file, wait a bit, and save the .env wherever you want.


## 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](/features/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 found 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 byBabylon.js):

![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.


## Using a pure cube texture

![inspector env texture tool](/img/how_to/environment/inspector-generate-env-texture.png)

While using a .dds or .env 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).

## 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.


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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/divingDeeperFresnel1.jpg"/>
<Playground id="#AQZJ4C#0" title="Fresnel Parameters" description="Simple example for you to explore fresnel parameters in your scene." image="/img/playgroundsAndNMEs/features/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/features/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/features/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/features/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/features/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/features/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/toolsAndResources/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/features/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/features/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/features/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/features/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/features/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/features/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](/features/divingDeeper/materials/advanced/#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"/>

# Material

As of v5.0 Babylon includes a Material Plugin system, which allows customization of an existing material with custom shader code. This adds a lot of flexibility, since one can easily modify the behavior of existing materials with special effects without having to rewrite the entire shader code, in a simple and reusable way.

This is incredibly useful and powerful, since materials can be changed at runtime and have effects that were previously only possible with complex multi-pass renderings or postprocessing.

Let's start with an example: suppose you want an object to be rendered in black and white. All you want is to change the end of its shader, converting the final fragment color to grayscale. To do that you create a material plugin modifying that part of the shader code.

```javascript
/**
 * Extend from MaterialPluginBase to create your plugin.
 */
class BlackAndWhitePluginMaterial extends BABYLON.MaterialPluginBase {
 constructor(material) {
 // the second parameter is the name of this plugin.
 // the third one is a priority, which lets you define the order multiple plugins are run. Lower numbers run first.
 // the fourth one is a list of defines used in the shader code.
 super(material, "BlackAndWhite", 200, { BLACKANDWHITE: false });

 // let's enable it by default
 this._enable(true);
 }

 // Also, you should always associate a define with your plugin because the list of defines (and their values)
 // is what triggers a recompilation of the shader: a shader is recompiled only if a value of a define changes.
 prepareDefines(defines, scene, mesh) {
 defines["BLACKANDWHITE"] = true;
 }

 getClassName() {
 return "BlackAndWhitePluginMaterial";
 }

 getCustomCode(shaderType) {
 if (shaderType === "fragment") {
 // we're adding this specific code at the end of the main() function
 return {
 CUSTOM_FRAGMENT_MAIN_END: `
 float luma = gl_FragColor.r*0.299 + gl_FragColor.g*0.587 + gl_FragColor.b*0.114;
 gl_FragColor = vec4(luma, luma, luma, 1.0);
 `,
 };
 }
 // for other shader types we're not doing anything, return null
 return null;
 }
}
```

To actually use this plugin, you need to register it with a factory function. This factory can also associate the plugin instance to the material, so we can easily access it later.

```js
BABYLON.RegisterMaterialPlugin("BlackAndWhite", (material) => {
 material.blackandwhite = new BlackAndWhitePluginMaterial(material);
 return material.blackandwhite;
});
```

You can see the final code in action in the PlayGround: <Playground id="#GC63G5#16" title="Basic material plugin example" />

## More complex plugins

Sometimes your plugins will need to get uniforms. This is also possible with the plugins, which can register defines and uniforms.

Let's take a look at a more involved example, which is not enabled by default but has proper enable/disable controls as well.

```js
class ColorifyPluginMaterial extends BABYLON.MaterialPluginBase {
 // any local variable definitions of the plugin instance.
 color = new BABYLON.Color3(1.0, 0.0, 0.0);

 // we can add an enabled flag to be able to toggle the plugin on and off.
 get isEnabled() {
 return this._isEnabled;
 }

 set isEnabled(enabled) {
 if (this._isEnabled === enabled) {
 return;
 }
 this._isEnabled = enabled;
 // when it's changed, we need to mark the material as dirty so the shader is rebuilt.
 this.markAllDefinesAsDirty();
 this._enable(this._isEnabled);
 }

 _isEnabled = false;

 constructor(material) {
 // the fourth parameter is a list of #defines in the GLSL code
 super(material, "Colorify", 200, { COLORIFY: false });

 this._varColorName = material instanceof BABYLON.PBRBaseMaterial ? "finalColor" : "color";
 }

 // we use the define to enable or disable the plugin.
 prepareDefines(defines, scene, mesh) {
 defines.COLORIFY = this._isEnabled;
 }

 // here we can define any uniforms to be passed to the shader code.
 getUniforms() {
 return {
 // first, define the UBO with the correct type and size.
 ubo: [{ name: "myColor", size: 3, type: "vec3" }],
 // now, on the fragment shader, add the uniform itself.
 fragment: `#ifdef COLORIFY
 uniform vec3 myColor;
 #endif`,
 };
 }

 // whenever a material is bound to a mesh, we need to update the uniforms.
 // so bind our uniform variable to the actual color we have in the instance.
 bindForSubMesh(uniformBuffer, scene, engine, subMesh) {
 if (this._isEnabled) {
 uniformBuffer.updateColor3("myColor", this.color);
 }
 }

 getClassName() {
 return "ColorifyPluginMaterial";
 }

 getCustomCode(shaderType) {
 return shaderType === "vertex"
 ? null
 : {
 // this is just like before. Multiply the final shader color by
 // our color. Note that we have access to all shader variables:
 // we're effectively inserting a piece of code in the shader code.
 CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR: `
 #ifdef COLORIFY
 ${this._varColorName}.rgb *= myColor;
 #endif
 `,

 // we can even use regexes to replace arbitrary parts of the code.
 // if your key starts with '!' it's parsed as a Regex.
 "!diffuseBase\\+=info\\.diffuse\\*shadow;": `
 diffuseBase += info.diffuse*shadow;
 diffuseBase += vec3(0., 0.2, 0.8);
 `,
 };
 }
}
```

<Playground id="#P8B91Z#35" title="Material plugin example with uniforms"/>

## Applying a plugin to a single material

Even though your plugins can be enabled/disabled as shown above, sometimes you need to apply a plugin to a single material. In this case, instead of calling `RegisterMaterialPlugin`, you can instantiate the plugin directly with the material that will be modified:

```js
const myPlugin = new BlackAndWhitePluginMaterial(material);
```

This is also useful for dynamic loading of plugins.

<Playground id="#22HT5Z#15" title="Material plugin applied to a single material"/>

## Caveats

- The code insertion point names are standard over all materials, but not all of them have all insertion points. In general you can expect to have
 `CUSTOM_VERTEX_DEFINITIONS`, `CUSTOM_VERTEX_MAIN_BEGIN` and `CUSTOM_VERTEX_MAIN_END` in vertex shaders, and `CUSTOM_FRAGMENT_DEFINITIONS`, `CUSTOM_FRAGMENT_MAIN_BEGIN` and `CUSTOM_FRAGMENT_MAIN_END` in fragment shaders. But other `#defines` might not be present.
- There's no guarantee that using the shader point names / the regular expressions to update code / the variable names with a material plugin will work across Babylon.js versions. We reserve the possibility to update our shader code in a way that would break backward compatibility with those features if we have to. In particular, the color variable name for `standard.fragment.fx` is `color`, while for `pbrMaterial.fragment.fx` it's `finalColor`. If you are writing a plugin targeting multiple materials take care in your code to use different variable names according to the plugin and keep track of Babylon potentially changing (and breaking!) things.
- `RegisterMaterialPlugin` only adds the plugin to material instantiated AFTER the registration. So it must be run before you add any meshes or create your materials or they won't have the plugin.
- You can register multiple plugins to the same material (or the entire scene). The `priority` field controls the order the plugins will be executed if they are all enabled.

## Material Plugin Examples

Here are some other examples of plugins:

<Playground id="#HCLC5W#41" title="Using a class variable to animate a parameter for all instances"/>
<Playground id="#SYQW69#1077" title="Power plant with volumetric fog"/>
<Playground id="#IQPBS4#62" title="Grain (solves banding issues)"/>

You can also take a look at Babylon's source code. The PBR material includes several complex plugins, such as the [Anisotropic plugin](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrAnisotropicConfiguration.ts), [sheen](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrSheenConfiguration.ts) and [subsurface](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrSubSurfaceConfiguration.ts), and the [detail map plugin applies to PBR and Standard materials](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/material.detailMapConfiguration.ts).


The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.

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](/features/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/features/divingDeeperMaterialsIntro1.jpg" isMain={true} category="Materials"/>

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/features/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/features/divingDeeperMaterialsIntro3.jpg" isMain={true} category="Materials"/>

## 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/features/divingDeeperMaterialsIntro4.jpg" isMain={true} category="Materials"/>

## 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/features/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/features/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](/features/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. InBabylon.js 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/features/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/features/divingDeeperMoreMaterials1.jpg" isMain={true} category="Materials"/>

## 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/features/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/features/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/features/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); 
 
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/features/divingDeeperMultiMaterial1.jpg"/>

## With Merged Meshes

When you [merge meshes](/features/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/features/divingDeeperMultiMaterial2.jpg"/>

When you [merge meshes](/features/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/features/divingDeeperMultiMaterial2.jpg"/>

The goal of this article is to clearly explain what is happening with normal textures with some samples to hopefully clear up any confusion about what is happening.

To do so we are going to use this playground as an example: <Playground id="#YCCU8U" title="Normal Texture Example" description="Simple example of using a normal texture in your scene." image="/img/playgroundsAndNMEs/features/divingDeeperNormalMaps1.jpg"/>

What the normal map formats are and what they look like?

* OpenGL expects the first pixel in the texture to be at the bottom (lower-left pixel) and can be thought of as bottom up
* DirectX expects the first pixel in the texture to be at the top (upper-left pixel) and can be thought of as top down

To see what that looks like, we can consider this normal map comparison:

![Different normal maps convention](/img/how_to/Materials/normal_maps1.jpg)

To help identify what normal format you have by looking at the texture, you need to understand if details on the texture are embossed (stands proud of the surface) or debossed (does not stand proud of the surface). As an example, the left shapes in each texture above are embossed and the right shapes in each are debossed. Next look at the tones in the map and assume that the lighter tones in the normal texture (the light greens) are being cast from a light either directly above or below the texture. If you know your details are embossed and the lightest tones are at the top suggesting the light is positioned above your texture, you have an OpenGL format texture. If the lightest tones on an embossed detail are on the bottom, suggesting the light is below the texture, you have a DirectX format texture.

Truly, the only difference between the two formats at the file level is that the Y coordinate is inverted, positive being up in OpenGL and down in DirectX. If you assume the R, G, and B channels map to the coordinate system X, Y, and Z, you can see that we only need to change the G channel of the texture to convert between the formats. And the only operation you need to do is an invert of the tones in the G channel if you want to convert in an image editing package. Or you could convert directly in the shader by including a one minus pixel color for the G channel of the texture. And in our Node Material Editor, we have parameters on the perturb normal node that allow you to invert Y in the normal texture to effectively convert between the two formats.

Now let’s look at the requirements used by software:

* [Arnold Renderer uses OpenGL format](https://academy.substance3d.com/courses/Substance-guide-to-Rendering-in-Arnold)
* [Maya can use either format but needs to be specified in the Display preferences](https://knowledge.autodesk.com/support/maya/learn-explore/caas/CloudHelp/cloudhelp/2018/ENU/Maya-Customizing/files/GUID-BF017019-B89A-47F0-8AB5-106C058AB854-htm.html). I believe that the default is OpenGL - Core Profile (Compatibility) due to Arnold now being their bundled renderer.

![Maya export window](/img/how_to/Materials/normal_maps2.png)

When you are creating your textures, you can specify the format for the normal map before baking, but you need to align with your final use case. With that in mind, whether you are targeting an offline rendering engine like Arnold or a real-time rendering engine like Babylon.js, you need to know which format is expected by the renderer’s shaders and how your file formats may impact that choice. So let’s look at those:

* [glTF uses OpenGL as the format for its normal textures](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#materialnormaltexture).
* Babylon.js uses DirectX as the format for its normal textures for Standard Materials, PBR materials, and Node Materials

This would seem to be a simple conversion from OpenGL to DirectX formats when using a glTF, but there is another issue that complicates this matter.

* glTF uses a right-handed coordinate system
* Babylon.js uses a left-handed coordinate system

This is important for this reason:

![Visual difference between conventions](/img/how_to/Materials/normal_maps3.jpg)

This is a glTF file with two planes in it exported from Maya. They were both assigned an Arnold standard surface shader with an OpenGL format normal map. When the file is loaded the plane on the right has its material replaced

When you load that glTF into Babylon.js, we take care of converting the file to match the handedness of the scene for you. However, what you see here is that the plane on the right has been assigned a Node Material with a DirectX format normal texture. It may be a little confusing why the normal looks incorrect when we just said that Babylon materials expect a DirectX format normal but this has to do with how the glTF was loaded. Babylon.js materials still expect a DirectX format normal, but when we loaded the glTF, we inverted the tangent space in Y so that it conforms with the OpenGL convention of glTF. That means that any normal texture that is applied to the mesh, no matter if it is a material from the original file or one that is created in Babylon.js needs to be authored in the OpenGL format to render correctly.

Now it may be easy to assume that if I just save my files in the .babylon format that all would be fixed and I could just save all my normal maps and DirectX format. You would be correct only if you do not change any textures in the materials assigned to your meshes and just used the assets from the .babylon file directly. If you assign a new texture to a material on a mesh from a .babylon file or you assign an entirely new material such as a node material you will get an unexpected result. The image below shows a .babylon file imported with the same OpenGL format normal from above on the left and on the right a node material that assigns a DirectX format normal to the plane.

![Normal direction based on conventions](/img/how_to/Materials/normal_maps4.jpg)

So what happened? The plane on the left looks incorrect as it should, but the one on the right looks completely wrong. This stems from the origin of Babylon.js as it was a spiritual successor to an older engine that Deltakosh wrote which was a DirectX engine. Much the same as mentioned before, DirectX formatted normal textures are read from the upper left pixel rather than the lower left pixel in OpenGL, UV space in DirectX is also read from the upper left instead of the lower left.

To illustrate this, here is a simple graph to show how the UVs are stored in a glTF file versus .babylon file:

![UV directions](/img/how_to/Materials/normal_maps5.png)

When we export a .babylon file, we don’t change anything about the texture files as that could cause some extra problems when updating or editing the textures, but we know on load that the UV space is DirectX with the textures likely being in OpenGL format. So when we read in the textures we store them in memory inverted in Y. You can see this if you inspect a texture in your scene loaded from a .babylon file. You will notice an indication as to whether it is "Stored as Inverted on Y" in the list of general properties.

![Inspector](/img/how_to/Materials/normal_maps6.jpg)

So how do we fix this. There are three ways we can work around this issue when adding new textures to a loaded .babylon file, one art fix and two code fixes. The art fix would be to author your normal textures in DirectX format and save your textures inverted in Y. You could do this on export from your texturing tool like Substance or you could manually invert them in Y in an image editor. This could be very disruptive to your art pipeline, so it may not be the right solve.

The code fixes are simpler. One is to invert your texture when you load it by using the [invertY parameter available in BABYLON.Texture](/typedoc/classes/babylon.texture#constructor) which is the easiest solve. However, if you are loading textures through Node Material rather than in your javascript, that won’t work. This leads us to the other code solve which is to add a one minus Y operation to the UVs fed to your texture as you can see below.

![Node material](/img/how_to/Materials/normal_maps7.png)

This will correct your texture inversion issue and as you can see this will fix the rendering. Again, the planes are loaded from a .babylon file and the left one was assigned an OpenGL format normal texture in Maya and the right uses a DirectX format normal assigned with a Node Material that has the UV space inverted in Y.

![Final result](/img/how_to/Materials/normal_maps9.jpg)

It is a deep topic which is made more complex by multiple file formats with their own conventions, but there are tools available in engine to switch to whatever you need. In a way we can say that while Babylon.js was originally designed based on DirectX principles, it has since become more convention agnostic as there are plenty of tools available to make your assets work correctly so long as you know where you are coming from and where you are going.

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/features/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:

```javascript
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#49" title="Experiment With Noise Properties" description="Simple example for you to experiment with noise properties." image="/img/playgroundsAndNMEs/features/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/packages/dev/proceduralTextures

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/toolsAndResources/woodproceduraltexture
- **MarbleProceduralTexture**: //doc.babylonjs.com/toolsAndResources/marbleproceduraltexture
- **BrickProceduralTexture**: //doc.babylonjs.com/toolsAndResources/brickproceduraltexture
- **FireProceduralTexture**: //doc.babylonjs.com/toolsAndResources/fireproceduraltexture
- **GrassProceduralTexture**: //doc.babylonjs.com/toolsAndResources/grassproceduraltexture
- **RoadProceduralTexture**: //doc.babylonjs.com/toolsAndResources/roadproceduraltexture
- **CloudProceduralTexture**: //doc.babylonjs.com/toolsAndResources/cloudproceduraltexture


# Procedural Texture Library

A library of procedural textures, coded textures to run and enhance your scene.

## About environment mapping
Babylon.js uses _environment mapping_ ([wikipedia](https://en.wikipedia.org/wiki/Reflection_mapping)) to simulate reflection (mirror-like materials) and refraction (glass-like materials).

Environment maps are pictures of the world (as seen from some vantage point) which are transformed and applied to meshes to simulate reflection or refraction. These pictures may be single images or composite panoramas, and may be static snapshots or dynamically updated to track scene changes.

Once created (as described below), environment maps may be used in [StandardMaterial](/typedoc/classes/babylon.standardmaterial)'s [.reflectionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture) or [.refractionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture); environment maps are also used in [Physically Based Rendering](/features/divingDeeper/materials/using/introToPBR) for sophisticated material surfaces.

## Static environment maps (CubeTexture and friends)
[CubeTexture](/typedoc/classes/babylon.cubetexture) instances use six images to make a static wraparound environment map (or "cubemap"). [The CubeMap constructor](/typedoc/classes/babylon.cubetexture#constructor) takes a base URL and appends "\_px.jpg", "\_nx.jpg", "\_py.jpg", "\_ny.jpg", "\_pz.jpg" and "\_nz.jpg" to load images for the +x, -x, +y, -y, +z, and -z facing sides of a cube.

![Diagram of X/Y/Z axes and CubeTexture sides](/img/how_to/Materials/cubetexture1.png)

([Use the _extensions_ argument](/typedoc/classes/babylon.cubetexture#constructor) to customize these suffixes, e.g. to load .png instead of .jpg images.)

Despite the "Texture" name, CubeTexture can _only_ be used with the [.reflectionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture) or [.refractionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture) properties of [StandardMaterial](/typedoc/classes/babylon.standardmaterial), _not_ other properties like [.diffuseTexture](/typedoc/classes/babylon.standardmaterial#diffusetexture).

### Skybox cubemaps
[Skybox images](/features/divingDeeper/environment/skybox) may be used directly as environment maps. (Conveniently, skyboxes also typically use CubeTexture.) In this case only the skybox will show up in the reflection/refraction; other scene members will not be reflected, but that may be acceptable for simple scenes or small surfaces.

This classic cloudy skybox helps demonstrate skybox reflection:

|+x (right)|-x (left)|-y (up)|-y (down)|+z (back)|-z (front)|
|:---:|:---:|:---:|:---:|:---:|:---:|
|<img src="/img/getstarted/skybox_px.jpg" width="100" height="100" alt="Some clouds"/>|<img src="/img/getstarted/skybox_nx.jpg" width="100" height="100" alt="More clouds"/>|<img src="/img/getstarted/skybox_py.jpg" width="100" height="100" alt="The sun overhead"/>|<img src="/img/getstarted/skybox_ny.jpg" width="100" height="100" alt="Solid gray"/>|<img src="/img/getstarted/skybox_pz.jpg" width="100" height="100" alt="More clouds"/>|<img src="/img/getstarted/skybox_nz.jpg" width="100" height="100" alt="More clouds"/>|
 

<Playground id="#UU7RQ#3" title="Cube Reflecting Skybox" description="A cube reflecting skybox images." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction2.jpg"/>
<Playground id="#UU7RQ#5" title="Ground Reflecting Skybox" description="A ground plane reflecting skybox images." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction3.jpg"/>
<Playground id="#UU7RQ#4" title="Sphere Reflecting Skybox" description="A sphere reflecting skybox images." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction4.jpg"/>

With two shapes in the scene, it becomes clear that only the skybox is reflected:

<Playground id="#UU7RQ#1590" title="Vampire Cube Isn't Reflected" description="A cube reflecting skybox images but not reflecting a nearby red cube."/>

This "vampire effect" can be fixed by carefully adding scene contents to cubemap images, or by using [dynamic maps](#dynamic-environment-maps-rendertargettexture-and-friends).

### Local cubemaps
Environment maps (static or dynamic) are flat images with no depth. By default, they are treated as infinitely far away. This works for distant environments (like skyboxes) or small surfaces, but can cause parallax errors in other cases.

As an alterative, cubemaps can be treated as axis-aligned boxes of specific size and location by setting the cubemap texture's [.boundingBoxSize](/typedoc/classes/babylon.cubetexture#boundingboxsize) and [.boundingBoxPosition](/typedoc/classes/babylon.cubetexture#boundingboxposition) to the desired box size and position (as [Vector3](/typedoc/classes/babylon.vector3)).

<Playground id="#RNASML#37" title="Local cubemap demo" description="Demonstraction of the effect of local cubemap projection." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction5.jpg"/>

(Local cubemaps must use the default CUBIC\_MODE [coordinate mode](#coordinate-modes).)

An axis-aligned box is still an approximation of true reflected/refracted scene geometry, but it may be a useful approximation. See "[Reflections Based on Local Cubemaps](https://community.arm.com/graphics/b/blog/posts/reflections-based-on-local-cubemaps-in-unity)" (from the ARM Developer's Graphics and Gaming Blog) for a good write-up of the concept as used in Unity (Babylon.js's implementation is similar).

### EquiRectangularCubeTexture
Equirectangular panoramic images ([panotools wiki](https://wiki.panotools.org/Equirectangular_Projection)) squish a spherical panorama into one image (unlike the six sides needed for ordinary CubeTexture) using equirectangular projection ([wikipedia](https://en.wikipedia.org/wiki/Equirectangular_projection)).

<img caption="An equirectangular panorama image, flattened out" alt="A warped view of a dock with boats" src="https://playground.babylonjs.com/textures/equirectangular.jpg" width="1024" height="512"/>

[EquiRectangularCubeTexture](/typedoc/classes/babylon.equirectangularcubetexture) instances load an equirectangular panorama image into a CubeTexture-compatible environment map.

<Playground id="#RY8LDL#32" title="Spheres Reflecting Equirectangular Skybox" description="Reflections and refractions of an equirectangular skybox panorama." image="/img/playgroundsAndNMEs/divingDeeperReflectionRefraction9.jpg"/>

### HDRCubeTexture
High Dynamic Range ([wikipedia](https://en.wikipedia.org/wiki/High-dynamic-range_imaging)) images capture brighter and dimmer colors than a typical monitor can display. This can be useful for environment mapping even if the final output uses standard dynamic range.

<img caption="A panoramic HDR image, flattened and reduced to SDR" alt="A warped view of a room with lamps" src="/img/how_to/Materials/room.jpg" width="2048" height="1024"/>

[HDRCubeTexture](/typedoc/classes/babylon.hdrcubetexture) instances (Babylon.js v3.2+) loads a Radiance RGBE format ([wikipedia](https://en.wikipedia.org/wiki/RGBE_image_format)) HDR equirectangular panorama image into a CubeTexture-compatible environment map.

<Playground id="#114YPX#5" title="HDR Skybox" description="An HDR equirectangular skybox panorama." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction6.jpg"/>

### Flat textures as environment maps

Wraparound cubemaps work well for environment mapping, but ordinary flat Texture instances can be used for [.reflectionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture) and [.refractionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture) as well. The texture's .coordinatesMode must be set to define how the flat image should be "wrapped around" as an environment ([see "Coordinate Modes"](#coordinate-modes)).

<img src="/img/how_to/Materials/mona_lisa_head.jpg" width="200" height="200" caption="Example flat texture (Mona Lisa)" alt="Mona Lisa's head"/>

<Playground id="#UU7RQ#1629" title="Mona Lisa in SPAAAACE, reflected using PLANAR_MODE" description="A sphere reflecting a flat Mona Lisa texture." image="/img/playgroundsAndNMEs/pg-UU7RQ-1627.png"/>

(Note, cubemaps are normally preferred for environment mapping instead of flat textures.)

## Dynamic environment maps (RenderTargetTexture and friends)
[RenderTargetTexture](/typedoc/classes/babylon.rendertargettexture) instances hold environment maps updated during scene rendering, allowing reflections and refractions to track the scene in real time (unlike the [static maps](#static-environment-maps-cubetexture-and-friends) described above).

RenderTargetTexture instances are usually created through classes like ReflectionProbe or MirrorTexture, which manage the dynamic update process.

### ReflectionProbe
Each [ReflectionProbe](/typedoc/classes/babylon.reflectionprobe) instance provides a cubemap (in [.cubeTexture](/typedoc/classes/babylon.reflectionprobe#cubetexture)) that is dynamically rendered from a specified point in the scene, typically at or near an object that will use the cubemap.

<Playground id="#KA93U#243" title="Reflection Probes" description="Moving shapes reflecting each other and the ground using reflection probes." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionProbes1.jpg"/>

You must set each ReflectionProbe's [.renderList](/typedoc/classes/babylon.reflectionprobe#renderlist) to an explicit list of meshes to render. Be mindful of efficiency as each probe renders six times (once for each cube face) for every update. See the [Reflection Probes main page](/features/divingDeeper/environment/reflectionProbes) for more details.

### MirrorTexture
[MirrorTexture](/typedoc/classes/babylon.mirrortexture) (a RenderTargetTexture subclass) acts as a dynamically rendered environment map for flat mirrors.

<Playground id="#1YAIO7#5" title="Mirrors" description="Several mirrors surrounding a sphere." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction11.jpg"/>

As with reflection probes, you must set each MirrorTexture's [.renderList](/typedoc/classes/babylon.mirrortexture#renderlist) to an explicit list of meshes to show in the mirror, keeping efficiency in mind. You must also set each MirrorTexture's [.mirrorPlane](/typedoc/classes/babylon.mirrortexture#mirrorplane) to the [Plane](/typedoc/classes/babylon.plane) of reflection, with the plane's normal pointing _into_ the mirror (away from the viewer).

You may set Plane coordinates directly, but it can be convenient to build the Plane from mesh geometry:

```javascript
// Create, position, and rotate a flat mesh surface.
const mesh = BABYLON.MeshBuilder.CreatePlane("mirrorMesh", {width: 5, height: 5}, scene);
mesh.position = new BABYLON.Vector3(0, 0, 4);
mesh.rotation = new BABYLON.Vector3(Math.PI/4, Math.PI/6, Math.PI/8);

// Create the reflective material for the mesh.
mesh.material = new BABYLON.StandardMaterial("mirrorMaterial", scene);
mesh.material.reflectionTexture = new BABYLON.MirrorTexture("mirrorTexture", 512, scene, true);

// Get a normal vector from the mesh and invert it to create the mirror plane.
mesh.material.reflectionTexture.mirrorPlane = BABYLON.Plane.FromPositionAndNormal(
 mesh.position, mesh.getFacetNormal(0).scale(-1));
mesh.material.reflectionTexture.renderList = [... list of meshes ...];
```

To create a blurred reflection, set MirrorTexture's [.blurKernel](/typedoc/classes/babylon.mirrortexture#blurkernel) to the blur kernel size (higher is blurrier) relative to the render texture size (set when MirrorTexture is created). Use [.adaptiveBlurKernel](/typedoc/classes/babylon.mirrortexture#blurkernel) instead to scale the blur value by the ratio of the render texture size and viewport size.

<Playground id="#LVTTQX#1" title="Reflection Blur" description="A shape reflected in a surface with blurring." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction12.jpg"/>

### RefractionTexture
[RefractionTexture](/typedoc/classes/babylon.refractiontexture) (also a RenderTargetTexture subclass) is similar to MirrorTexture, but designed for refraction instead of reflection.

RefractionTexture acts as a dynamically rendered single-image environment map for flat _refractors_ (materials like glass or water that bend light). You can use RefractionTexture instances directly in [.refractionTexture](/typedoc/classes/babylon.standardmaterial#reflectiontexture). (Note, RefractionTexture simulates fixed-thickness plates of refractive material, and does not support lenses or shapes "bent" by immersion.)

<Playground id="#22KZUW#15" title="Refraction" description="A refractive disc in a simple scene." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction13.jpg"/>

As with MirrorTexture, you must set each RefractionTexture's [.renderList](/typedoc/classes/babylon.refractiontexture#renderlist) to an explicit list of meshes to show in the refraction, keeping efficiency in mind.

You must also set each RefractionTexture's [.refractionPlane](/typedoc/classes/babylon.refractiontexture#refractionplane) to the [Plane](/typedoc/classes/babylon.plane) of refraction, with the plane's normal pointing _out of_ the refractor (_toward_ the viewer). You may set Plane coordinates directly, but it can be convenient to build the Plane from mesh geometry as described above for MirrorTexture (but without the `.scale(-1)` call).

Finally, you must set each RefractionTexture's [.indexOfRefraction](/typedoc/classes/babylon.refractiontexture#indexofrefraction) and [.depth](/typedoc/classes/babylon.refractiontexture#depth) to the index of refraction ([wikipedia](https://en.wikipedia.org/wiki/Refractive_index)) and thickness of the refractive plate to simulate.


<Playground id="#1YAIO7#19" title="Changing Index Of Refraction" description="A plate with varying index of refraction." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction15.jpg"/>
<Playground id="#1YAIO7#20" title="Changing Refraction Depth" description="A plate with varying refraction depth." image="/img/playgroundsAndNMEs/features/divingDeeperReflectionRefraction14.jpg"/>


## Coordinate modes

By default, cubemap textures (static and dynamic) simulate the physical Laws of Reflection ([wikipedia](https://en.wikipedia.org/wiki/Reflection_(physics)#Laws\_of\_reflection)), to create realistic shiny surfaces. However, you may set a texture's [.coordinatesMode](/typedoc/classes/babylon.texture#coordinatesmode) to select different reflection behavior, and [flat (non-cubemap) textures](#flat-textures-as-environment-maps) always require you to set .coordinatesMode. (Refraction does not use coordinate modes.)

See the source ([reflectionFunction.fx](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/ShadersInclude/reflectionFunction.fx), called by [default.fragment.fx](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/default.fragment.fx)) for the mathematical definition of each mode.

| coordinatesMode | Description |
| --- | --- |
| CUBIC\_MODE | The default mode for cubemaps. Works best with cubemaps, but will project flat textures onto the X/Y axes of an environment sphere as 4 upside-down copies. |
| INVCUBIC\_MODE | Like CUBIC\_MODE, but inverts texture Y, so flat texture images are right side up. |
| PLANAR\_MODE | Like CUBIC\_MODE, but handles flat texture scaling and translation slightly better. (Despite the name, PLANAR\_MODE is not otherwise plane-oriented.) |
| SKYBOX\_MODE | Rather than reflecting, applies texture images directly to the object surface. Mostly used to make [skyboxes](/features/divingDeeper/environment/skybox). Works best for cubemaps, but will project flat textures onto the X/Y axes of the object. |
| EQUI&shy;RECTANGULAR\_MODE | Wraps flat textures into an environment map with equirectangular projection ([wikipedia](https://en.wikipedia.org/wiki/Equirectangular_projection)). Not recommended for cubemaps. |
| FIXED\_EQUIRECTANGULAR\_MODE | Like SKYBOX\_MODE, but wraps flat textures around the object with equirectangular projection. Does not support [reflection matrix](#the-reflection-matrix) transforms. Not recommended for cubemaps. |
| FIXED\_EQUIRECTANGULAR\_MIRRORED\_MODE | Like FIXED\_EQUIRECTANGULAR\_MODE, but inverts texture X so images look "correct" on the outside of an object. |
| PROJECTION\_MODE | Scales flat textures to the _screen size_ and shows them wherever the material is visible, as if projecting from the camera onto the scene. Mostly used for special effects. Not recommended for cubemaps. |
| SPHERICAL\_MODE | Performs reflection in _screen coordinates_ rather than world coordinates. Not useful in most cases. |
| EXPLICIT\_MODE | Uses only one point of the texture. Not useful in most cases. |

### Examples with a test pattern cubemap

|+x (right)|-x (left)|-y (up)|-y (down)|+z (back)|-z (front)|
|:---:|:---:|:---:|:---:|:---:|:---:|
|<img src="/img/how_to/Materials/testcube_px.png" width="100" height="100" alt="RGT test pattern"/>|<img src="/img/how_to/Materials/testcube_nx.png" width="100" height="100" alt="LFT test pattern"/>|<img src="/img/how_to/Materials/testcube_py.png" width="100" height="100" alt="TOP test pattern"/>|<img src="/img/how_to/Materials/testcube_ny.png" width="100" height="100" alt="BOT test pattern"/>|<img src="/img/how_to/Materials/testcube_pz.png" width="100" height="100" alt="BCK test pattern"/>|<img src="/img/how_to/Materials/testcube_nz.png" width="100" height="100" alt="FRT test pattern"/>|
 

<Playground id="#20OAV9#4308" title="PLANAR, (INV)CUBIC, SKYBOX, and PROJECTION Modes with Test Cubemap" description="Demonstration of cubemap reflection coordinate modes"/>

### Examples with a test pattern flat texture

<img src="/img/how_to/Materials/letter_grid.png" width="200" height="200" alt="Letters A-Y in a grid"/> 

<Playground id="#20OAV9#4307" title="PLANAR, EQUIRECTANGULAR, PROJECTION, and SPHERICAL Modes with Flat Test Pattern" description="Demonstration of flat texture reflection coordinate modes"/>

### The reflection matrix

In addition to selecting the overall coordinate mode, a texture's reflection matrix ([.getReflectionTextureMatrix()](/typedoc/classes/babylon.texture#getreflectiontexturematrix)) may be adjusted to transform the environment map, to match scene changes (e.g. a moving background) or for special effects.

<Playground id="#UU7RQ#1631" title="Sphere Reflecting Rotating Skybox" description="A sphere reflecting spinning skybox images"/>

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/features/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.

![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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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/features/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#83" title="Video Texture Example" description="Simple example of using video as a texture in your scene." image="/img/playgroundsAndNMEs/features/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](/typedoc/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. e.g. play, pause, loop, autoplay. 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);
```

## Auto Play

Modern browsers have strict policies for autoplaying video. Without user interaction, most browsers will autoplay only if the audio is muted. When VideoTexture setting `autoPlay` is true (the default), Babylon.js will automatically mute the audio if the first attempt to autoplay fails. To play video with audio, a user interaction (such as a tap) is often required. To manually start a video texture playback, code like this can be used:

```javascript
scene.onPointerDown = function () {
 videoTexture.video.play();
 scene.onPointerDown = null;
};
```

This will start the video on the first tap in the scene. A demo can be found here: <Playground id="#1BYH8W#4" title="Tap To Play Video Texture" description="Simple example of tapping to start playing a video texture." image="/img/playgroundsAndNMEs/divingDeeperVideoTexture2.jpg"/>

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();
 };
});
```

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.

## Web RTC

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.


## Disposal

VideoTexture creates and uses an HTML video element internally. When VideoTexture.dispose is called, texture resources are disposed as expected. However, the underlying video element is not removed. Causing complete release of all underlying video resources is not standardized across browsers, but code like this can be used:

```javascript
// Store reference to the underlying HTML5 video element
const videoEl = videoDome.videoTexture.video 

// Dispose texture
videoTexture.dispose();

// Remove any <source> elements, etc.
while (videoEl.firstChild) {
 videoEl.removeChild(videoEl.lastChild);
}

// Set a blank src
videoEl.src = ''

// Prevent non-important errors in some browsers
videoEl.removeAttribute('src')

// Get certain browsers to let go
videoEl.load()

videoEl.remove()
```

This is only important to users that need to load/dispose multiple VideoTextures over time.


## How To Use Materials

There is much you can achieve by applying the Babylon.js standard material to a mesh and a variety of types of texture. Beyond that there is also physically based rendering material to give a more realistic appearance to a material.



# 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

In This Category

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.

Normal Maps

Learn all about normal maps in Babylon.js.

----------

Documentation page for ----------

Introduction To Blend Modes

Learn blend modes and blending pixels 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.

Reflections and Refractions

Learn all about reflection and refraction in Babylon.js.

Fresnel Paramaters

Learn fresnel parameters in Babylon.js.

KTX2 Compressed Textures

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

----------

Documentation page for ----------

Materials Library

The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.

----------

Documentation page for ----------

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.

----------

Documentation page for ----------

Procedural Textures

Learn fresnel parameters in Babylon.js.

Procedural Texture Library

Learn about the free available Procedural Textures in the Babylon.js Procedural Texture library.

----------

Documentation page for ----------

Material Plugins

Create plugins to customize shaders of existing materials