amaterasu 0.6.0

data/lib/amaterasu/game_boy/joypad.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the joypad inputs and logic.
+    class Joypad
+      BIT_MASK_UNUSED_BITS = 0b11000000
+
+      BIT_MASK_BUTTONS_SELECT_BIT = 0b00100000
+      BIT_MASK_DPAD_SELECT_BIT    = 0b00010000
+
+      # Maps all face buttons to its relevant bit.
+      FACE_BUTTONS = {
+        a: 0,
+        b: 1,
+        select: 2,
+        start: 3
+      }.freeze
+
+      # Maps all D-pad buttons to its relevant bit.
+      DPAD_BUTTONS = {
+        right: 0,
+        left: 1,
+        up: 2,
+        down: 3
+      }.freeze
+
+      # Creates a joypad object.
+      #
+      # - Holds interrupts instance to request a :joypad interrupt.
+      # - @p1 register only holds the relevant selection bits (Bits 5 and 4).
+      # - Dpad and button state are tracked as separate nibbles.
+      def initialize(interrupts, skip_boot_rom: true)
+        @interrupts = interrupts
+        @p1 = skip_boot_rom ? 0xCF : 0x00
+
+        @dpad = 0xF
+        @buttons = 0xF
+      end
+
+      # Returns the 8-bit value stored in the P1 register.
+      #
+      # - Bits 7 and 6 are unused, they always read 1.
+      # - The actual @p1 register only holds the 2 selection bits (Bit 5 and 4).
+      # - Calculate the buttons state based on the pressed buttons and use it as the lower nibble.
+      def p1
+        BIT_MASK_UNUSED_BITS | @p1 | buttons_state
+      end
+
+      # Sets a 8-bit value into the P1 register.
+      #
+      # - The lower nibble is read-only.
+      # - Bit 5 is used to select the face buttons.
+      # - Bit 4 is used to select the d-pad.
+      def p1=(value)
+        old_state = buttons_state
+        @p1 = value & 0b00110000
+        new_state = buttons_state
+
+        falling_edges = old_state & ~new_state # checks for bits that went 1 -> 0
+        request_interrupt if falling_edges.anybits?(0x0F)
+      end
+
+      # @param button [Symbol] Dpad button pressed (:up, :down, :left, :right).
+      def press_dpad(button)
+        relevant_bit = DPAD_BUTTONS[button]
+        return if (@dpad >> relevant_bit).nobits?(1) # already pressed
+
+        clear_mask = ~(1 << relevant_bit)
+        @dpad &= clear_mask
+
+        request_interrupt if dpad_selected?
+      end
+
+      # @param button [Symbol] Dpad button released (:up, :down, :left, :right).
+      def release_dpad(button)
+        relevant_bit = DPAD_BUTTONS[button]
+        return if (@dpad >> relevant_bit).anybits?(1) # already released
+
+        set_mask = (1 << relevant_bit)
+        @dpad |= set_mask
+      end
+
+      # @param button [Symbol] Face button pressed (:a, :b, :start, :select).
+      def press_face(button)
+        relevant_bit = FACE_BUTTONS[button]
+        return if (@buttons >> relevant_bit).nobits?(1) # already pressed
+
+        clear_mask = ~(1 << relevant_bit)
+        @buttons &= clear_mask
+
+        request_interrupt if buttons_selected?
+      end
+
+      # @param button [Symbol] Face button released (:a, :b, :start, :select).
+      def release_face(button)
+        relevant_bit = FACE_BUTTONS[button]
+        return if (@buttons >> relevant_bit).anybits?(1) # already released
+
+        set_mask = (1 << relevant_bit)
+        @buttons |= set_mask
+      end
+
+      private
+
+      def request_interrupt
+        @interrupts.request(:joypad)
+      end
+
+      def dpad_selected?
+        (@p1 >> 4).nobits?(1)
+      end
+
+      def buttons_selected?
+        (@p1 >> 5).nobits?(1)
+      end
+
+      def buttons_state
+        return @dpad & @buttons if dpad_selected? && buttons_selected?
+        return @dpad if dpad_selected?
+        return @buttons if buttons_selected?
+
+        0xF
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/oam/sprite.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Oam
+      # Models each Sprite that is stored inside the Object Attribute Memory (OAM).
+      class Sprite
+        SIZE_IN_BYTES = 4
+
+        BIT_MASK_BG_WIN_PRIORITY_SET = 1 << 7
+        BIT_MASK_OBJ_Y_FLIPPED       = 1 << 6
+        BIT_MASK_OBJ_X_FLIPPED       = 1 << 5
+        BIT_MASK_USE_OBP1_PALETTE    = 1 << 4
+
+        # @param oam_data [Array] Reference to the original OAM @data.
+        # @param index [Integer] Sprite index within OAM (0 - 39).
+        def initialize(oam_data:, index:)
+          @oam_data    = oam_data
+          @base_offset = index * SIZE_IN_BYTES
+        end
+
+        # Screen Y position + 16, this means if Y = 0
+        # the object top pixel is offscreen at (- 16).
+        #
+        # @return [Integer] First byte of the Sprite in OAM.
+        def y
+          @oam_data[@base_offset]
+        end
+
+        # Where the top-most pixel starts at (top row).
+        #
+        def y_screen_pos
+          y - 16
+        end
+
+        # @return [Integer] Byte 1 of the Sprite.
+        def x
+          @oam_data[@base_offset + 1]
+        end
+
+        def x_screen_pos
+          x - 8
+        end
+
+        # @return [Integer] Byte 2 of the Sprite.
+        def tile_index(obj_size_8x16, y_flipped, current_obj_y)
+          return @oam_data[@base_offset + 2] unless obj_size_8x16
+
+          if current_obj_y >= 0 && current_obj_y < 8
+            y_flipped ? bottom_half : top_half
+          else
+            y_flipped ? top_half : bottom_half
+          end
+        end
+
+        def top_half
+          @oam_data[@base_offset + 2] & 0xFE
+        end
+
+        def bottom_half
+          @oam_data[@base_offset + 2] | 0x01
+        end
+
+        # @return [Integer] Byte 3 of the Sprite.
+        def attributes
+          @oam_data[@base_offset + 3]
+        end
+
+        # If this bit is set in the Sprite attributes
+        # it means that the Background or Window should
+        # be displayed on top of the Sprite *UNLESS* the
+        # Background/Window pixel has color_id = 0b00,
+        # in which case the Sprite pixel is shown.
+        #
+        # @return [Boolean]
+        def bg_win_priority_set?
+          (attributes & BIT_MASK_BG_WIN_PRIORITY_SET) != 0
+        end
+
+        # @return [Boolean] Whether or not the Sprite is flipped horizontally.
+        def y_flipped?
+          (attributes & BIT_MASK_OBJ_Y_FLIPPED) != 0
+        end
+
+        # @return [Boolean] Whether or not the Sprite is flipped vertically.
+        def x_flipped?
+          (attributes & BIT_MASK_OBJ_X_FLIPPED) != 0
+        end
+
+        # @return [Boolean] Selects which Color Palette to use for the Sprite pixels.
+        def use_obp1_palette?
+          (attributes & BIT_MASK_USE_OBP1_PALETTE) != 0
+        end
+
+        # @return [String] Custom inspect for easier debugging.
+        def inspect
+          '#<Sprite ' \
+            "y_pos=$#{format('%02X', y)} " \
+            "x_pos=$#{format('%02X', x)} " \
+            "tile_index=$#{format('%02X', top_half)} " \
+            "attributes=#{format('%08b', attributes)}>"
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/oam.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the OAM (Object Attribute Memory) from the DMG Game Boy.
+    class Oam < Ram
+      START_ADDRESS  = 0xFE00
+      END_ADDRESS    = 0xFE9F
+      SPRITE_ENTRIES = 40
+      SIZE = (END_ADDRESS - START_ADDRESS) + 1 #=> 160 bytes
+
+      def initialize
+        super(size: SIZE, offset: START_ADDRESS)
+
+        @sprites = Array.new(SPRITE_ENTRIES) do |sprite_index|
+          Sprite.new(oam_data: @data, index: sprite_index)
+        end
+      end
+
+      def sprite(index)
+        @sprites[index]
+      end
+
+      def each_sprite(&)
+        @sprites.each(&)
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ppu/modes/disabled.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Ppu
+      module Modes
+        # Defines the behavior of the PPU when LCD Control Bit 7 is 0.
+        class Disabled
+          attr_reader :name, :number
+
+          def initialize(ppu)
+            @ppu = ppu
+            @lcd_control = @ppu.registers.lcdc
+
+            @name = 'DISABLED'
+            @number = 0
+          end
+
+          def tick
+            return unless @lcd_control.lcd_enabled?
+
+            @ppu.reset_states
+            @ppu.set_mode(:oam_scan)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ppu/modes/h_blank.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Ppu
+      module Modes
+        # Defines the behavior of the Ppu during HBlank mode.
+        class HBlank
+          attr_reader :name, :number
+
+          def initialize(ppu)
+            @ppu = ppu
+
+            @name = 'HBLANK'
+            @number = 0
+          end
+
+          def tick
+            return unless @ppu.dots == DOTS_PER_SCANLINE
+
+            @ppu.reset_for_scanline
+            @ppu.increment_ly
+
+            if @ppu.registers.ly < VISIBLE_SCANLINES
+              @ppu.set_mode(:oam_scan)
+            elsif @ppu.registers.ly == VISIBLE_SCANLINES
+              @ppu.set_mode(:v_blank)
+              @ppu.request_interrupt(:v_blank)
+            end
+          end
+
+          def inspect
+            '#<Amaterasu::GameBoy::Ppu::Modes::HBlank ' \
+              "@name='#{@name}' " \
+              "@number=#{@number} "
+          end
+
+          def to_s
+            "#{@name} (##{@number}) | WAITING FOR SCANLINE TO FINISH"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ppu/modes/oam_scan.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Ppu
+      module Modes
+        # Defines the behavior of the PPU during OAM Scan mode.
+        class OamScan
+          # Each Sprite takes 2 dots to scan.
+          SCAN_DURATION_IN_DOTS = 80
+
+          attr_reader :name, :number
+
+          # @param ppu [Amaterasu::GameBoy::Ppu] Reference to the PPU instance.
+          def initialize(ppu)
+            @ppu = ppu
+
+            @name = 'OAM SCAN'
+            @number = 2
+
+            @sprite_count = 0
+            @sprite_index = 0
+            @current_sprite = nil
+          end
+
+          # This method is called by the PPU each T-cycle
+          # for all visible scanlines (0 - 143) and when
+          # dots are between 0 and 79.
+          #
+          # Takes exactly 2 dots to fetch a sprite so every
+          # even dot (0, 2, 4, ..., 78) is a NO-OP.
+          def tick
+            if @ppu.dots.odd?
+              @current_sprite = @ppu.fetch_sprite_at(@sprite_index) #=> 0 - 39
+              @sprite_index += 1
+
+              if sprite_within_current_scanline? && @sprite_count < Ppu::MAX_SPRITES_PER_SCANLINE
+                @ppu.sprite_buffer << @current_sprite
+                @sprite_count += 1
+              end
+            end
+
+            return unless @ppu.dots == SCAN_DURATION_IN_DOTS
+
+            sort_sprites_by_x_positions unless @ppu.sprite_buffer.empty?
+            @sprite_count = 0
+            @sprite_index = 0
+            @ppu.wy_eq_ly = true if window_triggered?
+            @ppu.set_mode(:rendering)
+          end
+
+          # Custom inspect to prevent circular dependencies.
+          def inspect
+            '#<Amaterasu::GameBoy::Ppu::Modes::OamScan ' \
+              "@name='#{@name}' " \
+              "@number=#{@number} " \
+              "@sprite_buffer=#{@sprite_buffer}"
+          end
+
+          # Custom to_s method to use in the Ppu#log_state method.
+          def to_s
+            "#{@name} (##{@number}) | " \
+              "SCANNED: Sprite ##{format('%02d', @sprite_index)} | " \
+              "BUFFER: #{@ppu.sprite_buffer} (#{@ppu.sprite_buffer.size})"
+          end
+
+          private
+
+          def window_triggered?
+            return false unless @ppu.registers.lcdc.window_enabled?
+            return false unless @ppu.registers.ly == @ppu.registers.wy
+            return false if @ppu.wy_eq_ly
+
+            true
+          end
+
+          def sprite_within_current_scanline?
+            sprite_height = @ppu.registers.lcdc.obj_size_8x16? ? 16 : 8
+
+            @ppu.registers.ly >= @current_sprite.y_screen_pos
+              && @ppu.registers.ly < @current_sprite.y_screen_pos + sprite_height
+          end
+
+          # TODO: benchmark the performance of both
+          def sort_sprites_by_x_positions
+            @ppu.sprite_buffer.sort_by!(&:x)
+            # @ppu.sprite_buffer.sort! { |a, b| a.x <=> b.x }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ppu/modes/rendering/bg_win_fetcher.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Ppu
+      module Modes
+        class Rendering
+          # Responsible for fetching Background and Window tiles,
+          # decoding the pixels and outputting them into the BG/WIN FIFO.
+          #
+          # Despite the similarity it behaves differently than the SpriteFetcher.
+          class BgWinFetcher
+            attr_reader :fetch_mode, :step
+
+            def initialize(ppu, bg_win_fifo)
+              @ppu = ppu
+              @bg_win_fifo = bg_win_fifo
+
+              @step = :fetch_tile_index
+              @bg_fetcher_x = 0
+              @window_fetcher_x = 0
+              @fetch_mode = :bg
+
+              @fetch_duration = 6
+              @sleep_duration = 2
+              @warming_up     = true
+
+              @tile_index     = nil
+              @tile_data_low  = nil
+              @tile_data_high = nil
+              @tile_pixels    = nil
+            end
+
+            # Core fetch state machine.
+            #
+            def tick
+              case @step
+              when :fetch_tile_index     then fetch_tile_index
+              when :fetch_tile_data_low  then fetch_tile_data_low
+              when :fetch_tile_data_high then fetch_tile_data_high
+              when :push  then push
+              when :sleep then sleep
+              end
+            end
+
+            def activate_window!
+              @bg_win_fifo.clear
+              @fetch_mode = :window
+              reset_cycle
+            end
+
+            def increment_window_y
+              return unless @window_drawed
+
+              @ppu.window_y_count += 1
+              @window_drawed = false
+            end
+
+            def reset_for_scanline
+              reset_cycle
+              @fetch_mode = :bg
+              @warming_up = true
+              @bg_fetcher_x = 0
+              @window_fetcher_x = 0
+              increment_window_y
+            end
+
+            private
+
+            # Fetches the BG Tile index at the current Tile map.
+            def fetch_tile_index
+              @fetch_duration -= 1
+              return unless @fetch_duration == 4
+
+              tile_x = @fetch_mode == :bg ? current_bg_tile_x : current_window_tile_x
+              tile_y = @fetch_mode == :bg ? current_bg_tile_y : current_window_tile_y
+
+              @tile_index = current_tile_map.tile_index_at(
+                tile_x: tile_x,
+                tile_y: tile_y
+              )
+
+              @step = :fetch_tile_data_low
+            end
+
+            # Fetches the low byte of the BG or Window Tile Row
+            # that overlaps with the current row/line being drawn.
+            def fetch_tile_data_low
+              @fetch_duration -= 1
+              return unless @fetch_duration == 2
+
+              current_y = @fetch_mode == :bg ? current_bg_y : current_window_y
+              @tile_data_low = current_tile_data.tile_at(@tile_index).data_low(current_y)
+
+              @step = :fetch_tile_data_high
+            end
+
+            # Fetches the high byte of the BG or Window Tile Row
+            # that overlaps with the current row/line being drawn.
+            def fetch_tile_data_high
+              @fetch_duration -= 1
+              return unless @fetch_duration == 0
+
+              current_y = @fetch_mode == :bg ? current_bg_y : current_window_y
+              @tile_data_high = current_tile_data.tile_at(@tile_index).data_high(current_y)
+              fetch_tile_pixels
+              @warming_up ? discard_pixels : attempt_push_into_fifo
+            end
+
+            # Fetches the BG or Window Tile pixels.
+            def fetch_tile_pixels
+              @tile_pixels = Vram::Tile::PIXELS_LOOKUP[(@tile_data_high << 8) | @tile_data_low]
+            end
+
+            def discard_pixels
+              @tile_pixels = nil
+              @warming_up = false
+              reset_cycle
+            end
+
+            def attempt_push_into_fifo
+              push_successful = @bg_win_fifo.push?(@tile_pixels)
+
+              if push_successful
+                if @fetch_mode == :bg
+                  @bg_fetcher_x += 1
+                else
+                  @window_fetcher_x += 1
+                  @window_drawed = true
+                end
+
+                @step = :sleep
+              else
+                @step = :push
+              end
+            end
+
+            def push
+              push_successful = @bg_win_fifo.push?(@tile_pixels)
+              return unless push_successful
+
+              reset_cycle
+            end
+
+            def sleep
+              @sleep_duration -= 1
+              reset_cycle if @sleep_duration == 0
+            end
+
+            def reset_cycle
+              @step = :fetch_tile_index
+              @fetch_duration = 6
+              @sleep_duration = 2
+              @tile_index     = nil
+              @tile_data_low  = nil
+              @tile_data_high = nil
+              @tile_pixels    = nil
+            end
+
+            def current_bg_y
+              @ppu.registers.ly + @ppu.registers.scy
+            end
+
+            def current_bg_tile_x
+              (@ppu.registers.scx / Vram::Tile::PIXEL_WIDTH) + @bg_fetcher_x
+            end
+
+            def current_bg_tile_y
+              current_bg_y / Vram::Tile::PIXEL_HEIGHT
+            end
+
+            def current_window_y
+              @ppu.window_y_count
+            end
+
+            def current_window_tile_x
+              @window_fetcher_x
+            end
+
+            def current_window_tile_y
+              @ppu.window_y_count / Vram::Tile::PIXEL_HEIGHT
+            end
+
+            # @return [Vram::TileMap]
+            def current_tile_map
+              @fetch_mode == :bg ? @ppu.bg_tile_map : @ppu.window_tile_map
+            end
+
+            # @return [Vram::TileData]
+            def current_tile_data
+              @ppu.bg_win_tile_data
+            end
+
+            def to_s
+              "Mode: #{@fetch_mode.upcase} | " \
+                "Step: #{@step.upcase} | " \
+                "PIX: #{@tile_pixels}"
+            end
+          end
+        end
+      end
+    end
+  end
+end