
## How To Support Fog with ShaderMaterial

In order to support fog in your custom shaders, you will have to add some lines of code in your vertex and pixel shaders.

## Vertex shader

First, you need to declare a varying variable:

```
varying float fFogDistance;
```

Then you have to compute this value inside the shader:

```
fFogDistance = (view * worldPosition).z; // This is the distance of the vertex from the point of view of the camera (Camera space)
```

## Pixel shader

Next, you need to add the following code to be able to compute the fog accordingly to parameters sent by the scene:

```
#define FOGMODE_NONE 0.
#define FOGMODE_EXP 1.
#define FOGMODE_EXP2 2.
#define FOGMODE_LINEAR 3.
#define E 2.71828

uniform vec4 vFogInfos;
uniform vec3 vFogColor;
varying float fFogDistance;

float CalcFogFactor()
{
 float fogCoeff = 1.0;
 float fogStart = vFogInfos.y;
 float fogEnd = vFogInfos.z;
 float fogDensity = vFogInfos.w;

 if (FOGMODE_LINEAR == vFogInfos.x)
 {
  fogCoeff = (fogEnd - fFogDistance) / (fogEnd - fogStart);
 }
 else if (FOGMODE_EXP == vFogInfos.x)
 {
  fogCoeff = 1.0 / pow(E, fFogDistance * fogDensity);
 }
 else if (FOGMODE_EXP2 == vFogInfos.x)
 {
  fogCoeff = 1.0 / pow(E, fFogDistance * fFogDistance * fogDensity * fogDensity);
 }

 return clamp(fogCoeff, 0.0, 1.0);
}
```

Then, inside the shader, you have to use this function to get the fog color:

```
float fog = CalcFogFactor();
color.rgb = fog * color.rgb + (1.0 - fog) * vFogColor;
```

## Javascript

You then have to add the following code for the onBind callback of your ShaderMaterial:

```javascript
shaderMaterial.onBind = function (mat, mesh) {
  const effect = mat.getEffect();
  effect.setMatrix("view", scene.getViewMatrix());
  effect.setFloat4("vFogInfos", scene.fogMode, scene.fogStart, scene.fogEnd, scene.fogDensity);
  effect.setColor3("vFogColor", scene.fogColor);
};
```

And, you are done :)

Please find an example here: <Playground id="#11GAIH#17" title="Fog And Shader Material" description="Example of supporting fog with the shader material."/>



Here's what [Wikipedia](https://en.wikipedia.org/wiki/Compute_kernel) has to say about compute shaders:
> In computing, a compute kernel is a routine compiled for high throughput accelerators (such as graphics processing units (GPUs), digital signal processors (DSPs) or field-programmable gate arrays (FPGAs)), separate from but used by a main program (typically running on a central processing unit). They are sometimes called compute shaders, sharing execution units with vertex shaders and pixel shaders on GPUs, but are not limited to execution on one class of device, or graphics APIs.

Note that in Babylon.js this is a [WebGPU](/setup/support/webGPU) feature only (starting at v5.0), WebGL does not support compute shaders.

You can query the engine for compute shader support by doing:
```javascript
engine.getCaps().supportComputeShaders
```

## Creating a compute shader
Use the `ComputeShader` class to create a computer shader, much like you would use `ShaderMaterial` to create a material for some custom shader code:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "src": { group: 0, binding: 2 }
    }
});
```
`copyTextureComputeShader` is the shader code and `bindingsMapping` an object that maps an input variable name (from the shader source code) to its binding location: see below for more explanations.

Once you have created the compute shader instance, you can set the input values by using the appropriate methods (see [ComputeShader class](/typedoc/classes/babylon.computeshader)):
```javascript
cs1.setTexture("src", src);
cs1.setStorageTexture("dest", dest);
```

A compute shader can be executed by calling one of the `dispatch()` or `dispatchWhenReady()` methods.

## Types of variables passed to compute shaders
Variables you pass to a compute shader can be of the following types:
* **texture**. Use `ComputeShader.setTexture()` to pass a regular texture to the shader.
* **storage texture**. A storage texture is a texture you can write to from your compute shader. Note that you can't read from a storage texture, only write to it. If you wrote something in a storage texture and need to read from it in a shader, simply pass it as a regular texture. In Babylon.js, storage textures are created as regular textures but pass a special flag for the `creationFlag` parameter: `BABYLON.Constants.TEXTURE_CREATIONFLAG_STORAGE`. There are also two helper methods that you can use to create storage textures: `BABYLON.RawTexture.CreateRGBAStorageTexture()` and `BABYLON.RawTexture.CreateRStorageTexture()`. Use `ComputeShader.setStorageTexture()` to pass a storage texture to the shader.
* **uniform buffer**. It's a buffer you can create by instantiating the `UniformBuffer` class and that can be used to pass some constant values to the shader side (values that still can be updated in the course of your program - they are constants inside the shader). Note that you need to first create the layout of this buffer by calling the `addUniform` method **in the order the properties appear in the buffer in the shader code**! The last point is important as the layout you create must match the layout of the buffer as used in the shader code. Once you have created the layout, you can set some values through calls to the `updateXXX()` methods. Once you are ready to update the buffer on the GPU side, call `update()`. Use `ComputeShader.setUniformBuffer()` to pass a uniform buffer to the shader.
* **storage buffer**. This is an arbitrary buffer that you can use to read or write values. Use the `StorageBuffer` class to create such buffers. Use `ComputeShader.setStorageBuffer()` to pass a storage buffer to the shader.
* **sampler**. This is a custom texture sampler object that you can use to sample a texture. Use the `TextureSampler` class to create one and `ComputeShader.setTexturesSampler()` to pass a texture sampler to the shader. See the next section for more explanations about texture samplers.

## Shader language and input bindings
The compute shader must be written in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/), which is the shader language used by [WebGPU](/setup/support/webGPU).

As GLSL shaders can be stored in `ShaderStore.ShadersStore`, WGSL shaders can be stored in `ShaderStore.ShadersStoreWGSL` and you can pass the name of the key used to store the shader in this object to the `ComputeShader` constructor. You can also directly pass the shader code to the constructor (as done in the example above).

Browsers do not currently support reflection for WGSL shaders, meaning we are not able to automatically retrieve the binding and group values of the input variables, as seen here:
```wgsl
@group(0) @binding(0) var dest : texture_storage_2d<rgba8unorm, write>;
@group(0) @binding(1) var srcSampler : sampler;
@group(0) @binding(2) var src : texture_2d<f32>;
```
That's why you need to provide those bindings yourself when creating a new `ComputeShader` instance:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "src": { group: 0, binding: 2 }
    }
});
```
Note that for a (sampled) texture variable as `src` in the example above, you can instruct the system to automatically bind the sampler corresponding to the texture. To do that, you must declare the sampler with a binding value equal to the binding value of the texture minus 1 and you should pass `true` as the 3rd parameter of the `setTexture()` call (or don't pass anything, as `true` is the default value). In this case, you must **not** add this sampler in the `bindingsMapping` object.

If you don't need/want to auto-bind the sampler corresponding to a texture, you can instruct the system not to bind the sampler by passing `false` as the 3rd parameter to `ComputeShader.setTexture()`.

You can also bind your own sampler by creating one (see the [TextureSampler class](/typedoc/classes/babylon.texturesampler)) and use the `ComputeShader.setTextureSampler()` method:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "srcSampler": { group: 0, binding: 1 },
        "src": { group: 0, binding: 2 }
    }
});
const sampler = new BABYLON.TextureSampler().setParameters();
cs1.setTextureSampler("samplerSrc", sampler);
```
In that case, you must add this sampler in the `bindingsMapping` object.

## Examples

### Simple compute shaders

<Playground id="#3URR7V#183" engine="webgpu" title="Simple compute shaders" description="A simple example of creating various compute shaders" image="/img/extensions/webgpu/simpleComputeShader.png"/>

This PG creates 3 compute shaders:
* the first one is loading a texture and copying it into another texture by means of a compute shader. This texture is then applied on the ground. **Warning**: it is for demonstration purpose only, don't use this compute shader in real code, a simple copy buffer would be enough to achieve the same thing!
* the second one is clearing a texture with a constant value and applying it to the sphere. Once again, **don't use it in real code**! Note that we don't use `addUniform` to create the layout of the uniform buffer: when there's a single property in a uniform buffer, calling `updateXXX()` to set the value of the property will also create the layout.
* the third one is computing the multiplication of two matrices. It uses 3 storage buffers, 2 for the two input matrices and one for the result. The result buffer is then read and dumped to the console log. It is a direct port of [Get started with GPU Compute on the Web](https://developers.google.com/web/updates/2019/08/get-started-with-gpu-compute-on-the-web).

### Image Blur

<Playground id="#3URR7V#185" engine="webgpu" title="Blur compute shader" description="This example shows how to blur an image using a WebGPU compute shader" image="/img/extensions/webgpu/blur.png"/>

This is a direct port of the WebGPU sample [imageBlur](http://austin-eng.com/webgpu-samples/samples/imageBlur).

Note that in the sample we are calling `dispatchWhenReady()` for the first compute shader to be sure the compute effect is ready before going on, but for the next shaders we simply call `dispatch()` because as they are using the same shader code we are sure the effect will be ready (as it is the same one).

### Compute Boids

<Playground id="#3URR7V#186" engine="webgpu" title="Boids compute shader" description="A GPU compute particle simulation that mimics the flocking behavior of birds" image="/img/extensions/webgpu/boids.png"/>

This is a direct port of the WebGPU sample [computeBoids](http://austin-eng.com/webgpu-samples/samples/computeBoids).

It is a compute shader that updates two ping-pong buffers which store particle data. The data is used to draw instanced particles.

Note that it is using the (new in 5.0) `Mesh.forcedInstanceCount` property to set an instance count for a mesh that has no instances (`InstancedMesh`) but that we would like to render multiple times because we provide the appropriate vertex buffers manually.

As the storage buffers we use to compute the particle positions and velocities will be used as (instanced) vertex buffers, we must flag them as `BUFFER_CREATIONFLAG_VERTEX` at creation time (see the `new BABYLON.StorageBuffer(...)` calls in the code).

### Hydraulic erosion

<Playground id="#C90R62#16" engine="webgpu" title="Hydraulic erosion" description="Simulate erosion to make terrains look more natural" image="/img/extensions/webgpu/hydraulicErosion.png"/>

This is a port of the great project [Hydraulic-Erosion](https://github.com/SebLague/Hydraulic-Erosion): all credits to sebastlague@gmail.com!

The generation of the terrain and the simulation of the erosion is done by using two different compute shaders.

Note that this sample also works in WebGL2 where compute shaders are not available but you should be careful when setting the parameters: don't raise too much **Iterations**, **Radius**, **Max lifetime**, **Resolution** else you may stuck your browser as now the terrain generation and erosion processes are handled on the CPU side!

### Slime simulation

<Playground id="#GXJ3FZ#51" engine="webgpu" title="Slime simulation" description="Simulate organic-like agents" image="/img/extensions/webgpu/slime.png"/>

This is a port of the great project [Slime-Simulation](https://github.com/SebLague/Slime-Simulation): all credits to sebastlague@gmail.com!

The implentation in WGSL is a little less pretty than the HLSL one because at the time of this writing WebGPU does not support read/write textures, so we had to use a storage buffer for the `TrailMap` texture. That means we need some copy buffer to texture and texture to buffer functions and we have to do 4 reads from `TrailMap` instead of a single one when we need to get a `vec4` (see the code), which is likely less performant than its HLSL counterpart.

### Ocean demo

<Playground id="#YX6IB8#152" engine="webgpu" title="Ocean demo" description="Ocean simulation" image="/img/extensions/webgpu/ocean.png"/>

This is a port of the great project [FFT-Ocean](https://github.com/gasgiant/FFT-Ocean): all credits to Ivan Pensionerov (https://github.com/gasgiant)!

This sample uses a lot of compute shader runs: there are around 200-250 compute shaders running each frame! Use F8 to show/hide the GUI (after you click anywhere in the rendering area to give focus to the canvas) and WASD to move.



In case you are using an `ImageProcessingPostProcess` on your scene, or another post process that may use `ImageProcessingPostProcess` under the hood, like `MotionBlurPostProcess`, you will notice a slightly different color output in the final image, compared to what you want to output with `gl_FragColor`.

This is due to the fact that `ImageProcessingPostProcess` is expecting a linear color input, and therefore converts every pixel to gamma color space. If you want to read more about linear color space versus gamma color space, read [this](https://en.wikipedia.org/wiki/Gamma_correction).

## Fix my pixel shader

To spare you the reading, basically, your `gl_FragColor` is put to the power `1 / 2.2`, which we call a standard gamma transformation.

In order to counteract that, you should apply the opposite transformation, which is, in GLSL language :

```
#ifdef IMAGEPROCESSINGPOSTPROCESS
    gl_FragColor.rgb = pow(gl_FragColor.rgb, vec3(2.2));
#endif
```

Of course you want to only have this additional line in your shader in case an `ImageProcessingPostProcess` is active on your scene. That's why you must enclose this in a `#define` statement.

For convenience, we added a small shader include that does just that. You can add this after every `gl_FragColor` output :

```
#include<imageProcessingCompatibility>
```

Now you need to toggle that define based on the presence of an `ImageProcessingPostProcess`.
In your material code, it should resemble something like this :

```
defines.IMAGEPROCESSINGPOSTPROCESS = scene.imageProcessingConfiguration.applyByPostProcess;
```

And now, whether you have the post-process active or not, the color should be similar !

### Further Reading

You may have a similar problem if you want to use fog on your scene, with a custom shader material.

[Here](/advanced_topics/shaders/Fog+ShaderMat) is an helpful page to get your shaders to be fog-ready.

## Tonemapping

If you are using tonemapping on your materials, it can happen that your image appears brighter than expected. It means that several image processing are applied in your pipeline.

Some post processes internally use a prepass to get some information, and this prepass proceeds to some image processing itself. In that case, color can be processed several times which is incorrect. For instance, it can happen if you use `pbr.imageProcessingConfiguration = myImageProcessingConfiguration;` along with an `SSAO2RenderingPipeline`.

So if you notice that problem, try to manually deactivate the gamma transform from the prepass :

```
scene.enablePrePassRenderer().disableGammaTransform = true;
```

Colors should then behave as expected from your `imageProcessingConfiguration`.



## Introduction to Shaders in Babylon.js

A shader is a program processed by the Graphical Processing Unit (GPU) to produce a screen image by manipulating data to
produce individual pixels. The GPU is optimised, through parallel processing, to deal with these thousand of operations
in an extremely fast way.

## Suggested Pre-Reading

- How To:
  - [Custom Meshes](/features/featuresDeepDive/mesh/creation/custom/custom)
  - [Updating Vertices](/features/featuresDeepDive/mesh/creation/custom/updatingVertices)
- Resources:
  - [Normals in BJS](/features/featuresDeepDive/mesh/creation/custom/vertexNormals)

## An Overview

### Basic

To produce a Babylon.js scene, code is written in Javascript which the Babylon.js Engine processes and displays the result on screen.
The scene can alter through changes to the meshes, the lights or camera position. To show possible changes in a timely way the screen
display (frame) is re-drawn up to 60 frames per second.

Simplifying, the process is

- Scene Code is processed in the CPU by the BJS Engine Code to produce a Virtual 3D Model
- Virtual 3D Model is processed in the CPU by the BJS Engine Code to produce Shader GPU Code
- Shader GPU Code is processed by GPU to produce screen image.

For example the Babylon.js Engine takes this code

```javascript
const box = BABYLON.MeshBuilder.CreateBox("box", {}, scene);
```

and turns it into vertex data including positions, colors and normals.

The Babylon.js Engine creates the shader code for this data and is passed to the GPU.

### Custom

Much more than this as well as Scene Code you can write your own user Shader Code so that
the process becomes:

- Scene Code is processed in the CPU by the BJS Engine Code to produce a Virtual 3D Model
- Virtual 3D Model and User Shader Code is processed in the CPU by the BJS Engine Code to produce the Shader GPU Code
- Shader GPU Code is processed by GPU to produce the screen image.

## Types of Shader

Shaders are written in Graphics Library Shader Language (GLSL) and come in two parts:

1. Vertex Shader: this takes the data for each vertex and determines where on the screen the pixel for it will be displayed and its color.

2. Fragment Shader: this uses data from the Vertex Shader to determine the position and colour of the pixels to represent each facet of the mesh.

Fragment Shaders are sometimes refered to as Pixel Shaders.

![Shaders](/img/how_to/Shaders/shade1.jpg)

## Passing Variables

The vertex data for position, normal and uv coordinates are passed to the Vertex Shader as variables of category attribute.
User data can be passed to both the Vertex Shader and the Fragment Shader as variables of category uniform.
Data can be passed from the Vertex Shader to the Fragment Shader with variables of category varying.

A vital uniform variable to declare in the Vertex Shader is `worldViewProjection` as theBabylon.js Engine uses this to
pass scene 3D - 2D projection data to the Vertex Shader.

![Pass Variables](/img/how_to/Shaders/shade2.jpg)

## Variable types

All variables used in both shaders must be given a type and any numbers assigned to the variable must be consistent with its type.

For example:

```
int n = 2;
float r = 2.0;
```

The following example will throw an error:

```
float r = 2;
```

Some examples of types are

- `vec2`: a two-dimensional vector of floating-point numbers
- `vec3`: a three-dimensional vector of floating-point numbers
- `mat4`: a matrix with 4 columns and 4 rows floating-point numbers
- `sampler2D`: a 2D texture image

Since vertex positions need to be as accurate as possible all floating-point numbers should be set as having high precision.
This is done at the start of the code for each shader using:

```
precision highp float
```

## Built In Variables

The GLSL language has a number of built in variables. Two are vital to the operation of the two shaders and are always necessary:

| Variable     | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| gl_Position  | provide positional data for screen coordinates                  |
| gl_FragColor | provide colour data for the representation of a facet on screen |

## Built In Inputs

| Attribute | Type | Description                                            |
| --------- | ---- | ------------------------------------------------------ |
| position  | vec3 | pixel: vertex position / fragment: face pixel position |
| normal    | vec3 | pixel: vertex normal / fragment: face pixel normal     |
| uv        | vec2 | texture coordinate                                     |

&nbsp;

| Uniform             | Type  | Description                                            |
| ------------------- | ----- | ------------------------------------------------------ |
| world               | mat4  | mesh global transforming state (move + rotate + scale) |
| worldView           | mat4  | global view part of mesh                               |
| worldViewProjection | mat4  | global camera                                          |
| view                | mat4  | mesh local view part                                   |
| projection          | mat4  | local camera                                           |
| time                | float | per each frame                                         |

## Functions

Functions needed to be typed as do their parameters and have the form:

```
float NAME(typed parameters) {
	*code*
}
```

## Running Shader Code

Both the Vertex and the Fragment Shader are run from a function which must be called `main` and be of type `void` since it returns
no result. It must also must type the empty parameter list as void:

```
void main(void) {
	*code*
}
```

![Shader Code](/img/how_to/Shaders/shade3.jpg)

## Putting Shader Code in Babylon.js

Here are four ways of putting shader code into your scene:

1. Use [BabylonJS Create Your Own Shader (CYOS)](https://www.babylonjs.com/cyos/) and download a zip file
2. Write the Vertex and Fragment Shader Code into `<script>` tags
3. Write, save and import a Vertex and Fragment Shader file of type _.fx_ into your code
4. Use the [ShaderBuilder extension](https://github.com/BabylonJS/Extensions/tree/master/ShaderBuilder) of Babylon.js.

More details on this can be found below.

## Further Reading

## How To

- [Putting Shader Code in Babylon.js](/features/featuresDeepDive/materials/shaders/shaderCodeInBjs)
- [ShaderMaterial Object](/features/featuresDeepDive/materials/shaders/shaderMaterial)



## Putting Shader Code in Babylon.js

Here are four ways of putting shader code into your scene:

1. Use [BabylonJS Create Your Own Shader (CYOS)](https://www.babylonjs.com/cyos/) and download a zip file;
2. Write the Vertex and Fragment Shader Code into &ltscript&gt tags
3. Write, save and import a Vertex and Fragment Shader file of type .fx into your code;
4. Use the shaderBuilder extension ofBabylon.js.

Methods 1, 2 and 3 use [BABYLON.ShaderMaterial](/features/featuresDeepDive/materials/shaders/shaderMaterial) to pass data to the shaders.

## Babylon.js CYOS Download

This site allows you to write code for a Vertex Shader and a Fragment Shader and see the results on a variety of meshes.
Downloading a zip file produces a folder containing and index.html file and some image files for texture.

![CYOS Screen](/img/how_to/Shaders/cyos1.jpg)

The _index.html_ file contains the shader code in the correct format to apply as a material.

Within the HTML page the shader code becomes (in Javascript)

```javascript
BABYLON.Effect.ShadersStore["customVertexShader"] =
  "\r\n" +
  "precision highp float;\r\n" +
  "// Attributes\r\n" +
  "attribute vec3 position;\r\n" +
  "attribute vec2 uv;\r\n" +
  "// Uniforms\r\n" +
  "uniform mat4 worldViewProjection;\r\n" +
  "// Varying\r\n" +
  "varying vec2 vUV;\r\n" +
  "void main(void) {\r\n" +
  "    gl_Position = worldViewProjection * vec4(position, 1.0);\r\n" +
  "    vUV = uv;\r\n" +
  "}\r\n";

BABYLON.Effect.ShadersStore["customFragmentShader"] = "\r\n" + "precision highp float;\r\n" + "varying vec2 vUV;\r\n" + "uniform sampler2D textureSampler;\r\n" + "void main(void) {\r\n" + "    gl_FragColor = texture2D(textureSampler, vUV);\r\n" + "}\r\n";
```

the Javascript code to use the shader as a material is

```javascript
const shaderMaterial = new BABYLON.ShaderMaterial(
  "shader",
  scene,
  {
    vertex: "custom",
    fragment: "custom",
  },
  {
    attributes: ["position", "normal", "uv"],
    uniforms: ["world", "worldView", "worldViewProjection", "view", "projection"],
  },
);
```

and the Javascript code to set a texture to the material is

```javascript
const mainTexture = new BABYLON.Texture("amiga.jpg", scene);
shaderMaterial.setTexture("textureSampler", mainTexture);
```

and to use the material on a mesh is

```javascript
mesh.material = shaderMaterial;
```

Extracting the appropriate sections of Javascript code allows you to transfer them to your own scenes.

[Guide Example From CYOS Zip](https://babylonjsguide.github.io/examples/cyoszip.html)

This method can easily be used in the Playground.

<Playground id="#1OH09K#131" title="Playground Example From CYOS" description="Playground Example From CYOS"/>

## Shader Code in &lt;script&gt; Tags

In the _index.html_ file the Javascript code for the shaders is

```javascript
<script type="application/vertexShader" id="vertexShaderCode">
    #ifdef GL_ES
        precision highp float;
    #endif

    // Attributes
    attribute vec3 position;
    attribute vec2 uv;

    // Uniforms
    uniform mat4 worldViewProjection;

    // Normal
    varying vec2 vUV;

    void main(void) {
    gl_Position = worldViewProjection * vec4(position, 1.0);

    vUV = uv;
    }
</script>

<script type="application/fragmentShader" id="fragmentShaderCode">
    #ifdef GL_ES
        precision mediump float;
    #endif

    varying vec2 vUV;

    uniform sampler2D textureSampler;

    void main(void) {
        gl_FragColor = texture2D(textureSampler, vUV);
    }
</script>
```

the Javascript code to use the shader as a material becomes

```javascript
const shaderMaterial = new BABYLON.ShaderMaterial(
  "shader",
  scene,
  {
    vertexElement: "vertexShaderCode",
    fragmentElement: "fragmentShaderCode",
  },
  {
    attributes: ["position", "normal", "uv"],
    uniforms: ["world", "worldView", "worldViewProjection", "view", "projection"],
  },
);
```

[Guide Example From Script](https://babylonjsguide.github.io/examples/scriptcode.html)

## Shader Code in fx Files

Save your code in two files, one for the Vertex Shader and one for the Fragment Shader.

These files **must** be in the same folder as your index.html page and the names of the files **must** follow this format

COMMON_NAME.vertex.fx

COMMON_NAME.fragment.fx

The Javascript code to use the shader as material becomes

```javascript
const shaderMaterial = new BABYLON.ShaderMaterial("shader", scene, "./COMMON_NAME", {
  attributes: ["position", "normal", "uv"],
  uniforms: ["world", "worldView", "worldViewProjection", "view", "projection"],
});
```

**Note**: `./` is necessary before the `COMMON_NAME`

It is also possible to access the fx files from an URL by giving the full address of the URL,
provide CORS is enabled for them.

[Guide Example From Import](https://babylonjsguide.github.io/examples/importcode.html)

## Shader Includes

When building shaders sometimes you have parts of your code that will be reused between multiple shaders. This is usually things like reused uniforms, functions, structs etc. A powerful method that users have at their disposal is to accomplish this task is the

```javascript
BABYLON.Effect.IncludesShadersStore["includeName"] = "...";
```

Already loaded in the includes are all the common shader elements for babylons StandardMaterial, PBR Materials, ProceduralTextures and more. See the github [https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/ShadersInclude](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/ShadersInclude) for a complete list of shader includes packaged with BJS.

Additionally you can add anything you want to the IncludesShadersStore pre or post compilation of the scene. To access these includes simply call:

```glsl
#include<includeName>
```

In the appropriate section of your shader code to have them injected into your shader when it is compiled [see example](https://www.babylonjs-playground.com/#0MAYNY).

## Shader Builder

This is an extension toBabylon.js. Copy and save the [source code](https://github.com/BabylonJS/Extensions/blob/master/ShaderBuilder/Babylonx.ShaderBuilder.js) for the extension and add as

```javascript
<script src="Babylonx.ShaderBuilder.js"></script>
```

The Shader Builder engine needs to be initialised

```javascript
BABYLONX.ShaderBuilder.InitializeEngine();
```

The format for writing a ShaderBuilder is **fluent coding** and it deals with attributes andBabylon.js uniforms automatically.  
An example for the shader code used in 1 to 3 above would be

```javascript
mesh.material = new BABYLONX.ShaderBuilder().Map({ path: "textures/amiga.jpg" }).BuildMaterial(scene);
```

[Guide Example using ShaderBuilder](https://babylonjsguide.github.io/examples/basiccodeSB.html)

This method can be used in the Playground. However it does require the loading of the ShaderBuilder Javascript file and an `onLoad`
function before it can be called.

<Playground id="#NCY1Q#36" title="Playground Example Using ShaderBuilder" description="Playground example using shaderbuilder."/>



## ShaderMaterial

The ShaderMaterial object has the necessary methods to pass data from your scene to the Vertex and Fragment Shaders and returns a material that can be applied to any mesh. This returned material effects how the mesh will look based on the code in the shaders.

It is called by

```javascript
const myShaderMaterial = new BABYLON.ShaderMaterial(name, scene, route, options);
```

- `name`: a string, naming the shader
- `scene`: the scene in which the shader is to be used
- `route`: the route to the shader code in one of three ways:

  1. object: `{ vertex: "custom", fragment: "custom" }`, used with `BABYLON.Effect.ShadersStore["customVertexShader"]` and `BABYLON.Effect.ShadersStore["customFragmentShader"]`
  2. object: `{ vertexElement: "vertexShaderCode", fragmentElement: "fragmentShaderCode" }`, used with shader code in `<script>` tags
  3. object: `{ vertexSource: "vertex shader code string", fragmentSource: "fragment shader code string" }` using with strings containing the shaders code
  4. string: `"./COMMON_NAME"`, used with external files _COMMON_NAME.vertex.fx_ and _COMMON_NAME.fragment.fx_ in _index.html_ folder.

- `options`: object containing attributes and uniforms arrays containing their names as strings.

An example:

```javascript
const myShaderMaterial = new BABYLON.ShaderMaterial("shader", scene, "./COMMON_NAME",
    {
        attributes: ["position", "normal", "uv"],
        uniforms: ["world", "worldView", "worldViewProjection", "view", "projection", "time", "direction" ],
        samplers: ["textureSampler"],
        defines: ["MyDefine"]
        needAlphaBlending: true,
        needAlphaTesting: true
});
```

**Note**: that's the exhaustive list of available attributes, uniforms.

Any attribute in the Vertex Shader code **must** appear in the `attributes` array.

The uniform `worldViewProjection` **must** be declared in the Vertex Shader as type `mat4` and **must** be in the `uniforms` array.

Attributes and uniforms named in the arrays and not used in the shader code are ignored.

if your shader code contains #define values, you can specify the ones you want to activate in the `defines` array.

Uniforms assigned to textures in the shader code must be present in the samplers array, all other uniforms must be present in the uniforms array.

Textures are passed, for example, as

```javascript
const amigaTexture = new BABYLON.Texture("amiga.jpg", scene);
myShaderMaterial.setTexture("textureSampler", amigaTexture);
```

where `textureSampler` has been declared as a uniform of type `sampler2D` in the shader code.

Other uniforms are passed, for example, as

```javascript
myShaderMaterial.setFloat("time", 0);
myShaderMaterial.setVector3("direction", BABYLON.Vector3.Zero());
```

the set method depending on the type passed.

## Troubleshoot

In some specific cases when you use post-processes, you might notice a slightly brighter color output than what you implemented in your shader.

Read [this](/features/featuresDeepDive/materials/shaders/image_processing) if you want to know how to fix it.



## Shaders

In this section, we'll dive into the crazy, wonderful, beautiful world of GPU shaders. In short, a shader is a set of instructions handed to the GPU. From ocean caustics to tree bark, from alien teleporters funhouse reflections, shaders are your one-stop shop for creating compelling, advanced visual effects in real time!


## Introduction

As of v5.0 Babylon includes a Material Plugin system, which allows customization of an existing material with custom shader code. This adds a lot of flexibility, since one can easily modify the behavior of existing materials with special effects without having to rewrite the entire shader code, in a simple and reusable way.

This is incredibly useful and powerful, since materials can be changed at runtime and have effects that were previously only possible with complex multi-pass renderings or postprocessing.

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

## Basic example

Let's start with an example: suppose you want an object to be rendered in black and white. All you want is to change the end of its shader, converting the final fragment color to grayscale. To do that you create a material plugin modifying that part of the shader code.

```javascript
/**
 * Extend from MaterialPluginBase to create your plugin.
 */
class BlackAndWhitePluginMaterial extends BABYLON.MaterialPluginBase {
  constructor(material) {
    // the second parameter is the name of this plugin.
    // the third one is a priority, which lets you define the order multiple plugins are run. Lower numbers run first.
    // the fourth one is a list of defines used in the shader code.
    super(material, "BlackAndWhite", 200, { BLACKANDWHITE: false });

    // let's enable it by default
    this._enable(true);
  }

  // Also, you should always associate a define with your plugin because the list of defines (and their values)
  // is what triggers a recompilation of the shader: a shader is recompiled only if a value of a define changes.
  prepareDefines(defines, scene, mesh) {
    defines["BLACKANDWHITE"] = true;
  }

  getClassName() {
    return "BlackAndWhitePluginMaterial";
  }

  getCustomCode(shaderType) {
    if (shaderType === "fragment") {
      // we're adding this specific code at the end of the main() function
      return {
        CUSTOM_FRAGMENT_MAIN_END: `
                    float luma = gl_FragColor.r*0.299 + gl_FragColor.g*0.587 + gl_FragColor.b*0.114;
                    gl_FragColor = vec4(luma, luma, luma, 1.0);
                `,
      };
    }
    // for other shader types we're not doing anything, return null
    return null;
  }
}
```

To actually use this plugin, you need to register it with a factory function. This factory can also associate the plugin instance to the material, so we can easily access it later.

```js
BABYLON.RegisterMaterialPlugin("BlackAndWhite", (material) => {
  material.blackandwhite = new BlackAndWhitePluginMaterial(material);
  return material.blackandwhite;
});
```

You can see the final code in action in the PlayGround: <Playground id="#GC63G5#16" title="Basic example" description="Basic material plugin example"/>

## More complex plugins

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

Let's take a look at a more involved example, which is not enabled by default but has proper enable/disable controls as well.

```js
class ColorifyPluginMaterial extends BABYLON.MaterialPluginBase {
  // any local variable definitions of the plugin instance.
  color = new BABYLON.Color3(1.0, 0.0, 0.0);

  // we can add an enabled flag to be able to toggle the plugin on and off.
  get isEnabled() {
    return this._isEnabled;
  }

  set isEnabled(enabled) {
    if (this._isEnabled === enabled) {
      return;
    }
    this._isEnabled = enabled;
    // when it's changed, we need to mark the material as dirty so the shader is rebuilt.
    this.markAllDefinesAsDirty();
    this._enable(this._isEnabled);
  }

  _isEnabled = false;

  constructor(material) {
    // the fourth parameter is a list of #defines in the GLSL code
    super(material, "Colorify", 200, { COLORIFY: false });

    this._varColorName = material instanceof BABYLON.PBRBaseMaterial ? "finalColor" : "color";
  }

  // we use the define to enable or disable the plugin.
  prepareDefines(defines, scene, mesh) {
    defines.COLORIFY = this._isEnabled;
  }

  // here we can define any uniforms to be passed to the shader code.
  getUniforms() {
    return {
      // first, define the UBO with the correct type and size.
      ubo: [{ name: "myColor", size: 3, type: "vec3" }],
      // now, on the fragment shader, add the uniform itself in case uniform buffers are not supported by the engine
      fragment: `#ifdef COLORIFY
                    uniform vec3 myColor;
                #endif`,
    };
  }

  // whenever a material is bound to a mesh, we need to update the uniforms.
  // so bind our uniform variable to the actual color we have in the instance.
  bindForSubMesh(uniformBuffer, scene, engine, subMesh) {
    if (this._isEnabled) {
      uniformBuffer.updateColor3("myColor", this.color);
    }
  }

  getClassName() {
    return "ColorifyPluginMaterial";
  }

  getCustomCode(shaderType) {
    return shaderType === "vertex"
      ? null
      : {
          // this is just like before. Multiply the final shader color by
          // our color. Note that we have access to all shader variables:
          // we're effectively inserting a piece of code in the shader code.
          CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR: `
                #ifdef COLORIFY
                    ${this._varColorName}.rgb *= myColor;
                #endif
            `,

          // we can even use regexes to replace arbitrary parts of the code.
          // if your key starts with '!' it's parsed as a Regex.
          "!diffuseBase\\+=info\\.diffuse\\*shadow;": `
                diffuseBase += info.diffuse*shadow;
                diffuseBase += vec3(0., 0.2, 0.8);
            `,
        };
  }
}
```

<Playground id="#P8B91Z#35" title="Using uniforms" description="Material plugin example with uniforms"/>

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

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

## Applying a plugin to a single material

Even though your plugins can be enabled/disabled as shown above, sometimes you need to apply a plugin to a single material. In this case, instead of calling `RegisterMaterialPlugin`, you can instantiate the plugin directly with the material that will be modified:

```js
const myPlugin = new BlackAndWhitePluginMaterial(material);
```

This is also useful for dynamic loading of plugins.

<Playground id="#22HT5Z#15" title="Single material" description="Material plugin applied to a single material"/>

## Implementing a complete and well designed plugin

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

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

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

getCustomCode(shaderType) {
    if (shaderType === "fragment") return {
        "CUSTOM_FRAGMENT_DEFINITIONS": `
            uniform sampler2D myTexture;
        `,

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

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

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

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

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

## Caveats

- The code insertion point names are standard over all materials, but not all of them have all insertion points. In general you can expect to have
  `CUSTOM_VERTEX_DEFINITIONS`, `CUSTOM_VERTEX_MAIN_BEGIN` and `CUSTOM_VERTEX_MAIN_END` in vertex shaders, and `CUSTOM_FRAGMENT_DEFINITIONS`, `CUSTOM_FRAGMENT_MAIN_BEGIN` and `CUSTOM_FRAGMENT_MAIN_END` in fragment shaders. But other `#defines` might not be present.
- There's no guarantee that using the shader point names / the regular expressions to update code / the variable names with a material plugin will work across Babylon.js versions. We reserve the possibility to update our shader code in a way that would break backward compatibility with those features if we have to. In particular, the color variable name for `standard.fragment.fx` is `color`, while for `pbrMaterial.fragment.fx` it's `finalColor`. If you are writing a plugin targeting multiple materials take care in your code to use different variable names according to the plugin and keep track of Babylon potentially changing (and breaking!) things.
- `RegisterMaterialPlugin` only adds the plugin to material instantiated AFTER the registration. So it must be run before you add any meshes or create your materials or they won't have the plugin.
- You can register multiple plugins to the same material (or the entire scene). The `priority` field controls the order the plugins will be executed if they are all enabled.

## Material Plugin Examples

Here are some other examples of plugins:

<Playground id="#HCLC5W#41" title="Animate parameter" description="Using a class variable to animate a parameter for all instances"/>
<Playground id="#SYQW69#1077" title="Volumetric fog" description="Power plant with volumetric fog"/>
<Playground id="#IQPBS4#62" title="Grain" description="Grain (solves banding issues)"/>
<Playground id="#8WJTJG#11" title="Fog of War" description="Simple Fog of War effect"/>

You can also take a look at Babylon's source code. The PBR material includes several complex plugins, such as the [Anisotropic plugin](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrAnisotropicConfiguration.ts), [sheen](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrSheenConfiguration.ts) and [subsurface](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/PBR/pbrSubSurfaceConfiguration.ts), and the [detail map plugin applies to PBR and Standard materials](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Materials/material.detailMapConfiguration.ts).


Shaders

Shaders

Coming next

Introduction to Shaders

Dive deep into the inner workings of shaders in Babylon.js.

Putting Shader Code Into Babylon.js

Dive deep into the inner workings of how Babylon.js handles shaders.

Shader Material

Learn about the shader material in Babylon.js.

Supporting Fog With ShaderMaterial

Learn how to support fog alongside the shader material in Babylon.js.

Image Processing

Learn all about image processing in Babylon.js.

Compute Shaders

Learn about the compute shaders in Babylon.js.