 

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)







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.


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