badline 0.2.1 → 0.4.0

data/lib/badline/options.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Badline
+  # The command line of `badline-ruby`. It opens the window for any media,
+  # or with --headless or --audio-out plays or renders a .sid tune without
+  # one. It loads nothing else from badline, so the executable can parse
+  # and reject its arguments before paying for the emulator.
+  class Options
+    class Error < StandardError; end
+
+    FALLBACK_SECONDS = 60.0
+
+    DEFAULT_RATE = 44_100
+
+    SID_MODELS = { "6581" => :mos6581, "8580" => :mos8580 }.freeze
+
+    BANNER = <<~BANNER.freeze
+      Usage: badline-ruby [options] [media]
+             badline-ruby --headless [options] tune.sid
+             badline-ruby [options] tune.sid --audio-out FILE
+
+      Media can be a .prg/.p00 program, a .d64/.d71/.d81 disk image,
+      a .t64 tape archive, a .tap tape, a .crt cartridge, a .sid tune, or
+      a directory to mount as device 8. It opens in the emulator window.
+
+      --headless plays a .sid tune on the host's audio device without the
+      window, and --audio-out renders it to 16-bit PCM instead. The
+      container follows the file's extension, .wav or .aiff. Played on a
+      terminal, n or → skips to the next song, p or ← to the previous one,
+      space pauses and q quits.
+
+      A .sid file carries no length of its own. Without --seconds the tune is
+      looked up by MD5 in HVSC's Songlengths.md5, taken from --songlengths, from
+      the DOCUMENTS directory of an HVSC collection above the tune, or from
+      $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds.
+
+      Without the window, PSID tunes run on a bare CPU and SID, faster than
+      real time. RSID tunes boot the whole machine and run at about half
+      real time, so they stutter when played. --filter-chunk 1 runs the
+      filter cycle by cycle, which is exact but takes about twice as long.
+
+    BANNER
+
+    attr_reader :media_path, :audio_out, :song, :seconds, :songlengths, :sid_model, :filter_chunk
+
+    alias tune_path media_path
+
+    def self.parse(argv) = new.parse(argv)
+
+    def initialize
+      @autostart = true
+      @read_only = false
+      @sound = false
+      @headless = false
+      @jit = true
+      @quiet = false
+      @tui = true
+      @help = false
+      @window_only = []
+      @headless_only = []
+    end
+
+    def parse(argv)
+      @media_path, *extra = parser.parse(argv)
+      raise Error, "unexpected argument: #{extra.first}" if extra.any?
+
+      validate unless help?
+      self
+    rescue OptionParser::ParseError => e
+      raise Error, e.message
+    end
+
+    # Plays or renders a .sid tune without the window.
+    def headless? = @headless || render?
+
+    def window? = !headless?
+
+    def render? = !audio_out.nil?
+
+    def rate = @rate || DEFAULT_RATE
+
+    # How long to play a tune whose length nothing gives.
+    def fallback_seconds = FALLBACK_SECONDS
+
+    def rate_given? = !@rate.nil?
+
+    def help = parser.help
+
+    def help? = @help
+
+    def autostart? = @autostart
+
+    def read_only? = @read_only
+
+    def sound? = @sound
+
+    def quiet? = @quiet
+
+    def tui? = @tui
+
+    def jit? = @jit
+
+    private
+
+    def validate
+      validate_mode
+      validate_numbers
+      validate_paths
+    end
+
+    def validate_mode
+      if headless?
+        raise Error, "#{@window_only.first} needs the window" if @window_only.any?
+        raise Error, "no tune given" unless media_path
+        raise Error, "not a .sid tune: #{media_path}" unless File.extname(media_path).casecmp?(".sid")
+      elsif @headless_only.any?
+        raise Error, "#{@headless_only.first} needs --headless or --audio-out"
+      end
+    end
+
+    def validate_numbers
+      raise Error, "invalid argument: --song #{song}" if song&.< 1
+      raise Error, "invalid argument: --seconds #{seconds}" unless seconds.nil? || seconds.positive?
+      raise Error, "invalid argument: --rate #{rate}" unless rate.positive?
+      raise Error, "invalid argument: --filter-chunk #{filter_chunk}" if filter_chunk&.< 1
+    end
+
+    def validate_paths
+      [media_path, songlengths].compact.each do |path|
+        raise Error, "no such file or directory: #{path}" unless File.exist?(path)
+      end
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = BANNER
+        opts.separator "Options:"
+        define_media_options(opts)
+        opts.separator ""
+        opts.separator "Window options:"
+        define_window_options(opts)
+        opts.separator ""
+        opts.separator "Options without the window:"
+        define_headless_options(opts)
+      end
+    end
+
+    def define_media_options(opts)
+      opts.on("-s", "--song N", Integer, "Subtune of a .sid, from 1 (default: the tune's own)") { |n| @song = n }
+      opts.on("--sid MODEL", SID_MODELS,
+              "SID to fit: 6581 or 8580 (default: a .sid tune's own, else 6581)") { |model| @sid_model = model }
+      opts.on("--disable-jit", "Run without enabling YJIT") { @jit = false }
+      opts.on("-h", "--help", "Show this help") { @help = true }
+    end
+
+    def define_window_options(opts)
+      opts.on("--no-autostart", "Boot to READY. instead of running the program") do
+        window_only("--no-autostart") { @autostart = false }
+      end
+      opts.on("--read-only", "Mount a disk image write-protected, leaving its file unchanged") do
+        window_only("--read-only") { @read_only = true }
+      end
+      opts.on("--sound", "Play the SID through the host's audio device (F10 mutes)") do
+        window_only("--sound") { @sound = true }
+      end
+    end
+
+    def define_headless_options(opts)
+      opts.on("--headless", "Play a .sid tune in the terminal instead of the window") { @headless = true }
+      opts.on("--audio-out FILE", "Render a .sid tune to a .wav or .aiff file") { |path| @audio_out = path }
+      define_length_options(opts)
+      define_rendering_options(opts)
+      opts.on("--quiet", "Don't report progress") { headless_only("--quiet") { @quiet = true } }
+      opts.on("--no-tui", "Play without the interactive display, even on a terminal") do
+        headless_only("--no-tui") { @tui = false }
+      end
+    end
+
+    def define_length_options(opts)
+      opts.on("--seconds N", Float, "Length to play (default: the tune's own)") do |n|
+        headless_only("--seconds") { @seconds = n }
+      end
+      opts.on("--songlengths PATH", "HVSC Songlengths.md5 to take the length from") do |path|
+        headless_only("--songlengths") { @songlengths = path }
+      end
+    end
+
+    def define_rendering_options(opts)
+      opts.on("--rate HZ", Integer, "Sample rate (default: #{DEFAULT_RATE}, or the audio device's own)") do |n|
+        headless_only("--rate") { @rate = n }
+      end
+      opts.on("--filter-chunk N", Integer, "Filter step in cycles, 1 is exact (default: 4)") do |n|
+        headless_only("--filter-chunk") { @filter_chunk = n }
+      end
+    end
+
+    def window_only(flag)
+      @window_only << flag
+      yield
+    end
+
+    def headless_only(flag)
+      @headless_only << flag
+      yield
+    end
+  end
+end

data/lib/badline/ram_expansion/banking.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Badline
+  module RAMExpansion
+    # The register and page mapping the expansions share. #map lays the
+    # selected banks out in the address bus's page tables, and #map_io puts
+    # the register over the VIC's I/O page at $D100.
+    module Banking
+      attr_reader :low_ram, :high_ram, :video_ram
+
+      # The block runs whenever the register moves a bank.
+      def on_change(&block)
+        @on_change = block
+      end
+
+      def peek(_addr) = 0xff
+
+      def map(read_pages, write_pages)
+        [read_pages, write_pages].each do |pages|
+          pages.fill(@low_ram, 0x00, 0x10)
+          pages.fill(@high_ram, 0x10, 0xf0)
+        end
+      end
+
+      def map_io(read_pages, write_pages)
+        read_pages[0xd1] = write_pages[0xd1] = self
+      end
+    end
+  end
+end

data/lib/badline/ram_expansion/plus256k.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Badline
+  module RAMExpansion
+    # The +256K: four 64K banks, the first of them the machine's own RAM.
+    # $D100 picks one for $0000-$0FFF (bits 0-1), one for the VIC (bits 2-3)
+    # and one for $1000-$FFFF (bits 6-7). Setting bit 4 locks the register
+    # until the next reset.
+    class Plus256k
+      include Banking
+
+      def initialize(ram)
+        @banks = [ram, Memory.new, Memory.new, Memory.new]
+        @on_change = nil
+        reset!
+      end
+
+      def poke(_addr, value)
+        return if @locked
+
+        @low_ram = @banks[value & 0b11]
+        @video_ram = @banks[(value >> 2) & 0b11]
+        @high_ram = @banks[value >> 6]
+        @locked = value.anybits?(0x10)
+        @on_change&.call
+      end
+
+      def reset!
+        @low_ram = @video_ram = @high_ram = @banks[0]
+        @locked = false
+      end
+
+      def power_on!
+        @banks.drop(1).each(&:clear!)
+      end
+    end
+  end
+end

data/lib/badline/ram_expansion/plus60k.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Badline
+  module RAMExpansion
+    # The +60K: a second bank of RAM behind $1000-$FFFF, selected by bit 7
+    # of $D100. $0000-$0FFF stays the machine's own RAM, and so does all of
+    # what the VIC sees.
+    class Plus60k
+      include Banking
+
+      def initialize(ram)
+        @low_ram = @video_ram = @high_ram = ram
+        @banks = [ram, Memory.new]
+        @on_change = nil
+      end
+
+      def poke(_addr, value)
+        @high_ram = @banks[value >> 7]
+        @on_change&.call
+      end
+
+      def reset!
+        @high_ram = @banks[0]
+      end
+
+      def power_on!
+        @banks[1].clear!
+      end
+    end
+  end
+end

data/lib/badline/ram_expansion/unexpanded.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Badline
+  module RAMExpansion
+    # The machine with no expansion fitted: its own RAM everywhere, and
+    # $D100 left to the VIC.
+    class Unexpanded
+      include Banking
+
+      def initialize(ram)
+        @low_ram = @video_ram = @high_ram = ram
+        @on_change = nil
+      end
+
+      def map_io(_read_pages, _write_pages); end
+
+      def reset!; end
+
+      def power_on!; end
+    end
+  end
+end

data/lib/badline/ram_expansion.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "badline/ram_expansion/banking"
+require "badline/ram_expansion/unexpanded"
+require "badline/ram_expansion/plus60k"
+require "badline/ram_expansion/plus256k"
+
+module Badline
+  # RAM expansions that bank extra memory in under the CPU through a
+  # register at $D100, in the VIC's I/O page. Any write to $D100-$D1FF
+  # sets the register, which reads back as $FF.
+  module RAMExpansion
+    TYPES = { plus60k: Plus60k, plus256k: Plus256k }.freeze
+
+    def self.build(type, ram, &)
+      expansion = type ? TYPES.fetch(type).new(ram) : Unexpanded.new(ram)
+      expansion.on_change(&)
+      expansion
+    end
+  end
+end

data/lib/badline/region.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Badline
+  # = Region
+  #
+  # The timing and geometry a video standard gives the machine.
+  module Region
+    # The CPU clock, the VIC's raster, where the beam is blanked, the display
+    # window's edges, the part of the raster a front end shows, and the
+    # mains frequency that feeds the CIAs' TOD pins.
+    #
+    # Columns are the VIC's cycles within a line, counted from 0, and a
+    # column draws 8 pixels, so the raster is `cycles_per_line * 8` pixels
+    # wide. `hblank` and `vblank` are the [first, last] blanked column and
+    # line, inclusive, and wrap past the end of the line or frame when first
+    # is the larger. `display_x_bounds` holds the display window's
+    # [left, right] pixels per CSEL state, 38 columns then 40, and `crop`
+    # the [left, top, width, height] a front end shows.
+    Profile = Data.define(:name, :clock_hz, :cycles_per_line, :lines_per_frame, :hblank, :vblank,
+                          :display_x_bounds, :crop, :mains_hz)
+
+    # The 6569 of a PAL C64: 63 cycles by 312 lines at 985,248 Hz, with
+    # 50 Hz mains.
+    PAL = Profile.new(
+      name: :pal, clock_hz: 985_248, cycles_per_line: 63, lines_per_frame: 312,
+      hblank: [61, 9].freeze, vblank: [300, 15].freeze,
+      display_x_bounds: [[135, 438].freeze, [128, 447].freeze].freeze,
+      crop: [96, 20, 384, 272].freeze, mains_hz: 50
+    )
+
+    # The 6567R8 of an NTSC C64: 65 cycles by 263 lines at 1,022,727 Hz,
+    # with 60 Hz mains, and lines 13-40 blanked (Bauer). The machine does
+    # not run it yet: the blanked columns and the display window are PAL's
+    # stand-ins, and the crop leaves out lines 0-12, which show below the
+    # last line.
+    NTSC = Profile.new(
+      name: :ntsc, clock_hz: 1_022_727, cycles_per_line: 65, lines_per_frame: 263,
+      hblank: [61, 9].freeze, vblank: [13, 40].freeze,
+      display_x_bounds: [[135, 438].freeze, [128, 447].freeze].freeze,
+      crop: [96, 41, 384, 222].freeze, mains_hz: 60
+    )
+
+    # Whether a column or line lies in a [first, last] blanking span.
+    def self.blanked?(position, span)
+      first, last = span
+      return position.between?(first, last) if first <= last
+
+      position >= first || position <= last
+    end
+  end
+end

data/lib/badline/rom.rb

@@ -1,17 +1,26 @@
 # frozen_string_literal: true
 
 module Badline
+  class << self
+    attr_writer :rom_path
+
+    # The directory ROM images and other bundled binaries load from.
+    # Defaults to $BADLINE_ROM_PATH, then to the roms directory next to this
+    # file. Assigning nil restores the default.
+    def rom_path
+      @rom_path ||= ENV.fetch("BADLINE_ROM_PATH", File.expand_path("roms", __dir__))
+    end
+  end
+
   class ROM < Memory
     class << self
       def load(filename, start = 0x0)
-        data = File.read(file_path(filename)).bytes
+        data = read(filename)
         new(data, length: data.length, start: start)
       end
 
-      private
-
-      def file_path(filename)
-        File.join(File.dirname(__FILE__), "roms", filename)
+      def read(filename)
+        File.binread(File.join(Badline.rom_path, filename)).bytes
       end
     end
 

data/lib/badline/sdl/events.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Badline
+  module SDL
+    KEY_TAB = 0x09
+    KEY_F10 = 0x4000_0043
+    KMOD_SHIFT = 0x0003
+
+    # The events the front end handles. SDL_Event is a 56-byte union, read
+    # here at the offsets its keyboard, mouse and controller members use.
+    Quit = Data.define
+    # A held key sends repeats, flagged at byte 13 of the event.
+    KeyDown = Data.define(:sym, :mod, :repeat) do
+      def initialize(sym:, mod:, repeat: false) = super
+    end
+    KeyUp = Data.define(:sym, :mod)
+    MouseMotion = Data.define(:xrel, :yrel)
+    MouseButton = Data.define(:button, :pressed)
+    ControllerDevice = Data.define
+
+    EVENT_SIZE = 56
+
+    # The next event the front end handles, skipping the others, or nil once
+    # the queue is empty.
+    def self.poll_event
+      buffer = (@event ||= Fiddle::Pointer.malloc(EVENT_SIZE, Fiddle::RUBY_FREE))
+      while PollEvent.call(buffer) == 1
+        event = decode(buffer.to_str(EVENT_SIZE))
+        return event if event
+      end
+      nil
+    end
+
+    def self.decode(bytes)
+      case bytes.unpack1("L")
+      when 0x100 then Quit.new
+      when 0x300 then KeyDown.new(*bytes.unpack("lS", offset: 20), bytes.getbyte(13) != 0)
+      when 0x301 then KeyUp.new(*bytes.unpack("lS", offset: 20))
+      when 0x400 then MouseMotion.new(*bytes.unpack("l2", offset: 28))
+      when 0x401, 0x402 then MouseButton.new(bytes.getbyte(16), bytes.getbyte(17) == 1)
+      when 0x653..0x655 then ControllerDevice.new
+      end
+    end
+
+    def self.key_name(sym) = GetKeyName.call(sym)
+  end
+end

data/lib/badline/sdl/functions.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Badline
+  module SDL
+    INIT_AUDIO = 0x10
+    INIT_VIDEO = 0x20
+    INIT_GAMECONTROLLER = 0x2000
+    INIT_EVENTS = 0x4000
+
+    WINDOWPOS_CENTERED = 0x2fff_0000
+    WINDOW_RESIZABLE = 0x20
+    RENDERER_ACCELERATED = 0x02
+    RENDERER_PRESENTVSYNC = 0x04
+
+    AUDIO_S16SYS = [1].pack("s").getbyte(0) == 1 ? 0x8010 : 0x9010
+    AUDIO_ALLOW_FREQUENCY_CHANGE = 0x01
+
+    CONTROLLER_AXIS_LEFTX = 0
+    CONTROLLER_AXIS_LEFTY = 1
+    CONTROLLER_BUTTON_A = 0
+    CONTROLLER_BUTTON_B = 1
+    CONTROLLER_BUTTON_X = 2
+    CONTROLLER_BUTTON_Y = 3
+    CONTROLLER_BUTTON_LEFTSHOULDER = 9
+    CONTROLLER_BUTTON_RIGHTSHOULDER = 10
+    CONTROLLER_BUTTON_DPAD_UP = 11
+    CONTROLLER_BUTTON_DPAD_DOWN = 12
+    CONTROLLER_BUTTON_DPAD_LEFT = 13
+    CONTROLLER_BUTTON_DPAD_RIGHT = 14
+
+    InitSubSystem = function("SDL_InitSubSystem", [UINT32], INT)
+    QuitSubSystem = function("SDL_QuitSubSystem", [UINT32], VOID)
+    GetError = function("SDL_GetError", [], STRING)
+    SetHint = function("SDL_SetHint", [STRING, STRING], INT)
+
+    CreateWindow = function("SDL_CreateWindow", [STRING, INT, INT, INT, INT, UINT32], POINTER)
+    SetWindowTitle = function("SDL_SetWindowTitle", [POINTER, STRING], VOID)
+    DestroyWindow = function("SDL_DestroyWindow", [POINTER], VOID)
+    GetCurrentDisplayMode = function("SDL_GetCurrentDisplayMode", [INT, POINTER], INT)
+    CreateRenderer = function("SDL_CreateRenderer", [POINTER, INT, UINT32], POINTER)
+    DestroyRenderer = function("SDL_DestroyRenderer", [POINTER], VOID)
+    RenderSetLogicalSize = function("SDL_RenderSetLogicalSize", [POINTER, INT, INT], INT)
+    SetRenderDrawColor = function("SDL_SetRenderDrawColor", [POINTER, UINT8, UINT8, UINT8, UINT8], INT)
+    RenderClear = function("SDL_RenderClear", [POINTER], INT)
+    RenderCopy = function("SDL_RenderCopy", [POINTER, POINTER, POINTER, POINTER], INT)
+    RenderPresent = function("SDL_RenderPresent", [POINTER], VOID)
+    CreateRGBSurfaceFrom = function("SDL_CreateRGBSurfaceFrom",
+                                    [POINTER, INT, INT, INT, INT, UINT32, UINT32, UINT32, UINT32], POINTER)
+    FreeSurface = function("SDL_FreeSurface", [POINTER], VOID)
+    CreateTextureFromSurface = function("SDL_CreateTextureFromSurface", [POINTER, POINTER], POINTER)
+    DestroyTexture = function("SDL_DestroyTexture", [POINTER], VOID)
+
+    PollEvent = function("SDL_PollEvent", [POINTER], INT)
+    PushEvent = function("SDL_PushEvent", [POINTER], INT)
+    GetKeyName = function("SDL_GetKeyName", [INT], STRING)
+    SetRelativeMouseMode = function("SDL_SetRelativeMouseMode", [INT], INT)
+
+    NumJoysticks = function("SDL_NumJoysticks", [], INT)
+    IsGameController = function("SDL_IsGameController", [INT], INT)
+    GameControllerOpen = function("SDL_GameControllerOpen", [INT], POINTER)
+    GameControllerName = function("SDL_GameControllerName", [POINTER], STRING)
+    GameControllerGetButton = function("SDL_GameControllerGetButton", [POINTER, INT], UINT8)
+    GameControllerGetAxis = function("SDL_GameControllerGetAxis", [POINTER, INT], INT16)
+    GameControllerClose = function("SDL_GameControllerClose", [POINTER], VOID)
+
+    OpenAudioDevice = function("SDL_OpenAudioDevice", [STRING, INT, POINTER, POINTER, INT], UINT32)
+    CloseAudioDevice = function("SDL_CloseAudioDevice", [UINT32], VOID)
+    PauseAudioDevice = function("SDL_PauseAudioDevice", [UINT32, INT], VOID)
+    QueueAudio = function("SDL_QueueAudio", [UINT32, POINTER, UINT32], INT)
+    GetQueuedAudioSize = function("SDL_GetQueuedAudioSize", [UINT32], UINT32)
+    ClearQueuedAudio = function("SDL_ClearQueuedAudio", [UINT32], VOID)
+  end
+end

data/lib/badline/sdl.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Badline
+  # The libSDL2 calls the window, the gamepads and the audio sink make,
+  # bound through Fiddle, so nothing has to compile against SDL at install
+  # time. Only the library itself has to be present.
+  #
+  # Each function is a constant named after its C name without the prefix:
+  # SDL::RenderClear.call(renderer) calls SDL_RenderClear. They're built
+  # with need_gvl, which skips releasing Ruby's lock around the call: none
+  # of these block for long, and releasing it costs more than most of them.
+  module SDL
+    class Error < StandardError; end
+
+    # Where package managers put the shared library. dlopen searches the
+    # system paths for the bare names, but not Homebrew's.
+    LIBRARIES = %w[
+      libSDL2-2.0.so.0 libSDL2.so
+      libSDL2-2.0.0.dylib /opt/homebrew/lib/libSDL2-2.0.0.dylib /usr/local/lib/libSDL2-2.0.0.dylib
+      SDL2.dll
+    ].freeze
+
+    def self.open_library
+      LIBRARIES.each do |name|
+        return Fiddle.dlopen(name)
+      rescue Fiddle::DLError
+        next
+      end
+      raise Error, "can't find libSDL2 (tried #{LIBRARIES.join(', ')})"
+    end
+
+    LIBRARY = open_library
+
+    VOID = Fiddle::TYPE_VOID
+    INT = Fiddle::TYPE_INT
+    UINT8 = Fiddle::TYPE_UINT8_T
+    INT16 = Fiddle::TYPE_INT16_T
+    UINT32 = Fiddle::TYPE_UINT32_T
+    POINTER = Fiddle::TYPE_VOIDP
+    STRING = Fiddle::TYPE_CONST_STRING
+
+    def self.function(name, arguments, result)
+      Fiddle::Function.new(LIBRARY[name], arguments, result, name:, need_gvl: true)
+    end
+
+    def self.error = GetError.call
+
+    # A negative result from SDL is an error, and SDL_GetError says which.
+    def self.check(result)
+      raise Error, error if result.negative?
+
+      result
+    end
+
+    # So is a null handle.
+    def self.check_pointer(pointer)
+      raise Error, error if pointer.null?
+
+      pointer
+    end
+  end
+end
+
+require "badline/sdl/functions"
+require "badline/sdl/events"