teek 0.1.0 → 0.1.2

data/ext/teek/tkeventsource.c

@@ -0,0 +1,195 @@
+/*
+ * tkeventsource.c - External event source integration via Tcl_CreateEventSource
+ *
+ * Allows other C extensions (e.g. teek-sdl2) to register poll callbacks
+ * that run inside Tcl's event loop with zero Ruby overhead in the hot path.
+ *
+ * The consumer passes a C function pointer via a Ruby method call at
+ * registration time. The Tcl event source setup/check procs call that
+ * pointer directly — no rb_funcall, no method dispatch.
+ */
+
+#include "tcltkbridge.h"
+#include <stdint.h>
+
+static VALUE cEventSource;
+
+/* ---------------------------------------------------------
+ * Event source struct — wrapped as Ruby TypedData
+ * --------------------------------------------------------- */
+
+typedef void (*event_source_check_fn)(void *client_data);
+
+struct event_source {
+    event_source_check_fn check_fn;  /* C function pointer from consumer */
+    void *client_data;               /* Opaque data from consumer */
+    Tcl_Time max_block;              /* Max block time for setup proc */
+    int registered;                  /* Whether Tcl event source is active */
+};
+
+/* Forward declarations */
+static void es_setup_proc(ClientData cd, int flags);
+static void es_check_proc(ClientData cd, int flags);
+
+/* ---------------------------------------------------------
+ * TypedData functions
+ * --------------------------------------------------------- */
+
+static void
+event_source_free(void *ptr)
+{
+    struct event_source *es = ptr;
+    if (es->registered) {
+        Tcl_DeleteEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+        es->registered = 0;
+    }
+    xfree(es);
+}
+
+static size_t
+event_source_memsize(const void *ptr)
+{
+    return sizeof(struct event_source);
+}
+
+static const rb_data_type_t event_source_type = {
+    .wrap_struct_name = "Teek::EventSource",
+    .function = {
+        .dmark = NULL,  /* No Ruby VALUEs to mark */
+        .dfree = event_source_free,
+        .dsize = event_source_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/* ---------------------------------------------------------
+ * Tcl event source callbacks (hot path — pure C)
+ * --------------------------------------------------------- */
+
+/*
+ * Setup proc: called before Tcl_WaitForEvent.
+ * Caps the block time so our check proc runs frequently.
+ */
+static void
+es_setup_proc(ClientData cd, int flags)
+{
+    struct event_source *es = (struct event_source *)cd;
+
+    if (!(flags & TCL_FILE_EVENTS) && !(flags & TCL_ALL_EVENTS))
+        return;
+
+    Tcl_SetMaxBlockTime(&es->max_block);
+}
+
+/*
+ * Check proc: called after Tcl_WaitForEvent returns.
+ * Calls the consumer's C function pointer directly.
+ * No rb_funcall, no Ruby method dispatch — just a function pointer call.
+ */
+static void
+es_check_proc(ClientData cd, int flags)
+{
+    struct event_source *es = (struct event_source *)cd;
+
+    if (!(flags & TCL_FILE_EVENTS) && !(flags & TCL_ALL_EVENTS))
+        return;
+
+    es->check_fn(es->client_data);
+}
+
+/* ---------------------------------------------------------
+ * Ruby methods
+ * --------------------------------------------------------- */
+
+/*
+ * Teek._register_event_source(check_fn_ptr, client_data_ptr, interval_ms) -> EventSource
+ *
+ * Registers a C function as a Tcl event source. The function will be called
+ * on every event loop iteration with no Ruby overhead.
+ *
+ * check_fn_ptr:    Integer — address of a C function with signature void(*)(void*)
+ * client_data_ptr: Integer — address passed to check_fn (0 for NULL)
+ * interval_ms:     Integer — max block time in ms (e.g. 16 for ~60fps)
+ *
+ * Returns an opaque EventSource object. Hold a reference to keep it alive.
+ * Call #unregister or let GC collect it to remove the event source.
+ */
+static VALUE
+teek_register_event_source(VALUE self, VALUE fn_ptr, VALUE data_ptr, VALUE interval)
+{
+    struct event_source *es;
+    VALUE obj;
+    int ms;
+
+    /* Validate */
+    event_source_check_fn fn = (event_source_check_fn)(uintptr_t)NUM2ULL(fn_ptr);
+    if (!fn) {
+        rb_raise(rb_eArgError, "check_fn_ptr must not be NULL");
+    }
+
+    ms = NUM2INT(interval);
+    if (ms < 1) ms = 1;
+
+    /* Allocate and populate */
+    obj = TypedData_Make_Struct(cEventSource, struct event_source, &event_source_type, es);
+    es->check_fn = fn;
+    es->client_data = (void *)(uintptr_t)NUM2ULL(data_ptr);
+    es->max_block.sec = ms / 1000;
+    es->max_block.usec = (ms % 1000) * 1000;
+    es->registered = 0;
+
+    /* Register with Tcl */
+    Tcl_CreateEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+    es->registered = 1;
+
+    return obj;
+}
+
+/*
+ * EventSource#unregister -> nil
+ *
+ * Explicitly removes the event source from Tcl's notifier.
+ * Safe to call multiple times.
+ */
+static VALUE
+event_source_unregister(VALUE self)
+{
+    struct event_source *es;
+    TypedData_Get_Struct(self, struct event_source, &event_source_type, es);
+
+    if (es->registered) {
+        Tcl_DeleteEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+        es->registered = 0;
+    }
+    return Qnil;
+}
+
+/*
+ * EventSource#registered? -> true/false
+ */
+static VALUE
+event_source_registered_p(VALUE self)
+{
+    struct event_source *es;
+    TypedData_Get_Struct(self, struct event_source, &event_source_type, es);
+    return es->registered ? Qtrue : Qfalse;
+}
+
+/* ---------------------------------------------------------
+ * Init — called from Init_tcltklib
+ * --------------------------------------------------------- */
+
+static VALUE cEventSource;
+
+void
+Init_tkeventsource(VALUE mTeek)
+{
+    cEventSource = rb_define_class_under(mTeek, "EventSource", rb_cObject);
+    rb_undef_alloc_func(cEventSource);  /* No Ruby-side new */
+
+    rb_define_method(cEventSource, "unregister", event_source_unregister, 0);
+    rb_define_method(cEventSource, "registered?", event_source_registered_p, 0);
+
+    rb_define_module_function(mTeek, "_register_event_source",
+                             teek_register_event_source, 3);
+}

data/ext/teek/tkphoto.c

@@ -1,4 +1,4 @@
-/* tkphoto.c - Photo image C functions for tk-ng
+/* tkphoto.c - Photo image C functions for teek
  *
  * Fast pixel manipulation using Tk's photo image C API.
  * These functions bypass Tcl string parsing for better performance.
@@ -18,8 +18,9 @@
  *   width      - Image width in pixels
  *   height     - Image height in pixels
  *   opts       - Optional hash:
- *                :x, :y    - destination offsets (default 0,0)
- *                :format   - :rgba (default) or :argb
+ *                :x, :y       - destination offsets (default 0,0)
+ *                :format      - :rgba (default) or :argb
+ *                :composite   - :set (default, overwrite) or :overlay (alpha blend)
  *
  * The pixel_data must be exactly width * height * 4 bytes.
  *
@@ -38,6 +39,7 @@ interp_photo_put_block(int argc, VALUE *argv, VALUE self)
     Tk_PhotoImageBlock block;
     int width, height, x_off, y_off;
     int is_argb = 0;
+    int comp_rule = TK_PHOTO_COMPOSITE_SET;
     long expected_size;
 
     rb_scan_args(argc, argv, "41", &photo_path, &pixel_data, &width_val, &height_val, &opts);
@@ -74,6 +76,12 @@ interp_photo_put_block(int argc, VALUE *argv, VALUE self)
                 is_argb = 1;
             }
         }
+        val = rb_hash_aref(opts, ID2SYM(rb_intern("composite")));
+        if (!NIL_P(val) && TYPE(val) == T_SYMBOL) {
+            if (rb_intern("overlay") == SYM2ID(val)) {
+                comp_rule = TK_PHOTO_COMPOSITE_OVERLAY;
+            }
+        }
     }
 
     /* Find the photo image by Tcl path */
@@ -105,7 +113,7 @@ interp_photo_put_block(int argc, VALUE *argv, VALUE self)
 
     /* Write pixels to the photo image */
     if (Tk_PhotoPutBlock(tip->interp, photo, &block, x_off, y_off,
-                         width, height, TK_PHOTO_COMPOSITE_SET) != TCL_OK) {
+                         width, height, comp_rule) != TCL_OK) {
         rb_raise(eTclError, "Tk_PhotoPutBlock failed: %s",
                  Tcl_GetStringResult(tip->interp));
     }
@@ -129,6 +137,7 @@ interp_photo_put_block(int argc, VALUE *argv, VALUE self)
  *                :zoom_x, :zoom_y       - zoom factors (default 1,1)
  *                :subsample_x, :subsample_y - subsample factors (default 1,1)
  *                :format       - :rgba (default) or :argb
+ *                :composite    - :set (default, overwrite) or :overlay (alpha blend)
  *
  * The pixel_data must be exactly width * height * 4 bytes.
  * Zoom replicates pixels (zoom=3 makes each pixel 3x3).
@@ -151,6 +160,7 @@ interp_photo_put_zoomed_block(int argc, VALUE *argv, VALUE self)
     int zoom_x, zoom_y, subsample_x, subsample_y;
     int dest_width, dest_height;
     int is_argb = 0;
+    int comp_rule = TK_PHOTO_COMPOSITE_SET;
     long expected_size;
 
     rb_scan_args(argc, argv, "41", &photo_path, &pixel_data, &width_val, &height_val, &opts);
@@ -200,6 +210,12 @@ interp_photo_put_zoomed_block(int argc, VALUE *argv, VALUE self)
                 is_argb = 1;
             }
         }
+        val = rb_hash_aref(opts, ID2SYM(rb_intern("composite")));
+        if (!NIL_P(val) && TYPE(val) == T_SYMBOL) {
+            if (rb_intern("overlay") == SYM2ID(val)) {
+                comp_rule = TK_PHOTO_COMPOSITE_OVERLAY;
+            }
+        }
     }
 
     /* Validate zoom/subsample */
@@ -245,7 +261,7 @@ interp_photo_put_zoomed_block(int argc, VALUE *argv, VALUE self)
     if (Tk_PhotoPutZoomedBlock(tip->interp, photo, &block, x_off, y_off,
                                dest_width, dest_height,
                                zoom_x, zoom_y, subsample_x, subsample_y,
-                               TK_PHOTO_COMPOSITE_SET) != TCL_OK) {
+                               comp_rule) != TCL_OK) {
         rb_raise(eTclError, "Tk_PhotoPutZoomedBlock failed: %s",
                  Tcl_GetStringResult(tip->interp));
     }
@@ -460,6 +476,151 @@ interp_photo_blank(VALUE self, VALUE photo_path)
     return Qnil;
 }
 
+/* ---------------------------------------------------------
+ * Interp#photo_set_size(photo_path, width, height)
+ *
+ * Set the dimensions of a photo image using Tk_PhotoSetSize.
+ *
+ * Arguments:
+ *   photo_path - Tcl path of the photo image
+ *   width      - New width in pixels
+ *   height     - New height in pixels
+ *
+ * Returns nil.
+ *
+ * See: https://www.tcl-lang.org/man/tcl8.6/TkLib/FindPhoto.htm
+ * --------------------------------------------------------- */
+
+static VALUE
+interp_photo_set_size(VALUE self, VALUE photo_path, VALUE width_val, VALUE height_val)
+{
+    struct tcltk_interp *tip = get_interp(self);
+    Tk_PhotoHandle photo;
+    int width, height;
+
+    StringValue(photo_path);
+    width = NUM2INT(width_val);
+    height = NUM2INT(height_val);
+
+    if (width < 0 || height < 0) {
+        rb_raise(rb_eArgError, "width and height must be non-negative");
+    }
+
+    photo = Tk_FindPhoto(tip->interp, StringValueCStr(photo_path));
+    if (!photo) {
+        rb_raise(eTclError, "photo image not found: %s", StringValueCStr(photo_path));
+    }
+
+    if (Tk_PhotoSetSize(tip->interp, photo, width, height) != TCL_OK) {
+        rb_raise(eTclError, "Tk_PhotoSetSize failed: %s",
+                 Tcl_GetStringResult(tip->interp));
+    }
+
+    return Qnil;
+}
+
+/* ---------------------------------------------------------
+ * Interp#photo_expand(photo_path, width, height)
+ *
+ * Expand a photo image to at least the given dimensions using Tk_PhotoExpand.
+ * Will not shrink the image if it is already larger.
+ *
+ * Arguments:
+ *   photo_path - Tcl path of the photo image
+ *   width      - Minimum width in pixels
+ *   height     - Minimum height in pixels
+ *
+ * Returns nil.
+ *
+ * See: https://www.tcl-lang.org/man/tcl8.6/TkLib/FindPhoto.htm
+ * --------------------------------------------------------- */
+
+static VALUE
+interp_photo_expand(VALUE self, VALUE photo_path, VALUE width_val, VALUE height_val)
+{
+    struct tcltk_interp *tip = get_interp(self);
+    Tk_PhotoHandle photo;
+    int width, height;
+
+    StringValue(photo_path);
+    width = NUM2INT(width_val);
+    height = NUM2INT(height_val);
+
+    if (width < 0 || height < 0) {
+        rb_raise(rb_eArgError, "width and height must be non-negative");
+    }
+
+    photo = Tk_FindPhoto(tip->interp, StringValueCStr(photo_path));
+    if (!photo) {
+        rb_raise(eTclError, "photo image not found: %s", StringValueCStr(photo_path));
+    }
+
+    if (Tk_PhotoExpand(tip->interp, photo, width, height) != TCL_OK) {
+        rb_raise(eTclError, "Tk_PhotoExpand failed: %s",
+                 Tcl_GetStringResult(tip->interp));
+    }
+
+    return Qnil;
+}
+
+/* ---------------------------------------------------------
+ * Interp#photo_get_pixel(photo_path, x, y)
+ *
+ * Read a single pixel from a photo image using Tk_PhotoGetImage.
+ * Faster than going through Tcl's "$photo get x y" string parsing.
+ *
+ * Arguments:
+ *   photo_path - Tcl path of the photo image
+ *   x          - X coordinate
+ *   y          - Y coordinate
+ *
+ * Returns [r, g, b, a] array.
+ *
+ * See: https://www.tcl-lang.org/man/tcl8.6/TkLib/FindPhoto.htm
+ * --------------------------------------------------------- */
+
+static VALUE
+interp_photo_get_pixel(VALUE self, VALUE photo_path, VALUE x_val, VALUE y_val)
+{
+    struct tcltk_interp *tip = get_interp(self);
+    Tk_PhotoHandle photo;
+    Tk_PhotoImageBlock block;
+    int x, y;
+    unsigned char *src;
+    int r_off, g_off, b_off, a_off;
+
+    StringValue(photo_path);
+    x = NUM2INT(x_val);
+    y = NUM2INT(y_val);
+
+    photo = Tk_FindPhoto(tip->interp, StringValueCStr(photo_path));
+    if (!photo) {
+        rb_raise(eTclError, "photo image not found: %s", StringValueCStr(photo_path));
+    }
+
+    if (!Tk_PhotoGetImage(photo, &block)) {
+        rb_raise(eTclError, "failed to get photo image data");
+    }
+
+    if (x < 0 || x >= block.width || y < 0 || y >= block.height) {
+        rb_raise(rb_eArgError, "coordinates (%d, %d) outside image bounds (%d x %d)",
+                 x, y, block.width, block.height);
+    }
+
+    r_off = block.offset[0];
+    g_off = block.offset[1];
+    b_off = block.offset[2];
+    a_off = block.offset[3];
+
+    src = block.pixelPtr + y * block.pitch + x * block.pixelSize;
+
+    return rb_ary_new_from_args(4,
+        INT2FIX(src[r_off]),
+        INT2FIX(src[g_off]),
+        INT2FIX(src[b_off]),
+        INT2FIX((block.pixelSize >= 4) ? src[a_off] : 255));
+}
+
 /* ---------------------------------------------------------
  * Init_tkphoto - Register photo image methods on Teek::Interp class
  *
@@ -473,5 +634,8 @@ Init_tkphoto(VALUE cInterp)
     rb_define_method(cInterp, "photo_put_zoomed_block", interp_photo_put_zoomed_block, -1);
     rb_define_method(cInterp, "photo_get_image", interp_photo_get_image, -1);
     rb_define_method(cInterp, "photo_get_size", interp_photo_get_size, 1);
+    rb_define_method(cInterp, "photo_set_size", interp_photo_set_size, 3);
+    rb_define_method(cInterp, "photo_expand", interp_photo_expand, 3);
+    rb_define_method(cInterp, "photo_get_pixel", interp_photo_get_pixel, 3);
     rb_define_method(cInterp, "photo_blank", interp_photo_blank, 1);
 }

data/ext/teek/tkwin.c

@@ -5,6 +5,21 @@
  */
 
 #include "tcltkbridge.h"
+#include <stdint.h>
+
+#ifdef __APPLE__
+/*
+ * Platform stubs for macOS. Tk_InitStubs sets up tkStubsPtr but
+ * tkPlatStubsPtr needs to be pulled from the hooks table.
+ * MAC_OSX_TK is needed for tkPlatDecls.h to expose macOS APIs.
+ */
+#ifndef MAC_OSX_TK
+#define MAC_OSX_TK
+#endif
+#include "tkPlatDecls.h"
+#elif defined(_WIN32) || defined(__CYGWIN__)
+#include "tkPlatDecls.h"
+#endif
 
 /* ---------------------------------------------------------
  * Interp#user_inactive_time
@@ -129,6 +144,74 @@ interp_coords_to_window(VALUE self, VALUE root_x, VALUE root_y)
     return rb_utf8_str_new_cstr(pathName);
 }
 
+/* ---------------------------------------------------------
+ * Interp#native_window_handle(window_path)
+ *
+ * Returns the platform-native window handle for SDL2 embedding.
+ *
+ *   macOS:   NSWindow* (via Tk_MacOSXGetNSWindowForDrawable)
+ *   X11:     X Window ID (via Tk_WindowId)
+ *   Windows: HWND (via Tk_GetHWND)
+ *
+ * The return value is an Integer suitable for passing to
+ * SDL_CreateWindowFrom. On macOS this is a pointer to an
+ * NSWindow object; on X11/Windows it's a window identifier.
+ *
+ * The window must be mapped (visible) before calling this.
+ * Use `update_idletasks` first to ensure geometry is committed.
+ * --------------------------------------------------------- */
+
+static VALUE
+interp_native_window_handle(VALUE self, VALUE window_path)
+{
+    struct tcltk_interp *tip = get_interp(self);
+    Tk_Window mainWin;
+    Tk_Window tkwin;
+    Drawable drawable;
+
+    StringValue(window_path);
+
+    mainWin = Tk_MainWindow(tip->interp);
+    if (!mainWin) {
+        rb_raise(eTclError, "Tk not initialized (no main window)");
+    }
+
+    tkwin = Tk_NameToWindow(tip->interp, StringValueCStr(window_path), mainWin);
+    if (!tkwin) {
+        rb_raise(eTclError, "window not found: %s", StringValueCStr(window_path));
+    }
+
+    /* Force the window to be mapped so we get a valid native handle */
+    Tk_MakeWindowExist(tkwin);
+
+    drawable = Tk_WindowId(tkwin);
+    if (!drawable) {
+        rb_raise(eTclError, "window has no native handle (not mapped?): %s",
+                 StringValueCStr(window_path));
+    }
+
+#ifdef __APPLE__
+    {
+        /* macOS: convert Tk drawable to NSWindow* for SDL2 */
+        void *nswindow = Tk_MacOSXGetNSWindowForDrawable(drawable);
+        if (!nswindow) {
+            rb_raise(eTclError, "could not get NSWindow for: %s",
+                     StringValueCStr(window_path));
+        }
+        return ULL2NUM((uintptr_t)nswindow);
+    }
+#elif defined(_WIN32) || defined(__CYGWIN__)
+    {
+        /* Windows: convert to HWND */
+        HWND hwnd = Tk_GetHWND(drawable);
+        return ULL2NUM((uintptr_t)hwnd);
+    }
+#else
+    /* X11: Drawable is already the X Window ID */
+    return ULL2NUM((uintptr_t)drawable);
+#endif
+}
+
 /* ---------------------------------------------------------
  * Init_tkwin - Register Tk window query methods on Interp
  *
@@ -141,4 +224,5 @@ Init_tkwin(VALUE cInterp)
     rb_define_method(cInterp, "user_inactive_time", interp_user_inactive_time, 0);
     rb_define_method(cInterp, "get_root_coords", interp_get_root_coords, 1);
     rb_define_method(cInterp, "coords_to_window", interp_coords_to_window, 2);
+    rb_define_method(cInterp, "native_window_handle", interp_native_window_handle, 1);
 }

data/lib/teek/background_ractor4x.rb

@@ -153,13 +153,21 @@ module Teek
       # @return [self]
       def close
         @done = true
-        @control_port = nil  # Prevent further message sends
+        # Send stop to let the worker terminate itself — Ruby 4.x doesn't
+        # allow closing a Ractor from outside. The message thread will
+        # raise StopIteration on the Ractor's main thread, which triggers
+        # the rescue block that sends [:done] to the output port and exits
+        # the Ractor cleanly.
         begin
-          @worker_ractor&.close_incoming
-          @worker_ractor&.close_outgoing
+          @control_port&.send(:stop)
         rescue Ractor::ClosedError
           # Already closed
         end
+        @control_port = nil
+        # Wait for the bridge thread to receive [:done] and exit. Without
+        # this, the zombie bridge thread blocks subsequent operations on
+        # Windows (Ractor::Port#receive holds the GVL).
+        @bridge_thread&.join(2)
         self
       end
 
@@ -173,7 +181,17 @@ module Teek
 
         # Wrap in isolated proc for Ractor sharing. The block can only access
         # its parameters (task, data), not outer-scope variables.
-        shareable_block = Ractor.shareable_proc(&@work_block)
+        isolation_error = false
+        begin
+          shareable_block = Ractor.shareable_proc(&@work_block)
+        rescue Ractor::IsolationError
+          isolation_error = true
+        end
+        if isolation_error
+          raise Ractor::IsolationError,
+            "Background work block must not reference outside variables (including `app`). " \
+            "Use t.yield() to send results to on_progress, which runs on the main thread."
+        end
 
         start_ractor(shareable_block)
         start_polling
@@ -201,6 +219,7 @@ module Teek
         output_port = Ractor::Port.new
 
         @worker_ractor = Ractor.new(data, output_port, shareable_block) do |d, out, blk|
+          # :nocov: -- Coverage.so cannot observe execution inside a Ractor
           # Worker creates its own control port for receiving messages
           control_port = Ractor::Port.new
           msg_queue = Thread::Queue.new
@@ -208,13 +227,20 @@ module Teek
           # Send control port back to main thread
           out.send([:control_port, control_port])
 
-          # Background thread receives from control port, forwards to queue
+          # Background thread receives from control port, forwards to queue.
+          # On :stop, interrupts the main Ractor thread with StopIteration
+          # (the main block may never call check_message) and signals the
+          # bridge thread via [:done] on the output port.
+          main_thread = Thread.current
           Thread.new do
             loop do
               begin
                 msg = control_port.receive
                 msg_queue << msg
-                break if msg == :stop
+                if msg == :stop
+                  main_thread.raise(StopIteration)
+                  break
+                end
               rescue Ractor::ClosedError
                 break
               end
@@ -232,6 +258,7 @@ module Teek
             out.send([:error, "#{e.class}: #{e.message}\n#{e.backtrace.first(3).join("\n")}"])
             out.send([:done])
           end
+          # :nocov:
         end
 
         # Bridge thread: Port.receive -> Queue
@@ -334,6 +361,7 @@ module Teek
       # Context object passed to the worker block inside the Ractor.
       # Provides methods for yielding results, sending/receiving messages,
       # and responding to pause/stop signals.
+      # :nocov: -- TaskContext runs exclusively inside a Ractor; invisible to Coverage.so
       class TaskContext
         # @api private
         def initialize(output_port, msg_queue)
@@ -405,6 +433,7 @@ module Teek
           end
         end
       end
+      # :nocov:
     end
   end
 end