Add an output pointer helper, reconcile method generators (#24)

README.md

@@ -40,15 +40,19 @@ To get set up to run samples (on macOS):
 
 ```
 [main] INFO vipsffm.VipsFfm - clearing sample run directory at path "sample_run"
-[main] INFO vipsffm.VipsFfm - running sample "GetVersionSample"...
-[main] INFO vipsffm.GetVersionSample - libvips version: "8.15.2"
+[main] INFO vipsffm.VipsFfm - running sample "RawGetVersionSample"...
+[main] INFO vipsffm.RawGetVersionSample - libvips version: "8.15.2"
+[main] INFO vipsffm.VipsFfm - validation succeeded ✅
+[main] INFO vipsffm.VipsFfm - running sample "HelperGetVersionSample"...
+[main] INFO vipsffm.HelperGetVersionSample - libvips version: "8.15.2"
 [main] INFO vipsffm.VipsFfm - validation succeeded ✅
 [main] INFO vipsffm.VipsFfm - running sample "RawCreateThumbnailSample"...
-[main] INFO vipsffm.GetVersionSample - source image size: 2490 x 3084
-[main] INFO vipsffm.GetVersionSample - output image size: 323 x 400
+[main] INFO vipsffm.RawGetVersionSample - source image size: 2490 x 3084
+[main] INFO vipsffm.RawGetVersionSample - output image size: 323 x 400
 [main] INFO vipsffm.VipsFfm - validation succeeded ✅
 [main] INFO vipsffm.VipsFfm - running sample "HelperCreateThumbnailSample"...
-[main] INFO vipsffm.GetVersionSample - source image size: 2490 x 3084
+[main] INFO vipsffm.RawGetVersionSample - source image size: 2490 x 3084
+[main] INFO vipsffm.RawGetVersionSample - thumbnail image size: 323 x 400
 [main] INFO vipsffm.VipsFfm - validation succeeded ✅
 [main] INFO vipsffm.VipsFfm - all samples ran successfully 🎉
 ```
@@ -75,7 +79,9 @@ Arena.ofConfined().use { arena ->
     val outputPath = workingDirectory.resolve("rabbit_copy.jpg")
     vips.imageWriteToFile(sourceImage, outputPath.absolutePathString())
 
-    val thumbnailImage = vips.thumbnail("sample/src/main/resources/sample_images/rabbit.jpg", 400)
+    val outputImagePointer = VipsOutputPointer(arena)
+    vips.thumbnail("sample/src/main/resources/sample_images/rabbit.jpg", outputImagePointer, 400)
+    val thumbnailImage = outputImagePointer.dereferencedOrThrow()
     val thumbnailPath = workingDirectory.resolve("rabbit_thumbnail_400.jpg")
     vips.imageWriteToFile(thumbnailImage, thumbnailPath.absolutePathString())
 

core/src/main/java/app/photofox/vipsffm/helper/VipsOutputPointer.java

@@ -0,0 +1,41 @@
+package app.photofox.vipsffm.helper;
+
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+
+// models output pointers in vips functions (eg VipsImage **out)
+public class VipsOutputPointer {
+
+    private final MemorySegment outPointer;
+    private MemorySegment dereferencedPointer;
+
+    public VipsOutputPointer(Arena arena) {
+        this.outPointer = arena.allocate(ValueLayout.ADDRESS);
+    }
+
+    // internal - do not use
+    public MemorySegment pointerOrNull$internal() {
+        return this.outPointer;
+    }
+
+    // internal - do not use
+    public void setReinterpretedPointer$internal(MemorySegment reinterpretedPointer) {
+        this.dereferencedPointer = reinterpretedPointer;
+    }
+
+    public MemorySegment dereferencedOrNull() {
+        if (!VipsValidation.isValidPointer(this.dereferencedPointer)) {
+            return null;
+        }
+        return this.dereferencedPointer;
+    }
+
+    public MemorySegment dereferencedOrThrow() throws VipsError {
+        var dereferencedPointer = this.dereferencedOrNull();
+        if (dereferencedPointer == null) {
+            throw new VipsError("dereferenced output pointer unexpectedly null");
+        }
+        return dereferencedPointer;
+    }
+}

core/src/main/java/app/photofox/vipsffm/helper/VipsValidation.java

@@ -7,6 +7,9 @@
 public class VipsValidation {
 
     public static boolean isValidPointer(MemorySegment memorySegment) {
+        if (memorySegment == null) {
+            return false;
+        }
         return memorySegment != MemorySegment.NULL && memorySegment.address() != 0;
     }