You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+145-1Lines changed: 145 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,8 @@ These instructions define how GitHub Copilot should assist with this project. Th
19
19
20
20
## General Guidelines
21
21
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`.
23
24
-**Documentation**: The project provides documentation in the form of wiki pages available at [Documentation](https://github.com/microsoft/DirectXTK/wiki/).
24
25
-**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.
25
26
-**Testing**: Unit tests for this project are implemented in this repository [Test Suite](https://github.com/walbourn/directxtktest/) and can be run using CTest per the instructions at [Test Documentation](https://github.com/walbourn/directxtktest/wiki).
MakeSpriteFont/ # CLI tool for capturing sprite fonts.
43
44
XWBTool/ # CLI tool for creating XACT-style wave banks.
44
45
Tests/ # Tests are designed to be cloned from a separate repository at this location.
46
+
wiki/ # Local clone of the GitHub wiki documentation repository.
45
47
```
46
48
47
49
## Patterns
@@ -55,6 +57,83 @@ Tests/ # Tests are designed to be cloned from a separate repository at
55
57
- Make use of anonymous namespaces to limit scope of functions and variables.
56
58
- Make use of `assert` for debugging checks, but be sure to validate input parameters in release builds.
57
59
- Make use of the `DebugTrace` helper to log diagnostic messages, particularly at the point of throwing an exception.
60
+
- Explicitly `= delete` copy constructors and copy-assignment operators on all classes that use the pImpl idiom.
61
+
- Explicitly utilize `= default` or `=delete` for copy constructors, assignment operators, move constructors and move-assignment operators where appropriate.
62
+
- Use 16-byte alignment (`_aligned_malloc` / `_aligned_free`) to support SIMD operations in the implementation, but do not expose this requirement in public APIs.
63
+
- All implementation `.cpp` files include `pch.h` as their first include (precompiled header). MinGW builds skip precompiled headers.
64
+
-`Model` and related classes require RTTI (`/GR` on MSVC, `__GXX_RTTI` on GCC/Clang). The CMake build enables `/GR` automatically; do not disable RTTI when using `Model`.
65
+
66
+
#### SAL Annotations
67
+
68
+
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.
69
+
70
+
Common annotations:
71
+
72
+
| Annotation | Meaning |
73
+
| --- | --- |
74
+
|`_In_`| Input parameter |
75
+
|`_Out_`| Output parameter |
76
+
|`_Inout_`| Bidirectional parameter |
77
+
|`_In_reads_bytes_(n)`| Input buffer with byte count |
78
+
|`_In_reads_(n)`| Input array with element count |
79
+
|`_In_z_`| Null-terminated input string |
80
+
|`_In_opt_`| Optional input parameter (may be null) |
81
+
|`_Out_opt_`| Optional output parameter |
82
+
|`_COM_Outptr_`| Output COM interface |
83
+
84
+
Example:
85
+
86
+
```cpp
87
+
// Header (BufferHelpers.h)
88
+
DIRECTX_TOOLKIT_API
89
+
HRESULT __cdecl CreateStaticBuffer(
90
+
_In_ ID3D11Device* device,
91
+
_In_reads_bytes_(count* stride) const void* ptr,
92
+
size_t count,
93
+
size_t stride,
94
+
unsigned int bindFlags,
95
+
_COM_Outptr_ ID3D11Buffer** pBuffer) noexcept;
96
+
97
+
// Implementation (.cpp)
98
+
_Use_decl_annotations_
99
+
HRESULT DirectX::CreateStaticBuffer(
100
+
ID3D11Device* device,
101
+
const void* ptr,
102
+
size_t count,
103
+
size_t stride,
104
+
unsigned int bindFlags,
105
+
ID3D11Buffer** pBuffer) noexcept
106
+
{ ... }
107
+
```
108
+
109
+
#### Calling Convention and DLL Export
110
+
111
+
- All public functions use `__cdecl` explicitly for ABI stability.
112
+
- All public function declarations are prefixed with `DIRECTX_TOOLKIT_API`, which wraps `__declspec(dllexport)` / `__declspec(dllimport)` or the GCC `__attribute__` equivalent when using `BUILD_SHARED_LIBS` in CMake.
113
+
114
+
#### `noexcept` Rules
115
+
116
+
- All query and utility functions that cannot fail are marked `noexcept`.
117
+
- All HRESULT-returning I/O and processing functions are also `noexcept` — errors are communicated via return code, never via exceptions.
118
+
- Constructors and functions that perform heap allocation or utilize Standard C++ containers that may throw are marked `noexcept(false)`.
119
+
120
+
#### Enum Flags Pattern
121
+
122
+
Flags enums follow this pattern — a `uint32_t`-based unscoped enum with a `_DEFAULT = 0x0` base case, followed by a call to `DEFINE_ENUM_FLAG_OPERATORS` to enable `|`, `&`, and `~` operators:
123
+
124
+
```cpp
125
+
enum DDS_LOADER_FLAGS : uint32_t
126
+
{
127
+
DDS_LOADER_DEFAULT = 0,
128
+
DDS_LOADER_FORCE_SRGB = 0x1,
129
+
DDS_LOADER_IGNORE_SRGB = 0x2,
130
+
DDS_LOADER_IGNORE_MIPS = 0x20,
131
+
};
132
+
133
+
DEFINE_ENUM_FLAG_OPERATORS(DDS_LOADER_FLAGS);
134
+
```
135
+
136
+
See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for more information on this pattern.
58
137
59
138
### Patterns to Avoid
60
139
@@ -63,6 +142,47 @@ Tests/ # Tests are designed to be cloned from a separate repository at
63
142
- Don’t put implementation logic in header files unless using templates, although the SimpleMath library does use an .inl file for performance.
64
143
- Avoid using `using namespace` in header files to prevent polluting the global namespace.
0 commit comments