From 779ad2408cf97687878f816ddff2b04f22f5172d Mon Sep 17 00:00:00 2001
From: lonkaars <loek@pipeframe.xyz>
Date: Sat, 25 Feb 2023 16:48:01 +0100
Subject: add developer documentation to ppusim/ppu interface

---
 src/ppusim/mem.h   | 1 +
 src/ppusim/pixel.h | 1 +
 src/ppusim/sim.h   | 2 ++
 src/ppusim/work.h  | 9 ++++++++-
 4 files changed, 12 insertions(+), 1 deletion(-)

(limited to 'src/ppusim')

diff --git a/src/ppusim/mem.h b/src/ppusim/mem.h
index 72f40be..bc36d98 100644
--- a/src/ppusim/mem.h
+++ b/src/ppusim/mem.h
@@ -1,4 +1,5 @@
 #include "ppu/types.h"
 
+/** @brief PPUSIM internal VRAM */
 extern hh_ppu_data_t *g_hh_ppusim_vram;
 
diff --git a/src/ppusim/pixel.h b/src/ppusim/pixel.h
index 475fe11..7b26ee6 100644
--- a/src/ppusim/pixel.h
+++ b/src/ppusim/pixel.h
@@ -2,5 +2,6 @@
 
 #include "ppusim/work.h"
 
+/** @brief calculate color for pixel (`x`,`y`), and put into `unsigned short s[3]` */
 void hh_ppusim_pixel(uint8_t* s, unsigned x, unsigned y);
 
diff --git a/src/ppusim/sim.h b/src/ppusim/sim.h
index e161746..73f4b23 100644
--- a/src/ppusim/sim.h
+++ b/src/ppusim/sim.h
@@ -1,4 +1,6 @@
 #pragma once
 
+/** @brief pixel-perfect upscale factor for PPUSIM */
 #define HH_PPUSIM_UPSCALE_FACTOR 3
+/** @brief max framerate for PPUSIM */
 #define HH_PPUSIM_FRAMERATE 60
diff --git a/src/ppusim/work.h b/src/ppusim/work.h
index c1a5148..6f72357 100644
--- a/src/ppusim/work.h
+++ b/src/ppusim/work.h
@@ -4,14 +4,21 @@
 
 #include "ppu/consts.h"
 
+/** @brief logical core count, used for multithreading in `hh_ppusim_draw_frame` */
 extern unsigned g_hh_ppusim_core_count;
+/** @brief thread handles, used for multithreading in `hh_ppusim_draw_frame` */
 extern pthread_t* g_hh_ppusim_threads;
 
+/** @brief ppusim color (24-bit RGB) */
 typedef uint8_t hh_s_ppusim_color[3];
+/** @brief ppusim screen scanline */
 typedef hh_s_ppusim_color hh_s_ppusim_scanline[HH_PPU_SCREEN_WIDTH];
+/** @brief ppusim complete screen buffer */
 typedef hh_s_ppusim_scanline hh_s_ppusim_screen[HH_PPU_SCREEN_HEIGHT];
 
-void* hh_ppusim_draw_thread(void*);
+/** @brief draw `core`'s work portion to `hh_s_ppusim_screen` */
+void* hh_ppusim_draw_thread(void* core);
 
+/** @brief spawn threads to draw frame, join threads and draw to `SDL_Renderer` */
 void hh_ppusim_draw_frame(SDL_Renderer*);
 
-- 
cgit v1.2.3