Add documentation for the chunk migrations in 1.57.

content/en/user-manual/graphics/shader-chunk-migrations.md

@@ -17,6 +17,7 @@ The debug version of the Engine will report any API changes to the runtime conso
 ![Console output][2]
 
 Once an application's chunks have been updated to the latest API they must be flagged as such. For example, after updating a material's custom chunks to the latest engine release (say v1.55), specify this in the chunks object as follows:
+
 ```javascript
 material.chunks.diffusePS = '...';
 material.chunks.APIVersion = pc.CHUNKAPI_1_55;
@@ -27,6 +28,73 @@ By doing this you will no longer see warning messages in the console.
 ## Chunk changes
 
 The following tables break down the chunk changes by Engine release.
+
+---
+#### *Engine v1.57*
+
+In 1.57, almost all front-end chunks have been changed to minimize the amount of samplers used by the shader. This is an optional feature, however it's recommended to follow the same coding style to reduce the amount of samplers used by the shader. The following chunks are affected by it:
+
+| Chunk  |
+| --- |
+| `aoPS` |
+| `clearCoatPS` |
+| `clearCoatGlossPS` |
+| `clearCoatNormalPS` |
+| `diffusePS` |
+| `diffuseDetailMapPS` |
+| `emissivePS` |
+| `metalnessPS` |
+| `normalMapPS` |
+| `normalDetailMapPS` |
+| `opacityPS` |
+| `parallaxPS` |
+| `sheenPS` |
+| `sheenGlossPS` |
+| `specularPS` |
+| `specularityFactorPS` |
+| `thicknessPS` |
+| `transmissionPS` |
+
+This is also supported in custom front-end chunks, given that your chunk piggybacks on the pre-existing material samplers. To support this method in your chunks, what you'd need to do is:
+
+* Remove the sampler uniform declaration from the chunk
+* Replace the sampler name with the `$SAMPLER` macro
+
+For example:
+
+```glsl
+uniform sampler2D texture_aoMap;
+void getAO() {
+    dAo = 1.0;
+
+    #ifdef MAPTEXTURE
+    dAo *= texture2DBias(texture_aoMap, $UV, textureBias).$CH;
+    #endif
+
+    #ifdef MAPVERTEX
+    dAo *= saturate(vVertexColor.$VC);
+    #endif
+}
+```
+
+Would be converted to:
+
+```glsl
+void getAO() {
+    dAo = 1.0;
+
+    #ifdef MAPTEXTURE
+    dAo *= texture2DBias($SAMPLER, $UV, textureBias).$CH;
+    #endif
+
+    #ifdef MAPVERTEX
+    dAo *= saturate(vVertexColor.$VC);
+    #endif
+}
+```
+
+This allows the engine to automatically pick the sampler uniform to use, thus potentially reducing the total number of samplers. But note, this is only supported for front-end chunks. 
+
 ---
 #### *Engine v1.56*
 
@@ -43,7 +111,6 @@ The following tables break down the chunk changes by Engine release.
 | `bakeDirLmEndPs` | <ul><li>moved to `chunks-lightmapper.js`.</li></ul>
 | `bakeLmEndPS` | <ul><li>moved to `chunks-lightmapper.js`.</li></ul>
 
-
 ---
 #### *Engine v1.55*
 
@@ -76,6 +143,5 @@ The following tables break down the chunk changes by Engine release.
 | `specularPS` | <ul><li>only provides specular color, metalness modulation is now done in backend.</li></ul> |
 | `specularityFactorPS` | <ul><li>new chunk to control specular intensity for metalness workflow.</li></ul> |
 
-
 [1]: https://github.com/playcanvas/engine/issues/4250
 [2]: /images/user-manual/graphics/shader-chunk-migrations/console-warning.png