Fix signature of VCustomSource#SeekCallback (fixes #171)

Previously the offset was mistyped as a `*void`/`MemorySegment`. It was now
changed to be a `gint64`/`long`. Additionally, the `int whence`
parameter was replaced with a new `SeekWhence` enum that provides more
type safety and discoverability for implementers.

To test, a sample was added to provide `VCustomSource` based on a
`FileHandle` that implements seeking, testing it agains a TIF image.

Author: jbaiter

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

@@ -16,13 +16,55 @@ public final class VCustomSource extends VSource {
     @FunctionalInterface
     public interface ReadCallback {
 
+        /**
+         * Read data from the input and write it to the provided memory segment
+         *
+         * @param dataPointer Pointer to the memory segment where the data should be written
+         * @param length      The maximum number of bytes to read
+         * @return The number of bytes actually read, or -1 on error
+         */
         long read(MemorySegment dataPointer, long length);
     }
 
     @FunctionalInterface
     public interface SeekCallback {
 
-        long seek(int whence);
+        /**
+         * Seek to a specific position in the input
+         *
+         * @param offset Relative offset in bytes from the position specified by {@code whence}
+         * @param whence Where to seek from, one of {@link SeekWhence}
+         * @return the new position in the input, or -1 on error
+         */
+        long seek(long offset, SeekWhence whence);
+    }
+
+    public enum SeekWhence {
+        /** Seek from the beginning of the input */
+        SEEK_SET(0),
+        /** Seek from the current position in the input */
+        SEEK_CUR(1),
+        /** Seek from the end of the input */
+        SEEK_END(2);
+
+        private final int value;
+
+        public static SeekWhence fromValue(int value) {
+            return switch (value) {
+                case 0 -> SEEK_SET;
+                case 1 -> SEEK_CUR;
+                case 2 -> SEEK_END;
+                default -> throw new IllegalArgumentException("Unknown seek whence value: " + value);
+            };
+        }
+
+        SeekWhence(int value) {
+            this.value = value;
+        }
+
+        public int getValue() {
+            return value;
+        }
     }
 
     private final VCustomSource.ReadCallback readCallback;
@@ -39,7 +81,7 @@ public VCustomSource(
 
         attachReadSignal(arena, this);
         if (seekCallback != null) {
-            attachSeekSignal(arena, this, seekCallback);
+            attachSeekSignal(arena, this);
         }
     }
 
@@ -78,17 +120,17 @@ public long apply(
         }
     }
 
-    private void attachSeekSignal(Arena arena, VSource source, SeekCallback seekCallback) {
+    private void attachSeekSignal(Arena arena, VSource source) {
         var callback = new CustomStreamSeekCallback.Function() {
 
             @Override
             public long apply(
                 MemorySegment source,
-                MemorySegment data,
+                long offset,
                 int whence,
                 MemorySegment handle
             ) {
-                return seekCallback.seek(whence);
+                return seekCallback.seek(offset, SeekWhence.fromValue(whence));
             }
         };
         var callbackPointer = CustomStreamSeekCallback.allocate(callback, arena);

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

@@ -14,7 +14,7 @@
 
 /**
  * {@snippet lang=c :
- * typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *, void *, int, void *)
+ * typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *, gint64, int, void *)
  * }
  */
 public class CustomStreamSeekCallback {
@@ -27,13 +27,13 @@ public class CustomStreamSeekCallback {
      * The function pointer signature, expressed as a functional interface
      */
     public interface Function {
-        long apply(MemorySegment source, MemorySegment data, int whence, MemorySegment handle);
+        long apply(MemorySegment source, long offset, int whence, MemorySegment handle);
     }
 
     private static final FunctionDescriptor $DESC = FunctionDescriptor.of(
-        VipsRaw.C_LONG_LONG,
-        VipsRaw.C_POINTER,
+        VipsRaw.C_LONG,
         VipsRaw.C_POINTER,
+        VipsRaw.C_LONG,
         VipsRaw.C_INT,
         VipsRaw.C_POINTER
     );
@@ -60,9 +60,9 @@ public static MemorySegment allocate(CustomStreamSeekCallback.Function fi, Arena
     /**
      * Invoke the upcall stub {@code funcPtr}, with given parameters
      */
-    public static long invoke(MemorySegment funcPtr,MemorySegment source, MemorySegment data, int whence, MemorySegment handle) {
+    public static long invoke(MemorySegment funcPtr,MemorySegment source, long offset, int whence, MemorySegment handle) {
         try {
-            return (long) DOWN$MH.invokeExact(funcPtr, source, data, whence, handle);
+            return (long) DOWN$MH.invokeExact(funcPtr, source, offset, whence, handle);
         } catch (Throwable ex$) {
             throw new AssertionError("should not reach here", ex$);
         }

jextract_entry/callback_typedefs.h

@@ -1,6 +1,6 @@
 typedef gint64 (*CustomStreamReadCallback)(VipsSourceCustom *source, void *data, gint64 length, void *handle);
 
-typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *source, void *data, int whence, void *handle);
+typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *source, gint64 offset, int whence, void *handle);
 
 typedef gint64 (*CustomStreamWriteCallback)(VipsTargetCustom *source, void *data, gint64 length, void *handle);
 

sample/src/main/kotlin/vipsffm/SampleRunner.kt

@@ -13,6 +13,7 @@ import vipsffm.sample.VImageCachingSample
 import vipsffm.sample.VImageChainSample
 import vipsffm.sample.VImageCopyWriteSample
 import vipsffm.sample.VImageCreateThumbnailSample
+import vipsffm.sample.VImageCustomSourceTargetSample
 import vipsffm.sample.VImageFindTrimSample
 import vipsffm.sample.VImageFromBytesSample
 import vipsffm.sample.VImageGetPagesSample
@@ -55,7 +56,8 @@ object SampleRunner {
             HelperGetSetMetadataSample,
             VImageGetSetSample,
             VImageFindTrimSample,
-            VImageFromMemoryToMemorySample
+            VImageFromMemoryToMemorySample,
+            VImageCustomSourceTargetSample
         )
         val sampleParentRunPath = Paths.get("sample_run")
         if (Files.exists(sampleParentRunPath)) {

sample/src/main/kotlin/vipsffm/sample/VImageCustomSourceTargetSample.kt

@@ -0,0 +1,87 @@
+package vipsffm.sample
+
+import app.photofox.vipsffm.VCustomSource
+import app.photofox.vipsffm.VCustomTarget
+import app.photofox.vipsffm.VImage
+import vipsffm.RunnableSample
+import vipsffm.SampleHelper
+import java.io.IOException
+import java.lang.foreign.Arena
+import java.lang.foreign.MemorySegment
+import java.nio.channels.FileChannel
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardOpenOption
+import java.util.function.Consumer
+
+/**
+ * Sample showing loading an image from a custom source and writing it to a custom source.
+ *
+ * Implemented using `FileChannel` for reading and writing, which is of little practical use but
+ * demonstrates the use of custom sources and targets quite well.
+ *
+ * See https://www.libvips.org/2019/11/29/True-streaming-for-libvips.html
+ */
+object VImageCustomSourceTargetSample: RunnableSample {
+    internal class FileChannelSource {
+        val input: FileChannel
+
+        constructor(path: Path) {
+            this.input = FileChannel.open(path, StandardOpenOption.READ)
+        }
+
+        fun read(buffer: MemorySegment, length: Long): Long {
+            val byteBuffer = buffer.asSlice(0, length).asByteBuffer()
+            return input.read(byteBuffer).toLong()
+        }
+
+        fun seek(offset: Long, whence: VCustomSource.SeekWhence): Long {
+            return when (whence) {
+                VCustomSource.SeekWhence.SEEK_SET -> input.position(offset)
+                VCustomSource.SeekWhence.SEEK_CUR -> input.position(input.position() + offset)
+                VCustomSource.SeekWhence.SEEK_END -> input.position(input.size() + offset)
+            }.position()
+        }
+
+        fun close() {
+            input.close()
+        }
+    }
+
+    class FileChannelTarget {
+        private val output: FileChannel
+
+        constructor(path: Path) {
+            this.output = FileChannel.open(path, StandardOpenOption.WRITE, StandardOpenOption.CREATE)
+        }
+
+        fun write(buffer: MemorySegment): Long {
+            return output.write(buffer.asByteBuffer()).toLong()
+        }
+
+        fun end(): Int {
+            output.close()
+            return 0
+        }
+    }
+
+    override fun run(arena: Arena, workingDirectory: Path): Result<Unit> {
+        val outputPath = workingDirectory.resolve("fox_copy.jpg")
+        val inputPath = workingDirectory.resolve("fox_input.tif")
+        Files.copy(ClassLoader.getSystemResourceAsStream("sample_images/fox.tif"), inputPath)
+
+        val src = FileChannelSource(inputPath)
+        val vipsSrc = VCustomSource(arena, src::read, src::seek)
+
+        val target = FileChannelTarget(outputPath)
+        val vipsTarget = VCustomTarget(arena, target::write, target::end)
+
+        VImage.thumbnailSource(arena, vipsSrc, 800)
+            .writeToTarget(vipsTarget, ".jpg")
+
+        return SampleHelper.validate(
+            outputPath,
+            expectedSizeBoundsKb = 20..100L
+        )
+    }
+}