badline 0.12.1 → 0.14.0

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

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      # ADSR envelope generator.
+      #
+      # A 15-bit rate counter divides the 1 MHz clock down to one envelope step
+      # per period. Attack steps linearly; decay and release run through a
+      # second, level-dependent divider that approximates an exponential
+      # curve.
+      #
+      # Each stage runs a cycle or more behind the one feeding it, after
+      # reSID 1.0's single-cycle pipeline: the rate counter resets the cycle
+      # after it matches, the envelope counter steps two cycles after that,
+      # and a gate edge only switches the rate over on its second cycle.
+      class Envelope
+        # Rate counter comparison values for each ADSR nibble. The counter
+        # takes a cycle to reset, so the period is one cycle longer (2ms to
+        # 8s over the attack range).
+        PERIODS = [8, 31, 62, 94, 148, 219, 266, 312,
+                   391, 976, 1953, 3125, 3906, 11_719, 19_531, 31_250].freeze
+
+        # Envelope levels where the exponential divider changes, and the
+        # divider it changes to.
+        EXPONENTIAL_PERIODS = { 0xff => 1, 0x5d => 2, 0x36 => 4, 0x1a => 8,
+                                0x0e => 16, 0x06 => 30, 0x00 => 1 }.freeze
+
+        # The states, which VICE's SIDEXTENDED numbers by index.
+        STATES = %i[attack decay_sustain release].freeze
+        attr_reader :state, :counter, :env3
+
+        def initialize
+          @attack = @decay = @sustain = @release = 0x0
+          @gate = false
+          @state = @next_state = :release
+          @counter = @env3 = 0x00
+          @rate_counter = 0
+          @rate_period = PERIODS[0]
+          @reset_rate_counter = false
+          @exponential_counter = 0
+          @exponential_period = 1
+          @state_pipeline = @envelope_pipeline = @exponential_pipeline = 0
+          @hold_zero = true
+        end
+
+        def output = @counter
+
+        # The gate edge switches the state over two cycles. Rising, it runs
+        # the decay rate for the first of them. The rate counter is left
+        # running, so the first step lands somewhere inside the current
+        # period.
+        def control=(value)
+          gate = value.anybits?(0x01)
+          return if gate == @gate
+
+          @gate = gate
+          gate ? gate_on : gate_off
+        end
+
+        def attack_decay=(value)
+          @attack = (value >> 4) & 0x0f
+          @decay = value & 0x0f
+          @rate_period = PERIODS[@attack] if @state == :attack
+          @rate_period = PERIODS[@decay] if @state == :decay_sustain
+        end
+
+        def sustain_release=(value)
+          @sustain = (value >> 4) & 0x0f
+          @release = value & 0x0f
+          @rate_period = PERIODS[@release] if @state == :release
+        end
+
+        # ENV3 reads the counter as it stood at the start of the cycle.
+        #
+        # Lowering the rate period below the current counter sends it the long
+        # way round through 2^15 before the envelope can step, the ADSR delay
+        # bug that hard restarts rely on. Counting from 0x7fff wraps to 1.
+        def cycle!
+          @env3 = @counter
+          run_pipeline if pipelined?
+          return @reset_rate_counter = true if @rate_counter == @rate_period
+
+          @rate_counter += 1
+          @rate_counter = 1 if @rate_counter == 0x8000
+        end
+
+        # Runs `cycles` cycles as #cycle! would. Between steps only the rate
+        # counter moves, so it jumps from one match to the next and the cycles
+        # around each step run whole. Frozen at zero, a period changes
+        # nothing, so whole periods are counted off at once.
+        def fast_forward(cycles)
+          while cycles.positive?
+            if pipelined?
+              cycle!
+              cycles -= 1
+              next
+            end
+
+            @env3 = @counter
+            idle = cycles_to_match
+            return advance_rate_counter(cycles) if cycles < idle
+
+            advance_rate_counter(idle)
+            cycles = skip_frozen_periods(cycles - idle)
+          end
+        end
+
+        private
+
+        def land_step
+          @envelope_pipeline -= 1
+          step if @envelope_pipeline.zero? && !@hold_zero
+        end
+
+        def gate_on
+          @next_state = :attack
+          @state = :decay_sustain
+          @rate_period = PERIODS[@decay]
+          @state_pipeline = 2
+          if @reset_rate_counter || @exponential_pipeline == 2
+            @envelope_pipeline = @exponential_period == 1 || @exponential_pipeline == 2 ? 2 : 4
+          elsif @exponential_pipeline == 1
+            @state_pipeline = 3
+          end
+        end
+
+        def gate_off
+          @next_state = :release
+          @state_pipeline = @envelope_pipeline.positive? ? 3 : 2
+        end
+
+        def state_change
+          @state_pipeline -= 1
+          if @next_state == :attack
+            enter_attack if @state_pipeline.zero?
+          elsif (@state == :attack && @state_pipeline.zero?) ||
+                (@state == :decay_sustain && @state_pipeline == 1)
+            @state = :release
+            @rate_period = PERIODS[@release]
+          end
+        end
+
+        def enter_attack
+          @state = :attack
+          @rate_period = PERIODS[@attack]
+          @hold_zero = false
+        end
+
+        # The first attack step also resets the exponential divider.
+        def reset_rate_counter
+          @rate_counter = 0
+          @reset_rate_counter = false
+          if @state == :attack
+            @exponential_counter = 0
+            @envelope_pipeline = 2
+          elsif !@hold_zero && (@exponential_counter += 1) == @exponential_period
+            @exponential_pipeline = @exponential_period == 1 ? 1 : 2
+          end
+        end
+
+        def exponential_step
+          @exponential_counter = 0
+          return unless @state == :release || (@state == :decay_sustain && @counter != sustain_level)
+
+          @envelope_pipeline = 1
+        end
+
+        def pipelined?
+          @reset_rate_counter || (@state_pipeline | @envelope_pipeline | @exponential_pipeline) != 0
+        end
+
+        def run_pipeline
+          state_change if @state_pipeline.positive?
+          land_step if @envelope_pipeline.positive?
+          if @exponential_pipeline.positive? && (@exponential_pipeline -= 1).zero?
+            exponential_step
+          elsif @reset_rate_counter
+            reset_rate_counter
+          end
+        end
+
+        # Cycles that only count before the rate counter matches its period.
+        def cycles_to_match
+          return @rate_period - @rate_counter if @rate_counter <= @rate_period
+
+          0x7fff - @rate_counter + @rate_period
+        end
+
+        def advance_rate_counter(cycles)
+          @rate_counter += cycles
+          @rate_counter -= 0x7fff if @rate_counter > 0x7fff
+        end
+
+        # With the counter on its period, a frozen envelope comes back to the
+        # same state every period plus one cycles. Otherwise the next cycle
+        # starts a step.
+        def skip_frozen_periods(cycles)
+          cycles %= @rate_period + 1 if @hold_zero && @state != :attack
+          return cycles unless cycles.positive?
+
+          cycle!
+          cycles - 1
+        end
+
+        def step
+          if @state == :attack
+            attack_step
+          else
+            @counter = (@counter - 1) & 0xff
+          end
+          set_exponential_period
+        end
+
+        def attack_step
+          @counter = (@counter + 1) & 0xff
+          return unless @counter == 0xff
+
+          @state = :decay_sustain
+          @rate_period = PERIODS[@decay]
+        end
+
+        def sustain_level = (@sustain << 4) | @sustain
+
+        # Reaching zero freezes the envelope until the gate is raised again.
+        def set_exponential_period
+          period = EXPONENTIAL_PERIODS[@counter]
+          return unless period
+
+          @exponential_period = period
+          @hold_zero = true if @counter.zero?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+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
+        # 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
+
+          # 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