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.

.gitignore

@@ -76,3 +76,5 @@ build/
 conftest.dir/*
 confdefs.h
 *.xcuserdatad
+.idea
+cmake-build-debug

README.md

@@ -394,6 +394,10 @@ You can pass matrices the same way to other APIs e.g. Vulkan, DX...
 - This library uses float types only, does not support Integers, Double... yet
 - If headers are not working properly with your compiler, IDE please open an issue, because I'm using GCC and clang to test it maybe sometimes MSVC
 
+## Comparing cglm with glm results
+
+Contributors who wish to generate test results using the GLM library are pointed at the simple application in `test/glm_cmp`. A single file `test/glm_cmp/src/main.cpp` exists to which further functions can be added to print additional reference values. This is deliberately not part of the standard build.
+
 **TODO:**
 - [ ] Unit tests (In Progress)
 - [ ] Unit tests for comparing cglm with glm results

include/cglm/cam.h

@@ -248,6 +248,39 @@ glm_perspective(float fovy, float aspect, float nearZ, float farZ, mat4 dest) {
   dest[3][2] = 2.0f * nearZ * farZ * fn;
 }
 
+/*!
+ * @brief set up perspective projection matrix with a left-hand coordinate
+ * system (suitable for DirectX, Metal and Vulkan) and a clip-space with
+ * depth values from zero to one.
+ *
+ * @param[in]  fovy    field of view angle
+ * @param[in]  aspect  aspect ratio ( width / height )
+ * @param[in]  nearVal near clipping plane
+ * @param[in]  farVal  far clipping planes
+ * @param[out] dest    result matrix
+ */
+CGLM_INLINE
+void
+glm_perspective_lh_zo(float fovy,
+                      float aspect,
+                      float nearVal,
+                      float farVal,
+                      mat4  dest) {
+  /* Impl follows glm::perspectiveLH_ZO in glm/ext/matrix_clip_space.inl */
+  float f, fn;
+
+  glm_mat4_zero(dest);
+
+  f  = 1.0f / tanf(fovy * 0.5f);
+  fn = 1.0f / (farVal - nearVal);
+
+  dest[0][0] = f / aspect;
+  dest[1][1] = f;
+  dest[2][2] = farVal * fn;
+  dest[2][3] = 1.0f;
+  dest[3][2] = -(farVal * nearVal * fn);
+}
+
 /*!
  * @brief extend perspective projection matrix's far distance
  *

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)