From b1de7f37ffa1e81bdec9a0db86e057baf47768c3 Mon Sep 17 00:00:00 2001
From: Mark <mark@betalupi.com>
Date: Sun, 31 Dec 2023 18:59:08 -0800
Subject: [PATCH] Documentation

---
 TODO.md                       |  3 ++-
 crates/render/src/gpustate.rs | 24 ++++++++++++++++--------
 crates/render/src/lib.rs      | 10 ++++++++++
 crates/render/src/sprite.rs   |  1 +
 src/main.rs                   | 12 +++++-------
 5 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/TODO.md b/TODO.md
index dce9c8c..c57a18c 100644
--- a/TODO.md
+++ b/TODO.md
@@ -65,8 +65,9 @@
  - Better player controller? (only one shipbehavior needs inputs)
  - Clear all `// TODO:` comments littered in the source
  - CLI options (debug, save location, content location, check content)
- - Config file
+ - Config file and compile options, remove all those consts.
  - Engine flares shouldn't be centered
+ - Sprite optimization: do we need to allocate a new `Vec` every frame? Probably not.
 
 ## Content
  - Angled engines
diff --git a/crates/render/src/gpustate.rs b/crates/render/src/gpustate.rs
index b3cbf39..3aae2cd 100644
--- a/crates/render/src/gpustate.rs
+++ b/crates/render/src/gpustate.rs
@@ -3,11 +3,7 @@ use bytemuck;
 use cgmath::{Deg, EuclideanSpace, Matrix4, Point2, Vector2, Vector3};
 use std::{iter, rc::Rc};
 use wgpu;
-use winit::{
-	self,
-	dpi::{LogicalSize, PhysicalSize},
-	window::Window,
-};
+use winit::{self, dpi::LogicalSize, window::Window};
 
 use crate::{
 	consts::{OPENGL_TO_WGPU_MATRIX, SPRITE_INSTANCE_LIMIT, STARFIELD_INSTANCE_LIMIT},
@@ -24,14 +20,20 @@ use crate::{
 	ObjectSprite, StarfieldStar, UiSprite,
 };
 
+/// A high-level GPU wrapper. Consumes game state,
+/// produces pretty pictures.
 pub struct GPUState {
+	/// The window to we draw on
+	pub window: Window,
+
+	/// The size of the window we draw on
+	pub window_size: winit::dpi::PhysicalSize<u32>,
+
 	device: wgpu::Device,
 	config: wgpu::SurfaceConfiguration,
 	surface: wgpu::Surface,
 	queue: wgpu::Queue,
 
-	pub window: Window,
-	pub window_size: winit::dpi::PhysicalSize<u32>,
 	window_aspect: f32,
 
 	sprite_pipeline: wgpu::RenderPipeline,
@@ -49,6 +51,7 @@ struct VertexBuffers {
 }
 
 impl GPUState {
+	/// Make a new GPUState that draws on `window`
 	pub async fn new(window: Window, ct: &content::Content) -> Result<Self> {
 		let window_size = window.inner_size();
 		let window_aspect = window_size.width as f32 / window_size.height as f32;
@@ -185,11 +188,15 @@ impl GPUState {
 		});
 	}
 
+	/// Get the window this GPUState is attached to
 	pub fn window(&self) -> &Window {
 		&self.window
 	}
 
-	pub fn resize(&mut self, starfield: &Vec<StarfieldStar>, new_size: PhysicalSize<u32>) {
+	/// Update window size.
+	/// This should be called whenever our window is resized.
+	pub fn resize(&mut self, starfield: &Vec<StarfieldStar>) {
+		let new_size = self.window.inner_size();
 		if new_size.width > 0 && new_size.height > 0 {
 			self.window_size = new_size;
 			self.window_aspect = new_size.width as f32 / new_size.height as f32;
@@ -484,6 +491,7 @@ impl GPUState {
 		);
 	}
 
+	/// Main render function. Draws sprites on a window.
 	pub fn render(
 		&mut self,
 		camera_pos: Point2<f32>,
diff --git a/crates/render/src/lib.rs b/crates/render/src/lib.rs
index ebc3723..cf1ceb5 100644
--- a/crates/render/src/lib.rs
+++ b/crates/render/src/lib.rs
@@ -1,3 +1,12 @@
+#![warn(missing_docs)]
+
+//! This crate contains all drawing logic and NO game logic.
+//! It converts game state to a nice picture.
+//!
+//! [`GPUState`] is the main struct this crate provides,
+//! and the only one external code should interact with.
+//! (Excluding data structs, like [`ObjectSprite`])
+
 mod consts;
 mod globaldata;
 mod gpustate;
@@ -14,6 +23,7 @@ use galactica_content as content;
 pub use gpustate::GPUState;
 pub use sprite::{AnchoredUiPosition, ObjectSprite, ObjectSubSprite, UiSprite};
 
+/// TODO: this shouldn't be here
 pub struct StarfieldStar {
 	/// Star coordinates, in world space.
 	/// These are relative to the center of a starfield tile.
diff --git a/crates/render/src/sprite.rs b/crates/render/src/sprite.rs
index 28d7de6..69f84ee 100644
--- a/crates/render/src/sprite.rs
+++ b/crates/render/src/sprite.rs
@@ -56,6 +56,7 @@ pub struct ObjectSprite {
 	pub children: Option<Vec<ObjectSubSprite>>,
 }
 
+/// A sprite that is drawn relative to an ObjectSprite.
 #[derive(Debug, Clone)]
 pub struct ObjectSubSprite {
 	/// The sprite texture to draw
diff --git a/src/main.rs b/src/main.rs
index 0597417..69b09ef 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -40,9 +40,7 @@ fn main() -> Result<()> {
 					&game.get_ui_sprites(),
 				) {
 					Ok(_) => {}
-					Err(wgpu::SurfaceError::Lost) => {
-						gpu.resize(&game.system.starfield, gpu.window_size)
-					}
+					Err(wgpu::SurfaceError::Lost) => gpu.resize(&game.system.starfield),
 					Err(wgpu::SurfaceError::OutOfMemory) => *control_flow = ControlFlow::Exit,
 					// All other errors (Outdated, Timeout) should be resolved by the next frame
 					Err(e) => eprintln!("{:?}", e),
@@ -77,11 +75,11 @@ fn main() -> Result<()> {
 				WindowEvent::MouseWheel { delta, phase, .. } => {
 					game.process_scroll(delta, phase);
 				}
-				WindowEvent::Resized(physical_size) => {
-					gpu.resize(&game.system.starfield, *physical_size);
+				WindowEvent::Resized(_) => {
+					gpu.resize(&game.system.starfield);
 				}
-				WindowEvent::ScaleFactorChanged { new_inner_size, .. } => {
-					gpu.resize(&game.system.starfield, **new_inner_size);
+				WindowEvent::ScaleFactorChanged { .. } => {
+					gpu.resize(&game.system.starfield);
 				}
 				_ => {}
 			},