Merge pull request #48 from petiaccja/examples

examples

.github/workflows/build_and_test.yml

@@ -57,6 +57,9 @@ jobs:
     name: ${{ matrix.build_profile }}
 
     runs-on: ${{matrix.os}}
+
+    env:
+      CMAKE_EXTRA: "-DMATHTER_BUILD_TESTS:BOOL=ON -DMATHTER_BUILD_BENCHMARKS:BOOL=ON -DMATHTER_BUILD_EXAMPLES:BOOL=ON"
 
     steps:
     - uses: actions/checkout@v4
@@ -102,7 +105,7 @@ jobs:
         cmake -E make_directory "${{github.workspace}}/build"
         conan install "${{github.workspace}}" --build=missing -pr $PR -pr:b $PR
         conan cache clean
-        cmake -S "${{github.workspace}}" --preset conan-${{ matrix.conan_preset }}
+        cmake ${{env.CMAKE_EXTRA}} -S "${{github.workspace}}" --preset conan-${{ matrix.conan_preset }}
 
     - name: Build
       run: |

CMakeLists.txt

@@ -16,6 +16,7 @@ set(MATHTER_INIT_MODE "DEFAULT" CACHE STRING "Set default initialization of Math
 set_property(CACHE MATHTER_INIT_MODE PROPERTY STRINGS DEFAULT NULL INVALID UNINITIALIZED)
 option(MATHTER_BUILD_TESTS "Include or exclude tests from the generated project." ON)
 option(MATHTER_BUILD_BENCHMARKS "Include or exclude bechmarks from the generated project." OFF)
+option(MATHTER_BUILD_EXAMPLES "Include or exclude examples from the generated project." OFF)
 option(ENABLE_LLVM_COV "Adds compiler flags to generate LLVM source-based code coverage. Only works with Clang." OFF)
 set(MATHTER_CMAKE_INSTALL_DIR "lib/cmake/${PROJECT_NAME}" CACHE STRING "Subdirectory to install CMake package config files.")
 set(MATHTER_TARGET_ARCH "" CACHE STRING "CPU architecture flag to pass to the compiler, for example AVX2 for MSVC or native for GCC.")
@@ -54,6 +55,9 @@ endif()
 if (${MATHTER_BUILD_BENCHMARKS})
 	add_subdirectory(benchmark)
 endif()
+if (${MATHTER_BUILD_EXAMPLES})
+	add_subdirectory(examples)
+endif()
 
 # Installation
 install(TARGETS Mathter EXPORT MathterTargets

README.md

@@ -12,6 +12,8 @@ Introduction
 ---
 Mathter is a header-only linear algebra library for game development and scientific applications.
 
+*(Find out more in the [**guide**](docs/Guide.md) or in the examples folder.)*
+
 Why yet another 3D math library?
 - Existing libraries often have fixed conventions & notation, but Mathter is fully configurable:
   - Scalar types: floating point, integer, or complex
@@ -57,8 +59,6 @@ const Vec3 transformed = transform * original; // Compilation error due to matri
 ```
 
 
-For more detailed information about using Mathter, **read the** [**guide**](docs/Guide.md).
-
 Features
 ---
 - General:

examples/CMakeLists.txt

@@ -0,0 +1,15 @@
+add_executable(Examples)
+
+
+target_sources(Examples
+	PRIVATE
+		"main.cpp"
+		"Math.hpp"
+		"Camera.hpp"
+		"Camera.cpp"
+		"Object.hpp"
+		"Object.cpp"
+)
+
+
+target_link_libraries(Examples Mathter)

examples/Camera.cpp

@@ -0,0 +1,69 @@
+#include "Camera.hpp"
+
+#include <Mathter/Transforms.hpp>
+#include <Mathter/Utility.hpp>
+
+
+void Camera::SetEye(const Vec3f& eye) {
+	m_eye = eye;
+}
+
+
+const Vec3f& Camera::GetEye() const {
+	return m_eye;
+}
+
+
+void Camera::SetTarget(const Vec3f& target) {
+	m_target = target;
+}
+
+
+const Vec3f& Camera::GetTarget() const {
+	return m_target;
+}
+
+
+void Camera::SetUp(const Vec3f& up) {
+	m_up = up;
+}
+
+
+const Vec3f& Camera::GetUp() const {
+	return m_up;
+}
+
+
+void Camera::SetFoVH(float fovH) {
+	m_fovH = fovH;
+}
+
+
+float Camera::GetFoVH() const {
+	return m_fovH;
+}
+
+
+void Camera::SetAspect(float aspect) {
+	m_aspect = aspect;
+}
+
+
+float Camera::GetAspect() const {
+	return m_aspect;
+}
+
+
+Mat44f Camera::GetViewTransform() const {
+	// This creates a left-handed camera space where the Z axis is forward,
+	// the X axis if right, and the Y axis is up.
+	return LookAt(m_eye, m_target, m_up, true, false, false);
+}
+
+
+Mat44f Camera::GetPerspectiveTransform() const {
+	// This projects the camera space to normalized device coordinates.
+	// If the camera space used negative Z forward, the near and far planes should also be negative.
+	// The normalized device coordinates are X in [-1, 1], Y in [-1, 1], and Z in [0, 1].
+	return mathter::Perspective(mathter::Deg2Rad(m_fovH), m_aspect, 0.1f, 100.f, 0.0f, 1.0f);
+}

examples/Camera.hpp

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "Math.hpp"
+
+
+/// <summary> A camera object that help with view and projective transforms. </summary>
+class Camera {
+public:
+	void SetEye(const Vec3f& eye);
+	const Vec3f& GetEye() const;
+
+	void SetTarget(const Vec3f& target);
+	const Vec3f& GetTarget() const;
+
+	void SetUp(const Vec3f& eye);
+	const Vec3f& GetUp() const;
+
+	void SetFoVH(float fovH);
+	float GetFoVH() const;
+
+	void SetAspect(float aspect);
+	float GetAspect() const;
+
+	Mat44f GetViewTransform() const;
+	Mat44f GetPerspectiveTransform() const;
+
+private:
+	Vec3f m_eye = { 0, 0, 0 };
+	Vec3f m_target = { 1, 0, 0 };
+	Vec3f m_up = { 0, 0, 1 };
+	float m_fovH = 75.0f;
+	float m_aspect = 16.0f / 9.0f;
+};

examples/Math.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <Mathter/Geometry/Triangle.hpp>
+#include <Mathter/Matrix.hpp>
+#include <Mathter/Quaternion.hpp>
+#include <Mathter/Vector.hpp>
+
+
+// Type aliases for Mathter's types, defining the Example project's conventions.
+using Vec2i = mathter::Vector<int, 2, false>;
+using Vec2f = mathter::Vector<float, 2, false>;
+using Vec3f = mathter::Vector<float, 3, false>;
+using Mat44f = mathter::Matrix<float, 4, 4, mathter::eMatrixOrder::FOLLOW_VECTOR, mathter::eMatrixLayout::ROW_MAJOR, false>;
+using Quatf = mathter::Quaternion<float, mathter::eQuaternionLayout::SCALAR_FIRST, false>;
+
+using Triangle3f = mathter::Triangle<float, 3>;

examples/Object.cpp

@@ -0,0 +1,11 @@
+#include "Object.hpp"
+
+#include "Mathter/Transforms.hpp"
+
+
+Mat44f Object::GetTransform() const {
+	// The scaling and translation transforms must be converted to Mat44 before they can be used for multiplication.
+	// Since we defined Mat44 to have FOLLOW_VECTOR multiplication order, we're concatenating
+	// the transforms from left to right.
+	return Mat44f(Scale(scale)) * Mat44f(rotation) * Mat44f(Translation(position));
+}

examples/Object.hpp

@@ -0,0 +1,17 @@
+#pragma once
+
+#include "Math.hpp"
+
+#include <vector>
+
+
+/// <summary> A polygonal 3D geometry consisting of triangles. </summary>
+struct Object {
+	std::vector<Triangle3f> triangles;
+
+	Vec3f scale;
+	Quatf rotation;
+	Vec3f position;
+
+	Mat44f GetTransform() const;
+};