Documentation

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

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::{
+use winit::{self, dpi::LogicalSize, window::Window};
-	self,
-	dpi::{LogicalSize, PhysicalSize},
-	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>,

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.

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

src/main.rs

@@ -40,9 +40,7 @@ fn main() -> Result<()> {
 					&game.get_ui_sprites(),
 				) {
 					Ok(_) => {}
-					Err(wgpu::SurfaceError::Lost) => {
+					Err(wgpu::SurfaceError::Lost) => gpu.resize(&game.system.starfield),
-						gpu.resize(&game.system.starfield, gpu.window_size)
-					}
 					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) => {
+				WindowEvent::Resized(_) => {
-					gpu.resize(&game.system.starfield, *physical_size);
+					gpu.resize(&game.system.starfield);
 				}
-				WindowEvent::ScaleFactorChanged { new_inner_size, .. } => {
+				WindowEvent::ScaleFactorChanged { .. } => {
-					gpu.resize(&game.system.starfield, **new_inner_size);
+					gpu.resize(&game.system.starfield);
 				}
 				_ => {}
 			},