badline 0.6.1 → 0.8.0

data/doc/media.md

@@ -0,0 +1,69 @@
+# Media
+
+The [README](../README.md#media) lists the formats badline takes. This
+page covers how device 8 and the true 1541 work, and how to attach media
+from Ruby.
+
+## Device 8 without a drive
+
+Apart from a `.g64`, which only a true drive can read, there is no 1541
+unless `--true-drive` asks for one. Device 8 works by trapping the
+KERNAL's `LOAD` and `SAVE` routines and its serial bus primitives, so
+files open by name through `OPEN` and `CHRIN` as well. `LOAD"$",8` lists
+the directory of any medium mounted there, as a 1541 does.
+
+The command channel answers `I`, `B-P` and `U1` block reads, which
+covers loaders that read blocks directly. On a writable disk image it
+also takes `SAVE` (with `@0:` to replace a file), files opened for
+writing or appending, `S` to scratch, `U2` and `B-W` block writes, and
+`B-A` and `B-F`. It doesn't rename, copy, format or validate disks.
+Loaders that upload their own code to the drive with `M-W` and `M-E`,
+and copy protection that reads raw GCR, won't work there, but do on a
+true drive.
+
+A directory mounted as device 8 serves the `.prg` and `.p00` files in it
+and the contents of any `.t64`, and `SAVE` writes a new `.prg`.
+
+## The true 1541
+
+`--true-drive` puts an emulated 1541 on device 8 instead, running its
+own DOS ROM on its own 6502 and talking to the machine over the serial
+bus. It reads `.d64` and `.g64` images, which it autostarts with the
+same `LOAD"*",8,1` and `RUN`, but not `.d71`, `.d81` or `.t64` images
+or directories. Loading runs at the speed of a real 1541, and the
+drive's red LED lights in the bottom right corner of the border.
+
+A `.g64` holds the disk's raw GCR, half tracks and all, so copy
+protection and fast loaders that read it work.
+
+## Write protection
+
+Disks given on the command line, inserted from the pause menu or by an
+`--at` insert go in write-protected, so the drive reports
+`26,WRITE PROTECT ON` for any write and the image file stays as it was.
+`--writable`, or WRITABLE on the pause menu's Drive page, lets writes go
+straight back to the image file. An image the host can't write, and a
+`.t64`, stay write-protected.
+
+## From Ruby
+
+`Badline::Media.attach(computer, path)` attaches any medium the
+command line takes, and autostarts it unless given `autostart: false`.
+`Badline::Media.insert_disk(computer, path)` swaps the disk image or
+directory in device 8 while the machine runs, for software that asks for
+another disk. Both write to disk images unless told otherwise:
+`insert_disk` takes `read_only: true`, and `attach` takes
+`disk: { read_only: true }`, as the test harnesses under `bin/` do. A
+`.g64` goes in the true 1541, and takes out a disk mounted through the
+traps, so `LOAD` and `SAVE` reach the 1541 too. With the 1541 in device
+8, a `.d64` goes in its drive as well.
+
+`Badline::Media::DiskSet.around(path)` lists the disks of the set a disk
+image belongs to, found by name in its folder, which the pause menu's
+PREVIOUS DISK and NEXT DISK step through.
+
+## The light pen
+
+Control port 1's fire line is also the VIC-II's light pen input, so
+joystick 1's fire button and the 1351's left button in port 1 latch the
+light pen registers.

data/doc/sid-player.md

@@ -0,0 +1,132 @@
+# The SID player
+
+The [README](../README.md#playing-and-rendering-sid-tunes) shows how to
+start it. This page covers the player in detail.
+
+```sh
+badline sid ~/C64Music/MUSICIANS/H/Hubbard_Rob               # play every tune below a directory
+badline sid tune.sid other.sid                               # play a queue of tunes
+badline --headless tune.sid                             # play, length from HVSC
+badline --headless -s 3 tune.sid                        # play the third subtune
+badline --headless --all-subtunes tune.sid              # play on through every subtune
+badline --seconds 180 tune.sid --audio-out out.aiff
+badline -s 3 --rate 48000 tune.sid --audio-out out.wav
+badline --headless --sid 8580 tune.sid
+badline --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slower
+```
+
+## The queue
+
+`badline sid FILE|DIR...` plays a queue of tunes in the SID player's
+window, in the order given, and a directory adds every `.sid` tune below
+it in path order. `badline sid --headless` plays the queue in the
+terminal instead. `badline sid` on its own opens the window with an
+empty queue. Dropping `.sid` files or folders on the window adds them
+to the end of the queue, and an empty queue starts playing them. A file
+that isn't a tune is skipped.
+
+`badline tune.sid` plays the tune in the SID player too, unless an
+option of the emulator's window, such as `--ntsc` or `--reu`, asks for
+the machine: then a tune for one SID runs on the emulated C64, started
+through a small driver after boot.
+
+`--subtune` (or `-s`) picks the first tune's subtune, counting from 1 as
+HVSC does, and defaults to the tune's own start subtune. Each tune plays
+that one subtune, and when it ends the player goes on to the next tune,
+stopping after the last. `a`, or `--all-subtunes`, turns on playing all
+subtunes, so that a subtune that ends goes on to the tune's next
+subtune, and a tune stepped to starts on its first subtune.
+
+`--sid auto`, the default, fits each of a tune's SIDs the model its
+header names. A tune written for 2 or 3 SIDs plays on as many, at the
+addresses its header gives, in stereo: SID 1 on the left, SID 2 on the
+right and SID 3 in the centre. A tune on one SID plays the same on both
+channels.
+
+Playback asks the device for 44.1 kHz and takes whatever rate it
+offers, unless `--rate` says otherwise. Ctrl-C stops it. The emulator
+window's own options, `--no-autostart`, `--writable`, `--sound`,
+`--true-drive`, `--reu`, `--ntsc` and `--verbose`, don't apply.
+
+## The window
+
+The window is worked with the mouse. Its header shows the tune's name,
+author and release, the tune the subtune covers at the moment when
+HVSC's STIL credits one, following the times STIL gives, and buttons
+that switch between three views and between the tune's own SID model,
+the 6581 and the 8580, which changes the chips playing on the spot. Its
+footer shows the time played on a bar you can click to seek, and buttons
+that pause, step between tunes and between a tune's subtunes, and turn
+shuffle, looping and all subtunes on and off.
+
+- The visualizer shows each voice's note, and how far off it is in
+  cents, over a scope of the voice's output, and the mixed output below
+  them. A tune on more than one SID gets a row of voices for each SID,
+  and the mix splits into its left and right.
+- The SID view shows one SID at a time, and for a tune on more than one,
+  a row of SID 1, 2 and 3 buttons at its top picks which. It shows each
+  voice's output, its control bits, pulse width, envelope settings, and
+  the envelope's level and stage, and the filter's modes, cutoff,
+  resonance, volume and its response on the chip playing.
+- The INFO view shows the tune's STIL entry and the subtune's, with a
+  scroll bar, the mouse wheel or the up and down keys for the long ones.
+
+The terminal's keys work in the window too, along with Tab to switch
+views and `c` to step through the SID models.
+
+## The terminal
+
+Played on a terminal, `--headless` and `sid` show each tune's name,
+author and release as it starts, then the tune's place in the queue, the
+subtune number and the time played against the subtune's length.
+`--headless` queues just the one tune.
+
+→ and ← step to the tune's next and previous subtune, stopping at its
+first and last. `n` and `p` step to the next and previous tune. `s`
+turns shuffle on and off, which plays the queue's tunes in a random
+order, and `l` turns looping on and off, so that the end of the queue
+goes on to its start. `,` and `.` seek 10 seconds back and forward
+within the subtune: a seek forward runs on silently from where the
+subtune is, and a seek back plays it again from its start up to the
+point asked for. Space pauses and `q` quits. The status line shows which
+modes are on, and they last until the player quits.
+
+`--no-tui`, or output that isn't a terminal, gives plain progress output
+instead and plays through the queue without the keys.
+
+## Rendering
+
+`--audio-out` renders one subtune to a 16-bit stereo PCM file. The
+file's extension picks the format, `.wav` or `.aiff`.
+
+## Lengths and STIL
+
+A `.sid` file doesn't store its length, so the player looks the tune up
+by MD5 in HVSC's `Songlengths.md5`. It finds the database through
+`--songlengths`, in a `DOCUMENTS` directory in any of the tune's parent
+directories (the layout of an HVSC collection), or under
+`$HVSC_BASE/DOCUMENTS`. Without a database or `--seconds` it runs for 60
+seconds, but a subtune that falls silent for 5 seconds before then ends
+there, when played and when rendered alike. Silent means the output
+holds within 16 steps of one level, since a 6581 idles at a DC offset
+rather than at zero. A subtune with a known length plays to its length
+whatever it sounds like.
+
+A tune in an HVSC collection also gets its entry in HVSC's `STIL.txt`,
+found the same way: comments, covers, and subtune names and composers.
+The tune's own fields follow its header, and each subtune's print as it
+starts.
+
+## Speed
+
+`badline` plays PSID and RSID tunes in real time. In `badline-ruby`,
+PSID tunes run on a CPU and RAM with only the SID clocked, at about
+twice real time, so they play smoothly, but RSID tunes set up their own
+interrupts, so they boot a full C64 first and run at about half real
+time. They render fine but stutter when played, and `badline-ruby` says
+so when it falls behind. Both builds run the same code, so they render
+the same file sample for sample. See
+[native/README.md](../native/README.md#without-the-window).
+
+The filter steps four cycles at a time; `--filter-chunk 1` steps it
+every cycle, which is exact and takes about twice as long.

data/doc/snapshots.md

@@ -0,0 +1,69 @@
+# Snapshots
+
+In the window, `F11` saves the whole machine to a new
+`badline-<date>-<time>.vsf` in the working directory, and `F12` goes
+back to the snapshot last saved or opened, in a new machine built as the
+saved one was. Both executables do this, and both open a `.vsf` given as
+the media. A snapshot that fails to open leaves the machine running as
+it was.
+
+## From Ruby
+
+`computer.save_snapshot(path)` saves, `computer.restore_snapshot(path)`
+takes a machine back to a snapshot, and `Badline::Snapshot.load(path)`
+builds a new machine as the saved one was built and restores it.
+`computer.snapshot` and `computer.restore(state)` do the same in memory,
+without a file. A restore that fails leaves the machine as it was.
+
+## What a snapshot holds
+
+A snapshot holds the machine as it was on the cycle it was saved: the
+chips down to the instruction step and the pixel pipeline, the RAM and
+any +60K or +256K expansion, the cartridge with its RAM and flash, a
+GEO-RAM, a true 1541 with its RAM, its VIAs and the disk under the head,
+a disk or directory mounted through the traps with its open channels,
+and the tape with its place on it. A restored machine runs on exactly
+as the saved one would have.
+
+A directory, a tape and a true drive's disk image open again from their
+paths when the snapshot is restored, the disk with its tracks as the
+drive last saw them. A disk image mounted through the traps comes back
+with its contents from the snapshot. What the host holds stays the
+host's: the keyboard, the joysticks, the mouse and paddles, sound, and
+blocks given to `on_init` that hadn't run yet, which a restore reports.
+
+A snapshot only restores in the badline version that wrote it, into a
+machine with the same chip models, RAM expansion and REU.
+`computer.snapshot` holds an REU's RAM, registers and transfer too, but
+a machine with an REU doesn't save to a file yet, as badline doesn't
+write VICE's REU module. Nor does an NTSC machine, as badline doesn't
+write an NTSC VIC-II in VICE's terms yet.
+
+## VICE
+
+Snapshots use VICE's `.vsf` format. badline writes VICE's modules for
+the CPU, RAM and CPU port, both CIAs, the SID and the VIC-II, plus the
+ones x64sc needs to open the file, with nothing attached to the
+cartridge, tape or user ports and no true drive. A `BADLINE` module,
+which VICE skips, holds the whole machine, and badline restores its own
+snapshots from it.
+
+x64sc 3.10 opens badline's snapshots, taken at the end of the
+instruction the CPU was in, as long as its VIC-II model matches
+(`-model c64` for the default machine). It keeps its own drives and
+leaves out the cartridge, the expansions and the tape.
+
+Snapshots x64sc saves open in badline through the same modules: the CPU
+at its instruction boundary, RAM, the CPU port, the CIAs' registers,
+timers and clocks, the SID's registers and reSID voice state, and the
+VIC-II's registers, beam position, counters and colour RAM. The VIC-II's
+pixel pipeline starts empty. badline reads the modules x64sc 3.7 to 3.10
+write, and VICE's development versions' `MAINC64CPU` and `VIC-IISC`. A
+module version it doesn't know is left out, or fails the restore for the
+CPU and RAM. It reports the modules it leaves out, such as the 1541
+drives, the cartridge, the datasette and the keyboard, and carries on
+without them. A snapshot of an NTSC machine fails, as badline reads only
+VICE's PAL VIC-II. Restored into a running machine, a VICE snapshot
+fails for a machine built another way, such as a C64C's snapshot in a
+C64, and otherwise takes the cartridge out and switches the machine off
+and on.

data/exe/badline-ruby

@@ -36,13 +36,21 @@ end
 
 if options.headless?
   require "badline/audio/console"
+  console = if options.player_window?
+              lambda do |input:, output:|
+                load_sdl
+                Badline::Frontend::PlayerWindow.new(input:, output:)
+              end
+            else
+              Badline::Audio::Console.method(:new)
+            end
   sink = lambda do |rate:, exact_rate:|
     load_sdl
     Badline::Frontend::AudioSink.new(rate:, exact_rate:)
   rescue Badline::FFI::Error => e
     raise Badline::Audio::Playback::DeviceError, e.message
   end
-  exit Badline::Audio::CLI.run(options, sink:, console: Badline::Audio::Console.method(:new))
+  exit Badline::Audio::CLI.run(options, sink:, console:)
 end
 
 begin

data/lib/badline/address_bus/extra_sids.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The second and third SIDs the SID player fits for a tune written for
+    # them, each over its 32 bytes of the I/O area (SIDSlots). The SID
+    # player's machine has nothing else in I/O 1 and 2, so the rest of a
+    # page there reads the open bus.
+    module ExtraSIDs
+      # Fits a SID at the address it was built at, where it takes its 32
+      # bytes over from whatever maps there.
+      def add_sid(sid)
+        page = sid.start >> 8
+        slots = @sid_slots.find { |candidate| candidate.page == page }
+        if slots.nil?
+          slots = SIDSlots.new(page, @sid, @open_bus)
+          @sid_slots << slots
+        end
+        slots.place(sid)
+        update_overlays!
+      end
+
+      private
+
+      def map_extra_sids
+        @sid_slots.each { |slots| @read_pages[slots.page] = @write_pages[slots.page] = slots }
+      end
+    end
+  end
+end

data/lib/badline/address_bus/sid_slots.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # Stands in for a page of I/O that a second or third SID shares: each 32
+    # bytes of it go to the SID placed there, or else to the first SID's
+    # mirrors in `$d400-$d7ff`, and to the open bus in I/O 1 and 2.
+    class SIDSlots
+      attr_reader :page
+
+      def initialize(page, first, open_bus)
+        @page = page
+        @io = page >= 0xde
+        @first = first
+        @open_bus = open_bus
+        @sids = []
+        @slots = Array.new(8, -1)
+      end
+
+      def place(sid)
+        @slots[(sid.start >> 5) & 7] = @sids.size
+        @sids << sid
+      end
+
+      def peek(addr)
+        index = @slots[(addr >> 5) & 7]
+        return @sids[index].peek(addr) unless index.negative?
+
+        @io ? @open_bus.peek(addr) : @first.peek(addr)
+      end
+
+      def poke(addr, value)
+        index = @slots[(addr >> 5) & 7]
+        if !index.negative?
+          @sids[index].poke(addr, value)
+        elsif !@io
+          @first.poke(addr, value)
+        end
+      end
+    end
+  end
+end

data/lib/badline/address_bus.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "badline/address_bus/saved_state"
+require "badline/address_bus/sid_slots"
+require "badline/address_bus/extra_sids"
 require "badline/address_bus/ultimax_pages"
 
 module Badline
@@ -32,6 +34,7 @@ module Badline
   class AddressBus
     include Addressable
     include UltimaxPages
+    include ExtraSIDs
 
     # I/O 1 and 2, and the Ultimax holes, with nothing on the bus. A read
     # picks up the byte the VIC fetched in the preceding phi1 half-cycle,
@@ -82,6 +85,7 @@ module Badline
       @control_ports.port_a_source = @cia1
       @cia1.on_port_b4_change { |high| @vic.lightpen_level(high) }
       @sid = SID.new(model: sid_model, pots: @control_ports)
+      @sid_slots = []
 
       @datasette = Datasette.new
       @datasette.on_flag { @cia1.flag! }
@@ -252,6 +256,7 @@ module Badline
       @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
       @read_pages[0xdf] = @write_pages[0xdf] = @reu if @reu
       map_cartridge_io if @cartridge
+      map_extra_sids unless @sid_slots.empty?
     end
 
     def map_cartridge_io

data/lib/badline/audio/aiff.rb

@@ -13,14 +13,14 @@ module Badline
 
       def header
         ["FORM", 0, "AIFF",
-         "COMM", 18, 1, 0, 16].pack("a4Na4a4NnNn") +
+         "COMM", 18, channels, 0, 16].pack("a4Na4a4NnNn") +
           extended(rate) +
           ["SSND", 0, 0, 0].pack("a4NNN")
       end
 
       def patch
         write_at(4, [46 + data_size].pack("N"))
-        write_at(22, [samples].pack("N"))
+        write_at(22, [frames].pack("N"))
         write_at(42, [8 + data_size].pack("N"))
       end
 

data/lib/badline/audio/bare_player.rb

@@ -44,12 +44,12 @@ module Badline
       # The KERNAL's PAL/NTSC flag, 1 for PAL.
       VIDEO_STANDARD = 0x02a6
 
-      attr_reader :sid
+      attr_reader :sid, :stereo
 
-      def initialize(tune, song: nil, sid_model: tune.sid_model)
+      def initialize(tune, subtune: nil, sid_models: tune.sid_models)
         @tune = tune
-        @song = (song || tune.start_song).clamp(1, tune.songs) - 1
-        @bus = AddressBus.new(sid_model:)
+        @subtune = (subtune || tune.start_subtune).clamp(1, tune.subtunes) - 1
+        @bus = AddressBus.new(sid_model: sid_models[0])
         # The CPU port as the KERNAL leaves it, which a PSID tune expects.
         @bus.poke(0x00, 0x2f)
         @bus.poke(0x01, 0x37)
@@ -57,28 +57,38 @@ module Badline
         @bus.cia1.timer_a_latch = tune.ntsc? ? NTSC_KERNAL_TIMER : KERNAL_TIMER
         @cpu = CPU.new(@bus)
         @sid = @bus.sid
+        @stereo = Stereo.new(@bus, tune, sid_models)
+        @extras = @stereo.extras
+        @multi = !@extras.empty?
         @idle = false
       end
 
       def start
         @bus.ram.write(@tune.load_address, @tune.data)
         @bus.ram.write(stub_address, stub)
-        @sid.synthesize!
+        @stereo.synthesize!
         @cpu.status.interrupt = true
         @cpu.program_counter = idle_address
         install_dispatch
-        call(@tune.init_address, @song)
+        call(@tune.init_address, @subtune)
         settle
       end
 
       # Advances one call of play, or `budget` cycles if that is shorter,
-      # then yields whatever the SID recorded over it. Returns the cycles
-      # advanced.
+      # then yields whatever the SIDs recorded over it, in stereo. Returns
+      # the cycles advanced.
       def frame(budget, &)
         call(@tune.play_address)
         cycles = [budget, period].min
-        cycles.times { step }
-        @sid.drain_samples.each(&)
+        if @multi
+          cycles.times { step }
+        else
+          cycles.times do
+            @sid.cycle!
+            @cpu.cycle!
+          end
+        end
+        @stereo.mix(&)
         cycles
       end
 
@@ -86,10 +96,10 @@ module Badline
 
       private
 
-      # A video frame, or for a CIA-timed song one period of CIA 1 timer A,
+      # A video frame, or for a CIA-timed subtune one period of CIA 1 timer A,
       # which init and play are both free to reprogram.
       def period
-        return (@tune.ntsc? ? NTSC_FRAME_CYCLES : FRAME_CYCLES) unless @tune.cia_timed?(@song + 1)
+        return (@tune.ntsc? ? NTSC_FRAME_CYCLES : FRAME_CYCLES) unless @tune.cia_timed?(@subtune + 1)
 
         @bus.cia1.timer_a_latch + 1
       end
@@ -117,6 +127,7 @@ module Badline
 
       def step
         @sid.cycle!
+        @extras.each(&:cycle!) if @multi
         @cpu.cycle!
       end