badline 0.12.0 → 0.13.0

data/lib/badline/chips/vic/sprite.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "badline/chips/vic/sprite/internal_bus"
+require "badline/chips/vic/sprite/shifter"
+require "badline/chips/vic/sprite/saved_state"
+require "badline/chips/vic/sprite/timing"
+
+module Badline
+  module Chips
+    class VIC
+      # = Sprite
+      #
+      # The DMA/display state machine and the pixel sequencer for one sprite.
+      # The sequencer is a 24-bit shift register clocked once per pixel: the X
+      # comparator starts it, the expansion flip-flop gates the shift, and the
+      # multicolor flip-flop gates a two-bit output latch that feeds the color
+      # mux. Registers written mid-sprite therefore take hold from the pixel
+      # they reach, rather than re-decoding the row.
+      class Sprite
+        X_OFFSET = 104
+
+        # MCBASE and MC are six-bit byte counters into the sprite's 64-byte
+        # block. A sprite ends when MCBASE reaches exactly 63, which is why a
+        # mid-line $d017 write that steps it past 63 keeps it running.
+        LAST_MCBASE = 63
+        MC_MASK = 0x3f
+
+        # 24 bits at two pixels each, plus slack for a mid-sprite expansion
+        # change stretching the tail.
+        MAX_SPAN = 64
+
+        # Latch codes are the multicolor bit pairs: 0 is transparent, 1 and 3
+        # are the shared colors, 2 the sprite's own.
+        SHARED0 = 1
+        OWN_COLOR = 2
+        SHARED1 = 3
+
+        # The s-accesses reload the shift register partway through the line,
+        # at raster pixel 459 for sprite 0 and 16 later for each sprite after
+        # it. A sprite still shifting there loses the rest of its row, and the
+        # comparator is ignored for the twelve pixels from it, running on into
+        # the next line from a reload near the end of this one (the spritescan
+        # dumps). Its output holds the last pixel for seven, through K+6
+        # (spritefetchbug).
+        RELOAD_X = 459
+        RELOAD_STEP = 16
+        RELOAD_DEAD = 12
+        RELOAD_HOLD = 7
+
+        # On the line of its last row, a sprite whose DMA ended at cycle 16
+        # loses its display at cycle 58, so no hit from this pixel on starts
+        # it (spritegap3). One already shifting runs on. A region whose
+        # display compare falls later moves it with the compare.
+        DISPLAY_OFF_X = 460
+
+        include Shifter
+        include SavedState
+
+        attr_reader :index, :leftmost, :span, :codes,
+                    :reload_leftmost, :reload_span, :reload_codes
+
+        def initialize(index, registers, bank, bus, model: :mos6569)
+          @index = index
+          @new_chip = model == :mos8565
+          @registers = registers
+          @bank = bank
+          @bus = bus
+          @width = bus.columns * 8
+          @timing = bus.timing
+          @bit = 1 << index
+          @dma = false
+          @display_on = false
+          @mcbase = 0
+          @mc = 0
+          @exp_ff = true
+          @crunched_mc = nil
+          @bits = 0
+          @row_ready = false
+          @codes = Array.new(MAX_SPAN + RELOAD_HOLD, 0)
+          @leftmost = 0
+          @span = 0
+          @reload_codes = Array.new(MAX_SPAN + RELOAD_HOLD, 0)
+          @reload_leftmost = 0
+          @reload_span = 0
+          reload = @timing.reload_x(index)
+          @reload_x = reload % @width
+          @reload_next_line = reload < @width
+          @sr = 0
+          @latch = 0
+          @mc_flop = false
+          @xe_flop = false
+          @first_byte_lost = false
+          @blind = false
+          @show_from = 0
+        end
+
+        def displaying? = @dma
+
+        # True when this line has a row for the sequencer: its own, the next
+        # one for a sprite that reloads late in the line, or the last one for
+        # a sprite that reloads at its start.
+        def rendering?
+          return true if @row_ready
+
+          @reload_next_line ? @dma && @display_on : !@prev_bits.nil?
+        end
+
+        def enabled? = @registers[0x15].anybits?(@bit)
+        def multicolor? = @registers[0x1c].anybits?(@bit)
+        def x_expanded? = @registers[0x1d].anybits?(@bit)
+        def y_expanded? = @registers[0x17].anybits?(@bit)
+        def priority? = @registers[0x1b].anybits?(@bit)
+
+        def x
+          msb = @registers[0x10].anybits?(@bit) ? 0x100 : 0
+          msb | @registers[index * 2]
+        end
+
+        # The Y comparator is eight bits wide, so the PAL lines above 255
+        # match the coordinates 0-55 a second time (spritey).
+        def y_match?(line) = (line & 0xff) == @registers[(index * 2) + 1]
+
+        def color = @registers[0x27 + index] & 0x0f
+
+        # Cycle 16: MCBASE takes MC, which the three s-accesses stepped past
+        # the row, but only while the expansion flip-flop is set.
+        def advance_mcbase
+          mc = @crunched_mc || ((@mc + 3) & MC_MASK)
+          @crunched_mc = nil
+          @mcbase = mc if @exp_ff && @dma
+        end
+
+        # The end-of-sprite compare, a column after MCBASE moves. MCBASE has
+        # to land on 63 exactly, so a crunched sprite steps over it and runs
+        # on through the rest of its block. Only the DMA stops here; the
+        # display waits for cycle 58.
+        def finish_mcbase
+          @dma = false if @mcbase == LAST_MCBASE
+        end
+
+        # Clearing MxYE sets the expansion flip-flop at once. Cleared in
+        # cycle 15, while the flip-flop is still reset, it also crunches MC:
+        # the bits step to a mix of MC and MCBASE (Bauer §3.8, VICE
+        # `d017_store`) that cycle 16 then hands to MCBASE.
+        def clear_y_expansion(crunch)
+          return if @exp_ff
+
+          @exp_ff = true
+          return unless crunch && @dma
+
+          mc = (@mc + 3) & MC_MASK
+          @crunched_mc = (0x2a & @mcbase & mc) | (0x15 & (@mcbase | mc))
+        end
+
+        # Cycle 56, after the second Y compare: MxYE inverts the expansion
+        # flip-flop of a sprite with DMA running.
+        def toggle_expansion
+          @exp_ff = !@exp_ff if @dma && y_expanded?
+        end
+
+        # Cycles 55 and 56: a Y/enable match starts the DMA and rewinds
+        # MCBASE, and returns true. Display is enabled separately in cycle 58,
+        # so the rows render from the following line on.
+        #
+        # On the VIC's side, BA falls at the sprite's own column
+        # (Timing#ba_column) — 55 for sprite 0 on the 6569, two later for each
+        # sprite after it, a column behind the window the CPU sees
+        # (VIC#layout_columns) — or two columns after
+        # this compare, whichever is later. AEC follows three columns on, and
+        # the first of the three s-accesses runs in the column it arrives in:
+        # a DMA starting on the second compare therefore loses that access for
+        # sprite 0, alone among the eight in following the compares
+        # immediately (spriteenable2).
+        def check_dma(line, column)
+          return false if @dma || !enabled? || !y_match?(line)
+
+          @first_byte_lost = column + 2 > @timing.ba_column(index)
+          @dma = true
+          @mcbase = 0
+          @exp_ff = true
+        end
+
+        # Cycle 58: MC is reloaded from MCBASE for the coming row, and a
+        # sprite with DMA running starts displaying only while MxE and Y still
+        # match — a write to either between the compares and here keeps the
+        # data fetch running invisibly. The display goes off only here, and
+        # only once the DMA has, so a DMA restarted on the line of its last
+        # row keeps a display that was already on (spriterestart).
+        def check_display(line)
+          @mc = @mcbase
+          if @dma
+            @display_on = true if enabled? && y_match?(line)
+          else
+            @display_on = false
+          end
+          blind_fetch if @blind && @display_on
+        end
+
+        # The address of the s-access that falls in phi1, the middle of the
+        # three, or nil when the sprite's DMA is off and the VIC idles there.
+        def phi1_address
+          (pointer * 64) + ((@mc + 1) & MC_MASK) if @dma
+        end
+
+        # The row fetched at the end of the previous line renders on this one.
+        # A lost first s-access reads back the $ff the CPU is still driving.
+        def start_line
+          @span = 0
+          @reload_span = 0
+          @prev_bits = (@bits if @row_ready && @dma)
+          @row_ready = false
+          @blind = !@dma && !@reload_next_line
+          @show_from = 0
+          lost = @first_byte_lost
+          @first_byte_lost = false
+          return unless @dma && @display_on
+
+          @bits = row_bits(@mc)
+          @bits |= 0xff << 16 if lost
+          @row_ready = true
+        end
+
+        # Replay the line through the pixel sequencer, filling the code buffer
+        # from the X match on. A log of mid-line register writes makes the
+        # comparator and the shift register see the values each pixel was
+        # drawn with.
+        #
+        # The row can be shown once before the reload and once after it, so a
+        # sprite moved past the beam can fire a second time on the same line
+        # (spritex). A match inside the dead pixels shows nothing.
+        def sequence(log = nil)
+          @span = 0
+          @reload_span = 0
+          reload_bits = reload_row
+          return unless @row_ready || @prev_bits || reload_bits
+
+          log = nil if log.nil? || log.empty?
+          @stop_x = @dma ? nil : @timing.display_off_x
+          comparator_hits(log).each { |start| sequence_hit(log, start, reload_bits) }
+        end
+
+        # The color at a raster position, for a sprite sequenced with the
+        # registers as they stand.
+        def pixel(raster_x)
+          code = code_at(raster_x, @leftmost, @span, @codes) ||
+                 code_at(raster_x, @reload_leftmost, @reload_span, @reload_codes)
+          return nil if code.nil? || code.zero?
+
+          palette(@registers, Array.new(4, 0))[code]
+        end
+
+        # Fill a four-entry lookup from latch code to color, against a view of
+        # the color registers.
+        def palette(view, into)
+          into[SHARED0] = view[0x25] & 0x0f
+          into[OWN_COLOR] = view[0x27 + index] & 0x0f
+          into[SHARED1] = view[0x26] & 0x0f
+          into
+        end
+
+        private
+
+        # On the line whose compare started the DMA, sprites 3-7 ran their
+        # s-accesses before it was on, so the shift register holds what the
+        # VIC saw on its bus instead of a row, and a hit from the display
+        # turning on shows it (sbsprf24).
+        def blind_fetch
+          @bits = @bus.row(index)
+          @row_ready = true
+          @show_from = @timing.display_off_x
+        end
+
+        def code_at(raster_x, leftmost, span, codes)
+          dist = raster_x - leftmost
+          dist += @width if dist.negative?
+          codes[dist] if dist < span
+        end
+
+        def sequence_hit(log, start, reload_bits)
+          return if (@stop_x && start >= @stop_x) || start < @show_from || start < @reload_x + RELOAD_DEAD - @width
+
+          if start < @reload_x
+            sequence_early(log, start)
+          elsif start >= @reload_x + RELOAD_DEAD
+            sequence_reloaded(log, start, reload_bits)
+          end
+        end
+
+        def sequence_early(log, start)
+          bits = early_row
+          return unless bits && @span.zero?
+
+          @leftmost = start
+          cut = reload_cut(start)
+          @span = cut_at_reload(cut, run(log, start, @codes, bits, cut), @codes)
+        end
+
+        def sequence_reloaded(log, start, bits)
+          return unless bits && @reload_span.zero?
+
+          @reload_leftmost = start
+          cut = reload_cut(start)
+          @reload_span = cut_at_reload(cut, run(log, start, @reload_codes, bits, cut), @reload_codes)
+        end
+
+        # The row in the shift register ahead of the reload: this line's for
+        # sprites 0-2, and for the others the one their reload at the start of
+        # the last line brought in.
+        def early_row = @reload_next_line ? current_row : @prev_bits
+
+        def current_row = (@bits if @row_ready)
+
+        # The row the reload brings in. Sprites 0-2 reload late in the line
+        # with the next line's row, so one that fires after it shows that row
+        # a line early (spritegap); the others reload at the start of the line
+        # with the row it already has.
+        def reload_row
+          return current_row unless @reload_next_line
+          return unless @dma && @display_on
+
+          bits = row_bits(@mc)
+          bits |= 0xff << 16 if @first_byte_lost
+          bits
+        end
+
+        # The three s-accesses step MC through the sprite's block, wrapping
+        # within it.
+        def row_bits(counter)
+          base = pointer * 64
+          (@bank.peek(base + counter) << 16) |
+            (@bank.peek(base + ((counter + 1) & MC_MASK)) << 8) |
+            @bank.peek(base + ((counter + 2) & MC_MASK))
+        end
+
+        def pointer = @bank.peek(@registers.screen_base + 0x3f8 + index)
+      end
+    end
+  end
+end

data/lib/badline/chips/vic/sprites/saved_state.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIC
+      class Sprites
+        # The sprites' save_state and load_state.
+        module SavedState
+          # Whether any sprite's DMA runs, set after Sprite#restore_counters.
+          def update_any_dma
+            @any_dma = @sprites.any?(&:displaying?)
+          end
+
+          # The sprites, their shared bus, the collisions and the register log,
+          # then the line's coverage and the pixels carried into the next line,
+          # each as x, colour and priority.
+          def save_state(out)
+            out.boolean(@any_dma).boolean(@stopped_dma).boolean(@carried).int(@lo).int(@hi).int(@sequenced)
+            out.blob(@win_color).booleans(@win_priority).ints(@palette)
+            [@carry, @carry_next].each { |carry| carry.each { |pixels| save_carry(pixels, out) } }
+            @sprites.each { |sprite| sprite.save_state(out) }
+            @bus.save_state(out)
+            @collisions.save_state(out)
+            @log.save_state(out)
+          end
+
+          def load_state(input)
+            @any_dma = input.boolean?
+            @stopped_dma = input.boolean?
+            @carried = input.boolean?
+            @lo = input.int
+            @hi = input.int
+            @sequenced = input.int
+            input.blob_into(@win_color)
+            input.booleans_into(@win_priority)
+            input.ints_into(@palette)
+            [@carry, @carry_next].each { |carry| carry.each { |pixels| load_carry(pixels, input) } }
+            @sprites.each { |sprite| sprite.load_state(input) }
+            @bus.load_state(input)
+            @collisions.load_state(input)
+            @log.load_state(input)
+          end
+
+          private
+
+          def save_carry(pixels, out)
+            out.int(pixels.length / 3)
+            pixels.each_slice(3) { |x, color, priority| out.int(x).int(color).boolean(priority) }
+          end
+
+          def load_carry(pixels, input)
+            pixels.clear
+            input.int.times { pixels.push(input.int, input.int, input.boolean?) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/vic/sprites.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "badline/chips/vic/collisions"
+require "badline/chips/vic/register_log"
+require "badline/chips/vic/sprite"
+require "badline/chips/vic/sprites/saved_state"
+
+module Badline
+  module Chips
+    class VIC
+      class Sprites
+        include SavedState
+
+        # Pixels between the start of the cycle following a write and the
+        # point the new value shows. Each signal reaches the output on its own
+        # path: the colors feed the final mux, the sequencer inputs — X
+        # position, multicolor and expansion — sit furthest upstream, and the
+        # priority mux lands one pixel ahead of them.
+        COLOR_DELAY = 1
+        PRIORITY_DELAY = 6
+        SEQUENCER_DELAY = 7
+
+        # The beam position a CPU write in Bauer cycle 15 sees: the VIC has
+        # run column 13 and runs column 14, where MCBASE moves, next.
+        CRUNCH_X = 14 * 8
+
+        WRITE_DELAY = Array.new(2**6).tap do |delays|
+          (0x00..0x0e).step(2) { |reg| delays[reg] = SEQUENCER_DELAY }
+          [0x10, 0x1c, 0x1d].each { |reg| delays[reg] = SEQUENCER_DELAY }
+          delays[0x1b] = PRIORITY_DELAY
+          [0x25, 0x26, *0x27..0x2e].each { |reg| delays[reg] = COLOR_DELAY }
+        end.freeze
+
+        # The 8565's sprite sequencers take a multicolor change a pixel
+        # sooner than the 6569's.
+        WRITE_DELAY_8565 = WRITE_DELAY.dup.tap { |delays| delays[0x1c] = SEQUENCER_DELAY - 1 }.freeze
+
+        def initialize(registers, bank, width, model: :mos6569, region: Region::PAL)
+          @registers = registers
+          @write_delay = model == :mos8565 ? WRITE_DELAY_8565 : WRITE_DELAY
+          @bank = bank
+          @width = width
+          @bus = Sprite::InternalBus.new(bank, Sprite::Timing.new(region))
+          @sprites = Array.new(8) { |i| Sprite.new(i, registers, bank, @bus, model:) }
+          @collisions = Collisions.new(registers, width)
+          @hits = @collisions.hits
+          @win_color = Array.new(width, 0)
+          @win_priority = Array.new(width, false)
+          @palette = Array.new(4, 0)
+          @log = RegisterLog.new(registers)
+          @any_dma = false
+          @stopped_dma = false
+          @carry = Array.new(8) { [] }
+          @carry_next = Array.new(8) { [] }
+          @carried = false
+          @lo = width
+          @hi = 0
+          @sequenced = -1
+        end
+
+        def [](index) = @sprites[index]
+
+        # Pixels a sprite drew past the end of the last line land at the start
+        # of this one, which is when the beam reaches them.
+        def start_line
+          @bus.start_line(@registers[0x15].nonzero?)
+          @log.clear
+          @sprites.each(&:start_line)
+          @collisions.start_line
+          @sequenced = -1
+          @carry, @carry_next = @carry_next, @carry
+          @carry_next.each(&:clear)
+          @carried = @carry.any?(&:any?)
+        end
+
+        # Bauer cycle 16, two columns ahead like the compares: MCBASE takes
+        # MC for every sprite whose expansion flip-flop is set.
+        def advance_mcbase
+          @sprites.each(&:advance_mcbase) if @any_dma
+        end
+
+        # The end-of-sprite compare, a column after MCBASE moves. It is the
+        # only point a sprite's DMA stops, so the cached flag is settled here
+        # and set again by the compare that starts one.
+        def finish_mcbase
+          @stopped_dma = false
+          return unless @any_dma
+
+          running = @sprites.count(&:displaying?)
+          @sprites.each(&:finish_mcbase)
+          still = @sprites.count(&:displaying?)
+          @any_dma = still.positive?
+          @stopped_dma = still < running
+        end
+
+        # True when the last #finish_mcbase ended a DMA, so the BA columns
+        # have to be rebuilt without it.
+        def stopped_dma? = @stopped_dma
+
+        # Bauer cycle 56, after the second Y compare.
+        def toggle_expansion
+          @sprites.each(&:toggle_expansion) if @any_dma
+        end
+
+        # Run the Y/enable compare (Bauer cycles 55/56) for every sprite;
+        # returns true when any sprite turned its DMA on, so the BA columns
+        # can be rebuilt mid-line.
+        def check_dma(line, column)
+          return false if @registers[0x15].zero?
+
+          hit = @sprites.map { |sprite| sprite.check_dma(line, column) }.any?
+          @any_dma ||= hit
+          hit
+        end
+
+        # Not gated on the DMA flag, since this is where a display outlives its
+        # DMA. MC now points at the next row, which a sprite firing after its
+        # reload shows, so a line sequenced before this has to be redone.
+        def check_display(line)
+          @sprites.each { |sprite| sprite.check_display(line) }
+          @sequenced = -1
+        end
+
+        # A CPU access to a VIC register, in the cycle after the VIC's
+        # `column`.
+        def bus_data(column, value) = @bus.access(column, value)
+
+        # Not gated on the DMA flag: a row fetched at the start of the line
+        # still renders when cycle 16 ends the sprite.
+        def active? = @carried || @sprites.any?(&:rendering?)
+
+        # Record a mid-line write at the pixel where it becomes visible.
+        def log_change(reg, old, value, beam_x)
+          clear_y_expansion(old & ~value, beam_x) if reg == 0x17
+          delay = @write_delay[reg]
+          return unless delay && active?
+
+          @log.log(beam_x + delay, reg, old, value)
+        end
+
+        # Latch the collisions for every sprite pixel the beam has passed
+        # since the last fold.
+        def collide_upto(beam_x, mask)
+          upto = [beam_x, @width].min
+          return if upto <= @collisions.folded
+
+          sequence_line if active?
+          @collisions.fold(mask, upto, @lo, @hi)
+        end
+
+        def clear_collision(reg, beam_x) = @collisions.clear(reg, beam_x)
+
+        # End of line: fold in the pixels the beam reached since the last
+        # read, then paint the winners over the background. A line with no
+        # background to paint over — one in the vertical blank — still
+        # collides, so `colors` is nil there rather than absent.
+        def finish_line(colors, mask)
+          collide_upto(@width, mask)
+          colors ? apply(colors, mask) : clear_coverage
+        end
+
+        private
+
+        # A $d017 write that clears MxYE acts on the flip-flop at once, rather
+        # than from a column hook, and crunches in Bauer cycle 15.
+        def clear_y_expansion(cleared, beam_x)
+          crunch = beam_x == CRUNCH_X
+          @sprites.each do |sprite|
+            sprite.clear_y_expansion(crunch) if cleared.anybits?(1 << sprite.index)
+          end
+        end
+
+        # Replay the line for every sprite, filling the per-pixel coverage
+        # that both the fold and the composite read. A write logged later in
+        # the line can only move pixels past it, so re-running after the log
+        # grows leaves everything already folded where it was.
+        def sequence_line
+          return if @sequenced == @log.length
+
+          clear_coverage
+          @log.prepare
+          @sprites.each do |sprite|
+            sprite.sequence(@log)
+            merge(sprite)
+          end
+          @sequenced = @log.length
+        end
+
+        # Write one sprite's pixels into the coverage, picking up the color and
+        # priority registers as they stood at each pixel. The first sprite to
+        # claim a pixel wins (lowest index has priority); later ones only add
+        # their bit to it.
+        def merge(sprite)
+          bit = 1 << sprite.index
+          @carry_next[sprite.index].clear
+          @carry[sprite.index].each_slice(3) do |x, color, priority|
+            track(x, 1)
+            merge_pixel(x, color, bit, priority)
+          end
+          merge_run(sprite, sprite.leftmost, sprite.span, sprite.codes)
+          merge_run(sprite, sprite.reload_leftmost, sprite.reload_span, sprite.reload_codes)
+        end
+
+        def merge_run(sprite, leftmost, span, codes)
+          return if span.zero?
+
+          track(leftmost, span)
+          log = @log.empty? ? nil : @log
+          log&.rewind
+          merge_span(sprite, log, leftmost, span, codes)
+        end
+
+        def merge_span(sprite, log, leftmost, span, codes)
+          bit = 1 << sprite.index
+          palette = sprite.palette(log || @registers, @palette)
+          priority = (log || @registers)[0x1b].anybits?(bit)
+          pos = leftmost
+          boundary = log ? 0 : Float::INFINITY
+          index = 0
+          while index < span
+            if pos >= boundary
+              log.advance(pos)
+              sprite.palette(log, palette)
+              priority = log[0x1b].anybits?(bit)
+              boundary = log.next_x
+            end
+            code = codes[index]
+            place(pos, palette[code], bit, priority) unless code.zero?
+            index += 1
+            pos += 1
+          end
+        end
+
+        # A pixel past the end of the line belongs to the start of the next.
+        def place(pos, color, bit, priority)
+          if pos < @width
+            merge_pixel(pos, color, bit, priority)
+          else
+            @carry_next[bit.bit_length - 1].push(pos - @width, color, priority)
+          end
+        end
+
+        def track(left, span)
+          right = left + span
+          if right > @width
+            @lo = 0
+            @hi = @width
+          else
+            @lo = left if left < @lo
+            @hi = right if right > @hi
+          end
+        end
+
+        def merge_pixel(pos, color, bit, priority)
+          bits = @hits[pos]
+          if bits.zero?
+            @win_color[pos] = color
+            @win_priority[pos] = priority
+          end
+          @hits[pos] = bits | bit
+        end
+
+        def apply(colors, mask)
+          pos = @lo
+          while pos < @hi
+            unless @hits[pos].zero?
+              colors[pos] = @win_color[pos] unless @win_priority[pos] && mask[pos]
+              @hits[pos] = 0
+            end
+            pos += 1
+          end
+          @lo = @width
+          @hi = 0
+        end
+
+        def clear_coverage
+          @hits.fill(0, @lo, @hi - @lo) if @hi > @lo
+          @lo = @width
+          @hi = 0
+        end
+      end
+    end
+  end
+end