From 4eeb7e4e07678e49798ee7335a0fe8e94571bc85 Mon Sep 17 00:00:00 2001
From: Edwin Jakobs <edwin@rndr.studio>
Date: Thu, 19 Jan 2023 14:04:27 +0100
Subject: [PATCH] [orx-compositor] Update README.md

---
 orx-compositor/README.md | 193 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 189 insertions(+), 4 deletions(-)

diff --git a/orx-compositor/README.md b/orx-compositor/README.md
index fb178709..f2cc951f 100644
--- a/orx-compositor/README.md
+++ b/orx-compositor/README.md
@@ -2,7 +2,195 @@
 
 Toolkit to make composite (layered) images using blend modes and filters.
 
-##### Usage
+## Usage
+
+A `Composite` is made using the `compose {}` builder. We start with a very simple example:
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            // this is only executed once
+            val position = Vector2(100.0, 100.0)
+            
+            draw {
+                // code inside draw blocks is executed whenever the composite is drawn
+                drawer.circle(position, 100.0)
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+
+### Layers
+
+A `Composite` with two layers looks like this.
+
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            // this layer is drawn first
+            layer {
+                val position = Vector2(100.0, 100.0)
+                draw {
+                    drawer.circle(position, 100.0)
+                }
+            }
+            
+            // this layer is drawn second
+            layer {
+                val position = Vector2(150.0, 150.0)
+                draw {
+                    drawer.circle(position, 100.0)
+                }
+                blend(Multiply())
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+
+Layers can be nested:
+
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            layer {
+                layer {
+                    // this draw is processed first
+                    draw { }
+                }
+                layer {
+                    // this draw is processed second
+                    draw { }
+                }
+                val position = Vector2(100.0, 100.0)
+                draw {
+                    // this draw is processed third
+                    drawer.circle(position, 100.0)
+                }
+            }
+            
+            // this layer is drawn second
+            layer {
+                val position = Vector2(150.0, 150.0)
+                draw {
+                    drawer.circle(position, 100.0)
+                }
+                blend(Multiply())
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+
+### Asides
+
+An aside is a layer which output is not directly included in the composite drawing. The contents of an aside can be used in layers and post-processing.
+
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            
+            val a = aside {
+                val position = Vector2(250.0, 250.0)
+                draw {
+                    drawer.circle(position, 100.0)
+                }
+            }
+            
+            // this layer is drawn second
+            layer {
+                val position = Vector2(150.0, 150.0)
+                draw {
+                    drawer.image(a)
+                    drawer.circle(position, 100.0)
+                }
+                blend(Multiply())
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+
+
+### Post-processing
+
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            layer {
+                draw {
+                    
+                }
+                // the first Filter1to1 to apply
+                post(ApproximateGaussianBlur()) {
+                    // here is code that is executed everytime the layer is drawn
+                }
+                
+                // the second Filter1to1 to apply
+                post(ColorCorrection()) {
+                    // here is code that is executed everytime the layer is drawn
+                }
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+#### Using filters with multiple inputs
+
+Some filters use more than a single input in producing their output, these filters inherit from Filter2to1, Filter3to1, Filter4to1 etc.
+One such filter is `DirectionalBlur` which has image and direction field inputs. In the following example we use an aside to 
+draw a direction field which is fed into the blur filter.
+
+```kotlin
+fun main() = application {
+    program {
+        val composite = compose {
+            val directionField = aside {
+                draw {
+                    // [...]
+                }
+            }
+            layer {
+                draw {
+                    // [...]
+                }
+                post(DirectionalBlur(), directionField)
+            }
+        }
+        extend {
+            // draw the composite
+            composite.draw(drawer)
+        }
+    }
+}
+```
+
+##### Example
 
 ```kotlin
 import org.openrndr.application
@@ -13,7 +201,6 @@ import org.openrndr.extra.fx.edges.EdgesWork
 import org.openrndr.extra.gui.GUI
 import org.openrndr.math.Vector2
 
-
 fun main() {
     application {
         configure {
@@ -21,8 +208,6 @@ fun main() {
             height = 768
         }
         program {
-            val gui = GUI()
-
             val w2 = width / 2.0
             val h2 = height / 2.0