add developer documentation to ppusim/ppu interface

5 files changed, 47 insertions, 27 deletions

diff --git a/src/ppu/consts.h b/src/ppu/consts.h
index 0e8fba4..a27b7b7 100644
--- a/src/ppu/consts.h
+++ b/src/ppu/consts.h
@@ -18,9 +18,9 @@
 #define HH_PPU_SCREEN_WIDTH 320
 /** @brief screen height in pixels */
 #define HH_PPU_SCREEN_HEIGHT 240
-/** @brief amount of horizontal backgorund tiles on background canvas */
+/** @brief amount of horizontal background tiles on background canvas */
 #define HH_PPU_BG_CANVAS_TILES_H 40
-/** @brief amount of vertical backgorund tiles on background canvas */
+/** @brief amount of vertical background tiles on background canvas */
 #define HH_PPU_BG_CANVAS_TILES_V 30
 
 #include "ppu/types.h"
diff --git a/src/ppu/internals.c b/src/ppu/internals.c
index e4817f1..1c95a5a 100644
--- a/src/ppu/internals.c
+++ b/src/ppu/internals.c
@@ -4,9 +4,12 @@
 #include "ppu/internals.h"
 
 bool hh_ppu_vram_valid_address(hh_ppu_addr_t addr) {
-	#warning unimlemented 
-	(void) addr; // compiler bruh
-	return true;
+	if (addr >= HH_PPU_VRAM_TMM_OFFSET && addr <= HH_PPU_VRAM_TMM_OFFSET + HH_PPU_VRAM_TMM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_BAM_OFFSET && addr <= HH_PPU_VRAM_BAM_OFFSET + HH_PPU_VRAM_BAM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_FAM_OFFSET && addr <= HH_PPU_VRAM_FAM_OFFSET + HH_PPU_VRAM_FAM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_PAL_OFFSET && addr <= HH_PPU_VRAM_PAL_OFFSET + HH_PPU_VRAM_PAL_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_AUX_OFFSET && addr <= HH_PPU_VRAM_AUX_OFFSET + HH_PPU_VRAM_AUX_SIZE) return true;
+	return false;
 }
 
 void hh_ppu_vram_write(hh_s_ppu_vram_data data) {
diff --git a/src/ppu/internals.h b/src/ppu/internals.h
index 8f50c52..4a1726e 100644
--- a/src/ppu/internals.h
+++ b/src/ppu/internals.h
@@ -9,6 +9,7 @@
 /** @brief resize `in` to `upper downto lower` like in vhdl */
 #define HH_RESIZE(in, upper, lower) ((((hh_ppu_data_t)(in)) & (HH_MASK(upper+1-lower) << lower)) >> lower)
 
+/** @brief memory word(s) that can be placed into vram */
 typedef struct {
 	hh_ppu_addr_t offset;
 	hh_ppu_addr_t size;
@@ -22,9 +23,14 @@ void hh_ppu_vram_dwrite(hh_ppu_addr_t addr, hh_ppu_data_t data);
 /** @brief write data block into vram */
 void hh_ppu_vram_write(hh_s_ppu_vram_data data);
 
+/** @brief convert local background attribute memory entry to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_bam(hh_s_ppu_loc_bam_entry);
+/** @brief convert local foreground attribute memory entry to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_fam(hh_s_ppu_loc_fam_entry);
+/** @brief convert local AUX memory copy to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_aux(hh_s_ppu_loc_aux);
+/** @brief convert local sprite to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_sprite(const hh_ppu_loc_sprite_data_t);
+/** @brief convert local RGB color to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_color(hh_ppu_rgb_color_t);
 
diff --git a/src/ppu/ppu.h b/src/ppu/ppu.h
index cab0e30..75d97c1 100644
--- a/src/ppu/ppu.h
+++ b/src/ppu/ppu.h
@@ -2,21 +2,24 @@
 
 #include "ppu/types.h"
 
+/** @brief vblank interrupt (game main loop) */
 void hh_ppu_vblank_interrupt();
+/** @brief initialize ppu interface */
 void hh_ppu_init();
+/** @brief deinitialize ppu interface */
 void hh_ppu_deinit();
 
-/* @brief update single foreground sprite */
+/** @brief update single foreground sprite */
 void hh_ppu_update_foreground(unsigned index, hh_s_ppu_loc_fam_entry e);
-/* @brief update single background sprite */
+/** @brief update single background sprite */
 void hh_ppu_update_background(unsigned index, hh_s_ppu_loc_bam_entry e);
-/* @brief update aux register */
+/** @brief update aux register */
 void hh_ppu_update_aux(hh_s_ppu_loc_aux aux);
-/* @brief update single sprite */
+/** @brief update single sprite */
 void hh_ppu_update_sprite(unsigned tilemap_index, const hh_s_ppu_loc_sprite sprite);
-/* @brief update entire palette table */
+/** @brief update entire palette table */
 void hh_ppu_update_palette_table(hh_ppu_loc_palette_table_t table);
-/* @brief update single palette */
+/** @brief update single palette */
 void hh_ppu_update_palette(unsigned palette_index, hh_ppu_loc_palette_data_t palette);
-/* @brief update single color in palette */
+/** @brief update single color in palette */
 void hh_ppu_update_color(unsigned palette_index, unsigned color_index, hh_ppu_rgb_color_t color);
diff --git a/src/ppu/types.h b/src/ppu/types.h
index 08bef13..fa776e5 100644
--- a/src/ppu/types.h
+++ b/src/ppu/types.h
@@ -5,38 +5,46 @@
 
 #include "ppu/consts.h"
 
+/** @brief PPU VRAM address */
 typedef uint16_t hh_ppu_addr_t;
+/** @brief PPU VRAM data word */
 typedef uint16_t hh_ppu_data_t;
 
+/** @brief local RGB color */
 typedef uint8_t hh_ppu_rgb_color_t[3];
 
+/** @brief local palette */
 typedef hh_ppu_rgb_color_t hh_ppu_loc_palette_data_t[HH_PPU_PALETTE_COLOR_COUNT];
+/** @brief local palette table */
 typedef hh_ppu_loc_palette_data_t hh_ppu_loc_palette_table_t[HH_PPU_PALETTE_COUNT];
 
+/** @brief local sprite */
 typedef uint8_t hh_ppu_loc_sprite_data_t[HH_PPU_SPRITE_WIDTH * HH_PPU_SPRITE_HEIGHT];
 typedef hh_ppu_loc_sprite_data_t hh_s_ppu_loc_sprite;
 
+/** @brief local background attribute memory entry */
 typedef struct {
-	bool horizontal_flip;
-	bool vertical_flip;
-	uint8_t palette_index;
-	uint8_t tilemap_index;
+	bool horizontal_flip; /** @brief flip sprite horizontally */
+	bool vertical_flip; /** @brief flip sprite vertically */
+	uint8_t palette_index; /** @brief index of palette to use */
+	uint8_t tilemap_index; /** @brief index of sprite to use */
 } hh_s_ppu_loc_bam_entry;
 
+/** @brief local foreground attribute memory entry */
 typedef struct {
-	bool horizontal_flip;
-	bool vertical_flip;
-	int32_t position_x;
-	int32_t position_y;
-	uint8_t palette_index;
-	uint8_t tilemap_index;
+	bool horizontal_flip; /** @brief flip sprite horizontally */
+	bool vertical_flip; /** @brief flip sprite vertically */
+	int32_t position_x; /** @brief horizontal position from left edge of sprite to left edge of screen (-16 to 320), relative to viewport */
+	int32_t position_y; /** @brief vertical position from top edge of sprite to top edge of screen (-16 to 240), relative to viewport */
+	uint8_t palette_index; /** @brief index of palette to use */
+	uint8_t tilemap_index; /** @brief index of sprite to use */
 } hh_s_ppu_loc_fam_entry;
 
+/** @brief local copy of auxiliary memory */
 typedef struct {
-	bool sysreset;
-	bool fg_fetch;
-	uint16_t bg_shift_x;
-	uint16_t bg_shift_y;
+	bool sysreset; /** @brief enable sysreset, self-resets */
+	bool fg_fetch; /** @brief enable foreground fetch, self-resets */
+	uint16_t bg_shift_x; /** @brief shift background canvas left (0 to 320) */
+	uint16_t bg_shift_y; /** @brief shift background canvas down (0 to 240) */
 } hh_s_ppu_loc_aux;
 
-typedef uint16_t hh_ppu_native_color_t;