Relevant source files

The following files were used as context for generating this wiki page: - [include/velocity/vec3.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/vec3.h) - [include/velocity/mat4.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/mat4.h) - [include/velocity/common.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/common.h) - [include/velocity/vec2.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/vec2.h) - [include/velocity/vec4.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/vec4.h) - [include/velocity/velocity.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/velocity.h) - [README.md](https://github.com/AdrianParedez/velocity/blob/main/README.md)

# Compile-Time Operations with constexpr The Velocity math library leverages C++17's `constexpr` capabilities to provide zero-cost abstractions and high performance. By marking functions and variables as `constexpr`, the library allows the C++ compiler to perform mathematical calculations at compile time instead of at runtime. This pre-computation results in faster execution, as the results of these operations are embedded directly into the program binary. This feature is a cornerstone of the library's design, particularly for the vector types (`Vec2`, `Vec3`, `Vec4`) and common mathematical utilities. It enables the creation and manipulation of constant geometric and mathematical data without any runtime performance penalty, which is critical in performance-sensitive applications like graphics, game development, and scientific computing. *Sources: [README.md:7](), [include/velocity/vec3.h](), [include/velocity/common.h]()* ## Core `constexpr` Components The use of `constexpr` is widespread across the library's headers, primarily in constants, utility functions, and vector class operations. ### `constexpr` Constants The library defines several fundamental mathematical and library-specific constants as `constexpr`. This ensures they are treated as true compile-time constants, allowing for their use in other compile-time expressions and avoiding runtime lookups. | Constant | Description | File | | :--- | :--- | :--- | | `PI` | The value of Pi. | `common.h:8` | | `TWO_PI` | The value of 2 * Pi. | `common.h:9` | | `HALF_PI` | The value of Pi / 2. | `common.h:10` | | `EPSILON` | A small float value for equality comparisons. | `common.h:11` | | `DEG_TO_RAD` | Conversion factor from degrees to radians. | `common.h:12` | | `RAD_TO_DEG` | Conversion factor from radians to degrees. | `common.h:13` | | `VERSION_MAJOR` | The major version number of the library. | `velocity.h:9` | | `VERSION_MINOR` | The minor version number of the library. | `velocity.h:10` | | `VERSION_PATCH` | The patch version number of the library. | `velocity.h:11` | *Sources: [include/velocity/common.h:7-14](), [include/velocity/velocity.h:8-12]()* ### `constexpr` Utility Functions A suite of general-purpose math functions in the `vel::math` namespace are implemented as `constexpr`, enabling them to be used in compile-time contexts. The diagram below shows the flow of a `constexpr` function call, which is resolved by the compiler. ```mermaid graph TD A[Source Code: `math::radians(90.0f)`] --> B{Compiler}; B --> C[Compile-Time Evaluation]; C --> D[Result `1.570796...f` embedded in binary]; ``` *Sources: [include/velocity/common.h:17-51]()* | Function | Description | | :--- | :--- | | `radians(float degrees)` | Converts degrees to radians. | | `degrees(float radians)` | Converts radians to degrees. | | `clamp(float value, float min, float max)` | Clamps a value between a minimum and maximum. | | `lerp(float a, float b, float t)` | Performs linear interpolation between two values. | | `smoothstep(float edge0, float edge1, float x)` | Performs a smooth Hermite interpolation. | | `sign(float value)` | Returns the sign of a value (-1, 0, or 1). | | `min(float a, float b)` | Returns the smaller of two values. | | `max(float a, float b)` | Returns the larger of two values. | | `isPowerOfTwo(int value)` | Checks if an integer is a power of two. | *Sources: [include/velocity/common.h:17-51]()* ## `constexpr` in Vector Classes The `Vec2`, `Vec3`, and `Vec4` classes are designed with `constexpr` at their core, allowing for a wide range of vector algebra to be performed at compile time. The class diagram below for `Vec3` highlights the methods and operators that are `constexpr`. ```mermaid classDiagram class Vec3 { +float x +float y +float z +constexpr Vec3() +constexpr Vec3(float x, float y, float z) +constexpr Vec3(float scalar) +constexpr Vec3(Vec2 xy, float z) +constexpr Vec3 operator+(Vec3 rhs) +constexpr Vec3 operator-(Vec3 rhs) +constexpr Vec3 operator*(float scalar) +constexpr float dot(Vec3 rhs) +constexpr Vec3 cross(Vec3 rhs) +constexpr float lengthSquared() +constexpr Vec3 lerp(Vec3 rhs, float t) +constexpr Vec2 xy() +<> constexpr Vec3 zero() +<> constexpr Vec3 one() +<> constexpr Vec3 up() +float length() +Vec3 normalized() } ``` *This diagram shows that most `Vec3` operations are `constexpr`, except those requiring runtime math functions like `std::sqrt`.* *Sources: [include/velocity/vec2.h](), [include/velocity/vec3.h](), [include/velocity/vec4.h]()* ### `constexpr` Constructors and Factories All constructors for `Vec2`, `Vec3`, and `Vec4` are `constexpr`. This allows for the compile-time creation of vector instances. Additionally, static factory methods for common vectors (e.g., `zero()`, `one()`, `unitX()`, `up()`) are also `constexpr`. ```cpp // This entire expression can be evaluated at compile time constexpr vel::Vec3 up = vel::Vec3::up(); constexpr vel::Vec3 v(1.0f, 2.0f, 3.0f); ``` *Sources: [include/velocity/vec3.h:13-16, 61-71](), [include/velocity/vec2.h:11-13, 51-54](), [include/velocity/vec4.h:12-16, 52-57]()* ### `constexpr` Operators and Methods The majority of operators and methods that do not rely on complex `cmath` functions are `constexpr`. **`constexpr`-enabled operations include:** - **Arithmetic:** `+`, `-`, `*` (scalar), `/` (scalar), unary `-` - **Compound Assignment:** `+=`, `-=`, `*=`, `/=` - **Vector Algebra:** `dot()`, `cross()` (`Vec2`, `Vec3`), `lengthSquared()`, `distanceSquared()` - **Interpolation:** `lerp()` - **Element Access:** `operator[]` - **Swizzling:** `xy()`, `xz()`, `yz()`, `xyz()`, `zw()` This allows for complex chains of operations to be resolved by the compiler. ```cpp // This vector is fully computed during compilation constexpr vel::Vec3 a(1.0f, 0.0f, 0.0f); constexpr vel::Vec3 b(0.0f, 1.0f, 0.0f); constexpr vel::Vec3 c = (a + b).cross(b) * 2.0f; ``` *Sources: [include/velocity/vec3.h:23-48](), [include/velocity/vec2.h:21-44](), [include/velocity/vec4.h:24-45]()* ## Limitations and Runtime-Only Operations Not all operations in the library are `constexpr`. Operations that rely on functions not typically available at compile time in C++17 (like `std::sqrt`, `std::sin`, `std::cos`) are implemented as standard `inline` or member functions that execute at runtime. ### Non-`constexpr` Vector Methods The following methods in the vector classes are **not** `constexpr` and will always execute at runtime: - `length()` - `normalized()` and `normalize()` - `distance()` - `reflect()` - `project()` (`Vec3`) - `angle()` (`Vec2`) - `rotate()` (`Vec2`) *Sources: [include/velocity/vec3.h:43, 45, 46, 49, 50](), [include/velocity/vec2.h:37, 39, 40, 42, 45, 46]()* ### `Mat4` Class In contrast to the vector classes, the `Mat4` class has very limited `constexpr` support. While element access (`operator()`) and data pointer access (`data()`) are `constexpr`, the constructors and almost all mathematical operations (multiplication, inversion, transposition, etc.) are **not**. This design choice implies that matrix operations are considered too complex for practical compile-time evaluation within the library's C++17 scope, and are therefore intended exclusively for runtime execution. ```mermaid graph TD subgraph Compile-Time A[Vec3 a, b] --> B{a + b}; B --> C[Vec3 result]; end subgraph Runtime D[Mat4 M1, M2] --> E{M1 * M2}; E --> F[Mat4 result]; end style Compile-Time fill:#e6f3ff,stroke:#333,stroke-width:2px style Runtime fill:#fff0e6,stroke:#333,stroke-width:2px ``` *This diagram illustrates the separation between compile-time vector operations and runtime matrix operations.* *Sources: [include/velocity/mat4.h:12-53]()* ## Conclusion The Velocity library makes extensive and effective use of `constexpr` to push mathematical computations from runtime to compile time. This applies thoroughly to `Vec2`, `Vec3`, `Vec4`, and common utility functions, providing significant performance benefits for constant data. The deliberate exclusion of `constexpr` from more complex operations, such as most `Mat4` methods and vector normalization, draws a clear line between compile-time and runtime calculations within the library's architecture. This strategic implementation aligns with its goal of being a high-performance library for demanding applications. *Sources: [README.md:7](), [include/velocity/vec3.h](), [include/velocity/mat4.h]()*## FULL FILE CONTEXT SUMMARY Query: You are an expert technical writer and software architect. Your task is to generate a comprehensive and accurate technical wiki page in Markdown format about a specific feature, system, or module within a given software project. You will be given: 1. The "[WIKI_PAGE_TOPIC]" for the page you need to create. 2. A list of "[RELEVANT_SOURCE_FILES]" from the project that you MUST use as the sole basis for the content. You MUST use AT LEAST 5 relevant source files for comprehensive coverage - if fewer are provided, search for additional related files in the codebase. CRITICAL STARTING INSTRUCTION: The very first thing on the page MUST be a

block listing ALL the [RELEVANT_SOURCE_FILES] you used to generate the content. There MUST be AT LEAST 5 source files listed - if fewer were provided, you MUST find additional related files to include. Format it exactly like this:

Relevant source files

Remember, do not provide any acknowledgements, disclaimers, apologies, or any other preface before the `

` block. JUST START with the `

` block. The following files were used as context for generating this wiki page: - [include/velocity/vec3.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/vec3.h) - [include/velocity/mat4.h](https://github.com/AdrianParedez/velocity/blob/main/include/velocity/mat4.h)

Immediately after the

block, the main title of the page should be a H1 Markdown heading: # Compile-Time Operations with constexpr. Based ONLY on the content of the [RELEVANT_SOURCE_FILES]: 1. **Introduction:** Start with a concise introduction (1-2 paragraphs) explaining the purpose, scope, and high-level overview of "Compile-Time Operations with constexpr" within the context of the overall project. If relevant, and if information is available, link to other potential wiki pages using the format [Link Text](#page-anchor-or-id). 2. **Detailed Sections:** Break down "Compile-Time Operations with constexpr" into logical sections using H2 (##) and H3 (###) Markdown headings. For each section: * Explain the architecture, components, data flow, or logic relevant to the section's focus, as evidenced in the source files. * Identify key functions, classes, data structures, API endpoints, or configuration elements pertinent to that section. 3. **Mermaid Diagrams:** * EXTENSIVELY use Mermaid diagrams (e.g., flowchart TD, sequenceDiagram, classDiagram, erDiagram, graph TD) to visually represent architectures, flows, relationships, and schemas found in the source files. * Ensure diagrams are accurate and directly derived information from the [RELEVANT_SOURCE_FILES]. * Provide a brief explanation before or after each diagram to give context. * CRITICAL diagram requirements for optimal rendering: - **Flow diagrams**: Use "graph TD" (top-down) or "flowchart TD" directives for better vertical layout - **Node labels**: Keep node labels concise but descriptive (under 25 characters for readability) - **Node IDs**: Use alphanumeric characters and underscores only (avoid spaces, special characters) - **Connections**: Use standard arrow syntax (-->, ---, -.->) for reliable rendering - **Sequence diagrams**: - Start with "sequenceDiagram" directive on its own line - Use participant names without spaces (use underscores if needed) - Define participants explicitly when needed: `participant User as "User Interface"` - Use correct arrow types: - ->> for synchronous calls/requests - -->> for responses - -x for failed/error messages - --x for failed responses - Add activation boxes sparingly with +/- notation - Use "Note over" or "Note right of" for clarifications - **Class diagrams**: Use standard UML notation with proper relationship syntax - **ER diagrams**: Use entity relationship syntax with proper cardinality notations * **Quality guidelines**: - Test diagram syntax mentally before including - If a diagram becomes too complex, split into multiple focused diagrams - Ensure proper closing of all brackets and quotes - Use consistent naming conventions within each diagram - Add line breaks for readability in complex diagrams * **Example patterns (GOOD vs BAD)**: ``` GOOD Flow Diagram: ```mermaid flowchart TD A[User Request] --> B[Validate Input] B --> C[Process Data] C --> D[Return Response] ``` BAD Flow Diagram: ```mermaid graph LR A[User Request with Very Long Description] --> B ``` GOOD Sequence Diagram: ```mermaid sequenceDiagram participant User as "User Interface" participant API as "API Server" participant DB as "Database" User->>API: POST /api/data API->>DB: SELECT * FROM table DB-->>API: Query results API-->>User: JSON response ``` ``` 4. **Tables:** * Use Markdown tables to summarise information such as: * Key features or components and their descriptions. * API endpoint parameters, types, and descriptions. * Configuration options, their types, and default values. * Data model fields, types, constraints, and descriptions. 5. **Code Snippets (ENTIRELY OPTIONAL):** * Include short, relevant code snippets (e.g., Python, Java, JavaScript, SQL, JSON, YAML) directly from the [RELEVANT_SOURCE_FILES] to illustrate key implementation details, data structures, or configurations. * Ensure snippets are well-formatted within Markdown code blocks with appropriate language identifiers. 6. **Source Citations (EXTREMELY IMPORTANT):** * For EVERY piece of significant information, explanation, diagram, table entry, or code snippet, you MUST cite the specific source file(s) and relevant line numbers from which the information was derived. * Place citations at the end of the paragraph, under the diagram/table, or after the code snippet. * Use the exact format: `Sources: [filename.ext:start_line-end_line]()` for a range, or `Sources: [filename.ext:line_number]()` for a single line. Multiple files can be cited: `Sources: [file1.ext:1-10](), [file2.ext:5](), [dir/file3.ext]()` (if the whole file is relevant and line numbers are not applicable or too broad). * If an entire section is overwhelmingly based on one or two files, you can cite them under the section heading in addition to more specific citations within the section. * You MUST cite AT LEAST 5 different source files throughout the wiki page to ensure comprehensive coverage. 7. **Technical Accuracy:** All information must be derived SOLELY from the [RELEVANT_SOURCE_FILES]. Do not infer, invent, or use external knowledge about similar systems or common practices unless it's directly supported by the provided code. If information is not present in the provided files, do not include it or explicitly state its absence if crucial to the topic. 8. **Clarity and Conciseness:** Use clear, professional, and concise technical language suitable for other developers working on or learning about the project. Avoid unnecessary jargon, but use correct technical terms where appropriate. 9. **Conclusion/Summary:** End with a brief summary paragraph if appropriate for "Compile-Time Operations with constexpr", reiterating the key aspects covered and their significance within the project. IMPORTANT: Generate the content in English language. Remember: - Ground every claim in the provided source files. - Prioritize accuracy and direct representation of the code's functionality and structure. - Structure the document logically for easy understanding by other developers. Total Files Included: 15 Total Files Skipped: 0 Total Context Tokens: 20,037 / 800,000 (2.5%) Remaining Token Budget: 779,963 ### Included Files: 1. benchmarks/benchmark_suite.cpp (4,449 tokens) 2. README.md (572 tokens) 3. CMakeLists.txt (552 tokens) 4. examples/example.cpp (1,804 tokens) 5. tests/test_main.cpp (2,645 tokens) 6. include/velocity/velocity.h (76 tokens) 7. include/velocity/common.h (564 tokens) 8. include/velocity/vec4.h (1,092 tokens) 9. include/velocity/vec3.h (1,242 tokens) 10. src/vec3.cpp (320 tokens) 11. include/velocity/vec2.h (822 tokens) 12. src/vec4.cpp (235 tokens) 13. src/vec2.cpp (292 tokens) 14. include/velocity/mat4.h (800 tokens) 15. src/mat4.cpp (4,572 tokens) ================================================================================ FILE: benchmarks/benchmark_suite.cpp Relevance Score: 0.990 | Chunks Retrieved: 4 | Tokens: 4,449 ================================================================================ #include #include #include #include #include #include #include #include #include #include using namespace vel; class BenchmarkTimer { private: std::chrono::high_resolution_clock::time_point start_time; public: void start() { start_time = std::chrono::high_resolution_clock::now(); } double elapsed_microseconds() { auto end_time = std::chrono::high_resolution_clock::now(); auto duration = std::chrono::duration_cast(end_time - start_time); return static_cast(duration.count()); } double elapsed_milliseconds() { return elapsed_microseconds() / 1000.0; } }; class PerformanceBenchmark { private: std::mt19937 rng{42}; // Fixed seed for reproducible results std::uniform_real_distribution dist{-10.0f, 10.0f}; struct BenchmarkResult { std::string name; double time_us; double ops_per_sec; double mb_per_sec; }; std::vector results; void printHeader(const std::string& title) { std::cout << "\n" << std::string(60, '=') << std::endl; std::cout << title << std::endl; std::cout << std::string(60, '=') << std::endl; std::cout << std::left << std::setw(25) << "Operation" << std::setw(12) << "Time (μs)" << std::setw(15) << "Ops/sec" << std::setw(12) << "MB/s" << std::endl; std::cout << std::string(60, '-') << std::endl; } void printResult(const std::string& name, double time_us, int iterations, size_t bytes_per_op = 0) { double ops_per_sec = (iterations * 1e6) / time_us; double mb_per_sec = bytes_per_op > 0 ? (ops_per_sec * bytes_per_op) / (1024 * 1024) : 0; std::cout << std::left << std::setw(25) << name << std::setw(12) << std::fixed << std::setprecision(0) << time_us << std::setw(15) << std::fixed << std::setprecision(0) << ops_per_sec; if (bytes_per_op > 0) { std::cout << std::setw(12) << std::fixed << std::setprecision(1) << mb_per_sec; } std::cout << std::endl; // Store result for document generation results.push_back({name, time_us, ops_per_sec, mb_per_sec}); } public: void runVectorBenchmarks() { printHeader("Vector Operations Benchmark (1M iterations)"); const int iterations = 1000000; BenchmarkTimer timer; // Generate test data std::vector vec_a(iterations), vec_b(iterations), results(iterations); for (int i = 0; i < iterations; ++i) { vec_a[i] = Vec3(dist(rng), dist(rng), dist(rng)); vec_b[i] = Vec3(dist(rng), dist(rng), dist(rng)); } // Vec3 Addition timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = vec_a[i] + vec_b[i]; } printResult("Vec3 Addition", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 3); // Vec3 Subtraction timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = vec_a[i] - vec_b[i]; } printResult("Vec3 Subtraction", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 3); // Vec3 Scalar Multiplication timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = vec_a[i] * 2.5f; } printResult("Vec3 Scalar Mult", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 2); // Vec3 Dot Product std::vector dot_results(iterations); timer.start(); for (int i = 0; i < iterations; ++i) { dot_results[i] = vec_a[i].dot(vec_b[i]); } printResult("Vec3 Dot Product", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 2 + sizeof(float)); // Vec3 Cross Product timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = vec_a[i].cross(vec_b[i]); } printResult("Vec3 Cross Product", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 3); // Vec3 Length timer.start(); for (int i = 0; i < iterations; ++i) { dot_results[i] = vec_a[i].length(); } printResult("Vec3 Length", timer.elapsed_microseconds(), iterations, sizeof(Vec3) + sizeof(float)); // Vec3 Normalization timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = vec_a[i].normalized(); } printResult("Vec3 Normalization", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 2); // Vec3 Distance timer.start(); for (int i = 0; i < iterations; ++i) { dot_results[i] = vec_a[i].distance(vec_b[i]); } printResult("Vec3 Distance", timer.elapsed_microseconds(), iterations, sizeof(Vec3) * 2 + sizeof(float)); } void runMatrixBenchmarks() { printHeader("Matrix Operations Benchmark (100K iterations)"); const int iterations = 100000; BenchmarkTimer timer; // Generate test data std::vector mat_a(iterations), mat_b(iterations), results(iterations); for (int i = 0; i < iterations; ++i) { // Create random transformation matrices Vec3 translation(dist(rng), dist(rng), dist(rng)); Vec3 scale(std::abs(dist(rng)) + 0.1f, std::abs(dist(rng)) + 0.1f, std::abs(dist(rng)) + 0.1f); float angle = dist(rng); mat_a[i] = Mat4::translation(translation) * Mat4::rotationY(angle) * Mat4::scale(scale); mat_b[i] = Mat4::translation(translation * 0.5f) * Mat4::rotationX(angle * 0.7f); } // Matrix Multiplication timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = mat_a[i] * mat_b[i]; } printResult("Mat4 Multiplication", timer.elapsed_microseconds(), iterations, sizeof(Mat4) * 3); // Matrix Addition timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = mat_a[i] + mat_b[i]; } printResult("Mat4 Addition", timer.elapsed_microseconds(), iterations, sizeof(Mat4) * 3); // Matrix Transpose timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = mat_a[i].transposed(); } printResult("Mat4 Transpose", timer.elapsed_microseconds(), iterations, sizeof(Mat4) * 2); // Matrix Determinant std::vector det_results(iterations); timer.start(); for (int i = 0; i < iterations; ++i) { det_results[i] = mat_a[i].determinant(); } printResult("Mat4 Determinant", timer.elapsed_microseconds(), iterations, sizeof(Mat4) + sizeof(float)); // Matrix Inverse (fewer iterations due to complexity) const int inverse_iterations = iterations / 10; timer.start(); for (int i = 0; i < inverse_iterations; ++i) { try { results[i] = mat_a[i].inverse(); } catch (...) { results[i] = Mat4::identity(); // Fallback for singular matrices } } printResult("Mat4 Inverse", timer.elapsed_microseconds(), inverse_iterations, sizeof(Mat4) * 2); } void runTransformBenchmarks() { printHeader("Transformation Benchmark (1M iterations)"); const int iterations = 1000000; BenchmarkTimer timer; // Generate test data std::vector points(iterations), results(iterations); Mat4 transform = Mat4::translation(Vec3(1, 2, 3)) * Mat4::rotationY(math::radians(45.0f)) * Mat4::scale(Vec3(2, 2, 2)); for (int i = 0; i < iterations; ++i) { points[i] = Vec3(dist(rng), dist(rng), dist(rng)); } // Point Transformation timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = transform.transformPoint(points[i]); } printResult("Point Transform", timer.elapsed_microseconds(), iterations, sizeof(Vec3) + sizeof(Mat4)); // Direction Transformation timer.start(); for (int i = 0; i < iterations; ++i) { results[i] = transform.transformDirection(points[i]); } printResult("Direction Transform", timer.elapsed_microseconds(), iterations, sizeof(Vec3) + sizeof(Mat4)); } void runMemoryBenchmarks() { printHeader("Memory Access Pattern Benchmark"); const int size = 1000000; BenchmarkTimer timer; // Sequential access test std::vector sequential_data(size); for (int i = 0; i < size; ++i) { sequential_data[i] = Vec3(i, i+1, i+2); } timer.start(); Vec3 sum = Vec3::zero(); for (int i = 0; i < size; ++i) { sum += sequential_data[i]; } double sequential_time = timer.elapsed_microseconds(); // Random access test std::vector indices(size); std::iota(indices.begin(), indices.end(), 0); std::shuffle(indices.begin(), indices.end(), rng); timer.start(); sum = Vec3::zero(); for (int i = 0; i < size; ++i) { sum += sequential_data[indices[i]]; } double random_time = timer.elapsed_microseconds(); printResult("Sequential Access", sequential_time, size, sizeof(Vec3) * 2); printResult("Random Access", random_time, size, sizeof(Vec3) * 2); std::cout << "\nCache Efficiency Ratio: " << std::fixed << std::setprecision(2) << (sequential_time / random_time) << "x faster (sequential vs random)" << std::endl; } void runAccuracyTests() { printHeader("Numerical Accuracy Tests"); // Test vector normalization accuracy Vec3 test_vec(1e-6f, 1e-6f, 1e-6f); // Very small vector Vec3 normalized = test_vec.normalized(); float length_error = std::abs(normalized.length() - 1.0f); std::cout << "Vector Normalization Error: " << std::scientific << length_error << std::endl; // Test matrix inverse accuracy Mat4 original = Mat4::translation(Vec3(1, 2, 3)) * Mat4::rotationY(0.5f); Mat4 inverse = original.inverse(); Mat4 identity_test = original * inverse; float identity_error = 0.0f; for (int i = 0; i < 4; ++i) { for (int j = 0; j < 4; ++j) { float expected = (i == j) ? 1.0f : 0.0f; identity_error += std::abs(identity_test(i, j) - expected); } } std::cout << "Matrix Inverse Error: " << std::scientific << identity_error << std::endl; // Test floating-point comparison float a = 0.1f + 0.2f; float b = 0.3f; bool standard_equal = (a == b); bool epsilon_equal = math::isEqual(a, b); std::cout << "0.1 + 0.2 == 0.3: " << (standard_equal ? "true" : "false") << std::endl; std::cout << "isEqual(0.1 + 0.2, 0.3): " << (epsilon_equal ? "true" : "false") << std::endl; std::cout << "Difference: " << std::scientific << std::abs(a - b) << std::endl; } void generateBenchmarkDocument() { std::ofstream doc("docs/BENCHMARK_RESULTS.md"); doc << "# Velocity Math Library - Benchmark Results\n\n"; doc << "## System Information\n\n"; doc << "- **CPU**: Intel i5-11320H @ 3.20GHz (11th Gen)\n"; doc << "- **Compiler**: GCC 15.2\n"; doc << "- **Optimization**: -O3 -march=native -DNDEBUG\n"; doc << "- **Architecture**: 64-bit\n"; doc << "- **Date**: " << getCurrentDate() << "\n\n"; doc << "## Performance Results\n\n"; // Vector operations doc << "### Vector Operations (1M iterations)\n\n"; doc << "| Operation | Time (μs) | Ops/sec | MB/s |\n"; doc << "|-----------|-----------|---------|------|\n"; for (const auto& result : results) { if (result.name.find("Vec3") != std::string::npos) { doc << "| " << result.name << " | " << std::fixed << std::setprecision(0) << result.time_us << " | " << std::fixed << std::setprecision(0) << result.ops_per_sec / 1e6 << "M | " << std::fixed << std::setprecision(1) << result.mb_per_sec << " |\n"; } } // Matrix operations doc << "\n### Matrix Operations (100K iterations)\n\n"; doc << "| Operation | Time (μs) | Ops/sec | MB/s |\n"; doc << "|-----------|-----------|---------|------|\n"; for (const auto& result : results) { if (result.name.find("Mat4") != std::string::npos) { doc << "| " << result.name << " | " << std::fixed << std::setprecision(0) << result.time_us << " | " << std::fixed << std::setprecision(0) << result.ops_per_sec / 1e6 << "M | " << std::fixed << std::setprecision(1) << result.mb_per_sec << " |\n"; } } // Transformation operations doc << "\n### Transformation Operations (1M iterations)\n\n"; doc << "| Operation | Time (μs) | Ops/sec | MB/s |\n"; doc << "|-----------|-----------|---------|------|\n"; for (const auto& result : results) { if (result.name.find("Transform") != std::string::npos) { doc << "| " << result.name << " | " << std::fixed << std::setprecision(0) << result.time_us << " | " << std::fixed << std::setprecision(0) << result.ops_per_sec / 1e6 << "M | " << std::fixed << std::setprecision(1) << result.mb_per_sec << " |\n"; } } doc << "\n## Performance Summary\n\n"; doc << "### Top Performers\n\n"; // Find top performers double max_vec_ops = 0, max_mat_ops = 0; std::string best_vec, best_mat; for (const auto& result : results) { if (result.name.find("Vec3") != std::string::npos && result.ops_per_sec > max_vec_ops) { max_vec_ops = result.ops_per_sec; best_vec = result.name; } if (result.name.find("Mat4") != std::string::npos && result.ops_per_sec > max_mat_ops) { max_mat_ops = result.ops_per_sec; best_mat = result.name; } } doc << "- **Fastest Vector Operation**: " << best_vec << " (" << std::fixed << std::setprecision(0) << max_vec_ops / 1e6 << "M ops/sec)\n"; doc << "- **Fastest Matrix Operation**: " << best_mat << " (" << std::fixed << std::setprecision(0) << max_mat_ops / 1e6 << "M ops/sec)\n\n"; doc << "### Key Metrics\n\n"; doc << "- **Vector Addition**: High-frequency operation for real-time applications\n"; doc << "- **Matrix Multiplication**: Core transformation operation for graphics\n"; doc << "- **Memory Throughput**: Optimized for cache-friendly access patterns\n"; doc << "- **Numerical Accuracy**: Sub-microsecond precision errors\n\n"; doc << "## Notes\n\n"; doc << "- Results may vary based on CPU, compiler, and system load\n"; doc << "- Benchmarks use release optimization (-O3) for maximum performance\n"; doc << "- Memory throughput calculated based on theoretical data access patterns\n"; doc << "- All operations maintain numerical accuracy within specified tolerances\n"; doc.close(); std::cout << "\nBenchmark results saved to docs/BENCHMARK_RESULTS.md" << std::endl; } std::string getCurrentDate() { auto now = std::chrono::system_clock::now(); auto time_t = std::chrono::system_clock::to_time_t(now); std::stringstream ss; ss << std::put_time(std::localtime(&time_t), "%B %d, %Y"); return ss.str(); } }; int main() { std::cout << "Velocity Math Library - Performance Benchmark Suite" << std::endl; std::cout << "===================================================" << std::endl; // System info std::cout << "Compiler: " << #ifdef __GNUC__ "GCC " << __GNUC__ << "." << __GNUC_MINOR__ #elif defined(_MSC_VER) "MSVC " << _MSC_VER #else "Unknown" #endif << std::endl; std::cout << "Optimization: " << #ifdef NDEBUG "Release (-O3)" #else "Debug" #endif << std::endl; std::cout << "Architecture: " << sizeof(void*) * 8 << "-bit" << std::endl; PerformanceBenchmark benchmark; benchmark.runVectorBenchmarks(); benchmark.runMatrixBenchmarks(); benchmark.runTransformBenchmarks(); benchmark.runMemoryBenchmarks(); benchmark.runAccuracyTests(); // Generate benchmark document benchmark.generateBenchmarkDocument(); std::cout << "\nBenchmark completed successfully!" << std::endl; std::cout << "Note: Results may vary based on CPU, compiler, and system load." << std::endl; return 0; } ================================================================================ ================================================================================ FILE: README.md Relevance Score: 0.980 | Chunks Retrieved: 1 | Tokens: 572 ================================================================================ # Velocity Math Library A high-performance C++17 vector and matrix math library designed for real-time graphics, game development, and scientific computing. ## Features - **High Performance**: Optimized vector and matrix operations with up to 400M+ operations per second - **Modern C++**: C++17 with constexpr operations and zero-cost abstractions - **Graphics Ready**: Column-major matrices, projection utilities, and transformation functions - **Cross-Platform**: Windows, Linux, and macOS support with multiple build systems - **Comprehensive**: Vec2, Vec3, Vec4 vectors and Mat4 matrices with full mathematical operations ## Quick Start ```cpp #include using namespace vel; // Vector operations Vec3 position(1.0f, 2.0f, 3.0f); Vec3 velocity(0.5f, 0.0f, -1.0f); Vec3 newPosition = position + velocity * deltaTime; // Matrix transformations Mat4 transform = Mat4::translation(position) * Mat4::rotationY(math::radians(45.0f)) * Mat4::scale(Vec3(2.0f)); // Transform points Vec3 transformedPoint = transform.transformPoint(Vec3(1, 0, 0)); ``` ## Performance Benchmark results on Intel i5-11320H @ 3.20GHz: - **Vector Operations**: Up to 408M operations/second - **Matrix Operations**: Up to 48M operations/second - **Memory Throughput**: Up to 9.2GB/second See [docs/BENCHMARK_RESULTS.md](docs/BENCHMARK_RESULTS.md) for detailed performance analysis. ## Building ### Using Make ```bash make all # Build library, examples, tests, and benchmarks make run-tests # Build and run tests make run-benchmarks # Build and run performance benchmarks ``` ### Using CMake ```bash mkdir build && cd build cmake .. make ``` ## Documentation Complete documentation is available in the [docs/](docs/) directory: - [Benchmark Results](docs/BENCHMARK_RESULTS.md) - Latest performance data - [Documentation Index](docs/README.md) - Complete documentation overview ## Requirements - **C++17** compatible compiler - **CMake 3.12+** (for CMake builds) - **Make** (for Makefile builds) ## License MIT License - see [LICENSE](LICENSE) for details. ## Contributing Contributions are welcome! Please ensure all tests pass and include benchmarks for performance-related changes. ## Author Adrian Paredez - [GitHub](https://github.com/AdrianParedez) ================================================================================ ================================================================================ FILE: CMakeLists.txt Relevance Score: 0.970 | Chunks Retrieved: 1 | Tokens: 552 ================================================================================ cmake_minimum_required(VERSION 3.12) project(velocity VERSION 1.0.0 LANGUAGES CXX) # Set C++ standard set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) # Compiler flags if(MSVC) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W4") else() set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wpedantic") endif() # Include directories include_directories(include) # Source files set(VELOCITY_SOURCES src/vec2.cpp src/vec3.cpp src/vec4.cpp src/mat4.cpp ) # Header files set(VELOCITY_HEADERS include/velocity/common.h include/velocity/vec2.h include/velocity/vec3.h include/velocity/vec4.h include/velocity/mat4.h include/velocity/velocity.h ) # Create library add_library(velocity STATIC ${VELOCITY_SOURCES} ${VELOCITY_HEADERS}) # Set target properties set_target_properties(velocity PROPERTIES VERSION ${PROJECT_VERSION} SOVERSION 1 PUBLIC_HEADER "${VELOCITY_HEADERS}" ) # Include directories for the library target_include_directories(velocity PUBLIC $ $ ) # Example executable (optional) option(BUILD_EXAMPLES "Build example programs" ON) if(BUILD_EXAMPLES) add_executable(velocity_example examples/example.cpp) target_link_libraries(velocity_example velocity) endif() # Tests (optional) option(BUILD_TESTS "Build test programs" ON) if(BUILD_TESTS) add_executable(velocity_tests tests/test_main.cpp) target_link_libraries(velocity_tests velocity) endif() # Install configuration install(TARGETS velocity EXPORT velocityTargets LIBRARY DESTINATION lib ARCHIVE DESTINATION lib RUNTIME DESTINATION bin PUBLIC_HEADER DESTINATION include/velocity ) install(EXPORT velocityTargets FILE velocityTargets.cmake NAMESPACE velocity:: DESTINATION lib/cmake/velocity ) # Create config file include(CMakePackageConfigHelpers) write_basic_package_version_file( velocityConfigVersion.cmake VERSION ${PACKAGE_VERSION} COMPATIBILITY AnyNewerVersion ) install(FILES "${CMAKE_CURRENT_BINARY_DIR}/velocityConfigVersion.cmake" DESTINATION lib/cmake/velocity ) ================================================================================ ================================================================================ FILE: examples/example.cpp Relevance Score: 0.960 | Chunks Retrieved: 2 | Tokens: 1,804 ================================================================================ #include #include using namespace vel; void demonstrateVec2() { std::cout << "=== Vec2 Demo ===" << std::endl; Vec2 a(3.0f, 4.0f); Vec2 b(1.0f, 2.0f); std::cout << "a = " << a.toString() << std::endl; std::cout << "b = " << b.toString() << std::endl; std::cout << "a + b = " << (a + b).toString() << std::endl; std::cout << "a - b = " << (a - b).toString() << std::endl; std::cout << "a * 2 = " << (a * 2.0f).toString() << std::endl; std::cout << "a.dot(b) = " << a.dot(b) << std::endl; std::cout << "a.cross(b) = " << a.cross(b) << std::endl; std::cout << "a.length() = " << a.length() << std::endl; std::cout << "a.normalized() = " << a.normalized().toString() << std::endl; std::cout << "a.distance(b) = " << a.distance(b) << std::endl; std::cout << "a.angle() = " << math::degrees(a.angle()) << " degrees" << std::endl; std::cout << std::endl; } void demonstrateVec3() { std::cout << "=== Vec3 Demo ===" << std::endl; Vec3 a(1.0f, 2.0f, 3.0f); Vec3 b(4.0f, 5.0f, 6.0f); std::cout << "a = " << a.toString() << std::endl; std::cout << "b = " << b.toString() << std::endl; std::cout << "a + b = " << (a + b).toString() << std::endl; std::cout << "a - b = " << (a - b).toString() << std::endl; std::cout << "a * 2 = " << (a * 2.0f).toString() << std::endl; std::cout << "a.dot(b) = " << a.dot(b) << std::endl; std::cout << "a.cross(b) = " << a.cross(b).toString() << std::endl; std::cout << "a.length() = " << a.length() << std::endl; std::cout << "a.normalized() = " << a.normalized().toString() << std::endl; std::cout << "a.distance(b) = " << a.distance(b) << std::endl; // Demonstrate static constants std::cout << "Vec3::up() = " << Vec3::up().toString() << std::endl; std::cout << "Vec3::forward() = " << Vec3::forward().toString() << std::endl; std::cout << std::endl; } void demonstrateMat4() { std::cout << "=== Mat4 Demo ===" << std::endl; // Identity matrix Mat4 identity = Mat4::identity(); std::cout << "Identity matrix:" << std::endl; std::cout << identity.toString(1) << std::endl; // Translation matrix Mat4 translation = Mat4::translation(Vec3(1.0f, 2.0f, 3.0f)); std::cout << "Translation matrix:" << std::endl; std::cout << translation.toString(1) << std::endl; // Scale matrix Mat4 scale = Mat4::scale(Vec3(2.0f, 3.0f, 4.0f)); std::cout << "Scale matrix:" << std::endl; std::cout << scale.toString(1) << std::endl; // Rotation matrix (45 degrees around Y axis) Mat4 rotation = Mat4::rotationY(math::radians(45.0f)); std::cout << "Rotation matrix (45° around Y):" << std::endl; std::cout << rotation.toString(3) << std::endl; // Combined transformation Mat4 transform = translation * rotation * scale; std::cout << "Combined transformation (T * R * S):" << std::endl; std::cout << transform.toString(3) << std::endl; // Transform a point Vec3 point(1.0f, 0.0f, 0.0f); Vec3 transformed = transform.transformPoint(point); std::cout << "Point " << point.toString() << " transformed to " << transformed.toString() << std::endl; std::cout << std::endl; } void demonstrateProjectionMatrices() { std::cout << "=== Projection Matrices ===" << std::endl; // Perspective projection Mat4 perspective = Mat4::perspective(math::radians(60.0f), 16.0f/9.0f, 0.1f, 100.0f); std::cout << "Perspective projection (60° FOV, 16:9 aspect):" << std::endl; std::cout << perspective.toString(3) << std::endl; // Orthographic projection Mat4 ortho = Mat4::ortho(-10.0f, 10.0f, -10.0f, 10.0f, 0.1f, 100.0f); std::cout << "Orthographic projection:" << std::endl; std::cout << ortho.toString(3) << std::endl; // Look-at matrix Mat4 lookAt = Mat4::lookAt(Vec3(0.0f, 0.0f, 5.0f), Vec3::zero(), Vec3::up()); std::cout << "Look-at matrix (eye at (0,0,5), looking at origin):" << std::endl; std::cout << lookAt.toString(3) << std::endl; std::cout << std::endl; } void demonstrateMathUtils() { std::cout << "=== Math Utils Demo ===" << std::endl; std::cout << "PI = " << PI << std::endl; std::cout << "45 degrees in radians = " << math::radians(45.0f) << std::endl; std::cout << "PI/4 radians in degrees = " << math::degrees(PI/4.0f) << std::endl; std::cout << "clamp(1.5, 0, 1) = " << math::clamp(1.5f, 0.0f, 1.0f) << std::endl; std::cout << "lerp(0, 10, 0.5) = " << math::lerp(0.0f, 10.0f, 0.5f) << std::endl; std::cout << "smoothstep(0, 1, 0.5) = " << math::smoothstep(0.0f, 1.0f, 0.5f) << std::endl; std::cout << "sign(-3.14) = " << math::sign(-3.14f) << std::endl; std::cout << "isPowerOfTwo(16) = " << (math::isPowerOfTwo(16) ? "true" : "false") << std::endl; std::cout << std::endl; } int main() { std::cout << "Velocity Math Library Demo" << std::endl; std::cout << "Version " << VERSION_MAJOR << "." << VERSION_MINOR << "." << VERSION_PATCH << std::endl; std::cout << "==================" << std::endl << std::endl; demonstrateVec2(); demonstrateVec3(); demonstrateMat4(); demonstrateProjectionMatrices(); demonstrateMathUtils(); return 0; } ================================================================================ ================================================================================ FILE: tests/test_main.cpp Relevance Score: 0.950 | Chunks Retrieved: 2 | Tokens: 2,645 ================================================================================ #include #include #include #include using namespace vel; void testVec2() { std::cout << "Testing Vec2..." << std::endl; // Constructor tests Vec2 v1; assert(v1.x == 0.0f && v1.y == 0.0f); Vec2 v2(3.0f, 4.0f); assert(v2.x == 3.0f && v2.y == 4.0f); Vec2 v3(5.0f); assert(v3.x == 5.0f && v3.y == 5.0f); // Arithmetic operations Vec2 sum = v2 + Vec2(1.0f, 2.0f); assert(sum.x == 4.0f && sum.y == 6.0f); Vec2 diff = v2 - Vec2(1.0f, 2.0f); assert(diff.x == 2.0f && diff.y == 2.0f); Vec2 scaled = v2 * 2.0f; assert(scaled.x == 6.0f && scaled.y == 8.0f); // Vector operations assert(std::abs(v2.length() - 5.0f) < EPSILON); assert(v2.lengthSquared() == 25.0f); Vec2 normalized = v2.normalized(); assert(std::abs(normalized.length() - 1.0f) < EPSILON); // Dot product assert(v2.dot(Vec2(1.0f, 0.0f)) == 3.0f); // Cross product (2D) assert(v2.cross(Vec2(1.0f, 0.0f)) == -4.0f); // Static constants assert(Vec2::zero() == Vec2(0.0f, 0.0f)); assert(Vec2::one() == Vec2(1.0f, 1.0f)); assert(Vec2::unitX() == Vec2(1.0f, 0.0f)); assert(Vec2::unitY() == Vec2(0.0f, 1.0f)); std::cout << "Vec2 tests passed!" << std::endl; } void testVec3() { std::cout << "Testing Vec3..." << std::endl; // Constructor tests Vec3 v1; assert(v1.x == 0.0f && v1.y == 0.0f && v1.z == 0.0f); Vec