[orx-noise] Add comments to all demos, add demo

orx-noise/src/jvmDemo/kotlin/DemoCubicNoise2D01.kt

@@ -2,6 +2,11 @@ import org.openrndr.application
 import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.noise.cubicHermite3D
 
+/**
+ * Demonstrates how to render dynamic grayscale patterns using 3D cubic Hermite interpolation.
+ * The program draws one point per pixel on the screen, calculating the color intensity of each point
+ * based on a 3D cubic Hermite noise function.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoFunctionalComposition01.kt

@@ -5,6 +5,14 @@ import org.openrndr.extra.noise.gradient
 import org.openrndr.extra.noise.simplex3D
 import org.openrndr.extra.noise.withVector2Output
 
+/**
+ * Demonstrates how to chain methods behind noise functions like `simplex3D` to
+ * alter its output. By default `simplex3D` produces one double value, but
+ * by calling `.withVector2Output()` it produces `Vector2` instances instead.
+ *
+ * The `.gradient()` method alters the output to return the direction of fastest
+ * increase. Read more in [WikiPedia](https://en.wikipedia.org/wiki/Gradient).
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoGradientPerturb2D.kt

@@ -6,6 +6,17 @@ import org.openrndr.extra.noise.simplex
 import org.openrndr.math.Vector2
 import kotlin.math.absoluteValue
 
+/**
+ * Demonstrates how to generate a dynamic fractal-based visual effect
+ * using 2D gradient perturbation and simplex noise.
+ *
+ * This method initializes a color buffer to create an image and applies fractal gradient noise to set
+ * each pixel's brightness, producing a dynamic visual texture. The fractal effect is achieved by layering multiple
+ * levels of noise, and each pixel's color intensity is based on the noise function results.
+ * The output is continuously updated to produce animated patterns.
+ *
+ * CPU-based.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoGradientPerturb3D.kt

@@ -6,6 +6,17 @@ import org.openrndr.extra.noise.simplex
 import org.openrndr.math.Vector3
 import kotlin.math.absoluteValue
 
+/**
+ * Demonstrates how to generate a dynamically evolving visual
+ * representation of fractal noise. The program uses 3D gradient perturbation and simplex noise
+ * to produce a grayscale gradient on a color buffer.
+ *
+ * The visual output is created by iteratively computing the fractal gradient perturbation and simplex
+ * noise for each pixel in the color buffer, applying a perturbation based on time, and rendering the
+ * result as an image.
+ *
+ * CPU-based.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoScatter01.kt

@@ -6,6 +6,17 @@ import org.openrndr.shape.Ellipse
 import kotlin.math.cos
 import kotlin.random.Random
 
+/**
+ * Demonstrates how to create an animated visualization of scattered points.
+ *
+ * The program creates an animated ellipse with increasing and decreasing height.
+ * Then, scatters points inside it with a placementRadius of 20.0.
+ *
+ * The animation reveals that the scattering positions are somewhat stable between
+ * animation frames.
+ *
+ * The ellipse's contour is revealed and hidden every other second.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoSimplex01.kt

@@ -4,6 +4,14 @@ import org.openrndr.draw.LineJoin
 import org.openrndr.extra.noise.simplex
 import org.openrndr.shape.contour
 
+/**
+ * Demonstrates how to use the `simplex` method to obtain noise values based on a seed and an x value.
+ *
+ * The program creates 20 horizontal contours with 40 steps each in which each 2D step and each 2D control point
+ * is affected by noise.
+ *
+ * Time is used as a noise argument to produce an animated effect.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/DemoValueNoise2D01.kt

@@ -2,6 +2,13 @@ import org.openrndr.application
 import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.noise.valueQuintic3D
 
+/**
+ * Demonstrates how to render grayscale noise patterns dynamically using 3D quintic noise.
+ *
+ * The program draws one point per pixel on the screen, calculating the color intensity of
+ * each point based on a 3D quintic noise function. The noise value is influenced by the
+ * pixel's 2D coordinates and animated over time.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/hammersley/DemoHammersley2D01.kt

@@ -6,8 +6,7 @@ import org.openrndr.extra.noise.hammersley.hammersley2D
 /**
  * Demo that visualizes a 2D Hammersley point set.
  *
- * The application is configured to run at 720x720 resolution. The program computes
+ * The program computes 400 2D Hammersley points mapped within the window bounds.
- * 400 2D Hammersley points mapped within the bounds of the application's resolution.
  * These points are visualized by rendering circles at their respective positions.
  */
 fun main() = application {

orx-noise/src/jvmDemo/kotlin/hammersley/DemoHammersley3D01.kt

@@ -11,14 +11,12 @@ import org.openrndr.math.Vector3
 /**
  * Demo program rendering a 3D visualization of points distributed using the Hammersley sequence in 3D space.
  *
- * The application is set up at a resolution of 720x720 pixels. Within the visual
+ * A set of 1400 points is generated using the Hammersley sequence.
- * program, a sphere mesh is created and a set of 1400 points is generated using
+ * Each point is translated and rendered as a small sphere
- * the Hammersley sequence. Each point is translated and rendered as a small sphere
+ * in 3D space.
- * in 3D space. This is achieved by mapping the generated points into a scaled domain.
  *
- * The rendering utilizes the Orbital extension, enabling an interactive 3D camera
+ * The rendering uses the Orbital extension, enabling an interactive 3D camera
- * to navigate the scene. The visualization relies on the draw loop for continuous
+ * to navigate the scene.
- * rendering of the points.
  */
 fun main() = application {
     configure {

orx-noise/src/jvmDemo/kotlin/hammersley/DemoHammersley4D01.kt

@@ -10,17 +10,15 @@ import org.openrndr.extra.noise.hammersley.hammersley4D
 import org.openrndr.math.Vector4
 
 /**
- * Demo that visualizes a 4D Hammersley point set in a 3D space, with colors determined by the 4th dimension.
+ * Demo visualizing a 4D Hammersley point set in a 3D space, with colors determined by the 4th dimension.
  *
- * The application is configured at a resolution of 720x720 pixels. A sphere mesh is created
+ * A total of 10,000 4D points are generated with the `hammersley4D` sequence.
- * using the `sphereMesh` utility, and a total of 10,000 4D points are generated with the
+ * These points are mapped to a cubical volume and rendered as small spheres.
- * `hammersley4D` sequence. These points are scaled, translated, and rendered as small spheres.
  * The color of each sphere is modified based on the 4th dimension of its corresponding point by
  * shifting the hue in HSV color space.
  *
  * This program employs the `Orbital` extension, enabling camera interaction for 3D navigation
- * of the scene. Rendering occurs within the draw loop, providing continuous visualization
+ * of the scene.
- * of the point distribution.
  */
 fun main() = application {
     configure {

orx-noise/src/jvmDemo/kotlin/hash/DemoCircleHash01.kt

@@ -6,6 +6,17 @@ import org.openrndr.extra.noise.shapes.uniform
 import org.openrndr.shape.Circle
 import kotlin.random.Random
 
+/**
+ * Demonstrates how to draw circles distributed within two subregions of a rectangular area
+ * using uniform random distribution and a hash-based method for randomness.
+ *
+ * The application divides the window area into two subregions, offsets the edges inwards,
+ * and then calculates two circles representing these subregions. Points are then generated and drawn
+ * within these circles using two different methods:
+ *
+ * - A uniform random distribution within the first circle.
+ * - A hash-based deterministic random point generation within the second circle.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/hash/DemoRectangleHash01.kt

@@ -5,6 +5,14 @@ import org.openrndr.extra.noise.shapes.hash
 import org.openrndr.extra.noise.shapes.uniform
 import kotlin.random.Random
 
+/**
+ * Demonstrates how to generate and draw random points within two subregions of a rectangular area
+ * using two different randomization methods.
+ *
+ * The first subregion generates points using a _uniform_ random distribution, while the second subregion
+ * generates points deterministically with a _hash-based_ randomization approach. The points are visualized
+ * as small circles.
+ */
 fun main() = application {
     configure {
         width = 720

orx-noise/src/jvmDemo/kotlin/hash/DemoUHash01.kt

@@ -4,6 +4,14 @@ import org.openrndr.application
 import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.noise.fhash3D
 
+/**
+ * Demonstrates how to render a dynamic grid of points where the color of each point
+ * is determined using a hash-based noise generation method.
+ *
+ * The application dynamically updates the visual output by calculating a 3D hash
+ * value for each point in the grid, based on the current time and the point's coordinates.
+ * The hash value is then used to determine the grayscale color intensity of each point.
+ */
 fun main() = application {
     configure {
         width = 720
@@ -14,7 +22,7 @@ fun main() = application {
             drawer.points {
                 for (y in 0 until height) {
                     for (x in 0 until width) {
-                        val c = fhash3D(100, x + (seconds * 60.0).toInt(), y, (0).toInt())
+                        val c = fhash3D(seed = 100, x = x + (seconds * 60.0).toInt(), y, z = 0)
                         //val u = uhash11(x.toUInt()).toDouble() / UInt.MAX_VALUE.toDouble()
                         fill = ColorRGBa(c, c, c, 1.0)
                         point(x.toDouble(), y.toDouble())

orx-noise/src/jvmDemo/kotlin/linearrange/DemoLinearRange01.kt

@@ -6,6 +6,12 @@ import org.openrndr.extra.noise.linearrange.uniform
 import org.openrndr.extra.math.linearrange.rangeTo
 import kotlin.random.Random
 
+/**
+ * Demonstrates how to create a linear range with two [org.openrndr.shape.Rectangle]s.
+ *
+ * This range is then sampled at 100 random locations using the `uniform` method to get and render interpolated
+ * rectangles. The random seed changes once per second.
+ */
 fun main() {
     application {
         configure {
@@ -13,7 +19,9 @@ fun main() {
             height = 720
         }
         program {
-            val range = drawer.bounds.offsetEdges(-300.0, -50.0) .. drawer.bounds.offsetEdges(-50.0, -300.0)
+            val rect1 = drawer.bounds.offsetEdges(-300.0, -50.0)
+            val rect2 = drawer.bounds.offsetEdges(-50.0, -300.0)
+            val range =  rect1 .. rect2
             extend {
                 drawer.fill = ColorRGBa.WHITE.opacify(0.9)
                 val r = Random(seconds.toInt())

orx-noise/src/jvmDemo/kotlin/linearrange/DemoLinearRange02.kt

@@ -0,0 +1,35 @@
+package linearrange
+
+import org.openrndr.application
+import org.openrndr.color.ColorLCHUVa
+import org.openrndr.extra.math.linearrange.rangeTo
+import org.openrndr.extra.noise.linearrange.hash
+import org.openrndr.shape.Circle
+
+/**
+ * Demonstrates how to create a linear range with two [org.openrndr.shape.Circle]s.
+ *
+ * This range is then sampled at 100 random locations using the `hash` method to get and render interpolated
+ * circles. The random seed changes once per second.
+ *
+ * Colors are calculated based on the index of each circle.
+ */
+fun main() {
+    application {
+        configure {
+            width = 720
+            height = 720
+        }
+        program {
+            val circle1 = Circle(drawer.bounds.position(0.3, 0.3), 50.0)
+            val circle2 = Circle(drawer.bounds.position(0.7, 0.7), 200.0)
+            val range = circle1..circle2
+            extend {
+                for (i in 0 until 100) {
+                    drawer.fill = ColorLCHUVa(i * 1.0, i * 1.0, i * 30.0).toRGBa().opacify(0.6)
+                    drawer.circle(range.hash(seconds.toInt(), i))
+                }
+            }
+        }
+    }
+}

orx-noise/src/jvmDemo/kotlin/phrases/DemoUHashPhrase01.kt

@@ -2,10 +2,15 @@ package phrases
 
 import org.openrndr.application
 import org.openrndr.draw.shadeStyle
-import org.openrndr.extra.noise.phrases.fhash13
+import org.openrndr.extra.shaderphrases.noise.fhash13Phrase
 
 /**
- * Demonstrate uniform hashing function phrase in a shadestyle
+ * Demonstrate the use of a uniform hashing function phrase in a ShadeStyle.
+ *
+ * The hashing function uses the screen coordinates and the current time to
+ * calculate the brightness of each pixel.
+ *
+ * Multiple GLSL hashing functions are defined in orx-shader-phrases.
  */
 fun main() = application {
     configure {
@@ -16,7 +21,10 @@ fun main() = application {
         extend {
             /** A custom shadestyle */
             val ss = shadeStyle {
-                fragmentPreamble = """$fhash13"""
+                fragmentPreamble = """
+                        $fhash13Phrase
+                    """.trimIndent()
+
                 fragmentTransform = """
                         float cf = fhash13(vec3(c_screenPosition, p_time));
                         x_fill = vec4(cf, cf, cf, 1.0);                                                                       

orx-noise/src/jvmDemo/kotlin/rseq/DemoRseq2D01.kt

@@ -4,8 +4,7 @@ import org.openrndr.application
 import org.openrndr.extra.noise.rsequence.rSeq2D
 
 /**
- * This demo sets up a window with dimensions 720x720 and renders frames
+ * Demonstrates quasirandomly distributed 2D points. The points are generated
- * demonstrating 2D quasirandomly distributed points. The points are generated
  * using the R2 sequence and drawn as circles with a radius of 5.0.
  */
 fun main() = application {

orx-noise/src/jvmDemo/kotlin/rseq/DemoRseq3D01.kt

@@ -9,7 +9,7 @@ import org.openrndr.extra.noise.rsequence.rSeq3D
 import org.openrndr.math.Vector3
 
 /**
- * This demo renders a 3D visualizationof points distributed using the R3 quasirandom sequence. Each point is
+ * This demo renders a 3D visualization of points distributed using the R3 quasirandom sequence. Each point is
  * represented as a sphere and positioned in 3D space based on the quasirandom sequence values.
  *
  * The visualization setup includes: