Add VTarget.getBlob for memory-backed targets, improve docs (#83)

Author: lopcode

README.md

@@ -20,7 +20,7 @@ repositories {
 }
 
 dependencies {
-    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.11")
+    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.12")
 }
 ```
 When running your project you must add: `--enable-native-access=ALL-UNNAMED` to your JVM runtime arguments. If you

core/src/main/java/app/photofox/vipsffm/VTarget.java

@@ -1,5 +1,7 @@
 package app.photofox.vipsffm;
 
+import app.photofox.vipsffm.jextract.VipsTarget;
+
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
 
@@ -8,12 +10,14 @@
  */
 public class VTarget {
 
+    final Arena arena;
     final MemorySegment address;
 
-    VTarget(MemorySegment address) throws VipsError {
+    VTarget(Arena arena, MemorySegment address) throws VipsError {
         if (!VipsValidation.isValidPointer(address)) {
             throw new VipsError("invalid pointer used for creation");
         }
+        this.arena = arena;
         this.address = address;
     }
 
@@ -51,18 +55,40 @@ public MemorySegment getUnsafeStructAddress() {
         return this.address;
     }
 
-    public static VTarget newToDescriptor(Arena arena, int descriptor) {
+    /**
+     * Create a new target pointed at a file descriptor
+     * This target can be used with (for example) {@link VImage#writeToTarget(VTarget, String, VipsOption...)}
+     */
+    public static VTarget newToDescriptor(Arena arena, int descriptor) throws VipsError {
         var pointer = VipsHelper.target_new_to_descriptor(arena, descriptor);
-        return new VTarget(pointer);
+        return new VTarget(arena, pointer);
     }
 
-    public static VTarget newToFile(Arena arena, String filename) {
+    /**
+     * Create a new target pointed at an output file
+     * This target can be used with (for example) {@link VImage#writeToTarget(VTarget, String, VipsOption...)}
+     */
+    public static VTarget newToFile(Arena arena, String filename) throws VipsError {
         var pointer = VipsHelper.target_new_to_file(arena, filename);
-        return new VTarget(pointer);
+        return new VTarget(arena, pointer);
     }
 
-    public static VTarget newToMemory(Arena arena) {
+    /**
+     * Create a new memory-backed VipsTarget
+     * This target can be used with (for example) {@link VImage#writeToTarget(VTarget, String, VipsOption...)}
+     * After writing to this target, you can also retrieve the backing {@link VBlob} with {@link #getBlob()}
+     */
+    public static VTarget newToMemory(Arena arena) throws VipsError {
         var pointer = VipsHelper.target_new_to_memory(arena);
-        return new VTarget(pointer);
+        return new VTarget(arena, pointer);
+    }
+
+    /**
+     * Only valid for memory-backed targets (eg via {@link #newToMemory(Arena)})
+     * Returns the contents of the backing VBlob
+     */
+    public VBlob getBlob() throws VipsError {
+        var blob = VipsTarget.blob(this.address);
+        return new VBlob(arena, blob);
     }
 }

core/src/main/java/app/photofox/vipsffm/VipsInvoker.java

@@ -145,7 +145,7 @@ private static void readGValueAndSetOptionValue(
                 VipsRaw.g_object_get_property(operation, keyCString, gvaluePointer);
                 var vipsPointer = g_value_get_object(gvaluePointer);
                 vipsPointer = refGObjectToArenaScope(arena, vipsPointer);
-                var vipsObject = new VTarget(vipsPointer);
+                var vipsObject = new VTarget(arena, vipsPointer);
                 o.setValue(vipsObject);
             }
             case VipsOption.Blob o -> {

core/src/main/java/app/photofox/vipsffm/jextract/VipsConnection.java

@@ -0,0 +1,32 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsConnection {
+ *     VipsObject parent_object;
+ *     int descriptor;
+ *     int tracked_descriptor;
+ *     int close_descriptor;
+ *     char *filename;
+ * } VipsConnection
+ * }
+ */
+public class VipsConnection extends _VipsConnection {
+
+    VipsConnection() {
+        // Should not be called directly
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsConnectionClass.java

@@ -0,0 +1,28 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsConnectionClass {
+ *     VipsObjectClass parent_class;
+ * } VipsConnectionClass
+ * }
+ */
+public class VipsConnectionClass extends _VipsConnectionClass {
+
+    VipsConnectionClass() {
+        // Should not be called directly
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsObject.java

@@ -0,0 +1,26 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsObject VipsObject
+ * }
+ */
+public class VipsObject extends _VipsObject {
+
+    VipsObject() {
+        // Should not be called directly
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsObjectClass.java

@@ -0,0 +1,26 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsObjectClass VipsObjectClass
+ * }
+ */
+public class VipsObjectClass extends _VipsObjectClass {
+
+    VipsObjectClass() {
+        // Should not be called directly
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsObjectSetArguments.java

@@ -0,0 +1,70 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef void *(*VipsObjectSetArguments)(VipsObject *, void *, void *)
+ * }
+ */
+public class VipsObjectSetArguments {
+
+    VipsObjectSetArguments() {
+        // Should not be called directly
+    }
+
+    /**
+     * The function pointer signature, expressed as a functional interface
+     */
+    public interface Function {
+        MemorySegment apply(MemorySegment object, MemorySegment a, MemorySegment b);
+    }
+
+    private static final FunctionDescriptor $DESC = FunctionDescriptor.of(
+        VipsRaw.C_POINTER,
+        VipsRaw.C_POINTER,
+        VipsRaw.C_POINTER,
+        VipsRaw.C_POINTER
+    );
+
+    /**
+     * The descriptor of this function pointer
+     */
+    public static FunctionDescriptor descriptor() {
+        return $DESC;
+    }
+
+    private static final MethodHandle UP$MH = VipsRaw.upcallHandle(VipsObjectSetArguments.Function.class, "apply", $DESC);
+
+    /**
+     * Allocates a new upcall stub, whose implementation is defined by {@code fi}.
+     * The lifetime of the returned segment is managed by {@code arena}
+     */
+    public static MemorySegment allocate(VipsObjectSetArguments.Function fi, Arena arena) {
+        return Linker.nativeLinker().upcallStub(UP$MH.bindTo(fi), $DESC, arena);
+    }
+
+    private static final MethodHandle DOWN$MH = Linker.nativeLinker().downcallHandle($DESC);
+
+    /**
+     * Invoke the upcall stub {@code funcPtr}, with given parameters
+     */
+    public static MemorySegment invoke(MemorySegment funcPtr,MemorySegment object, MemorySegment a, MemorySegment b) {
+        try {
+            return (MemorySegment) DOWN$MH.invokeExact(funcPtr, object, a, b);
+        } catch (Throwable ex$) {
+            throw new AssertionError("should not reach here", ex$);
+        }
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsTarget.java

@@ -0,0 +1,37 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsTarget {
+ *     VipsConnection parent_object;
+ *     gboolean memory;
+ *     gboolean ended;
+ *     GString *memory_buffer;
+ *     VipsBlob *blob;
+ *     unsigned char output_buffer[8500];
+ *     int write_point;
+ *     gint64 position;
+ *     gboolean delete_on_close;
+ *     char *delete_on_close_filename;
+ * } VipsTarget
+ * }
+ */
+public class VipsTarget extends _VipsTarget {
+
+    VipsTarget() {
+        // Should not be called directly
+    }
+}
+

core/src/main/java/app/photofox/vipsffm/jextract/VipsTargetClass.java

@@ -0,0 +1,33 @@
+// Generated by jextract
+
+package app.photofox.vipsffm.jextract;
+
+import java.lang.invoke.*;
+import java.lang.foreign.*;
+import java.nio.ByteOrder;
+import java.util.*;
+import java.util.function.*;
+import java.util.stream.*;
+
+import static java.lang.foreign.ValueLayout.*;
+import static java.lang.foreign.MemoryLayout.PathElement.*;
+
+/**
+ * {@snippet lang=c :
+ * typedef struct _VipsTargetClass {
+ *     VipsConnectionClass parent_class;
+ *     gint64 (*write)(VipsTarget *, const void *, size_t);
+ *     void (*finish)(VipsTarget *);
+ *     gint64 (*read)(VipsTarget *, void *, size_t);
+ *     gint64 (*seek)(VipsTarget *, gint64, int);
+ *     int (*end)(VipsTarget *);
+ * } VipsTargetClass
+ * }
+ */
+public class VipsTargetClass extends _VipsTargetClass {
+
+    VipsTargetClass() {
+        // Should not be called directly
+    }
+}
+