teek 0.1.1 → 0.1.2

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

@@ -154,13 +154,20 @@ module Teek
       def close
         @done = true
         # Send stop to let the worker terminate itself — Ruby 4.x doesn't
-        # allow closing a Ractor from outside.
+        # 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
           @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
 
@@ -174,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
@@ -202,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
@@ -209,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
@@ -233,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
@@ -335,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)
@@ -406,6 +433,7 @@ module Teek
           end
         end
       end
+      # :nocov:
     end
   end
 end

data/lib/teek/photo.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Teek
+  # CPU-side RGBA pixel buffer backed by Tk's "photo image" format.
+  #
+  # Despite the name, this is really a raw pixel manipulation surface.
+  # Tk has two built-in image types: "bitmap" (two colors + transparency)
+  # and "photo" (full-color, 32-bit RGBA). The naming reflects Tk's
+  # image type system, not the contents — a "photo" is just Tk's term
+  # for a full-color pixel buffer.
+  #
+  # Think of it as a software framebuffer: you pack RGBA bytes, write
+  # them in bulk, read them back, zoom/subsample, and blit to a canvas
+  # or label for display. All work is CPU-driven — there is no GPU
+  # acceleration.
+  #
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/photo.html Tk photo image type
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/bitmap.html Tk bitmap image type
+  # @see https://www.tcl-lang.org/man/tcl9.0/TkCmd/image.html Tk image command (lists all types)
+  #
+  # The C methods ({#put_block}, {#get_image}, {#get_pixel}, etc.) call
+  # Tk_PhotoPutBlock / Tk_PhotoGetImage directly, bypassing Tcl string
+  # parsing for much better performance than the Tcl-level +$photo put+
+  # command. Designed for games, visualizations, and real-time drawing.
+  #
+  # @example Create and fill with red pixels
+  #   photo = Teek::Photo.new(app, width: 100, height: 100)
+  #   red = ([255, 0, 0, 255].pack('CCCC')) * (100 * 100)
+  #   photo.put_block(red, 100, 100)
+  #
+  # @example Read pixels back
+  #   result = photo.get_image
+  #   r, g, b, a = result[:data][0, 4].unpack('CCCC')
+  #
+  # @example Zoom a small sprite
+  #   sprite = Teek::Photo.new(app, width: 64, height: 64)
+  #   # ... fill sprite pixels ...
+  #   dest = Teek::Photo.new(app, width: 192, height: 192)
+  #   dest.put_zoomed_block(sprite_data, 64, 64, zoom_x: 3, zoom_y: 3)
+  #
+  # @see https://www.tcl-lang.org/man/tcl8.6/TkLib/FindPhoto.htm Tk Photo C API
+  class Photo
+    attr_reader :app, :name
+
+    @counter = 0
+
+    class << self
+      # @api private
+      def next_name
+        @counter += 1
+        "teek_photo#{@counter}"
+      end
+    end
+
+    # Create a new photo image.
+    #
+    # @param app [Teek::App] the application instance
+    # @param name [String, nil] Tcl image name (auto-generated if nil)
+    # @param width [Integer, nil] image width in pixels
+    # @param height [Integer, nil] image height in pixels
+    # @param file [String, nil] path to an image file to load
+    # @param data [String, nil] base64-encoded image data
+    # @param format [String, nil] image format (e.g. "png", "gif")
+    # @param palette [String, nil] palette specification
+    # @param gamma [Float, nil] gamma correction value
+    def initialize(app, name: nil, width: nil, height: nil,
+                   file: nil, data: nil, format: nil, palette: nil, gamma: nil)
+      @app = app
+      @name = name || self.class.next_name
+
+      kwargs = {}
+      kwargs[:width] = width if width
+      kwargs[:height] = height if height
+      kwargs[:file] = file if file
+      kwargs[:data] = data if data
+      kwargs[:format] = format if format
+      kwargs[:palette] = palette if palette
+      kwargs[:gamma] = gamma if gamma
+
+      @app.command(:image, :create, :photo, @name, **kwargs)
+    end
+
+    # Write RGBA pixel data to the image.
+    #
+    # @param pixel_data [String] binary string, 4 bytes (RGBA) per pixel
+    # @param width [Integer] width of the pixel block
+    # @param height [Integer] height of the pixel block
+    # @param x [Integer] destination X offset
+    # @param y [Integer] destination Y offset
+    # @param format [:rgba, :argb] pixel format
+    # @param composite [:set, :overlay] compositing rule
+    # @return [self]
+    def put_block(pixel_data, width, height, x: 0, y: 0, format: :rgba, composite: :set)
+      opts = { x: x, y: y, format: format, composite: composite }
+      @app.interp.photo_put_block(@name, pixel_data, width, height, opts)
+      self
+    end
+
+    # Write RGBA pixel data with zoom and subsample.
+    #
+    # Zoom replicates each pixel (zoom=3 makes each source pixel 3x3).
+    # Subsample skips source pixels (subsample=2 takes every other pixel).
+    #
+    # @param pixel_data [String] binary string, 4 bytes (RGBA) per pixel
+    # @param width [Integer] source width in pixels
+    # @param height [Integer] source height in pixels
+    # @param x [Integer] destination X offset
+    # @param y [Integer] destination Y offset
+    # @param zoom_x [Integer] horizontal zoom factor
+    # @param zoom_y [Integer] vertical zoom factor
+    # @param subsample_x [Integer] horizontal subsample factor
+    # @param subsample_y [Integer] vertical subsample factor
+    # @param format [:rgba, :argb] pixel format
+    # @param composite [:set, :overlay] compositing rule
+    # @return [self]
+    def put_zoomed_block(pixel_data, width, height,
+                         x: 0, y: 0, zoom_x: 1, zoom_y: 1,
+                         subsample_x: 1, subsample_y: 1,
+                         format: :rgba, composite: :set)
+      opts = {
+        x: x, y: y,
+        zoom_x: zoom_x, zoom_y: zoom_y,
+        subsample_x: subsample_x, subsample_y: subsample_y,
+        format: format, composite: composite
+      }
+      @app.interp.photo_put_zoomed_block(@name, pixel_data, width, height, opts)
+      self
+    end
+
+    # Read pixel data from the image.
+    #
+    # @param x [Integer] source X offset
+    # @param y [Integer] source Y offset
+    # @param width [Integer, nil] region width (nil for full image)
+    # @param height [Integer, nil] region height (nil for full image)
+    # @param unpack [Boolean] if true, return flat array of integers instead of binary string
+    # @return [Hash] +{ data: String, width: Integer, height: Integer }+ or
+    #   +{ pixels: Array<Integer>, width: Integer, height: Integer }+ if unpack is true
+    def get_image(x: nil, y: nil, width: nil, height: nil, unpack: false)
+      opts = { unpack: unpack }
+      opts[:x] = x if x
+      opts[:y] = y if y
+      opts[:width] = width if width
+      opts[:height] = height if height
+      @app.interp.photo_get_image(@name, opts)
+    end
+
+    # Read a single pixel.
+    #
+    # @param x [Integer] X coordinate
+    # @param y [Integer] Y coordinate
+    # @return [Array<Integer>] [r, g, b, a] values (0-255)
+    def get_pixel(x, y)
+      @app.interp.photo_get_pixel(@name, x, y)
+    end
+
+    # Get image dimensions.
+    #
+    # @return [Array<Integer>] [width, height]
+    def get_size
+      @app.interp.photo_get_size(@name)
+    end
+
+    # Set image dimensions. May crop or add transparent pixels.
+    #
+    # @param width [Integer] new width
+    # @param height [Integer] new height
+    # @return [self]
+    def set_size(width, height)
+      @app.interp.photo_set_size(@name, width, height)
+      self
+    end
+
+    # Expand image to at least the given dimensions. Will not shrink.
+    #
+    # @note Has no effect on photos created with explicit +width:+ / +height:+
+    #   options. Only works on auto-sized photos (those whose size was set by
+    #   writing pixel data). This is a Tk limitation.
+    #
+    # @param width [Integer] minimum width
+    # @param height [Integer] minimum height
+    # @return [self]
+    def expand(width, height)
+      @app.interp.photo_expand(@name, width, height)
+      self
+    end
+
+    # Clear the image to fully transparent.
+    #
+    # @return [self]
+    def blank
+      @app.interp.photo_blank(@name)
+      self
+    end
+
+    alias clear blank
+
+    # Delete this photo image and free its resources.
+    #
+    # @return [void]
+    def delete
+      @app.tcl_eval("image delete #{@name}")
+    end
+
+    # Check if this photo image still exists.
+    #
+    # @return [Boolean]
+    def exist?
+      @app.tcl_eval("image type #{@name}") == 'photo'
+    rescue Teek::TclError
+      false
+    end
+
+    # @return [String] the Tcl image name
+    def to_s
+      @name
+    end
+
+    def inspect
+      "#<Teek::Photo #{@name}>"
+    end
+
+    def ==(other)
+      other.is_a?(Photo) ? @name == other.name : @name == other.to_s
+    end
+    alias eql? ==
+
+    def hash
+      @name.hash
+    end
+  end
+end

data/lib/teek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teek
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/teek.rb

@@ -4,6 +4,7 @@ require 'tcltklib'
 require_relative 'teek/version'
 require_relative 'teek/ractor_support'
 require_relative 'teek/widget'
+require_relative 'teek/photo'
 
 # Ruby interface to Tcl/Tk. Provides a thin wrapper around a Tcl interpreter
 # with Ruby callbacks, event bindings, and background work support.
@@ -313,7 +314,8 @@ module Teek
     # @param widget [String] Tk widget path (e.g. ".frame1")
     # @return [void]
     # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/destroy.htm destroy
-    def destroy(widget)
+    def destroy(widget = '.')
+      raise ArgumentError, 'widget path cannot be nil' if widget.nil?
       tcl_eval("destroy #{widget}")
     end