From ff1cc940902b5a00c9fca8215ac2e68541a1708a Mon Sep 17 00:00:00 2001
From: Laurent Le Brun <laurentlb@gmail.com>
Date: Sun, 2 Jun 2024 00:15:50 +0200
Subject: [PATCH] Document the new transformations (#426)

---
 README.md          |  3 ++
 TRANSFORMATIONS.md | 76 +++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 72 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 604ff5b7..3000f389 100644
--- a/README.md
+++ b/README.md
@@ -312,11 +312,14 @@ them all at the same time by listing them all on the command-line.
 - [Automatic inlining](TRANSFORMATIONS.md#Automatic-inlining)
 - [Aggressive inlining](TRANSFORMATIONS.md#Aggressive-inlining)
 - [Explicit inlining](TRANSFORMATIONS.md#Explicit-inlining)
+- [Reassignment merging](TRANSFORMATIONS.md#Reassignment-merging)
+- [Variable reuse](TRANSFORMATIONS.md#Variable-reuse)
 - [Vector constructors](TRANSFORMATIONS.md#Vector-constructors)
 - [Function predeclarations](TRANSFORMATIONS.md#Function-predeclarations)
 - [Unused local variables](TRANSFORMATIONS.md#Unused-local-variables)
 - [Dead code removal](TRANSFORMATIONS.md#Dead-code-removal)
 - [Unused function removal](TRANSFORMATIONS.md#Unused-function-removal)
+- [Other functions](TRANSFORMATIONS.md#Other-functions)
 - [Renaming](TRANSFORMATIONS.md#Renaming)
 
 
diff --git a/TRANSFORMATIONS.md b/TRANSFORMATIONS.md
index afd41ec3..dcb61851 100644
--- a/TRANSFORMATIONS.md
+++ b/TRANSFORMATIONS.md
@@ -121,13 +121,14 @@ int foo() {
 
 If you write `x*(y*z)`, Shader Minifier will not remove the parentheses because
 it would change the orders of evaluation (this could be a problem with floating
-point numbers and affect the precision of the result). Instead, it will swap the
-operands and return `y*z*x`.
+point numbers and affect the precision of the result). Instead, it will swap
+the operands and return `y*z*x`. With additive operators, we assume we can
+remove the parentheses.
 
 We apply this technique in a few cases:
 - `x*(y*z)` becomes `y*z*x`
-- `x+(y+z)` becomes `y+z+x`
-- `x+(y-z)` becomes `y-z+x`
+- `x+(y+z)` becomes `x+y+z`
+- `x+(y-z)` becomes `x+y-z`
 - `x-(y+z)` becomes `x-y-z`
 - `x-(y-z)` becomes `x-y+z`
 
@@ -377,7 +378,7 @@ int foo(int x) {
 
 will be simplified into:
 
-```c
+```glsl
 int foo(int x)
 {
   return 10*x;
@@ -386,7 +387,7 @@ int foo(int x)
 
 And this input:
 
-```c
+```glsl
 float i_foo(float f, float g, float x) {
   return f*x + g*x + f*g;
 }
@@ -398,7 +399,7 @@ float bar(float a) {
 
 will be simplified into:
 
-```c
+```glsl
 float bar(float a)
 {
   return 2.*sin(sqrt(a))+3.*sin(sqrt(a))+6.;
@@ -413,6 +414,62 @@ If you want to aggressively reduce the size of your shader, try inlining more
 variables. Inlining can have performance implications though (if the variable
 stored the result of a computation), so be careful with it.
 
+## Reassignment merging
+
+Shader Minifier can remove or merge assignment statements in some cases:
+- if a variable is declared and reassigned on the next line;
+- if a variable is reassigned on two consecutive lines;
+- if a variable is reassigned and then part of a return.
+
+Of course, this is not always possible (the variable should be read only once;
+side-effects might can prevent the optimization).
+
+For example:
+
+```glsl
+float d = 100.;
+d = min(d, sdfBox(...));
+d = min(d, sdfBall(...));
+return d;
+```
+
+can be simplified into:
+
+```glsl
+return min(min(100., sdfBox(...)), sdfBall(...));
+```
+
+## Variable reuse
+
+If a local variable is no longer used and we declare a new variable of the
+same type, the old variable will be reused instead.
+
+For example:
+
+```glsl
+int a = 1;
+// ...
+f(a);
+int b = 2;
+// ...
+f(b);
+```
+
+can be simplified to:
+
+```glsl
+int a = 1;
+// ...
+f(a);
+a = 2;
+// ...
+f(a)'
+```
+
+**Note**: This operation reduces the number of variables in the file, which
+usually improves the compression. When renaming is disabled, the code can be
+misleading, as the variable name won't match the code behavior anymore.
+
 ## Vector constructors
 
 - Calls to `vec2`, `vec3`, and `vec4` can be simplified using swizzles.
@@ -468,6 +525,11 @@ default, this is the case for `main` and `mainImage`.
 **Note**: Use `--no-remove-unused` to disable this transformation.
 
 
+## Other functions
+
+* `distance(a, b)` becomes `length(a-b)`.
+* `pow(x, 1.)` becomes `x`.
+
 ## Renaming
 
 There are two renaming strategies: