

## Using a Files-Based Custom Procedural Texture
To use a files-based custom procedural texture, you need to create a folder containing at least 2 files:

- config.json
- custom.fragment.fx

The config file is a Javascript Simple Object Notation file containing 4 elements. Here is an example:

```javascript
    {
     "animate": false,
     "refreshrate": 0,
     "uniforms": [
      {
          "type": "float",
          "name": "dirtAmplifier",
          "value": "6.0"
      }
  ],
     "sampler2Ds": [
      {
          "sample2Dname": "dirt",
          "textureRelativeUrl": "textures/dirt.jpg"
      },
      {
          "sample2Dname": "grass",
          "textureRelativeUrl": "textures/grass.png"
      }
     ]
    }
```

The **animate** property indicates if a time value should be created and increased each time the fragment shader code is executed.

The **refreshrate** property is set to 0 if you want the texture to only render once. If set to 1, it will render every frame, 2 every two frames, etc.

**Uniforms** are the values that will be passed from the javascript code to the shader code. By setting them that way, you can allow the custom texture user to modify this value at runtime... to customize the texture. 

Uniforms can be of type:
 
- **float** (parameters : value)
- **Vector2** (parameters: x, y)
- **Vector3** (parameters: x, y, z)
- **Color3** (parameters: r, g, b)
- **Color4** (parameters: r, g, b, a)

**Textures2D** are 2D image files that are passed to the shader code as **sampler2D** variables. They can be read by the shader code and be used to create the final pixel color. You only need to provide a name and the relative path inside the folder.

The **custom.fragment.fx** file contains the GLSL code. The purpose of this wiki article is not to teach you how to create a fragment shader or how it works. You simply need to know that the code contained in your main function will be called once for each pixel to create on the texture. In this main function, you only know the coordinates of the current pixel in the final texture.

Here is a simple code which is setting all pixels to a specific gray.

```javascript 
    #ifdef GL_ES
    precision highp float;
    #endif
    
    void main(void) {
     vec3 color = vec3(0.9, 0.9, 0.9);
     gl_FragColor = vec4(color, 1.0);
    }
```
Gl_FragColor is the variable in which you put the color object you want the pixel to be.
Here is a more complex example using 2 samplers and mixing their color equally. 

```javascript
    #ifdef GL_ES
    precision highp float;
    #endif
    
    varying vec2 vPosition;
    varying vec2 vUV;
    
    uniform sampler2D grass;
    uniform sampler2D dirt;
    
    void main(void) {
     vec3 color = mix(texture2D(dirt, vUV).xyz, texture2D(grass, vUV).xyz, 0.5);
     gl_FragColor = vec4(color, 1.0);
    }
```
To use this custom texture, you need to make your folder available to your babylon.js html/javascript files and use a **CustomProceduralTexture** class instead of a standard one. The difference is only that you specify a new parameter which is the relative path to the folder containing the custom texture. Babylon.js will automatically read the config.json and custom.fragment.fx files and load everything for you.

```javascript
    var texture = new BABYLON.CustomProceduralTexture("texture", "./pathtotexture", 1024, scene);
```

## Using a ShaderStore for Shader Storage
You can also use the ShaderStore to write a shader inline and use it in a CustomProceduralTexture.
This can be done easily using the **BABYLON.Effect.ShaderStore** array : 

```javascript
BABYLON.Effect.ShadersStore["LinesPixelShader"] =
       "#ifdef GL_ES\n" +
       "precision highp float;\n" +
       "#endif\n\n" +
       "varying vec2 vUV; \n" +
       "void main(void) {\n" +
       " gl_FragColor = vec4(vUV.x,vUV.y,-vUV.x, 1.0);\n" +
       "}\n" +
       "";
```
Note that your shader name should be suffixed with **PixelShader** as the Procedural Texture shader is always a pixel shader. Babylon.JS will automatically understand it is a pixel shader.

To use this shader, you just have to create a CustomProceduralTexture and put the name of your shader in the store instead of the path to the files.

```javascript
var customProcText = new BABYLON.CustomProceduralTexture("customtext", "Lines", 1024, scene);
```
## Using a DOM Element for Shader Storage

Finally you can also use **DOM Elements** to store your shader. You just have to create a script tag in your HTML file like this:

```javascript
<script type="application/pixelShader" id="LinesPixelShader">
        #ifdef GL_ES
        precision highp float;
        #endif
        varying vec2 vUV; 
        void main(void) {
             gl_FragColor = vec4(vUV.x,vUV.y,-vUV.x, 1.0);
        }
</script>
```
To use it, you just have to create a simple object containing one property which is named **fragmentElement** and contains the id identifying the script DOM element.

```javascript
var linesShader = { fragmentElement: 'LinesPixelShader' };
var customProcText = new BABYLON.CustomProceduralTexture("customtext", linesShader, 1024, scene);
```

## Using Node Material to generate procedural texture

You can use NodeMaterial to generate the shaders for your procedural texture.
The code to generate it is very simple:
```
BABYLON.NodeMaterial.ParseFromSnippetAsync("#A7A3UB#1", scene).then((nodeMaterial) => {
    const proceduralTexture = nodeMaterial.createProceduralTexture(256);
});
```
Example: <Playground id="#8S19ZC#1" title="Node Material Procedural Texture Example 1" description="Simple example of creating a procedural texture using the node material editor." image="/img/playgroundsAndNMEs/divingDeeperCreateProceduralTexture1.jpg"/>

More here: [Creating Procedural Textures](/divingDeeper/materials/node_material/nodeMaterial#creating-procedural-textures)

<Youtube id="qqMuuSM7GvI"/>

**Note :** when using ShaderStore or DOM Element shader for custom procedural textures : the config.json file is not needed anymore and you can just use setFloat or setVector3 (and so on), and setTexture on the CustomProceduralTexture will give values and Sampler2D to the shader code.

Feel free to play with this scene here: <Playground id="#24C4KC#17" title="Node Material Procedural Texture Example 2" description="Simple example of creating a procedural texture using the node material editor." image="/img/playgroundsAndNMEs/divingDeeperCreateProceduralTexture2.jpg"/>


BABYLON.DepthRenderer is a tool used to generate depth texture (a texture that contains depth buffer and which can be used to read scene depth values).

Using it is pretty straightforward:

```
var renderer = scene.enableDepthRenderer();
```

Starting from there, the scene will fill for you the renderer with depth values. All active meshes (Meshes which are visible from the current camera point of view) are drawn by the DepthRenderer. 

**Warning: Transparent meshes are not drawn because they are not written to the depth buffer**

You can then use the texture associated with the renderer like any other textures by using ```getDepthMap()``` function:

```
var mat = new BABYLON.StandardMaterial("mat01", scene);
mat.emissiveTexture = renderer.getDepthMap(); 

```

If you want to disable the renderer, just call the following code:
```
scene.disableDepthRender();
```

As you can see, you can use the depth map associated with the DepthRenderer with any materials or post-processes.

**Note: By default, generated texture uses float components thanks to *WebGL OES_texture_float extension*. If this extension is not supported, Babylon.js reverts back to byte component which means less precision for depth values.**


## Materials and Vertices

BabylonJS allows you to create many meshes and apply material to them quite simply and in a range of ways.

Sometimes it may be useful to know more on how this is achieved. Any attempt to answer the question of how colours and textures are applied to a mesh must start with looking at the construction of a mesh.

Below is a simple wireframe cube which has 8 vertices:

![Wireframe](/img/how_to/Materials/box1.jpg)

The cube is constructed from 12 facets or triangles, each face having 2 facets.

The colour or texture for each facet is determined from those assigned to its vertices.

## Colours at Vertices

Assigning red to each of the vertices of the facet 3, 2, 6 results in a red facet:

![Red Facet](/img/how_to/Materials/redVert.jpg)

Assigning red to vertex 3, green to vertex 2 and blue to vertex 6 results in a graduated colour image:

![Graduated Facet](/img/how_to/Materials/gradVert.jpg)

## Textures at Vertices

Applying an image as a texture to the face 3, 2, 6, 7 means assigning image 
coordinates to each of the vertices; (0, 1) to vertex 3, (1, 1) to vertex 2, (1, 0) to vertex 6 and (0, 0) to vertex 7.

These are then used to map the image across the facets.

Of course with a mesh consisting of many vertices wrapping an image as texture around the mesh will mean each vertex being assigned a point on the image using fractional values as described in [custom meshes](/divingDeeper/mesh/creation/custom/custom#calculating-uvs).

## Issues with Adjoining Faces

The construction method given above will lead to problems should different colours or textures need to be applied to different faces 
since adjoining faces use the same vertex index. 

For example if face `3, 2, 6, 7` should be red and face `0, 3, 7, 4` should be green, it is not possible to assign both red and green to vertices 3 and 7.

Sharing vertex indices will also cause problems when wrapping an image around a mesh.

For example if the image above was to be wrapped around faces `3, 2, 6, 7` and `1, 2, 6, 5` and `0, 1, 5, 4` and `0, 3, 7, 4` it is not possible for vertex 3 to be assigned (1, 0) and (1, 1) nor for vertex 7 to be assigned (0, 0) and (1,0).

## Solutions for Adjoining Faces

There are two solutions both of which require additional facets:

1. **Inbetweens**

Replace a shared edges with a face. For example taking the shared edge 3, 7 and replacing with a face gives:

![Extra Face](/img/how_to/Materials/box2.jpg)

Now vertices 8 and 9 can be assigned green or (1, 1) and (1, 0) and so face `3, 2, 6, 7` can be red or have the start of the image and face `0, 8, 9, 4` can be green or have the end of the image with no conflict.

Of course facets `8, 9, 7` and `3, 7, 8` will have graduated fill or messed up images but by setting vertices 8 and 3 to have the same position and also 9 and 7 to have the same position the face `3, 7, 9, 8` disappears, the box appears to only have six faces and the adjoining faces have the colour or image wanted. 

Spheres, cylinders and other self joining meshes use this method.

2. **Separated Faces**

In this case each face has its own set of indices for its vertices, so each face can have a different material applied: 

![Individual Faces](/img/how_to/Materials/box3.jpg)

Again correct coincident positioning of vertices leads to a solid looking mesh. Think of the mesh as being made of individual faces that are brought together to form a whole.

Some meshes created with the MeshBuilder method use this approach, allowing the faceColors and faceUV options.


Pretty much every 3D programmer runs into depth buffer issues sooner or later. 
This is especially true when creating outer-space scenes where object distances can be in light years.

In such cases, the linear depth buffer (the default) can generate glitches when distances start reaching big numbers. 
In short, the depth values are proportional to the reciprocal of Z. This gives good precision near the camera, but a little off in the distance.

You can read an interesting analysis by Brano Kemen on this blog: http://www.gamasutra.com/blogs/BranoKemen/20090812/85207/Logarithmic_Depth_Buffer.php

To help with this issue, you may want to use a better Z-value distribution: the logarithmic depth buffer where Z = log(C*z + 1) / log(C*Far + 1) * w

StandardMaterials can enable the logarithmic depth buffer if the browser supports *GL_EXT_frag_depth* extension.

To enable it, just use this code:
```
material.useLogarithmicDepth = true;
```

If the extension is not supported, Babylon.js will revert to linear depth buffering.



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.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](/api/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.



The Raw Texture feature is incredibly simple, but unbelievably powerful! It allows you to create a texture from raw data! This type of thing is perfect for creating procedural textures on the fly. Let's take a look at how to create a simple RBG texture from scratch.

Creating a Raw RBG Texture can be done using the following construction method:

```javascript
new BABYLON.RawTexture.CreateRGBTexture(data, width, height, scene);
```

data: This is the raw data that you'll use for the rbg values of each pixel of your texture. The data needs to be an 8-bit array...specifically a javascript 'uint8array.'

width: The desired width of the texture you'd like to create.

height: The desired height of the texture you'd like to create.

scene: Your Babylon scene.

Here's a small demo of it working. Check out line 29 in this playground: <Playground id="#3TM0BZ" title="Raw Texture Noise Terrain Example" description="Simple example of using noise data to generate an rgb texture, used as a height map to displace a mesh for a terrain effect." image="/img/playgroundsAndNMEs/divingDeeperRawTexture1.jpg"/>

In this case, random noise is being generated, converted into a Uint8Array and that is then used to create a Raw RGB Texture.

Here is a video explanation, diving a little futher into how this demo uses the raw texture.

<Youtube id="YKqXcrWliww"/>

## Diving Deeper

Of course, creating an RBG texture on the fly is only the tip of the iceberg. There's a LOT more you can do with Raw Texture, such as creating RGBA, Luminance, Alpha, and Luminance Alpha textures. 

For more detail, be sure to check out the full API documentation on Raw Texture [here](/api/classes/babylon.rawtexture).


Some complex scenes will require a large amount of textures. A single material will often use three or more! To simplify the loading process it can be convenient to package the textures from multiple materials into a series of images. The trade-off will be that each texture will be scaled to a set size and might cause some desegregation, there are also WebGL limits to take into consideration as well. The packer will create a set of "frames" for each unique material and its required texture channels. The result produces one image for each channel that is used by the materials that are being packed. The process then modifies a target UV# from the meshes passed into the constructor, making them match the frame of the texture sets. The system assumes textures are 1:1 ratio (square).

Create a TexturePacker series by calling:

```javascript
let pack = new BABYLON.TexturePacker(name, targetMeshes, options, scene);
```

There are some limitations that you should consider. These include texture size limits, transparencies, and refection/refraction materials. You can find more information here: <Playground id="#TQ408M" title="Creating A Texture Package" description="Simple example of creating a texture package." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage1.jpg"/>

-   <Playground id="#TQ408M" title="Texture Packer Example 1" description="Simple example of using a texture packer in your scene." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage2.jpg"/>

Create a TexturePacker by calling:

```javascript
let pack = new BABYLON.TexturePacker(name, targetMeshes, options, scene);
pack.processAsync().then(success).catch(error);
```

-   name:string, Name of the Texture Pack.
-   targetMeshes:`Array<AbstractMesh>`, Array of meshes to use as material sources.
-   options:any, Basic object with argument parameters
-   scene:Scene, The scene that everything is scoped to.

The options argument has a few parameters you can use to tweak the result of the texture packing.

-   map:`Array<string>`, An array that contains the names of the channels to pack on the materials if they exist. `Default = [ 'ambientTexture', 'bumpTexture', 'diffuseTexture', 'emissiveTexture', 'lightmapTexture', 'opacityTexture', 'specularTexture' ]`
-   uvsIn:number, The target UV channel to use when creating the frames. `Default = BABYLON.VertexBuffer.UVKind`
-   uvsOut:number, The target UV channel to modify on the targetMeshes. `Default = BABYLON.VertexBuffer.UVKind`
-   layout:number, Defines the layout of the packer(LAYOUT_STRIP, LAYOUT_POWER2, LAYOUT_COLNUM). `Default = TexturePacker.LAYOUT_STRIP;`
-   colnum:number, If using LAYOUT_COLNUM will define the number of columns to use. `Default = 8;`
-   frameSize:number, The base size of the frames before padding is added. `Default = 256;`
-   paddingMode:number, Defines the padding style of the packer (SUBUV_WRAP, SUBUV_EXTEND, SUBUV_COLOR). `Default = TexturePacker.SUBUV_WRAP;`
-   paddingColor:Color3|Color4, Custom color of the padding if paddingMode SUBUV_COLOR. `Default = new Color4(0, 0, 0, 1.0);`
-   paddingRatio:number, Ratio of the amount of padding to add to the frames. `Default = 0.0115;`
-   fillBlanks:boolean, Toggle to full blank cell when a material does not use that channel. `Default = true;`
-   customFillColor:string, css color string for what color to fill the blank frames. `Default = 'black';`
-   updateInputMeshes:boolean, Toggle to have the packer automatically update the input meshes to the new packer frames and channels. `Default = true;`
-   disposeSources:boolean, Toggle to dispose the source textures after they are packed. `Default = true;`

For PBR materials you will need to change the map to reflect the channels you want to target. The Environment map should be handled separately.

In order to ensure that the packing process does not lock your thread you will have to start the compilation process with

```javascript
pack.processAsync().then(success).catch(error);
```

Having all interactions with your pack happening in the success callback on the returned promise. See the below playgrounds for examples.

-   <Playground id="#TQ408M#6" title="Texture Packer Example 2" description="Simple example of using a texture packer in your scene." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage2.jpg"/>

Downloading the pack is simple! When initializing the package through both a JSON load or naturally like in the above mentioned constructor, a Promise Object is created.
In order to assure that the textures are all packed and ready to go we call any interactions with the texture pack inside the success callback of the `then` method.

```javascript

pack.processAsync().then(
    //Success
    ()=>{
        pack.download( type, ?quality);
    }
)
```

You can tell the downloaded to change between jpeg and png image types depending on if you need an alpha channel. Due to the fact that the images are stored as base64 you should avoid using png unless absolutely necessary. You can always download both types and then manually mix and match inside the JSON file.

-   <Playground id="#TQ408M#7" title="Texture Packer Download Example" description="Simple example of changing between jpeg and png depending on alpha channel." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage2.jpg"/>

## Loading From JSON

To load from a downloaded package is easy! First create a blank Texture Package.

```javascript
let pack = new BABYLON.TexturePacker("", [], {}, scene);
```

Then simply call the loadFromJSON method, with JSON file as a string and then the same success/error promise callback structure as the processAsync.

```javascript
pack.updateFromJSON(jsonString).then(success).catch(error);
```

-   <Playground id="#TQ408M#9" title="Texture Packer Load Example" description="Simple example of using the texture packer loader in your scene." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage3.jpg"/>
-   <Playground id="#96CDLA" title="PBR Texture Packer Load Example" description="Simple example of loading a PBR packed texture into your scene." image="/img/playgroundsAndNMEs/divingDeeperCreateTexturePackage4.jpg"/>



This article has been written to help you understand how things are drawn on screen, and how transparency is handled in BabylonJS. Feel free to contribute in whatever way seems fit to you!

## General Considerations

A general rule of thumb in real-time 3D rendering is that drawing several overlapping opaque objects is always easier than non-opaque ones. This is due to the fact that opaque objects are compatible with the use of a depth buffer, and thus no specific order is required when rendering them.

A depth buffer is a surface using the same dimensions as the screen, and holding for every pixel the following information: how far from the camera was the last pixel drawn here. With this information, we can draw as many objects as we want and always be sure that we will never draw something that was supposed to be hidden by another object. BabylonJS offers access to this information with a special DepthRenderer object.

Rendering objects without a depth buffer would require resorting to an old-school technique called [*Painter's Algorithm*](http://en.wikipedia.org/wiki/Painter's_algorithm), which is extremely simple: draw further objects first. Sky, then backdrop, etc. all the way to foreground objects. This is basically ordering objects by distance from camera (a.k.a. depth), and clearly not enough for most cases.

Testing against a depth buffer during render is a very common technique, simple to implement and performance-inexpensive. However, things get more complicated for non-opaque objects, as a depth buffer can't be used anymore (since these objects don't completely hide what's behind them).

This is what a depth buffer looks like for a scene which contains only opaque meshes:
![Opaque only meshes](/img/resources/transparency_meshes_rendering/opaque-depth-buffer.jpg)


## Rendering Order

## General Order

Before actually drawing meshes on the screen, BabylonJS puts them in the following categories, which are presented in the order in which they are drawn:
1. **Depth pre-pass meshes**

2. **Opaque meshes**

3. **Alpha tested meshes**

4. **Sprites** (handled by SpriteManager)

5. **Particles** (handled by ParticleSystem)

6. **Alpha blended meshes**, sorted by depth (= distance to camera)

Categories 4 and 5 should be self-explanatory, we won't discuss them further.

## Rendering Groups

Renderable objects can be organized into rendering groups, which act as layers. Layers are rendered in ascending order by ID, starting with the default one (which has the ID of 0). Within each rendering group, the "General Order" above will also be used.

To use rendering groups, you simply need to set the property `.renderingGroupId` on the objects you want to put in other layers than the default one.

This property exists on meshes, particle systems and sprite managers.

By default, there are 4 rendering groups in total, meaning that the only valid IDs are 0, 1, 2 and 3. This can be increased by setting the static property `BABYLON.RenderingManager.MAX_RENDERINGGROUPS` to the max ID you'd like (ex. set to 8 to support 7 rendering groups).

## Alpha Index

Meshes have another property that has an influence on the rendering order: `.alphaIndex`

By default, this property is set to `Number.MAX_VALUE`, which is the highest value that a numerical variable can hold (around 1.79E+308).

Unlike opaque and alpha-tested meshes, the BabylonJS rendering engine sorts alpha-blended meshes by depth before drawing them on screen (see below). The `.alphaIndex` property allows you to override this sorting, as one mesh which has a lower alpha index than another will *always* be rendered before it, regardless of their respective depth.

To phrase it more simply: **alpha-blended are sorted *first* by alpha index, and *then* by depth (distance to camera).**

Keep in mind that this property works only for alpha-blended mesh, and has absolutely no effect for opaque and alpha-tested ones.

*Note: this property can be manually set on meshes in 3DS Max with the BabylonJS exporter plugin.*

## Opaque or Transparent?

How your meshes are categorized may be very important for the final aspect of your scene. Let's take a closer look at the way categories 1 to 4 are defined.

## Depth pre-pass meshes

The depth pre-pass meshes define an additional rendering pass for meshes. During this pass, meshes are only rendered to depth buffer. The depth pre-pass meshes are not exclusive. A mesh can have a depth pre-pass and an opaque or alpha blend pass. To enable the depth pre-pass for a mesh, just set `mesh.material.needDepthPrePass = true`.
The goal is either to optimize the scene by rendering meshes to the depth buffer to reduce overdraw or to help reducing alpha blending sorting issues.

## Opaque Meshes

These will be the easiest to render: their polygons are fully drawn on screen with their colors and textures. A depth buffer will be used to make sure nothing is drawn over something that is closer to the camera.

# Alpha Tested Meshes

Same as opaque meshes, except that some parts of these meshes can be defined as completely transparent. Alpha test means that each pixel of the mesh can be either opaque (and then drawn on screen and in the depth buffer) or transparent, which means the pixel is completely discarded. Although very efficient, this type of render usually produces aliased borders and does not allow for smooth transparency effects.

By default, a pixel is considered transparent if its alpha value is < 0.4, and opaque if not. For the `StandardMaterial` and `PBR` materials, you can change the `0.4` value by updating the `mesh.material.alphaCutOff` property.

## Alpha Blended Meshes

These meshes have translucent parts that may have an alpha value of 0.0 (completely transparent) to 1.0 (completely opaque). Their color is blended with what's behind them to reflect that. These meshes are sorted by depth, based on the center of their bounding sphere. This does not prevent some problems when several alpha-blended meshes overlap.

Also, note that backface culling is pretty much obligatory for alpha blended meshes, otherwise polygons from the front and the back of the objects will be garbled (unless you use a depth pre-pass)

This is what a depth buffer looks like for a scene that contains each of those type of meshes:
![All kinds of meshes](/img/resources/transparency_meshes_rendering/alpha-depth-buffer.jpg)

*In this scene, the sphere is alpha tested, the base blocks are opaque and the pillars are alpha blended. As you can see, the alpha blended meshes are **not** written to the depth buffer!*

## Categorizing meshes

The following list will help you understand which categories your meshes will be put into. For more information on each of the properties mentioned here, take a look at the [Materials tutorial](/start/chap2/face_material).

**Alpha blended meshes:**

* Any mesh that either has :
  * the property `hasVertexAlpha` set to true (automatically set for exported meshes if vertices have individual alpha (transparency) values)
  * `mesh.visibility` value < 1
* In case of a mesh using `StandardMaterial`, if it either has:
  * `material.alpha` property < 1
  * an opacity texture defined
  * the opacity Fresnel effect active
  * a diffuse texture with `hasAlpha = true` and `useAlphaFromDiffuseTexture = true`
* In case of a mesh using a PBR material, if it either has:
  * `material.alpha` property < 1
  * an opacity texture defined
  * an albedo texture with `hasAlpha = true` and `useAlphaFromAlbedoTexture = true`
* In case of another type of material, if the material's `.needAlphaBlending()` function returns `true`

**Alpha tested meshes:**

* In case of a mesh using `StandardMaterial`, if it has:
  * a diffuse texture with the property `.hasAlpha` set to `true`
* In case of a mesh using a `PBR` material, if:
  * the sub surface module does not disable alpha blending
  * AND an albedo texture is defined with the property `.hasAlpha` set to `true`
* In case of another type of material, if the material's `.needAlphaTesting()` function returns `true`

Notes:
  * alpha testing is linked to the diffuse/albedo texture: to enable it, you must set the `.hasAlpha` property of the diffuse/albedo texture to `true` even if all you are interested in is to apply alpha testing to the opacity texture for eg. Alternatively, you can override the `Material.needAlphaTesting()` method and return `true` if you want alpha testing to be enabled:
    * `myMat.needAlphaTesting = () => myMat.opacityTexture !== null;`
  * for the standard material:
    * if `transparencyMode` (see next section for details about this property) is `null`, the alpha test is applied only on the alpha value read from the diffuse texture
    * if `transparencyMode` is not `null`, the alpha test is applied near the end of the pipeline, when all alpha contributions have been taken into account (vertex alpha, opacity texture alpha, fresnel alpha). Note however that the computation is applied **BEFORE** the visibility property of the mesh is factored in!
  * for the PBR material:
    * the alpha test is applied after the contributions from the albedo / vertex alpha / opacity texture have been factored in

**Opaque meshes:**

* Any mesh that does not fit into one of the above categories

Occasionally, you may have some of your meshes falling into the wrong category, e.g. an alpha tested mesh unnecessarily marked as alpha blended, or a mesh staying opaque when it shouldn't. This will give you weird glitches, which can sometimes be very annoying. You should refer to this article to check how your meshes and materials properties are set.

You're welcome to use this example to experiment on the different things explained here: <Playground id="#1PHYB0#81" title="Transparency Rendering Example" description="Simple example to experiment and understand how transparency is handled." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering1.jpg"/> Pressing F9 will switch between normal render and depth buffer render.

It's important to note that these categories are evaluated from top to bottom, so if a mesh is considered as an alpha blended mesh, it can't be alpha tested at the same time, which is something you may need/want to do nonetheless! Enter the `transparencyMode` property.

## The transparencyMode property

This is a property on `StandardMaterial` and `PBR` materials. It exists for PBR materials since they were introduced, and since v4.1 for `StandardMaterial`.

As you may see above, categorizing a mesh depends on a number of properties and it is not always easy to infer the right category. The `transparencyMode` property can help in that matter, as well as enabling alpha test + alpha blend modes simultaneously.

By default, it is `null` and everything works as described above. The other values it can take are:

| Value | Description |
|------ | ----------|
| Material.MATERIAL_OPAQUE| No transparency mode, Alpha channel is not use| 
| Material.MATERIAL_ALPHATEST | Alpha Test mode, pixels are discarded below a certain threshold defined by the alpha cutoff value|
| Material.MATERIAL_ALPHABLEND | Pixels are blended (according to the alpha mode) with the already drawn pixels in the current frame buffer|
| Material.MATERIAL_ALPHATESTANDBLEND | Pixels are blended (according to the alpha mode) with the already drawn pixels in the current frame buffer. They are also discarded below the alpha cutoff threshold to improve performances|

If `transparencyMode` equals:
* Material.MATERIAL_OPAQUE. Mesh will always be opaque, there will be no alpha blending nor alpha testing whatever the other properties you modify, **EXCEPT** if you set `mesh.visibility` < 1, in which case alpha blending is automatically turned on.
* Material.MATERIAL_ALPHATEST. Mesh will only be alpha tested (as long as you set the `hasAlpha` property of the diffuse/albedo texture to `true`), not alpha blended whatever the other properties you modify, **EXCEPT** if you set `mesh.visibility` < 1, in which case alpha blending is automatically turned on **AND** alpha testing is disabled
  * a difference between standard and PBR materials is that for PBR materials the alpha channel of the albedo texture is still used even if `useAlphaFromAlbedoTexture` is set to `false`, which is different from the standard material where the alpha channel of the diffuse texture is not used if `useAlphaFromDiffuseTexture` is set to `false`
* Material.MATERIAL_ALPHABLEND. Mesh will only be alpha blended and not alpha tested
* Material.MATERIAL_ALPHATESTANDBLEND. Mesh will be both alpha tested and alpha blended
  * a difference between standard and PBR materials is that for PBR materials the alpha channel of the albedo texture is still used even if `useAlphaFromAlbedoTexture` is set to `false`, which is different from the standard material where the alpha channel of the diffuse texture is not used if `useAlphaFromDiffuseTexture` is set to `false`

You're welcome to use this example to experiment on the different values of `transparencyMode` for both the standard and PBR materials: <Playground id="#TMDNDM" title="Transparency Modes Example" description="Simple example to experiment with different transparencyMode values." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering2.jpg"/>

## Things To Do And Not To Do

- Make sure your alpha blended meshes do not intersect, as this will inevitably lead to render glitches.
- Avoid having heavily-stretched alpha blended meshes (i.e. large planes); since the center of its bounding sphere is used for depth sorting, doing this may result in a mesh being sorted as far away from the camera but actually closer to many other meshes.
- Use alpha test as much as possible; this may look perfect for a pixel art style, or if the transparent parts boundaries are straight horizontal or vertical lines.
- To get rid of jagged edges on your alpha tested meshes, use anti-aliasing for your scene ([FxaaPostProcess](/divingDeeper/postProcesses/usePostProcesses#fxaa)); when using anti-aliasing, you can even disable the built-in smoothing of WebGL when creating the engine object:

```javascript
engine = new BABYLON.Engine(canvas, false); // built-in smoothing will be disabled
```

This may help you with visible seams between meshes and other similar issues.

- Do not forget to enable backface culling with alpha blended meshes!
- Use rendering groups to have better control over the order in which your meshes are displayed. These are especially useful if you know that some meshes will be above others 100% of the time (for example, an overlayed UI drawn on top of the scene).
- A mesh's `alphaIndex` property can be very useful as well, since they allow you to override the depth sorting of alpha-blended meshes. Also this property does not suffer from the same limitation as Rendering Groups (4 layers at most), and only has an effect on alpha-blended meshes.
- You can rely on `needDepthPrePass` to help fixing issues with self transparency.
- You can also use `separateCullingPass` on materials to force the engine to render the transparent objects in 2 passes: first the back faces and then the front faces. This can help a lot with self transparency.
- `twoSidedLighting` will not take effect if `separateCullingPass` is enabled. For double sided, transparent PBR materials you can instead use `forceNormalForward = true`, which will in practice result in the same effect. If used, you can set `twoSidedLighting = false` and `backfaceCulling = true` to slightly improve shader performance.
- To prevent both the cost of either `needDepthPrePass` or `separateCullingPass` if the sum of your alpha stays below 1.0, you can change the alphaMode of the material to either `Engine.ALPHA_PREMULTIPLIED` or `Engine.ALPHA_PREMULTIPLIED_PORTERDUFF` which prevent the need of ordering the triangles.

## Concave meshes and transparency

The transparent concave meshes render obviously with the same rules than explained before: <Playground id="#1PLV5Z" title="Concave Meshes And Transparency Example 1" description="Simple example of transparency and concave meshes." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering3.jpg"/>

For some reasons (example : camera flying from outside to inside a sphere), you may want to remove the backface culling in order to also render the back side of the mesh : <Playground id="#1PLV5Z#1" title="Concave Meshes And Transparency Example 2" description="Simple example of transparency and concave meshes with removed backface culling." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering4.jpg"/>

As you can notice, the transparency rendering rules may lead to some weird things making some parts of the mesh geometries visible.  
In this very case, an acceptable workaround would then be to enable the backface culling but to build the meshes as double sided with the parameter `sideOrientation` set to `BABYLON.Mesh.DOUBLESIDE`: <Playground id="#1PLV5Z#2" title="Concave Meshes And Transparency Example 3" description="Simple example of transparency and concave meshes with double sided meshes." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering5.jpg"/>

Other option will be to rely on depth pre-pass: <Playground id="#1PLV5Z#16" title="Concave Meshes And Transparency Example 4" description="Simple example of transparency and concave meshes with depth pre-pass." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering6.jpg"/>

At last, if you accept to spend some CPU cycles to get a correct self transparency, you can use the FacetData feature and enable the [facet depth sort](/divingDeeper/mesh/facetData#facet-depth-sort).

Example, depth sorted on the left, standard on the right: <Playground id="#FWKUY0#1" title="Concave Meshes And Transparency Example 5" description="Simple example of transparency and concave meshes with facet depth sort." image="/img/playgroundsAndNMEs/divingDeeperTransparencyRendering7.jpg"/>


## How Materials Work

Materials are an encapsulation on top of shaders. They provide a simple way to configure and share shaders. 

## Cache and compilation
The first time a material is created, an internal object named effect will be created. The effect is the host for the vertex and pixel (fragment) shaders.
These shaders have to be compiled by the GPU from plain text to GPU machine code.

The compilation step is a process that will be done synchronously on the main thread and thus could cause a bit of lag in the rendering.

As the process is a bit expensive, once compiled an effect will remain in memory until you dispose the engine. 

Everytime you will change a property of a material (like adding a texture or enabling an option), a new effect will be compiled unless an equivalent can be found in the cache.

## Improving User Experience

## Precompilation
By default, materials are compiled only when required. But you may want to precompile everything before running your rendering in order to get the smoother experience possible.

To do so, you can just prepare your material with: 

```
material.forceCompilation(mesh, function() {
    // Do something when material is compiled
});
```

For instance you could go through all your meshes and force compilation of all materials in order to get everything ready before the first frame.

## Non blocking textures
You also have the opportunity to flag textures as non blocking. By default, a material will not be able to render a mesh until its effect is compiled and all textures are loaded.

You can decide to still render your mesh even if textures are not loaded (The missing textures will be replaced by a 1x1 black texture). To do so, just call:

```
texture.isBlocking = false;
```




## How To use the Node Material with Particles

The Node Material Editor (aka NME) is a powerful tool that can be used to design shaders, [particles](/divingDeeper/materials/node_material/nodeMaterial#creating-particle-shaders), and [post processes](/divingDeeper/materials/node_material/nodeMaterial#creating-post-processes).

This article will help you set up a simple scene that will contain only a few lines of code, because all of the work will be done using our editors.

You can see the final result here: 

<Playground id="#RA18GJ" title="Node Material With Particles" description="Simple example of using the node material to create a particle fragment shader." image="/img/playgroundsAndNMEs/divingDeeperNodeMaterialParticle1.jpg"/>

## Setting up the scene

Setting up this scene is actually quite simple. We only need a scene, a camera, and a sphere to act as the particle emitter:

```
var scene = new BABYLON.Scene(engine);

var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, new BABYLON.Vector3.Zero(), scene);
camera.attachControl(canvas, true);

// Create a random emitter
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);
```

## Invoking the inspector to create our particle system

If you are executing this code in the [Playground](https://playground.babylonjs.com), you can simply click on the Inspector button inside the header bar.

If you are running the code on your own, you can call `scene.debugLayer.show()`.

Once there, you can right click on the "Particle Systems" node to create a new particle system:

![Create new system](/img/how_to/Particles/create_new_system.jpg)

The inspector will then let you play with all the parameters to define the system the way you want.

When you're done setting up your system, you can go to the Snippet zone and click "Save to Snippet Server":

![Save a snippet](/img/how_to/Particles/save_snippet.jpg)

This will give you a snippet ID that we will use later to load the particle system from our code.

You can see my setup in this playground:

<Playground id="#KST50Y" title="Particles Created In the Inspector" description="Simple example showing particles saved and loaded from the snippet server." image=""/>

## Working with the snippet server

The beauty of the snippet server is that it gives you a central place to store and update your particle system without having to modify your code.

We can use the [async/await pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) in our example to load a snippet asychronously. We can flag our function as `async` and then `await` a link to our particle system using the snippet ID:

```
var createScene = async function () {

    var scene = new BABYLON.Scene(engine);

    var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, new BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);

    // Create a random emitter
    var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);

    // Load the previously setup particle system (it was setup with the inspector)
    let system = await BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false);
    system.emitter = sphere;

    return scene;
};
```

As you can see, you can simply call `BABYLON.ParticleHelper.CreateFromSnippetAsync` to download your particle system from the snippet server.

If you do not want to (or cannot) use async / await, you can get the same outcome using Promises:

```
BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false).then(system => {
    system.emitter = sphere;
});
```

## Creating the node material for our particle system

We are going to use the same approach for the node material.

To setup our material, let's open the NME at [https://nme.babylonjs.com/](https://nme.babylonjs.com/)

The NME can be used for materials, particles and postprocesses. We'll switch to particles mode:

![Particle mode in NME](/img/how_to/Particles/nme_particle.jpg)

For this demo, I created a material where the particles are displayed with one texture when above ground (y = 0) and with another one below ground, with a smooth transition between the two. Here is the the shader I ended up with: <nme id="#345ATT#4" title="Node Material Particle Shader Example" description="Simple example of using the node material to create a particle fragment shader." image="/img/playgroundsAndNMEs/divingDeeperNodeMaterialParticle2.jpg"/>

![Demo shader](/img/how_to/Particles/demo_shader.jpg)

In a nutshell, I'm checking the particle position in world space and using a [smoothstep](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml) to output a value between 0 and 1, which is then used with a gradient between black and white. This color is then used to mix (lerp) between two textures.

Just like the particle system, you can save your creation to the snippet server and gets a snippet Id.

## Applying the material
The final step is to get that shader from the snippet server and use it with our particle system.

To do so, we will use the exact same approach as before:
```
// Load our node material
let nodeMaterial = await BABYLON.NodeMaterial.ParseFromSnippetAsync("#345ATT#4", scene);

// Apply it to the particle system
nodeMaterial.createEffectForParticles(system);
```

As you can see the NodeMaterial class has a handy function to apply it to a particle system.

And voila! 
The final code is extremely simple (thanks to async/await in particular):

```
var createScene = async function () {

    var scene = new BABYLON.Scene(engine);

    var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, new BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);

    // Create a random emitter
    var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);

    // Load the previously setup particle system (it was setup with the inspector)
    let system = await BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false);
    system.emitter = sphere;

    // Load our node material
    let nodeMaterial = await BABYLON.NodeMaterial.ParseFromSnippetAsync("#345ATT#4", scene);
    
    // Apply it to the particle system
    nodeMaterial.createEffectForParticles(system);

    return scene;
};
```

## Automatic updates

The best part is that our Playground can evolve automagically. If you open the main Playground (referenced at the beginning of this article), you can keep editing the particle system or the material, and your code will automatically update. This happens every time open the Inspector and use one of the editors. When you click "Save to Snippet Server", the system will be smart enough to work with the Playground and update the link for you:

![Automatic update](/img/how_to/Particles/auto-pg.gif)

You can see in the GIF that the Snippet ID for the particle system is updated to version #14 when I hit the save button.

Now that we know about that automatic update,there was another option to create the initial particle. You could have called the CreateFromSnippetAsync with a "__BLANK" id:

```
BABYLON.ParticleHelper.CreateFromSnippetAsync("_BLANK", scene, false).then(system => {
    system.emitter = sphere;
});
```

And then from there you could have used the Inspector to edit it (The inspector can replace the __BLANK with the right id later on)

Advanced Materials

Advanced Materials

Coming next

How Babylon.js Materials Work

Learn about how materials in Babylon.js work under the hood.

Materials and Vertices

Learn about the relationship between materials and vetices.

Creating Procedural Textures

Learn how to create your own procedural textures in Babylon.js.

Creating A Texture Package

Learn how to create your own texture package in Babylon.js.

Normal Maps

Learn all about normal maps in Babylon.js.

Transparent Rendering

Learn all about how transparency is handled in Babylon.js.

Creating Raw RBG Textures

Learn how to create raw rgb textures in Babylon.js.

Depth Renderer

Learn all about the depth renderer in Babylon.js.

Logarithmic Depth Buffer

Learn how to use the logarithmic depth buffer in Babylon.js.