//! # Thinking about matrix layout
//!
//! So, you're programming your game's mathematics. You've gotten to the point where you're using
//! matrices to do transformations quickly, and you're trying to figure out where to put the numbers
//! on the screen so that everything works out correctly. This, somehow, has ended up being confusing
//! and you're trying to figure out why you can't just lay out your numbers in the source code the
//! same way they're laid out in your linear algebra textbook or whatever webpage you found that
//! explains matrices. This explanation will attempt to make sense of that.
//!
//! Say you have a 3D vector at point `(0x, 1y, 2z)`. If you were a mathematician, you would write
//! that out as a vertical box, like this:
//!
//! ```text
//! ___
//! |0|
//! |1|
//! |2|
//! ‾‾‾
//! ```
//!
//! However, you're reading the documentation for a Rust crate, so it's not much of a stretch to
//! assume that you're a programmer, not a mathematician. With that in mind, if you wanted to write
//! out that vector in your source code (assuming you're using our handy [`GVector3`] type), you'd
//! probably do so like this:
//!
//! ```rust
//! let vector = GVector3::new(0, 1, 2);
//! ```
//!
//! In memory, that corresponds to an array of three numbers:
//!
//! ```rust
//! let vector_array = [0, 1, 2];
//! ```
//!
//! Let's return to the (admittedly debunked) assumption that you're a mathematician. Mathematician
//! you may be aware of the fact that vectors are just single-column matrices. Indeed, you can form
//! a matrix by just taking a bunch of vectors (I've commonly heard these referred to as "basis
//! vectors" in this context):
//!
//! ```text
//! ___ ___ ___
//! |0| |2| |4|
//! |1| |3| |5|
//! ‾‾‾ ‾‾‾ ‾‾‾
//! ```
//!
//! and gluing them together:
//!
//! ```text
//! _______
//! |0 2 4|
//! |1 3 5|
//! ‾‾‾‾‾‾‾
//! ```
//!
//! Just like that, we've created a `2x3` matrix via judicious application of Elmer's. (I'll note
//! that "gluing vectors together" isn't a mathematically rigorous operation. However, I don't have
//! a formal background in math, so I don't know anyone who will complain at me for doing that.)
//! Conceptually, we can think of that as an array of vectors:
//!
//! ```text
//! ___
//! |0|
//! |1|
//! ‾‾‾
//! ___
//! |2|
//! |3|
//! ‾‾‾
//! ___
//! |4|
//! |5|
//! ‾‾‾
//! ```
//!
//! Re-donning our programmer hats, we would express an array of arrays like this:
//!
//! ```rust
//! let matrix_array = [
//!     [0, 1],
//!     [2, 3],
//!     [4, 5],
//! ];
//! ```
//!
//! Or, with one of Gullery's matrix types, like this:
//!
//! ```rust
//! let matrix = GLMatrix2r3c {
//!     x: GLVector2::new(0, 1),
//!     y: GLVector2::new(2, 3),
//!     z: GLVector2::new(4, 5),
//! }
//! ```
//!
//! We've recreated the mismatch. This style of layout is referred to as "column major", and most
//! Rust mathematics libraries (and this crate) use that convention. Unfortunately, it means that
//! our source code layout doesn't correspond with mathematical layout. Hopefully, understanding
//! that will help you avoid mixing up your numbers in your code.
//!
//! ----
//!
//! As an aside, you may be aware of the fact that the size of a matrix is written as
//! `rows x columns`. Indeed, we used that notation above to denote the size of our 2 row, 3 column
//! matrix above. GLSL doesn't do that. Instead, it writes matrix size as `columns x rows`, such
//! that our previous `2x3` matrix would have a GLSL type of `mat3x2`. The only sensible reason I
//! can think of for this is that God hates OpenGL programmers, and He worked his best to make
//! matricies as confusing as possible. This is consistent with the rest of OpenGL's raw API, so
//! I'd consider that relatively plausible.
//!
//! Good luck.