adding file doc comments

6 files changed, 131 insertions, 103 deletions

diff --git a/examples/cube.c b/examples/cube.c
index cf64370..f107e75 100644
--- a/examples/cube.c
+++ b/examples/cube.c
@@ -29,13 +29,13 @@ void draw() {
 
   // print debug info for one frame
   static bool printed = false;
-  if (!printed) {
-    printf("\nTo Center:\n");
-    for (int i = 0; i < 16; i += 4) {
-      printf("%f %f %f %f\n", to_center.data[i], to_center.data[i + 1], to_center.data[i + 2], to_center.data[i + 3]);
-    }
-    printed = true;
-  }
+  // if (!printed) {
+  //   printf("\nTo Center:\n");
+  //   for (int i = 0; i < 16; i += 4) {
+  //     printf("%f %f %f %f\n", to_center.data[i], to_center.data[i + 1], to_center.data[i + 2], to_center.data[i + 3]);
+  //   }
+  //   printed = true;
+  // }
 
   // first move to center, then rotate, then move back
   mat4 cube_transform = mat4_mult(from_center, mat4_mult(rotation, to_center));
@@ -63,7 +63,6 @@ void draw() {
 }
 
 int main() {
-
   core_bringup("Celeritas Example: Triangle", NULL);
 
   // create rendering pipeline
diff --git a/include/celeritas.h b/include/celeritas.h
index 979e8c4..94d08fb 100644
--- a/include/celeritas.h
+++ b/include/celeritas.h
@@ -76,6 +76,10 @@ _Static_assert(sizeof(ptrdiff_t) == 8, "type ptrdiff_t should be 8 bytes");
 #define GPU_METAL 1
 #endif
 
+#define TODO(msg) \
+  printf("TODO: %s\n", msg); \
+  exit(1);
+
 // --- Forward declare vital structures
 typedef struct core core;
 typedef struct renderer renderer;
@@ -241,10 +245,11 @@ typedef struct vec4 {
 /** @brief Quaternion */
 typedef vec4 quat;
 
-/** @brief 4x4 Matrix */
+/** @brief 4x4 Matrix
+ * @note Column-major is used throughout the Celeritas maths code.
+ */
 typedef struct mat4 {
-  // TODO: use this format for more readable code: vec4 x_axis, y_axis, z_axis, w_axis;
-  f32 data[16];
+  vec4 x_axis, y_axis, z_axis, w_axis;
 } mat4;
 
 /** @brief 3D affine transformation */
@@ -486,10 +491,13 @@ void ral_backend_resize_framebuffer(int width, int height);
 
 // Frame lifecycle
 
+/** @brief A function pointer to a function that should be called with any prepared graphics resources for a frame
+           + access to the renderer. */
 typedef void (*scoped_draw_commands)();  // callback that we run our draw commands within.
 // allows us to wrap some api-specific behaviour
 
 void ral_frame_start();
+
 void ral_frame_draw(scoped_draw_commands draw_fn);
 void ral_frame_end();
 
@@ -559,7 +567,9 @@ typedef struct camera {
   f32 fov;
 } camera;
 
-/** @brief calculates the view and projection matrices for a camera  */
+/**
+ * @brief Calculates a matrix that transforms a model into camera-space with perspective projection applied.
+ */
 mat4 camera_view_proj(camera camera, f32 lens_height, f32 lens_width, mat4* out_view, mat4* out_proj);
 
 // TODO: Filament PBR model
diff --git a/src/camera.c b/src/camera.c
index eb8fc7d..2f5506e 100644
--- a/src/camera.c
+++ b/src/camera.c
@@ -1,3 +1,11 @@
+/**
+ * @file camera.c
+ * @author Omniscient
+ * @brief Camera movement
+ * 
+ * @copyright Copyright (c) 2024
+ */
+
 #include <celeritas.h>
 
 mat4 camera_view_proj(camera camera, f32 lens_height, f32 lens_width, mat4* out_view, mat4* out_proj) {
diff --git a/src/core.c b/src/core.c
index ed09597..addae75 100644
--- a/src/core.c
+++ b/src/core.c
@@ -1,8 +1,12 @@
-// The engine "core"
+/**
+ * @file core.c
+ * @author Omniscient
+ * @brief 
+ * 
+ * @copyright Copyright (c) 2024
+ */
 
 #include <celeritas.h>
-#include <stdlib.h>
-#include "glfw3.h"
 
 NAMESPACED_LOGGER(core);
 
diff --git a/src/impl.c b/src/impl.c
index 18f2549..3af8ed2 100644
--- a/src/impl.c
+++ b/src/impl.c
@@ -1,4 +1,10 @@
-// For pulling in implementation files of single-header libraries
+/**
+ * @file impl.c
+ * @author Omniscient
+ * @brief Pulls in implementations of single-header libraries
+ * 
+ * @copyright Copyright (c) 2024
+ */
 
 #define STB_IMAGE_IMPLEMENTATION
 #include "stb_image.h"
\ No newline at end of file
diff --git a/src/maths.c b/src/maths.c
index 3a7ecf1..72b6dd3 100644
--- a/src/maths.c
+++ b/src/maths.c
@@ -1,3 +1,11 @@
+/**
+ * @file maths.c
+ * @author Omniscient
+ * @brief Linear algebra for 2D and 3D including vectors, matrices, and quaternion functions.
+ *
+ * @copyright Copyright (c) 2024
+ */
+
 #include <celeritas.h>
 
 vec3 vec3_create(f32 x, f32 y, f32 z) { return (vec3){ x, y, z }; }
@@ -43,117 +51,110 @@ quat quat_from_axis_angle(vec3 axis, f32 angle, bool normalize) {
   return q;
 }
 
-mat4 mat4_ident() { return (mat4){ .data = { 1.0, 0., 0., 0., 0., 1., 0., 0., 0., 0., 1., 0., 0., 0., 0., 1.0 } }; }
+mat4 mat4_ident() {
+  return (mat4){
+    .x_axis = { 1, 0, 0, 0 },
+    .y_axis = { 0, 1, 0, 0 },
+    .z_axis = { 0, 0, 1, 0 },
+    .w_axis = { 0, 0, 0, 1 },
+  };
+}
 
 mat4 mat4_translation(vec3 position) {
   mat4 out_matrix = mat4_ident();
-  out_matrix.data[12] = position.x;
-  out_matrix.data[13] = position.y;
-  out_matrix.data[14] = position.z;
+  out_matrix.w_axis.x = position.x;
+  out_matrix.w_axis.y = position.y;
+  out_matrix.w_axis.z = position.z;
   return out_matrix;
 }
 
 mat4 mat4_scale(vec3 scale) {
   mat4 out_matrix = mat4_ident();
-  out_matrix.data[0] = scale.x;
-  out_matrix.data[5] = scale.y;
-  out_matrix.data[10] = scale.z;
+  out_matrix.x_axis.x = scale.x;
+  out_matrix.y_axis.y = scale.y;
+  out_matrix.z_axis.z = scale.z;
   return out_matrix;
 }
 
 // TODO: double check this
 mat4 mat4_rotation(quat rotation) {
-  mat4 out_matrix = mat4_ident();
-  quat n = quat_normalise(rotation);
+  TODO("impl mat4_rotation");
+  // mat4 out_matrix = mat4_ident();
+  // quat n = quat_normalise(rotation);
 
-  out_matrix.data[0] = 1.0f - 2.0f * n.y * n.y - 2.0f * n.z * n.z;
-  out_matrix.data[1] = 2.0f * n.x * n.y - 2.0f * n.z * n.w;
-  out_matrix.data[2] = 2.0f * n.x * n.z + 2.0f * n.y * n.w;
+  // out_matrix.data[0] = 1.0f - 2.0f * n.y * n.y - 2.0f * n.z * n.z;
+  // out_matrix.data[1] = 2.0f * n.x * n.y - 2.0f * n.z * n.w;
+  // out_matrix.data[2] = 2.0f * n.x * n.z + 2.0f * n.y * n.w;
 
-  out_matrix.data[4] = 2.0f * n.x * n.y + 2.0f * n.z * n.w;
-  out_matrix.data[5] = 1.0f - 2.0f * n.x * n.x - 2.0f * n.z * n.z;
-  out_matrix.data[6] = 2.0f * n.y * n.z - 2.0f * n.x * n.w;
+  // out_matrix.data[4] = 2.0f * n.x * n.y + 2.0f * n.z * n.w;
+  // out_matrix.data[5] = 1.0f - 2.0f * n.x * n.x - 2.0f * n.z * n.z;
+  // out_matrix.data[6] = 2.0f * n.y * n.z - 2.0f * n.x * n.w;
 
-  out_matrix.data[8] = 2.0f * n.x * n.z - 2.0f * n.y * n.w;
-  out_matrix.data[9] = 2.0f * n.y * n.z + 2.0f * n.x * n.w;
-  out_matrix.data[10] = 1.0f - 2.0f * n.x * n.x - 2.0f * n.y * n.y;
+  // out_matrix.data[8] = 2.0f * n.x * n.z - 2.0f * n.y * n.w;
+  // out_matrix.data[9] = 2.0f * n.y * n.z + 2.0f * n.x * n.w;
+  // out_matrix.data[10] = 1.0f - 2.0f * n.x * n.x - 2.0f * n.y * n.y;
 
-  return out_matrix;
+  // return out_matrix;
 }
 
-// mat4 mat4_mult(mat4 lhs, mat4 rhs) {
-//   mat4 out_matrix = mat4_ident();
-
-//   const f32* m1_ptr = lhs.data;
-//   const f32* m2_ptr = rhs.data;
-//   f32* dst_ptr = out_matrix.data;
-
-//   for (i32 i = 0; i < 4; ++i) {
-//     for (i32 j = 0; j < 4; ++j) {
-//       *dst_ptr = m1_ptr[0] * m2_ptr[0 + j] + m1_ptr[1] * m2_ptr[4 + j] + m1_ptr[2] * m2_ptr[8 + j] +
-//                  m1_ptr[3] * m2_ptr[12 + j];
-//       dst_ptr++;
-//     }
-//     m1_ptr += 4;
-//   }
-
-//   return out_matrix;
-// }
 mat4 mat4_mult(mat4 lhs, mat4 rhs) {
-  mat4 out_matrix = mat4_ident();
-
-  for (i32 row = 0; row < 4; row++) {
-    for (i32 col = 0; col < 4; col++) {
-      f32 sum = 0;
-      for (i32 i = 0; i < 4; i++) {
-        // column-major: first matrix columns × second matrix rows
-        sum += lhs.data[row + i * 4] * rhs.data[i + col * 4];
-      }
-      out_matrix.data[row + col * 4] = sum;
-    }
-  }
-
-  return out_matrix;
+  TODO("impl mat4_mult");
+  // mat4 out_matrix = mat4_ident();
+
+  // for (i32 row = 0; row < 4; row++) {
+  //   for (i32 col = 0; col < 4; col++) {
+  //     f32 sum = 0;
+  //     for (i32 i = 0; i < 4; i++) {
+  //       // column-major: first matrix columns × second matrix rows
+  //       sum += lhs.data[row + i * 4] * rhs.data[i + col * 4];
+  //     }
+  //     out_matrix.data[row + col * 4] = sum;
+  //   }
+  // }
+
+  // return out_matrix;
 }
 
 mat4 mat4_perspective(f32 fov_radians, f32 aspect_ratio, f32 near_z, f32 far_z) {
-  f32 half_tan_fov = tanf(fov_radians * 0.5f);
-  mat4 out_matrix = { .data = { 0 } };
-  out_matrix.data[0] = 1.0f / (aspect_ratio * half_tan_fov);
-  out_matrix.data[5] = 1.0f / half_tan_fov;
-  out_matrix.data[10] = -((far_z + near_z) / (far_z - near_z));
-  out_matrix.data[11] = -1.0f;
-  out_matrix.data[14] = -((2.0f * far_z * near_z) / (far_z - near_z));
-  return out_matrix;
+  TODO("impl mat4_perspective");
+  // f32 half_tan_fov = tanf(fov_radians * 0.5f);
+  // mat4 out_matrix = { .data = { 0 } };
+  // out_matrix.data[0] = 1.0f / (aspect_ratio * half_tan_fov);
+  // out_matrix.data[5] = 1.0f / half_tan_fov;
+  // out_matrix.data[10] = -((far_z + near_z) / (far_z - near_z));
+  // out_matrix.data[11] = -1.0f;
+  // out_matrix.data[14] = -((2.0f * far_z * near_z) / (far_z - near_z));
+  // return out_matrix;
 }
 
 mat4 mat4_look_at(vec3 position, vec3 target, vec3 up) {
-  mat4 out_matrix;
-  vec3 z_axis;
-  z_axis.x = target.x - position.x;
-  z_axis.y = target.y - position.y;
-  z_axis.z = target.z - position.z;
-
-  z_axis = vec3_normalise(z_axis);
-  vec3 x_axis = vec3_normalise(vec3_cross(z_axis, up));
-  vec3 y_axis = vec3_cross(x_axis, z_axis);
-
-  out_matrix.data[0] = x_axis.x;
-  out_matrix.data[1] = y_axis.x;
-  out_matrix.data[2] = -z_axis.x;
-  out_matrix.data[3] = 0;
-  out_matrix.data[4] = x_axis.y;
-  out_matrix.data[5] = y_axis.y;
-  out_matrix.data[6] = -z_axis.y;
-  out_matrix.data[7] = 0;
-  out_matrix.data[8] = x_axis.z;
-  out_matrix.data[9] = y_axis.z;
-  out_matrix.data[10] = -z_axis.z;
-  out_matrix.data[11] = 0;
-  out_matrix.data[12] = -vec3_dot(x_axis, position);
-  out_matrix.data[13] = -vec3_dot(y_axis, position);
-  out_matrix.data[14] = vec3_dot(z_axis, position);
-  out_matrix.data[15] = 1.0f;
-
-  return out_matrix;
+  TODO("impl mat4_lookat");
+  // mat4 out_matrix;
+  // vec3 z_axis;
+  // z_axis.x = target.x - position.x;
+  // z_axis.y = target.y - position.y;
+  // z_axis.z = target.z - position.z;
+
+  // z_axis = vec3_normalise(z_axis);
+  // vec3 x_axis = vec3_normalise(vec3_cross(z_axis, up));
+  // vec3 y_axis = vec3_cross(x_axis, z_axis);
+
+  // out_matrix.data[0] = x_axis.x;
+  // out_matrix.data[1] = y_axis.x;
+  // out_matrix.data[2] = -z_axis.x;
+  // out_matrix.data[3] = 0;
+  // out_matrix.data[4] = x_axis.y;
+  // out_matrix.data[5] = y_axis.y;
+  // out_matrix.data[6] = -z_axis.y;
+  // out_matrix.data[7] = 0;
+  // out_matrix.data[8] = x_axis.z;
+  // out_matrix.data[9] = y_axis.z;
+  // out_matrix.data[10] = -z_axis.z;
+  // out_matrix.data[11] = 0;
+  // out_matrix.data[12] = -vec3_dot(x_axis, position);
+  // out_matrix.data[13] = -vec3_dot(y_axis, position);
+  // out_matrix.data[14] = vec3_dot(z_axis, position);
+  // out_matrix.data[15] = 1.0f;
+
+  // return out_matrix;
 }