Add descriptions to demos

Author: hamoid

orx-color/src/jvmDemo/kotlin/DemoXSLUV01.kt

@@ -1,18 +1,30 @@
-// Visualize XSLUV color space by drawing a recursively subdivided arcs
-
 import org.openrndr.application
 import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.color.spaces.ColorXSLUVa
 import org.openrndr.math.Polar
 import org.openrndr.shape.contour
 
+/**
+ * Visualize the XSLUV color space by drawing a recursively subdivided set of arcs.
+ *
+ * The provided `Arc` class provides a `contour` getter, which creates a "thick" arc with
+ * its thickness defined by the `height` argument. This is created by two arcs and two
+ * connecting lines.
+ *
+ * The mouse x coordinate controls the saturation, while the y coordinate controls the luminosity.
+ * The two if-statements check whether the program is taking a screenshot (this happens when
+ * it runs on GitHub actions) to set fixed saturation and luminosity values.
+ */
 fun main() = application {
     configure {
         width = 720
         height = 720
     }
 
     class Arc(val start: Double, val radius: Double, val length: Double, val height: Double) {
+        /**
+         * Splits the Arc in two equal parts with half the length of the original
+         */
         fun split(offset: Double = 0.0): List<Arc> {
             val hl = length / 2.0
             return listOf(
@@ -21,6 +33,11 @@ fun main() = application {
             )
         }
 
+        /**
+         * Return the contour of an arc with `height` thickness, by drawing an arc using `radius`,
+         * then a line connecting to a returning arc using `radius + height`, and a final line to
+         * close the contour.
+         */
         val contour
             get() = contour {
                 moveTo(Polar(start, radius).cartesian)
@@ -32,18 +49,22 @@ fun main() = application {
             }
     }
 
+    /**
+     * Create a list of `Arc` by recursively calling the `split` function until `depth` reaches 0.
+     */
     fun List<Arc>.split(depth: Int): List<Arc> = if (depth == 0) {
         this
     } else {
         this + flatMap { it.split(it.height) }.split(depth - 1)
     }
 
     program {
-        val arcs = (0..4).map { Arc(it * 90.0 - 45.0, 50.0, 90.0, 50.0) }.split(5)
+        val arcs = (0..4).map {
+            Arc(it * 90.0 - 45.0, 50.0, 90.0, 50.0)
+        }.split(5)
 
         extend {
             drawer.clear(ColorRGBa.GRAY)
-            val color = ColorRGBa.RED
             drawer.stroke = ColorRGBa.BLACK
             drawer.strokeWeight = 1.0
             drawer.translate(drawer.bounds.center)

orx-compositor/src/jvmDemo/kotlin/DemoCompositor01.kt

@@ -36,9 +36,11 @@ fun main() = application {
         }
 
         val items = List(50) {
-            val pos = Vector3(Random.nextDouble() * width,
-                    Random.nextDouble(0.3, 0.7) * height,
-                    Random.nextDouble())
+            val pos = Vector3(
+                Random.nextDouble() * width,
+                Random.nextDouble(0.3, 0.7) * height,
+                Random.nextDouble()
+            )
             Item(pos, ColorRGBa.PINK.shade(Random.nextDouble(0.2, 0.9)))
         }.sortedBy { it.pos.z }
 

orx-jumpflood/src/commonMain/kotlin/draw/SDFDraw.kt

@@ -24,7 +24,6 @@ class SDFStrokeFill : Filter(filterShaderFromCode(jf_sdf_stroke_fill, "sdf-strok
     @DoubleParameter("fill feather", 0.0, 20.0, order = 0)
     var fillFeather: Double by parameters
 
-
     @ColorParameter("fill color", order = 2)
     var fillColor: ColorRGBa by parameters
     init {

orx-jumpflood/src/jvmDemo/kotlin/DemoDirectionField01.kt

@@ -12,7 +12,8 @@ import org.openrndr.shape.Rectangle
  * Shows how to use the [DirectionalField] filter.
  * Draws moving white shapes on black background,
  * then applies the DirectionalField filter which returns a [ColorBuffer] in which
- * the red and green components encode the direction to the closest black/white edge.
+ * the red and green components encode the direction to the closest black/white edge,
+ * and the blue component the distance to that edge.
  *
  * Hold down a mouse button to see the raw animation.
  */

orx-jumpflood/src/jvmDemo/kotlin/DemoDirectionField02.kt

@@ -12,7 +12,17 @@ import org.openrndr.math.Vector3
 import org.openrndr.math.clamp
 
 /**
- * Create directional distance field and demonstrate signed distance
+ * Demonstrates how use the `DirectionalField` effect to create
+ * a `ColorBuffer` in which the RGB components encode direction and distance to the closest
+ * edge of every pixel in an input `ColorBuffer`.
+ *
+ * The program draws scattered white circles on a `ColorBuffer`, then applies the `DistanceField()`
+ * effect and renders the static result on every animation frame.
+ *
+ * Additionally, it uses the shadow (CPU version of the texture) to query the distance field texture
+ * at current mouse position. The resulting blue color component is used as the radius of a circle
+ * centered at the mouse position. The red and green components are used to draw a line to the
+ * black/white edge closest to the mouse pointer.
  */
 fun main() = application {
     configure {
@@ -26,12 +36,12 @@ fun main() = application {
             drawer.circles(points, 50.0)
         }
 
-        val filter = DirectionalField()
+        val directionalField = DirectionalField()
         val ddf = input.createEquivalent(type = ColorType.FLOAT32)
 
-        filter.signedMagnitude = true
-        filter.unitDirection = true
-        filter.apply(input, ddf)
+        directionalField.signedMagnitude = true
+        directionalField.unitDirection = true
+        directionalField.apply(input, ddf)
 
         ddf.shadow.download()
         extend {

orx-jumpflood/src/jvmDemo/kotlin/DemoShapeSDF01.kt

@@ -6,6 +6,15 @@ import org.openrndr.draw.colorBuffer
 import org.openrndr.extra.jumpfill.ShapeSDF
 import org.openrndr.extra.svg.loadSVG
 
+/**
+ * Demonstrates the use of the `ShapeSDF()` effect, which takes vector shapes
+ * (either `Shape` or `ShapeContour` instances) and produces a `ColorBuffer`
+ * texture containing a signed distance field pointing at the closest vector edge
+ * encoded in its RGB channels.
+ *
+ * Hold down any mouse button to observe the original vector shape in black and white,
+ * without the effect applied.
+ */
 fun main() =  application {
     configure {
         width = 720

orx-jumpflood/src/jvmDemo/kotlin/DemoShapeSDF02.kt

@@ -11,8 +11,21 @@ import org.openrndr.extra.svg.loadSVG
 import org.openrndr.math.Vector3
 import org.openrndr.math.transforms.transform
 
-import kotlin.math.min
-
+/**
+ * Advanced demonstration making use of two `ShapeSDF` filters: the first applied to a static
+ * SVG loaded from a file, and the second to a rotating version of the same shape.
+ *
+ * The demo also uses three additional SDF filters:
+ * - `SDFSmoothIntersection`, which combines two color buffers containing SDF information
+ *   into a new color buffer
+ * - `SDFOnion`, which takes one SDF color buffer and outputs one SDF color buffer
+ * - `SDFStrokeFill`, used for rendering using configurable fill and stroke properties.
+ *
+ * The vertical mouse position is used to control the radius of the `SDFSmoothIntersection` effect.
+ *
+ * The program finally renders the result of the previous operations as one color buffer
+ * thanks to the `SDFStrokeFill` effect.
+ */
 fun main() = application {
     configure {
         width = 720
@@ -30,7 +43,6 @@ fun main() = application {
         val union = SDFSmoothIntersection()
         val onion = SDFOnion()
 
-
         val strokeFill = SDFStrokeFill()
 
         extend {
@@ -41,17 +53,20 @@ fun main() = application {
             sdf1.setShapes(shapes.map {
                 it.transform(transform {
                     translate(drawer.bounds.center)
-                    rotate(Vector3.Companion.UNIT_Z, seconds * 45.0 - 30.0)
+                    rotate(Vector3.UNIT_Z, seconds * 45.0 - 30.0)
                     translate(-drawer.bounds.center)
                 })
             })
 
             sdf0.apply(emptyArray(), df0)
             sdf1.apply(emptyArray(), df1)
-            union.radius = 10.0 + min(mouse.position.y, 100.0)
+
+            union.radius = 10.0 + mouse.position.y.coerceAtMost(100.0)
             union.apply(arrayOf(df0, df1), df0)
+
             onion.radius = 20.0
             onion.apply(df0, df0)
+
             strokeFill.strokeWeight = 2.0
             strokeFill.apply(df0, df0)
             drawer.image(df0)

orx-jumpflood/src/jvmDemo/kotlin/DemoShapeSDF03.kt

@@ -9,6 +9,18 @@ import org.openrndr.extra.jumpfill.draw.SDFStrokeFill
 import org.openrndr.extra.jumpfill.ops.SDFSmoothDifference
 import org.openrndr.extra.svg.loadSVG
 
+/**
+ * Advanced demonstration making use the `ShapeSDF` filter applied twice to a static
+ * SVG loaded from a file, one with `useUV` set to true.
+ *
+ * A `FluidDistort` filter is used to generate an animated UV map which is fed into
+ * both `ShapeSDF` filters. A `SDFSmoothDifference` filter is then applied to combine
+ * both resulting `ColorBuffer` instances, and a `SDFStrokeFill` filter used for
+ * rendering the result.
+ *
+ * The mouse horizontal position determines which of the three used color buffers is
+ * displayed.
+ */
 fun main() = application {
     configure {
         width = 720
@@ -40,13 +52,22 @@ fun main() = application {
 
             sdf0.useUV = true
             sdf0.apply(uvmap, df0)
+
             sdf1.apply(uvmap, df1)
+
             union.radius = 10.0
             union.apply(arrayOf(df0, df1), df0)
 
             strokeFill.strokeWeight = 10.0
             strokeFill.apply(df0, df0)
-            drawer.image(df0)
+
+            drawer.image(
+                when (mouse.position.x) {
+                    in 0.0..width * 0.6 -> df0
+                    in width * 0.6..width * 0.8 -> df1
+                    else -> uvmap
+                }
+            )
         }
     }
 }

orx-jumpflood/src/jvmDemo/kotlin/DemoShapeSDF04.kt

@@ -11,6 +11,22 @@ import org.openrndr.extra.jumpfill.ops.SDFSmoothDifference
 import org.openrndr.extra.svg.loadSVG
 import org.openrndr.shape.Circle
 
+/**
+ * Demonstrates using tow `ShapeSDF` filters. One contairs a vector shape loaded
+ * from disk, the other a circular shape.
+ *
+ * A `Perturb` effect is used to generate a noise UV map, which is then fed into
+ * the `ShapeSDF` filters.
+ *
+ * The two resulting `ColorBuffer`s are combined using a `SDFSmoothDifference` filter,
+ * which erases the distorted circular shape from the loaded shape.
+ *
+ * The `SDFStrokeFill` is used to render the result.
+ *
+ * A GUI is available to tweak the parameters of the `Perturb` effect.
+ * Lowering its `gain` to zero disables the effect, revealing the circle and the
+ * smoothness (round corners) of the difference effect.
+ */
 fun main() = application {
     configure {
         width = 720

orx-jumpflood/src/jvmDemo/kotlin/DemoShapeSDF05.kt

@@ -14,6 +14,11 @@ import org.openrndr.shape.Circle
 import kotlin.math.cos
 import kotlin.math.sin
 
+/**
+ * Variation of DemoShapeSDF04, in which `Perturb` is applied twice with different
+ * parameters for a more complex UV map, and with four effects added to the GUI
+ * for further customization and exploration.
+ */
 fun main() = application {
     configure {
         width = 720
@@ -44,8 +49,8 @@ fun main() = application {
         sdf0.useUV = true
         gui.add(sdf0)
         gui.add(perturb)
-        gui.add(strokeFill)
         gui.add(difference)
+        gui.add(strokeFill)
 
         extend(gui)
         extend {