Skip to content

Commit 069e811

Browse files
walbournwalbourn
authored
Update CoPilot instructions (#275)
1 parent b459b53 commit 069e811

File tree

1 file changed

+147
-2
lines changed

1 file changed

+147
-2
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 147 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ These instructions define how GitHub Copilot should assist with this project. Th
1919

2020
## General Guidelines
2121

22-
- **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 code requires C++11/C++14 features.
22+
- **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.
23+
> 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`.
2324
- **Documentation**: The project provides documentation in the form of wiki pages available at [Documentation](https://github.com/microsoft/DirectXMesh/wiki/).
2425
- **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.
2526
- **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).
@@ -39,6 +40,7 @@ DirectXMesh/ # DirectXMesh implementation files.
3940
Utilities/ # Utility headers such as a WaveFront .obj file loader and a FVF converter.
4041
Meshconvert/ # CLI tool for importing WaveFront .obj files and converting to CMO, SDKMESH, or VBO formats.
4142
Tests/ # Tests are designed to be cloned from a separate repository at this location.
43+
wiki/ # Local clone of the GitHub wiki documentation repository.
4244
```
4345

4446
## Patterns
@@ -51,6 +53,90 @@ Tests/ # Tests are designed to be cloned from a separate repository at th
5153
- Use `Microsoft::WRL::ComPtr` for COM object management.
5254
- Make use of anonymous namespaces to limit scope of functions and variables.
5355
- Make use of `assert` for debugging checks, but be sure to validate input parameters in release builds.
56+
- Explicitly `= delete` copy constructors and copy-assignment operators on all classes that use the pImpl idiom.
57+
- Explicitly utilize `= default` or `=delete` for copy constructors, assignment operators, move constructors and move-assignment operators where appropriate.
58+
- Use 16-byte alignment (`_aligned_malloc` / `_aligned_free`) to support SIMD operations in the implementation, but do not expose this requirement in public APIs.
59+
> For non-Windows support, the implementation uses C++17 `aligned_alloc` instead of `_aligned_malloc`.
60+
61+
#### SAL Annotations
62+
63+
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.
64+
65+
Common annotations:
66+
67+
| Annotation | Meaning |
68+
| --- | --- |
69+
| `_In_` | Input parameter |
70+
| `_In_opt_` | Optional input pointer |
71+
| `_In_z_` | Null-terminated input string |
72+
| `_In_reads_(n)` | Input array with element count |
73+
| `_In_reads_bytes_(n)` | Input buffer with byte count |
74+
| `_In_reads_opt_(n)` | Optional input array with element count |
75+
| `_Out_` | Output parameter |
76+
| `_Out_opt_` | Optional output pointer |
77+
| `_Out_writes_(n)` | Output array with element count |
78+
| `_Out_writes_opt_(n)` | Optional output array with element count |
79+
| `_Out_writes_bytes_(n)` | Output buffer with byte count |
80+
| `_Inout_` | Bidirectional parameter |
81+
| `_Inout_updates_all_(n)` | In-place update of entire array |
82+
83+
Example:
84+
85+
```cpp
86+
// Header (DirectXMesh.h)
87+
DIRECTX_MESH_API HRESULT __cdecl ComputeNormals(
88+
_In_reads_(nFaces * 3) const uint16_t* indices, _In_ size_t nFaces,
89+
_In_reads_(nVerts) const XMFLOAT3* positions, _In_ size_t nVerts,
90+
_In_ CNORM_FLAGS flags,
91+
_Out_writes_(nVerts) XMFLOAT3* normals) noexcept;
92+
93+
// Implementation (.cpp)
94+
_Use_decl_annotations_
95+
HRESULT DirectX::ComputeNormals(
96+
const uint16_t* indices,
97+
size_t nFaces,
98+
const XMFLOAT3* positions,
99+
size_t nVerts,
100+
CNORM_FLAGS flags,
101+
XMFLOAT3* normals) noexcept
102+
{ ... }
103+
```
104+
105+
#### Calling Convention and DLL Export
106+
107+
- All public functions use `__cdecl` explicitly for ABI stability.
108+
- 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`.
109+
110+
#### `noexcept` Rules
111+
112+
- All query and utility functions that cannot fail (e.g., `IsValidVB`, `IsValidIB`) are marked `noexcept`.
113+
- All HRESULT-returning I/O and processing functions are also `noexcept` — errors are communicated via return code, never via exceptions.
114+
- Constructors and functions that perform heap allocation or utilize Standard C++ containers that may throw are marked `noexcept(false)`.
115+
116+
#### Enum Flags Pattern
117+
118+
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:
119+
120+
```cpp
121+
enum CNORM_FLAGS : uint32_t
122+
{
123+
CNORM_DEFAULT = 0x0,
124+
// Default is to compute normals using weight-by-angle
125+
126+
CNORM_WEIGHT_BY_AREA = 0x1,
127+
// Computes normals using weight-by-area
128+
129+
CNORM_WEIGHT_EQUAL = 0x2,
130+
// Compute normals with equal weights
131+
132+
CNORM_WIND_CW = 0x4,
133+
// Vertices are clock-wise (defaults to CCW)
134+
};
135+
136+
DEFINE_ENUM_FLAG_OPERATORS(CNORM_FLAGS);
137+
```
138+
139+
See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for more information on this pattern.
54140

55141
### Patterns to Avoid
56142

@@ -59,6 +145,40 @@ Tests/ # Tests are designed to be cloned from a separate repository at th
59145
- Don’t put implementation logic in header files unless using templates, although the SimpleMath library does use an .inl file for performance.
60146
- Avoid using `using namespace` in header files to prevent polluting the global namespace.
61147

148+
## Naming Conventions
149+
150+
| Element | Convention | Example |
151+
| --- | --- | --- |
152+
| Classes / structs | PascalCase | `Meshlet`, `MeshletTriangle` |
153+
| Public functions | PascalCase + `__cdecl` | `ComputeInputLayout` |
154+
| Private data members | `m_` prefix | `m_count` |
155+
| Enum type names | UPPER_SNAKE_CASE | `CNORM_FLAGS` |
156+
| Enum values | UPPER_SNAKE_CASE | `CNORM_DEFAULT` |
157+
| Files | PascalCase | `DirectXMesh.h` |
158+
159+
## File Header Convention
160+
161+
Every source file (`.cpp`, `.h`, etc.) must begin with this block:
162+
163+
```cpp
164+
//-------------------------------------------------------------------------------------
165+
// {FileName}
166+
//
167+
// {One-line description}
168+
//
169+
// Copyright (c) Microsoft Corporation.
170+
// Licensed under the MIT License.
171+
//
172+
// http://go.microsoft.com/fwlink/?LinkID=324981
173+
//-------------------------------------------------------------------------------------
174+
```
175+
176+
Section separators within files use:
177+
- Major sections: `//-------------------------------------------------------------------------------------`
178+
- Subsections: `//---------------------------------------------------------------------------------`
179+
180+
The project does **not** use Doxygen. API documentation is maintained exclusively on the GitHub wiki.
181+
62182
## References
63183

64184
- [Source git repository on GitHub](https://github.com/microsoft/DirectXMesh.git)
@@ -102,7 +222,32 @@ When creating documentation:
102222
## Cross-platform Support Notes
103223

104224
- The code supports building for Windows and Linux.
105-
- Portability and conformance of the code is validated by building with Visual C++, clang/LLVM for Windows, MinGW, and GCC for Linux.
225+
- Portability and conformance of the code is validated by building with Visual C++, clang/LLVM for Windows, MinGW, and GCC for Linux compilers.
226+
227+
### Platform and Compiler `#ifdef` Guards
228+
229+
Use these established guards — do not invent new ones:
230+
231+
| Guard | Purpose |
232+
| --- | --- |
233+
| `_WIN32` | Windows platform (desktop, UWP, Xbox) |
234+
| `_GAMING_XBOX` | Xbox One or Xbox Series X\|S |
235+
| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S |
236+
| `_XBOX_ONE && _TITLE` | Legacy Xbox One XDK — **no longer supported**; triggers a `#error` at compile time |
237+
| `_MSC_VER` | MSVC-specific (and MSVC-like clang-cl) pragmas and warning suppression |
238+
| `__clang__` | Clang/LLVM diagnostic suppressions |
239+
| `__MINGW32__` | MinGW compatibility headers |
240+
| `__GNUC__` | MinGW/GCC DLL attribute equivalents |
241+
| `_M_ARM64` / `_M_X64` / `_M_IX86` | Architecture-specific code paths for MSVC (`#ifdef`) |
242+
| `_M_ARM64EC` | ARM64EC ABI (ARM64 code with x64 interop) for MSVC |
243+
| `__aarch64__` / `__x86_64__` / `__i386__` | Additional architecture-specific symbols for MinGW/GNUC (`#if`) |
244+
| `USING_DIRECTX_HEADERS` | External DirectX-Headers package in use |
245+
246+
> `_M_ARM`/ `__arm__` is legacy 32-bit ARM which is deprecated.
247+
248+
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.
249+
250+
### Error Codes
106251

107252
The following symbols are not custom error codes, but aliases for `HRESULT_FROM_WIN32` error values.
108253

0 commit comments

Comments
 (0)