[wip] Feature: colored height maps to ordered point clouds + point clouds to wireframes and meshes

.gitignore

@@ -9,3 +9,4 @@ gradle.properties
 /gui-parameters/
 /ShaderError.glsl
 /.kotlin
+/.lwjgl

README.md

@@ -17,6 +17,7 @@ complement [OPENRNDR](https://github.com/openrndr/openrndr).
 | [`orx-compositor`](orx-compositor/) | Toolkit to make composite (layered) images using blend modes and filters. |
 | [`orx-compute-graph`](orx-compute-graph/) | A graph for computation. |
 | [`orx-compute-graph-nodes`](orx-compute-graph-nodes/) | A collection of nodes that can be used with `orx-compute-graph`. |
+| [`orx-compute-shaders`](orx-compute-shaders/) | Tools easing the work with compute shaders. |
 | [`orx-delegate-magic`](orx-delegate-magic/) | Collection of magical property delegators. For tracking variable change or interpolate towards the value of a variable. |
 | [`orx-easing`](orx-easing/) | Easing functions for smooth animation or non-linear interpolation. |
 | [`orx-envelopes`](orx-envelopes/) | ADSR (Attack, Decay, Sustain, Release) envelopes and tools. |
@@ -39,6 +40,7 @@ complement [OPENRNDR](https://github.com/openrndr/openrndr).
 | [`orx-obj-loader`](orx-obj-loader/) | Simple loader for Wavefront .obj 3D mesh files. |
 | [`orx-palette`](orx-palette/) | Provides hundreds of color palettes. |
 | [`orx-parameters`](orx-parameters/) | Provides annotations and tools for turning Kotlin properties into introspectable parameters. Used by [`orx-gui`](../orx-jvm/orx-gui/README.md) to automatically generate user interfaces. |
+| [`orx-point-clouds`](orx-point-clouds/) | 3D-point cloud generating functions |
 | [`orx-property-watchers`](orx-property-watchers/) | Tools for setting up property watcher based pipelines |
 | [`orx-quadtree`](orx-quadtree/) | A [Quadtree](https://en.wikipedia.org/wiki/Quadtree) is a spatial partioning tree structure meant to provide fast spatial queries such as nearest points within a range. |
 | [`orx-shade-styles`](orx-shade-styles/) | Shader based fills and strokes, including various types of gradient fills. |
@@ -52,6 +54,7 @@ complement [OPENRNDR](https://github.com/openrndr/openrndr).
 | [`orx-triangulation`](orx-triangulation/) | **Delaunay** triangulation and **Voronoi** diagrams. |
 | [`orx-turtle`](orx-turtle/) | Bezier (`ShapeContour`) backed [turtle graphics](https://en.wikipedia.org/wiki/Turtle_graphics). |
 | [`orx-view-box`](orx-view-box/) | To create independent views inside one program window. |
+| [`orx-wireframes`](orx-wireframes/) | 3D-wireframe generating functions |
 
 ## JVM only
 

orx-compute-shaders/README.md

@@ -0,0 +1,57 @@
+# orx-compute-shaders
+
+Tools easing the work with compute shaders.
+
+## Overview
+
+`orx-compute-shaders` is designed to simplify the execution of compute shaders, especially for 2D data. This can include
+images, grids of values, or organized point clouds.
+
+## Executing Compute Shaders for 2D Data
+
+When working with 2-dimensional data, particularly if the dimensions are unknown, certain assumptions must be made about
+the dimensions of the computation. Below is an example of how to specify the layout in the shader and execute it.
+
+### Shader Layout
+In the shader itself, specify the layout as follows:
+
+```glsl
+#version 430
+layout (local_size_x = 8, local_size_y = 8) in;
+
+uniform ivec2 resolution;
+
+void main() {
+    ivec2 coord = ivec2(gl_GlobalInvocationID.xy);
+    // Prevent computation outside the resolution range
+    if (coord.x >= resolution.x || coord.y >= resolution.y) {
+        return;
+    }
+
+    // Desired computation
+    // ...
+}
+```
+
+### Execution in Kotlin
+
+Now, you can execute such a shader in Kotlin with the following code:
+
+```kotlin
+val shader = ComputeShader.fromCode(shaderCode)
+val executeDimensions = computeShaderExecuteDimensions(
+    resolution,
+    localSizeX = 8,
+    localSizeY = 8
+)
+shader.execute(executeDimensions)
+```
+
+Note: Ensure the local size matches between the GLSL and Kotlin code for each respective dimension.
+
+<!-- __demos__ -->
+## Demos
+### DemoComputeShaderExecute2D
+[source code](src/jvmDemo/kotlin/DemoComputeShaderExecute2D.kt)
+
+![DemoComputeShaderExecute2DKt](https://raw.githubusercontent.com/openrndr/orx/media/orx-compute-shaders/images/DemoComputeShaderExecute2DKt.png)

orx-compute-shaders/build.gradle.kts

@@ -0,0 +1,22 @@
+plugins {
+    org.openrndr.extra.convention.`kotlin-multiplatform`
+}
+
+kotlin {
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                api(libs.openrndr.application)
+                api(libs.openrndr.math)
+            }
+        }
+        val commonTest by getting {
+            dependencies {
+                api(libs.kotest.assertions)
+            }
+        }
+        val jvmDemo by getting {
+            dependencies {}
+        }
+    }
+}

orx-compute-shaders/src/commonMain/kotlin/ComputeShaders.kt

@@ -0,0 +1,46 @@
+package org.openrndr.extra.computeshaders
+
+import org.openrndr.draw.ColorBuffer
+import org.openrndr.math.IntVector2
+import org.openrndr.math.IntVector3
+import kotlin.math.ceil
+
+val ColorBuffer.resolution get() = IntVector2(width, height)
+
+/**
+ * Computes dimensions needed to execute a compute shader when computing 2D data.
+ *
+ * @param resolution the resolution of the 2D data to compute.
+ * @param localSizeX the `local_size_x` specified in the compute shader.
+ * @param localSizeY the `local_size_y` specified in the compute shader.
+ */
+fun computeShaderExecuteDimensions(
+    resolution: IntVector2,
+    localSizeX: Int,
+    localSizeY: Int
+): IntVector3 = IntVector3(
+    workGroupDimension(resolution.x, localSizeX),
+    workGroupDimension(resolution.y, localSizeY),
+    z = 1
+)
+
+/**
+ * Appends given string after `#version x` statement.
+ *
+ * Useful for adding `#define` statements to existing shaders.
+ *
+ * @param string the string to append.
+ */
+fun String.appendAfterVersion(
+    string: String
+) = replace(versionRegex) {
+    "${it.value}\n$string\n"
+}
+
+private fun workGroupDimension(
+    size: Int,
+    layout: Int
+) = ceil(size.toDouble() / layout.toDouble()).toInt()
+
+private val versionRegex = Regex("#version [0-9]+")
+

orx-compute-shaders/src/commonTest/kotlin/TestComputeShaders.kt

@@ -0,0 +1,49 @@
+package org.openrndr.extra.computeshaders
+
+import io.kotest.matchers.shouldBe
+import org.openrndr.math.IntVector2
+import org.openrndr.math.IntVector3
+import kotlin.test.Test
+
+class TestComputeShaders {
+
+    @Test
+    fun testComputeShaderExecuteDimensions() {
+
+        computeShaderExecuteDimensions(
+            resolution = IntVector2(639, 480),
+            localSizeX = 8,
+            localSizeY = 8
+        ) shouldBe IntVector3(80, 60, 1)
+
+        computeShaderExecuteDimensions(
+            resolution = IntVector2(640, 480),
+            localSizeX = 8,
+            localSizeY = 8
+        ) shouldBe IntVector3(80, 60, 1)
+
+        computeShaderExecuteDimensions(
+            resolution = IntVector2(641, 480),
+            localSizeX = 8,
+            localSizeY = 8
+        ) shouldBe IntVector3(81, 60, 1)
+
+        computeShaderExecuteDimensions(
+            resolution = IntVector2(641, 481),
+            localSizeX = 8,
+            localSizeY = 8
+        ) shouldBe IntVector3(81, 61, 1)
+
+    }
+
+    @Test
+    fun replaceVersion() {
+        "foo".appendAfterVersion("bar") shouldBe "foo"
+        "#version 430".appendAfterVersion("#define FOO") shouldBe """
+            #version 430
+            #define FOO
+
+            """.trimIndent()
+    }
+
+}

orx-compute-shaders/src/jvmDemo/kotlin/DemoComputeShaderExecute2D.kt

@@ -0,0 +1,60 @@
+import org.openrndr.application
+import org.openrndr.draw.ComputeShader
+import org.openrndr.draw.colorBuffer
+import org.openrndr.draw.font.BufferAccess
+import org.openrndr.draw.imageBinding
+import org.openrndr.extra.computeshaders.computeShaderExecuteDimensions
+import org.openrndr.extra.computeshaders.resolution
+
+/**
+ * A compute shader computing an image of an arbitrary size. If dimensions of an image are not a multiplicity
+ * of a workgroup size dimensions (`local_size_x`, `local_size_y`), then excessive calculations will happen,
+ * and they should be discarded with the initial if statement in the compute shader.
+ * The [computeShaderExecuteDimensions] function will calculate proper `executeDimensions` for the `ComputeShader`
+ * outputting such a 2D image.
+ */
+fun main() = application {
+    program {
+        val image = colorBuffer(
+            width = width - 1,  // we are changing to image size to uneven on purpose
+            height = height -1
+        )
+        val shader = ComputeShader.fromCode(
+            code = """
+                |#version 430
+                |layout (local_size_x = 8, local_size_y = 8) in;
+                |uniform writeonly image2D image;
+                |uniform ivec2 resolution;
+                |uniform float seconds;
+                |
+                |void main() {
+                |    ivec2 coord = ivec2(gl_GlobalInvocationID.xy);
+                |    if (coord.x >= resolution.x || coord.y >= resolution.y) {
+                |        return;
+                |    }
+                |    vec4 color = vec4(
+                |        coord.x / float(resolution.x),
+                |        coord.y / float(resolution.y),
+                |        sin(seconds) * .5 + .5,
+                |        1.0
+                |    );
+                |    imageStore(image, coord, color);
+                |}
+                """.trimMargin(),
+            name = "image-computer"
+        ).apply {
+            uniform("resolution", image.resolution)
+            image("image", 0, image.imageBinding(0, BufferAccess.WRITE))
+        }
+        val executeDimensions = computeShaderExecuteDimensions(
+            image.resolution,
+            localSizeX = 8,
+            localSizeY = 8
+        )
+        extend {
+            shader.uniform("seconds", seconds)
+            shader.execute(executeDimensions)
+            drawer.image(image)
+        }
+    }
+}

orx-mesh-generators/README.md

@@ -83,6 +83,37 @@ The [demo folder](src/jvmDemo/kotlin) contains examples using these methods.
 
 Check out the [source code](src/commonMain/kotlin) to learn about function arguments.
 
+## Meshes out of point clouds
+
+```kotlin
+val resolution = IntVector2(640, 480)
+val mesh = PointCloudToMeshGenerator().generate(pointCloud, resolution)
+```
+
+This approach is suitable for one time generation, but the mesh `VertexBuffer` can be also updated continuously.
+
+```kotlin
+val resolution = IntVector2(640, 480)
+val mesh = meshVertexBuffer(resolution)
+val generator = PointCloudToMeshGenerator()
+// ...
+extend {
+    generator.populate(mesh, pointCloud, resolution)
+}
+```
+
+All of this can be also achieved for colored point clouds:
+
+```kotlin
+val resolution = IntVector2(640, 480)
+val mesh = coloredMeshVertexBuffer(resolution)
+val generator = ColoredPointCloudToMeshGenerator()
+// ...
+extend {
+    generator.populate(mesh, pointCloud, resolution)
+}
+```
+
 <!-- __demos__ -->
 ## Demos
 ### DemoAll
@@ -95,6 +126,11 @@ Check out the [source code](src/commonMain/kotlin) to learn about function argum
 
 ![DemoBoxKt](https://raw.githubusercontent.com/openrndr/orx/media/orx-mesh-generators/images/DemoBoxKt.png)
 
+### DemoColoredHeightMapToMesh
+[source code](src/jvmDemo/kotlin/DemoColoredHeightMapToMesh.kt)
+
+![DemoColoredHeightMapToMeshKt](https://raw.githubusercontent.com/openrndr/orx/media/orx-mesh-generators/images/DemoColoredHeightMapToMeshKt.png)
+
 ### DemoComplex01
 [source code](src/jvmDemo/kotlin/DemoComplex01.kt)
 
@@ -154,3 +190,8 @@ Check out the [source code](src/commonMain/kotlin) to learn about function argum
 [source code](src/jvmDemo/kotlin/DemoExtrude06.kt)
 
 ![DemoExtrude06Kt](https://raw.githubusercontent.com/openrndr/orx/media/orx-mesh-generators/images/DemoExtrude06Kt.png)
+
+### DemoHeightMapToMesh
+[source code](src/jvmDemo/kotlin/DemoHeightMapToMesh.kt)
+
+![DemoHeightMapToMeshKt](https://raw.githubusercontent.com/openrndr/orx/media/orx-mesh-generators/images/DemoHeightMapToMeshKt.png)

orx-mesh-generators/build.gradle.kts

@@ -2,24 +2,32 @@ plugins {
     org.openrndr.extra.convention.`kotlin-multiplatform`
 }
 
+val embedShaders = tasks.register<EmbedShadersTask>("embedShaders") {
+    inputDir.set(file("$projectDir/src/shaders/glsl"))
+    outputDir.set(layout.buildDirectory.dir("generated/shaderKotlin"))
+    defaultPackage.set("org.openrndr.extra.meshgenerators")
+    defaultVisibility.set("internal")
+    namePrefix.set("meshgenerators_")
+}.get()
+
 kotlin {
+    kotlin.sourceSets.getByName("commonMain").kotlin.srcDir(embedShaders.outputDir)
     sourceSets {
-        @Suppress("UNUSED_VARIABLE")
         val commonMain by getting {
             dependencies {
                 api(libs.openrndr.application)
                 api(libs.openrndr.math)
                 implementation(project(":orx-shapes"))
+                implementation(project(":orx-compute-shaders"))
             }
         }
-
-        @Suppress("UNUSED_VARIABLE")
         val jvmDemo by getting {
             dependencies {
                 implementation(project(":orx-shapes"))
                 implementation(project(":orx-mesh-generators"))
                 implementation(project(":orx-camera"))
                 implementation(project(":orx-noise"))
+                implementation(project(":orx-point-clouds"))
             }
         }
     }