From f44494aa114c0089995448758aa22301df921cde Mon Sep 17 00:00:00 2001
From: Kawe Mazidjatari <48657826+Mauler125@users.noreply.github.com>
Date: Wed, 25 Dec 2024 16:14:18 +0100
Subject: [PATCH] Add design details to page manager class

Add details so its known how this system actually works as to afoid future confusion and chances for regressions when someone wants to make a change.
---
 src/logic/pakpage.cpp | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/logic/pakpage.cpp b/src/logic/pakpage.cpp
index 63618fe..1487425 100644
--- a/src/logic/pakpage.cpp
+++ b/src/logic/pakpage.cpp
@@ -2,6 +2,37 @@
 //
 // Pak page builder and management class
 //
+// ----------------------------------------------------------------------------
+// Design details:
+// 
+// - a slab is a memory buffer in which all pages get allocated to, the slab's
+//   alignment is equal to its containing page with the highest alignment.
+// - a page is a memory buffer in which assets are statically stored, the page's
+//   alignment is equal to its containing asset with the highest alignment.
+// - a lump is a piece of data that represents a part of an asset, pages are
+//   constructed from these ordered lumps.
+// 
+// Slab and page details (both header and data) gets stored in the pak file,
+// lumps are only used to construct these slabs and pages, no other details
+// about them are stored in the resulting pak file.
+// 
+// The stored sizes of slabs and pages do not necessarily extend to their full
+// aligned size, the runtime aligns the size and allocates a buffer to its full
+// boundary.
+// 
+// Since pages are static, the assets that are in them need to be aligned and
+// padded out to their full alignments already. This means that if we have an
+// asset that has a higher alignment than the previous asset in the same page,
+// the previous asset must be padded out to accommodate the alignment of this
+// asset. If the requested alignment of the asset results in a boundary that is
+// larger than the total asset's data size, then the remainder must be padded.
+// 
+// Slabs on the other hand are not static, but constructed in the runtime from
+// their pages. Even though the pages aren't necessarily stored to their full
+// aligned size, the slab must have a size of all containing pages with their
+// full aligned size. This is necessary because the runtime aligns the page
+// size to their alignment boundaries and copies it into the preallocated slab.
+// 
 //=============================================================================//
 #include "pch.h"
 #include "pakpage.h"