Add function glm_perspective_lh_zo

This commit adds the function `glm_perspective_lh_zo`, modelled on the
implementation of glm_perspective, but amended to provide a left-hand
coordinate system expected by DirectX, Metal and Vulkan (per the GLM
project's `glm/detail/setup.hpp`). It uses a clip-space of zero-to-one.

The function is tested against a longhand version of the algorithm it
seeks to implement as well as against the output of the GLM project's
`glm::perspectiveLH_ZO` function. This commit adds a new subdirectory
`test/glm_cmp` which contains a basic CMake file and `main.cpp`. An
interested user should link or copy or clone the GLM project into this
directory. The `main` function can be used to print the reference data
used so others can verify behaviour in the future, or add new literal
reference values.

test/glm_cmp/.gitignore

@@ -0,0 +1 @@
+glm

test/glm_cmp/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.17)
+project(glm_cmp LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 14)
+set(CMP_MAIN glmcmp)
+
+add_subdirectory(glm)
+
+add_executable(${CMP_MAIN} src/main.cpp)
+
+target_link_libraries(${CMP_MAIN} PRIVATE glm)
+

test/glm_cmp/README.md

@@ -0,0 +1,8 @@
+### Simple GLM app for quick generation of reference values
+
+#### Usage
+1. Clone, link or copy the GLM library's root directory to `test/glm_cmp/glm`.
+1. Ensuring your current directory is `test/glm_cmp`:
+    `mkdir build && cd build && cmake .. && make && ./glmcmp`
+
+Please do not delete prior reference-data-producing functions as it may be necessary to return to these to examine future bugs or assumptions. By all means remove or comment-out the call site from the `main` function, though, to focus on what you're working on.

test/glm_cmp/src/main.cpp

@@ -0,0 +1,24 @@
+#include <stdio.h>
+
+#include "glm/glm.hpp"
+#include "glm/mat4x4.hpp"
+#include <glm/ext/matrix_clip_space.hpp>
+
+static void outputForPerspectiveLH_ZO() {
+  const float fovy   = glm::radians(45.0f);
+  const float aspect = 640/480.0f;
+  const float near   = 0.1f;
+  const float far    = 100.0f;
+  glm::mat4 cmp = glm::perspectiveLH_ZO(fovy, aspect, near, far);
+  puts("mat4 cmp = {0};");
+  printf("cmp[0][0] = %0.7ff;\n", cmp[0][0]);
+  printf("cmp[1][1] = %0.7ff;\n", cmp[1][1]);
+  printf("cmp[2][2] = %0.7ff;\n", cmp[2][2]);
+  printf("cmp[2][3] = %0.7ff;\n", cmp[2][3]);
+  printf("cmp[3][2] = %0.7ff;\n", cmp[3][2]);
+}
+
+int main(int argc, char** argv) {
+  outputForPerspectiveLH_ZO();
+	return 0;
+}

test/src/test_cam.c

@@ -7,6 +7,40 @@
 
 #include "test_common.h"
 
+TEST_IMPL(perspective_lh_zo) {
+  mat4 dst;
+  const float fovy   = glm_rad(45.0f);
+  const float aspect = 640/480.0f;
+  const float near   = 0.1f;
+  const float far    = 100.0f;
+
+  glm_perspective_lh_zo(fovy, aspect, near, far, dst);
+
+  /* Sanity mk. I */
+  /* Longhand version of what the above function _should_ be doing */
+  ASSERT(test_eq(dst[0][0], 1 / (tanf(fovy / 2) * aspect)))
+  ASSERT(test_eq(dst[1][1], 1 / tanf(fovy / 2)))
+  ASSERT(test_eq(dst[2][2], far / (far - near)))
+  ASSERT(test_eq(dst[2][3], 1.0f))
+  ASSERT(test_eq(dst[3][2], -1 * far * near / (far - near)))
+
+  /* Sanity mk. II */
+  /* "Reference values" generated by GLM's glm::perspectiveLH_ZO */
+  mat4 cmp = {0};
+  cmp[0][0] = 1.8106601f;
+  cmp[1][1] = 2.4142134f;
+  cmp[2][2] = 1.0010010f;
+  cmp[2][3] = 1.0000000f;
+  cmp[3][2] = -0.1001001f;
+
+  for (uint32_t i = 0 ; i < 16 ; i++) {
+    uint32_t r = i%4, c = i/4;
+    ASSERT(fabsf(dst[r][c] - cmp[r][c]) < GLM_FLT_EPSILON)
+  }
+
+  TEST_SUCCESS
+}
+
 TEST_IMPL(camera_lookat) {
   mat4 view1, view2;
   vec3 center,

test/tests.h

@@ -223,6 +223,7 @@ TEST_DECLARE(glmc_mat2_swap_row)
 TEST_DECLARE(glmc_mat2_rmc)
 
 /* camera */
+TEST_DECLARE(perspective_lh_zo)
 TEST_DECLARE(camera_lookat)
 TEST_DECLARE(camera_decomp)
 
@@ -947,6 +948,7 @@ TEST_LIST {
   TEST_ENTRY(glmc_mat2_rmc)
 
   /* camera */
+  TEST_ENTRY(perspective_lh_zo)
   TEST_ENTRY(camera_lookat)
   TEST_ENTRY(camera_decomp)