Added nVerts parameter to OptimizeFaces (#289)

Author: walbourn

.github/copilot-instructions.md

@@ -14,16 +14,16 @@ These instructions define how GitHub Copilot should assist with this project. Th
 
 - See the tutorial at [Getting Started](https://github.com/microsoft/DirectXMesh/wiki/Getting-Started).
 - The recommended way to integrate *DirectXMesh* into your project is by using the *vcpkg* Package Manager.
-- You can make use of the nuget.org packages **directxmesh_desktop_2019**, **directxmesh_desktop_win10**, or **directxmesh_uwp**.
+- You can make use of the nuget.org packages **directxmesh_desktop_win10** or **directxmesh_uwp**.
 - You can also use the library source code directly in your project or as a git submodule.
 
 ## General Guidelines
 
-- **Code Style**: The project uses an .editorconfig file to enforce coding standards. Follow the rules defined in `.editorconfig` for indentation, line endings, and other formatting. Additional information can be found on the wiki at [Implementation](https://github.com/microsoft/DirectXTK/wiki/Implementation). The library implementation is written to be compatible with C++14 features, but C++17 is required to build the project for the command-line tools which utilize C++17 filesystem for long file path support.
-> Notable `.editorconfig` rules: C/C++ files use 4-space indentation, `crlf` line endings, and `latin1` charset — avoid non-ASCII characters in source files. HLSL files have separate indent/spacing rules defined in `.editorconfig`.
+- **Code Style**: The project uses an .editorconfig file to enforce coding standards. Follow the rules defined in `.editorconfig` for indentation, line endings, and other formatting. Additional information can be found on the wiki at [Implementation](https://github.com/microsoft/DirectXTK/wiki/Implementation). The library's public API requires C++11, and the project builds with C++17 (`CMAKE_CXX_STANDARD 17`). The command-line tools also use C++17, including `<filesystem>` for long file path support. This code is designed to build with Visual Studio 2022, Visual Studio 2026, clang for Windows v12 or later, or MinGW 12.2.
+> Notable `.editorconfig` rules: C/C++ files use 4-space indentation, `crlf` line endings, and `latin1` charset — avoid non-ASCII characters in source files.
 - **Documentation**: The project provides documentation in the form of wiki pages available at [Documentation](https://github.com/microsoft/DirectXMesh/wiki/).
 - **Error Handling**: Use C++ exceptions for error handling and uses RAII smart pointers to ensure resources are properly managed. For some functions that return HRESULT error codes, they are marked `noexcept`, use `std::nothrow` for memory allocation, and should not throw exceptions.
-- **Testing**: Unit tests for this project are implemented in this repository [Test Suite](https://github.com/walbourn/directxmeshtest/) and can be run using CTest per the instructions at [Test Documentation](https://github.com/walbourn/directxmeshtest/wiki).
+- **Testing**: Unit tests for this project are implemented in this repository [Test Suite](https://github.com/walbourn/directxmeshtest/) and can be run using CTest per the instructions at [Test Documentation](https://github.com/walbourn/directxmeshtest/wiki). See [test copilot instructions](https://github.com/walbourn/directxmeshtest/blob/main/.github/copilot-instructions.md) for additional information on the tests.
 - **Security**: This project uses secure coding practices from the Microsoft Secure Coding Guidelines, and is subject to the `SECURITY.md` file in the root of the repository. Functions that read input from geometry files are subject to OneFuzz fuzz testing to ensure they are secure against malformed files.
 - **Dependencies**: The project uses CMake and VCPKG for managing dependencies, making optional use of DirectXMath and DirectX-Headers. The project can be built without these dependencies, relying on the Windows SDK for core functionality.
 - **Continuous Integration**: This project implements GitHub Actions for continuous integration, ensuring that all code changes are tested and validated before merging. This includes building the project for a number of configurations and toolsets, running a subset of unit tests, and static code analysis including GitHub super-linter, CodeQL, and MSVC Code Analysis.
@@ -49,14 +49,14 @@ wiki/         # Local clone of the GitHub wiki documentation repository.
 
 - Use RAII for all resource ownership (memory, file handles, etc.).
 - Many classes utilize the pImpl idiom to hide implementation details, and to enable optimized memory alignment in the implementation.
-- Use `std::unique_ptr` for exclusive ownership and `std::shared_ptr` for shared ownership.
-- Use `Microsoft::WRL::ComPtr` for COM object management.
+- Use `std::unique_ptr` for exclusive ownership.
 - Make use of anonymous namespaces to limit scope of functions and variables.
 - Make use of `assert` for debugging checks, but be sure to validate input parameters in release builds.
 - Explicitly `= delete` copy constructors and copy-assignment operators on all classes that use the pImpl idiom.
 - Explicitly utilize `= default` or `=delete` for copy constructors, assignment operators, move constructors and move-assignment operators where appropriate.
 - Use 16-byte alignment (`_aligned_malloc` / `_aligned_free`) to support SIMD operations in the implementation, but do not expose this requirement in public APIs.
 > For non-Windows support, the implementation uses C++17 `aligned_alloc` instead of `_aligned_malloc`.
+- All implementation `.cpp` files include `DirectXMeshP.h` as their first include (precompiled header). MinGW builds skip precompiled headers.
 
 #### SAL Annotations
 
@@ -110,17 +110,18 @@ HRESULT DirectX::ComputeNormals(
 #### `noexcept` Rules
 
 - All query and utility functions that cannot fail (e.g., `IsValidVB`, `IsValidIB`) are marked `noexcept`.
-- All HRESULT-returning I/O and processing functions are also `noexcept` — errors are communicated via return code, never via exceptions.
+- HRESULT-returning functions that do not perform heap allocation or use Standard C++ containers are `noexcept` — errors are communicated via return code, never via exceptions (e.g., `ComputeNormals`, `ReorderIB`, `FinalizeIB`, `FinalizeVB`, `CompactVB`, `OptimizeVertices`, `ComputeCullData`).
+- HRESULT-returning functions that use `std::vector`, `std::function`, or other potentially throwing types are *not* marked `noexcept` — they may throw on allocation failure (e.g., `GenerateAdjacencyAndPointReps`, `Validate`, `Clean`, `WeldVertices`, `ComputeMeshlets`, `OptimizeFaces`).
 - Constructors and functions that perform heap allocation or utilize Standard C++ containers that may throw are marked `noexcept(false)`.
 
 #### Enum Flags Pattern
 
-Flags enums follow this pattern — a `uint32_t`-based unscoped enum with a `_NONE = 0x0` base case, followed by a call to `DEFINE_ENUM_FLAG_OPERATORS` (defined in `DirectXMesh.inl`) to enable `|`, `&`, and `~` operators:
+Flags enums follow this pattern — a `uint32_t`-based unscoped enum with a `_DEFAULT = 0` base case, followed by a call to `DEFINE_ENUM_FLAG_OPERATORS` (invoked in `DirectXMesh.inl`) to enable `|`, `&`, and `~` operators:
 
 ```cpp
 enum CNORM_FLAGS : uint32_t
 {
-    CNORM_DEFAULT = 0x0,
+    CNORM_DEFAULT = 0,
     // Default is to compute normals using weight-by-angle
 
     CNORM_WEIGHT_BY_AREA = 0x1,
@@ -142,7 +143,7 @@ See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for m
 
 - Don’t use raw pointers for ownership.
 - Avoid macros for constants—prefer `constexpr` or `inline` `const`.
-- Don’t put implementation logic in header files unless using templates, although the SimpleMath library does use an .inl file for performance.
+- Don't put implementation logic in header files unless using templates, although the DirectXMesh library does use an .inl file for performance for a few specific utility functions that are called in tight loops (e.g., `IsValidIB`, `IsValidVB`).
 - Avoid using `using namespace` in header files to prevent polluting the global namespace.
 
 ## Naming Conventions
@@ -174,16 +175,16 @@ Every source file (`.cpp`, `.h`, etc.) must begin with this block:
 ```
 
 Section separators within files use:
-- Major sections: `//-------------------------------------------------------------------------------------`
-- Subsections:   `//---------------------------------------------------------------------------------`
+- Major sections: `//=====================================================================================`
+- Subsections:   `//-------------------------------------------------------------------------------------`
 
 The project does **not** use Doxygen. API documentation is maintained exclusively on the GitHub wiki.
 
 ## References
 
 - [Source git repository on GitHub](https://github.com/microsoft/DirectXMesh.git)
 - [DirectXMesh documentation git repository on GitHub](https://github.com/microsoft/DirectXMesh.wiki.git)
-- [DirectXMesh test suite git repository on GitHub](https://github.com/walbourn/directxmeshtest.wiki.git).
+- [DirectXMesh test suite git repository on GitHub](https://github.com/walbourn/directxmeshtest.git).
 - [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)
 - [Microsoft Secure Coding Guidelines](https://learn.microsoft.com/en-us/security/develop/secure-coding-guidelines)
 - [CMake Documentation](https://cmake.org/documentation/)
@@ -221,8 +222,9 @@ When creating documentation:
 
 ## Cross-platform Support Notes
 
-- The code supports building for Windows and Linux.
+- The code targets Win32 desktop applications for Windows 8.1 or later, Xbox One, Xbox Series X\|S, Universal Windows Platform (UWP) apps for Windows 10 and Windows 11, and Linux.
 - Portability and conformance of the code is validated by building with Visual C++, clang/LLVM for Windows, MinGW, and GCC for Linux compilers.
+- The project ships MSBuild projects for Visual Studio 2022 (`.sln` / `.vcxproj`) and Visual Studio 2026 (`.slnx` / `.vcxproj`). VS 2019 projects have been retired.
 
 ### Platform and Compiler `#ifdef` Guards
 
@@ -231,10 +233,12 @@ Use these established guards — do not invent new ones:
 | Guard | Purpose |
 | --- | --- |
 | `_WIN32` | Windows platform (desktop, UWP, Xbox) |
-| `_GAMING_XBOX` | Xbox One or Xbox Series X\|S |
-| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S |
+| `_GAMING_XBOX` | Xbox platform (GDK - covers both Xbox One and Xbox Series X\|S) |
+| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S (GDK with Xbox Extensions) |
+| `_GAMING_XBOX_XBOXONE` | Xbox One (GDK with Xbox Extensions) |
 | `_XBOX_ONE && _TITLE` | Legacy Xbox One XDK — **no longer supported**; triggers a `#error` at compile time |
 | `_MSC_VER` | MSVC-specific (and MSVC-like clang-cl) pragmas and warning suppression |
+| `__INTEL_COMPILER` | Intel C++ Compiler classic warning suppression |
 | `__clang__` | Clang/LLVM diagnostic suppressions |
 | `__MINGW32__` | MinGW compatibility headers |
 | `__GNUC__` | MinGW/GCC DLL attribute equivalents |
@@ -245,17 +249,18 @@ Use these established guards — do not invent new ones:
 
 > `_M_ARM`/ `__arm__` is legacy 32-bit ARM which is deprecated.
 
-Non-Windows builds (Linux/WSL) omit WIC entirely and use `<directx/dxgiformat.h>` and `<wsl/winadapter.h>` from the DirectX-Headers package instead of the Windows SDK.
+Non-Windows builds (Linux/WSL) use `<directx/dxgiformat.h>` and `<wsl/winadapter.h>` from the DirectX-Headers package instead of the Windows SDK.
 
 ### Error Codes
 
-The following symbols are not custom error codes, but aliases for `HRESULT_FROM_WIN32` error values.
+The following symbols are not custom error codes, but aliases for `HRESULT_FROM_WIN32` error codes.
 
 | Symbol | Standard Win32 HRESULT |
 | -------- | ------------- |
 | `HRESULT_E_ARITHMETIC_OVERFLOW` | `HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)` |
 | `HRESULT_E_NOT_SUPPORTED` | `HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)` |
 | `HRESULT_E_INVALID_NAME` | `HRESULT_FROM_WIN32(ERROR_INVALID_NAME)` |
+| `E_BOUNDS` | `0x8000000BL` (conditionally defined if not already present) |
 
 ## Code Review Instructions
 

.github/workflows/arm64.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -45,7 +47,7 @@ jobs:
         build_type: [arm64-Debug, arm64-Release, arm64-Debug-UWP, arm64-Release-UWP]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: 'Install Ninja'
         run: choco install ninja

.github/workflows/arm64bvt.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -46,10 +48,10 @@ jobs:
         build_type: [arm64-Release]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Clone test repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: walbourn/directxmeshtest
           path: Tests

.github/workflows/bvt.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -48,10 +50,10 @@ jobs:
         arch: [amd64]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Clone test repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: walbourn/directxmeshtest
           path: Tests

.github/workflows/clangcl.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props

.github/workflows/codeql.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -49,15 +51,15 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: 'Install Ninja'
         run: choco install ninja
 
       - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
+        uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
         with:
           languages: c-cpp
           build-mode: manual
@@ -71,6 +73,6 @@ jobs:
         run: cmake --build out\build\x64-Debug
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
+        uses: github/codeql-action/analyze@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
         with:
           category: "/language:c-cpp"

.github/workflows/main.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props

.github/workflows/msbuild.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*
   pull_request:
@@ -20,6 +21,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*
 

.github/workflows/msvc.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -47,7 +49,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Configure CMake
         working-directory: ${{ github.workspace }}
@@ -63,6 +65,6 @@ jobs:
 
       # Upload SARIF file to GitHub Code Scanning Alerts
       - name: Upload SARIF to GitHub
-        uses: github/codeql-action/upload-sarif@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
+        uses: github/codeql-action/upload-sarif@c10b8064de6f491fea524254123dbe5e09572f13 # v3.29.5
         with:
           sarif_file: ${{ steps.run-analysis.outputs.sarif }}

.github/workflows/test.yml

@@ -12,6 +12,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props
@@ -24,6 +25,7 @@ on:
       - '*.md'
       - LICENSE
       - '.azuredevops/**'
+      - '.github/*.md'
       - '.nuget/*'
       - build/*.cmd
       - build/*.props