From 9d68b75c5d0a4b8114c82c6b5cfb7ee63e61193a Mon Sep 17 00:00:00 2001
From: Abe Pazos <abe@hamoid.com>
Date: Sat, 15 Nov 2025 17:37:13 +0100
Subject: [PATCH] [orx-obj-loader] Add demo descriptions

---
 .../src/jvmDemo/kotlin/DemoObjCompoundRW01.kt   |  5 +++++
 .../src/jvmDemo/kotlin/DemoObjLoader01.kt       |  6 ++++++
 .../src/jvmDemo/kotlin/DemoObjSaver01.kt        |  6 ++++++
 .../src/jvmDemo/kotlin/DemoObjSaver02.kt        |  6 ++++++
 .../src/jvmDemo/kotlin/DemoWireframe01.kt       | 17 ++++++++++++++---
 5 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjCompoundRW01.kt b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjCompoundRW01.kt
index 6c4d806d..80b18423 100644
--- a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjCompoundRW01.kt
+++ b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjCompoundRW01.kt
@@ -5,6 +5,11 @@ import org.openrndr.extra.objloader.toObj
 import org.openrndr.math.Vector2
 import java.io.File
 
+/**
+ * This program loads an OBJ mesh as a CompoundMeshData and demonstrates
+ * how to convert it to a OBJ String representation, then
+ * draws the beginning of this String on the program window.
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjLoader01.kt b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjLoader01.kt
index cd642a18..36679483 100644
--- a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjLoader01.kt
+++ b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjLoader01.kt
@@ -6,6 +6,12 @@ import org.openrndr.draw.shadeStyle
 import org.openrndr.extra.objloader.loadOBJasVertexBuffer
 import org.openrndr.math.Vector3
 
+/**
+ * Demonstrates how to load a `.obj` file as a `VertexBuffer`.
+ *
+ * The `loadOBJasVertexBuffer()` function expects the path to the `.obj` file as an argument.
+ *
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver01.kt b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver01.kt
index 047fb842..e7d1e4e9 100644
--- a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver01.kt
+++ b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver01.kt
@@ -3,6 +3,12 @@ import org.openrndr.draw.loadFont
 import org.openrndr.extra.objloader.loadOBJasVertexBuffer
 import org.openrndr.extra.objloader.saveOBJ
 
+/**
+ * Demonstrates how to save a `VertexBuffer` as an `.obj` file using the
+ * `VertexBuffer.saveOBJ()` method.
+ *
+ * The program loads an existing OBJ file, then saves it with a new file name.
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver02.kt b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver02.kt
index 18820e11..a5a39645 100644
--- a/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver02.kt
+++ b/orx-obj-loader/src/jvmDemo/kotlin/DemoObjSaver02.kt
@@ -4,6 +4,12 @@ import org.openrndr.extra.meshgenerators.buildTriangleMesh
 import org.openrndr.extra.meshgenerators.sphere
 import org.openrndr.extra.objloader.saveOBJ
 
+/**
+ * Demonstrates saving a `VertexBuffer` generated via code as an OBJ file.
+ *
+ * This file can be loaded in a 3D modelling / rendering program.
+ *
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-obj-loader/src/jvmDemo/kotlin/DemoWireframe01.kt b/orx-obj-loader/src/jvmDemo/kotlin/DemoWireframe01.kt
index c8310dac..50ab0845 100644
--- a/orx-obj-loader/src/jvmDemo/kotlin/DemoWireframe01.kt
+++ b/orx-obj-loader/src/jvmDemo/kotlin/DemoWireframe01.kt
@@ -1,6 +1,3 @@
-/**
-Display wireframe and non-planar faces
- */
 import org.openrndr.WindowMultisample
 import org.openrndr.application
 import org.openrndr.color.ColorRGBa
@@ -16,6 +13,20 @@ import org.openrndr.shape.Path3D
 import java.io.File
 import kotlin.math.cos
 
+/**
+ * Demonstrates two approaches for loading an OBJ file: as a `VertexBuffer` and as `CompoundMeshData`.
+ *
+ * A `CompoundMeshData` object contains vertices, texture coordinates, colors, normals, tangents, and bitangents,
+ * alongside their associated face indices, grouped into meshes.
+ *
+ * In this demo `CompoundMeshData.wireframe()` is called to generate a wireframe representation of the loaded mesh.
+ *
+ * When rendering the wireframe, a shade style is used to displace the lines slightly towards the camera, to ensure
+ * the lines do not end up occluded by the mesh rendered as triangles.
+ *
+ * Finally, the `sub` method is called on the `Path3D` instances to draw only parts of the wireframe, creating
+ * an animated effect.
+ */
 fun main() = application {
     configure {
         width = 720