DirectXMesh

# GitHub Copilot Instructions

These instructions define how GitHub Copilot should assist with this project. The goal is to ensure consistent, high-quality code generation aligned with our conventions, stack, and best practices.

## Context

- **Project Type**: Graphics Library / DirectX / Direct3D 11 / Direct3D 12 / Geometry Processing
- **Project Name**: DirectXMesh Geometry Processing Library
- **Language**: C++
- **Framework / Libraries**: STL / CMake / CTest
- **Architecture**: Modular / RAII / OOP

## Getting Started

- 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_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/DirectXMesh/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, MinGW, and GCC on Linux.
> 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). 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. Platforms tested include Windows (MSVC, clang-cl, MinGW), Windows on ARM64, Xbox, UWP, WSL (Linux with GCC), and macOS (Apple Clang). 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.
- **Code of Conduct**: The project adheres to the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). All contributors are expected to follow this code of conduct in all interactions related to the project.

## File Structure

```plaintext
.azuredevops/ # Azure DevOps pipeline configuration and policy files.
.github/      # GitHub Actions workflow files and linter configuration files.
.nuget/       # NuGet package configuration files.
build/        # Miscellaneous build files and scripts.
DirectXMesh/  # DirectXMesh implementation files.
Utilities/    # Utility headers such as a WaveFront .obj file loader and a FVF converter.
Meshconvert/  # CLI tool for importing WaveFront .obj files and converting to CMO, SDKMESH, or VBO formats.
skills/       # Published CoPilot skills for use by developers.
Tests/        # Tests are designed to be cloned from a separate repository at this location.
wiki/         # Local clone of the GitHub wiki documentation repository.
```

## Patterns

### Patterns to Follow

- 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.
- 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

All public API functions must use SAL annotations on every parameter. Use `_Use_decl_annotations_` at the top of each implementation that has SAL in the header declaration — never repeat the annotations in the `.cpp` or `.inl` file.

Common annotations:

| Annotation | Meaning |
| --- | --- |
| `_In_` | Input parameter |
| `_In_opt_` | Optional input pointer |
| `_In_z_` | Null-terminated input string |
| `_In_reads_(n)` | Input array with element count |
| `_In_reads_bytes_(n)` | Input buffer with byte count |
| `_In_reads_opt_(n)` | Optional input array with element count |
| `_Out_` | Output parameter |
| `_Out_opt_` | Optional output pointer |
| `_Out_writes_(n)` | Output array with element count |
| `_Out_writes_opt_(n)` | Optional output array with element count |
| `_Out_writes_bytes_(n)` | Output buffer with byte count |
| `_Inout_` | Bidirectional parameter |
| `_Inout_updates_all_(n)` | In-place update of entire array |

Example:

```cpp
// Header (DirectXMesh.h)
DIRECTX_MESH_API HRESULT __cdecl ComputeNormals(
    _In_reads_(nFaces * 3) const uint16_t* indices, _In_ size_t nFaces,
    _In_reads_(nVerts) const XMFLOAT3* positions, _In_ size_t nVerts,
    _In_ CNORM_FLAGS flags,
    _Out_writes_(nVerts) XMFLOAT3* normals) noexcept;

// Implementation (.cpp)
_Use_decl_annotations_
HRESULT DirectX::ComputeNormals(
    const uint16_t* indices,
    size_t nFaces,
    const XMFLOAT3* positions,
    size_t nVerts,
    CNORM_FLAGS flags,
    XMFLOAT3* normals) noexcept
{ ... }
```

#### Calling Convention and DLL Export

- All public functions use `__cdecl` explicitly for ABI stability.
- All public function declarations are prefixed with `DIRECTX_MESH_API`, which wraps `__declspec(dllexport)` / `__declspec(dllimport)` (or the MinGW `__attribute__` equivalent) when the `DIRECTX_MESH_EXPORT` or `DIRECTX_MESH_IMPORT` preprocessor symbols are defined. CMake sets these automatically when `BUILD_SHARED_LIBS=ON`.

#### `noexcept` Rules

- All query and utility functions that cannot fail (e.g., `IsValidVB`, `IsValidIB`) are marked `noexcept`.
- HRESULT-returning functions that do not use Standard C++ containers are `noexcept` — errors are communicated via return code, never via exceptions (e.g., `ComputeNormals`, `ReorderIB`, `FinalizeIB`, `FinalizeVB`, `CompactVB`, `OptimizeVertices`, `ComputeCullData`). Note that `noexcept` HRESULT functions may still allocate scratch memory internally using `new (std::nothrow)` and return `E_OUTOFMEMORY` on failure — `noexcept` only means they will not throw C++ exceptions.
- 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 `_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 = 0,
    // Default is to compute normals using weight-by-angle

    CNORM_WEIGHT_BY_AREA = 0x1,
    // Computes normals using weight-by-area

    CNORM_WEIGHT_EQUAL = 0x2,
    // Compute normals with equal weights

    CNORM_WIND_CW = 0x4,
    // Vertices are clock-wise (defaults to CCW)
};

DEFINE_ENUM_FLAG_OPERATORS(CNORM_FLAGS);
```

See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for more information on this pattern.

### Patterns to Avoid

- 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 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

| Element | Convention | Example |
| --- | --- | --- |
| Classes / structs | PascalCase | `Meshlet`, `MeshletTriangle` |
| Public functions | PascalCase + `__cdecl` | `ComputeInputLayout` |
| Private data members | `m_` prefix | `m_count` |
| Enum type names | UPPER_SNAKE_CASE | `CNORM_FLAGS` |
| Enum values | UPPER_SNAKE_CASE | `CNORM_DEFAULT` |
| Files | PascalCase | `DirectXMesh.h` |

## File Header Convention

Every source file (`.cpp`, `.h`, etc.) must begin with this block:

```cpp
//-------------------------------------------------------------------------------------
// {FileName}
//
// {One-line description}
//
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
//
// https://go.microsoft.com/fwlink/?LinkID=324981
//-------------------------------------------------------------------------------------
```

Section separators within files use:
- 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.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/)
- [VCPKG Documentation](https://learn.microsoft.com/vcpkg/)
- [Games for Windows and the DirectX SDK blog - June 2014](https://walbourn.github.io/directxmesh/)
- [Games for Windows and the DirectX SDK blog - April 2025](https://walbourn.github.io/github-project-updates-2025/)

## No speculation

When creating documentation:

### Document Only What Exists

- Only document features, patterns, and decisions that are explicitly present in the source code.
- Only include configurations and requirements that are clearly specified.
- Do not make assumptions about implementation details.

### Handle Missing Information

- Ask the user questions to gather missing information.
- Document gaps in current implementation or specifications.
- List open questions that need to be addressed.

### Source Material

- Always cite the specific source file and line numbers for documented features.
- Link directly to relevant source code when possible.
- Indicate when information comes from requirements vs. implementation.

### Verification Process

- Review each documented item against source code whenever related to the task.
- Remove any speculative content.
- Ensure all documentation is verifiable against the current state of the codebase.

## Cross-platform Support Notes

- 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 Windows Subsystem for Linux (WSL).
- macOS is not officially supported due to a lack of support for Direct3D, which is reflected in the fact that the *directx-headers* VCPKG port is not supported for macOS.
- Portability and conformance of the code is validated by building with Visual C++ (MSVC), clang/LLVM for Windows (clang-cl), MinGW, GCC for Linux, and Apple Clang for macOS.
- The project ships MSBuild projects for Visual Studio 2022 (`.sln` / `.vcxproj`) and Visual Studio 2026 (`.slnx` / `.vcxproj`). VS 2019 projects have been retired.
- CMake is the primary build system and can be used on all supported platforms.

### Platform and Compiler `#ifdef` Guards

Use these established guards — do not invent new ones:

| Guard | Purpose |
| --- | --- |
| `_WIN32` | Windows platform (desktop, UWP, Xbox) |
| `_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 |
| `_M_ARM64` / `_M_X64` / `_M_IX86` | Architecture-specific code paths for MSVC (`#ifdef`) |
| `_M_ARM64EC` | ARM64EC ABI (ARM64 code with x64 interop) for MSVC |
| `__aarch64__` / `__x86_64__` / `__i386__` | Additional architecture-specific symbols for MinGW/GNUC (`#if`) |
| `USING_DIRECTX_HEADERS` | External DirectX-Headers package in use |

> `_M_ARM`/ `__arm__` is legacy 32-bit ARM which is deprecated.

Non-Windows builds (Linux/WSL/macOS) 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 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

When reviewing code, focus on the following aspects:

- Adherence to coding standards defined in `.editorconfig` and on the [wiki](https://github.com/microsoft/DirectXMesh/wiki/Implementation).
- Make coding recommendations based on the *C++ Core Guidelines*.
- Proper use of RAII and smart pointers.
- Correct error handling practices and C++ Exception safety.
- Clarity and maintainability of the code.
- Adequate comments where necessary.
- Public interfaces located in `DirectXMesh.h` should be clearly defined and documented on the GitHub wiki.
- Compliance with the project's architecture and design patterns.
- Ensure that all public functions and classes are covered by unit tests located on [GitHub](https://github.com/walbourn/directxmeshtest.git) where applicable. Report any gaps in test coverage.
- Check for performance implications, especially in geometry processing algorithms.
- Provide brutally honest feedback on code quality, design, and potential improvements as needed.

## Documentation Review Instructions

When reviewing documentation, do the following:

- Read the code located in [this git repository](https://github.com/microsoft/DirectXMesh.git) in the main branch.
- Review the public interface defined in `DirectXMesh.h`, as well as the headers in the `Utilities` folder.
- Read the documentation on the wiki located in [this git repository](https://github.com/microsoft/DirectXMesh.wiki.git).
- Report any specific gaps in the documentation compared to the public interface.

## Code Change Rules

- Make precise, surgical changes that **fully** address the request. Don't modify unrelated code, but ensure changes are complete and correct.
- Don't fix pre-existing issues unrelated to your task. However, if you discover bugs directly caused by or tightly coupled to the code you're changing, fix those too.
- Update documentation if it is directly related to the changes you are making.
- Always validate that your changes don't break existing behavior.

### Linting, Building, Testing

- Only run linters, builds and tests that already exist. Do not add new linting, building or testing tools unless necessary for the task.
- Use the smallest targeted test, build, or lint command that covers the changed behavior. When related targeted selectors use the same runner, include them in one invocation; escalate to full-suite or baseline runs only when targeted validation shows they are needed.
- Documentation changes do not need to be linted, built or tested unless there are specific tests for documentation.

### Using Ecosystem Tools

- Prefer ecosystem tools (package managers, scaffolding, refactoring tools, linters) over manual changes.
- Install packages only when changing dependencies or after a missing-dependency failure.

### Code Commenting Style

- Only comment code that needs a bit of clarification. Do not comment otherwise.

## Release Process

The release process is documented in the [release skill](.github/skills/release/SKILL.md). Invoke the `release` skill for step-by-step guidance when performing a release.

The release workflow includes:
- Preparing release branch with version updates in `CMakeLists.txt`, `README.md`, and `.nuspec` files
- Tagging releases with verified GPG signatures
- Creating GitHub releases with release notes from `CHANGELOG.md`
- Publishing to MSCodeHub mirror, Azure DevOps signed binaries, and NuGet packages
- Source archive signing with minisign
- NuGet package validation and publishing to nuget.org

## CoPilot Skills

The project includes published CoPilot skills for developers:

- **Release-Process**: Guide for performing the DirectXMesh release process. Invoked when asked to help with releasing a new version, publishing packages, or updating ports. See [Release Process skill](.github/skills/release/SKILL.md) for details.
- **directxmesh-usage**: Provides usage guidance for the DirectXMesh library. Located in the `skills/directxmesh-usage/` directory.
- **mesh-converter**: Provides guidance for using the meshconvert command-line tool. Located in the `skills/mesh-converter/` directory.

To use these skills in the Copilot CLI:

```bash
/skills list
/skills search directxmesh
```