xinerama 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b933357913f6fed409fde25826b23f96b615be6d22856960c796a6edb2e8655e
+  data.tar.gz: 5019b91d24b032ae78b5e2fe6ee1c5ec60855bb82a36a7a5a30658e6ef30ac54
+SHA512:
+  metadata.gz: 10d929bfe5dda72bca4d05b796c08db422c5f29951b6a4cd863e34000fe8c2ce67c0c53f942499b0eee9045c78b8f036b882309c03414f58c5551d73f5b74b0c
+  data.tar.gz: 12d2672635c3c30987bee19d26185a7aa207e1f2d58903d9e95b486d488040f88e3e08de8f85b975a40697df523b3eabd52edba0084e66c49884f46a661e4395

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# Xinerama
+
+Ruby FFI bindings for the Xinerama X11 extension. Query multi-monitor screen configurations with a clean, idiomatic Ruby API.
+
+Official libXinerama repo: https://gitlab.freedesktop.org/xorg/lib/libxinerama
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'xinerama'
+```
+
+Or install directly:
+
+```bash
+gem install xinerama
+```
+
+**Dependencies:** Requires `libX11` and `libXinerama` to be installed on your system.
+
+```bash
+# Debian/Ubuntu
+apt-get install libx11-6 libxinerama1
+
+# Fedora/RHEL
+dnf install libX11 libXinerama
+
+# Arch
+pacman -S libx11 libxinerama
+```
+
+## Usage
+
+### Quick Access
+
+```ruby
+require 'xinerama'
+
+# Get all screens (lazy enumerator)
+Xinerama.screens.each do |screen|
+  puts "Screen #{screen.screen_number}: #{screen.width}x#{screen.height}+#{screen.x}+#{screen.y}"
+end
+
+# Check if Xinerama is active
+Xinerama.active?  # => true
+
+# Get version
+Xinerama.version  # => #<Xinerama::Version 1.1>
+```
+
+### Display Connection
+
+For multiple queries, reuse the display connection:
+
+```ruby
+Xinerama.open do |display|
+  puts "Xinerama active: #{display.active?}"
+  puts "Version: #{display.version}"
+  puts "Extension event base: #{display.extension.event_base}"
+  
+  display.screens.each do |screen|
+    puts screen.inspect
+  end
+end
+```
+
+### Screen Information
+
+```ruby
+Xinerama.open do |display|
+  display.screens.each do |screen|
+    screen.screen_number  # => 0
+    screen.x              # => 0
+    screen.y              # => 0
+    screen.width          # => 1920
+    screen.height         # => 1080
+    screen.origin         # => [0, 0]
+    screen.dimensions     # => [1920, 1080]
+    screen.area           # => 2073600
+    screen.aspect_ratio   # => (16/9)
+    screen.to_h           # => { screen_number: 0, x: 0, y: 0, width: 1920, height: 1080 }
+  end
+end
+```
+
+### Finding Screens
+
+```ruby
+Xinerama.open do |display|
+  # Primary screen (first in list)
+  display.primary_screen
+
+  # Find screen containing a point
+  display.screen_at(100, 200)
+
+  # Total virtual desktop dimensions
+  display.total_dimensions  # => [3840, 1080]
+end
+```
+
+### Lazy Evaluation
+
+Screen queries return lazy enumerators, efficient for large multi-monitor setups:
+
+```ruby
+# Only iterates until first matching screen is found
+large_screen = Xinerama.screens.find { |s| s.area > 2_000_000 }
+
+# Chain operations without intermediate arrays
+Xinerama.screens
+  .select { |s| s.width > 1920 }
+  .map(&:to_h)
+  .first(2)
+```
+
+### Connecting to Remote Displays
+
+```ruby
+Xinerama.open("remote:0.0") do |display|
+  display.screens.each { |s| puts s }
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  Xinerama.open do |display|
+    display.extension  # Raises if Xinerama unavailable
+  end
+rescue Xinerama::DisplayError => e
+  puts "Cannot connect to X server"
+rescue Xinerama::NotAvailableError => e
+  puts "Xinerama extension not available"
+end
+```
+
+## API Reference
+
+### Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `Xinerama.open(display_name = nil, &block)` | Open display connection |
+| `Xinerama.screens(display_name = nil)` | Get lazy enumerator of screens |
+| `Xinerama.active?(display_name = nil)` | Check if Xinerama is active |
+| `Xinerama.version(display_name = nil)` | Get Xinerama version |
+
+### Display
+
+| Method | Description |
+|--------|-------------|
+| `#active?` | Boolean indicating Xinerama activation |
+| `#available?` | Boolean indicating extension availability |
+| `#screens` | Lazy enumerator of ScreenInfo objects |
+| `#primary_screen` | First screen |
+| `#screen_at(x, y)` | Screen containing the given point |
+| `#screen_count` | Number of screens |
+| `#total_dimensions` | `[width, height]` of virtual desktop |
+| `#version` | Version object |
+| `#extension` | Extension object with event/error bases |
+| `#close` | Close display connection |
+| `#closed?` | Check if connection is closed |
+
+### ScreenInfo
+
+| Method | Description |
+|--------|-------------|
+| `#screen_number` | Screen index |
+| `#x`, `#y` | Origin coordinates |
+| `#width`, `#height` | Dimensions |
+| `#origin` | `[x, y]` |
+| `#dimensions` | `[width, height]` |
+| `#area` | `width * height` |
+| `#aspect_ratio` | Rational width/height |
+| `#contains?(x, y)` | Point containment check |
+| `#to_h`, `#to_a` | Conversion methods |
+
+## License
+
+MIT License. See LICENSE.txt.

data/lib/xinerama/display.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Xinerama
+  class Display
+    attr_reader :display_name
+
+    def initialize(display_pointer, display_name = nil)
+      @pointer = display_pointer
+      @display_name = display_name
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      FFI.XCloseDisplay(@pointer)
+      @closed = true
+      nil
+    end
+
+    def closed?
+      @closed
+    end
+
+    def extension
+      ensure_open!
+      @extension ||= query_extension
+    end
+
+    def available?
+      ensure_open!
+      @available ||= check_availability
+    end
+
+    def version
+      ensure_open!
+      @version ||= query_version
+    end
+
+    def active?
+      ensure_open!
+      FFI.XineramaIsActive(@pointer)
+    end
+
+    def screens
+      ensure_open!
+      query_screens
+    end
+
+    def primary_screen
+      screens.first
+    end
+
+    def screen_count
+      screens.count
+    end
+
+    def screen_at(x, y)
+      screens.find { |screen| screen.contains?(x, y) }
+    end
+
+    def total_dimensions
+      all_screens = screens.to_a
+      return [0, 0] if all_screens.empty?
+
+      max_x = all_screens.map { |s| s.x + s.width }.max
+      max_y = all_screens.map { |s| s.y + s.height }.max
+      [max_x, max_y]
+    end
+
+    class << self
+      def open(display_name = nil)
+        display = connect(display_name)
+        return display unless block_given?
+
+        begin
+          yield display
+        ensure
+          display.close
+        end
+      end
+
+      private
+
+      def connect(display_name)
+        pointer = FFI.XOpenDisplay(display_name)
+        raise DisplayError, "Cannot open display: #{display_name || '$DISPLAY'}" if pointer.null?
+
+        new(pointer, display_name)
+      end
+    end
+
+    private
+
+    def ensure_open!
+      raise DisplayError, "Display connection closed" if @closed
+    end
+
+    def check_availability
+      event_base = ::FFI::MemoryPointer.new(:int)
+      error_base = ::FFI::MemoryPointer.new(:int)
+      FFI.XineramaQueryExtension(@pointer, event_base, error_base)
+    end
+
+    def query_extension
+      event_base = ::FFI::MemoryPointer.new(:int)
+      error_base = ::FFI::MemoryPointer.new(:int)
+
+      available = FFI.XineramaQueryExtension(@pointer, event_base, error_base)
+      raise NotAvailableError, "Xinerama extension not available" unless available
+
+      Extension.new(
+        event_base: event_base.read_int,
+        error_base: error_base.read_int
+      )
+    end
+
+    def query_version
+      major = ::FFI::MemoryPointer.new(:int)
+      minor = ::FFI::MemoryPointer.new(:int)
+
+      status = FFI.XineramaQueryVersion(@pointer, major, minor)
+      raise NotAvailableError, "Cannot query Xinerama version" if status.zero?
+
+      Version.new(
+        major: major.read_int,
+        minor: minor.read_int
+      )
+    end
+
+    def query_screens
+      count_ptr = ::FFI::MemoryPointer.new(:int)
+      screens_ptr = FFI.XineramaQueryScreens(@pointer, count_ptr)
+      count = count_ptr.read_int
+
+      return Enumerator.new { }.lazy if screens_ptr.null? || count.zero?
+
+      build_screens_enumerator(screens_ptr, count)
+    end
+
+    def build_screens_enumerator(screens_ptr, count)
+      Enumerator.new do |yielder|
+        begin
+          ScreenInfo.from_pointer(screens_ptr, count).each do |screen|
+            yielder << screen
+          end
+        ensure
+          FFI.XFree(screens_ptr) unless screens_ptr.null?
+        end
+      end.lazy
+    end
+  end
+end

data/lib/xinerama/extension.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Xinerama
+  class Extension
+    attr_reader :event_base, :error_base
+
+    def initialize(event_base:, error_base:)
+      @event_base = event_base
+      @error_base = error_base
+      freeze
+    end
+
+    def to_h
+      { event_base: event_base, error_base: error_base }
+    end
+
+    def inspect
+      "#<#{self.class} event_base=#{event_base} error_base=#{error_base}>"
+    end
+
+    alias_method :to_s, :inspect
+  end
+
+  class Version
+    attr_reader :major, :minor
+
+    def initialize(major:, minor:)
+      @major = major
+      @minor = minor
+      freeze
+    end
+
+    def to_s
+      "#{major}.#{minor}"
+    end
+
+    def to_a
+      [major, minor]
+    end
+
+    def to_h
+      { major: major, minor: minor }
+    end
+
+    def inspect
+      "#<#{self.class} #{self}>"
+    end
+
+    def <=>(other)
+      [major, minor] <=> [other.major, other.minor]
+    end
+
+    include Comparable
+  end
+end

data/lib/xinerama/ffi.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Xinerama
+  module FFI
+    extend ::FFI::Library
+
+    ffi_lib "X11"
+    ffi_lib "Xinerama"
+
+    # XineramaScreenInfo struct
+    # typedef struct {
+    #   int screen_number;
+    #   short x_org;
+    #   short y_org;
+    #   short width;
+    #   short height;
+    # } XineramaScreenInfo;
+    class XineramaScreenInfoStruct < ::FFI::Struct
+      layout :screen_number, :int,
+             :x_org,         :short,
+             :y_org,         :short,
+             :width,         :short,
+             :height,        :short
+    end
+
+    # Display* XOpenDisplay(const char *display_name)
+    attach_function :XOpenDisplay, [:string], :pointer
+
+    # int XCloseDisplay(Display *display)
+    attach_function :XCloseDisplay, [:pointer], :int
+
+    # int XFree(void *data)
+    attach_function :XFree, [:pointer], :int
+
+    # Bool XineramaQueryExtension(Display *dpy, int *event_base_return, int *error_base_return)
+    attach_function :XineramaQueryExtension, [:pointer, :pointer, :pointer], :bool
+
+    # Status XineramaQueryVersion(Display *dpy, int *major_version_return, int *minor_version_return)
+    attach_function :XineramaQueryVersion, [:pointer, :pointer, :pointer], :int
+
+    # Bool XineramaIsActive(Display *dpy)
+    attach_function :XineramaIsActive, [:pointer], :bool
+
+    # XineramaScreenInfo* XineramaQueryScreens(Display *dpy, int *number)
+    attach_function :XineramaQueryScreens, [:pointer, :pointer], :pointer
+  end
+end

data/lib/xinerama/screen_info.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Xinerama
+  class ScreenInfo
+    attr_reader :screen_number, :x, :y, :width, :height
+
+    def initialize(screen_number:, x:, y:, width:, height:)
+      @screen_number = screen_number
+      @x = x
+      @y = y
+      @width = width
+      @height = height
+      freeze
+    end
+
+    def origin
+      [x, y]
+    end
+
+    def dimensions
+      [width, height]
+    end
+
+    def area
+      width * height
+    end
+
+    def aspect_ratio
+      Rational(width, height)
+    end
+
+    def contains?(point_x, point_y)
+      point_x >= x && point_x < (x + width) &&
+        point_y >= y && point_y < (y + height)
+    end
+
+    def to_h
+      {
+        screen_number: screen_number,
+        x: x,
+        y: y,
+        width: width,
+        height: height
+      }
+    end
+
+    def to_a
+      [screen_number, x, y, width, height]
+    end
+
+    def inspect
+      "#<#{self.class} screen=#{screen_number} geometry=#{width}x#{height}+#{x}+#{y}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    def ==(other)
+      other.is_a?(ScreenInfo) &&
+        screen_number == other.screen_number &&
+        x == other.x &&
+        y == other.y &&
+        width == other.width &&
+        height == other.height
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      to_a.hash
+    end
+
+    class << self
+      def from_struct(struct)
+        new(
+          screen_number: struct[:screen_number],
+          x: struct[:x_org],
+          y: struct[:y_org],
+          width: struct[:width],
+          height: struct[:height]
+        )
+      end
+
+      def from_pointer(pointer, count)
+        Enumerator.new do |yielder|
+          count.times do |index|
+            offset = index * FFI::XineramaScreenInfoStruct.size
+            struct = FFI::XineramaScreenInfoStruct.new(pointer + offset)
+            yielder << from_struct(struct)
+          end
+        end.lazy
+      end
+    end
+  end
+end

data/lib/xinerama/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xinerama
+  VERSION = "0.1.0"
+end

data/lib/xinerama.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "xinerama/version"
+require_relative "xinerama/ffi"
+require_relative "xinerama/screen_info"
+require_relative "xinerama/display"
+require_relative "xinerama/extension"
+
+module Xinerama
+  class Error < StandardError; end
+  class NotAvailableError < Error; end
+  class DisplayError < Error; end
+
+  class << self
+    def open(display_name = nil, &block)
+      Display.open(display_name, &block)
+    end
+
+    def screens(display_name = nil)
+      Display.open(display_name, &:screens)
+    end
+
+    def active?(display_name = nil)
+      Display.open(display_name, &:active?)
+    end
+
+    def version(display_name = nil)
+      Display.open(display_name, &:version)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: xinerama
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nathan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: Provides a clean Ruby interface to query Xinerama screen information
+  for multi-monitor X11 setups
+email:
+- nathankidd@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/xinerama.rb
+- lib/xinerama/display.rb
+- lib/xinerama/extension.rb
+- lib/xinerama/ffi.rb
+- lib/xinerama/screen_info.rb
+- lib/xinerama/version.rb
+homepage: https://github.com/n-at-han-k/ruby-xinerama
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/n-at-han-k/ruby-xinerama
+  source_code_uri: https://github.com/n-at-han-k/ruby-xinerama
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby FFI bindings for the Xinerama X11 extension
+test_files: []