\h1\Using Matrices\h1\
\lo \
\-\ \url #initialization \Initialization\ url\\list switch\
\--\ \url #initialization-with-no-arguments \with no arguments\ url\
\--\ \url #initialization-with-a-single-number \with single number\ url\
\--\ \url #initialization-with-a-quaternion \with quaternion\ url\
\--\ \url #initializing-the-matrix-diagonal-with-custom-values \with custom diagonal values\ url\
\--\ \url #initializing-all-components-with-numbers \all components with numbers\ url\
\--\ \url #copying-a-matrix \copying a matrix\ url\
\--\ \url #constructing-matrices-from-vectors \with vectors\ url\
\--\ \url #lists-and-other-iterables \Lists (and other iterables)\ url\
\--\ \url #objects-that-support-the-buffer-protocol-numpy-bytes \Buffer protocol (numpy, bytes)\ url\\list switch\
\-\ \url #methods \Methods\ url\\list switch\
\--\ \url #the-copy-protocol \The copy protocol\ url\
\--\ \url #pickling \Pickling\ url\
\--\ \url #to-list--tuple \To list / tuple\ url\
\--\ \url #to-and-from-bytes \To and from bytes\ url\\list switch\
\-\ \url #operators \Operators\ url\\list switch\
\--\ \url #add--operator \add\ url\
\--\ \url #sub--operator \sub\ url\
\--\ \url #mul--operator \mul\ url\
\--\ \url #matmul--operator \matmul\ url\
\--\ \url #div--operator \div\ url\
\--\ \url #len \len\ url\
\--\ \url #getitem-and-setitem--operator \getitem and setitem\ url\
\--\ \url #contains-in-operator \contains\ url\
\--\ \url #richcompare-eg--operator \richcompare\ url\
\--\ \url #iter \iter\ url\
\--\ \url #hash\hash\url\
\ list\
\h2 \Initialization\ h2\
Matrices can be constructed in quite a few different ways.
\h4 \Initialization with no arguments\ h4\
Initializing a matrix without any additional arguments will return an identity matrix, meaning that it's values are set to \code \1\ code\ where column and row indices are equal and set to \code\0\code\ otherwise.  
This results in a diagonal line of ones from top left to bottom right.  
Example:
\code Python \
>>> print(glm.mat2())
[            1 ][            0 ]
[            0 ][            1 ]

>>> print(glm.mat4())
[            1 ][            0 ][            0 ][            0 ]
[            0 ][            1 ][            0 ][            0 ]
[            0 ][            0 ][            1 ][            0 ]
[            0 ][            0 ][            0 ][            1 ]

>>> print(glm.mat2x4())
[            1 ][            0 ]
[            0 ][            1 ]
[            0 ][            0 ]
[            0 ][            0 ]
\code\
\h4 \Initialization with a single number\ h4\
Initializing a matrix with a single number returns a matrix similar to the identity matrices shown above.  
The only difference is that instead of setting equal column and row indices to \code\1\code\, they're set to the provided number.  
Example:
\code Python \
>>> print(glm.mat2(3))
[            3 ][            0 ]
[            0 ][            3 ]

>>> print(glm.mat4(0))
[            0 ][            0 ][            0 ][            0 ]
[            0 ][            0 ][            0 ][            0 ]
[            0 ][            0 ][            0 ][            0 ]
[            0 ][            0 ][            0 ][            0 ]

>>> print(glm.mat2x4(1.5))
[          1.5 ][            0 ]
[            0 ][          1.5 ]
[            0 ][            0 ]
[            0 ][            0 ]
\code\
\h4 \Initialization with a quaternion\ h4\
Initializing a 3x3 or 4x4 matrix with a quaternion yields a matrix with the same basic rotational properties as the quaternion.
Example:
\code Python \
>>> q = glm.quat(glm.vec3(0, 0, glm.radians(90))) # rotate 90 degrees around the Z axis
>>> print(glm.mat4(q))
[  5.96046e-08 ][           -1 ][            0 ][            0 ]
[            1 ][  5.96046e-08 ][            0 ][            0 ]
[            0 ][            0 ][            1 ][            0 ]
[            0 ][            0 ][            0 ][            1 ]

>>> print(glm.rotate(glm.radians(90), glm.vec3(0, 0, 1)))
[ -4.37114e-08 ][           -1 ][            0 ][            0 ]
[            1 ][ -4.37114e-08 ][            0 ][            0 ]
[            0 ][            0 ][            1 ][            0 ]
[            0 ][            0 ][            0 ][            1 ]
\code\
\h4 \Initializing the matrix diagonal with custom values\ h4\
You can initialize a matrix' diagonal with custom values.
Example:
\code Python \
>>> print(glm.mat2(1, 2))
[            1 ][            0 ]
[            0 ][            2 ]

>>> print(glm.mat4(1, 2, 3, 4))
[            1 ][            0 ][            0 ][            0 ]
[            0 ][            2 ][            0 ][            0 ]
[            0 ][            0 ][            3 ][            0 ]
[            0 ][            0 ][            0 ][            4 ]

>>> print(glm.mat2x4(1, 2))
[            1 ][            0 ]
[            0 ][            2 ]
[            0 ][            0 ]
[            0 ][            0 ]
\code\
i.e. a \code\matNxM\code\ matrix can be initialized with \code\int(sqrt(N * M))\code\ numbers.
\h4 \Initializing all components with numbers\ h4\
A matrix \code\matNxM\code\ can be initialized with \i\N\i\ x \i\M\i\ numbers, which will be copied (or may be converted) to their respective components.  
Example:
\code Python \
>>> print(glm.mat2(1, 2, 3, 4))
[            1 ][            3 ]
[            2 ][            4 ]

>>> print(glm.mat4(*range(16)))
[            0 ][            4 ][            8 ][           12 ]
[            1 ][            5 ][            9 ][           13 ]
[            2 ][            6 ][           10 ][           14 ]
[            3 ][            7 ][           11 ][           15 ]
\code\
\h4 \Copying a matrix\ h4\
A copy of a matrix can be obtained by initializing a matrix with an instance of a matrix.  
i.e. \code\glm.mat2(glm.mat2(5, 2, 4, 3))\code\ returns matrix \code\((5, 2), (4, 3))\code\  
This is what's known as the copy constructor.
\h4 \Initializing matrices with other matrices\ h4\
You can initialize any matrix with another matrix (as long as they have the same datatype or size).  
Any values that don't fit into the new matrix are discarded and any values that aren't filled by the supplied matrix are padded up with values from the respective identity matrix.  
Example:  
\code Python \
>>> print(glm.mat4( glm.mat2(9, 8, 7, 6) ))
[            9 ][            7 ][            0 ][            0 ]
[            8 ][            6 ][            0 ][            0 ]
[            0 ][            0 ][            1 ][            0 ]
[            0 ][            0 ][            0 ][            1 ]

>>> m44 = glm.mat4(*range(16))
>>> print(m44)
[            0 ][            4 ][            8 ][           12 ]
[            1 ][            5 ][            9 ][           13 ]
[            2 ][            6 ][           10 ][           14 ]
[            3 ][            7 ][           11 ][           15 ]

>>> print(glm.mat2(m44))
[            0 ][            4 ]
[            1 ][            5 ]

>>> m32 = glm.mat3x2(6, 5, 4, 3, 2, 1)
>>> print(m32)
[            6 ][            4 ][            2 ]
[            5 ][            3 ][            1 ]

>>> print(glm.mat2x3(m32))
[            6 ][            4 ]
[            5 ][            3 ]
[            0 ][            0 ]

>>> print(glm.mat3(m32))
[            6 ][            4 ][            2 ]
[            5 ][            3 ][            1 ]
[            0 ][            0 ][            1 ]

>>> print(glm.imat2(glm.dmat2(7.9)))
[            7 ][            0 ]
[            0 ][            7 ]
\code\
\h4 \Constructing matrices from vectors\ h4\
You can construct a \code \matNxM\ code\ from \i\N\i\ vectors of length \i\M\i\, if they share the same datatype.
Example:
\code Python \
>>> print(glm.mat2( glm.vec2(1, 2), glm.vec2(3, 4) )) # 2 vectors of length 2
[            1 ][            3 ]
[            2 ][            4 ]

>>> print(glm.mat2x4( glm.vec4(1, 2, 3, 4), glm.vec4(5, 6, 7, 8) )) # 2 vectors of length 4
[            1 ][            5 ]
[            2 ][            6 ]
[            3 ][            7 ]
[            4 ][            8 ]

>>> print(glm.mat4x2( glm.vec2(1, 2), glm.vec2(3, 4), glm.vec2(5, 6), glm.vec2(7, 8) )) # 4 vectors of length 2
[            1 ][            3 ][            5 ][            7 ]
[            2 ][            4 ][            6 ][            8 ]
\ code\

\h3 \Lists (and other iterables)\ h3\
Instead of using matrices, you can use matrix-like lists / tuples in most cases.
For example, you can initialize a matrix with a matrix-like tuple:
\code Python \
>>> print(glm.mat2( ((1, 2), (3, 4)) ))
[            1 ][            3 ]
[            2 ][            4 ]
\ code\ 
Or use it on one handside of a numeric operator:
\code Python \
>>> m22 = glm.mat2()
>>> print(m22)
[            1 ][            0 ]
[            0 ][            1 ]

>>> print(m22 + ((4, 3), (2, 1)))
[            5 ][            2 ]
[            3 ][            2 ]
\ code\
It is also accepted by most functions:
\code Python \
>>> print(glm.inverse( ((1,2),(3,4)) ))
[           -2 ][          1.5 ]
[            1 ][         -0.5 ]
\ code\ 

\h3 \Objects that support the buffer protocol (numpy, bytes)\ h3\
A few objects in Python support a functionality called the buffer protocol.  
One such example would be the Python \code\bytes\code\ type or \code\numpy.array\code\.  
PyGLM also supports this protocol and thus can be converted to or from any other object that supports it, granted it's in a fitting format.  
Examples:
\code Python \
>>> narr = numpy.array(glm.mat4())
>>> print(narr)
[[1. 0. 0. 0.]
 [0. 1. 0. 0.]
 [0. 0. 1. 0.]
 [0. 0. 0. 1.]]
 
>>> print(glm.mat4(narr))
[            1 ][            0 ][            0 ][            0 ]
[            0 ][            1 ][            0 ][            0 ]
[            0 ][            0 ][            1 ][            0 ]
[            0 ][            0 ][            0 ][            1 ]
\ code\

\i\Note: objects that use the buffer protocol may request a reference instead of a copy of the object, meaning that if you change the 'copy', you'll also change the original.\i\

\h2 \Methods\ h2\
Any matrix type implements the following methods:

\h3 \Length\ h3\
You can acquire the length of a matrix with the \code \length()\ code\ method.
It will give you the same result as the builtin \code \len(<matrix>)\ code\ method.

\h3 \The copy protocol\ h3\
Matrices support the copy protocol (see \url https://docs.python.org/3/library/copy.html \here\ url\).  
You can use \code\copy.copy(<matrix>)\code\ or \code\copy.deepcopy(<matrix>)\code\ to get a copy of a matrix.

\h3\Pickling\h3\
Matrices support \url https://docs.python.org/3/library/pickle.html#module-interface \pickling\url\ (as of PyGLM 2.0.0), which is Python's serialization method.

\h3 \To list / tuple\ h3\
Any matrix type has a \code\to_list()\code\ and a \code\to_tuple()\code\ function, which returns the matrix' data represented as a list or tuple respectively.
Example:
\code Python \
>>> print(glm.mat4().to_list())
[[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]]

>>> print(glm.mat4().to_tuple())
((1.0, 0.0, 0.0, 0.0), (0.0, 1.0, 0.0, 0.0), (0.0, 0.0, 1.0, 0.0), (0.0, 0.0, 0.0, 1.0))
\ code\


\h3\To and from bytes\h3\
All matrices have a \code\to_bytes()\code\ and a \code\from_bytes()\code\ method, which allows for conversion of the matrix' data to and from bytes strings.

\h2 \Operators\ h2\
Matrix types support a bunch of operators.
\h3 \add (\code\+\code\ operator)\ h3\
Matrices support addition with other matrices and numbers.
Only matrices of the same shape and type can be used.
\code Python \
sum1 = mat2(1, 2, 3, 4) + mat2(1, 0, 1, 0) # returns mat2(2, 2, 4, 4)
sum2 = mat2(1, 2, 3, 4) + 4                # returns mat2(5, 6, 7, 8)
\code\
Note: Only square matrices allow for left side addition of numbers
\h3 \sub (\code\-\code\ operator)\ h3\
Matrices support subtraction with other matrices and numbers.  
\code Python \
diff1 = mat2(1, 2, 3, 4) - mat2(1, 0, 1, 0) # returns mat2(0, 2, 2, 4)
diff2 = mat2(1, 2, 3, 4) - 4                # returns mat2(-3, -2, -1, 0)
\code\
Note: Only square matrices allow for left side subtration of numbers
\h3 \mul (\code\*\code\ operator)\ h3\
Matrices support multiplication with vectors, other matrices and numbers.  
Multiplying a matrix with a number multiplies each component with that number.
\code Python \
prod = mat2(1, 2, 3, 4) * 4 # returns mat2(4, 8, 12, 16)
\code\
Multiplying a matrix with a vector is a bit more complex.
If you have a \code \matNxM\ code\ matrix, you can either
left-side multiply it with a length \i\M\i\ vector and get a length \i\N\i\ vector in return
\code Python \
prod1 = vec3(7, 8, 9) * mat2x3((1, 2, 3), (4, 5, 6))
# returns vec2(
#      7 * 1 + 8 * 2 + 9 * 3,
#      7 * 4 + 8 * 5 + 9 * 6
#    )
#    = vec2(50, 122)
prodx = vec4(a, b, c, d) * mat3x4((m00, m01, m02, m03), (m10, m11, m12, m13), (m20, m21, m22, m23))
# returns vec3(
#      a * m00 + b * m01 + c * m02 + d * m03,
#      a * m10 + b * m11 + c * m12 + d * m13,
#      a * m20 + b * m21 + c * m22 + d * m23
#    )
\ code\
or right-side multiply it with a length \i\N\i\ vector and get a length \i\M\i\ vector in return.
\code Python \
prod1 = mat2x3((1, 2, 3), (4, 5, 6)) * vec2(7, 8)
# returns vec3(
#      7 * 1 + 8 * 4,
#      7 * 2 + 8 * 5,
#      7 * 3 + 8 * 6
#    )
#    = vec3(39, 54, 69)
prodx = mat3x4((m00, m01, m02, m03), (m10, m11, m12, m13), (m20, m21, m22, m23)) * vec3(a, b, c)
# returns vec4(
#      a * m10 + b * m10 + c * m20,
#      a * m11 + b * m11 + c * m21,
#      a * m12 + b * m12 + c * m22,
#      a * m13 + b * m13 + c * m23
#    )
\ code\
For multiplication of square matrices with vectors using homogenous coordinates, PyGLM provides a shorthand:
\code Python \
m = rotate(radians(90), vec3(0, 1, 0)) # creates a 4x4 rotation matrix
v = vec3(1, 2, 3) # some 3D vector

# This is what you would normally have to do to apply the rotation to v:

v_rotated = vec3(m * vec4(v, 1)) # returns vec3( 3, 2, -1 )

# This is the shorthand:

v_rotated = m * v # returns vec3( 3, 2, -1 )
\ code\
Now for the most complex part.
Matrix-matrix multiplication.
You can only multiply a \code\matAxB\code\ with a \code\matCxA\code\ matrix and it will return a \code\matCxB\code\ matrix.
\code Python \
mat2x3() * mat4x2() # returns a mat4x3
mat3x2() * mat2x4() # error - these matrices are incompatible
mat2x4() * mat2x4() # error - these matrices are incompatible
mat2x2() * mat2x2() # returns a mat2x2
mat3x3() * mat2x3() # returns a mat2x3
\ code\
The actual computation is a combination of multiplication and addition.
Okay, so this may be a bit difficult to grasp at first:
Each component of the resulting matrix is the sum of each component of the \i\first\i\ matrix' respective \i\row\i\ 
multiplied by the components of the \i\second\i\ matrix' respective \i\column\i\.
\b\Keep in mind, that glm's columns and rows are in the opposite order\b\, so this gets even more complicated.
Lets try to visualize it using an example:
\code Python \
>>> m24 = glm.mat2x4(1, 2, 3, 4, 5, 6, 7, 8)
>>> print(m24)
[            1 ][            5 ]
[            2 ][            6 ]
[            3 ][            7 ]
[            4 ][            8 ]
>>> m22 = glm.mat2(4, 3, 2, 1)
>>> print(m22)
[            4 ][            2 ]
[            3 ][            1 ]
>>> print(m24 * m22)
[           19 ][            7 ]
[           26 ][           10 ]
[           33 ][           13 ]
[           40 ][           16 ]

result = mat2x4(
		(
            m24[0, 0] * m22[0, 0] + m24[1, 0] * m22[0, 1],
            m24[0, 1] * m22[0, 0] + m24[1, 1] * m22[0, 1],
		    m24[0, 2] * m22[0, 0] + m24[1, 2] * m22[0, 1],
		    m24[0, 3] * m22[0, 0] + m24[1, 3] * m22[0, 1]
		),
		(
		    m24[0, 0] * m22[1, 0] + m24[1, 0] * m22[1, 1],
		    m24[0, 1] * m22[1, 0] + m24[1, 1] * m22[1, 1],
		    m24[0, 2] * m22[1, 0] + m24[1, 2] * m22[1, 1],
		    m24[0, 3] * m22[1, 0] + m24[1, 3] * m22[1, 1]
		)
	)
\ code\ 
\h3 \matmul (\code\@\code\ operator)\ h3\
Has the same effects as the \code\*\code\ operator.
\h3 \div (\code\/\code\ operator)\ h3\
Matrices support division with numbers, vectors and other matrices.  
\code Python \
quot = mat2(1, 2, 3, 4) / 2 # returns mat2(0.5, 1, 1.5, 2)
\code\
Only square matrices can support division with other matrices and vectors.
If a matrix is divided by a vector or vice versa, the matrix is simply inversed and multiplied with that vector instead.
\code Python \
>>> m22 = mat2(1, 2, 3, 4)
>>> v2 = vec2(5, 6)
>>> m22 / v2
vec2( -1, 2 )
>>> glm.inverse(m22) * v2
vec2( -1, 2 )
\ code\
Division with other matrices follows the same scheme.
The right handside matrix is inversed and then multiplied by the other matrix.
\code Python \
>>> m22 = mat2(1, 2, 3, 4)
>>> m22 / mat2(8, 7, 6, 5)
mat2x2(( 8, 9 ), ( -9, -10 ))

>>> m22 * glm.inverse(mat2(8, 7, 6, 5))
mat2x2(( 8, 9 ), ( -9, -10 ))
\ code\
\h3 \len\ h3\
The length of a matrix (i.e. the column count) can be queried using \code\len()\code\.
\code Python \
mat_length = len(mat2x4()) # returns 2
\code\
\h3 \getitem and setitem (\code\[]\code\ operator)\ h3\
You can get the values of a matrix using indices.
\code Python \
m = mat2x3(1, 2, 3, 4, 5, 6)
print(m[0])    # prints mvec3(1, 2, 3)
print(m[1])    # prints mvec3(4, 5, 6)
print(m[0, 2]) # prints 3
print(m[1, 0]) # prints 4
\code\
Note: \i\mvec is a special vector type, that references the values of the matrix it came from.
I.e. if you change the mvec's values, you will do so with the values of the matrix too.\i\

You can also set the values.
\code Python \
>>> m    = mat2(1, 2, 3, 4)
>>> m[0] = vec2(5, 6)
>>> print(m)
[            5 ][            3 ]
[            6 ][            4 ]
\code\
\h3 \contains (\code\in\code\ operator)\ h3\
You can query wether or not a value is contained by a matrix using the \code\in\code\ operator.
\code Python \
>>> m = mat2(1, 2, 3, 4)
>>> vec2(1, 2) in m
True
>>> vec2(2, 3) in m
False
>>> 3 in m
True
>>> 0 in m
False
\code\
\h3 \richcompare (e.g. \code\==\code\ operator)\ h3\
You can compare matrices using the equals and not-equals richcompare operators:
\code Python \
mat2(1, 2, 3, 4) == mat2(1, 2, 3, 4)                # True
mat2(1, 2, 3, 4) == mat2(3, 4, 1, 2)                # False
mat2(1, 2, 3, 4) == mat3(1, 2, 3, 4, 5, 6, 7, 8, 9) # False

mat2(1, 2, 3, 4) != mat2(1, 2, 3, 4)                # False
mat2(1, 2, 3, 4) != mat2(3, 4, 1, 2)                # True
mat2(1, 2, 3, 4) != mat3(1, 2, 3, 4, 5, 6, 7, 8, 9) # True
\code\
\h3 \iter\ h3\
You can generate an iterable from matrices using \code\iter()\code\.
\code Python \
m  = mat2(1, 2, 3, 4)
it = iter(m)
print(next(it)) # prints mvec2(1, 2)
print(next(it)) # prints mvec2(3, 4)
\code\

\h3\hash\h3\
You can generate a hash value for matrices using \code\hash()\code\
Example:
\code Python\
>>> m = mat2()
>>> hash(m)
-8340327414932306126
>>> m2 = mat2(1, 2, 3, 4)
>>> hash(m2)
2533527020982565631
\code\