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


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


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