Tidy up docs, add Mat3-Mat4 and Vec3-Vec4 functions

Author: matthew-e-brown

gloog-core/src/funcs/mod.rs

@@ -1,8 +1,8 @@
-mod buffers;
-mod debug;
-mod shaders;
-mod uniforms;
-mod vertex;
+pub(crate) mod buffers;
+pub(crate) mod debug;
+pub(crate) mod shaders;
+pub(crate) mod uniforms;
+pub(crate) mod vertex;
 
 use std::ffi::CStr;
 

gloog-core/src/funcs/uniforms.rs

@@ -46,7 +46,7 @@ impl GLContext {
     ///
     /// ```
     /// # const program: ProgramID = ProgramID::new(0);
-    /// # fn perspective(_fov_deg: f32, _aspect: f32, _near_clip: f32, _far_clip: f32) {}
+    /// # fn perspective(_fov_deg: f32, _aspect: f32, _near_clip: f32, _far_clip: f32) -> Mat4 { Mat4::IDENTITY }
     ///
     /// fn draw_loop(gl: &GLContext) {
     ///     // --- snip ---
@@ -203,7 +203,7 @@ macro_rules! impl_uniform {
             type PtrType = GLfloat; // Only `fv` matrices
 
             fn get_ptr(&self) -> *const Self::PtrType {
-                self.as_ptr()
+                self.as_ptr().cast()
             }
 
             fn count(&self) -> GLsizei {
@@ -276,6 +276,10 @@ impl_uniform!(matrix, Mat2, uniform_matrix_2fv);
 impl_uniform!(matrix, Mat3, uniform_matrix_3fv);
 impl_uniform!(matrix, Mat4, uniform_matrix_4fv);
 
+impl_uniform!(matrix, [[f32; 2]; 2], uniform_matrix_2fv);
+impl_uniform!(matrix, [[f32; 3]; 3], uniform_matrix_3fv);
+impl_uniform!(matrix, [[f32; 4]; 4], uniform_matrix_4fv);
+
 
 /// Because all uniforms make use of the `Uniform*v` functions, it can be safely implemented it for all slices by simply
 /// casting the pointer to the slice.

gloog-core/src/lib.rs

@@ -6,6 +6,7 @@ pub mod types;
 pub(crate) use crate::macros::*;
 use crate::raw::GLPointers;
 pub use crate::raw::InitFailureMode;
+pub use crate::funcs::uniforms::Uniform;
 use crate::types::DebugMessage;
 
 

gloog-core/src/raw.rs

@@ -132,7 +132,7 @@ pub mod types {
 }
 
 
-/// How [`GLPointers::init`] should behave when a function pointer cannot be loaded.
+/// How [`GLPointers::load`] should behave when a function pointer cannot be loaded.
 ///
 /// Be careful with using options other than `Abort`. They should be considered `unsafe`. See their documentation for
 /// more information.
@@ -144,7 +144,7 @@ pub enum InitFailureMode {
     /// As far as Rust safety guarantees go, **this is the only safe option.** All other options will result in
     /// `GLPointers` being partially uninitialized, which violates Rust's initialization invariant.
     Abort,
-    /// When a function pointer fails to load, a warning will [be logged][https://docs.rs/log] and initialization will
+    /// When a function pointer fails to load, a warning will [be logged](https://docs.rs/log) and initialization will
     /// continue. The function pointer will be left as [`null`][std::ptr::null] instead.
     ///
     /// **This option is unsafe.** If a pointer fails to load, [`GLPointers`] will be left partially uninitialized,

gloog-math/src/base/matrix/mat3.rs

@@ -1,6 +1,6 @@
 use bytemuck::{Pod, Zeroable};
 
-use crate::Vec3;
+use crate::{Mat4, Vec3};
 
 /// A 3×3 matrix of 32-bit floats.
 ///
@@ -76,6 +76,17 @@ impl Mat3 {
         )
     }
 
+    /// Creates a [`Mat3`] from a [`Mat4`] by trimming out the last row and column.
+    #[inline]
+    #[rustfmt::skip]
+    pub fn from_mat4(mat: &Mat4) -> Mat3 {
+        Mat3::new(
+            mat[[0,0]], mat[[0,1]], mat[[0,2]],
+            mat[[1,0]], mat[[1,1]], mat[[1,2]],
+            mat[[2,0]], mat[[2,1]], mat[[2,2]],
+        )
+    }
+
     /// Computes the determinant of this matrix.
     pub fn det(&self) -> f32 {
         // See equation 1.94 and 1.95 (p. 47/48) [Foundations of Game Development, Vol. 1]

gloog-math/src/base/matrix/mat4.rs

@@ -1,6 +1,6 @@
 use bytemuck::{Pod, Zeroable};
 
-use crate::{Vec3, Vec4};
+use crate::{Mat3, Vec3, Vec4};
 
 
 /// A 4×4 matrix of 32-bit floats.
@@ -90,6 +90,17 @@ impl Mat4 {
         )
     }
 
+    /// Creates a [`Mat3`] by trimming out the last row and column of this matrix.
+    #[inline]
+    #[rustfmt::skip]
+    pub fn to_mat3(&self) -> Mat3 {
+        Mat3::new(
+            self[[0,0]], self[[0,1]], self[[0,2]],
+            self[[1,0]], self[[1,1]], self[[1,2]],
+            self[[2,0]], self[[2,1]], self[[2,2]],
+        )
+    }
+
     /// Function for accessing the columns of this 4D matrix as 3D vectors, getting the bottom row directly, and
     /// calculating the intermediate vectors `s`, `t`, `u`, and `v`.
     ///

gloog-math/src/base/vector/vec2.rs

@@ -21,7 +21,7 @@ impl Vec2 {
     pub const UNIT_X: Vec2 = Vec2::new(1.0, 0.0);
     pub const UNIT_Y: Vec2 = Vec2::new(0.0, 1.0);
 
-    /// Creates a new [`Vector3D`] out of this vector's `x` and `y` components and a given `z` component.
+    /// Creates a new [`Vec3`] out of this vector's `x` and `y` components and a given `z` component.
     #[inline]
     pub const fn to3(&self, z: f32) -> Vec3 {
         Vec3::new(self.x, self.y, z)

gloog-math/src/base/vector/vec3.rs

@@ -44,17 +44,25 @@ impl Vec3 {
 
     // --------------------------------------------------------------------------------------------
 
-    /// Creates a new [`Vector4D`] from this vector's `x`, `y`, and `z` components and a given `w` component.
+    /// Creates a new [`Vec4`] from this vector's `x`, `y`, and `z` components and a given `w` component.
     ///
-    /// See also: [`Vector4D::from3`].
+    /// See also: [`Vec4::from_vec3`].
     #[inline]
-    pub const fn to4(&self, w: f32) -> Vec4 {
+    pub const fn to_vec4(&self, w: f32) -> Vec4 {
         Vec4::new(self.x, self.y, self.z, w)
     }
 
-    /// Creates a new [`Vector3D`] from a [`Vector2D`] and a float.
+    /// Creates a new [`Vec3`] out of a [`Vec4`] by ignoring its `w` component.
+    ///
+    /// See also: [`Vec4::to_vec3`].
+    #[inline]
+    pub const fn from_vec4(vec: Vec4) -> Vec3 {
+        Vec3::new(vec.x, vec.y, vec.z)
+    }
+
+    /// Creates a new [`Vec3`] from a [`Vec2`] and a float.
     #[inline]
-    pub const fn from2(xy: Vec2, z: f32) -> Vec3 {
+    pub const fn from_vec2(xy: Vec2, z: f32) -> Vec3 {
         Vec3::new(xy.x, xy.y, z)
     }
 }

gloog-math/src/base/vector/vec4.rs

@@ -27,13 +27,19 @@ impl Vec4 {
 
     // --------------------------------------------------------------------------------------------
 
-    /// Creates a new [`Vector4D`] out of a [`Vector3D`]'s `x`, `y`, and `z` components and a given `w` component.
+    /// Creates a new [`Vec4`] out of a [`Vec3`]'s `x`, `y`, and `z` components and a given `w` component.
     ///
-    /// See also: [`Vector3D::to4`].
+    /// See also: [`Vec3::to_vec4`].
     #[inline]
-    pub const fn from3(xyz: Vec3, w: f32) -> Vec4 {
+    pub const fn from_vec3(xyz: Vec3, w: f32) -> Vec4 {
         Vec4::new(xyz.x, xyz.y, xyz.z, w)
     }
+
+    /// Creates a new [`Vec3`] by ignoring this vector's `w` component.
+    #[inline]
+    pub const fn to_vec3(&self) -> Vec3 {
+        Vec3::new(self.x, self.y, self.z)
+    }
 }
 
 impl FromStr for Vec4 {

gloog/src/lib.rs

@@ -18,7 +18,7 @@ pub struct SceneObject {
     /// in, the _highest_ byte of the ID becomes the 4th float, alpha. Additionally, we subtract our values from 255 so
     /// they start at 1.0 and transition downwards, giving us brighter colours.
     ///
-    /// ```rust,ignore
+    /// ```text
     /// let id: u32 = 0xAA_RR_GG_BB;
     /// let id = Vec4 {
     ///     w: (255 - 0xAA) / 255,

gloog/src/loader/obj/mod.rs

@@ -5,9 +5,9 @@
 //!
 //! For future reference, here are some of the documents I used for the OBJ and MTL specs:
 //!
-//! - https://www.uhu.es/francisco.moreno/gii_rv/practicas/practica08/OBJ_SPEC.PDF
-//! - also: https://paulbourke.net/dataformats/obj/ (missing math section)
-//! - https://paulbourke.net/dataformats/mtl/
+//! - <https://www.uhu.es/francisco.moreno/gii_rv/practicas/practica08/OBJ_SPEC.PDF>
+//! - also: <https://paulbourke.net/dataformats/obj/> (missing math section)
+//! - <https://paulbourke.net/dataformats/mtl/>
 
 mod error;
 mod mtl;

src/bin/model-test/main.rs

@@ -21,7 +21,7 @@ use gloog_core::types::{
     VertexAttribType,
 };
 use gloog_core::{GLContext, InitFailureMode};
-use gloog_math::{Mat3, Mat4, Vec3, Vec4};
+use gloog_math::{Mat4, Vec3, Vec4};
 use log::{debug, info, log};
 
 
@@ -90,7 +90,7 @@ fn run(model_path: String) -> Result<(), Box<dyn Error>> {
             gl.uniform(uniforms.lights[i].ambient, &light.ambient);
             gl.uniform(uniforms.lights[i].specular, &light.specular);
 
-            let lp4_ws = Vec4::from3(light.position, 1.0);
+            let lp4_ws = Vec4::from_vec3(light.position, 1.0);
             let lp4_vs = view_matrix * lp4_ws;
             let lp3_vs = Vec3::new(lp4_vs[0], lp4_vs[1], lp4_vs[2]);
 
@@ -217,18 +217,10 @@ impl<'gl, 'a> Thingy<'gl, 'a> {
         let &Self { gl, model, vao, .. } = self;
 
         let model_matrix = model_matrix(&self.pos, &self.rot, &self.scl);
-        let normal_matrix = (view_matrix * model_matrix).inverse().transpose();
-
-        // TODO: actually write a method to trim a Mat4 down to a Mat3 (and Vec4->Vec3 too lol)
-        #[rustfmt::skip]
-        let norm_matrix = Mat3::new(
-            normal_matrix[[0,0]], normal_matrix[[0,1]], normal_matrix[[0,2]],
-            normal_matrix[[1,0]], normal_matrix[[1,1]], normal_matrix[[1,2]],
-            normal_matrix[[2,0]], normal_matrix[[2,1]], normal_matrix[[2,2]],
-        );
+        let normal_matrix = (view_matrix * model_matrix).inverse().transpose().to_mat3();
 
         gl.uniform(uniforms.matrix.model, &model_matrix);
-        gl.uniform(uniforms.matrix.normal, &norm_matrix);
+        gl.uniform(uniforms.matrix.normal, &normal_matrix);
 
         gl.bind_vertex_array(vao);
 

src/bin/teapot-test/light.rs

@@ -191,9 +191,8 @@ impl<'gl> Light<'gl> {
         gl.uniform(uniforms.ambient, &self.ambient);
         gl.uniform(uniforms.specular, &self.specular);
 
-        let position4 = Vec4::from3(self.position, 1.0);
-        let vs_position = view_matrix * position4;
-        let vs_position = Vec3::new(vs_position.x, vs_position.y, vs_position.z);
+        let position4 = self.position.to_vec4(1.0);
+        let vs_position = (view_matrix * position4).to_vec3();
         gl.uniform(uniforms.position, &vs_position);
     }
 

src/bin/teapot-test/main.rs

@@ -371,7 +371,7 @@ fn handle_input(delta_time: f32, keys: &KeyStatus, camera_pos: &mut Vec3, camera
             };
 
             let r_mat = axis_angle_matrix(spin_speed, axis);
-            let r_cam = r_mat * Vec4::from3(*camera_pos, 1.0);
+            let r_cam = r_mat * Vec4::from_vec3(*camera_pos, 1.0);
             *camera_pos = Vec3::new(r_cam.x, r_cam.y, r_cam.z);
         } else if let Key::Up | Key::Down = key {
             let mut zoom_speed = CAMERA_ZOOM_SPEED * delta_time;

src/bin/teapot-test/teapot.rs

@@ -10,7 +10,7 @@ use gloog_core::types::{
     VertexAttribType,
 };
 use gloog_core::GLContext;
-use gloog_math::{Mat3, Mat4, Vec3, Vec4};
+use gloog_math::{Mat4, Vec3, Vec4};
 use rand::distributions::Uniform;
 use rand::Rng;
 
@@ -217,14 +217,7 @@ impl<'gl> Teapot<'gl> {
 
         let ctm = trans_matrix(self.position) * rotate_matrix(self.rotation) * scale_matrix(self.scale);
         let mv_matrix = view_matrix * ctm;
-
-        let n = mv_matrix.inverse().transpose();
-        #[rustfmt::skip]
-        let norm_matrix = Mat3::new(
-            n[[0,0]], n[[0,1]], n[[0,2]],
-            n[[1,0]], n[[1,1]], n[[1,2]],
-            n[[2,0]], n[[2,1]], n[[2,2]],
-        );
+        let norm_matrix = mv_matrix.inverse().transpose().to_mat3();
 
         gl.uniform(info.u_model_view_matrix, &mv_matrix);
         gl.uniform(info.u_normal_matrix, &norm_matrix);