From 867c062ebad6fe6dff363fa499c758ffe7e5072a Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Fri, 13 Mar 2026 12:34:27 -0700 Subject: [PATCH 1/5] Update CoPilot instructions --- .github/copilot-instructions.md | 133 +++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8fd5e742..311122a8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -19,7 +19,8 @@ These instructions define how GitHub Copilot should assist with this project. Th ## 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 code requires C++11/C++14 features. +- **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`. - **Documentation**: The project provides documentation in the form of wiki pages available at [Documentation](https://github.com/microsoft/DirectXTex/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/directxtextest/) and can be run using CTest per the instructions at [Test Documentation](https://github.com/walbourn/directxtextest/wiki). @@ -60,6 +61,73 @@ Tests/ # Tests are designed to be cloned from a separate repository a - Use `Microsoft::WRL::ComPtr` for COM object management. - 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`. + +#### 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 | +| `_Out_` | Output parameter | +| `_Inout_` | Bidirectional parameter | +| `_In_reads_bytes_(n)` | Input buffer with byte count | +| `_In_reads_(n)` | Input array with element count | +| `_In_z_` | Null-terminated input string | +| `_Out_opt_` | Optional output parameter | + +Example: +```cpp +// Header (DirectXTex.h) +DIRECTX_TEX_API HRESULT __cdecl GetMetadataFromDDSMemory( + _In_reads_bytes_(size) const uint8_t* pSource, _In_ size_t size, + _In_ DDS_FLAGS flags, + _Out_ TexMetadata& metadata) noexcept; + +// Implementation (.cpp) +_Use_decl_annotations_ +HRESULT __cdecl GetMetadataFromDDSMemory( + const uint8_t* pSource, size_t size, + DDS_FLAGS flags, + TexMetadata& metadata) noexcept +{ ... } +``` + +#### Calling Convention and DLL Export + +- All public functions use `__cdecl` explicitly for ABI stability. +- All public function declarations are prefixed with `DIRECTX_TEX_API`, which wraps `__declspec(dllexport)` / `__declspec(dllimport)` or the GCC `__attribute__` equivalent when using `BUILD_SHARED_LIBS` in CMake. + +#### `noexcept` Rules + +- All query and utility functions that cannot fail (e.g., `IsCompressed`, `IsCubemap`, `ComputePitch`) are marked `noexcept`. +- All HRESULT-returning I/O and processing functions are also `noexcept` — errors are communicated via return code, never via exceptions. +- 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 `DirectXTex.inl`) to enable `|`, `&`, and `~` operators: + +```cpp +enum TEX_FILTER_FLAGS : uint32_t +{ + TEX_FILTER_DEFAULT = 0, + + TEX_FILTER_WRAP_U = 0x1, + // Enables wrapping addressing on U coordinate + ... +}; + +DEFINE_ENUM_FLAG_OPERATORS(TEX_FILTER_FLAGS); +``` + +See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for more information on this pattern. ### Patterns to Avoid @@ -68,6 +136,50 @@ Tests/ # Tests are designed to be cloned from a separate repository a - Don’t put implementation logic in header files unless using templates, although the SimpleMath library does use an .inl file for performance. - Avoid using `using namespace` in header files to prevent polluting the global namespace. +## Naming Conventions + +| Element | Convention | Example | +|---|---|---| +| Classes / structs | PascalCase | `ScratchImage`, `TexMetadata` | +| Public functions | PascalCase + `__cdecl` | `ComputePitch`, `IsCompressed` | +| Private data members | `m_` prefix | `m_nimages`, `m_metadata` | +| Enum type names | UPPER_SNAKE_CASE | `TEX_DIMENSION`, `CP_FLAGS` | +| Enum values | UPPER_SNAKE_CASE | `CP_FLAGS_NONE`, `TEX_ALPHA_MODE_PREMULTIPLIED` | +| Flag enum suffix | `_FLAGS` with `_NONE = 0x0` base | `DDS_FLAGS`, `WIC_FLAGS` | +| Files | PascalCase | `DirectXTex.h`, `BC6HEncode.hlsl` | + +## File Header Convention + +Every source file (`.cpp`, `.h`, `.hlsl`, etc.) must begin with this block: + +```cpp +//------------------------------------------------------------------------------------- +// {FileName} +// +// {One-line description} +// +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. +// +// http://go.microsoft.com/fwlink/?LinkId=248926 +//------------------------------------------------------------------------------------- +``` + +Section separators within files use: +- Major sections: `//-------------------------------------------------------------------------------------` +- Subsections: `//---------------------------------------------------------------------------------` + +The project does **not** use Doxygen. API documentation is maintained exclusively on the GitHub wiki. + +## HLSL Shader Compilation + +Shaders in `DirectXTex/Shaders/` are compiled with **FXC** (not DXC), producing embedded C++ header files (`.inc`) that are checked in alongside the source: + +- Each shader is compiled twice: `cs_5_0` (primary) and `cs_4_0` with `/DEMULATE_F16C` (legacy fallback). +- Standard compiler flags: `/nologo /WX /Ges /Zi /Zpc /Qstrip_reflect /Qstrip_debug` +- Use `CompileShaders.cmd` in `DirectXTex/Shaders/` to regenerate the `.inc` files. +- The CMake option `USE_PREBUILT_SHADERS` controls whether pre-compiled shaders are used. + ## References - [Source git repository on GitHub](https://github.com/microsoft/DirectXTex.git) @@ -113,6 +225,25 @@ When creating documentation: - The code supports building for Windows and Linux. - Portability and conformance of the code is validated by building with Visual C++, clang/LLVM for Windows, MinGW, and GCC for Linux. +### Platform and Compiler `#ifdef` Guards + +Use these established guards — do not invent new ones: + +| Guard | Purpose | +|---|---| +| `_WIN32` | Windows platform (desktop, UWP, Xbox) | +| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S (check before `_GAMING_XBOX`) | +| `_GAMING_XBOX` | Xbox One / Scarlett GDK fallback | +| `_XBOX_ONE && _TITLE` | Xbox One XDK (legacy) | +| `_MSC_VER` | MSVC-specific pragmas and warning suppression | +| `__clang__` | Clang/LLVM diagnostic suppressions | +| `__MINGW32__` | MinGW compatibility headers | +| `__GNUC__` | GCC DLL attribute equivalents | +| `_M_ARM64` / `_M_IX86` | Architecture-specific code paths | +| `USING_DIRECTX_HEADERS` | External DirectX-Headers package in use | + +Non-Windows builds (Linux/WSL) omit WIC entirely and use `` and `` from the DirectX-Headers package instead of the Windows SDK. + The following symbols are not custom error codes, but aliases for `HRESULT_FROM_WIN32` error codes. | Symbol | Standard Win32 HRESULT | From 78ac1a33c0cb639ec933deb1a8e792237fe57531 Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Fri, 13 Mar 2026 12:42:14 -0700 Subject: [PATCH 2/5] Pick markdown lint --- .github/copilot-instructions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 311122a8..ae48dd3f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -73,7 +73,7 @@ All public API functions must use SAL annotations on every parameter. Use `_Use_ Common annotations: | Annotation | Meaning | -|---|---| +| --- | --- | | `_In_` | Input parameter | | `_Out_` | Output parameter | | `_Inout_` | Bidirectional parameter | @@ -83,6 +83,7 @@ Common annotations: | `_Out_opt_` | Optional output parameter | Example: + ```cpp // Header (DirectXTex.h) DIRECTX_TEX_API HRESULT __cdecl GetMetadataFromDDSMemory( @@ -139,7 +140,7 @@ See [this blog post](https://walbourn.github.io/modern-c++-bitmask-types/) for m ## Naming Conventions | Element | Convention | Example | -|---|---|---| +| --- | --- | --- | | Classes / structs | PascalCase | `ScratchImage`, `TexMetadata` | | Public functions | PascalCase + `__cdecl` | `ComputePitch`, `IsCompressed` | | Private data members | `m_` prefix | `m_nimages`, `m_metadata` | @@ -230,7 +231,7 @@ When creating documentation: Use these established guards — do not invent new ones: | Guard | Purpose | -|---|---| +| --- | --- | | `_WIN32` | Windows platform (desktop, UWP, Xbox) | | `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S (check before `_GAMING_XBOX`) | | `_GAMING_XBOX` | Xbox One / Scarlett GDK fallback | From a51a5cadf90025e586c6ec9d2988bacea2e10688 Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Mon, 16 Mar 2026 12:26:42 -0700 Subject: [PATCH 3/5] Code review update --- .github/copilot-instructions.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ae48dd3f..88da6528 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -233,18 +233,21 @@ Use these established guards — do not invent new ones: | Guard | Purpose | | --- | --- | | `_WIN32` | Windows platform (desktop, UWP, Xbox) | -| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S (check before `_GAMING_XBOX`) | -| `_GAMING_XBOX` | Xbox One / Scarlett GDK fallback | +| `_GAMING_XBOX` | Xbox One or Xbox Series X\|S | +| `_GAMING_XBOX_SCARLETT` | Xbox Series X\|S | | `_XBOX_ONE && _TITLE` | Xbox One XDK (legacy) | -| `_MSC_VER` | MSVC-specific pragmas and warning suppression | +| `_MSC_VER` | MSVC-specific (and MSVC-like clang-cl) pragmas and warning suppression | | `__clang__` | Clang/LLVM diagnostic suppressions | | `__MINGW32__` | MinGW compatibility headers | -| `__GNUC__` | GCC DLL attribute equivalents | -| `_M_ARM64` / `_M_IX86` | Architecture-specific code paths | +| `__GNUC__` | MinGW/GCC DLL attribute equivalents | +| `_M_ARM64` / `_M_X64` / `_M_IX86` | Architecture-specific code paths for MSVC (`#ifdef`) | +| `__aarch64__` / `__x86_64__` / `__i386__` | Additional architecture-specific symbols for MinGW/GNUC (`#if`) | | `USING_DIRECTX_HEADERS` | External DirectX-Headers package in use | Non-Windows builds (Linux/WSL) omit WIC entirely and use `` and `` 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 | From f31754b7ca5a98c764ce32ff383dd6977829813d Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Mon, 16 Mar 2026 12:30:23 -0700 Subject: [PATCH 4/5] Pick lint --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 88da6528..c37f6e15 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -240,7 +240,7 @@ Use these established guards — do not invent new ones: | `__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_ARM64` / `_M_X64` / `_M_IX86` | Architecture-specific code paths for MSVC (`#ifdef`) | | `__aarch64__` / `__x86_64__` / `__i386__` | Additional architecture-specific symbols for MinGW/GNUC (`#if`) | | `USING_DIRECTX_HEADERS` | External DirectX-Headers package in use | From f40583d14130938bb5d36fc44054008c6337a6eb Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Mon, 16 Mar 2026 13:17:18 -0700 Subject: [PATCH 5/5] More content --- .github/copilot-instructions.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c37f6e15..9efbee23 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -47,6 +47,7 @@ DDSTextureLoader/ # Standalone version of the DDS texture loader for Direct3D 9/ ScreenGrab/ # Standalone version of the screenshot capture utility for Direct3D 9/11/12. WICTextureLoader/ # Standalone versoin of the WIC texture loader for Direct3D 9/11/12. Tests/ # Tests are designed to be cloned from a separate repository at this location. +wiki/ # Local clone of the GitHub wiki documentation repository. ``` > Note that DDSTextureLoader, ScreenGrab, and WICTextureLoader are standalone version of utilities which are also included in the *DirectX Tool Kit for DirectX 11* and *DirectX Tool Kit for DirectX 12*. @@ -103,7 +104,7 @@ HRESULT __cdecl GetMetadataFromDDSMemory( #### Calling Convention and DLL Export - All public functions use `__cdecl` explicitly for ABI stability. -- All public function declarations are prefixed with `DIRECTX_TEX_API`, which wraps `__declspec(dllexport)` / `__declspec(dllimport)` or the GCC `__attribute__` equivalent when using `BUILD_SHARED_LIBS` in CMake. +- All public function declarations are prefixed with `DIRECTX_TEX_API`, which wraps `__declspec(dllexport)` / `__declspec(dllimport)` (or the MinGW `__attribute__` equivalent) when the `DIRECTX_TEX_EXPORT` or `DIRECTX_TEX_IMPORT` preprocessor symbols are defined. CMake sets these automatically when `BUILD_SHARED_LIBS=ON`. #### `noexcept` Rules @@ -174,7 +175,7 @@ The project does **not** use Doxygen. API documentation is maintained exclusivel ## HLSL Shader Compilation -Shaders in `DirectXTex/Shaders/` are compiled with **FXC** (not DXC), producing embedded C++ header files (`.inc`) that are checked in alongside the source: +Shaders in `DirectXTex/Shaders/` are compiled with **FXC** (not DXC), producing embedded C++ header files (`.inc`): - Each shader is compiled twice: `cs_5_0` (primary) and `cs_4_0` with `/DEMULATE_F16C` (legacy fallback). - Standard compiler flags: `/nologo /WX /Ges /Zi /Zpc /Qstrip_reflect /Qstrip_debug` @@ -241,9 +242,12 @@ Use these established guards — do not invent new ones: | `__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) omit WIC entirely and use `` and `` from the DirectX-Headers package instead of the Windows SDK. ### Error Codes