
## Introduction

The highly recommended way to set up an environment texture is through an HDR-ready file (either DDS or ENV) containing a cube texture with prefiltered MipMaps.

To load an HDR environment, you can use [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
const hdrTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("textures/environment.env", scene);
scene.environmentTexture = hdrTexture;
```

You can also pass an option to `createDefaultEnvironment()`:

```javascript
scene.createDefaultEnvironment({
    environmentTexture: "texture-url.env"
}););
```

We detail below the two supported ways of creating such files.

As of 4.2, Babylon.js supports prefiltering directly in the Sandbox!

`.hdr` files are easy to find on the web, so they are often 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 a special way to pack your texture in Babylon.js. 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.webp)

You can now download and use your `.env` environment, using this bit of code:

```
scene.environmentTexture = new BABYLON.CubeTexture("environment.env", scene);
```

Note that you can rotate your environmentTexture if needed:

```javascript
const hdrRotation = 10; // in degrees
scene.environmentTexture.setReflectionTextureMatrix(BABYLON.Matrix.RotationY(BABYLON.Tools.ToRadians(hdrRotation)));
```

As of 7.48.0, you can even check the diffuse box to ensure your env texture contains the diffuse information in a texture. This can help a lot with rendering quality at the expense of a slightly bigger file (about 10 more kb).

See the [What is a .env (Tech Deep Dive)](#what-is-a-env-tech-deep-dive) section at the bottom of this page for more details.

## IBL Texture tool

If you have a `.hdr` texture, you can use the [IBL Texture Tool](https://www.babylonjs.com/tools/textures/) to convert it easily to `.env`.

Just drag &amp; drop your .hdr file, wait a bit, and save the .env wherever you want.

## Directly use .hdr files

If you want to directly use a `.hdr` or `.exr` file and are not able to prefilter it to a `.env` or `.dds` file from the Sandbox or an external tool, you can do it when your texture is loaded.

```javascript
const hdrReflectionTexture = new BABYLON.HDRCubeTexture("./textures/environment.hdr", scene, 128, false, true, false, true);

const exrReflectionTexture = new BABYLON.EXRCubeTexture("./textures/environment.exr", scene, 128, false, true, false, true);
```

This method adds a small delay when loading the texture, because the prefiltering is done 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 you might sometimes want to filter in real time (for animated reflections, for instance), you may also want to look at [the reflection probes tutorial](/features/featuresDeepDive/environment/reflectionProbes).

As of 7.48.0 new options are available on the prefiltering front.
- The parameter `prefilterIrradianceOnLoad` prefilters the HDR texture and stores the diffuse part of the IBL as a texture instead of harmonics. This provides much more dynamic range in the output and can allow "true" HDR.
- The parameter `prefilterUsingCdf` can be used to generate the irradiance texture by relying on the HDR CDF data, which helps produce results closer to ray tracers.

![IBL Filters](/img/how_to/environment/iblFilters.webp)

## Using a pure cube texture

![inspector env texture tool](/img/how_to/environment/inspector-generate-env-texture.webp)

While using a `.dds` or `.env` cube texture is the best option, you may still want to rely on a classic cube texture (mostly for size reasons).
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 own packing format to simplify sharing and downloading those assets. This file needs to work cross-platform for easy deployment, which is why we are not relying directly on compressed textures.

We then pack into one file (similar to DDS or KTX) a JSON manifest header, the polynomial information, and all the faces of the mipmap chain from the prefiltered cube texture in `.png` format, which compresses well and decodes quickly in all browsers.

To keep HDR support with PNG, we chose to rely on RGBD because it offers a better distribution of values in the low range than RGBM while keeping the [0-1] range untouched, which is generally used more frequently. It is also less complex to decode at runtime than LogLUV when needed. It seems like the best tradeoff for us.

RGBD also offers little to no transparency in the lower range, preventing browsers that rely on premultiplication of alpha from losing data in the most visible area. We also introduced a special offset from the max range to ensure that we do not reach problematic alpha values in legacy browsers (when alpha is too close to 0, color quantization creates unacceptable banding artifacts).

In WebGL2 browsers, we unpack the data into HalfFloat or FullFloat textures, if supported, to speed up runtime and allow some interpolations to be computed correctly.

The file also packs the polynomial harmonics/spherical data in the format Babylon expects internally, speeding up load time by avoiding additional computation or transformation.

As rendering to LOD, or even copying to LOD, of Half/Full float textures does not work consistently in WebGL1-based browsers, we unpack the data live in the fragment shader. Because RGBD interpolation is not correct, we verified through different test cases that the resulting visual artifacts were worth the transfer-size savings. It looks acceptable in the sets of textures we have been testing.

For example, we can now rely on a 512px cube-sized texture with around 3Mb of data versus 32 Mb for the unpacked version, without noticing any significant quality loss. This also speeds up our time to first frame by removing the need to compute the polynomials.



## Introduction

[OpenPBR](https://github.com/AcademySoftwareFoundation/OpenPBR?tab=readme-ov-file) is an open standard developed by Autodesk and Adobe that defines an artist-friendly material model with a focus on interoperability. Materials authored using it should have a consistent look on platforms that support OpenPBR.

The implementation of OpenPBR support in Babylon.js has started and its status is listed below.


## OpenPBR model description

OpenPBR is a so-called über shader. Unlike node-based or closure-based models like MaterialX or MDL, which allow arbitrarily complex shaders to be described, OpenPBR has a fixed material structure. This saves valuable time because the structure is already designed to cover the majority of production needs, but it is less flexible and will not cover all possible cases.


## OpenPBR support in Babylon.js

The parameters controlling the behaviour of the different parts of the material are organised in groups: Base, Specular, Transmission, Subsurface, Coat, Fuzz, Emission, Thin-film, Geometry.


### Base

Most of the Base group is already expected to work in Babylon.js. One notable missing element is the new [energy conserving Oren-Nayar diffuse model](https://arxiv.org/abs/2410.18026) introduced for OpenPBR.

| Parameter                | Support in Babylon.js |
| ------------------------ | --------------------- |
| `base_weight`            | Present as `PBRBaseMaterial._baseWeightTexture` and `_baseWeight` |
| `base_color`             | Present as `PBRBaseMaterial._albedoTexture` and `_albedoColor` |
| `base_metalness`         | Present as `PBRBaseMaterial._metallicTexture` and `_metallic` |
| `base_diffuse_roughness` | Missing. |


### Specular

In OpenPBR, the specular lobe uses the F82-tint model and a new anisotropy parametrisation.

| Parameter                       | Support in Babylon.js |
| ------------------------------- | --------------------- |
| `specular_weight`               | Missing               |
| `specular_color`                | To be evaluated       |
| `specular_roughness`            | Present as `PBRBaseMaterial._microSurfaceTexture` and `_roughness` |
| `specular_roughness_anisotropy` | To be evaluated       |
| `specular_ior`                  | To be evaluated       |


### Transmission

In OpenPBR, Transmission represents the volume part in which scattering is limited or absent.

| Parameter                             | Support in Babylon.js |
| ------------------------------------- | --------------------- |
| `transmission_weight`                 | To be evaluated       |
| `transmission_color`                  | To be evaluated       |
| `transmission_depth`                  | To be evaluated       |
| `transmission_scatter`                | To be evaluated       |
| `transmission_scatter_anisotropy`     | To be evaluated       |
| `transmission_dispersion_scale`       | To be evaluated       |
| `transmission_dispersion_abbe_number` | To be evaluated       |


### Subsurface

In OpenPBR, Subsurface represents the volume part in which scattering is strong.

| Parameter                       | Support in Babylon.js |
| ------------------------------- | --------------------- |
| `subsurface_weight`             | To be evaluated       |
| `subsurface_color`              | To be evaluated       |
| `subsurface_radius`             | To be evaluated       |
| `subsurface_radius_scale`       | To be evaluated       |
| `subsurface_scatter_anisotropy` | To be evaluated       |


### Coat

| Parameter                   | Support in Babylon.js |
| --------------------------- | --------------------- |
| `coat_weight`               | Present as `PBRClearCoatConfiguration.intensity` |
| `coat_color`                | Present as `PBRClearCoatConfiguration.tintColor` |
| `coat_roughness`            | Present as `PBRClearCoatConfiguration.roughness` |
| `coat_roughness_anisotropy` | Missing               |
| `coat_ior`                  | Present as `PBRClearCoatConfiguration.indexOfRefraction` |
| `coat_darkening`            | Missing               |


### Fuzz

What OpenPBR refers to as "Fuzz" is what some models call "Sheen", but expressive enough to cover cases like clothes or dust.

| Parameter        | Support in Babylon.js |
| ---------------- | --------------------- |
| `fuzz_weight`    | To be evaluated       |
| `fuzz_color`     | To be evaluated       |
| `fuzz_roughness` | To be evaluated       |


### Emission

In OpenPBR, the emissive properties of a material are given in physical units. This requires the renderer to handle physical light units to get a correct result.

| Parameter            | Support in Babylon.js |
| -------------------- | --------------------- |
| `emission_luminance` | To be evaluated       |
| `emission_color`     | To be evaluated       |


### Thin-film

In OpenPBR, iridescence uses a thin-film model. Iridescence is already supported in Babylon.js and exposes similar parameters, but the model might be different.

| Parameter             | Support in Babylon.js |
| --------------------- | --------------------- |
| `thin_film_weight`    | Present as `PBRIridescenceConfiguration.intensity` |
| `thin_film_thickness` | Exposed as `PBRIridescenceConfiguration.thicknessTexture` with `minimumThickness` and `maximumThickness` |
| `thin_film_ior`       | Present as `PBRIridescenceConfiguration.indexOfRefraction` |


### Geometry

OpenPBR only describes the material, but it expects to be given certain information about the geometry.

| Parameter               | Support in Babylon.js |
| ----------------------- | --------------------- |
| `geometry_opacity`      | To be evaluated       |
| `geometry_thin_walled`  | To be evaluated       |
| `geometry_normal`       | To be evaluated       |
| `geometry_tangent`      | To be evaluated       |
| `geometry_coat_normal`  | To be evaluated       |
| `geometry_coat_tangent` | To be evaluated       |



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 separately on the R, G, and B components of the pixel values, each one 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 a red value (R=1, G=0, B=0).


## How to Use Blend Modes

Blend modes are used by manipulating the `alphaMode` property of materials and 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 has 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.webp)

This playground showcases the available blend modes in action: <Playground id="#1MSIXB#4" title="Blend Modes Example" description="Simple example of blend modes in Babylon.js." image="/img/playgroundsAndNMEs/divingDeeperBlendModes1.webp"/>



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.webp)

## Creating and Applying

This is simply achieved using the `dynamicTexture` function with just three parameters:

```javascript
const myDynamicTexture = new BABYLON.DynamicTexture(name, option, scene);
```

though the existing default values of `mipmaps`, `sampling mode`, and `texture format` can be overridden.

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 existing 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
const myMaterial = new BABYLON.StandardMaterial("Mat", scene);
myMaterial.diffuseTexture = myDynamicTexture;
mesh.material = myMaterial;
```
## Attaching to a Canvas
An existing canvas can be used to define the size of a `dynamicTexture` when passed as an `option` parameter during creation, as seen above. In addition to referencing the size of the canvas, the created `dynamicTexture` will also attach itself to that referenced canvas. This means that the `dynamicTexture` will duplicate whatever is rendered to that referenced canvas when `dynamicTexture.update()` is called. 

<Playground id="#RLDCOV" title="Attach to Canvas" description="Copying contents of canvas to a dynamic texture." image="/img/playgroundsAndNMEs/dynamicTextureReferencingCanvas.webp"/>

## 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 the distance from the bottom and the letters are reversed;
- update: boolean, true by default, the dynamic texture will immediately be updated.

<Playground id="#5ZCGRM#2" title="Drawing Text" description="Simple example of drawing text with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture1.webp"/>

## Canvas Methods

You can obtain the canvas context using

```javascript
const ctx = myDynamicTexture.getContext();
```

This exposes all the possibilities of the [HTML5 canvas](https://www.w3schools.com/Tags/ref_canvas.asp) element, giving you full control over drawing, transforming, compositing, and other pixel manipulation to create or update your dynamic texture in real time.

### 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 to be updated.

```javascript
myDynamicTexture.update();
```

**Note:** use `update(false)` if you do not want to use `invertY`.

<Playground id="#5ZCGRM#3" title="Drawing A Curve" description="Simple example of drawing a circle with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture2.webp"/>

### 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 a whole image

```javascript
const 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
const img = new Image();
img.src = 'PATH TO IMAGE';
img.onload = function() {
  ctx.drawImage(this, image start x, image start y, image width, image height, canvas to x, canvas to y, destination width, destination height);
  myDynamicTexture.update();
}
```

<Playground id="#5ZCGRM#4" title="Adding An Image" description="Simple example of adding an image with dynamic textures." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture3.webp"/>

### Transformations

Anything that is drawn to a canvas can be transformed using methods like `scale`, `rotate`, or `translate`. It is helpful to `save` the context before the transformation and then `restore` the context afterward to ensure the texture updates correctly.

``` javascript
const texSize = 512;

ctx.save();

// define position and size of rectangle
const left = texSize * 0.5 - (texSize * 0.125);
const top = texSize * 0.5 - (texSize * 0.125);
const width = 0.25 * texSize;
const height = 0.25 * texSize;

// translate context to center rotation of rectangle
const rotationCenterU = width * 0.5 + left;
const rotationCenterV = height * 0.5 + top;
ctx.translate(rotationCenterU, rotationCenterV);

// rotate context before drawing
ctx.rotate(Math.PI/4);

// draw rectangle
ctx.fillStyle = "Red";
ctx.fillRect(-width * 0.5, -height * 0.5, width, height);

ctx.restore();

```

<Playground id="#6XFI1A" title="Translate and Rotate Rectangle" description="Simple example of transforming a rectangle on a dynamic texture" image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture8.webp"/>


## Playground Combination

This playground combines all the above techniques.

<Playground id="#5ZCGRM#1" title="All Dynamic Texture Techniques" description="Simple example of all of the dynamic texture techniques." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture4.webp"/>

## 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 the aspect ratio. The number you multiply by defines the sharpness of the text; low numbers produce blurred text. Now you can create the dynamic texture.

```javascript
const DTWidth = planeWidth * 60;
const DTHeight = planeHeight * 60;
const dynamicTexture = new BABYLON.DynamicTexture("DynamicTexture", { width: DTWidth, height: DTHeight }, scene);
```

For the next stage, use any font size to write and measure the width of the text on the dynamic texture.

```javascript
const ctx = dynamicTexture.getContext();
const size = 12; //any value will work
ctx.font = size + "px " + font_type;
const textWidth = ctx.measureText(text).width;
```

The ratio of text width to the applied font size can then be used with the dynamic texture width to determine the font size that will fit the plane.

```javascript
const ratio = textWidth / size;

const 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
const font_size = Math.floor(DTWidth / (ratio * 1.1));
```

Now set the font and draw the text.

```javascript
const 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
const mat = new BABYLON.StandardMaterial("mat", scene);
mat.diffuseTexture = dynamicTexture;
plane.material = mat;
```

<Playground id="#TMHF80#1" title="Fit Text To Plane" description="Simple example of fitting text to a plane with a dynamic texture." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture5.webp"/>

### Fit an Area to Text

Take a plane mesh of fixed height, **planeHeight**, and some text with a set font size. You can then calculate how wide the plane must be for the text to fit. 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
const temp = new BABYLON.DynamicTexture("DynamicTexture", 64, scene);
const tmpctx = temp.getContext();
tmpctx.font = font;
const DTWidth = tmpctx.measureText(text).width;
```

Choose a height for the dynamic texture, **DTHeight**, and then 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;
5. create the plane with width and height planeWidth and planeHeight.

```javascript
const planeHeight = 3;
const DTHeight = 256; //or set as wished
const ratio = planeHeight / DTHeight;
const planeWidth = DTWidth * ratio;

const dynamicTexture = new BABYLON.DynamicTexture("DynamicTexture", { width: DTWidth, height: DTHeight }, scene, false);
const 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

const plane = BABYLON.MeshBuilder.CreatePlane("plane", { width: planeWidth, height: planeHeight }, scene);
plane.material = mat;
```

<Playground id="#TMHF80" title="Fit Plane To Text" description="Simple example of fitting a plane to text with a dynamic texture." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture6.webp"/>

## Serialization

The dynamic texture can be serialized with the scene using `SceneSerializer.Serialize()` or a mesh using `SceneSerializer.SerializeMesh()`.

**Note:** Be sure that the scene is ready before serialization.

This playground demonstrates serializing a dynamic texture associated with a material on a mesh:

<Playground id="#FU0ES5" title="Drawing Text and a Curve Texture Serialized Mesh" description="Simple example of drawing text and a curve texture serialized mesh." image="/img/playgroundsAndNMEs/divingDeeperDynamicTexture7.webp"/>

## Dynamic Texture Example
![product customization with dynamic texture](/img/how_to/productCustomizationDynamicTexture.webp)

This playground example incorporates a user-manipulated dynamic texture allowing the customization of an asset. This scene demonstrates many of the previous concepts and shows why dynamic textures are a great way to provide users with interactive scene materials.

<Playground id="#XMEL56#7" title="Product Customization" description="Customize the graphics of a skateboard deck." isMain={true} category="Dynamic Texture"/>




Babylon.js 1.14 introduced new parameters for the StandardMaterial: _FresnelParameters_.

![](/img/how_to/Fresnel/fresnel.webp)

There are 5 of them:

* ```StandardMaterial.diffuseFresnelParameters```
* ```StandardMaterial.opacityFresnelParameters```
* ```StandardMaterial.reflectionFresnelParameters```
* ```StandardMaterial.emissiveFresnelParameters```
* ```StandardMaterial.refractionFresnelParameters```

## How Fresnel Works

A Fresnel term is computed by the StandardMaterial to change how a color is applied based on the viewing angle.

For instance, you can simulate great glass or reflection effects by just using a simple Fresnel term. It gives you more reflection on the edges and less in 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.webp)

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.webp)

By using the ```bias``` and ```power``` properties, you can control how the Fresnel term 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.webp)

## How to use it

A _FresnelParameter_ is defined by the following properties:
* ```isEnabled``` to activate or deactivate the Fresnel effect
* leftColor to define the color used on the edges
* rightColor to define the color used in the center
* bias to define the bias applied to the computed Fresnel term
* power to define the exponent applied to the Fresnel term

Here is a simple example:

```javascript
material.reflectionTexture = new BABYLON.CubeTexture("Scenes/Customs/skybox/TropicalSunnyDay", scene);
material.diffuseColor = new BABYLON.Color3(0, 0, 0);
material.emissiveColor = new BABYLON.Color3(0.5, 0.5, 0.5);
material.alpha = 0.2;
material.specularPower = 16;

// Fresnel
material.reflectionFresnelParameters = new BABYLON.FresnelParameters();
material.reflectionFresnelParameters.bias = 0.1;

material.emissiveFresnelParameters = new BABYLON.FresnelParameters();
material.emissiveFresnelParameters.bias = 0.6;
material.emissiveFresnelParameters.power = 4;
material.emissiveFresnelParameters.leftColor = BABYLON.Color3.White();
material.emissiveFresnelParameters.rightColor = BABYLON.Color3.Black();

material.opacityFresnelParameters = new BABYLON.FresnelParameters();
material.opacityFresnelParameters.leftColor = BABYLON.Color3.White();
material.opacityFresnelParameters.rightColor = BABYLON.Color3.Black();
```

<Playground id="#22KZUW#6" title="Fresnel Refraction" description="Simple example of using fresnel refraction in your scene." image="/img/playgroundsAndNMEs/divingDeeperFresnel1.webp"/>
<Playground id="#AQZJ4C#0" title="Fresnel Parameters" description="Simple example for you to explore fresnel parameters in your scene." image="/img/playgroundsAndNMEs/divingDeeperFresnel2.webp"/>



Having a front and a back makes the most sense when talking about flat meshes such as a plane, a disc, or a polygon. All of these 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 on the front and back, the front and back images must be in the same file, like the one below.

![front and back images](/img/how_to/different-material-front-back/card.webp)

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, where
(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 define two variables:

```javascript
const f = new BABYLON.Vector4(0.5, 0, 1, 1); // front image = half the whole image along the width
const b = new BABYLON.Vector4(0, 0, 0.5, 1); // back image = second half along the width
```

and then place them in the options

```javascript
const plane = BABYLON.MeshBuilder.CreatePlane("plane", { height: 1, width: 0.665, sideOrientation: BABYLON.Mesh.DOUBLESIDE, frontUVs: f, backUVs: b }, scene);
```

taking into account the width-to-height ratio of the section of the image.

You then simply create a _StandardMaterial_ and set the texture to the image.

```javascript
const mat = new BABYLON.StandardMaterial("", scene);
mat.diffuseTexture = new BABYLON.Texture("URL to Image File", scene);
plane.material = mat;
```

## Two Sided Examples

<Playground id="#LXZPJK#3" title="Different Images On A Plane" description="Simple example of applying different images to the front and back of a plane." image="/img/playgroundsAndNMEs/divingDeeperFrontBack1.webp"/>
<Playground id="#4G18GY#909" title="Different Images On A Polygon" description="Simple example of applying different images to the front and back of a Polygon." image="/img/playgroundsAndNMEs/divingDeeperFrontBack2.webp"/>

## Inside and Outside Examples

<Playground id="#165IV6#74" title="Different Images On A Tube" description="Simple example of applying different images to the front and back of a tube." image="/img/playgroundsAndNMEs/divingDeeperFrontBack3.webp"/>
<Playground id="#K6M44R#3" title="Image On The Outside Of A Sphere" description="Simple example of applying an image to the outside of a sphere." image="/img/playgroundsAndNMEs/divingDeeperFrontBack4.webp"/>
<Playground id="#K6M44R#4" title="Image On The Inside Of A Sphere" description="Simple example of applying an image to the inside of a sphere." image="/img/playgroundsAndNMEs/divingDeeperFrontBack5.webp"/>



## What is an HTML Texture?

`HtmlTexture` renders a **live HTML element** — a `<div>`, a form, an SVG, an entire styled DOM subtree — into a texture you can apply to any material. It is built on the experimental [WICG HTML-in-Canvas](https://github.com/WICG/html-in-canvas) API, which lets the browser lay out and rasterize a real DOM element directly into a WebGL or WebGPU texture.

Unlike a [Dynamic Texture](/features/featuresDeepDive/materials/using/dynamicTexture) (where you draw with the 2D canvas API) or a [Video Texture](/features/featuresDeepDive/materials/using/videoTexture) (which copies a `<video>` element), `HtmlTexture` snapshots arbitrary, fully styled HTML — including text, CSS layout, and nested elements.

It also ships with optional **interaction managers** that route Babylon pointer events back to the DOM, so the rendered HTML can stay interactive (buttons, links, hover states) on a 3D surface.

## Examples

<Playground id="#C9MWZC#2" title="HTML Texture Control Panel" description="An interactive HTML control panel (theme swatches, counter, toggle and animated progress bar) rendered onto a plane as an HtmlTexture."/>

<Playground id="#8RDVXG#1" title="Multiple HTML Textures" description="Two independent HtmlTextures — a live counter and an interactive button card — each on its own rotating plane."/>

Both demos load the polyfill from a CDN so they run in any browser (see [Enabling the polyfill](#enabling-the-polyfill)).

## Browser support

The underlying API is experimental and not yet broadly shipped. `HtmlTexture` renders through the first available of these paths:

- **Natively**, in a browser that exposes the API (for example, Chrome Canary with `chrome://flags/#canvas-draw-element` enabled). This is the fastest path: the browser copies the laid-out element straight into the GPU texture.
- **Via a polyfill**, using [`three-html-render`](https://github.com/repalash/three-html-render), installed through the helper in `@babylonjs/core` (see [Enabling the polyfill](#enabling-the-polyfill) below).
- **Via the built-in SVG fallback**, which works in any modern browser with no extra setup (see [The built-in SVG fallback](#the-built-in-svg-fallback) below). This is the default when neither of the above is present.

Because the SVG fallback is enabled by default, `HtmlTexture` renders in regular browsers out of the box. It never throws, so it is safe to include in code that also runs on browsers without the native API.

Both **WebGL2** and **WebGPU** engines are supported; the correct upload path is selected automatically.

## Creating an HTML Texture

```javascript
// Any live DOM element can be the source.
const el = document.createElement("div");
el.style.cssText = "width:512px;height:512px;background:#1e293b;color:#fff;font:24px sans-serif;padding:24px;box-sizing:border-box";
el.innerHTML = "<h1>Hello DOM</h1><p>Rendered into a texture.</p>";

const htmlTexture = new BABYLON.HtmlTexture("html", el, { scene });

const material = new BABYLON.StandardMaterial("mat", scene);
material.emissiveTexture = htmlTexture;
material.disableLighting = true;

const plane = BABYLON.MeshBuilder.CreatePlane("plane", { size: 2 }, scene);
plane.material = material;
```

The element is hosted inside a hidden `<canvas layoutsubtree>` that Babylon adds to the document for you, so the browser can lay it out and paint it. You do not need to attach the element to the DOM yourself.

### Creation options

The third constructor argument is an `IHtmlTextureOptions` object:

| Option            | Default                            | Description                                                                                                                                       |
| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scene`           | —                                  | The scene the texture belongs to. Provide either `scene` or `engine`.                                                                             |
| `engine`          | —                                  | The engine to use, when no scene is available.                                                                                                    |
| `width`           | element `offsetWidth`, then `256`  | Texture width in pixels.                                                                                                                          |
| `height`          | element `offsetHeight`, then `256` | Texture height in pixels.                                                                                                                         |
| `generateMipMaps` | `false`                            | Whether mip maps are generated.                                                                                                                   |
| `samplingMode`    | `TEXTURE_BILINEAR_SAMPLINGMODE`    | The texture sampling mode.                                                                                                                        |
| `format`          | `TEXTUREFORMAT_RGBA`               | The texture format.                                                                                                                               |
| `autoUpdate`      | `true`                             | When `true`, the texture refreshes whenever the host canvas reports a paint change.                                                               |
| `useSvgFallback`  | `true`                             | When `true`, render through the built-in SVG fallback if the native (or polyfilled) API is unavailable. Set to `false` to require the native API. |

## Updating the texture

When `autoUpdate` is enabled (the default), the texture refreshes automatically whenever the hosted element repaints. You can also drive updates manually:

```javascript
// Force an immediate re-render from the current DOM state.
htmlTexture.update();

// Ask the host canvas to repaint on the next frame (falls back to update() when unsupported).
htmlTexture.requestUpdate();
```

The `onLoadObservable` fires once, the first time the texture has rendered successfully:

```javascript
htmlTexture.onLoadObservable.addOnce(() => {
  console.log("HTML texture is ready");
});
```

Call `htmlTexture.dispose()` when you are done; it removes the hidden host canvas and releases the GPU texture.

## The built-in SVG fallback

When the native WICG API (or its polyfill) is unavailable, `HtmlTexture` falls back to rasterizing the element through an SVG [`<foreignObject>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/foreignObject). The element is serialized, wrapped in an SVG image, and uploaded to the texture as a [Dynamic Texture](/features/featuresDeepDive/materials/using/dynamicTexture). This works in any modern browser with no flags or extra dependencies, so it is the default behavior.

The fallback is convenient but less capable than the native path. Keep these caveats in mind:

- **Inline styles only.** External stylesheets and `<link>`-ed CSS are not applied; style the element (or its children) inline, or inject a `<style>` element into the serialized subtree.
- **Same-origin resources.** Cross-origin images, fonts, and other external resources taint the snapshot and cause the fallback to fail; the texture logs a one-time warning when this happens.
- **Static snapshot.** The fallback captures the DOM as it is at update time. Interactive states that the browser computes during real rendering — `:hover`, focus rings, native form-control state, running scripts — are not reflected.
- **Heavier than the native copy.** Each update serializes the DOM and decodes an image, so prefer driving updates explicitly (rather than per-frame) for complex content.

To require the native API and skip the fallback entirely, pass `useSvgFallback: false`. The texture then logs a one-time warning and renders nothing when the native API is missing.

```javascript
// Only render when the native WICG API (or polyfill) is available.
const htmlTexture = new BABYLON.HtmlTexture("html", el, { scene, useSvgFallback: false });
```

## Interaction

`HtmlTexture` is one-way by default: it produces a live image of the DOM, but pointer picks on the mesh do not reach the element. Two optional managers (both in `@babylonjs/core`) bridge Babylon pointer events to the DOM so the rendered HTML stays interactive. They are tree-shaken out unless you import them.

### Raycast interaction (any mesh)

`HtmlRaycastInteractionManager` works for **arbitrary meshes** — planes, boxes, and curved surfaces — because it maps the picked UV coordinate back to a pixel inside the element and dispatches a synthetic DOM pointer event there.

```javascript
// Register your DOM listeners as usual.
el.querySelector("button").addEventListener("click", () => console.log("clicked in 3D"));

new BABYLON.HtmlRaycastInteractionManager(scene, htmlTexture, plane);
```

| Option            | Default           | Description                                                                       |
| ----------------- | ----------------- | --------------------------------------------------------------------------------- |
| `targetElement`   | texture's element | The element that receives forwarded events.                                       |
| `backFaceCulling` | `true`            | Ignore hits on back-facing geometry.                                              |
| `invertY`         | `true`            | Whether the texture content is stored Y-inverted, used when mapping UV to pixels. |

> Because it relies on scene picking, `HtmlRaycastInteractionManager` requires the `Ray` side-effect import when you consume `@babylonjs/core` as ES modules. Add it once, anywhere in your app:
>
> ```javascript
> import "@babylonjs/core/Culling/ray";
> ```
>
> The UMD bundle and the Playground include this automatically. `HtmlInteractionManager` (below) does not need it.

### Overlay interaction (planar meshes)

`HtmlInteractionManager` positions the **real DOM element** as a screen-aligned overlay over the projected face of a planar mesh, so the browser hit-tests it natively. This preserves full native fidelity — focus, text selection, and form input — at the cost of being limited to flat, camera-facing surfaces (it applies position, size, and in-plane rotation, not a full perspective skew).

```javascript
new BABYLON.HtmlInteractionManager(scene, htmlTexture, plane);
```

| Option                | Default           | Description                                                         |
| --------------------- | ----------------- | ------------------------------------------------------------------- |
| `targetElement`       | texture's element | The element to overlay.                                             |
| `enablePointerEvents` | `true`            | Whether the overlay captures pointer events for native hit-testing. |

Both managers expose a `dispose()` method that detaches their observers.

> Choose `HtmlRaycastInteractionManager` when the surface is curved or non-planar, or when you want Babylon to remain in control of the pointer pipeline. Choose `HtmlInteractionManager` when you need true native DOM input (keyboard, IME, text selection) on a flat panel.

## Enabling the polyfill

When the native API is not present, install the polyfill helper from `@babylonjs/core`. It lazily imports `three-html-render` only when needed, so it never adds to your bundle unless it is actually used.

```javascript
import { InstallHtmlInCanvasPolyfill } from "@babylonjs/core/Materials/Textures/HTML/htmlInCanvasPolyfill";

// No-op when the API is supported natively; installs the polyfill otherwise.
await InstallHtmlInCanvasPolyfill();
```

Helpers available in `@babylonjs/core`:

- `IsHtmlInCanvasSupportedNatively()` — returns `true` when the browser exposes the API natively.
- `InstallHtmlInCanvasPolyfill(options?)` — installs the polyfill and resolves to `true` when it was installed. By default it is a no-op when native support is present; pass `{ force: true }` to install regardless. Appending `?polyfillHIC` to the page URL also forces installation.
- `UninstallHtmlInCanvasPolyfill()` — removes a previously installed polyfill.

### In the Playground

The Playground's UMD bundle can't dynamically import the polyfill package, so load the self-installing CDN build with a `<script>` tag before creating any `HtmlTexture`. The script installs itself on load, is idempotent, and no-ops when the native API is present:

```javascript
const ensureHtmlInCanvasAsync = function () {
    if ("captureElementImage" in HTMLCanvasElement.prototype) {
        return Promise.resolve();
    }
    if (document.querySelector("script[data-hic-polyfill]")) {
        return Promise.resolve();
    }
    return new Promise(function (resolve, reject) {
        const script = document.createElement("script");
        script.src = "https://cdn.jsdelivr.net/npm/three-html-render@0.1.2/dist/polyfill.js";
        script.dataset.hicPolyfill = "";
        script.onload = function () { resolve(); };
        script.onerror = function () { reject(new Error("Failed to load the HTML-in-Canvas polyfill")); };
        document.head.appendChild(script);
    });
};

// at the top of your async createScene, before building any HtmlTexture:
await ensureHtmlInCanvasAsync();
```

## Putting it together

```javascript
import { InstallHtmlInCanvasPolyfill } from "@babylonjs/core/Materials/Textures/HTML/htmlInCanvasPolyfill";

const createScene = async function () {
  const scene = new BABYLON.Scene(engine);
  const camera = new BABYLON.ArcRotateCamera("camera", -Math.PI / 2, Math.PI / 2.5, 4, BABYLON.Vector3.Zero(), scene);
  camera.attachControl(true);
  new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);

  // Use the native API when present, fall back to the polyfill otherwise.
  await InstallHtmlInCanvasPolyfill();

  const el = document.createElement("div");
  el.style.cssText = "width:512px;height:512px;background:#1e293b;color:#fff;font:24px sans-serif;padding:24px;box-sizing:border-box";
  el.innerHTML = "<h1>Hello DOM</h1><button>Click me</button>";
  el.querySelector("button").addEventListener("click", (e) => (e.target.textContent = "Clicked!"));

  const htmlTexture = new BABYLON.HtmlTexture("html", el, { scene, autoUpdate: true });

  const material = new BABYLON.StandardMaterial("mat", scene);
  material.emissiveTexture = htmlTexture;
  material.disableLighting = true;

  const plane = BABYLON.MeshBuilder.CreatePlane("plane", { size: 2 }, scene);
  plane.material = material;

  // Forward pointer picks to the DOM so the button is clickable in 3D.
  new BABYLON.HtmlRaycastInteractionManager(scene, htmlTexture, plane);

  return scene;
};
```

## Notes and limitations

- The API is experimental; behavior and availability may change as the WICG specification evolves.
- Cross-origin content (for example, third-party `<iframe>`s) cannot be rasterized, mirroring the browser's tainted-canvas rules.
- The built-in SVG fallback only captures same-origin, inline-styled content as a static snapshot; see [The built-in SVG fallback](#the-built-in-svg-fallback) for details, or set `useSvgFallback: false` to require the native API.
- The overlay `HtmlInteractionManager` is screen-aligned and does not perspective-correct steeply oblique faces; use the raycast manager for those.
- Synthetic pointer forwarding (`HtmlRaycastInteractionManager`) delivers pointer events, but not native keyboard or IME input into rasterized form fields; use the overlay manager when real text input is required.



## Introduction

The aim of Physically Based Rendering, PBR, is to simulate **real life lighting**.

PBR is a grouping of techniques; it does not force you to choose one in particular. Among others, these include:

- [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 implemented through `PBRMaterial`. This material contains all the 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.webp)

The two additional materials are `PBRMetallicRoughnessMaterial` and `PBRSpecularGlossinessMaterial`. They both implement a specific convention based on GLTF specifications:

- [Metallic roughness convention](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#metallic-roughness-material) (This is the recommended convention)
- [Specular glossiness convention](https://github.com/KhronosGroup/glTF/blob/master/extensions/2.0/Khronos/KHR_materials_pbrSpecularGlossiness/README.md)

## PBRMetallicRoughnessMaterial

This material is based on five main values:

- baseColor / baseTexture: The base color has two different interpretations depending on the value of metalness. When the material is a metal, the base color is the specific measured reflectance value at normal incidence (F0). For a non-metal the base color represents the reflected diffuse color of the material.
- metallic: Specifies the metallic scalar value of the material. Can also be used to scale the metalness values of the metallic texture.
- roughness: Specifies the roughness scalar value of the material. Can also be used to scale the roughness values of the metallic texture.
- metallicRoughnessTexture: Texture containing both the metallic value in the B channel and the roughness value in the G channel to keep better precision. Ambient occlusion can also be saved in R channel.
- environmentTexture: texture

If you are already familiar with the Babylon Standard Material, we'll focus here on the main differences and the simplest setup; your only change will be to instantiate a **PBRMetallicRoughnessMaterial** instead of a **StandardMaterial**.

```javascript
const 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 physically based values of your material to get a great look and feel:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 0;
pbr.roughness = 1.0;
```

<Playground id="#2FDQT5" title="Roughness Using PBR" description="Simple example PBR roughness in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro1.webp"/>

With this specific configuration, you can see that there is no reflection at all (metallic set to 0) and no specular (roughness set to 1).

If we want to introduce more reflection we can just do the opposite:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0;
pbr.roughness = 0;
```

But in this case, we need something to reflect. To define this environment, just add this line:

```javascript
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("/textures/environment.dds", scene);
```

This call will create all required data used by the materials to produce final output.

<Playground id="#2FDQT5#11" title="Reflective Metallic Surface Using PBR" description="Simple example of a reflective metallic surface using PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro2.webp"/>

Perhaps a bit too reflective now, so let's add more roughness to give it a more golden look:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0;
pbr.roughness = 0.4;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("/textures/environment.dds", scene);
```

<Playground id="#2FDQT5#12" title="Reflective Surface With Roughness Using PBR" description="Simple example of a reflective surface with roughness using PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro3.webp"/>

To get more precise control over the metallic and roughness values on your object, you can also specify the metallicRoughnessTexture:

```javascript
pbr.baseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.metallic = 1.0; // set to 1 to only use it from the metallicRoughnessTexture
pbr.roughness = 1.0; // set to 1 to only use it from the metallicRoughnessTexture
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("/textures/environment.dds", scene);
pbr.metallicRoughnessTexture = new BABYLON.Texture("/textures/mr.jpg", scene);
```

<Playground id="#2FDQT5#13" title="Reflective Surface With A Metallic Roughness Texture" description="Simple example of a reflective surface with a metallic roughness texture in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro4.webp"/>

## 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 the material is (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 pixel.
- environmentTexture: texture

The setup of this material is comparable to the one used for PBRMetallicRoughnessMaterial:

```javascript
const pbr = new BABYLON.PBRSpecularGlossinessMaterial("pbr", scene);
pbr.diffuseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.specularColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.glossiness = 0.4;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("/textures/environment.dds", scene);
```

<Playground id="#Z1VL3V#5" title="Surface Glossiness With PBR" description="Simple example of surface glossiness with PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro5.webp"/>

The specularGlossinessTexture can then, like the metallicRoughnessTexture, be used to provide more control over specular and glossiness:

```javascript
pbr.diffuseColor = new BABYLON.Color3(1.0, 0.766, 0.336);
pbr.specularColor = new BABYLON.Color3(1.0, 1.0, 1.0);
pbr.glossiness = 1.0;
pbr.environmentTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("/textures/environment.dds", scene);
pbr.specularGlossinessTexture = new BABYLON.Texture("/textures/sg.png", scene);
```

<Playground id="#Z1VL3V#4" title="Glossiness Texture Added In PBR" description="Simple example of glossiness texture added in PBR in your scene." image="/img/playgroundsAndNMEs/divingDeeperPBRIntro6.webp"/>

## 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 to how light behaves in real life. So, the farther you are, the higher your light intensity will need to be to reach a surface.

To go even further, the intensity you define on the lights follows physics-based units:

- 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) with PBR.



## Introduction

<img src="/img/resources/gpu_compressed_textures/compression_cesar.webp" 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 world because it allows you to use more assets within the same memory budget and provides better performance 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. That's different from a `.png` or `.jpg` file, for example, which also holds compressed data but must be expanded before being sent to the GPU.

## Working with compressed texture formats

<img src="/img/resources/gpu_compressed_textures/container.webp" 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/featuresDeepDive/materials/advanced/mutliPlatTextures#khronos-texture-container-format--ktx-files) for more details. So, to support a wide range of devices, you would need to provide your assets in multiple different formats and Babylon.js would choose the right one depending on the capability of the target device.

It can be a bit tedious to generate and maintain so many formats for a given asset, so **container files** have been created. These files can either contain multiple formats of the same asset or be transcodable to multiple formats. Because this is 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.webp" 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 version 1), and the associated file format extension is **.ktx2**.

This file does not in fact contain different formats of the same asset, but rather a **universal representation** of the data that can be transcoded to any format supported by the target device! We speak of **transcoding** instead of **expanding** because the data are not expanded per se; they are transformed into another compressed format, one supported by your target device (the universal representation is 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 sizes. Works best on images, photos, map data, or albedo/specular/etc. textures, but does not work as well on 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 texture, 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 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 only deals with the ETC1S and UASTC universal compression schemes listed above.

## Babylon.js support for .ktx2 files

<img src="/img/resources/gpu_compressed_textures/breeze.webp" title="KTX2" caption="Gif courtesy of giphy.com"/>

On the **Babylon.js** side, using such files is a breeze: just create a Texture instance that points 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 implementation of Babylon.js is developed 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 or heard of **.basis** files. Those files use the same compression scheme as `.ktx2` files, but this format is not backed by any standards committee, unlike the KTX2 format. So, you should prefer the latter, as it will become the de-facto standard.

## Tools

<img src="/img/resources/gpu_compressed_textures/tools.webp" 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 provides [command line tools](https://github.com/KhronosGroup/KTX-Software/releases) that you can use to generate, check, and 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 compressing!_

<img src="/img/resources/gpu_compressed_textures/compression.webp" title="KTX2" caption="Gif courtesy of giphy.com"/>



## Introduction

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 you 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 can have effects that were previously only possible with complex multi-pass rendering or postprocessing.

**Important note: this only works for Standard and PBR materials (and for materials that would subclass them)!**

## Basic example

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 that modifies 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";
  }

  // This is used to inform the system which language is supported
  isCompatible(shaderLanguage) {
    switch (shaderLanguage) {
        case BABYLON.ShaderLanguage.GLSL:
        case BABYLON.ShaderLanguage.WGSL:
            return true;
        default:
            return false;
    }
  }

  getCustomCode(shaderType, shaderLanguage) {
      if (shaderType === "fragment") { 
        // we're adding this specific code at the end of the main() function
        if (shaderLanguage === BABYLON.ShaderLanguage.WGSL) {
            return {
                CUSTOM_FRAGMENT_MAIN_END: `
                            var luma = fragmentOutputs.color.r*0.299 + fragmentOutputs.color.g*0.587 + fragmentOutputs.color.b*0.114;
                            fragmentOutputs.color = vec4f(luma, luma, luma, 1.0);
                        `,
            };
        }
         
        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 with 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#90" engine="webgpu" title="Basic example" description="Basic material plugin example"/>

## More complex plugins

Sometimes, your material extension will need uniforms. This is also possible with plugins, which can register defines, uniforms, samplers (textures), and attributes.

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;

  isCompatible(shaderLanguage) {
      switch (shaderLanguage) {
          case BABYLON.ShaderLanguage.GLSL:
          case BABYLON.ShaderLanguage.WGSL:
              return true;
          default:
              return false;
      }
  }

  constructor(material) {
    // the fourth parameter is a list of #defines in the [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) 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(shaderLanguage) {
    if (shaderLanguage === BABYLON.ShaderLanguage.WGSL) {
      // For webgpu we only define the UBO with the correct type and size.
        return {
            "ubo": [
            { name: "myColor", size: 3, type: "vec3" },
            ]
        };
    }
    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 in case uniform buffers are not supported by the engine
      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, shaderLanguage) {
    if (shaderLanguage === BABYLON.ShaderLanguage.WGSL) {
        return shaderType === "vertex" ? null : {
            "CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR": `
                #ifdef COLORIFY
                    ${this._varColorName} = vec4f(${this._varColorName}.rgb * uniforms.myColor, ${this._varColorName}.a);
                #endif
            `,

            "!diffuseBase\\+=info\\.diffuse\\*shadow;": `
                diffuseBase += info.diffuse*shadow;
                diffuseBase += vec3f(0., 0.2, 0.8);
            `,
        };
    }
    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#127" engine="webgpu" title="Using uniforms" description="Material plugin example with uniforms"/>

Here's another example which uses a sampler: <Playground id="#HBWKYN#86" engine="webgpu" title="Using sampler" description="Material plugin example with sampler"/>

And another one using a custom attribute this time: <Playground id="#HBWKYN#87" engine="webgpu" title="Using attribute" description="Material plugin example with attribute"/>

## Applying a plugin to a single material

Even though your plugins can be enabled or 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#112" engine="webgpu" title="Single material" description="Material plugin applied to a single material"/>

## Implementing a complete and well-designed plugin

The examples given above should be appropriate 90% of the time, but if you want to fully integrate into the framework or have additional requirements, you may need to do additional work.

A material plugin extends the `MaterialPluginBase` class and we have only implemented a few methods in the examples so far. Here are all the methods you can implement in a material plugin:
| Method | Description |
|--------|-------------|
|`isCompatible`|Implements this method if you are creating a plugin that can handle both GLSL and WGSL (recommended)|
|`isReadyForSubMesh`|Implements this method if you are using resources that may take some time to be ready (like textures). As long as the method returns `false`, the material won't be used to render the mesh|
|`bindForSubMesh`|This method will allow you to bind the uniforms and textures used by your plugin. Use the methods of the provided `uniformBuffer` to set these uniforms / textures|
|`hardBindForSubMesh`|This method is like `bindForSubMesh` but is called even if `mustRebind()` returns `false` (`bindForSubMesh` is only called if `mustRebind` returns `true`). `mustRebind()` is an internal method that returns `true` only if the system thinks the uniform parameters should be rebound. It has its own logic for deciding whether to return `true` or `false` and it may be different from your needs. Use `hardBindForSubMesh` in cases where `isReadyForSubMesh` is not called but you still need to bind some parameters|
|`dispose`|Implements this method if your plugin uses some resources that should be disposed when the plugin is no longer needed|
|`getCustomCode`|This is the method used to inject code in the vertex and fragment shaders. Look at the playgrounds on this page for examples of how to do this|
|`prepareDefines`|This allows you to set the defines used by (the shader code of) your plugin|
|`prepareDefinesBeforeAttributes`|This methods does the same thing as `prepareDefines` but is called before `MaterialHelper.PrepareDefinesForAttributes` is called. So, if you need some defines to exist when `MaterialHelper.PrepareDefinesForAttributes` is called, you should use `prepareDefinesBeforeAttributes` instead of `prepareDefines`|
|`hasTexture`|You should return `true` if you are using the texture passed as a parameter in your plugin. That will ensure that your plugin is properly notified when some properties of this texture change|
|`hasRenderTargetTextures`|You should return `true` if your plugin uses one or more render target texture(s) for its work. That will ensure that the texture(s) is/are rendered correctly in each frame (you also need to implement the `fillRenderTargetTextures` method)|
|`fillRenderTargetTextures`|Will be called if `hasRenderTargetTextures` returns `true`. You should add the render target texture(s) you are using into the array passed as a parameter|
|`getActiveTextures`|You should return all the textures you are using in your plugin (if any)|
|`getAnimatables`|You should return all the animatables you are using in your plugin (if any). Most of the time, these are the textures that have animations (`texture.animations && texture.animations.length > 0`)|
|`getSamplers`|You should return all the samplers (textures) you are using in your plugin (if any)|
|`getAttributes`|You should return all the attributes you are using in your plugin (if any)|
|`getUniformBuffersNames`|You should return the names of all the uniform buffers you are using in your plugin (if any)|
|`getUniforms`|You should return all the uniforms you are using in your plugin (if any). Look at the playgrounds on this page for examples of how to do this|
|`serialize` and `parse`|You should implement these methods if you want your plugin to be properly serialized and parsed. Note that you must also register your plugin class in the BABYLON class store by doing `BABYLON.RegisterClass("BABYLON.PLUGINNAME", PluginClass);`, with `PLUGINNAME` the name of your plugin (as returned by `getClassName()`) and `PluginClass` the name of your plugin class.|

Additional comments:
* if you want to use a texture in your plugin, you have to implement `getSamplers` and add its definition in the **CUSTOM_FRAGMENT_DEFINITIONS** block of code (**CUSTOM_VERTEX_DEFINITIONS** if you want to use the texture in the vertex shader):
```typescript
getSamplers(samplers) {
    samplers.push("texture");
}

getCustomCode(shaderType, shaderLanguage) {
    if (shaderType === "fragment") {
      if (shaderLanguage === BABYLON.ShaderLanguage.WGSL) {
        return {
          "CUSTOM_FRAGMENT_DEFINITIONS": `
              var myTextureSampler: sampler;
              var myTexture: texture_2d<f32>;
          `,

          "CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR": `
                color = vec4f(textureSample(myTexture, myTextureSampler, fragmentInputs.vDiffuseUV + uvOffset).rgb, color.a);
          `,
        }
      }
      return {
        "CUSTOM_FRAGMENT_DEFINITIONS": `
            uniform sampler2D myTexture;
        `,

        "CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR": `
              color.rgb = texture(myTexture, vDiffuseUV + uvOffset).rgb;
        `,
      }
    }
    return null
}
```
* if you want to use a custom attribute in your plugin, you have to implement `getAttributes` and add its definition in the **CUSTOM_VERTEX_DEFINITIONS** block of code:
```typescript
getSamplers(samplers) {
    samplers.push("arrayTex");
}

getAttributes(attributes) {
    attributes.push('texIndices');
}

getCustomCode(shaderType, shaderLanguage) {
  if (shaderLanguage === BABYLON.ShaderLanguage.WGSL) {
    if (shaderType === "vertex") return {
      "CUSTOM_VERTEX_DEFINITIONS": `
          attribute texIndices: f32;
          varying texIndex: f32;
      `,

      "CUSTOM_VERTEX_MAIN_BEGIN": `
          vertexOutputs.texIndex = input.texIndices;
      `,
    }
    if (shaderType === "fragment") return {
        "CUSTOM_FRAGMENT_DEFINITIONS": `
            uniform highp sampler2DArray arrayTex;
            varying texIndex: f32;
        `,

        "!baseColor\\=texture2D\$diffuseSampler,vDiffuseUV\\+uvOffset\$;":
            `baseColor = texture(arrayTex, vec3(vDiffuseUV, texIndex));`,
    }
  }

  if (shaderType === "vertex") return {
      "CUSTOM_VERTEX_DEFINITIONS": `
          attribute float texIndices;
          varying float texIndex;
      `,

      "CUSTOM_VERTEX_MAIN_BEGIN": `
          texIndex = texIndices;
      `,
  }
  if (shaderType === "fragment") return {
      "CUSTOM_FRAGMENT_DEFINITIONS": `
          uniform highp sampler2DArray arrayTex;
          varying float texIndex;
      `,

      "!baseColor\\=texture2D\$diffuseSampler,vDiffuseUV\\+uvOffset\$;":
          `baseColor = texture(arrayTex, vec3(vDiffuseUV, texIndex));`,
  }
  return null
}
```

## Caveats

- The code insertion point names are standard across 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 materials 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="Animate parameter" description="Using a class variable to animate a parameter for all instances"/>
<Playground id="#SYQW69#1077" title="Volumetric fog" description="Power plant with volumetric fog"/>
<Playground id="#IQPBS4#62" title="Grain" description="Grain (solves banding issues)"/>
<Playground id="#8WJTJG#19" title="Fog of War" description="Simple Fog of War effect"/>
<Playground id="#P8B91Z#102" title="Serialize and parse" description="Implements the methods to serialize and parse the plugin"/>

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).



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 materials require a [light source](/features/featuresDeepDive/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
const 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
const 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 of how the material's diffuse color reacts to the diffuse light color, the following Playground example shows how different material colors react to white, red, green, and blue diffuse spot lights.

<Playground id="#20OAV9#325" title="Material Color Reaction to Light Color" description="Simple example of material color reacting to light color." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro1.webp" isMain={true} category="Materials"/>

The following materials also show this reaction to white, red, green, and blue diffuse spot lights:

- Yellow Material
- Purple Material
- Cyan Material
- White Material

![ Spot Light](/img/how_to/Materials/spots1.webp)

## 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 a 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.webp)

<Playground id="#20OAV9#14" title="Use of Ambient Color" description="Simple example of using ambient color in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro2.webp"/>

## Transparent Color Example

Transparency is achieved by setting a material's _alpha_ property from 0 (invisible) to 1 (opaque).

```javascript
myMaterial.alpha = 0.5;
```

<Playground id="#20OAV9#16" title="Material Transparency" description="Simple example of using transparency in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro3.webp" isMain={true} category="Materials"/>

## Texture

Textures are formed using a saved image.

Create a material using

```javascript
const 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
const 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 has an emissive texture, and the one on the right has a material with red diffuse color and an ambient texture.

![Texture](/img/how_to/Materials/texture1.webp)

<Playground id="#20OAV9#15" title="Material with Diffuse, Emissive, and Ambient Textures" description="Simple example of using diffuse, emissive, and ambient textures in your scene materials." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro4.webp" isMain={true} category="Materials"/>

## Transparent Texture Examples

For colors, transparency is achieved by setting a material's _alpha_ property from 0 (invisible) to 1 (opaque).

```javascript
myMaterial.alpha = 0.5;
```

<Playground id="#20OAV9#17" title="Transparent Texture Example" description="Simple example of transparent textures in your scene." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro5.webp"/>

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.webp)

In this case we set the _hasAlpha_ property of the **texture** to true.

```javascript
myMaterial.diffuseTexture.hasAlpha = true;
```

<Playground id="#YDO1F#18" title="Transparent Background Example" description="Simple example of a transparent background in your scene." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro6.webp"/>

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/featuresDeepDive/materials/advanced/texturePackage)

## Back-Face Culling

This is a method for efficiently drawing the 2D rendering of the 3D model. Usually there is no need to draw the back face of a cube or other object,
as it will be hidden by the front face. In Babylon.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.webp) | ![BFC False](/img/how_to/Materials/bfc1.webp) |

<Playground id="#YDO1F#20" title="Backface Culling Example" description="Simple example of using backface culling." image="/img/playgroundsAndNMEs/divingDeeperMaterialsIntro7.webp"/>

Note that backface culling is one aspect of face culling: you can also perform frontface culling if you wish! Backface culling is much more commonly used than frontface culling, but in some cases you may want to enable frontface culling. To do so, set the material property _cullBackFaces_ to **false**. Note that you must always set _backFaceCulling_ to **true** to enable culling! _backFaceCulling_ is misnamed for historical reasons, and in order to maintain backward compatibility, we cannot rename it to _faceCulling_.

## WireFrame

Every material can be displayed as a wireframe by setting the wireframe accessor of the material to true.

```javascript
materialSphere1.wireframe = true;
```

The output of enabling wireframe mode on the material is to display the wireframe using a line renderer, while still displaying the specific properties defined by the material including color, specularity, and alpha. Note that wireframe mode ignores the value for _backFaceCulling_ on the material because there is no backface any longer. Instead, lines are rendered on mesh edges and the concept of "back face" is no longer applicable. 

![wireframe mode on a sphere](/img/how_to/Materials/04-3.webp)

<Playground id="#T8KESP" title="Wireframe Example" description="Simple example enabling wireframe on a material." image="/img/playgroundsAndNMEs/wireframeMode.webp"/>

This will work with any material available in Babylon.js such as _StandardMaterial_, _PBRMaterial_, and even _NodeMaterial_. This is because the accessor is inherited from the _Material_ class, enabling every material in the engine to take advantage of it. Controlling the appearance of the wireframe is done through the material's parameters. 

![Making the wireframe red and emissive](/img/how_to/Materials/wireframe_red.webp)
<Playground id="#T8KESP#1" title="Styling a wireframe" description="Styling the wireframe to be red." image="/img/playgroundsAndNMEs/wireframe_red.webp"/>

However, the thickness of the line is predetermined by the line renderer in screen space which renders the line at the same thickness regardless of the distance from the line to the camera. This means that the wireframe will dynamically update the thickness so that it won't cease to render if the camera gets too far away.

### Rendering WireFrame Over Material
If it is necessary to render a wireframe over an existing material, the way to achieve this is by cloning the mesh and assigning a material to it that has _wireframe_ enabled. Since the wireframe renders in screen space, depth sorting is not an issue and the wireframe will always render on top of the visible parts of the mesh. The wireframe can be occluded by other meshes in the scene, but will not be occluded by an identical mesh that shares the same world position as the wireframe mesh.

This enables scenarios where blending materials and wireframes is necessary. In the example below, two _NodeMaterials_ are used to create the layer effect blending between wireframe over a solid color to the material's base color. The gradient for the interpolation is based on the distance from a pixel to the world origin and the same value is passed to both the _NodeMaterial_ for the mesh and the _NodeMaterial_ for the wireframe. In the case of the wireframe, this gradient is setting the alpha value of the material rather than interpolating between two different colors, which makes the wireframe appear to blend into the original material base color. This is the power of leveraging _NodeMaterial_ to drive the look of the wireframe of a mesh.

![Blending wireframe with material color](/img/how_to/Materials/wireframe_blending.webp)

<Playground id="#PKJCS5" title="Blending wireframe" description="Using node material to blend wireframe" image="/img/playgroundsAndNMEs/wireframe_blend.webp"/>

## Local File Access

An important thing to remember is that, for security reasons, web browsers don't allow local files to be accessed from 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 used to simulate bumps and dents on a rendered surface. These are created by making 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 methods of doing this.

![Image Bump Map](/img/how_to/Materials/bump.webp)

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 with another image, as shown below.

![Bump Example](/img/how_to/Materials/bump_spheres.webp)

## Creating a Bump Map Example

Just add a _bumpTexture_ to an existing material.

```javascript
const myMaterial = new BABYLON.StandardMaterial("myMaterial", scene);
myMaterial.bumpTexture = new BABYLON.Texture("PATH TO NORMAL MAP", scene);
```

<Playground id="#20OAV9#8621" title="Using Bump Maps" description="Simple example of applying bump maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials1.webp" isMain={true} category="Materials"/>

## Inverting Bumps and Dents

Use _invertNormalMapX_ and/or _invertNormalMapY_ on the material.

```javascript
const 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 transparency. The following PNG image with
a transparency gradient can be applied to a material using _opacityTexture_.

![Opacity Map](/img/how_to/Materials/degrade_map.webp)

The same gradient is then applied to the material, as shown in the image below.

![Opacity Material](/img/how_to/Materials/degraded_plane.webp)

<Playground id="#20OAV9#8622" title="Using Opacity Maps" description="Simple example of applying opacity maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials2.webp"/>

## Applying Opacity

Add an _opacityTexture_ to an existing material.

```javascript
const 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 and 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.webp)

To tile an image, 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#8623" title="UV Tiling and Offset" description="Simple example of UV tiling and offset." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials3.webp"/>

## 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.webp)

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.webp)

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.webp)
![Bump - With detail map](/img/how_to/Materials/detailmap_bump_with.webp)

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 contain albedo (diffuse), normal, and roughness (for PBR materials only) channels, arranged this way (following the **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.webp)

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 example.

You can take advantage of this to make the detail map effects fade when the texture gets minimized on screen: you simply need to create mip maps that fade to the 0.5 value after a given level.

For eg, you can decide that the fading effect begins at mip level 3, and is fully achieved at level 5, meaning that from level 3 to 5 the R/G/B/A values are interpolated from their initial values to the 0.5 value, then at level 5 and onward all values are set to 0.5, disabling the detail map effects completely. If you use the mip map levels this way, don't forget to activate trilinear interpolation!

You can enable detail mapping this way:

```javascript
myMaterial.detailMap.texture = new BABYLON.Texture("textures/detailmap.png", scene);
myMaterial.detailMap.isEnabled = true;
```

You can control the strength of the albedo/normal/roughness detail effects this way:

```javascript
myMaterial.detailMap.diffuseBlendLevel = 0.1; // between 0 and 1
myMaterial.detailMap.bumpLevel = 1; // between 0 and 1
myMaterial.detailMap.roughnessBlendLevel = 0.25; // between 0 and 1
```

You can use this PG to experiment with detail maps:
<Playground id="#5NS7A2#4" title="Using Detail Maps" description="Simple example of applying detail maps." image="/img/playgroundsAndNMEs/divingDeeperMoreMaterials4.webp"/>

![Detail map PG](/img/how_to/Materials/detailmap_pg.webp)



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.webp)

To define a multi-material, you first have to define some standard materials:

```javascript
const material0 = new BABYLON.StandardMaterial("mat0", scene);
material0.diffuseColor = new BABYLON.Color3(1, 0, 0);
material0.bumpTexture = new BABYLON.Texture("normalMap.jpg", scene);

const material1 = new BABYLON.StandardMaterial("mat1", scene);
material1.diffuseColor = new BABYLON.Color3(0, 0, 1);

const material2 = new BABYLON.StandardMaterial("mat2", scene);
material2.emissiveColor = new BABYLON.Color3(0.4, 0, 0.4);
```

Then you can create a multi-material in order to gather them all:

```javascript
const multimat = new BABYLON.MultiMaterial("multi", scene);
multimat.subMaterials.push(material0);
multimat.subMaterials.push(material1);
multimat.subMaterials.push(material2);
```

You are now able to assign the multi-material to your mesh:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("Sphere0", { segments: 16, diameter: 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 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 covers the entire mesh.

To define multiple submeshes, you just have to use this code:

```javascript
sphere.releaseSubMeshes();
const 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)
- The index of the first index to use and the index count
- The parent mesh

So with the code above, you can use the first material on the top part of the sphere, the second material on the middle part and the last material on the bottom part of the sphere.

<Playground id="#2Q4S2S#268" title="Sphere With Multi-Material" description="Simple example of applying a multi-material to a sphere." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial1.webp"/>

## With Merged Meshes

When you [merge meshes](/features/featuresDeepDive/mesh/mergeMeshes) together, setting the final parameter _multiMultiMaterial_ to true, the `subMeshes` array is automatically created with all of the merging meshes' subMeshes. Each subMesh's material is also included in the resulting mesh's new multiMaterial. This feature ignores the parameter (`subdivideWithSubMeshes`).

<Playground id="#INZ0Z0#59" title="Multi-Material With Merged Meshes 1" description="Simple example of applying a multi-material to merged meshes." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial2.webp"/>

When you [merge meshes](/features/featuresDeepDive/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 multiMaterial's `subMaterials` array contains materials in the order [mat1, mat2], then for the subMesh from `mesh2` to have material `mat2`, you need to set

```javascript
mergedMesh.subMeshes[1].materialIndex = 1;
```

<Playground id="#INZ0Z0#6" title="Multi-Material With Merged Meshes 2" description="Simple example of applying a multi-material to merged meshes." image="/img/playgroundsAndNMEs/divingDeeperMultiMaterial2.webp"/>



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/divingDeeperNormalMaps1.webp"/>

What are the normal map formats, and what do 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.webp)

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.webp)

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.webp)

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.webp)

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.webp)

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.webp)

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 solution.

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 solution. 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 solution, 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.webp)

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.webp)

It is a deep topic made more complex by multiple file formats with their own conventions, but there are tools available in the engine to switch to whatever you need. In a way, we can say that while Babylon.js was originally designed around DirectX principles, it has since become more convention-agnostic, as there are plenty of tools available to make your assets work correctly as 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#408" title="Parallax Mapping Example" description="Simple example of using parallax mapping in your scene." image="/img/playgroundsAndNMEs/divingDeeperParallaxMapping1.webp"/>

![parallax mapping example](/img/how_to/Materials/parallax-mapping.webp)

## What is Parallax Mapping?

Parallax Mapping is an algorithm that, based on a height map, applies an offset to the material's textures in order to accentuate the relief of the geometry's surface.

While this technique is independent of Normal Mapping (a.k.a. Bump), it is often used in conjunction with it. The simple reason is that the height map needed to perform Parallax Mapping is often encoded in the Alpha channel of the Normal Map texture. (A diffuse texture is required to use parallax mapping).

There are many techniques based on the Parallax Mapping principle, and Babylon.js supports two of them.

## Parallax Mapping

The core algorithm performs an offset computation for the texture UV coordinates based on a height map. This algorithm is very fast, and you can almost think of it as being free if you are already using Bump.

## Parallax Occlusion Mapping (POM)

While traditional Parallax Mapping computes the offset based on one sample of the height map, the Occlusion version loops to sample the height map many times in order to reach a more precise location for what the computed pixel 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)
 - [NodeMaterial](/typedoc/classes/BABYLON.NodeMaterial)

In Babylon.js, parallax mapping is treated as an extension of Normal Mapping, so to benefit from the former, you have to enable the latter. 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 haven't assigned a **bumpTexture**.
 - **useParallaxOcclusion**: enables Parallax Occlusion, when setting this property, you must also set **useParallax** to true.
 - **parallaxScaleBias**: applies a scaling factor that determines which "depth" the height map should represent. A value between 0.05 and 0.1 is reasonable in Parallax, and you can reach 0.2 using Parallax Occlusion.

### Using Parallax Mapping in Node Material

When setting up a node material to use Parallax Mapping, use a `PerturbNormal` block attached to a `PBRRoughnessMetallic` block and ensure you have wired values to both the parallax scale input and the parallax height input. This will enable the node material to utilize the parallax occlusion method from our standard shaders.

![parallax mapping set up for nodematerial](/img/how_to/Materials/nme_parallaxMapping.webp)

### Using Parallax Occlusion Mapping in Node Material

When setting up a node material to use Parallax Occlusion Mapping (POM), you follow much of the same setup as above. Wire a `PerturbNormal` block to the `PBRRoughnessMetallic` block to start. This time, however, you want to check the box for Parallax Occlusion Mapping on the `PerturbNormal` block. Doing this will disable the inputs for both parallax scale and parallax height on the `PerturbNormal` block, as these contribute to the other method. In the case of Parallax Occlusion Mapping, your height texture needs to be authored into the alpha channel of your normal texture in the same way as when using Standard Material and PBR Material. There is no connection that needs to be made to use the alpha of the attached normal texture for parallax occlusion, as the checkbox tells the engine to look in the attached normal texture's alpha channel for the height texture.

![parallax occlusion mapping set up for nodematerial](/img/how_to/Materials/nme_parallaxOcclusionMapping.webp)







## 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 and working on a dwarf pub with multiple large, "old school" wooden tables. With classic 2D texturing, you have three 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, ensuring that they each look different

None of these choices seems ideal.

Enter **procedural textures**.

Procedural texturing is a way to programmatically create a texture. There are two 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](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) in the case of Babylon.js). That means the code generating the texture is executed by the GPU, not the CPU (that is to say, not in JavaScript code). This has a strongly positive performance impact.

Procedural textures can be generated:

- Only once, to create a texture that is then cached

- Every 1, 2, 3, 4, or more frames 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 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
const cylinder = BABYLON.MeshBuilder.CreateCylinder("mycylinder", { height: 7, diameterTop: 2, diameterBottom: 2, tessellation: 12, subdivisions: 1 }, scene);
```

Then, you need to create a StandardMaterial:

```javascript
const material = new BABYLON.StandardMaterial("material", scene);
```

Now create a WoodProceduralTexture object, passing a name, the size of the generated texture, and the scene.

```javascript
const texture = new BABYLON.WoodProceduralTexture("texture", 1024, scene);
```

You are almost set! All you need to do now is associate the texture with the material as a diffuseTexture, for instance (or emissiveTexture, specularTexture, or any other texture), 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
const 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/divingDeeperProceduralTexture1.webp"/>

## 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/procedural-textures`
- With a direct reference to: https://cdn.babylonjs.com/proceduralTexturesLibrary/babylonjs.proceduralTextures.min.js

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

All standard procedural textures can be used in the same way, but they each have specific properties:

- [BrickProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/brick)
- [CloudProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/cloud)
- [FireProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/fire)
- [GrassProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/grass)
- [MarbleProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/marble)
- [RoadProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/road)
- [WoodProceduralTexture](https://doc.babylonjs.com/toolsAndResources/assetLibraries/proceduralTexturesLibrary/wood)



This method is only available when creating a mesh using the _MeshBuilder_ method.

The following meshes have identifiable faces when created with the _MeshBuilder_ method: box, cylinder, extruded polygon, and polyhedron. They have the _faceUV_ and _faceColors_ parameters in their options. This means that each face 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 file.

If you are concerned about the orientation of the images on the faces, it may be necessary to use different orientations for the separate images in the source file.

Using these methods on the meshes above means 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 for `MeshBuilder.CreateBox` is as follows:

- side 0 faces the positive z direction
- side 1 faces the negative z direction
- side 2 faces the positive x direction
- side 3 faces the negative x direction
- side 4 faces the positive y direction
- side 5 faces the negative y direction

<Playground id="#ICLXQ8#1" title="Individual Face Numbers Example" description="Simple example of applying individual face numbers to a cube." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials1.webp"/>

## 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 Atlas](/img/how_to/apply-material-to-faces/spriteAtlas.webp)

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) uses the whole texture atlas. In this case, there are six sprites in a row and four in a column, so divide the image into a grid and mark the axes as below.

![Sprite Atlas with Grid](/img/how_to/Materials/spritesheet1.webp)

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, so the bottom left is `(2 * 1/6, 1 * 1/4) = (2/6, 1/4)` and the 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
const mat = new BABYLON.StandardMaterial("mat", scene);
const 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 a `faceColors` array 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 mesh types 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
const columns = 6; // 6 columns
const rows = 4; // 4 rows

const faceUV = new Array(6);

for (let 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
const options = {
  width: 10,
  height: 3,
  depth: 5,
  faceUV: faceUV,
};

const box = BABYLON.MeshBuilder.CreateBox("box", options, scene);

const mat = new BABYLON.StandardMaterial("mat", scene);
const texture = new BABYLON.Texture("URL of Texture Atlas", scene);
mat.diffuseTexture = texture;
box.material = mat;
```

<Playground id="#ICZEXW#812" title="FaceUVs Example" description="Simple example of using FaceUVs to create a box." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials2.webp"/>

You do not have to map all the faces. If you want just one face with an image, map only that face.

Take the alien sprite on row 0 and column 3 and just map this sprite to face 1.

```javascript
const columns = 6; // 6 columns
const rows = 4; // 4 rows

const faceUV = new Array(6);

faceUV[1] = new BABYLON.Vector4(3 / columns, 0, (3 + 1) / columns, 1 / rows);
```

<Playground id="#ICZEXW#813" title="Specific Sprite to Single Face" description="Simple example a single sprite on a single face of a box." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials3.webp"/>

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
const columns = 6; // 6 columns
const rows = 4; // 4 rows

const faceUV = new Array(6);

//set all values to zero
for (let 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#814" title="Sprite On Face With Other Blank Faces" description="Simple Example of applying a sprite to the side of a box with the other box faces blank." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials4.webp"/>

Of course, you can do this with one, two, three, four, or five box faces.

If you want to add some all-over color to the box, just add a _diffuseColor_ to your material.

<Playground id="#ICZEXW#815" title="Sprite on Box Face With Material Color" description="Simple Example of applying a sprite to the side of a box with applied material color." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials5.webp"/>

You can also use one texture atlas to apply two different images from the same sheet onto two different meshes.

<Playground id="#ICZEXW#816" title="Sprites Sheet On Faces of 2 Meshes" description="Simple Example of applying a sprite sheet to the faces of different meshes." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials6.webp"/>

Looking more closely at the face images around the sides, you will see that some images are rotated by 90 degrees relative to others. Unfortunately, if you want all images around the sides to have the same orientation, this is not possible by adjusting only the UV coordinates. What can be done by swapping coordinates is covered next, followed by a method that adjusts the texture atlas to orient the 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.webp)

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 lines, 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#817" title="Understanding Face Orientation With Sprites" description="Simple Example of applying sprites to face mesh reflection." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials7.webp"/>

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
const 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:

- 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 rotated around the x axis and these sides become vertical, the applied image textures will keep 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 to 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 to the side with the number given.

In the following playground, the two boxes at the top do not use the wrap parameter, and the results are backward compatible with earlier versions of Babylon.js. The lower boxes have wrap set to true.

<Playground id="#ICZEXW#4" title="Wrap Sprite Orientation" description="Simple Example of a wrap to orient a sprite on a mesh face." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials8.webp"/>

The next playground shows the use of non-default values for topBaseAt and bottomBaseAt.

<Playground id="#ICLXQ8#4" title="Wrap Top and Bottom Rotate" description="Simple Example of a wrap with top and bottom sprites rotated." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials9.webp"/>
<Playground id="#ICLXQ8" title="Wrap Cartoon Head" description="Simple Example of a wrap to produce a box with a cartoon head." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials10.webp"/>

### 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.webp)

and apply it to a cube to give the playground below

<Playground id="#ICZEXW#8" title="Default Image Rotation" description="Simple Example of the default image rotation on faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials11.webp"/>

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.webp)

resulting in the following playground

<Playground id="#ICZEXW#9" title="Aligning Images on Faces" description="Simple Example of aligning images by altering the sprite sheet." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials12.webp"/>

## Box - faceColors

For this, no material is needed.

Define a 6-element array _faceColors_ (one entry for each box face) and set the color of the faces you want.

```javascript
const 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
const options = {
  width: 10,
  height: 3,
  depth: 5,
  faceColors: faceColors,
};

const box = BABYLON.MeshBuilder.CreateBox("box", options, scene);
```

<Playground id="#ICZEXW#5" title="Different Colors on 2 Faces" description="Simple Example of applying different colors to 2 faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials13.webp"/>

These colors are BJS Color4-class values. The Color4 alpha values become active if you set `hasVertexAlpha = true` for the box.

<Playground id="#ICZEXW#6" title="Different Transparent Colors on 2 Faces" description="Simple Example of applying different transparent colors to 2 faces." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials14.webp"/>

## 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#818" title="Mixed Textures and Colors Per Face" description="Simple Example of applying different textures and colors per face." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials15.webp"/>

## 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 is 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.webp)

The label part has width 866 pixels and height 319 pixels.

So you need the tube surface to have the same height-to-width ratio.

When you create a cylinder with a default diameter of 1, 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 ratio of the image wrapped around the cylinder 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 image to correct the reflection of the image.

<Playground id="#VA2AC#3" title="Different Texture on Cylinder and Its Top" description="Simple Example of applying different textures to a cylinder's side and top." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials16.webp"/>

## Extruded Polygon

An extruded polygon has three surfaces: top, bottom, and extruded sides. Face 0 is the top, face 1 is the extruded sides, and face 2 is the bottom.

<Playground id="#RNCYVM#1352" title="Extruded Polygon with Different Textures on Sides and Top" description="Simple Example of applying different textures to an extruded polygon's sides and top." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials17.webp"/>

## Polyhedra

You can use a texture atlas with all polyhedra; however, without very careful consideration of the nature of the texture atlas, the results can look a little random.

<Playground id="#21QRSK#16" title="Polyhedra with Different Characters Per Face" description="Simple Example of applying different characters to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials18.webp"/>

Using each sprite as a texture rather than as part of a picture makes more sense.

<Playground id="#21QRSK#18" title="Polyhedra with Different Textures Per Face" description="Simple Example of applying different textures to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials19.webp"/>

Just colors work well.

<Playground id="#21QRSK#17" title="Polyhedra with Different Colors Per Face" description="Simple Example of applying different colors to faces of a Polyhedra." image="/img/playgroundsAndNMEs/divingDeeperFaceMaterials20.webp"/>



## The Problem

When the same texture is tiled many times across a large surface, the human eye picks up the repetition very quickly — what should look like a continuous patch of grass, sand, or rock turns into an obvious grid pattern. The screenshot below shows this: a 5×5 tiling of the same `grass.png` texture, with the grid clearly visible.

![Default tiling — repetition is visible](/img/how_to/Materials/textureRepetition_grass_none.webp)

Starting with Babylon.js v9.7.0, every material exposes a `textureRepetitionMode` property that can apply one of four repetition-breaking techniques to all the surface textures (albedo / diffuse, bump, ambient, specular, emissive, etc.) sampled by the material.

## Quick Start

```javascript
const mat = new BABYLON.PBRMaterial("mat", scene);
mat.albedoTexture = new BABYLON.Texture("textures/grass.png", scene);
mat.albedoTexture.uScale = 5;
mat.albedoTexture.vScale = 5;

// Enable hex tiling — a good default that works on most textures
mat.textureRepetitionMode = BABYLON.Constants.TEXTURE_REPETITION_HEX_TILING;
```

That single property change is enough to break the visible repetition.

## Available Modes

The property is a numeric enum on the `Constants` class. Modes are ordered by GPU cost (number of texture fetches per pixel):

| Constant | Fetches | Visual character |
|---|---|---|
| `TEXTURE_REPETITION_NONE` | 1 | Default tiling, no breaking. |
| `TEXTURE_REPETITION_NOISE_BLEND` | 3 | Two virtual offset patterns selected by a low-frequency noise lookup. Cheapest breaking mode. |
| `TEXTURE_REPETITION_HEX_TILING` | 3 | Hex-tile grid with per-tile rotation and luminance-weighted blending. Best visual quality for the cost. |
| `TEXTURE_REPETITION_TILE_RANDOMIZATION` | 4 | Per-tile random offset and mirror, blended at borders. |
| `TEXTURE_REPETITION_VORONOI_BOMBING` | 9 | Smooth Voronoi pattern with Gaussian-weighted blending. Highest quality. |

### Visual comparison

All shots below use the same UV scale, same camera, and same lighting.

| Mode | Grass | Rock |
|---|---|---|
| None | ![](/img/how_to/Materials/textureRepetition_grass_none.webp!300) | ![](/img/how_to/Materials/textureRepetition_rock_none.webp!300) |
| Noise blend | ![](/img/how_to/Materials/textureRepetition_grass_noiseBlend.webp!300) | ![](/img/how_to/Materials/textureRepetition_rock_noiseBlend.webp!300) |
| Hex tiling | ![](/img/how_to/Materials/textureRepetition_grass_hexTiling.webp!300) | ![](/img/how_to/Materials/textureRepetition_rock_hexTiling.webp!300) |
| Tile randomization | ![](/img/how_to/Materials/textureRepetition_grass_tileRandomization.webp!300) | ![](/img/how_to/Materials/textureRepetition_rock_tileRandomization.webp!300) |
| Voronoi bombing | ![](/img/how_to/Materials/textureRepetition_grass_voronoiBombing.webp!300) | ![](/img/how_to/Materials/textureRepetition_rock_voronoiBombing.webp!300) |

## Hex Tiling Parameters

The hex tiling mode (`TEXTURE_REPETITION_HEX_TILING`) is the only mode with user-configurable parameters. They are exposed as a single 4-component array, `material.textureRepetitionHexTilingParams`:

| Index | Parameter | Range | Default | Description |
|---|---|---|---|---|
| `[0]` | Rotation strength | 0..1 | 1.0 | How much each hex tile is rotated. 0 disables per-tile rotation. |
| `[1]` | Fall-off contrast | 0..1 | 0.6 | How much the local luminance affects the blending weight at tile borders. Higher values produce sharper transitions. |
| `[2]` | Exponent | 1..20 | 7.0 | Sharpness of the weight falloff between adjacent tiles. Higher values make tile boundaries more distinct. |
| `[3]` | Contrast | 0..1 | 0.5 | Boosts the blending contrast (0.5 = neutral, &gt;0.5 = higher contrast). |

```javascript
mat.textureRepetitionMode = BABYLON.Constants.TEXTURE_REPETITION_HEX_TILING;
mat.textureRepetitionHexTilingParams = [1.0, 0.6, 7.0, 0.5];
```

The other three modes have no user-configurable parameters.

## Materials Supported

The feature is implemented on the base `Material` class, but the actual shader work is done in:

- [`StandardMaterial`](/typedoc/classes/BABYLON.StandardMaterial) — affects `diffuseTexture`, `bumpTexture`, `ambientTexture`, `specularTexture`, `emissiveTexture`, `opacityTexture`, `lightmapTexture`.
- [`PBRMaterial`](/typedoc/classes/BABYLON.PBRMaterial) and `PBRBaseMaterial` subclasses — affects all surface textures including `albedoTexture`, `bumpTexture`, `metallicTexture`, `reflectivityTexture`, sheen, clear coat, anisotropy, iridescence, sub-surface, etc.
- [`OpenPBRMaterial`](/typedoc/classes/BABYLON.OpenPBRMaterial) — same coverage as PBR plus OpenPBR-specific layers (coat, fuzz, thin film, transmission, sub-surface).

The following textures are intentionally **not** affected, even when a non-default mode is active:

- `decalTexture` — decals are placed at specific positions, blending them across tiles would break that.
- `detailMap` (the detail texture plugin) — it is itself a tiling-breaking helper; running it through another tiling-breaking pass is counter-productive.
- The bump/parallax sampling for height (the `.w` channel of the bump texture used by parallax occlusion) — this read is structural, not surface color.
- Reflection / refraction / environment cube samplers.

## Live Demo

<Playground id="#HUOG6P#2" title="Texture Repetition Breaking — Interactive Demo" description="Drag the yellow line to compare original tiling (left) with the chosen breaking method (right)." image="/img/how_to/Materials/textureRepetition_grass_hexTiling.webp"/>

The demo lets you switch:

- **Material Type** — Standard, PBR, OpenPBR.
- **Texture Set** — grass, rock, or rocky ground (the rocky ground set's metalness/roughness map is only used by PBR / OpenPBR; Standard ignores it).
- **Repetition Mode** — applied only to the **right** side of the split.
- **UV Scale** — to see how the breaking holds up at different repetition densities.
- **Hex tiling parameters** — when hex tiling is selected.

Drag the yellow vertical line with the mouse to slide the comparison.

## Limitations

- **Normal maps with hex tiling**: per-tile UV rotation is applied to the lookup, but the sampled normal vectors are not rotated to match. This can cause subtle directional artifacts on normal-mapped surfaces under strong directional lighting. The other modes (which don't rotate UVs) are unaffected.
- **WebGL 1**: this feature is not supported on WebGL 1. The mode is silently forced to `TEXTURE_REPETITION_NONE` when the engine is WebGL 1.
- **Cost is per-pixel and per-texture**: every active surface sampler in the material is replaced. A PBR material with albedo + bump + metallic + AO running in hex tiling mode performs 3× sampling work for each of those four maps. Use the cheaper modes (Noise Blend) for distant surfaces or large screens.
- **Texture must be tileable**: the techniques break visible repetition, but they assume the source texture itself can be sampled outside the [0..1] UV range without seams. Use textures with `wrapU` / `wrapV` set to `WRAP_ADDRESSMODE` (the default).

## Inspector

The Inspector v2 exposes the property under a "Texture Repetition" section in the material properties pane, including the four hex tiling parameter sliders that appear when the hex tiling mode is selected.



If you want to display a video in your scene, the Babylon engine has a special texture for that. This special texture works similarly to other textures, with the exception of a few parameters. These parameters include video URLs (a URL array), the size of the video texture (256 here), the scene, and a final optional boolean that indicates whether 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/divingDeeperVideoTexture1.webp"/>

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);
```
Note: after loading the texture, the class sets the `wrapU` and `wrapV` properties to `WRAP_ADDRESSMODE`. If you wish to use another address mode, you need to add an observer to  `VideoTexture.onLoadObservable` and modify the properties in this observer.

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 the 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, and 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 the VideoTexture `autoPlay` setting 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 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.webp"/>

An event is also available to detect whether your browser is preventing autoplay because of its policy:

```javascript
texture.onUserActionRequestedObservable.add(() => {
    scene.onPointerDown = function () {
        videoTexture.video.play();
    };
});
```

If you wish to display a texture during load time, you can provide the URL of an image in the `poster` property of the settings. It will be displayed during loading or until the user interacts with the video.

## Web RTC

Starting with v2.6, we introduced support for WebRTC. You can now create a specific VideoTexture that 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 constrain 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. Fully releasing 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 for users who need to load and dispose of multiple VideoTextures over time.



## How To Use Materials

You can achieve a lot by applying the Babylon.js standard material to a mesh with a variety of textures. Beyond that, there is also a physically based rendering material that can give surfaces a more realistic appearance.



# Materials

Materials give your meshes color and texture. One material in Babylon.js can be used to cover as many meshes as you wish. Materials can be displayed as wireframes, scaled and offset across a mesh, made transparent, and blended. You can apply multiple materials to 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 appear more textured or bumpier, or make it reflect and refract? The first section shows you how.

Node materials allow you to create a material based on custom shaders but without having to deal with shader code.

The advanced section covers more technical aspects of materials and ways to customize them.


Using Materials

How To Use Materials

Coming next

Map Materials to Individual Mesh Faces

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

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.

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.

Texture Repetition

Hide visible texture tiling patterns on large surfaces with the textureRepetitionMode property.

Parallax Mapping

Learn all about using parallax mapping in Babylon.js.

Normal Maps

Learn all about normal maps in Babylon.js.

Introduction To Blend Modes

Learn blend modes and blending pixels in Babylon.js.

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.

HTML Textures

Render live HTML elements into a Babylon.js texture using the WICG HTML-in-Canvas API.

Fresnel Parameters

Learn fresnel parameters in Babylon.js.

KTX2 Compressed Textures

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

Introduction to Physically Based Rendering

Start learning about Physically Based Rendering in Babylon.js.

Using An HDR Environment For PBR

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

Mastering PBR Materials

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

OpenPBR

Read about the support of OpenPBR in Babylon.js and learn about its features.

Procedural Textures

Learn about procedural textures in Babylon.js.

Material Plugins

Create plugins to customize shaders of existing materials