
## 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 and 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 to describe arbitrarily complex shaders, OpenPBR has a fixed material structure. This saves valuable time because the structure is already designed (by gauging the most valuable material features to cover the majority of production needs), but 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       |



## Introduction

The highly recommended way to setup an environment texture is through an HDR ready file (either DDS or ENV) containing a cube texture with prefiltered MipMaps.

To load an HDR environment, you can use a [createDefaultEnvironment](https://doc.babylonjs.com/typedoc/classes/babylon.scene#createdefaultenvironment):

```javascript
scene.createDefaultEnvironment();
```

This will load the file [_environmentSpecular.env_](https://assets.babylonjs.com/environments/environmentSpecular.env) from _assets.babylonjs.com_.

To load a custom env texture, simply set the `scene.environmentTexture`:

```javascript
const hdrTexture = BABYLON.CubeTexture.CreateFromPrefilteredData("textures/environment.env", scene);
scene.environmentTexture = hdrTexture;
```

You can also use an option in `createDefaultEnvironment()`:

```javascript
scene.createDefaultEnvironment({
    environmentTexture: "texture-url.env"
}););
```

We are detailing below the two supported ways of creating such files.

As of 4.2 we now support prefiltering directly in the Sandbox!

.hdr files are easy to find on the web so it looks like the most convenient input for filtering.

## Creating a compressed environment texture using the Sandbox

As the generated DDS files can be relatively large (32Mb for a 512px wide file), we introduced in Babylon a special way to pack your texture. Here are the steps to follow to create the `.env` files used in Babylon.js:

- go to the [sandbox](https://sandbox.babylonjs.com/)
- drag &amp; drop a PBR scene file ([example](https://models.babylonjs.com/PBR_Spheres.glb))
- drag &amp; drop your .dds environmentTexture file ([example](https://playground.babylonjs.com/textures/environment.dds))
- open the Inspector, go to the Tools, and click on `Generate .env texture`

![inspector env texture tool](/img/how_to/Environment/inspector-generate-env-texture.png)

You can now download and use your `.env` environment, using this bit of code:

```
scene.environmentTexture = new BABYLON.CubeTexture("environment.env", scene);
```

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 will contain the diffuse information in a texture. This can help a lot with the rendering quality at the expense of a tiny big bigger file (about 10 more kb).

See [What is a .env (Tech Deep Dive)](#what-is-a-env-tech-deep-dive) part at the bottom of this page to know more.

## IBL Texture tool

In case you have a .hdr texture, you're able to use the [IBL Texture Tool](https://www.babylonjs.com/tools/ibl/) to convert it in an easy way to .env.

Just drag &amp; drop your .hdr file, wait a bit, and save the .env wherever you want.

## Directly use .hdr files

In case you want to directly use a .hdr file and are not able to prefilter it to a .env or a .dds from the sandbox or an external tool, you can do it at the moment your texture is loaded.

```javascript
const reflectionTexture = new BABYLON.HDRCubeTexture("./textures/environment.hdr", scene, 128, false, true, false, true);
```

This method will involve a small delay in the loading of the texture, due to the prefiltering being achieved on-the-fly. Therefore it is preferable to use .env or .dds files for optimal performance.
Please note that WebGL2 is required for prefiltering on-the-fly.

As sometimes you might even want to fully filter in realtime (for animated reflections for instance) you might want to have a look at [the reflection probes tutorial](/features/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 gives a lot more dynamicity to the output and can allow "true" hdr.
- The parameter `prefilterUsingCdf` can be used to generate the irradiance texture containing by relying on the HDR CDF data which helps a lot to get closer from Ray tracers.

![IBL Filters](/img/how_to/environment/iblFilters.png)

## Using a pure cube texture

![inspector env texture tool](/img/how_to/environment/inspector-generate-env-texture.png)

While using a .dds or .env cube texture is the best option, you may want to still rely on classic cube texture (mostly for size reason).
So, you can still do this as well:

```javascript
scene.environmentTexture = new BABYLON.CubeTexture("textures/TropicalSunnyDay", scene);
```

In this case you won't be able to get HDR rendering and some visual artifacts may appear (mostly when using glossiness or roughness).

## What is a .env (Tech Deep Dive)

The issue we are addressing with .env is the size and quality of our IBL Environment Textures. We decided to implement our custom packing to simplify sharing and downloading those assets. This file needs to work cross platform for an easy deployment hence why we are not relying directly on compressed textures.

We are then packing in one file (similar to DDS or KTX) a json manifest header, the polynomial information and all the faces of the mipmaps chain from the prefiltered cube texture in .png format (which compresses more than decently and decode really fast in all browsers.).

In order to keep an HDR support with png, we chose to rely on RGBD as it offers a better distribution of the value in the low range than RGBM by keeping the [0-1] range untouched knowing it is generally used more frequently. It is also less complex to decode at runtime than LogLUV when needed. It seems the like the best tradeoff for us.

RGBD also offers none to low transparency in the lower range preventing browser relying on premultiplication of alpha to loose data in the most visible area. We also introduced a special offset from the max range ensuring that we are not reaching problematic values of alpha in legacy browsers (when alpha is too close from 0 the color quantization is created unacceptable banding artifacts).

In WebGL2 browsers, we are unpacking the data to HalfFloat or FullFloat texture if supported to speedup the runtime and allow correct some interpolations.

The file is also packing the polynomials harmonics vs sphericals to match what Babylon is expected internally speeding up load time by not having to compute or transform them anymore.

As rendering to LOD or even copy to LOD of Half/Fulll float texture does not work consistently on WebGL1 based browser, we are unpacking in live the data in the fragment shader. As RGBD interpolation is not correct we ensured with different test cases that the generated visual artifacts were worth the transport gain. It looks ok in the sets of textures we have been testing.

As an example of result, we can now rely on 512px cube sized texture with around 3Mb of data vs 32 Mb for the unpacked version without noticing any blocking quality drops. This also speed ups our time to first frame by not requiring the compute of the polynomials anymore.
