Add capture method to CaptureStream to retrieve frames as BufferedImage

Author: doblon8

src/main/java/io/github/doblon8/openpnp/capture/CaptureDevice.java

@@ -41,7 +41,7 @@ public CaptureStream openStream(CaptureFormat format) {
         if (streamId == -1) {
             throw new CaptureException("Error opening capture stream: " + streamId);
         }
-        return new CaptureStream(context, streamId);
+        return new CaptureStream(context, streamId, format);
     }
 
     /**

src/main/java/io/github/doblon8/openpnp/capture/CaptureStream.java

@@ -1,15 +1,57 @@
 package io.github.doblon8.openpnp.capture;
 
-import static io.github.doblon8.openpnp.capture.bindings.openpnp_capture.Cap_closeStream;
-import static io.github.doblon8.openpnp.capture.bindings.openpnp_capture.Cap_isOpenStream;
+import java.awt.image.BufferedImage;
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+
+import static io.github.doblon8.openpnp.capture.bindings.openpnp_capture.*;
 
 public class CaptureStream implements AutoCloseable {
     private final CaptureContext context;
     private final int id;
+    private final CaptureFormat format;
 
-    public CaptureStream(CaptureContext context, int id) {
+    public CaptureStream(CaptureContext context, int id, CaptureFormat format) {
         this.context = context;
         this.id = id;
+        this.format = format;
+    }
+
+    /**
+     * Capture a single frame from the stream and return it as a BufferedImage.
+     *
+     * @return a BufferedImage containing the captured frame.
+     */
+    public BufferedImage capture() {
+        int width = format.info().width();
+        int height = format.info().height();
+        byte[] bytes;
+
+        try (Arena arena = Arena.ofConfined()) {
+            int numBytes = width * height * 3; // 3 bytes per pixel for each of R, G, and B channels
+            MemorySegment bufferPointer = arena.allocate(ValueLayout.JAVA_BYTE, numBytes);
+
+            int result = Cap_captureFrame(context.getSegment(), id, bufferPointer, numBytes);
+            CaptureResult captureResult = CaptureResult.values()[result];
+            if (captureResult != CaptureResult.OK) {
+                throw new CaptureException("Error capturing frame: " + result);
+            }
+            bytes = bufferPointer.toArray(ValueLayout.JAVA_BYTE);
+        }
+
+        // Note: openpnp-capture documentation says that frames are always 24-bit RGB:
+        // https://github.com/openpnp/openpnp-capture/blob/32a9bdd3e8e3a31b12cb6573e7c6076208421651/include/openpnp-capture.h#L192-L202
+        // However, the original JNI-based openpnp-capture-java uses TYPE_3BYTE_BGR:
+        // https://github.com/openpnp/openpnp-capture-java/blob/06504247a2688d0258f46cb4d7e451cb9715d241/src/main/java/org/openpnp/capture/CaptureStream.java#L102-L109
+        // noting that the expected R/B swap did not occur, and that the comment's author thinks it's because
+        // setDataElements converts to the BufferedImage's color model, but I don't think that is the case.
+        // I just think that the openpnp-capture documentation might be wrong, as the openpnp-capture-java code seems to
+        // have been working correctly in practice.
+        // So I'll the same approach as openpnp-capture-java.
+        BufferedImage image = new BufferedImage(width, height, BufferedImage.TYPE_3BYTE_BGR);
+        image.getRaster().setDataElements(0, 0, width, height, bytes);
+        return image;
     }
 
     /**

src/main/java/module-info.java

@@ -1,3 +1,4 @@
 module io.github.doblon8.openpnp.capture {
+    requires java.desktop;
     exports io.github.doblon8.openpnp.capture;
 }