teek-sdl2 0.1.0

data/lib/teek/sdl2/texture.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Teek
+  module SDL2
+    # GPU-resident pixel buffer backed by an +SDL_Texture+.
+    #
+    # Textures are created through a {Renderer}, not directly instantiated.
+    # Use the convenience constructors {.streaming} and {.target}, or call
+    # {Renderer#create_texture} directly.
+    #
+    # ## C-defined methods
+    #
+    # These are defined in the C extension (+sdl2surface.c+):
+    #
+    # - {#update} — upload pixel data from a String
+    # - {#width} — texture width in pixels
+    # - {#height} — texture height in pixels
+    # - {#destroy} — free GPU resources
+    # - {#destroyed?} — check if the texture has been destroyed
+    #
+    # @example Create and update a streaming texture
+    #   tex = Teek::SDL2::Texture.streaming(renderer, 256, 224)
+    #   tex.update(pixel_data_string)
+    #   renderer.copy(tex)
+    #
+    # @see Renderer#create_texture
+    class Texture
+
+      # @!method update(pixel_data)
+      #   Upload pixel data to the texture. The data must be a binary String
+      #   of ARGB8888 pixels (4 bytes per pixel, width * height * 4 total).
+      #   @param pixel_data [String] raw pixel bytes
+      #   @return [self]
+
+      # @!method width
+      #   @return [Integer] texture width in pixels
+
+      # @!method height
+      #   @return [Integer] texture height in pixels
+
+      # @!method destroy
+      #   Free this texture's GPU resources.
+      #   @return [void]
+
+      # @!method destroyed?
+      #   @return [Boolean] whether this texture has been destroyed
+
+      # Load an image file into a GPU texture via SDL2_image.
+      #
+      # @param renderer [Renderer] the renderer that owns this texture
+      # @param path [String] path to an image file (PNG, JPG, BMP, etc.)
+      # @return [Texture]
+      #
+      # @example
+      #   sprite = Teek::SDL2::Texture.from_file(renderer, "assets/player.png")
+      #   renderer.copy(sprite)
+      def self.from_file(renderer, path)
+        renderer.load_image(path)
+      end
+
+      # Create a streaming texture (lockable, CPU-updatable).
+      #
+      # @param renderer [Renderer] the renderer that owns this texture
+      # @param width [Integer] width in pixels
+      # @param height [Integer] height in pixels
+      # @return [Texture]
+      #
+      # @example
+      #   tex = Teek::SDL2::Texture.streaming(renderer, 256, 224)
+      #   tex.update(rgba_string)
+      def self.streaming(renderer, width, height)
+        renderer.create_texture(width, height, :streaming)
+      end
+
+      # Create a target texture (can be rendered to via +SDL_SetRenderTarget+).
+      #
+      # @param renderer [Renderer] the renderer that owns this texture
+      # @param width [Integer] width in pixels
+      # @param height [Integer] height in pixels
+      # @return [Texture]
+      def self.target(renderer, width, height)
+        renderer.create_texture(width, height, :target)
+      end
+
+      # @return [Array(Integer, Integer)] +[width, height]+
+      def size
+        [width, height]
+      end
+    end
+  end
+end

data/lib/teek/sdl2/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Teek
+  module SDL2
+    VERSION = "0.1.0"
+  end
+end

data/lib/teek/sdl2/viewport.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Teek
+  module SDL2
+    # An SDL2-accelerated rendering surface embedded in a Tk frame.
+    #
+    # Viewport creates a Tk frame, obtains its native window handle via
+    # the Tk C API, then embeds an SDL2 renderer inside it using
+    # +SDL_CreateWindowFrom+. All drawing goes through SDL2 with GPU
+    # acceleration — no Tk involvement in the rendering path.
+    #
+    # Keyboard input is tracked automatically via Tk bindings so you can
+    # poll key state with {#key_down?} in a game loop.
+    #
+    # @example Create a viewport and draw a red rectangle
+    #   viewport = Teek::SDL2::Viewport.new(app, width: 800, height: 600)
+    #   viewport.pack(fill: :both, expand: true)
+    #
+    #   viewport.render do |r|
+    #     r.clear(0, 0, 0)
+    #     r.fill_rect(10, 10, 100, 50, 255, 0, 0)
+    #   end
+    #
+    # @example Poll keyboard input
+    #   if viewport.key_down?('left')
+    #     player_x -= speed
+    #   end
+    #
+    # @see Renderer
+    class Viewport
+      # @return [Teek::App] the Teek application
+      attr_reader :app
+
+      # @return [Teek::Widget] the underlying Tk frame
+      attr_reader :frame
+
+      # @return [Teek::SDL2::Renderer] the SDL2 renderer
+      attr_reader :renderer
+
+      # @return [Set<String>] currently held key names (lowercase keysyms)
+      attr_reader :keys_down
+
+      # @param app [Teek::App] the Teek application
+      # @param parent [Teek::Widget, String, nil] parent widget (nil for root)
+      # @param width [Integer] initial width in pixels
+      # @param height [Integer] initial height in pixels
+      def initialize(app, parent: nil, width: 640, height: 480)
+        @app = app
+        @destroyed = false
+
+        # Create a Tk frame to host the SDL2 window
+        @frame = app.create_widget('frame', parent: parent,
+                                   width: width, height: height)
+
+        # Pack with fixed size so the frame is managed, then force a
+        # full update. On X11, update_idletasks alone isn't enough —
+        # the window must process MapNotify to be usable by SDL2.
+        @frame.pack
+        app.tcl_eval('update')
+
+        # Get platform-native window handle via Tk C API
+        # (macOS: NSWindow*, X11: Window ID, Windows: HWND)
+        #
+        # NOTE: On macOS, Tk_MacOSXGetNSWindowForDrawable returns the NSWindow
+        # for the entire Tk toplevel, not just this frame. SDL_CreateWindowFrom
+        # therefore creates a renderer that covers the whole window. Tk widgets
+        # packed alongside the viewport will be painted over by SDL2 rendering.
+        # On X11 each frame has its own X Window, so embedding is frame-scoped.
+        # Workaround on macOS: use SDL2_ttf to draw overlay text on the surface
+        # rather than Tk widgets.
+        handle = app.interp.native_window_handle(@frame.path)
+
+        # Create SDL2 renderer embedded in the frame (Layer 2 → Layer 1)
+        @renderer = Teek::SDL2.create_renderer_from_handle(handle)
+
+        # Register SDL2 event source if this is the first viewport
+        Teek::SDL2.register_event_source
+
+        # Key state tracking for game-loop polling
+        @keys_down = Set.new
+        @frame.bind('KeyPress', :keysym) { |k| @keys_down.add(k.downcase) }
+        @frame.bind('KeyRelease', :keysym) { |k| @keys_down.delete(k.downcase) }
+
+        # Click-to-focus: Tk frames must have focus to receive key events
+        @frame.bind('ButtonPress-1') { focus }
+
+        # Bind cleanup on frame destroy
+        @frame.bind('<Destroy>') { _on_destroy }
+
+        # Track viewport count for event source lifecycle
+        Teek::SDL2._viewports << self
+      end
+
+      # Draw with the renderer in a block, auto-presenting at the end.
+      #
+      # @yield [renderer] the SDL2 renderer for this viewport
+      # @yieldparam renderer [Teek::SDL2::Renderer]
+      # @return [self]
+      # @raise [Teek::SDL2::Error] if the viewport has been destroyed
+      #
+      # @example
+      #   viewport.render do |r|
+      #     r.clear(0, 0, 0)
+      #     r.fill_rect(10, 10, 100, 50, 255, 0, 0)
+      #   end
+      def render(&block)
+        raise Teek::SDL2::Error, "viewport has been destroyed" if @destroyed
+        @renderer.render(&block)
+      end
+
+      # Pack the viewport into its parent using Tk's pack geometry manager.
+      #
+      # @param kwargs options passed to the Tk +pack+ command
+      # @return [self]
+      def pack(**kwargs)
+        @frame.pack(**kwargs)
+        self
+      end
+
+      # Grid the viewport into its parent using Tk's grid geometry manager.
+      #
+      # @param kwargs options passed to the Tk +grid+ command
+      # @return [self]
+      def grid(**kwargs)
+        @frame.grid(**kwargs)
+        self
+      end
+
+      # Check if a key is currently held down. Uses Tk keysym names (lowercase).
+      #
+      # @param keysym [String, Symbol] Tk keysym name (e.g. +'left'+, +'space'+, +'a'+)
+      # @return [Boolean]
+      #
+      # @example
+      #   viewport.key_down?('left')   # arrow key
+      #   viewport.key_down?('space')  # spacebar
+      #   viewport.key_down?('a')      # letter key
+      def key_down?(keysym)
+        @keys_down.include?(keysym.to_s.downcase)
+      end
+
+      # Give this viewport keyboard focus so it receives key events.
+      #
+      # @return [void]
+      def focus
+        @app.tcl_eval("focus #{@frame.path}")
+      end
+
+      # Bind a Tk event on the viewport frame.
+      #
+      # Automatically chains with internal behavior (key tracking,
+      # click-to-focus) so user callbacks don't clobber {#key_down?}.
+      #
+      # @param event [String] Tk event name (e.g. +'KeyPress'+, +'ButtonPress-1'+)
+      # @param subs [Array<Symbol, String>] Tk substitution codes
+      # @yield called when the event fires
+      # @return [void]
+      def bind(event, *subs, &block)
+        case event.to_s
+        when 'KeyPress'
+          @frame.bind(event, *subs) do |*args|
+            @keys_down.add(args.first.to_s.downcase) if args.first
+            block&.call(*args)
+          end
+        when 'KeyRelease'
+          @frame.bind(event, *subs) do |*args|
+            @keys_down.delete(args.first.to_s.downcase) if args.first
+            block&.call(*args)
+          end
+        when /ButtonPress/
+          @frame.bind(event, *subs) do |*args|
+            focus
+            block&.call(*args)
+          end
+        else
+          @frame.bind(event, *subs, &block)
+        end
+      end
+
+      # Destroy the viewport, its SDL2 renderer, and the Tk frame.
+      #
+      # @return [void]
+      def destroy
+        return if @destroyed
+        @renderer.destroy unless @renderer.destroyed?
+        @frame.destroy if @frame.exist?
+        _cleanup
+      end
+
+      # @return [Boolean] whether this viewport has been destroyed
+      def destroyed?
+        @destroyed
+      end
+
+      def inspect
+        "#<Teek::SDL2::Viewport #{@frame.path} #{destroyed? ? 'DESTROYED' : 'active'}>"
+      end
+
+      private
+
+      def _on_destroy
+        return if @destroyed
+        @renderer.destroy unless @renderer.destroyed?
+        _cleanup
+      end
+
+      def _cleanup
+        @destroyed = true
+        Teek::SDL2._viewports.delete(self)
+
+        # Unregister event source when last viewport is gone
+        if Teek::SDL2._viewports.empty?
+          Teek::SDL2.unregister_event_source
+        end
+      end
+    end
+
+    # Internal viewport tracking for event source lifecycle
+    @_viewports = []
+
+    class << self
+      # @api private
+      def _viewports
+        @_viewports
+      end
+    end
+  end
+end

data/lib/teek/sdl2.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "teek"
+require_relative "sdl2/version"
+require "teek_sdl2"
+
+module Teek
+  # GPU-accelerated 2D rendering via SDL2, embedded inside Tk windows.
+  #
+  # Teek::SDL2 lets you drop an SDL2 hardware-accelerated surface into any
+  # Tk application. The surface lives inside a Tk frame so it coexists with
+  # normal Tk widgets (buttons, labels, menus) while all pixel work is
+  # GPU-driven.
+  #
+  # The main entry point is {Viewport}, which creates a Tk frame, obtains
+  # its native window handle, and hands it to SDL2 for rendering.
+  #
+  # @example Basic usage
+  #   require 'teek'
+  #   require 'teek/sdl2'
+  #
+  #   app = Teek::App.new
+  #   vp  = Teek::SDL2::Viewport.new(app, width: 800, height: 600)
+  #   vp.render do |r|
+  #     r.clear(0, 0, 0)
+  #     r.fill_rect(10, 10, 100, 50, 255, 0, 0)
+  #   end
+  #   app.mainloop
+  #
+  # @see Viewport
+  # @see Renderer
+  # @see Texture
+  # @see Font
+  module SDL2
+    @event_source = nil
+
+    # Register SDL2 as a Tcl event source. Called automatically when the
+    # first {Viewport} is created. Uses a C function pointer for the hot
+    # path — no Ruby in the poll loop.
+    #
+    # @param interval_ms [Integer] polling interval in milliseconds
+    # @return [void]
+    # @api private
+    def self.register_event_source(interval_ms: 16)
+      return if @event_source&.registered?
+
+      fn_ptr = _event_check_fn_ptr   # C function address from sdl2bridge.c
+      @event_source = Teek._register_event_source(fn_ptr, 0, interval_ms)
+    end
+
+    # Remove SDL2 from Tcl's event loop. Called automatically when the last
+    # {Viewport} is destroyed.
+    #
+    # @return [void]
+    # @api private
+    def self.unregister_event_source
+      @event_source&.unregister
+      @event_source = nil
+    end
+  end
+end
+
+# Ruby convenience layers (reopen C-defined classes)
+require_relative "sdl2/renderer"
+require_relative "sdl2/texture"
+require_relative "sdl2/font"
+
+# Tk bridge (embeds SDL2 surface into a Tk frame)
+require_relative "sdl2/viewport"

data/teek-sdl2.gemspec

@@ -0,0 +1,28 @@
+require_relative "lib/teek/sdl2/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "teek-sdl2"
+  spec.version       = Teek::SDL2::VERSION
+  spec.authors       = ["James Cook"]
+  spec.email         = ["jcook.rubyist@gmail.com"]
+
+  spec.summary       = "GPU-accelerated SDL2 rendering for teek (Tk)"
+  spec.description   = "Embeds an SDL2 renderer inside a Tk frame for GPU-accelerated drawing"
+  spec.homepage      = "https://github.com/jamescook/teek"
+  spec.licenses      = ["MIT"]
+
+  spec.files         = Dir.glob("{lib,ext,test}/**/*").select { |f|
+                         File.file?(f) && f !~ /\.(bundle|so|o|log)$/
+                       } + %w[teek-sdl2.gemspec]
+  spec.require_paths = ["lib"]
+  spec.extensions    = ["ext/teek_sdl2/extconf.rb"]
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.add_dependency "teek", ">= 0.1.2"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rake-compiler", "~> 1.0"
+  spec.add_development_dependency "minitest", "~> 6.0"
+
+  spec.requirements << "SDL2 development headers (libsdl2-dev or sdl2 via Homebrew)"
+end

data/test/test_callback_teardown.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../../test/tk_test_helper"
+
+class TestCallbackTeardown < Minitest::Test
+  include TeekTestHelper
+
+  def test_viewport_destroy_no_bgerror
+    assert_tk_app("destroying viewport does not trigger bgerror") do
+      require "teek/sdl2"
+      app.show
+      app.update
+
+      # Capture any bgerror that Tcl would normally show in a dialog
+      app.set_variable("_bgerror_msg", "")
+      app.tcl_eval('proc bgerror {msg} { set ::_bgerror_msg $msg }')
+
+      vp = Teek::SDL2::Viewport.new(app, width: 200, height: 200)
+      vp.pack
+      app.update
+
+      vp.render do |r|
+        r.clear(30, 30, 30)
+        r.fill(20, 20, 80, 60, r: 200, g: 50, b: 50)
+      end
+
+      vp.destroy
+      app.update
+
+      err = app.get_variable("_bgerror_msg")
+      assert_equal "", err, "bgerror fired during viewport destroy: #{err}"
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+if ENV['COVERAGE']
+  require 'simplecov'
+  require_relative '../../test/simplecov_config'
+
+  coverage_name = ENV['COVERAGE_NAME'] || 'sdl2'
+  SimpleCov.coverage_dir "#{SimpleCovConfig::PROJECT_ROOT}/coverage/results/#{coverage_name}"
+  SimpleCov.command_name "sdl2:#{coverage_name}"
+  SimpleCov.print_error_status = false
+  SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
+
+  SimpleCov.start do
+    SimpleCovConfig.apply_filters(self)
+    track_files "#{SimpleCovConfig::PROJECT_ROOT}/lib/**/*.rb"
+  end
+end
+
+require "minitest/autorun"

data/test/test_image.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../../test/tk_test_helper"
+
+class TestImage < Minitest::Test
+  include TeekTestHelper
+
+  def test_load_image
+    assert_tk_app("load_image returns a texture with correct dimensions") do
+      require "teek/sdl2"
+
+      png = fixture_path("teek-sdl2/assets/test_red_8x8.png")
+      app.show
+      app.update
+      viewport = Teek::SDL2::Viewport.new(app, width: 200, height: 200)
+
+      tex = viewport.renderer.load_image(png)
+      assert_kind_of Teek::SDL2::Texture, tex
+      assert_equal 8, tex.width
+      assert_equal 8, tex.height
+      assert_equal [8, 8], tex.size
+      refute tex.destroyed?
+
+      tex.destroy
+      assert tex.destroyed?
+      viewport.destroy
+    end
+  end
+
+  def test_load_image_and_render
+    assert_tk_app("load_image texture can be rendered") do
+      require "teek/sdl2"
+
+      png = fixture_path("teek-sdl2/assets/test_red_8x8.png")
+      app.show
+      app.update
+      viewport = Teek::SDL2::Viewport.new(app, width: 200, height: 200)
+      viewport.pack
+
+      tex = viewport.renderer.load_image(png)
+
+      viewport.render do |r|
+        r.clear(0, 0, 0)
+        r.copy(tex, nil, [0, 0, tex.width * 4, tex.height * 4])
+      end
+
+      tex.destroy
+      viewport.destroy
+    end
+  end
+
+  def test_texture_from_file
+    assert_tk_app("Texture.from_file convenience works") do
+      require "teek/sdl2"
+
+      png = fixture_path("teek-sdl2/assets/test_red_8x8.png")
+      app.show
+      app.update
+      viewport = Teek::SDL2::Viewport.new(app, width: 200, height: 200)
+
+      tex = Teek::SDL2::Texture.from_file(viewport.renderer, png)
+      assert_kind_of Teek::SDL2::Texture, tex
+      assert_equal 8, tex.width
+      assert_equal 8, tex.height
+
+      tex.destroy
+      viewport.destroy
+    end
+  end
+
+  def test_load_image_bad_path
+    assert_tk_app("load_image raises on missing file") do
+      require "teek/sdl2"
+
+      app.show
+      app.update
+      viewport = Teek::SDL2::Viewport.new(app, width: 200, height: 200)
+
+      assert_raises(RuntimeError) do
+        viewport.renderer.load_image("/nonexistent/path/to/image.png")
+      end
+
+      viewport.destroy
+    end
+  end
+end