badline 0.12.0 → 0.13.0

data/lib/badline/chips/sid/filter.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "badline/chips/sid/filter/saved_state"
+
+module Badline
+  module Chips
+    class SID
+      # The SID's multimode filter: a state-variable design integrating low-,
+      # band- and high-pass in parallel, with the mixer and master volume on
+      # its output, and the C64 board's own RC network after that.
+      #
+      # Voices are routed through it or around it per the RES/FILT register,
+      # and the outputs selected by MODE/VOL are summed back together with the
+      # unfiltered ones.
+      class Filter
+        include SavedState
+
+        # Cutoff frequency in Hz at each chip's breakpoints. The 6581 curve was
+        # sampled from a real chip by reSID and bends sharply around $300; the
+        # 8580's is close to a straight line from 0 to 12.5 kHz. The curve
+        # between breakpoints is interpolated linearly; reSID fits a spline, so
+        # the two differ by a few Hz mid-segment.
+        CUTOFF_POINTS = {
+          mos6581: [[0, 220], [128, 230], [256, 250], [384, 300],
+                    [512, 420], [640, 780], [768, 1600], [832, 2300],
+                    [896, 3200], [960, 4300], [1024, 5000], [1088, 5400],
+                    [1152, 5800], [1216, 6000], [1280, 6200], [1344, 6400],
+                    [1408, 6600], [1472, 6800], [1536, 7000], [1600, 7200],
+                    [1664, 7400], [1728, 7600], [1792, 7800], [1856, 8000],
+                    [1920, 8200], [1984, 8400], [2047, 8600]].freeze,
+          mos8580: [[0, 0], [128, 800], [256, 1600], [384, 2500],
+                    [512, 3300], [640, 4100], [768, 4800], [896, 5600],
+                    [1024, 6500], [1152, 7500], [1280, 8400], [1408, 9200],
+                    [1536, 9800], [1664, 10_500], [1792, 11_000],
+                    [1920, 11_700], [2047, 12_500]].freeze
+        }.freeze
+
+        # 2^20 / 1 MHz, so one cycle of integration is a plain shift.
+        SCALE = (2**20) / 1_000_000.0
+
+        # The integrator goes unstable above ~16 kHz at a one-cycle step.
+        W0_MAX = (2 * Math::PI * 16_000 * SCALE).to_i
+
+        # A step of several cycles scales w0 by their count. reSID keeps such
+        # a step stable by capping the cutoff at 4 kHz over 8 cycles; this is
+        # the same bound on the product, so a single cycle is never capped.
+        W0_STEP_MAX = (2 * Math::PI * 4_000 * 8 * SCALE).to_i
+
+        def self.build_w0(points)
+          table = Array.new(2048)
+          points.each_cons(2) do |(fc0, hz0), (fc1, hz1)|
+            (fc0..fc1).each do |register|
+              hz = hz0 + (((hz1 - hz0) * (register - fc0)).to_f / (fc1 - fc0))
+              table[register] = [(2 * Math::PI * hz * SCALE).to_i, W0_MAX].min
+            end
+          end
+          table.freeze
+        end
+        private_class_method :build_w0
+
+        W0 = CUTOFF_POINTS.transform_values { |points| build_w0(points) }.freeze
+
+        # 1024/Q, with Q sweeping from 0.707 up to 1.707 across the register.
+        RESONANCE = (0x0..0xf).map { |res| (1024.0 / (0.707 + (res / 15.0))).to_i }.freeze
+
+        # The mixer's own input DC offset, derived by reSID from the 6581's
+        # zero-volume and full-volume output levels. The 8580 has none.
+        MIXER_DC = { mos6581: -((0xfff * 0xff) / 18) >> 7, mos8580: 0 }.freeze
+
+        # Fractional bits carried in the integrators. At low cutoffs a cycle's
+        # step is only a few units, which truncating to whole units would
+        # swallow, and always toward minus infinity.
+        FRACTION = 12
+
+        # The RC network between the SID's audio pin and the C64's output jack:
+        # a 10kΩ/1000pF low-pass at ~16 kHz, then a 1kΩ/10µF high-pass at
+        # ~16 Hz that strips the 6581's DC offset off the mix.
+        class External
+          W0_LOWPASS = (100_000 * SCALE).round
+          W0_HIGHPASS = (100 * SCALE).round
+
+          # The high-pass step is W0_HIGHPASS/2^20 of the gap, so in whole
+          # units it stalls on any gap under ~10k, as reSID's does. Sixteen
+          # fractional bits bring that under one unit.
+          FRACTION = 16
+
+          # Its input arrives with the filter's fractional bits still on.
+          INPUT_SHIFT = FRACTION - Filter::FRACTION
+
+          attr_reader :output
+
+          def initialize
+            @lowpass = 0
+            @highpass = 0
+            @output = 0
+          end
+
+          def save_state(out)
+            out.int(@lowpass).int(@highpass).int(@output)
+          end
+
+          def load_state(input)
+            @lowpass = input.int
+            @highpass = input.int
+            @output = input.int
+          end
+
+          # Takes the input in 1/2^Filter::FRACTION units, and reads the
+          # output out in whole ones. A step of several cycles moves each pole
+          # at most onto its input.
+          def cycle!(input, cycles = 1)
+            w0_lowpass = [(W0_LOWPASS >> 8) * cycles, 1 << 12].min
+            w0_highpass = [W0_HIGHPASS * cycles, 1 << 20].min
+            delta_lowpass = (w0_lowpass * ((input << INPUT_SHIFT) - @lowpass)) >> 12
+            delta_highpass = (w0_highpass * (@lowpass - @highpass)) >> 20
+            @output = (@lowpass - @highpass) >> FRACTION
+            @lowpass += delta_lowpass
+            @highpass += delta_highpass
+            @output
+          end
+        end
+
+        attr_reader :model, :cutoff, :routing, :mode, :volume
+
+        def initialize(model: :mos6581)
+          @model = model
+          @w0_table = W0.fetch(model)
+          @mixer_dc = MIXER_DC.fetch(model)
+          @external = External.new
+          reset
+        end
+
+        # The integrators and the registers carry over; the cutoff maps
+        # through the new model's curve.
+        def model=(model)
+          @model = model
+          @w0_table = W0.fetch(model)
+          @mixer_dc = MIXER_DC.fetch(model)
+          @w0 = @w0_table[@cutoff]
+        end
+
+        def reset
+          @cutoff = 0x000
+          @routing = 0x0
+          @mode = 0x0
+          @volume = 0x0
+          @voice3_off = false
+          @w0 = @w0_table[0]
+          @resonance = RESONANCE[0]
+          @lowpass = @bandpass = @highpass = 0
+          @input = @unfiltered = 0
+        end
+
+        def write(reg, value)
+          case reg
+          when 0x15 then self.cutoff = (@cutoff & 0x7f8) | (value & 0x07)
+          when 0x16 then self.cutoff = (value << 3) | (@cutoff & 0x007)
+          when 0x17 then write_resonance(value)
+          when 0x18 then write_mode_volume(value)
+          end
+        end
+
+        def cutoff=(value)
+          @cutoff = value & 0x7ff
+          @w0 = @w0_table[@cutoff]
+        end
+
+        def voice3_off? = @voice3_off
+
+        def lowpass = @lowpass >> FRACTION
+        def bandpass = @bandpass >> FRACTION
+        def highpass = @highpass >> FRACTION
+
+        # Integrates `cycles` cycles in one step, from the voices' output at
+        # the end of them.
+        def cycle!(voices, cycles = 1)
+          route(voices)
+          w0 = @w0 * cycles
+          w0 = W0_STEP_MAX if w0 > W0_STEP_MAX
+          @bandpass -= (w0 * @highpass) >> 20
+          @lowpass -= (w0 * @bandpass) >> 20
+          @highpass = ((@bandpass * @resonance) >> 10) - @lowpass - (@input << FRACTION)
+          @external.cycle!(fine_mix, cycles)
+        end
+
+        # The SID's own audio pin, before the board's RC network.
+        def mix = fine_mix >> FRACTION
+
+        def output = @external.output
+
+        private
+
+        def write_resonance(value)
+          @routing = value & 0x0f
+          @resonance = RESONANCE[(value >> 4) & 0x0f]
+        end
+
+        def write_mode_volume(value)
+          @volume = value & 0x0f
+          @mode = (value >> 4) & 0x07
+          @voice3_off = value.anybits?(0x80)
+        end
+
+        # Unrolled over the three voices, like SID#clock!. Voice 3 is silenced
+        # by MODE/VOL bit 7 only while it bypasses the filter.
+        def route(voices)
+          voice1, voice2, voice3 = voices
+          @input = 0
+          @unfiltered = 0
+          route_voice(voice1.output >> 7, 0x1)
+          route_voice(voice2.output >> 7, 0x2)
+          if @routing & 0x4 != 0
+            @input += voice3.output >> 7
+          elsif !@voice3_off
+            @unfiltered += voice3.output >> 7
+          end
+        end
+
+        def route_voice(output, bit)
+          if @routing & bit == bit
+            @input += output
+          else
+            @unfiltered += output
+          end
+        end
+
+        # The mix with the integrators' fractional bits kept, so the RC
+        # network isn't fed the filter's output floored to whole units.
+        def fine_mix = (((@unfiltered + @mixer_dc) << FRACTION) + filtered) * @volume
+
+        def filtered
+          value = 0
+          value += @lowpass  if @mode & 0x1 != 0
+          value += @bandpass if @mode & 0x2 != 0
+          value += @highpass if @mode & 0x4 != 0
+          value
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/saved_state.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      # The SID's state for a snapshot.
+      module SavedState
+        # How far the recording has got into the sample it is averaging, for
+        # a host that carries on recording from a saved state: it calls
+        # #record, then #load_recording.
+        def save_recording(out)
+          decimator = @decimator
+          raise ArgumentError, "the SID isn't recording" if decimator.nil?
+
+          out.marker("RECORDING")
+          decimator.save_state(out)
+        end
+
+        def load_recording(input)
+          decimator = @decimator
+          raise ArgumentError, "the SID isn't recording" if decimator.nil?
+
+          input.marker("RECORDING")
+          decimator.load_state(input)
+        end
+
+        # The registers, the data bus, the voices and the filter, and the span
+        # the DSP has yet to catch up on, as it stands: saving leaves the SID
+        # as it was. Whether it synthesizes or records is the host's.
+        def save_state(out)
+          out.marker("SID")
+          @registers.save_state(out)
+          out.int(@bus_value).int(@bus_ttl).int(@pending_cycles).ints(@deferred_writes)
+          @voices.each { |voice| voice.save_state(out) }
+          @filter.save_state(out)
+        end
+
+        def load_state(input)
+          input.marker("SID")
+          @registers.load_state(input)
+          @bus_value = input.int
+          @bus_ttl = input.int
+          @pending_cycles = input.int
+          input.ints_into(@deferred_writes)
+          @voices.each { |voice| voice.load_state(input) }
+          @filter.load_state(input)
+          update_span_rules
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/voice.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      # One of the three voices: a waveform generator amplitude-modulated by
+      # its envelope.
+      #
+      # The 6581 waveform DAC swings around a midpoint well above ground, so
+      # even a silent voice carries a large DC offset into the mixer. The
+      # 8580's is centred and carries none.
+      class Voice
+        WAVE_ZERO = { mos6581: 0x380, mos8580: 0x800 }.freeze
+        DC_OFFSET = { mos6581: 0x800 * 0xff, mos8580: 0 }.freeze
+
+        attr_reader :waveform, :envelope
+
+        # Each voice hard-syncs and ring-modulates against the previous one,
+        # wrapping from the first back round to the last.
+        def self.linked(count, model:)
+          voices = Array.new(count) { new(model:) }
+          waveforms = voices.map(&:waveform)
+          waveforms.each_with_index do |waveform, i|
+            waveform.sync_source = waveforms[i - 1]
+            waveform.sync_dest = waveforms[(i + 1) % count]
+          end
+          voices
+        end
+
+        def initialize(model: :mos6581)
+          @waveform = Waveform.new(model:)
+          @envelope = Envelope.new
+          @wave_zero = WAVE_ZERO.fetch(model)
+          @dc_offset = DC_OFFSET.fetch(model)
+        end
+
+        def model=(model)
+          @waveform.model = model
+          @wave_zero = WAVE_ZERO.fetch(model)
+          @dc_offset = DC_OFFSET.fetch(model)
+        end
+
+        def reset!
+          @waveform.reset!
+          @envelope = Envelope.new
+        end
+
+        def save_state(out)
+          @waveform.save_state(out)
+          @envelope.save_state(out)
+        end
+
+        def load_state(input)
+          @waveform.load_state(input)
+          @envelope.load_state(input)
+        end
+
+        def control=(value)
+          @waveform.control = value
+          @envelope.control = value
+        end
+
+        def cycle!
+          @envelope.cycle!
+          @waveform.cycle!
+        end
+
+        def fast_forward(cycles)
+          @envelope.fast_forward(cycles)
+          @waveform.fast_forward(cycles)
+        end
+
+        def output
+          ((@waveform.output - @wave_zero) * @envelope.output) + @dc_offset
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/waveform/combined.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      class Waveform
+        # The shapes the chip puts out when more than one waveform is selected.
+        #
+        # Selecting several shapers connects their outputs to the same twelve
+        # DAC lines. Each line settles somewhere between the levels the
+        # shapers drive it to, and couples to the lines around it through the
+        # resistances between them, so a bit reads high only when enough of
+        # its own drive and its neighbours' is high. Modelled here as a
+        # threshold on a weighted sum: each selected shaper adds its bit times
+        # its strength, a high pulse adds its strength to every line, and the
+        # neighbours contribute with one weight per distance below and one per
+        # distance above.
+        #
+        # A low pulse grounds every line.
+        #
+        # The parameters come from bin/sidwavefit, fitted against OSC3 dumps of
+        # real chips in SID/resid-test (oscsample0/1-6581/8580wf30/50/60/70).
+        # The tables are built from them once per chip model.
+        module Combined
+          BITS = 12
+
+          # Per chip and selection (triangle $1, sawtooth $2, pulse $4): the
+          # triangle's strength next to a sawtooth (the sawtooth, or a lone
+          # triangle, has strength 1), the pulse's strength, the threshold as
+          # a fraction of the full drive, then the weights of the lines one to
+          # eleven bits below and one to eleven bits above.
+          PARAMETERS = {
+            mos6581: {
+              0x3 => [0.522, 6.4087, 0.9062,
+                      0.5304, 0.278, 0.1473, 0.0773, 0.0, 0.0184, 0.0113, 0.0251, 0.0594, 0.2001, 0.2001,
+                      0.4103, 0.1756, 0.0687, 0.0282, 0.0115, 0.0047, 0.0031, 0.2001, 0.2001, 0.2001, 0.2001],
+              0x5 => [5.871, 0.0, 0.7485,
+                      0.6522, 0.5913, 0.5404, 0.4828, 0.428, 0.361, 0.2955, 0.2453, 0.1558, 0.0501, 0.0016,
+                      0.7106, 0.6667, 0.6426, 0.6376, 0.5761, 0.6639, 0.7193, 0.4728, 0.4306, 0.392, 0.357],
+              0x6 => [3.8329, 4.7751, 0.9565,
+                      0.815, 0.8302, 0.8204, 0.8107, 0.8511, 0.8416, 0.8322, 0.8728, 0.8636, 0.8545, 0.8954,
+                      0.8071, 0.7979, 0.7465, 0.7771, 0.7643, 0.7572, 0.7054, 0.4585, 0.4159, 0.3773, 0.3421],
+              0x7 => [5.5703, 0.2543, 0.9575,
+                      0.7177, 0.515, 0.3696, 0.2653, 0.1904, 0.1367, 0.0606, 0.0953, 0.0506, 0.0363, 0.2261,
+                      0.6347, 0.286, 0.203, 0.0817, 0.0438, 0.1235, 0.2001, 0.2001, 0.2001, 0.2001, 0.2001]
+            },
+            mos8580: {
+              0x3 => [0.2223, 7.7741, 0.8869,
+                      0.4626, 0.2025, 0.0911, 0.041, 0.0185, 0.0, 0.0008, 0.0, 0.0, 0.0127, 0.0063,
+                      0.5633, 0.311, 0.2099, 0.0881, 0.0255, 0.0, 0.0431, 0.2002, 0.2002, 0.2002, 0.2002],
+              0x5 => [3.1022, 1.1282, 0.9157,
+                      0.2731, 0.2748, 0.0031, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
+                      0.6228, 0.7375, 0.6094, 0.6667, 0.4381, 0.4714, 0.3648, 0.2669, 0.2264, 0.2001, 0.2001],
+              0x6 => [0.9477, 0.0012, 0.7837,
+                      0.2565, 0.2289, 0.1095, 0.0805, 0.0282, 0.0281, 0.0, 0.0, 0.0, 0.0, 0.0063,
+                      0.3382, 0.3131, 0.3129, 0.2898, 0.233, 0.1762, 0.2135, 0.2002, 0.2002, 0.2002, 0.2002],
+              0x7 => [1.219, 1.1111, 0.9473,
+                      0.3829, 0.1466, 0.0577, 0.0215, 0.0082, 0.0032, 0.0, 0.0, 0.0, 0.0, 0.0,
+                      0.7273, 0.6845, 0.566, 0.4807, 0.6, 0.1954, 0.4651, 0.2194, 0.2002, 0.2002, 0.2002]
+            }
+          }.freeze
+
+          # A compiled parameter set: the weight matrix, and per line the sum
+          # of its weights and the threshold against the full drive.
+          class Network
+            attr_reader :triangle_strength, :pulse_strength
+
+            def initialize(params)
+              @triangle_strength, @pulse_strength, threshold = params[0, 3]
+              below = [1.0] + params[3, BITS - 1]
+              above = [1.0] + params[3 + BITS - 1, BITS - 1]
+              @weights = Array.new(BITS) do |i|
+                Array.new(BITS) { |j| j <= i ? below[i - j] : above[j - i] }.freeze
+              end.freeze
+              @norms = @weights.map(&:sum).freeze
+              @threshold = threshold
+            end
+
+            # `drives` holds [bits, strength] for each selected shaper; a high
+            # pulse is passed separately, as it drives every line alike.
+            def shape(drives, pulse)
+              total = drives.sum { |_, strength| strength }
+              total += @pulse_strength if pulse
+              out = 0
+              BITS.times do |i|
+                level = pulse ? @pulse_strength * @norms[i] : 0.0
+                weights = @weights[i]
+                drives.each do |bits, strength|
+                  BITS.times { |j| level += weights[j] * strength if bits[j] == 1 }
+                end
+                out |= 1 << i if level >= @threshold * @norms[i] * total
+              end
+              out
+            end
+          end
+
+          module_function
+
+          # The pulse-high shapes of the four combinations without noise.
+          def tables(model)
+            @tables ||= {}
+            @tables[model] ||= PARAMETERS.fetch(model).to_h do |selected, params|
+              [selected, table(selected, params)]
+            end.freeze
+          end
+
+          # One combination's shapes, indexed by the phase (the sawtooth), or
+          # for triangle and pulse by the triangle. A triangle combined with a
+          # sawtooth is never folded, so it is the phase shifted left one bit.
+          def table(selected, params)
+            network = Network.new(params)
+            Array.new(1 << BITS) do |index|
+              triangle = selected == 0x5 ? index : (index << 1) & 0xfff
+              network.shape(drives(selected, network, index, triangle), selected.anybits?(0x4))
+            end.freeze
+          end
+
+          def drives(selected, network, saw, triangle)
+            drives = []
+            drives << [saw, 1.0] if selected.anybits?(0x2)
+            drives << [triangle, selected.anybits?(0x2) ? network.triangle_strength : 1.0] if selected.anybits?(0x1)
+            drives
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/waveform/fast_forward.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      class Waveform
+        # Running an oscillator many cycles in one step, for the catch-ups that
+        # fast-forward the voices between whole cycles.
+        module FastForward
+          # Runs `cycles` cycles as #cycle! would, for an oscillator that is not
+          # feeding back. What those cycles latch onto the output is left to the
+          # whole cycle that follows, which latches over it.
+          def fast_forward(cycles)
+            drain_floating(cycles) if @selected.zero?
+            if @test
+              bleed_shift_register(cycles)
+            else
+              while @shift_pipeline != 0 && cycles != 0
+                advance
+                cycles -= 1
+              end
+              skip_ahead(cycles) if cycles != 0 && @frequency != 0
+              compare_pulse(((@accumulator - @frequency) & 0xffffff) >> 12)
+            end
+            @stale = true
+          end
+
+          # The cycle on which the accumulator MSB next rises, counting the next
+          # one as 1, or nil if it never will. The test bit leaves the last
+          # rise standing for as long as it is held.
+          def cycles_to_msb_rise
+            return (@msb_rising ? 1 : nil) if @test
+            return if @frequency.zero?
+
+            distance = (MSB - @accumulator) & 0xffffff
+            distance = 0x1000000 if distance.zero?
+            (distance + @frequency - 1) / @frequency
+          end
+
+          # A combined waveform with sawtooth (on the 6581) or noise in the mix
+          # writes back into the oscillator every cycle, so it cannot be
+          # fast-forwarded. Triangle and pulse alone write nothing back.
+          def feedback?
+            combined_waveform? && (@selected.anybits?(0x8) || (@topbit_feedback && @selected.anybits?(0x2)))
+          end
+
+          # Whether a catch-up has to run this oscillator a cycle at a time.
+          # While synthesizing, every combined waveform does, so the filter
+          # integrates it a cycle at a time.
+          def stepped?(synthesizing) = synthesizing ? combined_waveform? : feedback?
+
+          private
+
+          def combined_waveform? = !@test && combined?(@selected)
+
+          # Advances an accumulator with no shift in flight. Each rise of bit 19
+          # shifts the LFSR two cycles on, so a rise in the last two cycles
+          # leaves its shift pending for the cycles after.
+          def skip_ahead(cycles)
+            previous = @accumulator
+            @accumulator += @frequency * cycles
+            rises = bit19_rises(previous, @accumulator)
+            if rises != 0
+              @shift_pipeline = pipeline_after(cycles)
+              rises -= 1 if @shift_pipeline != 0
+              rises.times { shift_noise }
+            end
+            @accumulator &= 0xffffff
+          end
+
+          # Bit 19 rises at most once a cycle, on each odd multiple of 2^19,
+          # and at most once in any eight.
+          def bit19_rises(from, to) = ((to + 0x80000) >> 20) - ((from + 0x80000) >> 20)
+
+          # How far a rise on one of the last two cycles has come.
+          def pipeline_after(cycles)
+            last = @accumulator - @frequency
+            return 2 if bit19_rises(last, @accumulator) != 0
+            return 1 if cycles > 1 && bit19_rises(last - @frequency, last) != 0
+
+            0
+          end
+
+          def drain_floating(cycles)
+            return if @floating_ttl.zero?
+
+            @floating_ttl -= cycles
+            return unless @floating_ttl <= 0
+
+            @floating_ttl = 0
+            @floating = 0x000
+          end
+
+          def bleed_shift_register(cycles = 1)
+            return if @shift_register_reset.zero?
+
+            @shift_register_reset -= cycles
+            return unless @shift_register_reset <= 0
+
+            @shift_register_reset = 0
+            @shift_register = SHIFT_REGISTER_RESET
+          end
+        end
+      end
+    end
+  end
+end