adding file doc comments

1 files changed, 14 insertions, 4 deletions

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